如何编写符合惯用风格的http4s Scala函数式Web请求处理代码

核心原则：业务层只处理领域逻辑和领域错误，HTTP层负责将领域错误映射为HTTP响应，完全隔离两者的依赖。我们可以通过调整业务层返回类型、结合monadic错误处理来简化代码结构，让逻辑更清晰。

第一步：调整业务层的返回类型 #

让业务层方法返回F[Either[DomainError, T]]，彻底和HTTP框架解耦，避免自定义Success/Failure这类非标准类型：

// 纯领域错误类型，完全不依赖HTTP相关库
sealed trait DomainError
case class ValidationErrors(errors: List[String]) extends DomainError
case class ProcessingError(message: String) extends DomainError

trait BusinessLogic[F[_]] {
  type BusinessRequest
  type BusinessResponse

  // 把请求解析逻辑封装到业务层，路由层无需直接处理circe/http4s解析
  def parseRequest(req: Request[F]): F[Either[ValidationErrors, BusinessRequest]]
  // 验证请求，返回领域级错误
  def validateRequest(req: BusinessRequest): F[Either[ValidationErrors, BusinessRequest]]
  // 执行业务逻辑，返回领域级结果或错误
  def processRequest(req: BusinessRequest): F[Either[ProcessingError, BusinessResponse]]
}

第二步：重构路由层，用线性逻辑替代嵌套结构 #

利用EitherT串联所有步骤，把错误分支映射为HTTP响应，让代码逻辑和命令式流程完全对应：

import cats.data.EitherT
import cats.implicits._
import org.http4s._
import org.http4s.dsl.Http4sDsl

def businessRoutes[F[_]: Sync](BL: BusinessLogic[F]): HttpRoutes[F] = {
  val dsl = Http4sDsl[F]
  import dsl._

  HttpRoutes.of[F] {
    case req @ POST -> Root / "sms" =>
      val responseFlow = for {
        // 1. 解析请求，错误返回400
        parsedReq <- EitherT(BL.parseRequest(req)).leftMap(err => BadRequest(err.errors))
        // 2. 验证请求，错误返回400（如需业务级NotFound可改为404）
        validatedReq <- EitherT(BL.validateRequest(parsedReq)).leftMap(err => BadRequest(err.errors))
        // 3. 执行业务逻辑，错误返回500
        businessResp <- EitherT(BL.processRequest(validatedReq)).leftMap(err => InternalServerError(err.message))
      } yield Ok(businessResp)

      // 将EitherT转换为F[Response[F]]，自动处理所有错误分支
      responseFlow.valueOr(identity)
  }
}

关键优化点说明 #

• 线性逻辑流：用EitherT的for推导式让代码顺序和命令式步骤完全一致，没有嵌套的if/match，可读性大幅提升。
• 严格分层：业务层仅返回领域错误，HTTP层负责错误到响应的映射，彻底避免http4s/circe泄漏到业务逻辑。
• 单一职责：每个步骤只做一件事（解析→验证→处理），逻辑清晰易维护。
• 错误处理集中：所有HTTP响应的映射规则都在路由层，便于统一修改状态码或响应格式。

可选：拆分辅助函数简化代码 #

如果路由逻辑更复杂，可将错误映射逻辑拆为独立函数，进一步提升代码简洁度：

private def handleParseError[F[_]](err: ValidationErrors): F[Response[F]] = 
  BadRequest(err.errors)

private def handleValidationError[F[_]](err: ValidationErrors): F[Response[F]] = 
  BadRequest(err.errors)

private def handleProcessingError[F[_]](err: ProcessingError): F[Response[F]] = 
  InternalServerError(err.message)

// 重构后的路由
def businessRoutes[F[_]: Sync](BL: BusinessLogic[F]): HttpRoutes[F] = {
  val dsl = Http4sDsl[F]
  import dsl._

  HttpRoutes.of[F] {
    case req @ POST -> Root / "sms" =>
      val responseFlow = for {
        parsedReq <- EitherT(BL.parseRequest(req)).leftMapF(handleParseError)
        validatedReq <- EitherT(BL.validateRequest(parsedReq)).leftMapF(handleValidationError)
        businessResp <- EitherT(BL.processRequest(validatedReq)).leftMapF(handleProcessingError)
      } yield Ok(businessResp)

      responseFlow.valueOr(identity)
  }
}

内容的提问来源于stack exchange，提问作者WhiteleyJ