瞧瞧别人家的 API 接口，那叫一個優雅

前言

在實際工作中，我們需要經常跟第三方平台打交道，可能會對接第三方平台API接口，或者提供API接口給第三方平台調用。

那麼問題來了，如何設計一個優雅的API接口，能夠滿足：安全性、可重複調用、穩定性、好定位問題等多方面需求？

今天跟大家一起聊聊設計API接口時，需要注意的一些地方，希望對你會有所幫助。

1. 簽名

為了防止API接口中的資料被篡改，很多時候我們需要對API接口做簽名。

接口請求方将請求參數 + 時間戳 + 密鑰拼接成一個字元串，然後通過md5等hash算法，生成一個前面sign。

然後在請求參數或者請求頭中，增加sign參數，傳遞給API接口。

API接口的網關服務，擷取到該sign值，然後用相同的請求參數 + 時間戳 + 密鑰拼接成一個字元串，用相同的m5算法生成另外一個sign，對比兩個sign值是否相等。

如果兩個sign相等，則認為是有效請求，API接口的網關服務會将給請求轉發給相應的業務系統。

如果兩個sign不相等，則API接口的網關服務會直接傳回簽名錯誤。

問題來了：簽名中為什麼要加時間戳？

答：為了安全性考慮，防止同一次請求被反複利用，增加了密鑰沒破解的可能性，我們必須要對每次請求都設定一個合理的過期時間，比如：15分鐘。

這樣一次請求，在15分鐘之内是有效的，超過15分鐘，API接口的網關服務會傳回超過有效期的異常提示。

目前生成簽名中的密鑰有兩種形式：

一種是雙方約定一個固定值privateKey。

另一種是API接口提供方給出AK/SK兩個值，雙方約定用SK作為簽名中的密鑰。AK接口調用方作為header中的accessKey傳遞給API接口提供方，這樣API接口提供方可以根據AK擷取到SK，而生成新的sgin。

2. 加密

有些時候，我們的API接口直接傳遞的非常重要的資料，比如：使用者的銀行卡号、轉賬金額、使用者身份證等，如果将這些參數，直接明文，暴露到公網上是非常危險的事情。

由此，我們需要對資料進行加密。

目前使用比較多的是用BASE64加解密。

我們可以将所有的資料，安裝一定的規律拼接成一個大的字元串，然後在加一個密鑰，拼接到一起。

然後使用JDK1.8之後的Base64工具類處理，效果如下：

【加密前的資料】www.baidu.com
【加密後的資料】d3d3LmJhaWR1LmNvbQ==
           

為了安全性，使用Base64可以加密多次。

API接口的調用方在傳遞參數時，body中隻有一個參數data，它就是base64之後的加密資料。

API接口的網關服務，在接收到data資料後，根據雙方事先預定的密鑰、加密算法、加密次數等，進行解密，并且反序列化出參數資料。

3. ip白名單

為了進一步加強API接口的安全性，防止接口的簽名或者加密被破解了，攻擊者可以在自己的伺服器上請求該接口。

需求限制請求ip，增加ip白名單。

隻有在白名單中的ip位址，才能成功請求API接口，否則直接傳回無通路權限。

ip白名單也可以加在API網關服務上。

但也要防止公司的内部應用伺服器被攻破，這種情況也可以從内部伺服器上發起API接口的請求。

這時候就需要增加web防火牆了，比如：ModSecurity等。

4. 限流

如果你的API接口被第三方平台調用了，這就意味着着，調用頻率是沒法控制的。

第三方平台調用你的API接口時，如果并發量一下子太高，可能會導緻你的API服務不可用，接口直接挂掉。

由此，必須要對API接口做限流。

限流方法有三種：

1. 對請求ip做限流：比如同一個ip，在一分鐘内，對API接口總的請求次數，不能超過10000次。
2. 對請求接口做限流：比如同一個ip，在一分鐘内，對指定的API接口，請求次數不能超過2000次。
3. 對請求使用者做限流：比如同一個AK/SK使用者，在一分鐘内，對API接口總的請求次數，不能超過10000次。

我們在實際工作中，可以通過nginx，redis或者gateway實作限流的功能。

