在實際工作中，我們需要經常跟第三方平臺打交道，可能會對接第三方平臺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接口做限流。

限流方法有三種：

對請求ip做限流：比如同一個ip，在一分鐘內，對API接口總的請求次數，不能超過10000次。
對請求接口做限流：比如同一個ip，在一分鐘內，對指定的API接口，請求次數不能超過2000次。
對請求用戶做限流：比如同一個AK/SK用戶，在一分鐘內，對API接口總的請求次數，不能超過10000次。
我們在實際工作中，可以通過nginx，redis或者gateway實現限流的功能。

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

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

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

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

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

還有些狀態字段，如果不做校驗，用戶如果傳入了系統中不存在的枚舉值，就會導致保存的數據異常。

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

在Java中校驗數據使用最多的是hiberate的Validator框架，它里面包含了@Null、@NotEmpty、@Size、@Max、@Min等注解。

用它們校驗數據非常方便。

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

不知道你有沒有遇到過這種場景：有時候在API接口中，需要訪問數據庫，但表不存在，或者sql語句異常，就會直接把sql信息在API接口中直接返回。

返回值中包含了異常堆棧信息、數據庫信息、錯誤代碼和行數等信息。

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

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

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

當然有些時候，請求日志不光是你們公司開發人員需要查看，第三方平臺的用戶也需要能查看接口的請求日志。