API 上下游關(guān)聯(lián)方

  1. 一致性與可重用性：API 設(shè)計為在不同項目和應(yīng)用中具有一致性和可重用性。這使得標(biāo)準(zhǔn)化變得簡單，減少了開發(fā)時間，提升了解決方案的可擴(kuò)展性。
  2. 協(xié)作與文檔：API 優(yōu)先的方法強(qiáng)調(diào)開發(fā)團(tuán)隊、業(yè)務(wù)利益相關(guān)者和外部合作伙伴之間的協(xié)作。全面的文檔對于確保每個人了解如何有效使用 API 至關(guān)重要。
  3. 測試驅(qū)動開發(fā)：從一開始就對 API 進(jìn)行嚴(yán)格的測試，以便在開發(fā)過程中盡早識別和解決問題。這有助于保持高質(zhì)量標(biāo)準(zhǔn)，并降低后期出現(xiàn)昂貴錯誤的風(fēng)險。

從上述準(zhǔn)則中我們可以看到，基本上貫穿了 API 生命周期的大部分，也對我們設(shè)計、開發(fā) API 提出了一定的要求，那么遵循 API First 可以給我們帶來哪些好處？

通過提供 API 接口使得多個團(tuán)隊協(xié)同開發(fā)進(jìn)度不會互相 Block。

阿里云上 API First 實踐

基于 API 網(wǎng)關(guān)策略場景，談 API First 實踐。

API 網(wǎng)關(guān)存在非常多策略規(guī)則

在云原生 API 網(wǎng)關(guān)的使用和管理中，存在大量不同類型的策略規(guī)則，這些規(guī)則主要集中在安全能力、流量治理能力管理和 API/接口策略方面。為了有效管理這些策略，我們設(shè)計了一種通用的方式來抽象這些規(guī)則，并能夠靈活地應(yīng)用到不同的實體（如網(wǎng)關(guān)、路由、服務(wù)、域名）上。

設(shè)計 API

我們的解決方案基于兩個主要模型：Policy（策略）模型和 PolicyAttachment（策略附加）模型。Policy 模型負(fù)責(zé)定義所有策略的細(xì)節(jié)和規(guī)則，通過這個模型可以對策略進(jìn)行增、刪、改、查等操作，確保靈活性和可管理性。

API 網(wǎng)關(guān)策略管理能力模型設(shè)計

策略類型包括 IP 黑白名單、消費者鑒權(quán)和全局鑒權(quán)等安全能力管理，以及超時限制、重試機(jī)制、跨域資源共享 (CORS) 和重定向等 API/接口策略。下面是其中一個策略的示例：

{  "policyId": "policy1",  "name": "IP 黑名單策略",  "description": "禁止來自特定 IP 地址的訪問",  "type": "security",  "rules": {    "blacklist": ["192.168.1.1", "10.0.0.1"]  }}

為了將這些策略有效地應(yīng)用到特定的實體中，我們引入了 PolicyAttachment 模型。PolicyAttachment 模型用于將已經(jīng)定義的策略綁定到特定的實體（如網(wǎng)關(guān)、路由、服務(wù)、域名）上，使得同一策略可以在不同的上下文和場景中應(yīng)用，從而提供了更高的復(fù)用性和管理效率。下方展示了將策略綁定到一個服務(wù)的示例：

{  "attachmentId": "attachment1",  "policyId": "policy1",  "entityType": "service",  "entityId": "serviceA"}

為了管理策略和綁定關(guān)系這兩個模型，我們設(shè)計了一套 RESTful 風(fēng)格的 API 接口。這些接口涵蓋創(chuàng)建、獲取、更新和刪除策略的所有操作，以及附加和移除策略的功能。例如，一個 IP 黑名單策略的 Policy 結(jié)構(gòu)如下：

{  "name": "IPBlacklist",  "type": "security",  "rules": {    "blacklist": ["192.168.1.1", "10.0.0.2"]  }}

并且將該策略附加到一個 API 網(wǎng)關(guān)的請求如下：

POST /api/policyContent-Type: application/json

