前言

今天延續(xù)設(shè)計(jì)的話(huà)題，給大家總結(jié)了接口設(shè)計(jì)的18條軍規(guī)，希望對(duì)你會(huì)有所幫助。

1. 簽名

為了防止API接口中的數(shù)據(jù)被篡改，很多時(shí)候我們需要對(duì)API接口做簽名。

接口請(qǐng)求方將請(qǐng)求參數(shù) + 時(shí)間戳 + 密鑰拼接成一個(gè)字符串，然后通過(guò)md5等hash算法，生成一個(gè)前面sign。

然后在請(qǐng)求參數(shù)或者請(qǐng)求頭中，增加sign參數(shù)，傳遞給API接口。

API接口的網(wǎng)關(guān)服務(wù)，獲取到該sign值，然后用相同的請(qǐng)求參數(shù) + 時(shí)間戳 + 密鑰拼接成一個(gè)字符串，用相同的m5算法生成另外一個(gè)sign，對(duì)比兩個(gè)sign值是否相等。

如果兩個(gè)sign相等，則認(rèn)為是有效請(qǐng)求，API接口的網(wǎng)關(guān)服務(wù)會(huì)將給請(qǐng)求轉(zhuǎn)發(fā)給相應(yīng)的業(yè)務(wù)系統(tǒng)。

如果兩個(gè)sign不相等，則API接口的網(wǎng)關(guān)服務(wù)會(huì)直接返回簽名錯(cuò)誤。

問(wèn)題來(lái)了：簽名中為什么要加時(shí)間戳？

答：為了安全性考慮，防止同一次請(qǐng)求被反復(fù)利用，增加了密鑰沒(méi)破解的可能性，我們必須要對(duì)每次請(qǐng)求都設(shè)置一個(gè)合理的過(guò)期時(shí)間，比如：15分鐘。

這樣一次請(qǐng)求，在15分鐘之內(nèi)是有效的，超過(guò)15分鐘，API接口的網(wǎng)關(guān)服務(wù)會(huì)返回超過(guò)有效期的異常提示。

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

一種是雙方約定一個(gè)固定值privateKey。

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

2. 加密

有些時(shí)候，我們的API接口直接傳遞的非常重要的數(shù)據(jù)，比如：用戶(hù)的登錄密碼、銀行卡號(hào)、轉(zhuǎn)賬金額、用戶(hù)身份證等，如果將這些參數(shù)，直接明文，暴露到公網(wǎng)上是非常危險(xiǎn)的事情。

由此，我們需要對(duì)數(shù)據(jù)進(jìn)行加密。

比如：用戶(hù)注冊(cè)接口，用戶(hù)輸入了用戶(hù)名和密碼之后，需要將密碼加密。

我們可以使用AES對(duì)稱(chēng)加密算法。

在前端使用公鑰對(duì)用戶(hù)密碼加密。

然后注冊(cè)接口中，可以使用密鑰解密，做一些業(yè)務(wù)需求校驗(yàn)。然后再換成其他的加密方式加密，保存到數(shù)據(jù)庫(kù)當(dāng)中。

3. ip白名單

為了進(jìn)一步加強(qiáng)API接口的安全性，防止接口的簽名或者加密被破解了，攻擊者可以在自己的服務(wù)器上請(qǐng)求該接口。

需求限制請(qǐng)求ip，增加ip白名單。

只有在白名單中的ip地址，才能成功請(qǐng)求API接口，否則直接返回?zé)o訪(fǎng)問(wèn)權(quán)限。

ip白名單也可以加在API網(wǎng)關(guān)服務(wù)上。

但也要防止公司的內(nèi)部應(yīng)用服務(wù)器被攻破，這種情況也可以從內(nèi)部服務(wù)器上發(fā)起API接口的請(qǐng)求。

這時(shí)候就需要增加web防火墻了，比如：ModSecurity等。

4. 限流

如果你的API接口被第三方平臺(tái)調(diào)用了，這就意味著著，調(diào)用頻率是沒(méi)法控制的。

第三方平臺(tái)調(diào)用你的API接口時(shí)，如果并發(fā)量一下子太高，可能會(huì)導(dǎo)致你的API服務(wù)不可用，接口直接掛掉。

由此，必須要對(duì)API接口做限流。

限流方法有三種：

