前言

1、域名訪問(wèn)不到

2、簽名錯(cuò)誤

3、簽名過(guò)期

4、接口突然沒(méi)返回?cái)?shù)據(jù)

5、token 失效

6、接口超時(shí)

7、接口返回 500

8、接口返回 404

9、接口返回少數(shù)據(jù)了

10、偷偷改參數(shù)了

11、接口時(shí)好時(shí)壞

12、文檔和接口邏輯不一致

13、欠費(fèi)了

前言

在實(shí)際工作中，我們經(jīng)常需要在項(xiàng)目中調(diào)用第三方API接口，獲取數(shù)據(jù)，或者上報(bào)數(shù)據(jù)，進(jìn)行數(shù)據(jù)交換和通信。

那么，調(diào)用第三方 API 接口會(huì)遇到哪些問(wèn)題？如何解決這些問(wèn)題呢？

這篇文章就跟大家一起聊聊第三方API接口的話(huà)題，希望對(duì)你會(huì)有所幫助。

基于 Spring Boot + MyBatis Plus + Vue & Element 實(shí)現(xiàn)的后臺(tái)管理系統(tǒng) + 用戶(hù)小程序，支持 RBAC 動(dòng)態(tài)權(quán)限、多租戶(hù)、數(shù)據(jù)權(quán)限、工作流、三方登錄、支付、短信、商城等功能

項(xiàng)目地址：https://github.com/YunaiV/ruoyi-vue-pro

視頻教程：https://doc.iocoder.cn/video/

1、域名訪問(wèn)不到

一般我們?cè)诘谝淮螌?duì)接第三方平臺(tái)的 API 接口時(shí)，可能會(huì)先通過(guò)瀏覽器或者 postman 調(diào)用一下，該接口是否可以訪問(wèn)。

有些人可能覺(jué)得多次一舉。

其實(shí)不然。

有可能你調(diào)用第三方平臺(tái)的 API 接口時(shí)，他們的接口真的掛了，他們還不知道。還有一種最重要的情況，就是你的工作網(wǎng)絡(luò)，是否可以訪問(wèn)這個(gè)外網(wǎng)的接口。

有些公司為了安全考慮，對(duì)內(nèi)網(wǎng)的開(kāi)發(fā)環(huán)境，是設(shè)置了防火墻的，或者有一些其他的限制，有些 IP 白名單，只能訪問(wèn)一些指定的外網(wǎng)接口。

如果你發(fā)現(xiàn)你訪問(wèn)的域名，在開(kāi)發(fā)環(huán)境訪問(wèn)不通，就要到運(yùn)維同學(xué)給你添加ip白名單了。

基于 Spring Cloud Alibaba + Gateway + Nacos + RocketMQ + Vue & Element 實(shí)現(xiàn)的后臺(tái)管理系統(tǒng) + 用戶(hù)小程序，支持 RBAC 動(dòng)態(tài)權(quán)限、多租戶(hù)、數(shù)據(jù)權(quán)限、工作流、三方登錄、支付、短信、商城等功能

項(xiàng)目地址：https://github.com/YunaiV/yudao-cloud

視頻教程：https://doc.iocoder.cn/video/

2、簽名錯(cuò)誤

很多第三方 API 接口為了防止別人篡改數(shù)據(jù)，通常會(huì)增加數(shù)字簽名（sign）的驗(yàn)證。

sign=md5(多個(gè)參數(shù)拼接+密鑰)

在剛開(kāi)始對(duì)接第三方平臺(tái)接口時(shí)，會(huì)遇到參數(shù)錯(cuò)誤，簽名錯(cuò)誤等問(wèn)題。

其中參數(shù)錯(cuò)誤比較好解決，重點(diǎn)是簽名錯(cuò)誤這個(gè)問(wèn)題。

簽名是由一些算法生成的。

比如：將參數(shù)名和參數(shù)值用冒號(hào)拼接，如果有多個(gè)參數(shù)，則按首字母排序，然后再將多個(gè)參數(shù)一起拼接。然后加鹽（即：密鑰），再通過(guò) md5，生成一個(gè)簽名。

