API 設計就是創建一個有效的接口，使你可以更好地維護和實現 API，同時使消費者能夠輕松地使用這個 API。

一致的 API 設計意味著，在組織或團隊中對所有 API 及其公開的資源進行標準化設計。它是開發人員、架構師和技術作者共同遵守的藍圖，可以保證在 API 使用過程中品牌和體驗的一致性。風格指南旨在確保 API 設計和實現方式的一致性，組織就是用它來標準化設計。下面是比較流行的兩份風格指南：

1. 微軟 REST API 指南

2. 谷歌 API 設計指南在業余項目里，為了開發出一致的 API，并遵循 API 開發的行業最佳實踐，我經常參考這本風格手冊。

清晰的設計方法可以確保 API 與業務需求相一致。API 越標準，歧義就越少，合作成果就越多，質量就更有保障，API 的采用也會相應增加。

清晰一致的 API 設計標準是良好開發體驗和消費體驗的基礎。它們使開發人員和消費者都能夠快速有效地理解 API，縮短學習曲線，并按照一套指南進行構建。

API 標準化還可以改善團隊協作，提供提升準確性和降低延遲的指導原則，有助于降低總開發成本。標準對于 API 策略的成功如此重要，以至于許多科技公司（如微軟、谷歌和 IBM）以及行業組織（如 SWIFT、TMForum 和 IATA）都使用并支持 OpenAPI 規范（OAS），并將其作為定義 RESTful API 的基本標準。

如果不進行標準化，那么個體開發人員在設計過程中就可以隨意選擇。雖然我們鼓勵創造，但如果沒有適當的風格指南，很快就會變得混亂。

如果不進行標準化，那么組織就無法在 API 設計和交付過程中提供質量保證。強化設計標準有助于提升預測成功結果的能力，讓組織能夠在保證質量的前提下快速擴展 API 開發。

如果沒有一個正式的流程來強化標準化，就不可能成功地擴展 API 設計和開發過程，也不可能符合監管和行業標準。API 設計風格指南提供了內外部團隊在構建 API 定義和重用資產時開展協作所需的“護欄”。

最初，組織在內部以 PDF 或 Wiki 的形式發布 API 指南，供所有人參考，并制定相應的流程以確保團隊遵循設計指南。確保開發一致性的一種方案是在 API 開發期間進行人工評審。

API 以 OpenAPI 格式指定，并在版本控制系統中維護，API 定義可以遵循與其他代碼工件相同的評審過程。開發人員可以為 API 更改創建 pull 請求，并讓同事提供反饋。這個過程是手動的，是保障治理以及確保遵循 API 指南的有效方法，但與所有手動過程一樣，它容易受人為錯誤所影響，而且有時候不及時。

等待同事評審 API 更改可能會導致周期變慢，對開發人員的工作效率產生不利的影響，特別是涉及到評審過程中可以自動化的方面時。當組織規模擴大，更多的開發人員開始參與 API 開發時，這個過程也無法擴展。在這種情況下，可以提供 API 自動評審的左移法就很有用了。就像我們對其他工件所做的那樣，借助一些自動化工具或分析器盡早獲得反饋，這樣最好了。

術語“左移”指的是軟件開發中的一種實踐。在這種實踐中，團隊會比以往更早地開始測試，幫助自己聚焦質量，致力于問題預防而不是檢測。左移的目標是提高質量，縮短漫長的測試周期，并降低在開發周期結束時（或者更糟，在生產環境中）出現令人不快的意外情況的可能性。

說到 OpenAPI 分析器，我見過一些。它們將 API 風格指南轉換為一組規則，并根據 Open API 規范進行驗證。這些分析器允許你根據組織風格指南自定義規則。一個名為 Zally 的分析器引起了我的注意，它是一個用 Kotlin 編寫的工具，由 Zalando 開源。OpenAPI 風格指南驗證器的工作流程如下：

將 API 標準或風格指南表示成一組規則。這里有 Zalando 提供的一份指南；

根據 OpenAPI 編寫 API；

像 Zally、SonarQube、Spectra 這樣的檢測工具可以驗證開發人員編寫的 OpenAPI 規范是否符合第 1 步中定義的規范規則。

Zally 是一個簡單易用的 API 分析器。它的標準配置是根據 Zalando RESTful 指南中定義的規則檢查 API，對任何人來說都是開箱即用的。它具有可擴展性，允許我們添加自己的規則集。它還提供以下特性：

• 根據需要在服務器端啟用 / 禁用規則；

• 接受 JSON 和 YAML 格式的 Swagger V2 和 OpenAPI V3 規范；

• 可以編寫并插入自己的規則；

• 直觀的 Web UI 顯示了實現的規則和規范驗證的結果；

• 使用 Web 鉤子集成 GitHub，驗證每個 pull 請求中的 OpenAPI，并在評論中回顯違規情況。

雖然 Zally 的編寫方式更具可擴展性和可定制性，但我覺得，我們仍然可以進一步改進 Zally 當前的驗證工作流，縮短開發反饋循環。由于 Zally 缺少像 checkstyle、ktlint、spot bug 這樣的插件，所以我在使用 Zally 時遇到了以下幾個痛點：

• 為了使用 CLI 工具，開發人員需要在本地或遠程系統上托管 Zally 服務器；

• 開發人員需要切換運行 CLI 工具的上下文，或是額外做一些工作，將 CLI 配置為 Maven/Gradle 構建過程的一部分，前提是第一條已經滿足；

• 在每個 pull 請求中使用 GitHub 集成組件驗證 API 會增加反饋循環時間。所有這些都增加了向開發人員反饋的時間，并且還有托管 Zally 服務器的人工開銷。所以我決定編寫自己的 Gradle 插件，它既可以集成在本地開發環境中，也可以集成在 CI 工具中，幫助我驗證和提取不同格式的驗證結果。

zally-gradle-plugin 是一個用 kotlin 編寫的 Gradle 插件，可以集成到構建腳本中。該插件根據規則集驗證規范，并提供 JSON 和 HTML 格式的報告。

該項目包含一個示例任務配置：

// settings.gradle.kts
pluginManagement {
    repositories {
        gradlePluginPortal()
        mavenLocal()
    }
}


// build.gradke.kts
plugins {
    id("io.github.thiyagu06") version "1.0.2-dev"
}


zallyLint {
    inputSpec = File("${projectDir}/docs/petstore-spec.yml")
    reports {
        json {
            enabled = true
            destination = File("${rootDir}/zally/violation.json")
        }
        rules {
            must {
               max = 10
            }
        }
    }
}


//execute task
./gradlew clean zallyLint


```
```
Run ZallyLint task
./gradlew zallyLint

有了這個 Gradle 插件，我就可以在 API 開發過程中實時獲得反饋。這使我能夠在進入手動檢查步驟之前修復 API 的問題。該插件還可以與 CI 作業集成，用于風格指南的檢查驗證。因為所有開發團隊都使用相同的規則，所以組織就可以為用戶提供更加一致的 API。該方法大致有如下好處。該插件提供了一個選項，可以將違規報告導出為 JSON 和 HTML 格式。它還提供了一種簡單的規則配置方法，用于定義每個嚴重性級別下規范中可以存在的最大違規數。

可以將 JSON 格式解析并導出到任何數據庫中，用于計算 API 設計兼容性得分，并構建一個儀表板，共享給更廣泛的組織，作為 API 標準化方案的決策依據。同樣，HTML 報告也可以導出到 S3 桶或谷歌云存儲，并以網站的形式提供給更廣泛的受眾。

審核編輯 ：李倩