一、優秀的接口設計
在日常開發中，總會接觸到各種接口。前后端數據傳輸接口，第三方業務平台接口。一個平台的前后端數據傳輸接口一般都會在內網環境下通信，而且會使用安全框架，所以安全性可以得到很好的保護。這篇文章重點討論一下提供給第三方平台的業務接口應當如何設計？我們應該考慮哪些問題？
主要從以上三個方面來設計一個安全的API接口。
1.1 安全性問題
安全性問題是一個接口必須要保證的規范。如果接口保證不了安全性，那么你的接口相當於直接暴露在公網環境中任人蹂躪。
1.1.1 調用接口的先決條件-token
獲取token一般會涉及到幾個參數appid，appkey，timestamp，nonce，sign。我們通過以上幾個參數來獲取調用系統的憑證。
appid和appkey可以直接通過平台線上申請，也可以線下直接頒發。appid是全局唯一的，每個appid將對應一個客戶，appkey需要高度保密。
timestamp是時間戳，使用系統當前的unix時間戳。時間戳的目的就是為了減輕DOS攻擊。防止請求被攔截后一直嘗試請求接口。服務器端設置時間戳閥值，如果請求時間戳和服務器時間超過閥值，則響應失敗。
nonce是隨機值。隨機值主要是為了增加sign的多變性，也可以保護接口的冪等性，相鄰的兩次請求nonce不允許重復，如果重復則認為是重復提交，響應失敗。
sign是參數簽名，將appkey，timestamp，nonce拼接起來進行md5加密（當然使用其他方式進行不可逆加密也沒問題）。
token，使用參數appid，timestamp，nonce，sign來獲取token，作為系統調用的唯一憑證。token可以設置一次有效（這樣安全性更高），也可以設置時效性，這里推薦設置時效性。如果一次有效的話這個接口的請求頻率可能會很高。token推薦加到請求頭上，這樣可以跟業務參數完全區分開來。
1.1.2 使用POST作為接口請求方式
一般調用接口最常用的兩種方式就是GET和POST。兩者的區別也很明顯，GET請求會將參數暴露在瀏覽器URL中，而且對長度也有限制。為了更高的安全性，所有接口都采用POST方式請求。
1.1.3 客戶端IP白名單
ip白名單是指將接口的訪問權限對部分ip進行開放。這樣就能避免其他ip進行訪問攻擊，設置ip白名單比較麻煩的一點就是當你的客戶端進行遷移后，就需要重新聯系服務提供者添加新的ip白名單。設置ip白名單的方式很多，除了傳統的防火牆之外，spring cloud alibaba提供的組件sentinel也支持白名單設置。為了降低api的復雜度，推薦使用防火牆規則進行白名單設置。
1.1.4 單個接口針對ip限流
限流是為了更好的維護系統穩定性。使用redis進行接口調用次數統計，ip+接口地址作為key，訪問次數作為value，每次請求value+1，設置過期時長來限制接口的調用頻率。
1.5 記錄接口請求日志
使用aop全局記錄請求日志，快速定位異常請求位置，排查問題原因。
1.1.6 敏感數據脫敏
在接口調用過程中，可能會涉及到訂單號等敏感數據，這類數據通常需要脫敏處理，最常用的方式就是加密。加密方式使用安全性比較高的RSA非對稱加密。非對稱加密算法有兩個密鑰，這兩個密鑰完全不同但又完全匹配。只有使用匹配的一對公鑰和私鑰，才能完成對明文的加密和解密過程。
1.2 冪等性問題
冪等性是指任意多次請求的執行結果和一次請求的執行結果所產生的影響相同。說的直白一點就是查詢操作無論查詢多少次都不會影響數據本身，因此查詢操作本身就是冪等的。但是新增操作，每執行一次數據庫就會發生變化，所以它是非冪等的。
冪等問題的解決有很多思路，這里講一種比較嚴謹的。提供一個生成隨機數的接口，隨機數全局唯一。調用接口的時候帶入隨機數。第一次調用，業務處理成功后，將隨機數作為key，操作結果作為value，存入redis，同時設置過期時長。第二次調用，查詢redis，如果key存在，則證明是重復提交，直接返回錯誤。
1.3 數據規范問題
1.3.1 版本控制
一套成熟的API文檔，一旦發布是不允許隨意修改接口的。這時候如果想新增或者修改接口，就需要加入版本控制，版本號可以是整數類型，也可以是浮點數類型。一般接口地址都會帶上版本號，http://ip:port//v1/list。
1.3.2 響應狀態碼規范
一個牛逼的API，還需要提供簡單明了的響應值，根據狀態碼就可以大概知道問題所在。我們采用http的狀態碼進行數據封裝，例如200表示請求成功，4xx表示客戶端錯誤，5xx表示服務器內部發生錯誤。狀態碼設計參考如下：
分類 描述
1xx 信息，服務器收到請求，需要請求者繼續執行操作
2xx 成功
3xx 重定向，需要進一步的操作以完成請求
4xx 客戶端錯誤，請求包含語法錯誤或無法完成請求
5xx 服務端錯誤
狀態碼枚舉類：
public enum CodeEnum {
// 根據業務需求進行添加
SUCCESS(200,"處理成功"),
ERROR_PATH(404,"請求地址錯誤"),
ERROR_SERVER(505,"服務器內部發生錯誤");
private int code;
private String message;
CodeEnum(int code, String message) {
this.code = code;
this.message = message;
}
public int getCode() {
return code;
}
public void setCode(int code) {
this.code = code;
}
public String getMessage() {
return message;
}
public void setMessage(String message) {
this.message = message;
}
}
1.3.3 統一響應數據格式
為了方便給客戶端響應，響應數據會包含三個屬性，狀態碼（code）,信息描述（message）,響應數據（data）。客戶端根據狀態碼及信息描述可快速知道接口，如果狀態碼返回成功，再開始處理數據。
響應結果定義及常用方法：
public class R implements Serializable {
private static final long serialVersionUID = 793034041048451317L;
private int code;
private String message;
private Object data = null;
public int getCode() {
return code;
}
public void setCode(int code) {
this.code = code;
}
public String getMessage() {
return message;
}
public void setMessage(String message) {
this.message = message;
}
public Object getData() {
return data;
}
/**
* 放入響應枚舉
*/
public R fillCode(CodeEnum codeEnum){
this.setCode(codeEnum.getCode());
this.setMessage(codeEnum.getMessage());
return this;
}
/**
* 放入響應碼及信息
*/
public R fillCode(int code, String message){
this.setCode(code);
this.setMessage(message);
return this;
}
/**
* 處理成功，放入自定義業務數據集合
*/
public R fillData(Object data) {
this.setCode(CodeEnum.SUCCESS.getCode());
this.setMessage(CodeEnum.SUCCESS.getMessage());
this.data = data;
return this;
}
}
1.4 接口設計總結
本篇文章從安全性、冪等性、數據規范等方面討論了API設計規范。除此之外，一個好的API還少不了一個優秀的接口文檔。接口文檔的可讀性非常重要，雖然很多程序員都不喜歡寫文檔，而且不喜歡別人不寫文檔。為了不增加程序員的壓力，推薦使用swagger或其他接口管理工具，通過簡單配置，就可以在開發中測試接口的連通性，上線后也可以生成離線文檔用於管理API。
二、推薦些優秀的在線文檔生成工具
一些優秀的在線文檔、接口文檔的生成工具，需滿足如下條件：
- 必須是開源的
- 能夠實時生成在線文檔
- 支持全文搜索
- 支持在線調試功能
- 界面優美
在此推薦一些滿足上述條件的在線接口文檔工具。
2.1 Knife4j
gitee地址：https://gitee.com/xiaoym/knife4j
推薦指數：★★★★
Knife4j是為Java MVC框架集成Swagger生成Api文檔的增強解決方案，前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一樣小巧,輕量,並且功能強悍。
-
優點：基於swagger生成實時在線文檔，支持在線調試，全局參數、國際化、訪問權限控制等，功能非常強大。
-
缺點：界面有一點點丑，需要依賴額外的jar包
-
個人建議：如果公司對ui要求不太高，可以使用這個文檔生成工具，比較功能還是比較強大的。
2.2 smartdoc
gitee地址：https://gitee.com/smart-doc-team/smart-doc
用戶：小米、科大訊飛、1加
示例：
smart-doc是一個java restful api文檔生成工具，smart-doc顛覆了傳統類似swagger這種大量采用注解侵入來生成文檔的實現方法。smart-doc完全基於接口源碼分析來生成接口文檔，完全做到零注解侵入，只需要按照java標准注釋的寫就能得到一個標准的markdown接口文檔。
-
優點：基於接口源碼分析生成接口文檔，零注解侵入，支持html、pdf、markdown格式的文件導出。
-
缺點：需要引入額外的jar包，不支持在線調試
-
個人建議：如果實時生成文檔，但是又不想打一些額外的注解，比如：使用swagger時需要打上@Api、@ApiModel等注解，就可以使用這個。
2.3 redoc
github地址：https://github.com/Redocly/redoc
用戶：docker、redocly
示例：
redoc自己號稱是一個最好的在線文檔工具。它支持swagger接口數據，提供了多種生成文檔的方式，非常容易部署。使用redoc-cli能夠將您的文檔捆綁到零依賴的 HTML文件中，響應式三面板設計，具有菜單/滾動同步。
-
優點：非常方便生成文檔，三面板設計
-
缺點：不支持中文搜索，分為：普通版本 和 付費版本，普通版本不支持在線調試。另外UI交互個人感覺不適合國內大多數程序員的操作習慣。
-
個人建議：如果想快速搭建一個基於swagger的文檔，並且不要求在線調試功能，可以使用這個。
2.4 yapi
github地址：https://github.com/YMFE/yapi
用戶：騰訊、阿里、百度、京東等大廠
示例：
yapi是去哪兒前端團隊自主研發並開源的，主要支持以下功能：
-
可視化接口管理
-
數據mock
-
自動化接口測試
-
數據導入（包括swagger、har、postman、json、命令行）
-
權限管理
-
支持本地化部署
-
支持插件
-
支持二次開發
-
優點：功能非常強大，支持權限管理、在線調試、接口自動化測試、插件開發等，BAT等大廠等在使用，說明功能很好。
-
缺點：在線調試功能需要安裝插件，用戶體檢稍微有點不好，主要是為了解決跨域問題，可能有安全性問題。不過要解決這個問題，可以自己實現一個插件，應該不難。
-
個人建議：如果不考慮插件安全的安全性問題，這個在線文檔工具還是非常好用的，可以說是一個神器，筆者在這里強烈推薦一下。
2.5 apidoc
github地址：https://github.com/apidoc/apidoc
推薦指數：★★★★☆
示例：
apidoc 是一個簡單的 RESTful API 文檔生成工具，它從代碼注釋中提取特定格式的內容生成文檔。支持諸如 Go、Java、C++、Rust 等大部分開發語言，具體可使用 apidoc lang 命令行查看所有的支持列表。
apidoc 擁有以下特點：
- 跨平台，linux、windows、macOS 等都支持；
- 支持語言廣泛，即使是不支持，也很方便擴展；
- 支持多個不同語言的多個項目生成一份文檔；
- 輸出模板可自定義；
- 根據文檔生成 mock 數據；
-
優點：基於代碼注釋生成在線文檔，對代碼的嵌入性比較小，支持多種語言，跨平台，也可自定義模板。支持搜索和在線調試功能。
-
缺點：需要在注釋中增加指定注解，如果代碼參數或類型有修改，需要同步修改注解相關內容，有一定的維護工作量。
-
個人建議：這種在線文檔生成工具提供了另外一種思路，swagger是在代碼中加注解，而apidoc是在注解中加數據，代碼嵌入性更小，推薦使用。
2.6 showdoc(記得好像開始收費了)
github地址：https://github.com/star7th/showdoc
用戶：超過10000+互聯網團隊正在使用
示例：
ShowDoc就是一個非常適合IT團隊的在線文檔分享工具，它可以加快團隊之間溝通的效率。
它都有些什么功能：
- 響應式網頁設計，可將項目文檔分享到電腦或移動設備查看。同時也可以將項目導出成word文件，以便離線瀏覽。
- 權限管理，ShowDoc上的項目有公開項目和私密項目兩種。公開項目可供任何登錄與非登錄的用戶訪問，而私密項目則需要輸入密碼驗證訪問。密碼由項目創建者設置。
- ShowDoc采用markdown編輯器，點擊編輯器上方的按鈕可方便地插入API接口模板和數據字典模板。
- ShowDoc為頁面提供歷史版本功能，你可以方便地把頁面恢復到之前的版本。
- 支持文件導入，文件可以是postman的json文件、swagger的json文件、showdoc的markdown壓縮包，系統會自動識別文件類型。
-
優點：支持項目權限管理，多種格式文件導入，全文搜索等功能，使用起來還是非常方便的。並且既支持部署自己的服務器，也支持在線托管兩種方式。
-
缺點：不支持在線調試功能
-
個人建議：如果不要求在線調試功能，這個在線文檔工具值得使用。
2.7 Apizza（極客專屬的接口協作管理工具）
2.7.1 主要功能
-
api跨域調試量身定制的chrome插件，本地，在線接口，都可以調。
-
雲端存儲，企業安全版支持本地數據中心。
-
一鍵分享，與團隊共享你的API文檔。
-
支持Postman，Swagger格式 導入Postman/Swagger Json 生成文檔。
-
導出離線文檔，部署本地服務器。
-
api Mock 根據文檔自動生成返回結果，提供獨立URL方便前端測試。
-
支持多種文檔 http接口文檔，markdown說明文檔。
Apizza接口文檔工具有一個很大不足的地方，那是Apizza個人免費版有人數限制，所有超過8人的團隊如果想免費用，你是不用考慮Apizza的。如果你看到有文章或公眾號上說Apizza是免費的，那簡直是胡扯，他肯定沒用過。當然如果你不缺錢，可以付費開通企業版。我們團隊也是用了半年多Apizza，后來由於人員增加，Apizza里又無法再新添加新成員，迫使我們不得不放棄Apizza。
2.8 APIJSON
Gitee地址：https://gitee.com/Tencent/APIJSON
推薦指數：★★★★
-
APIJSON 是一種專為 API 而生的 JSON 網絡傳輸協議 以及 基於這套協議實現的 ORM 庫。 為簡單的增刪改查、復雜的查詢、簡單的事務操作 提供了完全自動化的萬能 API。
-
能大幅降低開發和溝通成本，簡化開發流程，縮短開發周期。
-
適合中小型前后端分離的項目，尤其是 BaaS、Serverless、互聯網創業項目和企業自用項目。
-
通過萬能的 API，前端可以定制任何數據、任何結構。
-
大部分 HTTP 請求后端再也不用寫接口了，更不用寫文檔了。
-
前端再也不用和后端溝通接口或文檔問題了。再也不會被文檔各種錯誤坑了。
-
后端再也不用為了兼容舊接口寫新版接口和文檔了。再也不會被前端隨時隨地沒完沒了地煩了。
2.8.1 特點功能
對於前端
- 不用再向后端催接口、求文檔
- 數據和結構完全定制，要啥有啥
- 看請求知結果，所求即所得
- 可一次獲取任何數據、任何結構
- 能去除重復數據，節省流量提高速度
對於后端
- 提供通用接口，大部分 API 不用再寫
- 自動生成文檔，不用再編寫和維護
- 自動校驗權限、自動管理版本、自動防 SQL 注入
- 開放 API 無需划分版本，始終保持兼容
- 支持增刪改查、復雜查詢、跨庫連表、遠程函數等
2.8.2 APIJSON 接口展示
2.9 其他一些接口管理神器
由於 API 在軟件開發過程中如此關鍵，那么對 API 的管理就顯得格外重要。通過 API 管理工具和平台能夠大大簡化 API 管理的難度和復雜度。下面列舉了一些頂級 API 管理工具和平台，可供您參考。
2.9.1 API Umbrella
API Umbrella 是用於管理 API 和微服務的頂級開源工具之一。通過為不同的域授予不同的管理員權限，它可以使多個團隊使用同一個 Umbrella。該平台還提供速率限制，API 密鑰，緩存，實時分析和 Web 管理界面等功能。
2.9.2 Gravitee.io
Gravitee.io 是一個用於管理 API 的開源平台，這個工具是靈活的並且是輕量級的。它具有開箱即用的功能，例如速率限制，IP 過濾，跨域資源共享，即插即用選項，具有基於 OAuth2 和 JSON Web 令牌策略的開發者門戶，負載平衡等。
但是，此 API 管理工具的主要功能是能夠生成細粒度的報告以理解 API 的數據是如何使用的。
2.9.3 APIman.io
APIman.io 是由 Red Hat 引入的一個頂級 API 管理平台，這個平台在 GitHub 中可以找到，為后端開發人員提供了很多便利。這包括：
快速運行 具有可分離策略引擎的基於策略的治理 異步功能 增強的結算和分析選項 REST API 可用性的管理 限速，還有其他
2.9.4 WSO2 API 管理器
WSO2 API Manager 是一個完整的生命周期 API 管理平台，可以隨時隨地運行。可以在企業內部和私有雲上執行 API 的分發和部署。除此之外，它還提供了一些其他的便利。其中一些是：
高度定制化 管理策略易用， 為 SOAP 或 RESTful API 設計和原型的可能性， 更好的訪問控制和貨幣化設施等
2.9.5 Kong Enterprise
Kong 是一種廣泛采用的開源微服務 API 工具，它使開發人員能夠快速，輕松，安全地管理一切。它的企業版帶有許多特性和功能，例如：
開源插件的可用性 一鍵式操作 通用語言基礎架構功能 強大的可視化監控功能 常規軟件運行狀況檢查 OAuth2.0 權限，以及 更廣泛的社區支持
2.9.6 Tyk.io
Tyk.io 用 Go 編程語言編寫，也是公認的開源 API 網關。
它帶有開發者門戶，詳細的文檔，用於 API 分析的儀表板，API 的速率限制，身份驗證以及各種其他此類規范，可幫助組織專注於微服務環境和容器化。但是，其基於商業的服務僅適用於付費版本。
2.9.7 Fusio
Fusio 是另一個開源 API 管理工具，開發人員可以使用它從不同的數據類型創建和維護 REST API。它具有高效的生命周期管理功能，例如用於管理控制的后端儀表板，詳細的文檔，用於傳入請求的 JSON 驗證以及滿足用戶權限的范圍處理。
而且，此 APIM 平台會自動生成 OAI 和 RAML 要求，並根據定義的架構創建自定義的客戶端 SDK。
2.9.8 Apigility
Apigility 由 Zend 框架設計和維護，是考慮用於 API 管理的下一個開源框架。該平台創建並展示其代碼的 JSON 表示形式。它還為他們提供了不同的版本控制選項，以及通過 OAuth2 進行身份驗證的簡便性和包含 API 藍圖的文檔。
API 接口管理，這 15 種開源工具助你管理 API Apigility
2.9.9 SwaggerHub
SwaggerHub 被 40 多個組織考慮用於管理 API，它也是最好的開源 API 管理工具之一。
該平台為后端開發領域的設計人員和開發人員提供了廣泛的選擇。它為他們提供了強大而直觀的編輯器，可在保持設計一致性的同時提供更高的效率和速度。
此外，它還提供了智能錯誤反饋，語法自動完成和多種樣式驗證器可用性的機會。
2.9.10 API Axle
在 Exicon 的支持下，API Axle 是另一種開源，簡單且輕量級的代理，為開發人員提供了很多好處，例如：實時分析 強大的身份驗證， 記錄 API 流量以進行統計和報告， 易於創建和管理 API 密鑰，以及 支持 REST API 設計以及 Go，PHP 和 Node.js 庫的使用。
2.9.11 IBM Bluemix API
該 API 管理工具使開發人員可以使用 200 多種軟件和中間件模式來為混合雲構建可移植且兼容的應用程序。它還提供各種預先構建的服務和強大的機制，用於調節 API 訪問，管理多個 API 版本，維持速率限制以及跟蹤性能指標和所涉及的每個 API 的分析。
2.9.12 Repose
Repose 是一個開源的 RESTful 中間件平台，在不斷變化的 API 市場中起着舉足輕重的作用。該平台為組織提供了各種 API 處理功能，包括身份驗證，API 驗證，速率限制和 HTTP 請求日志記錄。
該 API 管理平台旨在提供格式正確且經過驗證的信任下游請求的下游服務。而且，它本質上具有高度可擴展性和可擴展性，這意味着開發人員可以根據不斷增長的需求輕松地使用它。
2.9.13 SnapLogic 企業集成雲
SnapLogic 是一個不錯的集成平台即服務（iPaaS）工具，可幫助組織獲取，維持和增長其客戶群。其具備的特征是：
它是快速的，多點的，並具有可靈活滿足面向批處理和實時應用程序數據集成需求的選項。它具有可擴展的體系結構，其運行方式類似於 Web 服務器，但也提供了擁抱多功能性的選項。它還帶有創新的數據流解決方案，鼓勵組織將著名的 SaaS 應用程序如 SugarCRM 和 Salesforce）添加到其傳統流程中。
2.9.14 DreamFactory
DreamFactory API 管理平台是下一個項目要考慮的最好的免費開源工具之一，其受歡迎的原因如下：
它為開發人員提供了無需手動編寫 API 即可進行移動應用程序開發的方法。
它使他們能夠將任何 SQL / NoSQL 數據庫，外部 HTTP / SOAP 服務或文件存儲系統集成到 DreamFactory 環境中，並自動獲得全面，靈活，完全文檔化且隨時可用的 REST API。除了訪問用於分頁，復雜過濾器，虛擬外鍵，相關表聯接等的 API 參數之外，該平台還為 SQL 數據庫提供了詳細的 REST API。
DreamFactory API 管理平台的另一個獨特功能是，它可以立即將 JSON 請求轉換為 SOAP，反之亦然。此外，該平台還以易於管理的形式提供了高度安全的用戶管理，SSO 身份驗證，CORS，JSON Web 令牌，SAML 集成，API 端點上基於角色的訪問控制，OAuth 和 LDAP。API 接口管理，這 15 種開源工具助你管理 API DreamFactory
2.9.15 3Scale
最后但並非最不重要的一點是，3Scale 是此 API 管理工具列表的補充。
API 管理工具由 Red Hat 擁有，它使大小型企業都可以通過以下功能輕松安全地管理其 API：
它采用了一個分布式的雲層來集中 API 程序的控制。這樣可以更輕松地控制分析，可訪問性，開發人員工作流程，獲利等。
由於它托管在分布式雲托管層上，因此具有高度的靈活性和可擴展性。
3Scale API 的 OpenShift 集成功能使您能夠以自動化且封閉的方式運行高性能應用程序。這個完整的生命周期 API 管理平台使開發人員可以隨時計划，設計，應用，發布，管理，分析，優化和淘汰您的 API，以提供卓越的體驗。
它具有通過 Web 或移動應用程序輕松共享組織數據，服務和內容的功能。最重要的是，3scale API 管理平台為您提供了將各種加密，身份驗證和授權協議注入開發環境的機會。這使后端開發公司能夠為其目標用戶群提供適合他們的高度安全的移動應用程序體驗。
上面共享的所有 API 管理工具都是開源的，有望成為技術堆棧的有益補充。但是，為了確保您選擇最適合自己的業務應用程序的需求，我們接下來將介紹一些有關選擇 API 管理工具的技巧。
三、第三方API接口測試問題反饋文檔
- 原文地址：蒲公英不是夢：第三方API接口測試問題反饋文檔
站在第三方技術人員的角度去思考他們需要什么信息來輔助他們定位問題。
- 文檔說明解釋了為什么發這份文檔給他們
- 問題反饋記錄匯總記錄了所有可能存在問題的接口，因為有時候處理接口並不是一次性就能完善的，需要不斷的協調並進行修改，文檔的目的也是為了記錄我們處理接口問題的過程，做留檔。
- 接口地址用於說明我們測試這個接口的時候是用了這樣的url，可以讓第三方技術人員判斷我們是不是測錯接口了。
- 測試人員用於第三方技術人員直接於測試人員聯系並做出解釋。
- 測試時間記錄的測試發生的時間，方便他們查找日志文檔。
- 請求方式、請求頭部信息、請求參數可以讓第三方技術人員快速判斷測試人員是否按照接口要求進行測試，此外請求猜數也方便第三方技術人員自己測試進行問題復現。
- 響應狀態碼則直接告訴他們接口有沒有通。
- 實際返回值和預期返回值可以讓第三方技術人員進行對比我們想要得到什么樣的數據。
- 問題描述記錄我們發現什么問題以及希望解決什么樣的問題。
- 個人網站：https://www.lovebetterworld.com/
- 往后余生，只想分享一些干貨，分享一些工作，學習當中的筆記、總結，並幫助需要幫助的任何人，關注我，大家一起來學習吧！