• 對(duì)請(qǐng)求ip做限流：比如同一個(gè)ip，在一分鐘內(nèi)，對(duì)API接口總的請(qǐng)求次數(shù)，不能超過(guò)10000次。
• 對(duì)請(qǐng)求接口做限流：比如同一個(gè)ip，在一分鐘內(nèi)，對(duì)指定的API接口，請(qǐng)求次數(shù)不能超過(guò)2000次。
• 對(duì)請(qǐng)求用戶(hù)做限流：比如同一個(gè)AK/SK用戶(hù)，在一分鐘內(nèi)，對(duì)API接口總的請(qǐng)求次數(shù)，不能超過(guò)10000次。

我們?cè)趯?shí)際工作中，可以通過(guò)nginx，redis或者gateway實(shí)現(xiàn)限流的功能。

5. 參數(shù)校驗(yàn)

我們需要對(duì)API接口做參數(shù)校驗(yàn)，比如：校驗(yàn)必填字段是否為空，校驗(yàn)字段類(lèi)型，校驗(yàn)字段長(zhǎng)度，校驗(yàn)枚舉值等等。

這樣做可以攔截一些無(wú)效的請(qǐng)求。

比如在新增數(shù)據(jù)時(shí)，字段長(zhǎng)度超過(guò)了數(shù)據(jù)字段的最大長(zhǎng)度，數(shù)據(jù)庫(kù)會(huì)直接報(bào)錯(cuò)。

但這種異常的請(qǐng)求，我們完全可以在API接口的前期進(jìn)行識(shí)別，沒(méi)有必要走到數(shù)據(jù)庫(kù)保存數(shù)據(jù)那一步，浪費(fèi)系統(tǒng)資源。

有些金額字段，本來(lái)是正數(shù)，但如果用戶(hù)傳入了負(fù)數(shù)，萬(wàn)一接口沒(méi)做校驗(yàn)，可能會(huì)導(dǎo)致一些沒(méi)必要的損失。

還有些狀態(tài)字段，如果不做校驗(yàn)，用戶(hù)如果傳入了系統(tǒng)中不存在的枚舉值，就會(huì)導(dǎo)致保存的數(shù)據(jù)異常。

由此可見(jiàn)，做參數(shù)校驗(yàn)是非常有必要的。

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

用它們校驗(yàn)數(shù)據(jù)非常方便。

當(dāng)然有些日期字段和枚舉字段，可能需要通過(guò)自定義注解的方式實(shí)現(xiàn)參數(shù)校驗(yàn)。

6. 統(tǒng)一返回值

我之前調(diào)用過(guò)別人的API接口，正常返回?cái)?shù)據(jù)是一種json格式，比如：

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

簽名錯(cuò)誤返回的json格式：

{
    "code":1001,
    "message":"簽名錯(cuò)誤",
    "data":null
}

沒(méi)有數(shù)據(jù)權(quán)限返回的json格式：

{
    "rt":10,
    "errorMgt":"沒(méi)有權(quán)限",
    "result":null
}

這種是比較坑的做法，返回值中有多種不同格式的返回?cái)?shù)據(jù)，這樣會(huì)導(dǎo)致對(duì)接方很難理解。

出現(xiàn)這種情況，可能是API網(wǎng)關(guān)定義了一直返回值結(jié)構(gòu)，業(yè)務(wù)系統(tǒng)定義了另外一種返回值結(jié)構(gòu)。如果是網(wǎng)關(guān)異常，則返回網(wǎng)關(guān)定義的返回值結(jié)構(gòu)，如果是業(yè)務(wù)系統(tǒng)異常，則返回業(yè)務(wù)系統(tǒng)的返回值結(jié)構(gòu)。

但這樣會(huì)導(dǎo)致API接口出現(xiàn)不同的異常時(shí)，返回不同的返回值結(jié)構(gòu)，非常不利于接口的維護(hù)。

其實(shí)這個(gè)問(wèn)題我們可以在設(shè)計(jì)API網(wǎng)關(guān)時(shí)解決。

業(yè)務(wù)系統(tǒng)在出現(xiàn)異常時(shí)，拋出業(yè)務(wù)異常的RuntimeException，其中有個(gè)message字段定義異常信息。

所有的API接口都必須經(jīng)過(guò)API網(wǎng)關(guān)，API網(wǎng)關(guān)捕獲該業(yè)務(wù)異常，然后轉(zhuǎn)換成統(tǒng)一的異常結(jié)構(gòu)返回，這樣能統(tǒng)一返回值結(jié)構(gòu)。

7. 統(tǒng)一封裝異常

我們的API接口需要對(duì)異常進(jìn)行統(tǒng)一處理。

不知道你有沒(méi)有遇到過(guò)這種場(chǎng)景：有時(shí)候在API接口中，需要訪(fǎng)問(wèn)數(shù)據(jù)庫(kù)，但表不存在，或者sql語(yǔ)句異常，就會(huì)直接把sql信息在API接口中直接返回。