5. 參數校驗

我們需要對API接口做參數校驗，比如：校驗必填字段是否為空，校驗字段類型，校驗字段長度，校驗枚舉值等等。

這樣做可以攔截一些無效的請求。

比如在新增資料時，字段長度超過了資料字段的最大長度，資料庫會直接報錯。

但這種異常的請求，我們完全可以在API接口的前期進行識别，沒有必要走到資料庫儲存資料那一步，浪費系統資源。

有些金額字段，本來是正數，但如果使用者傳入了負數，萬一接口沒做校驗，可能會導緻一些沒必要的損失。

還有些狀态字段，如果不做校驗，使用者如果傳入了系統中不存在的枚舉值，就會導緻儲存的資料異常。

由此可見，做參數校驗是非常有必要的。

在Java中校驗資料使用最多的是hiberate的Validator架構，它裡面包含了@Null、@NotEmpty、@Size、@Max、@Min等注解。

用它們校驗資料非常友善。

當然有些日期字段和枚舉字段，可能需要通過自定義注解的方式實作參數校驗。

6. 統一傳回值

我之前調用過别人的API接口，正常傳回資料是一種json格式，比如：

{
    "code":0,
    "message":null,
    "data":[{"id":123,"name":"abc"}]
},
           

簽名錯誤傳回的json格式：

{
    "code":1001,
    "message":"簽名錯誤",
    "data":null
}
           

沒有資料權限傳回的json格式：

{
    "rt":10,
    "errorMgt":"沒有權限",
    "result":null
}
           

這種是比較坑的做法，傳回值中有多種不同格式的傳回資料，這樣會導緻對接方很難了解。

出現這種情況，可能是API網關定義了一直傳回值結構，業務系統定義了另外一種傳回值結構。如果是網關異常，則傳回網關定義的傳回值結構，如果是業務系統異常，則傳回業務系統的傳回值結構。

但這樣會導緻API接口出現不同的異常時，傳回不同的傳回值結構，非常不利于接口的維護。

其實這個問題我們可以在設計API網關時解決。

業務系統在出現異常時，抛出業務異常的RuntimeException，其中有個message字段定義異常資訊。

所有的API接口都必須經過API網關，API網關捕獲該業務異常，然後轉換成統一的異常結構傳回，這樣能統一傳回值結構。

7. 統一封裝異常

我們的API接口需要對異常進行統一處理。

不知道你有沒有遇到過這種場景：有時候在API接口中，需要通路資料庫，但表不存在，或者sql語句異常，就會直接把sql資訊在API接口中直接傳回。

傳回值中包含了異常堆棧資訊、資料庫資訊、錯誤代碼和行數等資訊。

如果直接把這些内容暴露給第三方平台，是很危險的事情。

有些不法分子，利用接口傳回值中的這些資訊，有可能會進行sql注入或者直接脫庫，而對我們系統造成一定的損失。

是以非常有必要對API接口中的異常做統一處理，把異常轉換成這樣：

{
    "code":500,
    "message":"伺服器内部錯誤",
    "data":null
}
           

傳回碼code是500，傳回資訊message是伺服器内部異常。

這樣第三方平台就知道是API接口出現了内部問題，但不知道具體原因，他們可以找我們排查問題。

我們可以在内部的日志檔案中，把堆棧資訊、資料庫資訊、錯誤代碼行數等資訊，列印出來。

我們可以在gateway中對異常進行攔截，做統一封裝，然後給第三方平台的是處理後沒有敏感資訊的錯誤資訊。

8. 請求日志

在第三方平台請求你的API接口時，接口的請求日志非常重要，通過它可以快速的分析和定位問題。

我們需要把API接口的請求url、請求參數、請求頭、請求方式、響應資料和響應時間等，記錄到日志檔案中。

最好有traceId，可以通過它串聯整個請求的日志，過濾多餘的日志。

當然有些時候，請求日志不光是你們公司開發人員需要檢視，第三方平台的使用者也需要能檢視接口的請求日志。

這時就需要把日志落地到資料庫，比如：mongodb或者elastic search，然後做一個UI頁面，給第三方平台的使用者開通檢視權限。這樣他們就能在外網檢視請求日志了，他們自己也能定位一部分問題。