{  "name": "IPBlacklist",  "description": "gateway",  "config": {    "name": "IPBlacklist",    "type": "security",    "rules": {      "blacklist": ["192.168.1.1", "10.0.0.2"]    }  },  "attachResourceIds":[    "gatewayId1",  ],  "attachResourceType": "Gateway",  "environmentId": "environmentId1",  "gatewayId": "gatewayId1"}

通過這種統(tǒng)一的策略管理系統(tǒng)，我們不僅能夠提高系統(tǒng)的靈活性和可擴(kuò)展性，還使得安全性和管理變得更加高效。

基于上述思路我們提供了 API 網(wǎng)關(guān)最基本的策略相關(guān)的 API 接口設(shè)計思路。

在 API 網(wǎng)關(guān)中構(gòu)建 API

OpenAPI Specification (OAS) 是一種用于定義和描述 RESTful API 的標(biāo)準(zhǔn)化格式。以下是基于 OAS 定義的策略管理 API 模型：

openapi: 3.0.0info:  title: Policy Management API  version: v1servers:  - url: /apipaths:  /policies/{policyId}:    get:      summary: Get details of a specific policy.      operationId: getPolicy      parameters:        - name: policyId          in: path          required: true          description: The ID of the policy to retrieve.          schema:            type: string      responses:        '200':          description: Successful response with the policy details.          content:            application/json:              schema:                $ref: '#/components/schemas/Policy'components:  schemas:    Policy:      type: object      properties:        id:          type: string        name:          type: string        description:          type: string        createdAt:          type: string          format: date-time        updatedAt:          type: string          format: date-time

設(shè)計好 Policy 相關(guān)的 API 后，我們需要一個完整的 API 生命周期管理能力來幫助我們實踐 API First。我們以阿里云的云原生 API 網(wǎng)關(guān)為例，實踐整個 API First 的開發(fā)模式。

我們可以看到云原生 API 網(wǎng)關(guān)中，API 是整個產(chǎn)品的第一公民，與 API First 的開發(fā)原則顯得異曲同工。首先先創(chuàng)建 PolicyManagementAPI。在創(chuàng)建的過程中我們看到，支持 OAS/Sawgger 等標(biāo)準(zhǔn)導(dǎo)入 API，也支持手動創(chuàng)建整個流程。我們先看看手動錄入的效果。

云原生 API 網(wǎng)關(guān)控制臺創(chuàng)建 API

創(chuàng)建完成 API 之后，產(chǎn)品會引導(dǎo)我們?nèi)?chuàng)建接口。關(guān)于 Policy 相關(guān)的接口我們計劃創(chuàng)建關(guān)于 Policy 資源操作的生命周期增（創(chuàng)建策略并關(guān)聯(lián)資源）、刪（刪除策略并取消關(guān)聯(lián)資源）、改（修改策略并重新關(guān)聯(lián)資源）、查（查詢策略）。

云原生 API 網(wǎng)關(guān)控制臺創(chuàng)建 API 接口

我們提前設(shè)計好了 API ，因此創(chuàng)建接口的過程中，只需要按照我們的設(shè)計填入 API 接口的 Metadata 即可。

在 API First 原則中，文檔也是不可或缺的一部分，每次修改接口對應(yīng)的接口文檔也需要同步更新，既然我們在 API 管理平臺上完整錄入了接口的元數(shù)據(jù)信息，那么相關(guān)的文檔、SDK、spec都應(yīng)該實時更新。下面我們看到，比如請求參數(shù)的 Body 信息，其中 JSON Scheme 是用于 API 接口文檔的詳細(xì)內(nèi)容生成。如果我們不填寫，后續(xù)文檔的可讀性會大大降低，但我們也發(fā)現(xiàn)這個內(nèi)容其實非常重復(fù)性且標(biāo)準(zhǔn)化，所以 API 網(wǎng)關(guān)提供了 API 輔助生成 Schema 的能力。

云原生 API 網(wǎng)關(guān)控制臺創(chuàng)建 API 接口