返回值中包含了異常堆棧信息、數(shù)據(jù)庫(kù)信息、錯(cuò)誤代碼和行數(shù)等信息。

如果直接把這些內(nèi)容暴露給第三方平臺(tái)，是很危險(xiǎn)的事情。

有些不法分子，利用接口返回值中的這些信息，有可能會(huì)進(jìn)行sql注入或者直接脫庫(kù)，而對(duì)我們系統(tǒng)造成一定的損失。

因此非常有必要對(duì)API接口中的異常做統(tǒng)一處理，把異常轉(zhuǎn)換成這樣：

{
    "code":500,
    "message":"服務(wù)器內(nèi)部錯(cuò)誤",
    "data":null
}

返回碼code是500，返回信息message是服務(wù)器內(nèi)部異常。

這樣第三方平臺(tái)就知道是API接口出現(xiàn)了內(nèi)部問(wèn)題，但不知道具體原因，他們可以找我們排查問(wèn)題。

我們可以在內(nèi)部的日志文件中，把堆棧信息、數(shù)據(jù)庫(kù)信息、錯(cuò)誤代碼行數(shù)等信息，打印出來(lái)。

我們可以在gateway中對(duì)異常進(jìn)行攔截，做統(tǒng)一封裝，然后給第三方平臺(tái)的是處理后沒(méi)有敏感信息的錯(cuò)誤信息。

8. 請(qǐng)求日志

在第三方平臺(tái)請(qǐng)求你的API接口時(shí)，接口的請(qǐng)求日志非常重要，通過(guò)它可以快速的分析和定位問(wèn)題。

我們需要把API接口的請(qǐng)求url、請(qǐng)求參數(shù)、請(qǐng)求頭、請(qǐng)求方式、響應(yīng)數(shù)據(jù)和響應(yīng)時(shí)間等，記錄到日志文件中。

最好有traceId，可以通過(guò)它串聯(lián)整個(gè)請(qǐng)求的日志，過(guò)濾多余的日志。

當(dāng)然有些時(shí)候，請(qǐng)求日志不光是你們公司開(kāi)發(fā)人員需要查看，第三方平臺(tái)的用戶(hù)也需要能查看接口的請(qǐng)求日志。

這時(shí)就需要把日志落地到數(shù)據(jù)庫(kù)，比如：mongodb或者elastic search，然后做一個(gè)UI頁(yè)面，給第三方平臺(tái)的用戶(hù)開(kāi)通查看權(quán)限。這樣他們就能在外網(wǎng)查看請(qǐng)求日志了，他們自己也能定位一部分問(wèn)題。

9. 冪等設(shè)計(jì)

第三方平臺(tái)極有可能在極短的時(shí)間內(nèi)，請(qǐng)求我們接口多次，比如：在1秒內(nèi)請(qǐng)求兩次。有可能是他們業(yè)務(wù)系統(tǒng)有bug，或者在做接口調(diào)用失敗重試，因此我們的API接口需要做冪等設(shè)計(jì)。

也就是說(shuō)要支持在極短的時(shí)間內(nèi)，第三方平臺(tái)用相同的參數(shù)請(qǐng)求API接口多次，第一次請(qǐng)求數(shù)據(jù)庫(kù)會(huì)新增數(shù)據(jù)，但第二次請(qǐng)求以后就不會(huì)新增數(shù)據(jù)，但也會(huì)返回成功。

這樣做的目的是不會(huì)產(chǎn)生錯(cuò)誤數(shù)據(jù)。

我們?cè)谌粘９ぷ髦?，可以通過(guò)在數(shù)據(jù)庫(kù)中增加唯一索引，或者在redis保存requestId和請(qǐng)求參來(lái)保證接口冪等性。

10. 限制記錄條數(shù)

對(duì)于對(duì)我提供的批量接口，一定要限制請(qǐng)求的記錄條數(shù)。

如果請(qǐng)求的數(shù)據(jù)太多，很容易造成API接口超時(shí)等問(wèn)題，讓API接口變得不穩(wěn)定。

通常情況下，建議一次請(qǐng)求中的參數(shù)，最多支持傳入500條記錄。

如果用戶(hù)傳入多余500條記錄，則接口直接給出提示。

建議這個(gè)參數(shù)做成可配置的，并且要事先跟第三方平臺(tái)協(xié)商好，避免上線(xiàn)后產(chǎn)生不必要的問(wèn)題。

對(duì)于一次性查詢(xún)的數(shù)據(jù)太多的情況，我們需要將接口設(shè)計(jì)成分頁(yè)查詢(xún)返回的。