如果有多個(gè)參數(shù)，你是按首字母倒序的，則最后生成的簽名會(huì)出問(wèn)題。

如果你開(kāi)發(fā)環(huán)境的密鑰，用的生產(chǎn)環(huán)境的，也可能會(huì)導(dǎo)致生產(chǎn)的簽名出現(xiàn)問(wèn)題。

如果第三方平臺(tái)要求最后 3 次 md5 生成簽名，而你只用了 1 次，也可能會(huì)導(dǎo)致生產(chǎn)的簽名出現(xiàn)問(wèn)題。

因此，接口簽名在接口聯(lián)調(diào)時(shí)是比較麻煩的事情。

如果第三方平臺(tái)有提供 SDK 生成簽名是最好的，如果沒(méi)有，就只能根據(jù)他們文檔手寫(xiě)簽名算法了。

3、簽名過(guò)期

通過(guò)上面一步，我們將簽名調(diào)通了，可以正常訪問(wèn)第三方平臺(tái)獲取數(shù)據(jù)了。

但你可能會(huì)發(fā)現(xiàn)，同一個(gè)請(qǐng)求，15 分鐘之后，再獲取數(shù)據(jù)，卻返回失敗了。

第三方平臺(tái)在設(shè)計(jì)接口時(shí)，在簽名中增加了時(shí)間戳校驗(yàn)，同一個(gè)請(qǐng)求在 15 分鐘之內(nèi)，允許返回?cái)?shù)據(jù)。如果超過(guò)了 15 分鐘，則直接返回“失敗”。

這種設(shè)計(jì)是為了安全考慮。

防止有人利用工具進(jìn)行暴力破解，不停偽造簽名，不停調(diào)用接口校驗(yàn)，如果一直窮舉下去的話(huà)，總有一天可以校驗(yàn)通過(guò)的。

sign=md5(多個(gè)參數(shù)拼接+密鑰+時(shí)間戳)

因此，有必要增加時(shí)間戳的校驗(yàn)。

如果出現(xiàn)這種情況，不要慌，重新發(fā)起一次新的請(qǐng)求即可。

4、接口突然沒(méi)返回?cái)?shù)據(jù)

如果你調(diào)用第三方平臺(tái)的某個(gè) API 接口查詢(xún)數(shù)據(jù)，剛開(kāi)始一直都有數(shù)據(jù)返回。突然某一天沒(méi)返回?cái)?shù)據(jù)了。但是該 API 接口能夠正常響應(yīng)。

不要感到意外，有可能是第三方平臺(tái)將數(shù)據(jù)刪除了。

我對(duì)接完第三方平臺(tái)的 API 接口后，部署到了測(cè)試環(huán)境，發(fā)現(xiàn)他們接口竟然沒(méi)有返回?cái)?shù)據(jù)，原因是他們有一天將測(cè)試環(huán)境的數(shù)據(jù)刪完了。

因此，在部署測(cè)試環(huán)境之前，要先跟對(duì)方溝通，要用哪些數(shù)據(jù)測(cè)試，不能刪除。

5、token 失效

有些平臺(tái)的 API 接口在請(qǐng)求之前，先要調(diào)用另外一個(gè) API 接口獲取 token，然后在 header 中攜帶該 token 信息才能訪問(wèn)其他的業(yè)務(wù) API 接口。

在獲取 token 的 API 接口中，我們需要傳入賬號(hào)、密碼和密鑰等信息。每個(gè)接口對(duì)接方，這些信息都不一樣。

我們?cè)谡?qǐng)求其他的 API 接口之前，每次都實(shí)時(shí)調(diào)用一次獲取 token 的接口獲取 token？還是請(qǐng)求一次 token，將其緩存到 Redis 中，后面直接從 Redis 獲取數(shù)據(jù)呢？