填寫完成所有的內(nèi)容后，點擊添加。我們逐一錄入所有的接口，當(dāng)前 API 完整的情況如下圖所示。

云原生 API 網(wǎng)關(guān)控制臺 API 詳情

我們下載 SDK&文檔看一下，提前設(shè)計好 API (API First) 是如何幫助我們加速開發(fā)流程以及提升開發(fā)體驗。

云原生 API 網(wǎng)關(guān)控制臺生成 API SDK 與文檔

選擇 Java SDK 看看生成的效果。

API 文檔

由于后端還沒有編寫，目前不能直接調(diào)試。但是協(xié)作方可以基于此進(jìn)行開發(fā)。

我們可以構(gòu)建 API Mocking，這樣可以更加方便協(xié)作方進(jìn)行開發(fā)調(diào)試。

API Mocking

在開發(fā) API 邏輯之前，通過 API Mocking 提供初步的接口模擬，這有助于進(jìn)行早期的驗證和測試。提升開發(fā)聯(lián)調(diào)效率。在 API 網(wǎng)關(guān)中進(jìn)行該操作只需要 2 步，先定義 API 接口 Mock 返回的內(nèi)容，再發(fā)布 Mock 服務(wù)即可。

API 網(wǎng)關(guān)控制臺配置 API Mock

API 網(wǎng)關(guān)控制臺發(fā)布 API Mock

發(fā)布完成后，我們直接在 API 網(wǎng)關(guān)頁面進(jìn)行在線調(diào)試。

API 網(wǎng)關(guān)控制臺調(diào)試 API

我們在 API 文檔中找到需要的接口并且直接進(jìn)行調(diào)試，也返回預(yù)期的 Mock 值。這樣可以大幅度提升協(xié)作開發(fā)的效率。

通過 API 文檔調(diào)試 Mock 的 API

有了 API Mocking，前端、后端、 QA 以及其他依賴的業(yè)務(wù)方團(tuán)隊都可以同時進(jìn)行工作，構(gòu)建測試、客戶端應(yīng)用和服務(wù)器實現(xiàn)。

實現(xiàn) API 邏輯

我們可以將 spec 以 OAS3.0 格式導(dǎo)出，并通過 Swagger Codegen 可以快速生成服務(wù)端的代碼框架，幫助我們加速開發(fā)的效率。

Swagger Codegen 介紹

另一方面我們需要實現(xiàn) API 邏輯，并將其與后端系統(tǒng)集成。遵循編碼、安全和性能優(yōu)化的最佳實踐。在這邊我們不過多贅述。

API 測試和驗證

當(dāng)我們 API 開發(fā)完成后，我們可以先將后端發(fā)布至測試環(huán)境，并將 Mock 服務(wù)切換至真實測試環(huán)境后端服務(wù)。協(xié)同 QA、前端、依賴方進(jìn)行完整的測試驗證。包括但不限于進(jìn)行功能、性能和安全測試，以確保 API 達(dá)到質(zhì)量標(biāo)準(zhǔn)。

為了方便測試集成，我們需要對我們的 API 配置自動化的測試工具，集成到我們的測試體系中，可以做到常態(tài)化驗證保證 API 接口的正確性、性能和安全性。

我們還需要針對 API 配置安全防護(hù)策略，根據(jù)我們 API 的性能表現(xiàn)配置流量防護(hù)等限流策略，配置安全鑒權(quán)認(rèn)證規(guī)則，并完成完整策略能力驗證。

配置合適的流量防護(hù)策略

可以給當(dāng)前 API 授權(quán)給不同的消費者去訪問

完成這些準(zhǔn)備工作后，我們就可以對 API 進(jìn)行發(fā)布部署上線的流程。

API 策略配置

在 API 管理生命周期中，API 的安全性以及流量防護(hù)策略配置也是非常重要的一環(huán)。API 不僅是系統(tǒng)與系統(tǒng)之間的通信入口，還是安全和流量防護(hù)的第一道防線。阿里云 API 網(wǎng)關(guān)（API Gateway）提供了非常豐富的插件、策略能力，可以低成本幫助我們 API 做到完善安全防護(hù)以及系統(tǒng)防護(hù)能力，保證 API 的穩(wěn)定性。