11. 壓測(cè)

上線(xiàn)前我們務(wù)必要對(duì)API接口做一下壓力測(cè)試，知道各個(gè)接口的qps情況。

以便于我們能夠更好的預(yù)估，需要部署多少服務(wù)器節(jié)點(diǎn)，對(duì)于API接口的穩(wěn)定性至關(guān)重要。

之前雖說(shuō)對(duì)API接口做了限流，但是實(shí)際上API接口是否能夠達(dá)到限制的閥值，這是一個(gè)問(wèn)號(hào)，如果不做壓力測(cè)試，是有很大風(fēng)險(xiǎn)的。

比如：你API接口限流1秒只允許50次請(qǐng)求，但實(shí)際API接口只能處理30次請(qǐng)求，這樣你的API接口也會(huì)處理不過(guò)來(lái)。

我們?cè)诠ぷ髦锌梢杂胘meter或者apache benc對(duì)API接口做壓力測(cè)試。

12. 異步處理

一般的API接口的邏輯都是同步處理的，請(qǐng)求完之后立刻返回結(jié)果。

但有時(shí)候，我們的API接口里面的業(yè)務(wù)邏輯非常復(fù)雜，特別是有些批量接口，如果同步處理業(yè)務(wù)，耗時(shí)會(huì)非常長(zhǎng)。

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

在API接口中可以發(fā)送一條mq消息，然后直接返回成功。之后，有個(gè)專(zhuān)門(mén)的mq消費(fèi)者去異步消費(fèi)該消息，做業(yè)務(wù)邏輯處理。

直接異步處理的接口，第三方平臺(tái)有兩種方式獲取到。

第一種方式是：我們回調(diào)第三方平臺(tái)的接口，告知他們API接口的處理結(jié)果，很多支付接口就是這么玩的。

第二種方式是：第三方平臺(tái)通過(guò)輪詢(xún)調(diào)用我們另外一個(gè)查詢(xún)狀態(tài)的API接口，每隔一段時(shí)間查詢(xún)一次狀態(tài)，傳入的參數(shù)是之前的那個(gè)API接口中的id集合。

13. 數(shù)據(jù)脫敏

有時(shí)候第三方平臺(tái)調(diào)用我們API接口時(shí)，獲取的數(shù)據(jù)中有一部分是敏感數(shù)據(jù)，比如：用戶(hù)手機(jī)號(hào)、銀行卡號(hào)等等。

這樣信息如果通過(guò)API接口直接保留到外網(wǎng)，是非常不安全的，很容易造成用戶(hù)隱私數(shù)據(jù)泄露的問(wèn)題。

這就需要對(duì)部分?jǐn)?shù)據(jù)做數(shù)據(jù)脫敏了。

我們可以在返回的數(shù)據(jù)中，部分內(nèi)容用星號(hào)代替。

已用戶(hù)手機(jī)號(hào)為例：182****887。

這樣即使數(shù)據(jù)被泄露了，也只泄露了一部分，不法分子拿到這份數(shù)據(jù)也沒(méi)啥用。

14. 完整的接口文檔

說(shuō)實(shí)話(huà)，一份完整的API接口文檔，在雙方做接口對(duì)接時(shí)，可以減少很多溝通成本，讓對(duì)方少走很多彎路。

接口文檔中需要包含如下信息：

• 接口地址
• 請(qǐng)求方式，比如：post或get
• 請(qǐng)求參數(shù)和字段介紹
• 返回值和字段介紹
• 返回碼和錯(cuò)誤信息
• 加密或簽名示例
• 完整的請(qǐng)求demo
• 額外的說(shuō)明，比如：開(kāi)通ip白名單。

接口文檔中最好能夠統(tǒng)一接口和字段名稱(chēng)的命名風(fēng)格，比如都用駝峰標(biāo)識(shí)命名。

統(tǒng)一字段的類(lèi)型和長(zhǎng)度，比如：id字段用Long類(lèi)型，長(zhǎng)度規(guī)定20。status字段用int類(lèi)型，長(zhǎng)度固定2等。

統(tǒng)一時(shí)間格式字段，比如：time用String類(lèi)型，格式為：yyyy-MM-dd HH:mm:ss。

接口文檔中寫(xiě)明AK/SK和域名，找某某單獨(dú)提供等。

15. 請(qǐng)求方式

接口支持的請(qǐng)求方式有很多，比如：GET、POST、PUT、DELETE等等。

我們?cè)谠O(shè)計(jì)接口的時(shí)候，要根據(jù)實(shí)際情況選擇使用哪種請(qǐng)求方式。