很顯然我們更傾向于后者，因?yàn)槿绻看握?qǐng)求其他的 API 接口之前，都實(shí)時(shí)調(diào)用一次獲取 token 的接口獲取 token，這樣每次都會(huì)請(qǐng)求兩次接口，性能上會(huì)有一些影響。

如果將請(qǐng)求的 token，保存到 Redis，又會(huì)出現(xiàn)另外一個(gè)問(wèn)題：token 失效的問(wèn)題。

我們調(diào)用第三方平臺(tái)獲取 token 的接口獲取到的 token，一般都有個(gè)有效期，比如：1 天，1 個(gè)月等。在有效期內(nèi)，該 API 接口能夠正常訪問(wèn)。如果超過(guò)了 token 的有效期，則該 API 接口不允許訪問(wèn)。

好辦，我們把 Redis 的失效時(shí)間設(shè)置成跟 token 的有效期一樣不就 OK 了？想法是不錯(cuò)，但是有問(wèn)題。

你咋保證，你們系統(tǒng)的服務(wù)器時(shí)間，跟第三方平臺(tái)的服務(wù)器時(shí)間一模一樣？

我之前遇到過(guò)某大廠，提供了獲取 token 接口，在 30 天內(nèi)發(fā)起請(qǐng)求，每次都返回相同的 token 值。如果超過(guò)了 30 天，則返回一個(gè)新的。

有可能出現(xiàn)這種情況，你們系統(tǒng)的服務(wù)器時(shí)間要快一些，第三方平臺(tái)的時(shí)間要慢一些。結(jié)果到了 30 天，你們系統(tǒng)調(diào)用第三方平臺(tái)的獲取 token 接口獲取到了 token 還是老的 token，更新到 Redis 中了。

過(guò)一段時(shí)間，token 失效了，你們系統(tǒng)還是用老的 token 訪問(wèn)第三方平臺(tái)的其他API接口，一直都返回失敗。但獲取新的 token 卻要等 30 天，這個(gè)時(shí)間太漫長(zhǎng)了。

為了解決這個(gè)問(wèn)題，需要捕獲 token 失效的異常。如果在調(diào)用其他的 API 接口時(shí)發(fā)現(xiàn) token 失效了，馬上請(qǐng)求一次獲取 token 接口，將新的 token 立刻更新到 Redis 中。

這樣基本可以解決 token 失效問(wèn)題，也能盡可能保證訪問(wèn)其他接口的穩(wěn)定性和性能。

6、接口超時(shí)

系統(tǒng)上線(xiàn)之后，調(diào)用第三方API接口，最容易出現(xiàn)的問(wèn)題，應(yīng)該是接口超時(shí)問(wèn)題了。

系統(tǒng)到外部系統(tǒng)之間，有一條很復(fù)雜的鏈路，中間有很多環(huán)節(jié)出現(xiàn)問(wèn)題，都可能影響 API 接口的相應(yīng)時(shí)間。

作為 API 接口的調(diào)用方，面對(duì)第三方 API 接口超時(shí)問(wèn)題，除了給他們反饋問(wèn)題，優(yōu)化接口性能之外，我們更有效的方式，可能是增加接口調(diào)用的失敗重試機(jī)制。

例如：

intretryCount=0;
do{
try{
doPost();
break;
}catch(Exceptione){
log.warn("接口調(diào)用失敗")retryCount++;
}
}
where(retryCount<=?3)

如果接口調(diào)用失敗，則程序會(huì)立刻自動(dòng)重試 3 次。

如果重試之后成功了，則該 API 接口調(diào)用成功。

如果重試 3 次之后還是失敗，則該 API 接口調(diào)用失敗。

7、接口返回 500

調(diào)用第三方 API 接口，偶爾因?yàn)閰?shù)的不同，可能會(huì)出現(xiàn) 500 的問(wèn)題。

比如：有些 API 接口對(duì)于參數(shù)校驗(yàn)不到位，少部分必填字段，沒(méi)有校驗(yàn)不能為空。

