代碼優(yōu)先方法

在代碼生成OpenAPI規(guī)范。

優(yōu)點(diǎn)

• 可以立即開(kāi)始編碼。
• 能夠生成多種工件，如服務(wù)器、客戶端和文檔。
• 這種方法非常流行，網(wǎng)上有許多相關(guān)示例和資源。

缺點(diǎn)

• 生成的規(guī)范可能不夠穩(wěn)定，存在一定風(fēng)險(xiǎn)。
• 需要維護(hù)更多代碼，增加了認(rèn)知負(fù)擔(dān)和編譯時(shí)間，尤其是在Scala中。
• 捆綁包的大小會(huì)增加，因?yàn)樾枰~外的依賴(lài)項(xiàng)。
• 有時(shí)需要與DSL（領(lǐng)域特定語(yǔ)言）斗爭(zhēng)才能實(shí)現(xiàn)目標(biāo)，例如多態(tài)有效載荷。
• 受限于DSL的功能，某些框架特定的特性可能難以實(shí)現(xiàn)。

從某種意義上說(shuō)，API優(yōu)先方法更像是直接使用SQL。

API優(yōu)先方法

OpenAPI（Swagger）規(guī)范。然后根據(jù)規(guī)范生成服務(wù)器和客戶端代碼。

優(yōu)點(diǎn)

• 開(kāi)發(fā)者完全控制規(guī)范，規(guī)范是唯一的真實(shí)來(lái)源。
• 規(guī)范是穩(wěn)定且版本化的。
• 前端和后端之間的協(xié)作更加高效：
  • 可以快速更新規(guī)范。
  • 前端開(kāi)發(fā)者可以通過(guò)OpenAPI示例明確需求。
• 需要維護(hù)的代碼更少，沒(méi)有DSL或注解干擾代碼。
• 可以充分利用框架的功能。

缺點(diǎn)

• 需要手動(dòng)編寫(xiě)規(guī)范文件，可能包含大量樣板代碼。
• 規(guī)范文件可能會(huì)變得很大，但OpenAPI支持將其拆分為多個(gè)文件。

Scala中的API優(yōu)先工具

在Scala中，有多種工具可以支持API優(yōu)先方法。這些工具支持生成多個(gè)服務(wù)器框架，例如：

• Akka
• Finch
• Lagom
• Play
• Cask
• Scalatra

對(duì)于較小的項(xiàng)目，這些工具是一個(gè)不錯(cuò)的起點(diǎn)。然而，現(xiàn)有工具也存在一些問(wèn)題，例如生成的代碼可能對(duì)開(kāi)發(fā)者和Git來(lái)說(shuō)是隱藏的。此外，有些工具尚未支持Scala 3。

OpenApi4s工具的使用

生成模型和控制器

使用OpenApi4s工具，生成模型和控制器的過(guò)程非常簡(jiǎn)單：

1. 解析OpenAPI規(guī)范。
2. 生成模型。
3. 生成控制器。

例如，OpenApi4s會(huì)為以下“用戶”模型生成代碼：

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

處理規(guī)范中的更改

添加屬性

假設(shè)在User模型中添加了一個(gè)新屬性age（類(lèi)型為integer），OpenApi4s會(huì)將新生成的模型與現(xiàn)有代碼進(jìn)行比較，發(fā)現(xiàn)缺失的age:Int參數(shù)并將其添加。

修改屬性

如果將userStatus的格式從int32更改為int64，OpenApi4s會(huì)將userStatus: Option[Int]更新為userStatus: Option[Long]。

添加新端點(diǎn)

向現(xiàn)有控制器添加新端點(diǎn)也很簡(jiǎn)單。例如，添加一個(gè)新端點(diǎn)時(shí)，OpenApi4s會(huì)生成以下代碼：

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

開(kāi)發(fā)者只需補(bǔ)充實(shí)現(xiàn)邏輯即可。

刪除模型或端點(diǎn)

當(dāng)從OpenAPI規(guī)范中刪除模型或端點(diǎn)時(shí)，OpenApi4s不會(huì)自動(dòng)刪除代碼。開(kāi)發(fā)者需要手動(dòng)完成刪除操作。

CI管道中的檢查

為了確保代碼生成過(guò)程的可靠性，可以在持續(xù)集成（CI）管道中進(jìn)行以下檢查：

1. 修改openapi.json文件，觸發(fā)mill構(gòu)建工具檢測(cè)更改并運(yùn)行OpenApi4s。
2. 編譯代碼并重新生成文件。
3. 檢查Git差異（git diff）以確認(rèn)更改。

總結(jié)

API優(yōu)先方法在開(kāi)發(fā)中提供了更高的靈活性和穩(wěn)定性，尤其是在需要頻繁協(xié)作和版本管理的場(chǎng)景中。通過(guò)工具如OpenApi4s，開(kāi)發(fā)者可以更高效地生成和維護(hù)API代碼，同時(shí)減少手動(dòng)操作的復(fù)雜性。希望本文對(duì)您理解API優(yōu)先開(kāi)發(fā)方法及其在Scala中的應(yīng)用有所幫助。

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