如何更合理地组织Scala项目中的Tapir Endpoints？

我正在使用http4s和Tapir开发Scala Web应用，作为Tapir新手，我希望找到更优的项目组织方式。

目前我将端点描述与服务逻辑放在同一个类中，这类类采用类似Java Spring的Controller命名方式，示例如下：

class SomeController[F[_] : MonadThrow] {
  val something: ServerEndpoint[Any, F] =
    endpoint
      .description("Something")
      .post
      .in(query[String]("something"))
      .out(jsonBody[String])
      .errorOut(stringBody)
      .serverLogicSuccess {
        something => Monad[F].pure(something)
      }

  val allEndpoints: List[ServerEndpoint[Fs2Streams[F], F]] = List(resend)
}

随后我会在一个配置类中收集这些端点，生成OpenAPI文档与HTTP路由，配置示例如下：

object RoutesConfiguration {
  private val endpoints: List[ServerEndpoint[Fs2Streams[IO], IO]] = new SomeController[IO].allEndpoints

  private val openApi: List[ServerEndpoint[Any, IO]] =
    SwaggerInterpreter()
      .fromEndpoints(endpoints.map(_.endpoint), "Something", "1.0")

  val routes: HttpRoutes[IO] = Http4sServerInterpreter[IO]().toRoutes(List(openApi, endpoints).flatten)
}

请问是否应该将端点描述与服务逻辑分离？还有哪些更优的Tapir端点组织方式？

是否应该分离端点描述与服务逻辑？ #

完全应该。这种分离的核心价值在于：

• 端点契约可独立复用：不用依赖业务逻辑，就能单独生成OpenAPI文档、客户端代码，或用于接口测试
• 业务逻辑测试更纯粹：服务层可以脱离Tapir框架做单元测试，聚焦业务逻辑本身，无需处理API端点的细节
• 职责边界清晰：端点类只负责定义API的"契约规则"（路径、参数、响应格式、文档），服务类专注实现业务逻辑

更优的Tapir端点组织方式 #

1. 三层分离模式：契约层 + 服务层 + 绑定层 #

• 契约层：纯定义端点结构，不包含任何业务逻辑，按业务模块分组，比如UserEndpoints、OrderEndpoints：

object UserEndpoints {
  val getUser: Endpoint[UUID, Unit, User, Any] =
    endpoint
      .get
      .in("users" / path[UUID]("userId"))
      .out(jsonBody[User])
      .errorOut(statusCode(NotFound))
      .description("根据ID获取用户信息")
}

• 服务层：普通Scala类，完全独立于Tapir，只处理业务逻辑：

class UserService[F[_]: MonadThrow] {
  def getUser(userId: UUID): F[Either[NotFound.type, User]] = {
    // 实际业务逻辑，比如查询数据库、调用第三方服务
    if (userId == validUserId) Monad[F].pure(Right(User(userId, "Alice")))
    else Monad[F].pure(Left(NotFound))
  }
}

• 绑定层：仅负责把端点契约和服务逻辑绑定，生成可被http4s识别的ServerEndpoint：

class UserEndpointBinding[F[_]: MonadThrow](userService: UserService[F]) {
  val getUserServerEndpoint: ServerEndpoint[Any, F] =
    UserEndpoints.getUser.serverLogic(userId => userService.getUser(userId))

  val allEndpoints: List[ServerEndpoint[Any, F]] = List(getUserServerEndpoint)
}

2. 按业务模块聚合代码 #

将同一业务领域的契约、服务、绑定类放在同一个包下，比如com.example.app.user下包含UserEndpoints、UserService、UserEndpointBinding，模块内代码关联紧密，查找和维护更高效。

3. 可扩展的集中式端点注册 #

保留集中注册路由的逻辑，但改用依赖注入方式引入各个绑定类的端点，避免硬编码实例化：

object RoutesConfiguration {
  def buildRoutes[F[_]: MonadThrow](
    userBindings: UserEndpointBinding[F],
    orderBindings: OrderEndpointBinding[F]
  ): HttpRoutes[F] = {
    val allServerEndpoints = userBindings.allEndpoints ++ orderBindings.allEndpoints
    val openApiEndpoints = SwaggerInterpreter()
      .fromEndpoints(allServerEndpoints.map(_.endpoint), "My App", "1.0")
    Http4sServerInterpreter[F]().toRoutes(allServerEndpoints ++ openApiEndpoints)
  }
}

新增业务模块时，只需在注册方法中添加对应绑定类即可，扩展性更强。

4. 利用Tapir代码生成能力 #

若项目规模较大，可将契约层单独放在子模块中，通过Tapir的代码生成插件，自动生成客户端代码、OpenAPI YAML文件甚至前端API类型定义，让前后端共享同一API契约，减少不一致问题。

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