此時(shí)，系統(tǒng)的有些請(qǐng)求通過(guò)某個(gè)參數(shù)去調(diào)用該 API 接口時(shí)，沒(méi)有傳入那個(gè)參數(shù)，對(duì)方可能會(huì)出現(xiàn) NPE 問(wèn)題。而該接口的返回 code，很可能是 500。

還有一種情況，就是該 API 接口的內(nèi)部 bug，傳入不同的參數(shù)，走了不同的條件分支邏輯，在走某個(gè)分支時(shí)，接口邏輯出現(xiàn)異常，可能會(huì)導(dǎo)致接口返回 500。

這種情況做接口重試也沒(méi)用，只能聯(lián)系第三方 API 接口提供者，反饋相關(guān)問(wèn)題，讓他們排查具體原因。

他們可能會(huì)通過(guò)修復(fù) bug，或者修復(fù)數(shù)據(jù)，來(lái)解決這個(gè)問(wèn)題。

8、接口返回 404

如果你在系統(tǒng)日志中發(fā)現(xiàn)調(diào)用的第三方API接口返回了 404，這就非常坑了。

如果第三方的 API 接口沒(méi)有上線(xiàn)，很可能是他們把接口名改了，沒(méi)有及時(shí)通知你。

這種情況，可以錘他們了。

還有一種情況是，如果第三方的 API 接口已經(jīng)上線(xiàn)了，剛開(kāi)始接口是能正常調(diào)用的。

第三方也沒(méi)有改過(guò)接口地址。

后來(lái)，突然有一天發(fā)現(xiàn)調(diào)用第三方的 API 接口還是出現(xiàn)了 404 問(wèn)題。

這種情況很可能是他們網(wǎng)關(guān)出問(wèn)題了，最新的配置沒(méi)有生效，或者改了網(wǎng)關(guān)配置導(dǎo)致的問(wèn)題。

總之一個(gè)字：坑。

9、接口返回少數(shù)據(jù)了

之前我調(diào)過(guò)一個(gè)第三方的 API 接口分頁(yè)查詢(xún)數(shù)據(jù)，接入非常順利，但后來(lái)上線(xiàn)之后，發(fā)現(xiàn)他們的接口少數(shù)據(jù)了。

一查原因發(fā)現(xiàn)是該分頁(yè)查詢(xún)接口，返回的總頁(yè)數(shù)不對(duì)，比實(shí)際情況少了。

有些小伙伴可能會(huì)好奇，這么詭異的問(wèn)題我是怎么發(fā)現(xiàn)？

之前調(diào)用第三方 API 接口分頁(yè)查詢(xún)分類(lèi)數(shù)據(jù)，保存到我們的第三方分類(lèi)表中。

突然有一天，產(chǎn)品反饋說(shuō)，第三方有個(gè)分類(lèi)在分類(lèi)樹(shù)中找不到。

我確認(rèn)之后，發(fā)現(xiàn)竟然是真的沒(méi)有。

從調(diào)用第三方 API 接口的響應(yīng)日志中，也沒(méi)有查到該分類(lèi)的數(shù)據(jù)。

這個(gè)API接口是分頁(yè)查詢(xún)接口，目前已經(jīng)分了十幾頁(yè)查詢(xún)數(shù)據(jù)，但還是沒(méi)有查到我們想要的分類(lèi)。

之前的做法是先調(diào)用一次 API 接口查詢(xún)第一頁(yè)的數(shù)據(jù)，同時(shí)查出總頁(yè)數(shù)。然后再根據(jù)總頁(yè)數(shù)循環(huán)調(diào)用，查詢(xún)其他頁(yè)的數(shù)據(jù)。

我當(dāng)時(shí)猜測(cè)，可能是他們接口返回的總頁(yè)數(shù)有問(wèn)題。

于是，可以將接口調(diào)用邏輯改成這樣的：

從第一頁(yè)開(kāi)始，后面每調(diào)用一次 API 接口查數(shù)據(jù)，頁(yè)數(shù)就加 1。然后判斷接口返回的數(shù)據(jù)是否小于 pageSize，

如果不小于，則進(jìn)行下一次調(diào)用。

