什么是API標準化？

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

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

1. 微軟 REST API 指南

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

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

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

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

如果不進行標準化，那么個體開發(fā)人員在設計過程中就可以隨意選擇。雖然我們鼓勵創(chuàng)造，但如果沒有適當?shù)娘L格指南，很快就會變得混亂。

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

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

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

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

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

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

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

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

根據 OpenAPI 編寫 API；

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

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

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

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

• 可以編寫并插入自己的規(guī)則；

• 直觀的 Web UI 顯示了實現(xiàn)的規(guī)則和規(guī)范驗證的結果；

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

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

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

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

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

zally-gradle-plugin 是一個用 kotlin 編寫的 Gradle 插件，可以集成到構建腳本中。該插件根據規(guī)則集驗證規(guī)范，并提供 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 開發(fā)過程中實時獲得反饋。這使我能夠在進入手動檢查步驟之前修復 API 的問題。該插件還可以與 CI 作業(yè)集成，用于風格指南的檢查驗證。因為所有開發(fā)團隊都使用相同的規(guī)則，所以組織就可以為用戶提供更加一致的 API。該方法大致有如下好處。該插件提供了一個選項，可以將違規(guī)報告導出為 JSON 和 HTML 格式。它還提供了一種簡單的規(guī)則配置方法，用于定義每個嚴重性級別下規(guī)范中可以存在的最大違規(guī)數(shù)。

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

審核編輯 ：李倩