云原生 API 網(wǎng)關(guān)在安全防護(hù)領(lǐng)域的插件

設(shè)置黑白名單：設(shè)置黑白名單可以通過在 API 上配置特定的黑名單和白名單，有效地控制訪問請求的權(quán)限。插件支持在網(wǎng)關(guān)全局、域名以及路由級別進(jìn)行 IP 黑名單和白名單的配置，比如我們能夠拒絕或允許特定 IP 的訪問請求，靈活的配置策略滿足對不同場景下 API 的訪問控制的精細(xì)化需求。

云原生 API 網(wǎng)關(guān)在認(rèn)證鑒權(quán)領(lǐng)域的插件

細(xì)粒度權(quán)限控制：在 API 上實施細(xì)粒度的權(quán)限控制，確保用戶只能訪問其權(quán)限范圍內(nèi)的資源。云原生 API 網(wǎng)關(guān)支持全局認(rèn)證、路由配置認(rèn)證和消費者鑒權(quán)，實現(xiàn)對 API 訪問的控制、安全性保障和策略管理。下方展示了云原生 API 網(wǎng)關(guān)在認(rèn)證鑒權(quán)領(lǐng)域的插件。

云原生 API 網(wǎng)關(guān)豐富的策略能力

精細(xì)化流量防護(hù)能力：云原生 API 網(wǎng)關(guān)支持 API/接口級別進(jìn)行流量控制、并發(fā)控制策略，通過對 API 和接口級別進(jìn)行精細(xì)化流控，可以有效管理和監(jiān)控請求流量，從而防止因突發(fā)流量或惡意訪問導(dǎo)致的系統(tǒng)過載。這種精細(xì)化管理不僅可以限制單個用戶的請求頻率，保護(hù)后端服務(wù)的性能，還能根據(jù)實際負(fù)載動態(tài)調(diào)整策略，優(yōu)化資源分配，確保 API 服務(wù)在高并發(fā)場景下依然能夠平穩(wěn)運(yùn)行。

API 發(fā)布、部署與監(jiān)控

API 網(wǎng)關(guān)在發(fā)布部署的過程中提供了灰度發(fā)布、全鏈路灰度的能力，可以幫助我們在發(fā)布的過程中控制風(fēng)險與影響面。API 的發(fā)布過程，我們可以通過 CI/CD 集成的方式實現(xiàn)進(jìn)一步的自動化。云原生 API 網(wǎng)關(guān)默認(rèn)內(nèi)置了云監(jiān)控、Prometheus 等監(jiān)控、可觀測能力，可以幫助我們觀測 API 在生產(chǎn)環(huán)節(jié)中的性能和使用情況。我們可以通過監(jiān)控、告警來保障我們 API 的穩(wěn)定性，持續(xù)滿足業(yè)務(wù)的SLA需求。

API First 的實踐理念強(qiáng)調(diào)在軟件開發(fā)過程中，優(yōu)先設(shè)計和考慮 API 的需求，以確保系統(tǒng)的靈活性、可維護(hù)性和可擴(kuò)展性。這一理念貫穿了需求設(shè)計、協(xié)同開發(fā)、上線和運(yùn)維等全生命周期。

