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

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

1. 微軟 REST API 指南

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

清晰的設(shè)計(jì)方法可以確保 API 與業(yè)務(wù)需求相一致。API 越標(biāo)準(zhǔn)，歧義就越少，合作成果就越多，質(zhì)量就更有保障，API 的采用也會相應(yīng)增加。

清晰一致的 API 設(shè)計(jì)標(biāo)準(zhǔn)是良好開發(fā)體驗(yàn)和消費(fèi)體驗(yàn)的基礎(chǔ)。它們使開發(fā)人員和消費(fèi)者都能夠快速有效地理解 API，縮短學(xué)習(xí)曲線，并按照一套指南進(jìn)行構(gòu)建。

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

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

如果不進(jìn)行標(biāo)準(zhǔn)化，那么組織就無法在 API 設(shè)計(jì)和交付過程中提供質(zhì)量保證。強(qiáng)化設(shè)計(jì)標(biāo)準(zhǔn)有助于提升預(yù)測成功結(jié)果的能力，讓組織能夠在保證質(zhì)量的前提下快速擴(kuò)展 API 開發(fā)。

如果沒有一個(gè)正式的流程來強(qiáng)化標(biāo)準(zhǔn)化，就不可能成功地?cái)U(kuò)展 API 設(shè)計(jì)和開發(fā)過程，也不可能符合監(jiān)管和行業(yè)標(biāo)準(zhǔn)。API 設(shè)計(jì)風(fēng)格指南提供了內(nèi)外部團(tuán)隊(duì)在構(gòu)建 API 定義和重用資產(chǎn)時(shí)開展協(xié)作所需的“護(hù)欄”。

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

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

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

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

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

將 API 標(biāo)準(zhǔn)或風(fēng)格指南表示成一組規(guī)則。這里有 Zalando 提供的一份指南；

根據(jù) OpenAPI 編寫 API；

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

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

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

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

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

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

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

雖然 Zally 的編寫方式更具可擴(kuò)展性和可定制性，但我覺得，我們?nèi)匀豢梢赃M(jìn)一步改進(jìn) Zally 當(dāng)前的驗(yàn)證工作流，縮短開發(fā)反饋循環(huán)。由于 Zally 缺少像 checkstyle、ktlint、spot bug 這樣的插件，所以我在使用 Zally 時(shí)遇到了以下幾個(gè)痛點(diǎn)：

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

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

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

zally-gradle-plugin 是一個(gè)用 kotlin 編寫的 Gradle 插件，可以集成到構(gòu)建腳本中。該插件根據(jù)規(guī)則集驗(yàn)證規(guī)范，并提供 JSON 和 HTML 格式的報(bào)告。

該項(xiàng)目包含一個(gè)示例任務(wù)配置：

// 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

有了這個(gè) Gradle 插件，我就可以在 API 開發(fā)過程中實(shí)時(shí)獲得反饋。這使我能夠在進(jìn)入手動檢查步驟之前修復(fù) API 的問題。該插件還可以與 CI 作業(yè)集成，用于風(fēng)格指南的檢查驗(yàn)證。因?yàn)樗虚_發(fā)團(tuán)隊(duì)都使用相同的規(guī)則，所以組織就可以為用戶提供更加一致的 API。該方法大致有如下好處。該插件提供了一個(gè)選項(xiàng)，可以將違規(guī)報(bào)告導(dǎo)出為 JSON 和 HTML 格式。它還提供了一種簡單的規(guī)則配置方法，用于定義每個(gè)嚴(yán)重性級別下規(guī)范中可以存在的最大違規(guī)數(shù)。

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

審核編輯 ：李倩