Scala中的API优先开发 | Zuplo博客

构建规范化API的两种方法

在开发API时，通常有两种主要方法来构建具有规范的API：

代码优先方法
API优先方法（方案优先）

规范的作用

API规范在以下场景中非常有用：

您的API有多个消费者。
需要生成多种语言的客户端。
需要生成API模型以进行测试。
需要为API消费者提供文档。
需要维护API的向后兼容性。

代码优先方法

在代码优先方法中，开发者直接开始编码。由于时间紧迫，规范（如果存在的话）通常是事后补充的。例如，在Spring框架中，可以通过在控制器中添加注解（如@ApiParam）来生成OpenAPI规范。

优点

可以立即开始编码。
能够生成多种工件，如服务器、客户端和文档。
这种方法非常流行，网上有许多相关示例和资源。

缺点

生成的规范可能不够稳定，存在一定风险。
需要维护更多代码，增加了认知负担和编译时间，尤其是在Scala中。
捆绑包的大小会增加，因为需要包含额外的依赖项。
有时需要与DSL（领域特定语言）斗争才能实现目标，例如多态有效载荷。
受限于DSL的功能，某些框架特定的特性可能难以实现。

从某种意义上说，代码优先方法类似于使用ORM，而API优先方法更像是直接使用SQL。

API优先方法

API优先方法从定义API规范开始，通常使用YAML或JSON格式的OpenAPI（Swagger）规范。然后根据规范生成服务器和客户端代码。

优点

开发者完全控制规范，规范是唯一的真实来源。
规范是稳定且版本化的。
前端和后端之间的协作更加高效：
- 可以快速更新规范。
- 前端开发者可以通过OpenAPI示例明确需求。
需要维护的代码更少，没有DSL或注解干扰代码。
可以充分利用框架的功能。

缺点

需要手动编写规范文件，可能包含大量样板代码。
规范文件可能会变得很大，但OpenAPI支持将其拆分为多个文件。

Scala中的API优先工具

在Scala中，有多种工具可以支持API优先方法。这些工具支持生成多个服务器框架，例如：

Akka
Finch
Lagom
Play
Cask
Scalatra

对于较小的项目，这些工具是一个不错的起点。然而，现有工具也存在一些问题，例如生成的代码可能对开发者和Git来说是隐藏的。此外，有些工具尚未支持Scala 3。

OpenApi4s工具的使用

生成模型和控制器

使用OpenApi4s工具，生成模型和控制器的过程非常简单：

解析OpenAPI规范。
生成模型。
生成控制器。

例如，OpenApi4s会为以下“用户”模型生成代码：

case class User(
  id: Option[Long],
  username: Option[String],
  firstName: Option[String],
  lastName: Option[String],
  email: Option[String],
  password: Option[String],
  phone: Option[String],
  userStatus: Option[Int]
) derives JsonRW

处理规范中的更改

添加属性

假设在User模型中添加了一个新属性age（类型为integer），OpenApi4s会将新生成的模型与现有代码进行比较，发现缺失的age:Int参数并将其添加。

修改属性

如果将userStatus的格式从int32更改为int64，OpenApi4s会将userStatus: Option[Int]更新为userStatus: Option[Long]。

添加新端点

向现有控制器添加新端点也很简单。例如，添加一个新端点时，OpenApi4s会生成以下代码：

case GET -> Root / "users" / "new-endpoint" => 
  Response.withStatus(Status.Ok)

开发者只需补充实现逻辑即可。

删除模型或端点

当从OpenAPI规范中删除模型或端点时，OpenApi4s不会自动删除代码。开发者需要手动完成删除操作。

CI管道中的检查

为了确保代码生成过程的可靠性，可以在持续集成（CI）管道中进行以下检查：

修改openapi.json文件，触发mill构建工具检测更改并运行OpenApi4s。
编译代码并重新生成文件。
检查Git差异（git diff）以确认更改。

总结

API优先方法在开发中提供了更高的灵活性和稳定性，尤其是在需要频繁协作和版本管理的场景中。通过工具如OpenApi4s，开发者可以更高效地生成和维护API代码，同时减少手动操作的复杂性。希望本文对您理解API优先开发方法及其在Scala中的应用有所帮助。

原文链接: https://zuplo.com/blog/2025/04/11/api-first-development-in-scala