實(shí)際工作中使用最多的是：GET和POST，這兩種請(qǐng)求方式。

如果沒(méi)有輸入?yún)?shù)的接口，可以使用GET請(qǐng)求方式，問(wèn)題不大。

如果有輸入?yún)?shù)的接口，推薦使用POST請(qǐng)求方式，坑更少。

主要原因有下面兩點(diǎn)：

• POST請(qǐng)求方式更容易擴(kuò)展參數(shù)，特別是在Fegin調(diào)用接口的場(chǎng)景下，比如：增加一個(gè)參數(shù)，調(diào)用方可以不用修改代碼。而GET請(qǐng)求方式，需要修改代碼，否則編譯會(huì)出錯(cuò)。
• GET請(qǐng)求方式的參數(shù)，有長(zhǎng)度限制，最長(zhǎng)是5000個(gè)字符，而POST請(qǐng)求方式對(duì)參數(shù)的長(zhǎng)度沒(méi)有做限制，可以傳入更長(zhǎng)的參數(shù)值。

16. 請(qǐng)求頭

對(duì)于一些公共的功能，比如：接口的權(quán)限驗(yàn)證，或者接口的traceId參數(shù)。

我們?cè)谠O(shè)計(jì)接口的時(shí)候，不用把所有的參數(shù)，都放入接口的請(qǐng)求參數(shù)中。

有些參數(shù)可以放到Header請(qǐng)求頭中。

比如：我們需求記錄每個(gè)請(qǐng)求的traceId，不用在所有接口中都加traceId字段。

而改成讓用戶(hù)在header中傳入traceId，在服務(wù)端使用統(tǒng)一的攔截器解析header，即可獲取該traceId了。

17. 批量

我們?cè)谠O(shè)計(jì)接口的時(shí)候，無(wú)論是查詢(xún)數(shù)據(jù)、添加數(shù)據(jù)、修改數(shù)據(jù)，還是刪除的場(chǎng)景，都應(yīng)該考慮一下能否設(shè)計(jì)成批量的。

很多時(shí)候，需要通過(guò)id查詢(xún)數(shù)據(jù)詳情，比如：通過(guò)訂單id，查詢(xún)訂單詳情。

如果你的接口只支持，通過(guò)一個(gè)id，查詢(xún)一個(gè)訂單的詳情。

那么，后面需要通過(guò)多個(gè)id，查詢(xún)多個(gè)訂單詳情的時(shí)候，就需要額外增加接口了。

如果你添加數(shù)據(jù)的接口，只支持一條數(shù)據(jù)一條數(shù)據(jù)的添加。

后面，有個(gè)job需要一次性添加1000條數(shù)據(jù)的時(shí)候，這時(shí)在代碼中循環(huán)1000次，一個(gè)個(gè)添加，這種做法效率比較低。

為了讓你的接口設(shè)計(jì)的更加通用，滿(mǎn)足更多的業(yè)務(wù)場(chǎng)景，能設(shè)計(jì)成批量的，盡量別設(shè)計(jì)成單個(gè)的。

18. 職責(zé)單一

我之前見(jiàn)過(guò)有些小伙伴設(shè)計(jì)的接口，在入?yún)⒅懈鞣N條件都支持，在Service層有N多的if...else判斷。

而且返回的實(shí)體類(lèi)中，包含了各種場(chǎng)景下的返回值字段，字段很多很全。

接口上線(xiàn)一年之后，自己可能都忘了，在哪些業(yè)務(wù)場(chǎng)景下，要傳入哪些字段，返回值是哪些字段。

這類(lèi)接口的維護(hù)成本非常高，而且又不敢輕易重構(gòu)，怕改了A業(yè)務(wù)場(chǎng)景，影響B(tài)業(yè)務(wù)場(chǎng)景的功能，這種接口讓人非常痛苦的。

好的接口設(shè)計(jì)原則是：職責(zé)單一。

比如用戶(hù)下單的場(chǎng)景，有web端和移動(dòng)端。

而每個(gè)端都有普通下單和快速下單，兩種不同的業(yè)務(wù)場(chǎng)景。

我們?cè)谠O(shè)計(jì)接口的時(shí)候，可以將web端和移動(dòng)端的接口在controller層完全分開(kāi)。

/web/v1/order
/mobile/v1/order

并且將普通下單和快速下單也分開(kāi)：

/web/v1/order/create
/web/v1/order/fastCreate
/mobile/v1/order/create
/mobile/v1/order/fastCreate

這樣可以設(shè)計(jì)成4個(gè)接口。

業(yè)務(wù)邏輯更清晰一些，方便后面維護(hù)。