9. 幂等設計

第三方平台極有可能在極短的時間内，請求我們接口多次，比如：在1秒内請求兩次。有可能是他們業務系統有bug，或者在做接口調用失敗重試，是以我們的API接口需要做幂等設計。

也就是說要支援在極短的時間内，第三方平台用相同的參數請求API接口多次，第一次請求資料庫會新增資料，但第二次請求以後就不會新增資料，但也會傳回成功。

這樣做的目的是不會産生錯誤資料。

我們在日常工作中，可以通過在資料庫中增加唯一索引，或者在redis儲存requestId和請求參來保證接口幂等性。

10. 限制記錄條數

對于對我提供的批量接口，一定要限制請求的記錄條數。

如果請求的資料太多，很容易造成API接口逾時等問題，讓API接口變得不穩定。

通常情況下，建議一次請求中的參數，最多支援傳入500條記錄。

如果使用者傳入多餘500條記錄，則接口直接給出提示。

建議這個參數做成可配置的，并且要事先跟第三方平台協商好，避免上線後産生不必要的問題。

11. 壓測

上線前我們務必要對API接口做一下壓力測試，知道各個接口的qps情況。

以便于我們能夠更好的預估，需要部署多少伺服器節點，對于API接口的穩定性至關重要。

之前雖說對API接口做了限流，但是實際上API接口是否能夠達到限制的閥值，這是一個問号，如果不做壓力測試，是有很大風險的。

比如：你API接口限流1秒隻允許50次請求，但實際API接口隻能處理30次請求，這樣你的API接口也會處理不過來。

我們在工作中可以用jmeter或者apache benc對API接口做壓力測試。

12. 異步處理

一般的API接口的邏輯都是同步處理的，請求完之後立刻傳回結果。

但有時候，我們的API接口裡面的業務邏輯非常複雜，特别是有些批量接口，如果同步處理業務，耗時會非常長。

這種情況下，為了提升API接口的性能，我們可以改成異步處理。

在API接口中可以發送一條mq消息，然後直接傳回成功。之後，有個專門的mq消費者去異步消費該消息，做業務邏輯處理。

直接異步處理的接口，第三方平台有兩種方式擷取到。

第一種方式是：我們回調第三方平台的接口，告知他們API接口的處理結果，很多支付接口就是這麼玩的。

第二種方式是：第三方平台通過輪詢調用我們另外一個查詢狀态的API接口，每隔一段時間查詢一次狀态，傳入的參數是之前的那個API接口中的id集合。

13. 資料脫敏

有時候第三方平台調用我們API接口時，擷取的資料中有一部分是敏感資料，比如：使用者手機号、銀行卡号等等。

這樣資訊如果通過API接口直接保留到外網，是非常不安全的，很容易造成使用者隐私資料洩露的問題。

這就需要對部分資料做資料脫敏了。

我們可以在傳回的資料中，部分内容用星号代替。

已使用者手機号為例：182****887。

這樣即使資料被洩露了，也隻洩露了一部分，不法分子拿到這份資料也沒啥用。

14. 完整的接口文檔

說實話，一份完整的API接口文檔，在雙方做接口對接時，可以減少很多溝通成本，讓對方少走很多彎路。

接口文檔中需要包含如下資訊：

1. 接口位址
2. 請求方式，比如：post或get
3. 請求參數和字段介紹
4. 傳回值和字段介紹
5. 傳回碼和錯誤資訊
6. 加密或簽名示例
7. 完整的請求demo
8. 額外的說明，比如：開通ip白名單。

接口文檔中最好能夠統一接口和字段名稱的命名風格，比如都用駝峰辨別命名。

接口位址中可以加一個版本号v1，比如：v1/query/getCategory，這樣以後接口有很大的變動，可以非常友善更新版本。

統一字段的類型和長度，比如：id字段用Long類型，長度規定20。status字段用int類型，長度固定2等。

統一時間格式字段，比如：time用String類型，格式為：yyyy-MM-dd HH:mm:ss。

接口文檔中寫明AK/SK和域名，找某某單獨提供等。

來源：蘇三說技術

作者：蘇三呀