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

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

1. 微軟 REST API 指南

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

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

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

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

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

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

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

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

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

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

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

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

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

根據(jù) OpenAPI 編寫(xiě) API；

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

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

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

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

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

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

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

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

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

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

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

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

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

審核編輯 ：李倩