如果小于，則說(shuō)明已經(jīng)是最后一頁(yè)了，可以停止后續(xù)調(diào)用了。

驗(yàn)證之后發(fā)現(xiàn)這樣果然可以獲取那個(gè)分類(lèi)的數(shù)據(jù)，只能說(shuō)明第三方的分頁(yè)查詢(xún)接口返回的總頁(yè)數(shù)比實(shí)際情況小了。

10、偷偷改參數(shù)了

我之前調(diào)用過(guò)某平臺(tái)的 API 接口獲取指標(biāo)的狀態(tài)，之前根據(jù)雙方約定的狀態(tài)有：正常和禁用 兩種。

然后將狀態(tài)更新到我們的指標(biāo)表中。

后來(lái)，雙方系統(tǒng)上線(xiàn)運(yùn)行了好幾個(gè)月。

突然有一天，用戶(hù)反饋說(shuō)某一條數(shù)據(jù)明明刪除了，為什么在頁(yè)面上還是可以查到。

此時(shí)，我查我們這邊的指標(biāo)表，發(fā)現(xiàn)狀態(tài)是正常的。

然后查看調(diào)用該平臺(tái)的API接口日志，發(fā)現(xiàn)返回的該指標(biāo)的狀態(tài)是：下架。

what？這是什么狀態(tài)？

跟該平臺(tái)的開(kāi)發(fā)人員溝通后，發(fā)現(xiàn)他們改了狀態(tài)的枚舉，增加了：上架、下架等多個(gè)值，而且沒(méi)有通知我們。

這就坑了。

我們這邊的代碼中判斷，如果狀態(tài)非禁用狀態(tài)，都認(rèn)為是正常狀態(tài)。

而下架狀態(tài)，自動(dòng)被判斷為正常狀態(tài)。

經(jīng)過(guò)跟對(duì)方溝通后，他們確認(rèn)下架狀態(tài)，是非正常狀態(tài)，不應(yīng)該顯示指標(biāo)。他們改了數(shù)據(jù)，臨時(shí)解決了該指標(biāo)的問(wèn)題。

后來(lái)，他們按接口文檔又改回了之前的狀態(tài)枚舉值。

11、接口時(shí)好時(shí)壞

不知道你在調(diào)用第三方接口時(shí)，有沒(méi)有遇到過(guò)接口時(shí)好時(shí)壞的情況。

5 分鐘前，該接口還能正常返回?cái)?shù)據(jù)。

5 分鐘后，該接口返回 503 不可用。

又過(guò)了幾分鐘，該接口又能正常返回?cái)?shù)據(jù)了。

這種情況大概率是第三方平臺(tái)在重啟服務(wù)，在重啟的過(guò)程中，可能會(huì)出現(xiàn)服務(wù)暫時(shí)不可用的情況。

還有另外一種情況：第三方接口部署了多個(gè)服務(wù)節(jié)點(diǎn)，有一部分服務(wù)節(jié)點(diǎn)掛了。也會(huì)導(dǎo)致請(qǐng)求第三方接口時(shí)，返回值時(shí)好時(shí)壞的情況。

此外還有一種情況：網(wǎng)關(guān)的配置沒(méi)有及時(shí)更新，沒(méi)有把已經(jīng)下線(xiàn)的服務(wù)剔除掉。

這樣用戶(hù)請(qǐng)求經(jīng)過(guò)網(wǎng)關(guān)時(shí)，網(wǎng)關(guān)轉(zhuǎn)發(fā)到了已經(jīng)下線(xiàn)的服務(wù)，導(dǎo)致服務(wù)不可用。網(wǎng)關(guān)轉(zhuǎn)發(fā)請(qǐng)求到正常的服務(wù)，該服務(wù)能夠正常返回。

如果遇到該問(wèn)題，要盡快將問(wèn)題反饋給第三方平臺(tái)，然后增加接口失敗重試機(jī)制。

12、文檔和接口邏輯不一致