云原生 API 網(wǎng)關(guān)可以幫助我們更好地實踐 API First。

  1. 在需求設(shè)計階段，API First 方法鼓勵團(tuán)隊在早期就明確 API 的功能和接口契約，通過文檔化的形式確保各方對于 API 的理解一致。這種自上而下的設(shè)計思路能夠有效減少后續(xù)開發(fā)中的溝通成本和誤解，從而提高開發(fā)效率。
  2. 在協(xié)同開發(fā)過程中，云原生 API 網(wǎng)關(guān)發(fā)揮著關(guān)鍵作用。它不僅提供了統(tǒng)一的接口管理，還可以根據(jù) API 的定義，自動生成 SDK 和文檔，方便開發(fā)人員快速上手。通過 API 網(wǎng)關(guān)，團(tuán)隊可以實現(xiàn)快速構(gòu)建、發(fā)布和迭代，支持微服務(wù)架構(gòu)的靈活性，使開發(fā)人員可以專注于業(yè)務(wù)邏輯的實現(xiàn)而非底層細(xì)節(jié)。
  3. 上線階段，API 網(wǎng)關(guān)能夠幫助我們進(jìn)行流量管理和安全控制，確保 API 在生產(chǎn)環(huán)境中的穩(wěn)定性。例如，通過流量監(jiān)控和限流策略，及時發(fā)現(xiàn)和處理異常流量，保障用戶體驗。同時，API 網(wǎng)關(guān)可以集成身份驗證和授權(quán)機(jī)制，進(jìn)一步增強(qiáng) API 的安全性。
  4. 在運(yùn)維環(huán)節(jié)，云原生 API 網(wǎng)關(guān)提供了豐富的監(jiān)控和分析功能，幫助運(yùn)維團(tuán)隊實時評估 API 的性能和健康狀況。通過分析 API 的訪問日志和使用數(shù)據(jù)，運(yùn)維人員能夠快速定位問題，優(yōu)化系統(tǒng)性能，保證服務(wù)的高可用性。

API 設(shè)計建設(shè)

下面我們基于 API 網(wǎng)關(guān)開發(fā)過程中的一些生產(chǎn)實踐經(jīng)驗談一談關(guān)于 API 設(shè)計的建議。

可演進(jìn)性

API 設(shè)計中提供了版本的概念，對于同一個版本的 API 來說，每一次 API 變更都需要考慮到 API 的向前兼容性，即老的客戶端能否正常訪問服務(wù)端的新版本也不應(yīng)該有錯誤的行為。

任何一次API的升級，我們都需要考慮已經(jīng)使用 API 的用戶，他們的業(yè)務(wù)是否會因為我們的一次變更而出現(xiàn)不兼容的風(fēng)險。

如果存在不兼容的變更，我們需要通過升級 API 的大版本來實現(xiàn)，這時候會涉及到客戶端的升級，那么這個過程將會是非常漫長，頻繁的不兼容升級對我們的 API 使用者來說是一件不愿意接受的事情。也正是因為如此，反過來說，我們才從一開始就重要 API 的設(shè)計。在 API 設(shè)計的過程中，可以多驗證自己的 API 設(shè)計，在發(fā)布前提前挖掘潛在的風(fēng)險。

關(guān)于軟件升級與變更，在 OpenAPI 規(guī)范中，可以以描述的形式在基本信息中指定本 API 的版本。我們可以通過標(biāo)準(zhǔn)的版本控制方法允許引入新功能或者重大變更的過程中保證 API 的穩(wěn)定性，從而確保現(xiàn)有用戶和客戶端應(yīng)用不會受到突然的變化影響。這種向后兼容性對于維護(hù)長期用戶信任和應(yīng)用的連續(xù)性至關(guān)重要。另外，API 的版本控制幫助我們給 API 使用者提供一條平滑的升級路徑，使得開發(fā)者和用戶可以按照 API 維度逐步遷移至新版本，避免一次性全面升級的風(fēng)險。

好的 API 文檔

在如今微服務(wù)架構(gòu)日益普及的環(huán)境下，一個服務(wù)會依賴大量的外部 API 接口，在開發(fā)的過程中 API 文檔的重要性不容忽視。準(zhǔn)確而及時更新的 API 文檔能夠為開發(fā)者提供清晰的接口說明和代碼示例，這樣會大大減少了誤用和踩坑的幾率。同時，它顯著提高了開發(fā)效率，通過減少溝通成本和快速解決問題來支持敏捷開發(fā)和快速迭代。

JDK ArrayList 文檔

