一、優秀的接口設計
在日常開發中，總會接觸到各種接口。前後端資料傳輸接口，第三方業務平台接口。一個平台的前後端資料傳輸接口一般都會在内網環境下通信，而且會使用安全架構，是以安全性可以得到很好的保護。這篇文章重點讨論一下提供給第三方平台的業務接口應當如何設計？我們應該考慮哪些問題？
主要從以上三個方面來設計一個安全的api接口。
安全性問題是一個接口必須要保證的規範。如果接口保證不了安全性，那麼你的接口相當于直接暴露在公網環境中任人蹂躏。
擷取token一般會涉及到幾個參數<code>appid</code>，<code>appkey</code>，<code>timestamp</code>，<code>nonce</code>，<code>sign</code>。我們通過以上幾個參數來擷取調用系統的憑證。
<code>appid</code>和<code>appkey</code>可以直接通過平台線上申請，也可以線下直接頒發。<code>appid</code>是全局唯一的，每個<code>appid</code>将對應一個客戶，<code>appkey</code>需要高度保密。
<code>timestamp</code>是時間戳，使用系統目前的unix時間戳。時間戳的目的就是為了減輕dos攻j。防止請求被攔截後一直嘗試請求接口。伺服器端設定時間戳閥值，如果請求時間戳和伺服器時間超過閥值，則響應失敗。
<code>nonce</code>是随機值。随機值主要是為了增加<code>sign</code>的多變性，也可以保護接口的幂等性，相鄰的兩次請求<code>nonce</code>不允許重複，如果重複則認為是重複送出，響應失敗。
<code>sign</code>是參數簽名，将<code>appkey</code>，<code>timestamp</code>，<code>nonce</code>拼接起來進行md5加密（當然使用其他方式進行不可逆加密也沒問題）。
<code>token</code>，使用參數<code>appid</code>，<code>timestamp</code>，<code>nonce</code>，<code>sign</code>來擷取token，作為系統調用的唯一憑證。<code>token</code>可以設定一次有效（這樣安全性更高），也可以設定時效性，這裡推薦設定時效性。如果一次有效的話這個接口的請求頻率可能會很高。<code>token</code>推薦加到請求頭上，這樣可以跟業務參數完全區分開來。
一般調用接口最常用的兩種方式就是get和post。兩者的差別也很明顯，get請求會将參數暴露在浏覽器url中，而且對長度也有限制。為了更高的安全性，所有接口都采用post方式請求。
ip白名單是指将接口的通路權限對部分ip進行開放。這樣就能避免其他ip進行通路***，設定ip白名單比較麻煩的一點就是當你的用戶端進行遷移後，就需要重新聯系服務提供者添加新的ip白名單。設定ip白名單的方式很多，除了傳統的防火牆之外，spring cloud alibaba提供的元件sentinel也支援白名單設定。為了降低api的複雜度，推薦使用防火牆規則進行白名單設定。
限流是為了更好的維護系統穩定性。使用redis進行接口調用次數統計，ip+接口位址作為key，通路次數作為value，每次請求value+1，設定過期時長來限制接口的調用頻率。
使用aop全局記錄請求日志，快速定位異常請求位置，排查問題原因。
在接口調用過程中，可能會涉及到訂單号等敏感資料，這類資料通常需要脫敏處理，最常用的方式就是加密。加密方式使用安全性比較高的<code>rsa</code>非對稱加密。非對稱加密算法有兩個密鑰，這兩個密鑰完全不同但又完全比對。隻有使用比對的一對公鑰和私鑰，才能完成對明文的加密和解密過程。
幂等性是指任意多次請求的執行結果和一次請求的執行結果所産生的影響相同。說的直白一點就是查詢操作無論查詢多少次都不會影響資料本身，是以查詢操作本身就是幂等的。但是新增操作，每執行一次資料庫就會發生變化，是以它是非幂等的。
幂等問題的解決有很多思路，這裡講一種比較嚴謹的。提供一個生成随機數的接口，随機數全局唯一。調用接口的時候帶入随機數。第一次調用，業務處理成功後，将随機數作為key，操作結果作為value，存入redis，同時設定過期時長。第二次調用，查詢redis，如果key存在，則證明是重複送出，直接傳回錯誤。
一套成熟的api文檔，一旦釋出是不允許随意修改接口的。這時候如果想新增或者修改接口，就需要加入版本控制，版本号可以是整數類型，也可以是浮點數類型。一般接口位址都會帶上版本号，http://ip:port//v1/list。
一個牛逼的api，還需要提供簡單明了的響應值，根據狀态碼就可以大概知道問題所在。我們采用http的狀态碼進行資料封裝，例如200表示請求成功，4xx表示用戶端錯誤，5xx表示伺服器内部發生錯誤。狀态碼設計參考如下：
分類
描述
1xx
資訊，伺服器收到請求，需要請求者繼續執行操作
2xx
成功
3xx
重定向，需要進一步的操作以完成請求
4xx
用戶端錯誤，請求包含文法錯誤或無法完成請求
5xx
服務端錯誤
狀态碼枚舉類：
為了友善給用戶端響應，響應資料會包含三個屬性，狀态碼（code）,資訊描述（message）,響應資料（data）。用戶端根據狀态碼及資訊描述可快速知道接口，如果狀态碼傳回成功，再開始處理資料。
響應結果定義及常用方法：
本篇文章從安全性、幂等性、資料規範等方面讨論了api設計規範。除此之外，一個好的api還少不了一個優秀的接口文檔。接口文檔的可讀性非常重要，雖然很多程式員都不喜歡寫文檔，而且不喜歡别人不寫文檔。為了不增加程式員的壓力，推薦使用swagger或其他接口管理工具，通過簡單配置，就可以在開發中測試接口的連通性，上線後也可以生成離線文檔用于管理api。
二、推薦些優秀的線上文檔生成工具
一些優秀的線上文檔、接口文檔的生成工具，需滿足如下條件：
必須是開源的
能夠實時生成線上文檔
支援全文搜尋
支援線上調試功能
界面優美
在此推薦一些滿足上述條件的線上接口文檔工具。
gitee位址：https://gitee.com/xiaoym/knife4j 開源協定：apache-2.0 license
推薦指數：★★★★ 示例位址：http://swagger-bootstrap-ui.xiaominfo.com/doc.html
knife4j是為java mvc架構內建swagger生成api文檔的增強解決方案，前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一樣小巧,輕量,并且功能強悍。
優點：基于swagger生成實時線上文檔，支援線上調試，全局參數、國際化、通路權限控制等，功能非常強大。
缺點：界面有一點點醜，需要依賴額外的jar包
個人建議：如果公司對ui要求不太高，可以使用這個文檔生成工具，比較功能還是比較強大的。
gitee位址：https://gitee.com/smart-doc-team/smart-doc 開源協定：apache-2.0 license
使用者：小米、科大訊飛、1加 推薦指數：★★★★
示例：
smart-doc是一個java restful api文檔生成工具，smart-doc颠覆了傳統類似swagger這種大量采用注解侵入來生成文檔的實作方法。smart-doc完全基于接口源碼分析來生成接口文檔，完全做到零注解侵入，隻需要按照java标準注釋的寫就能得到一個标準的markdown接口文檔。
優點：基于接口源碼分析生成接口文檔，零注解侵入，支援html、pdf、markdown格式的檔案導出。
缺點：需要引入額外的jar包，不支援線上調試
個人建議：如果實時生成文檔，但是又不想打一些額外的注解，比如：使用swagger時需要打上@api、@apimodel等注解，就可以使用這個。
github位址：https://github.com/redocly/redoc 開源協定：mit license
使用者：docker、redocly 推薦指數：★★★☆
redoc自己号稱是一個最好的線上文檔工具。它支援swagger接口資料，提供了多種生成文檔的方式，非常容易部署。使用redoc-cli能夠将您的文檔捆綁到零依賴的 html檔案中，響應式三面闆設計，具有菜單/滾動同步。
優點：非常友善生成文檔，三面闆設計
缺點：不支援中文搜尋，分為：普通版本 和 付費版本，普通版本不支援線上調試。另外ui互動個人感覺不适合國内大多數程式員的操作習慣。
個人建議：如果想快速搭建一個基于swagger的文檔，并且不要求線上調試功能，可以使用這個。
github位址：https://github.com/ymfe/yapi 開源協定：apache-2.0 license
使用者：騰訊、阿裡、百度、京東等大廠 推薦指數：★★★★★
yapi是去哪兒前端團隊自主研發并開源的，主要支援以下功能：
可視化接口管理
資料mock
自動化接口測試
資料導入（包括swagger、har、postman、json、指令行）
權限管理
支援本地化部署
支援插件
支援二次開發
優點：功能非常強大，支援權限管理、線上調試、接口自動化測試、插件開發等，bat等大廠等在使用，說明功能很好。
缺點：線上調試功能需要安裝插件，使用者體檢稍微有點不好，主要是為了解決跨域問題，可能有安全性問題。不過要解決這個問題，可以自己實作一個插件，應該不難。
個人建議：如果不考慮插件安全的安全性問題，這個線上文檔工具還是非常好用的，可以說是一個神器，筆者在這裡強烈推薦一下。
github位址：https://github.com/apidoc/apidoc 開源協定：mit license
推薦指數：★★★★☆
apidoc 是一個簡單的 restful api 文檔生成工具，它從代碼注釋中提取特定格式的内容生成文檔。支援諸如 go、java、c++、rust 等大部分開發語言，具體可使用 apidoc lang 指令行檢視所有的支援清單。
apidoc 擁有以下特點：
跨平台，linux、windows、macos 等都支援；
支援語言廣泛，即使是不支援，也很友善擴充；
支援多個不同語言的多個項目生成一份文檔；
輸出模闆可自定義；
根據文檔生成 mock 資料；
優點：基于代碼注釋生成線上文檔，對代碼的嵌入性比較小，支援多種語言，跨平台，也可自定義模闆。支援搜尋和線上調試功能。
缺點：需要在注釋中增加指定注解，如果代碼參數或類型有修改，需要同步修改注解相關内容，有一定的維護工作量。
個人建議：這種線上文檔生成工具提供了另外一種思路，swagger是在代碼中加注解，而apidoc是在注解中加資料，代碼嵌入性更小，推薦使用。
github位址：https://github.com/star7th/showdoc 開源協定：apache licence
使用者：超過10000+網際網路團隊正在使用 推薦指數：★★★★☆
showdoc就是一個非常适合it團隊的線上文檔分享工具，它可以加快團隊之間溝通的效率。
它都有些什麼功能：
響應式網頁設計，可将項目文檔分享到電腦或移動裝置檢視。同時也可以将項目導出成word檔案，以便離線浏覽。
權限管理，showdoc上的項目有公開項目和私密項目兩種。公開項目可供任何登入與非登入的使用者通路，而私密項目則需要輸入密碼驗證通路。密碼由項目建立者設定。
showdoc采用markdown編輯器，點選編輯器上方的按鈕可友善地插入api接口模闆和資料字典模闆。
showdoc為頁面提供曆史版本功能，你可以友善地把頁面恢複到之前的版本。
支援檔案導入，檔案可以是postman的json檔案、swagger的json檔案、showdoc的markdown壓縮包，系統會自動識别檔案類型。
優點：支援項目權限管理，多種格式檔案導入，全文搜尋等功能，使用起來還是非常友善的。并且既支援部署自己的伺服器，也支援線上托管兩種方式。
缺點：不支援線上調試功能
個人建議：如果不要求線上調試功能，這個線上文檔工具值得使用。
官網位址：http://www.apizza.net/
api跨域調試量身定制的chrome插件，本地，線上接口，都可以調。
雲端存儲，企業安全版支援本地資料中心。
一鍵分享，與團隊共享你的api文檔。
支援postman，swagger格式 導入postman/swagger json 生成文檔。
導出離線文檔，部署本地伺服器。
api mock 根據文檔自動生成傳回結果，提供獨立url友善前端測試。
支援多種文檔 http接口文檔，markdown說明文檔。
apizza接口文檔工具有一個很大不足的地方，那是apizza個人免費版有人數限制，所有超過8人的團隊如果想免費用，你是不用考慮apizza的。如果你看到有文章或公衆号上說apizza是免費的，那簡直是胡扯，他肯定沒用過。當然如果你不缺錢，可以付費開通企業版。我們團隊也是用了半年多apizza，後來由于人員增加，apizza裡又無法再新添加新成員，迫使我們不得不放棄apizza。
gitee位址：https://gitee.com/tencent/apijson
推薦指數：★★★★
apijson 是一種專為 api 而生的 json 網絡傳輸協定 以及 基于這套協定實作的 orm 庫。 為簡單的增删改查、複雜的查詢、簡單的事務操作 提供了完全自動化的萬能 api。
能大幅降低開發和溝通成本，簡化開發流程，縮短開發周期。
适合中小型前後端分離的項目，尤其是 baas、serverless、網際網路創業項目和企業自用項目。
通過萬能的 api，前端可以定制任何資料、任何結構。
大部分 http 請求後端再也不用寫接口了，更不用寫文檔了。
前端再也不用和後端溝通接口或文檔問題了。再也不會被文檔各種錯誤坑了。
後端再也不用為了相容舊接口寫新版接口和文檔了。再也不會被前端随時随地沒完沒了地煩了。
不用再向後端催接口、求文檔
資料和結構完全定制，要啥有啥
看請求知結果，所求即所得
可一次擷取任何資料、任何結構
能去除重複資料，節省流量提高速度
提供通用接口，大部分 api 不用再寫
自動生成文檔，不用再編寫和維護
自動校驗權限、自動管理版本、自動防 sql 注入
開放 api 無需劃分版本，始終保持相容
支援增删改查、複雜查詢、跨庫連表、遠端函數等
由于 api 在軟體開發過程中如此關鍵，那麼對 api 的管理就顯得格外重要。通過 api 管理工具和平台能夠大大簡化 api 管理的難度和複雜度。下面列舉了一些頂級 api 管理工具和平台，可供您參考。
api umbrella 是用于管理 api 和微服務的頂級開源工具之一。通過為不同的域授予不同的管理者權限，它可以使多個團隊使用同一個 umbrella。該平台還提供速率限制，api 密鑰，緩存，實時分析和 web 管理界面等功能。
gravitee.io 是一個用于管理 api 的開源平台，這個工具是靈活的并且是輕量級的。它具有開箱即用的功能，例如速率限制，ip 過濾，跨域資源共享，即插即用選項，具有基于 oauth2 和 json web 令牌政策的開發者門戶，負載平衡等。
但是，此 api 管理工具的主要功能是能夠生成細粒度的報告以了解 api 的資料是如何使用的。
apiman.io 是由 red hat 引入的一個頂級 api 管理平台，這個平台在 github 中可以找到，為後端開發人員提供了很多便利。這包括：
快速運作 具有可分離政策引擎的基于政策的治理 異步功能 增強的結算和分析選項 rest api 可用性的管理 限速，還有其他
wso2 api manager 是一個完整的生命周期 api 管理平台，可以随時随地運作。可以在企業内部和私有雲上執行 api 的分發和部署。除此之外，它還提供了一些其他的便利。其中一些是：
高度定制化 管理政策易用， 為 soap 或 restful api 設計和原型的可能性， 更好的通路控制和貨币化設施等
kong 是一種廣泛采用的開源微服務 api 工具，它使開發人員能夠快速，輕松，安全地管理一切。它的企業版帶有許多特性和功能，例如：
開源插件的可用性 一鍵式操作 通用語言基礎架構功能 強大的可視化監控功能 正常軟體運作狀況檢查 oauth2.0 權限，以及 更廣泛的社群支援
tyk.io 用 go 程式設計語言編寫，也是公認的開源 api 網關。
它帶有開發者門戶，詳細的文檔，用于 api 分析的儀表闆，api 的速率限制，身份驗證以及各種其他此類規範，可幫助組織專注于微服務環境和容器化。但是，其基于商業的服務僅适用于付費版本。
fusio 是另一個開源 api 管理工具，開發人員可以使用它從不同的資料類型建立和維護 rest api。它具有高效的生命周期管理功能，例如用于管理控制的後端儀表闆，詳細的文檔，用于傳入請求的 json 驗證以及滿足使用者權限的範圍處理。
而且，此 apim 平台會自動生成 oai 和 raml 要求，并根據定義的架建構立自定義的用戶端 sdk。
apigility 由 zend 架構設計和維護，是考慮用于 api 管理的下一個開源架構。該平台建立并展示其代碼的 json 表示形式。它還為他們提供了不同的版本控制選項，以及通過 oauth2 進行身份驗證的簡便性和包含 api 藍圖的文檔。
api 接口管理，這 15 種開源工具助你管理 api apigility
swaggerhub 被 40 多個組織考慮用于管理 api，它也是最好的開源 api 管理工具之一。
該平台為後端開發領域的設計人員和開發人員提供了廣泛的選擇。它為他們提供了強大而直覺的編輯器，可在保持設計一緻性的同時提供更高的效率和速度。
此外，它還提供了智能錯誤回報，文法自動完成和多種樣式驗證器可用性的機會。
在 exicon 的支援下，api axle 是另一種開源，簡單且輕量級的代理，為開發人員提供了很多好處，例如：實時分析 強大的身份驗證， 記錄 api 流量以進行統計和報告， 易于建立和管理 api 密鑰，以及 支援 rest api 設計以及 go，php 和 node.js 庫的使用。
該 api 管理工具使開發人員可以使用 200 多種軟體和中間件模式來為混合雲建構可移植且相容的應用程式。它還提供各種預先建構的服務和強大的機制，用于調節 api 通路，管理多個 api 版本，維持速率限制以及跟蹤性能名額和所涉及的每個 api 的分析。
repose 是一個開源的 restful 中間件平台，在不斷變化的 api 市場中起着舉足輕重的作用。該平台為組織提供了各種 api 處理功能，包括身份驗證，api 驗證，速率限制和 http 請求日志記錄。
該 api 管理平台旨在提供格式正确且經過驗證的信任下遊請求的下遊服務。而且，它本質上具有高度可擴充性和可擴充性，這意味着開發人員可以根據不斷增長的需求輕松地使用它。
snaplogic 是一個不錯的內建平台即服務（ipaas）工具，可幫助組織擷取，維持和增長其客戶群。其具備的特征是：
它是快速的，多點的，并具有可靈活滿足面向批處理和實時應用程式資料內建需求的選項。它具有可擴充的體系結構，其運作方式類似于 web 伺服器，但也提供了擁抱多功能性的選項。它還帶有創新的資料流解決方案，鼓勵組織将著名的 saas 應用程式如 sugarcrm 和 salesforce）添加到其傳統流程中。
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
最後但并非最不重要的一點是，3scale 是此 api 管理工具清單的補充。
api 管理工具由 red hat 擁有，它使大小型企業都可以通過以下功能輕松安全地管理其 api：
它采用了一個分布式的雲層來集中 api 程式的控制。這樣可以更輕松地控制分析，可通路性，開發人員工作流程，獲利等。
由于它托管在分布式雲托管層上，是以具有高度的靈活性和可擴充性。
3scale api 的 openshift 內建功能使您能夠以自動化且封閉的方式運作高性能應用程式。這個完整的生命周期 api 管理平台使開發人員可以随時計劃，設計，應用，釋出，管理，分析，優化和淘汰您的 api，以提供卓越的體驗。
它具有通過 web 或移動應用程式輕松共享組織資料，服務和内容的功能。最重要的是，3scale api 管理平台為您提供了将各種加密，身份驗證和授權協定注入開發環境的機會。這使後端開發公司能夠為其目标使用者群提供适合他們的高度安全的移動應用程式體驗。
上面共享的所有 api 管理工具都是開源的，有望成為技術堆棧的有益補充。但是，為了確定您選擇最适合自己的業務應用程式的需求，我們接下來将介紹一些有關選擇 api 管理工具的技巧。
三、第三方api接口測試問題回報文檔
原文位址：蒲公英不是夢：第三方api接口測試問題回報文檔
站在第三方技術人員的角度去思考他們需要什麼資訊來輔助他們定位問題。
文檔說明解釋了為什麼發這份文檔給他們
問題回報記錄彙總記錄了所有可能存在問題的接口，因為有時候處理接口并不是一次性就能完善的，需要不斷的協調并進行修改，文檔的目的也是為了記錄我們處理接口問題的過程，做留檔。
接口位址用于說明我們測試這個接口的時候是用了這樣的url，可以讓第三方技術人員判斷我們是不是測錯接口了。
測試人員用于第三方技術人員直接于測試人員聯系并做出解釋。
測試時間記錄的測試發生的時間，友善他們查找日志文檔。
請求方式、請求頭部資訊、請求參數可以讓第三方技術人員快速判斷測試人員是否按照接口要求進行測試，此外請求猜數也友善第三方技術人員自己測試進行問題複現。
響應狀态碼則直接告訴他們接口有沒有通。
實際傳回值和預期傳回值可以讓第三方技術人員進行對比我們想要得到什麼樣的資料。
問題描述記錄我們發現什麼問題以及希望解決什麼樣的問題。
個人網站：https://www.lovebetterworld.com/
往後餘生，隻想分享一些幹貨，分享一些工作，學習當中的筆記、總結，并幫助需要幫助的任何人，關注我，大家一起來學習吧！