之前還遇到一個(gè)第三方平臺(tái)提供的 API 查詢(xún)接口，接口文檔中明確寫(xiě)明了有個(gè) dr 字段表示刪除狀態(tài)。

有了這個(gè)字段，我們?cè)谕降谌狡脚_(tái)的分類(lèi)數(shù)據(jù)時(shí)，就能夠知道有哪些數(shù)據(jù)是被刪除的，后面可以及時(shí)調(diào)整我們這邊的數(shù)據(jù)，將相關(guān)的數(shù)據(jù)也做刪除處理。

后來(lái)發(fā)現(xiàn)有些分類(lèi)，他們那邊已經(jīng)刪除了，但是我們這邊卻沒(méi)刪除。

這是啥情況呢？

代碼邏輯很簡(jiǎn)單，我 review 了一下代碼，也沒(méi)有 bug，為什么會(huì)出現(xiàn)這種情況呢？

追查日志之后發(fā)現(xiàn)，調(diào)用第三方平臺(tái)獲取分類(lèi)接口時(shí)，對(duì)方并沒(méi)有把已刪除的分類(lèi)數(shù)據(jù)返回給我們。

也就是說(shuō)接口文檔中的那個(gè) dr 字段沒(méi)有什么用，接口文檔和接口邏輯不一致。

這個(gè)問(wèn)題估計(jì)好多小伙伴都遇到過(guò)。

如果要解決這個(gè)問(wèn)題，主要的方案有兩種：

第三方平臺(tái)按文檔修改接口邏輯，返回刪除狀態(tài)。

我們系統(tǒng)在調(diào)用分類(lèi)查詢(xún)接口之后，根據(jù)分類(lèi) code 判斷，如果數(shù)據(jù)庫(kù)中有些分類(lèi)的 code 不在接口返回值中，則刪除這些分類(lèi)。

13、欠費(fèi)了

我們調(diào)用過(guò)百度的票據(jù)識(shí)別接口，可以自動(dòng)識(shí)別發(fā)票信息，獲取發(fā)票編號(hào)和金額等信息。

之前是另外一個(gè)同事對(duì)接的接口，后來(lái)他離職了。

發(fā)票識(shí)別功能上線(xiàn)，使用了很長(zhǎng)一段時(shí)間，一直都沒(méi)有出問(wèn)題。

后來(lái)，某一天，生產(chǎn)環(huán)境用戶(hù)反饋發(fā)票識(shí)別不了了。

我查詢(xún)了相關(guān)服務(wù)的日志，沒(méi)有發(fā)現(xiàn)異常，這就奇怪了。

打開(kāi)代碼仔細(xì)看了一下，發(fā)現(xiàn)那位同事的代碼中調(diào)用第三方的API接口，接收響應(yīng)數(shù)據(jù)時(shí)，直接轉(zhuǎn)換成了對(duì)象，沒(méi)有打印當(dāng)時(shí)返回的字符串。

莫非，接口返回值有問(wèn)題？

后來(lái)，我增加了日志，打印出了該接口真正的返回內(nèi)容值。

原因一下查到了，原來(lái)是欠費(fèi)了。

如果出現(xiàn)該異常，百度的 API 接口返回的數(shù)據(jù)結(jié)構(gòu)，用之前那位同事的實(shí)體有些參數(shù)沒(méi)法獲取到。

這是一個(gè)不小的坑。

我們?cè)诮邮盏谌?API 接口返回?cái)?shù)據(jù)時(shí)，盡可能先用字符串接收返回值，然后將字符串轉(zhuǎn)換成相應(yīng)實(shí)體類(lèi)，一定要將該返回值在日志中打印出來(lái)，方便后面定位問(wèn)題。

不要直接用實(shí)體對(duì)象接收返回值，有些 API 接口，如果出現(xiàn)不同的異常，返回的數(shù)據(jù)結(jié)構(gòu)差異比較大。

有些異常結(jié)果可能是他們網(wǎng)關(guān)系統(tǒng)直接返回的，有些異常是他們業(yè)務(wù)系統(tǒng)返回的。