這也是為什么一個好的 API 可以經(jīng)久不衰的原因之一。我們可以從上述示例中看大，一個好的 API 文檔會描述 API 的功能、實現(xiàn)、例子，同時也會提到使用該 API 需要注意的點，可能會有哪些風(fēng)險 Note that this implementation is not synchronized. 這些都可以幫助使用者提前識別該 API 適用的場景。

控制 API 的數(shù)量

當(dāng)一個產(chǎn)品涉及數(shù)千個 API 時，其使用者和維護(hù)者所面臨的成本都會顯著增加。最初花費幾個小時實現(xiàn)的 API，可能最終需要投入數(shù)百甚至數(shù)千小時進(jìn)行維護(hù)和升級。因此，對于我們內(nèi)部開發(fā)而言，每新增一個 API 都必須經(jīng)過嚴(yán)格的評審。我們盡量在初期通過精心的 API 設(shè)計和已有 API 的組合，來滿足新的 API 使用場景。因為一旦 API 開放，就有用戶和客戶端開始集成，這意味著 API 的收斂、下線以及變更將成為一項巨大的負(fù)擔(dān)。

再談 API First 的得與失

API First 對于效率是降低還是提升？由于 API First 模式在程序設(shè)計初期就需要集中精力進(jìn)行 API 設(shè)計，因此需要較為全面的前期規(guī)劃和設(shè)計工作。此外，提前做出 API 設(shè)計決策可能會限制開發(fā)過程中的一些嘗試與探索，可能在開發(fā)后期需要進(jìn)一步調(diào)整 API 的設(shè)計，當(dāng) API 數(shù)量大了之后這整個過程會在一定程度上減慢項目開發(fā)的速度，API 的設(shè)計、管理與維護(hù)都有一定的負(fù)擔(dān)。

一旦設(shè)計并確定了明確的 API 后，可以促進(jìn)并行開發(fā)，減少依賴性和瓶頸，從而加快功能交付速度。一個完善的 API 管理工具也能夠有效降低 API 管理成本。在項目的后期，包括上線后的產(chǎn)品體驗，使用 API First 開發(fā)模式都會有更多的益處：明確的 API 使得外部系統(tǒng)和第三方應(yīng)用的集成更加輕松，通過工具建設(shè)提升效率；一開始就考慮可擴(kuò)展性和安全設(shè)計，使系統(tǒng)具備更強(qiáng)的安全、高可用能力；通過 API 暴露出來的數(shù)據(jù)也會激發(fā)工程師和用戶的創(chuàng)新。因此，盡管前期開發(fā)速度可能受到一定影響，API First 模式在長期來看能夠顯著提升項目整體效率和產(chǎn)品質(zhì)量。

在 AI、小程序、Serverless 等軟件技術(shù)快速發(fā)展的趨勢下，API First 開發(fā)模式使應(yīng)用程序能夠更靈活地與這些技術(shù)進(jìn)行集成。通過 API，無論是與 AI 服務(wù)交互，還是與小程序和函數(shù)計算通信都能迅速實現(xiàn)。這不僅加快了探索和上線的速度，也降低了業(yè)務(wù)試錯的成本，為公司在快速變化的市場中保持競爭優(yōu)勢提供了有力支持。

文章轉(zhuǎn)載自： 基于 API 網(wǎng)關(guān)踐行 API First 開發(fā)實踐

上一篇：

API經(jīng)濟(jì)崛起！快速串接金流，為什么銀行「愈開放愈好賺」？

下一篇：

借助AI營銷類API，為產(chǎn)品開發(fā)和市場定位提供有力支持
#你可能也喜歡這些API文章!

我們有何不同？

API服務(wù)商零注冊

多API并行試用

數(shù)據(jù)驅(qū)動選型，提升決策效率

查看全部API→
??

熱門場景實測，選對API

#AI文本生成大模型API

對比大模型API的內(nèi)容創(chuàng)意新穎性、情感共鳴力、商業(yè)轉(zhuǎn)化潛力

25個渠道
一鍵對比試用API 限時免費

#AI深度推理大模型API

對比大模型API的邏輯推理準(zhǔn)確性、分析深度、可視化建議合理性

10個渠道
一鍵對比試用API 限時免費