直接說(shuō)個(gè)我自己的經(jīng)歷。前陣子用SMP軟件制作平臺(tái)做一個(gè)小工具需要把第三方天氣數(shù)據(jù)接進(jìn)來(lái)當(dāng)時(shí)心想不就是發(fā)個(gè)HTTP請(qǐng)求解析一下JSON嘛能有多難。結(jié)果花了大半個(gè)晚上在排查一個(gè)401鑒權(quán)錯(cuò)誤最后發(fā)現(xiàn)不是密鑰不對(duì)而是我在SMP里把接口參數(shù)名拼錯(cuò)了——服務(wù)端要求的字段叫city_code我寫(xiě)成了cityCode。那一刻我才意識(shí)到接口這東西定義階段省一分鐘調(diào)用階段要還一小時(shí)。這一講是接口API屬于SMP語(yǔ)言基礎(chǔ)知識(shí)系列里偏工程化的一節(jié)知識(shí)門檻不高但涉及的習(xí)慣和細(xì)節(jié)特別多。我會(huì)從SMP語(yǔ)言內(nèi)部怎么定義接口講起再聊到SMP程序怎么調(diào)用真實(shí)的HTTP API最后把冪等性、錯(cuò)誤碼、鑒權(quán)這些容易踩坑的點(diǎn)單獨(dú)拎出來(lái)說(shuō)透。不管你是剛開(kāi)始學(xué)SMP還是已經(jīng)在用別的語(yǔ)言寫(xiě)后臺(tái)、寫(xiě)自動(dòng)化腳本這講的內(nèi)容應(yīng)該都能幫得上。1. SMP里的接口到底指的是什么——先把這個(gè)概念錨定住先說(shuō)一個(gè)很多初學(xué)者會(huì)懵的地方在C語(yǔ)言或者單片機(jī)的語(yǔ)境里說(shuō)到接口大家往往想到的是GPIO、UART、SPI這類物理引腳或者頭文件里聲明的函數(shù)接口。但在SMP語(yǔ)言里接口不是一個(gè)物理概念也不是簡(jiǎn)單的函數(shù)聲明它是一組約定用來(lái)約束兩個(gè)軟件模塊之間怎么通信、傳什么數(shù)據(jù)、按什么順序執(zhí)行。1.1 從生活里的插座說(shuō)起我上課講接口的時(shí)候喜歡用插座來(lái)類比。墻上那個(gè)插座就是接口定義它規(guī)定了電壓是220V、頻率50Hz、插孔形狀是兩腳還是三腳。任何電器只要按照這個(gè)規(guī)范去做插頭插上去就能用不需要關(guān)心墻里面是哪個(gè)發(fā)電廠供的電。SMP里的接口也是這個(gè)意思。你在A模塊里定義了一個(gè)接口相當(dāng)于立了一個(gè)標(biāo)準(zhǔn)B模塊只要遵守這個(gè)標(biāo)準(zhǔn)去調(diào)用就能拿到服務(wù)不需要知道A模塊內(nèi)部是怎么實(shí)現(xiàn)的——是查了數(shù)據(jù)庫(kù)還是調(diào)了別的服務(wù)對(duì)B來(lái)說(shuō)都是黑盒。1.2 SMP接口的三個(gè)組成要素在SMP語(yǔ)言里一個(gè)完整的接口定義通常包含三個(gè)要素接口名全局唯一的標(biāo)識(shí)類似部門的門牌號(hào)。命名上我建議一律使用小駝峰加領(lǐng)域前綴比如userService_getInfo、orderService_create這樣在工程大了以后按前綴就能快速定位歸屬模塊。入?yún)⒁?guī)則規(guī)定調(diào)用方必須傳哪些字段、每個(gè)字段的類型和取值范圍。比如查詢用戶信息入?yún)⒗镏辽僖幸粋€(gè)userId類型為字符串或整數(shù)不允許為空。返回值規(guī)則規(guī)定成功時(shí)返回什么結(jié)構(gòu)、失敗時(shí)返回什么錯(cuò)誤碼。這一步最容易被忽略但恰恰是穩(wěn)定性的根基。一個(gè)定義了但沒(méi)約定失敗行為的接口就像插座上沒(méi)有保險(xiǎn)絲——大多數(shù)時(shí)候沒(méi)事一出問(wèn)題就是大事。1.3 接口定義與函數(shù)定義的區(qū)別有些同學(xué)會(huì)問(wèn)接口不就是一個(gè)函數(shù)嘛我在SMP里直接寫(xiě)一個(gè)公開(kāi)函數(shù)不就行了。區(qū)別在兩點(diǎn)。第一函數(shù)是實(shí)現(xiàn)細(xì)節(jié)接口是契約承諾。你可以今天把一個(gè)函數(shù)里查數(shù)據(jù)庫(kù)的邏輯改成查緩存函數(shù)的簽名不變調(diào)用方無(wú)感知但如果接口的入?yún)⒔Y(jié)構(gòu)變了所有調(diào)用方都必須跟著改因?yàn)槠跫s變了。第二接口往往是跨模塊甚至跨系統(tǒng)邊界的而函數(shù)通常是進(jìn)程內(nèi)的。SMP里的接口很可能最終映射為一個(gè)HTTP端點(diǎn)或者一個(gè)進(jìn)程間消息它天然帶有網(wǎng)絡(luò)傳輸?shù)奶攸c(diǎn)有延遲、有失敗、有并發(fā)。這些在普通函數(shù)調(diào)用里是不用考慮的。所以我在寫(xiě)SMP代碼時(shí)有個(gè)習(xí)慣先把接口定義單獨(dú)寫(xiě)在一個(gè)文件里像簽合同一樣把所有字段、類型、邊界條件列清楚再去寫(xiě)實(shí)現(xiàn)邏輯。先有契約后有代碼。2. 定義一個(gè)可用的SMP接口——聲明、實(shí)現(xiàn)、綁定三步走有了概念之后看實(shí)際操作。SMP語(yǔ)言里定義一個(gè)接口大致走三步接口聲明、接口實(shí)現(xiàn)、接口綁定。下面用一個(gè)最簡(jiǎn)單的獲取用戶昵稱場(chǎng)景來(lái)演示。2.1 第一步接口聲明文件接口聲明只描述要什么和給什么不寫(xiě)任何邏輯。SMP的聲明語(yǔ)法大致長(zhǎng)這樣interface userService_getNickName { // 入?yún)⒍x input { userId: string empty // 用戶ID必填 scene: string default // 場(chǎng)景標(biāo)識(shí)可選 } // 成功返回 success { nickName: string level: int } // 錯(cuò)誤碼約定 error { 10001: userId不能為空 10002: 用戶不存在 } }注意看這里我把錯(cuò)誤碼也寫(xiě)進(jìn)了聲明里這是很多半路轉(zhuǎn)SMP的人不習(xí)慣的地方。但恰恰是這個(gè)習(xí)慣讓后續(xù)的調(diào)用方省了無(wú)數(shù)對(duì)接成本。調(diào)用方看到錯(cuò)誤碼表等于提前拿到了接口會(huì)怎么拒絕我的完整清單寫(xiě)容錯(cuò)邏輯就有據(jù)可依。2.2 第二步接口實(shí)現(xiàn)文件聲明只是一紙合同實(shí)現(xiàn)才是真正的干活的人。SMP要求實(shí)現(xiàn)文件通過(guò)implement關(guān)鍵字顯式聲明自己實(shí)現(xiàn)的是哪個(gè)接口這樣跑冒煙測(cè)試的時(shí)候平臺(tái)能自動(dòng)檢查有沒(méi)有只聲明未實(shí)現(xiàn)的接口。implement userService_getNickName { process(input) { if input.userId empty { return error(10001) } userData db.query(select nick_name, level from t_user where user_id ?, input.userId) if userData null { return error(10002) } return success({ nickName: userData.nick_name, level: userData.level }) } }這里有一個(gè)關(guān)鍵設(shè)計(jì)真正的查詢動(dòng)作被封裝在process方法內(nèi)部外部調(diào)用方完全看不到db.query的存在。將來(lái)就算你把用戶表從MySQL遷到了Redis緩存只要接口的入?yún)⒑头祷刂挡蛔兯姓{(diào)用方一行代碼都不用改。這就是接口封裝帶來(lái)的維護(hù)紅利。2.3 第三步接口綁定與暴露SMP里的接口可以只在平臺(tái)內(nèi)部模塊間調(diào)用也可以通過(guò)綁定配置暴露成外部的HTTP API。綁定這一步通常在平臺(tái)的配置文件里完成不需要寫(xiě)代碼api_bindings: - interface: userService_getNickName http_method: GET http_path: /api/v1/user/nickname param_mapping: userId: query.userId這個(gè)配置的意思是外部系統(tǒng)通過(guò)GET /api/v1/user/nickname?userIdxxx就能訪問(wèn)到我們SMP模塊里的userService_getNickName接口。參數(shù)映射表解決了外部字段名和內(nèi)部字段名不一致的問(wèn)題比如外部都叫userId內(nèi)部可能叫oid映射一下就好了不用為了對(duì)接去改代碼。我實(shí)際項(xiàng)目中常用的做法是內(nèi)部接口命名偏向語(yǔ)義化外部路徑統(tǒng)一加/api/v1/前綴并且全部小寫(xiě)這樣外部對(duì)接方看到URL就能猜到功能看到版本號(hào)就知道能不能隨便升級(jí)。接口路徑一旦發(fā)布出去就盡量不要改了——因?yàn)檎{(diào)用方可能已經(jīng)把它寫(xiě)死在他們的代碼里你一改他們的程序就斷了。3. 調(diào)用真實(shí)世界的HTTP API——SMP里的請(qǐng)求、解析與鑒權(quán)三件套定義好了接口給自己用接下來(lái)更常見(jiàn)的場(chǎng)景是SMP程序要去調(diào)用別人家的API比如大模型問(wèn)答API、天氣API、支付API。這一步里有三個(gè)基本功必須扎實(shí)發(fā)請(qǐng)求、解析返回、帶上鑒權(quán)信息。任何一個(gè)出問(wèn)題整個(gè)鏈路就斷了。3.1 發(fā)起HTTP請(qǐng)求的標(biāo)準(zhǔn)姿勢(shì)SMP語(yǔ)言內(nèi)置了http庫(kù)封裝了常見(jiàn)的請(qǐng)求方法。一個(gè)標(biāo)準(zhǔn)的GET請(qǐng)求長(zhǎng)這樣resp http.get(https://api.example.com/v1/weather, { headers: { Authorization: Bearer config.apiKey }, params: { city: shenzhen }, timeout: 5000 // 毫秒 })我要特別強(qiáng)調(diào)一下timeout這個(gè)參數(shù)。很多剛學(xué)SMP的人不設(shè)置超時(shí)時(shí)間或者干脆設(shè)成0表示永不超時(shí)。這在測(cè)試環(huán)境沒(méi)問(wèn)題一旦上了生產(chǎn)只要下游服務(wù)慢一次你的SMP模塊就跟著卡死所有調(diào)用你的上層應(yīng)用也連鎖卡死。所以我的經(jīng)驗(yàn)是外部請(qǐng)求一律設(shè)置超時(shí)內(nèi)部服務(wù)之間通信可以稍微放寬一點(diǎn)但任何HTTP調(diào)用都必須有一個(gè)上限。3.2 JSON解析與字段提取的坑拿到響應(yīng)之后第一件事是判斷狀態(tài)碼第二件事才是解析body。SMP的json庫(kù)用法如下if resp.statusCode ! 200 { log.error(請(qǐng)求失敗狀態(tài)碼, resp.statusCode) return error(20001) } body json.parse(resp.body) // 很多API的返回格式是固定的code / message / data if body.code ! 0 { log.error(業(yè)務(wù)錯(cuò)誤, body.message) return error(20002) } nickName body.data.nickName解析本身不難難在字段不一定存在。假如上游API調(diào)整了返回結(jié)構(gòu)把data.nickName改到了data.user.nickName你的解析代碼在運(yùn)行時(shí)就會(huì)拿到一個(gè)空值。所以我在項(xiàng)目里定了條規(guī)矩凡是解析外部API返回的字段一律做兩層防御——先判斷層級(jí)存在性再判斷類型符合性。SMP里可以這樣優(yōu)雅地處理nickName body.data?.user?.nickName ?? 未知用戶?.的意思是如果前面的對(duì)象為空后面的就不取值??的意思是如果結(jié)果是空就用默認(rèn)值兜底。這兩兄弟是防御式編程的利器我?guī)缀踉诿恳粋€(gè)外部API調(diào)用里都會(huì)用到。3.3 鑒權(quán)方式Bearer Token 與 API Key熱搜詞里出現(xiàn)的openrouter api key、deepseek api如何調(diào)用、智譜api其實(shí)都屬于這一類大模型廠商把模型能力封裝成HTTP API用API Key來(lái)標(biāo)識(shí)調(diào)用者身份。鑒權(quán)頭最常見(jiàn)的兩種寫(xiě)法// 方式一Bearer Token headers: { Authorization: Bearer sk-xxxxxxxxxxxx } // 方式二自定義Header headers: { X-API-Key: your-api-key-here }不同的服務(wù)商要求的頭部名稱不同有的是Authorization有的是api-key有的還要求同時(shí)傳app_id和api_secret。這些信息在服務(wù)商的文檔里都會(huì)寫(xiě)明但容易被忽略的是密鑰的換行問(wèn)題。我曾經(jīng)排查過(guò)一個(gè)詭異的問(wèn)題在SMP里配置了密鑰單獨(dú)測(cè)試請(qǐng)求完全正常但只要在循環(huán)里連續(xù)調(diào)用偶爾就報(bào)401。后來(lái)發(fā)現(xiàn)密鑰字符串末尾多了一個(gè)不可見(jiàn)的換行符——是從配置文件里復(fù)制的時(shí)候帶進(jìn)去的。SMP的trim()函數(shù)一用問(wèn)題立刻消失。從那以后所有密鑰配置我都要先過(guò)一遍trim()。3.4 OpenRouter這類聚合平臺(tái)的特殊之處熱搜里有人搜索openrouter api key說(shuō)明有人正準(zhǔn)備用這類聚合平臺(tái)。聚合平臺(tái)的思路是它幫你接入了多個(gè)大模型你只需要持有它一個(gè)Key就能統(tǒng)一調(diào)用不同廠商的模型。這類平臺(tái)的接口調(diào)用方式通常是resp http.post(https://openrouter.ai/api/v1/chat/completions, { headers: { Authorization: Bearer config.openrouterKey, Content-Type: application/json }, body: json.encode({ model: deepseek/deepseek-chat, messages: [ {role: user, content: 你好介紹一下SMP語(yǔ)言} ] }), timeout: 60000 })注意model字段聚合平臺(tái)要求在模型名前加廠商前綴比如deepseek/deepseek-chat、openai/gpt-4o這是為了方便區(qū)分哪個(gè)廠商的哪個(gè)模型。如果沒(méi)加前綴平臺(tái)會(huì)直接報(bào)錯(cuò)錯(cuò)誤信息里往往會(huì)出現(xiàn)像熱搜里那樣的The supported api model names are ...——這種報(bào)錯(cuò)一出現(xiàn)我第一反應(yīng)就是去看model字段十有八九是格式不對(duì)。4. 接口冪等性與重試機(jī)制——好的接口經(jīng)得起重復(fù)調(diào)用熱搜詞里有一條接口冪等性這絕對(duì)值得單獨(dú)講。冪等性這東西日常開(kāi)發(fā)里容易背概念但在SMP里真的寫(xiě)一次就忘不掉。4.1 用轉(zhuǎn)賬例子理解冪等假設(shè)你的SMP模塊對(duì)外提供一個(gè)創(chuàng)建訂單接口。調(diào)用方因?yàn)榫W(wǎng)絡(luò)超時(shí)沒(méi)收到響應(yīng)于是按我們的建議重試了一次。如果接口不是冪等的那么訂單就被創(chuàng)建了兩次用戶被扣了兩次錢——這是生產(chǎn)事故不是bug。冪等的意思是同一個(gè)操作無(wú)論你執(zhí)行一次還是執(zhí)行一百次結(jié)果都一樣。而創(chuàng)建訂單天然不是冪等的因?yàn)槊看螆?zhí)行都會(huì)產(chǎn)生一條新訂單。解決方案也很經(jīng)典在入?yún)⒅屑尤胍粋€(gè)唯一請(qǐng)求IDrequestId。interface orderService_create { input { requestId: string empty // 調(diào)用方生成的UUID productId: string amount: float } // ... }實(shí)現(xiàn)層這樣做判斷implement orderService_create { process(input) { // 先查一下這個(gè)requestId有沒(méi)有處理過(guò) exists db.query(select id from t_order where request_id ?, input.requestId) if exists ! null { // 已經(jīng)處理過(guò)直接返回上次的結(jié)果不再重復(fù)創(chuàng)建 return success({orderId: exists.id, dup: true}) } orderId doCreateOrder(input) return success({orderId: orderId, dup: false}) } }這段代碼的精髓在于先查再插的邏輯同一個(gè)requestId第二次進(jìn)來(lái)時(shí)不會(huì)重復(fù)創(chuàng)建訂單而是把第一次的結(jié)果原樣返回。調(diào)用方看到dup字段就知道這是一次重復(fù)請(qǐng)求不用再額外處理。4.2 冪等判斷的并發(fā)窗口問(wèn)題上面那段偽代碼有一個(gè)隱藏風(fēng)險(xiǎn)如果兩個(gè)一模一樣的請(qǐng)求在極短時(shí)間同時(shí)到達(dá)兩個(gè)進(jìn)程都先執(zhí)行了db.query都沒(méi)查到記錄然后都執(zhí)行了doCreateOrder還是會(huì)創(chuàng)建兩條訂單。解決方式有兩個(gè)層面數(shù)據(jù)庫(kù)層面給request_id字段加唯一索引。這是兜底方案確保數(shù)據(jù)庫(kù)層面不可能出現(xiàn)兩條相同請(qǐng)求ID的記錄。應(yīng)用層面在SMP里用分布式鎖或原子操作來(lái)控制先查再插這個(gè)復(fù)合動(dòng)作的原子性。我只推薦一種組合應(yīng)用層用唯一索引兜底業(yè)務(wù)層用requestId做提前判斷。前者保證不出大事后者避免大量無(wú)意義的重復(fù)計(jì)算。4.3 重試策略要配合冪等設(shè)計(jì)外部API調(diào)用時(shí)重試也必須有策略不能一股腦地重試。我把重試分為兩種情況錯(cuò)誤類型是否該重試建議策略網(wǎng)絡(luò)超時(shí)、連接失敗可以重試最多3次間隔指數(shù)退避5xx服務(wù)器錯(cuò)誤可以重試最多2次間隔拉長(zhǎng)4xx客戶端錯(cuò)誤不該重試立即熔斷檢查參數(shù)特別是4xx錯(cuò)誤比如400參數(shù)錯(cuò)誤、401鑒權(quán)失敗如果你還傻傻地重試不僅白白浪費(fèi)請(qǐng)求額度還會(huì)讓服務(wù)商把你的Key暫時(shí)封禁。所以我在寫(xiě)重試邏輯時(shí)有一條鐵律400、401、403、404一律不重試。5. 一次400錯(cuò)誤的完整排查鏈路——從報(bào)錯(cuò)到定位的全過(guò)程熱搜里有一條值得分析的報(bào)錯(cuò)原文api error: 400 this models maximum context length is 1048576 tokens. however, your messages resulted in 1049000 tokens這個(gè)報(bào)錯(cuò)翻譯過(guò)來(lái)是模型最大上下文長(zhǎng)度是1048576個(gè)token但你這次請(qǐng)求的文本折算出來(lái)有1049000個(gè)token超了。這類問(wèn)題的排查思路比問(wèn)題本身更值得總結(jié)。5.1 明確錯(cuò)誤類型400里的分類邏輯HTTP 400表示請(qǐng)求不合法但具體的不合法原因在提示文本里。上面這個(gè)報(bào)錯(cuò)其實(shí)是內(nèi)容太長(zhǎng)類問(wèn)題。遇到400我的排查順序是這樣的看提示文本是否明確寫(xiě)出了問(wèn)題原因本例很明確token超限。檢查請(qǐng)求體大小尤其是messages數(shù)組里有沒(méi)有不小心塞入超長(zhǎng)文本。檢查模型名稱是否正確——有些400提示是不支持的模型名比如熱搜里另一條the supported api model names are deepseek-flash, deepseek-v4說(shuō)明你把模型名寫(xiě)錯(cuò)了。檢查參數(shù)格式比如JSON里某個(gè)字段類型不對(duì)。5.2 為什么1048576這么長(zhǎng)的上下文還會(huì)超限這看起來(lái)是個(gè)矛盾明明模型已經(jīng)支持100萬(wàn)token的上下文了怎么還能超原因很簡(jiǎn)單你這100萬(wàn)token的總量包含了系統(tǒng)提示詞、歷史對(duì)話、工具定義和當(dāng)前用戶問(wèn)題四個(gè)部分四者之和一旦超過(guò)上限就報(bào)錯(cuò)。很多人只盯著用戶問(wèn)題的字?jǐn)?shù)忽略了歷史對(duì)話會(huì)隨輪次逐漸膨脹。所以如果你的SMP程序是一個(gè)聊天機(jī)器人一定要做歷史消息裁剪// 取最近20條消息再估算一下token量如果太大就截掉更早的 history getHistory() maxHistory history.slice(-20) // token量粗估中文字符約1.5個(gè)token/字英文約0.3個(gè)token/字 totalTokens estimateTokens(maxHistory) while totalTokens 800000 { maxHistory maxHistory.slice(1) // 去掉最早的一條 totalTokens estimateTokens(maxHistory) }注意這個(gè)裁剪邏輯要放在請(qǐng)求發(fā)送前而不是等到服務(wù)端報(bào)400后才處理。一次成功的集成調(diào)用應(yīng)該在客戶端就把這種可預(yù)測(cè)的問(wèn)題提前消化掉。5.3 從熱搜里的真實(shí)報(bào)錯(cuò)學(xué)到的排查習(xí)慣再看另一條常見(jiàn)的報(bào)錯(cuò)模板{code:api_key_required,message:api key is required in authorization header}這條報(bào)錯(cuò)直白得感人你在Authorization頭里沒(méi)帶API Key。我看到這個(gè)的第一反應(yīng)是查三件事代碼里從來(lái)沒(méi)寫(xiě)headers配置低級(jí)遺漏。寫(xiě)了但變量名拼錯(cuò)了比如配置的是apiKey代碼里取的是apikey。寫(xiě)了但變量的值是空的配置文件加載失敗密鑰壓根沒(méi)讀進(jìn)內(nèi)存。我有個(gè)笨但有效的習(xí)慣在發(fā)起請(qǐng)求前一幀把請(qǐng)求對(duì)象完整地打印到日志里。注意密鑰本身要打碼sk-xxxx...后四位但其他信息全部打印。這樣一旦報(bào)錯(cuò)直接看日志就能確認(rèn)請(qǐng)求頭到底帶沒(méi)帶Key、URL是不是正確省去一層一層猜的功夫。5.4 免費(fèi)WebService接口的特別提醒熱搜里有一條免費(fèi)webservice接口這類接口尤其適合新手練手但我要提醒幾句。免費(fèi)的接口通常有嚴(yán)格的調(diào)用頻率限制比如每分鐘最多10次。你寫(xiě)循環(huán)測(cè)試的時(shí)候一定要在循環(huán)里加sleep控制節(jié)奏別一口氣發(fā)50個(gè)請(qǐng)求等著被限流。另外免費(fèi)接口的穩(wěn)定性不要抱太高期望——我見(jiàn)過(guò)免費(fèi)的天氣接口一到節(jié)假日就掛掛幾天都沒(méi)人修。所以在SMP里調(diào)用這類接口一定要把接口不可用當(dāng)成正常分支處理而不是直接讓整個(gè)程序報(bào)錯(cuò)崩潰。我在代碼里給這類接口單獨(dú)做了一層降級(jí)緩存調(diào)用成功就把結(jié)果緩存10分鐘調(diào)用失敗時(shí)如果緩存里有舊數(shù)據(jù)就用舊數(shù)據(jù)頂替而不是直接返回錯(cuò)誤給用戶。這樣即使上游免費(fèi)接口抽風(fēng)用戶感知不到任何異常。6. 設(shè)計(jì)接口時(shí)的工程紀(jì)律——寫(xiě)給正在把SMP用于真實(shí)項(xiàng)目的你最后一部分不講具體語(yǔ)法講紀(jì)律。接口這東西一頭連著文檔一頭連著代碼再一頭連著所有調(diào)用方。你的紀(jì)律性有多強(qiáng)你的接口質(zhì)量就有多高。6.1 接口設(shè)計(jì)清單發(fā)布前過(guò)一遍我自己的項(xiàng)目規(guī)范里有一張接口發(fā)布檢查清單每次上線新接口前逐條打鉤已經(jīng)用了很久[ ] 接口命名是否有明確的領(lǐng)域前綴會(huì)不會(huì)與其他模塊沖突[ ] 入?yún)⑹欠衩總€(gè)字段都定義了類型、是否允許為空、枚舉值是否列全[ ] 返回值是否區(qū)分了成功、參數(shù)錯(cuò)誤、業(yè)務(wù)錯(cuò)誤、系統(tǒng)異常四類情況[ ] 是否定義了冪等字段創(chuàng)建、下單、轉(zhuǎn)賬類接口必須有[ ] 是否設(shè)置了超時(shí)時(shí)間[ ] 是否對(duì)下游異常做了降級(jí)預(yù)案[ ] 字段命名是否統(tǒng)一風(fēng)格全駝峰或全下劃線禁止混用表格形式的檢查清單看著刻板但它確實(shí)幫我攔下過(guò)很多次想當(dāng)然。尤其那個(gè)字段命名混用的問(wèn)題幾乎是跨團(tuán)隊(duì)協(xié)作時(shí)最常見(jiàn)的內(nèi)耗來(lái)源——你定義的是order_id調(diào)用方按orderId傳然后兩邊各花半小時(shí)排查為什么取不到值。6.2 API文檔即代碼讓文檔跟著接口走SMP平臺(tái)一個(gè)很好用的特性是支持從接口聲明的注釋直接生成文檔。這就意味著你花了心思寫(xiě)的那份接口聲明本身就是文檔不需要再另維護(hù)一份Word或在線表格。我的習(xí)慣是在接口聲明的注釋里寫(xiě)清楚三件事這個(gè)接口解決什么問(wèn)題——一句話說(shuō)清。典型調(diào)用場(chǎng)景——讓后來(lái)的查詢者快速理解。注意事項(xiàng)——包括但不限于重復(fù)請(qǐng)求會(huì)返回duptrue、該接口依賴外部XX服務(wù)可能失敗。好的接口文檔不是字段清單的堆砌而是告訴后來(lái)的人這里有什么坑。6.3 接口版本管理朝前兼容比破而后立更重要一旦接口被多個(gè)調(diào)用方使用你改接口的任何入?yún)⒒蚍祷刂刀枷喈?dāng)于強(qiáng)制所有人同步升級(jí)。為了不被人背后罵建議從一開(kāi)始就引入版本管理。最輕量的做法是在接口名上加版本號(hào)后綴或字段標(biāo)志interface orderService_create_v2 { ... } interface orderService_create_v1 { ... }新版本接口和舊版本接口可以共存舊調(diào)用方繼續(xù)走v1新調(diào)用方接入v2等到確認(rèn)沒(méi)有任何調(diào)用方再使用v1了才考慮下線。這個(gè)灰度切換比一次性強(qiáng)制升級(jí)要平滑得多。還有一種做法是在HTTP路徑里帶版本號(hào)比如/api/v1/和/api/v2/同時(shí)存在。這種做法對(duì)外部調(diào)用方最友好路徑即是版本不用在業(yè)務(wù)字段里區(qū)分。6.4 接口設(shè)計(jì)的最終判斷標(biāo)準(zhǔn)最后分享一個(gè)我自己衡量接口設(shè)計(jì)好壞的土辦法把接口文檔發(fā)給一個(gè)從未參與開(kāi)發(fā)的人看讓他在不提問(wèn)的情況下按文檔寫(xiě)一個(gè)模擬調(diào)用。如果他一次就寫(xiě)對(duì)了說(shuō)明你的接口定義合格如果他反復(fù)來(lái)問(wèn)這個(gè)字段什么意思這個(gè)參數(shù)是必填嗎說(shuō)明文檔和定義還有改善空間。這個(gè)土辦法看起來(lái)浪費(fèi)時(shí)間其實(shí)價(jià)值極高。因?yàn)榻涌诘谋举|(zhì)是讓別人用起來(lái)舒服而不是讓自己寫(xiě)起來(lái)省事。很多工程師習(xí)慣站在實(shí)現(xiàn)者的角度定義接口——參數(shù)越少越好邏輯越簡(jiǎn)單越好。但從調(diào)用方的角度參數(shù)的意義清晰、邊界明確、錯(cuò)誤信息有指導(dǎo)性才是真正的好接口。我自己經(jīng)歷過(guò)的轉(zhuǎn)變是剛開(kāi)始寫(xiě)接口總覺(jué)得接口是給自己寫(xiě)的方便就行后來(lái)被幾個(gè)外部調(diào)用方配合過(guò)之后才明白接口是一個(gè)服務(wù)型產(chǎn)品調(diào)用方才是它的用戶。換到那個(gè)視角之后我對(duì)字段命名、文檔注釋和錯(cuò)誤信息的重視程度明顯上了一個(gè)臺(tái)階。寫(xiě)了這么多其實(shí)核心就一句話SMP語(yǔ)言里的接口和API說(shuō)到底是約束和服務(wù)的結(jié)合體。定義約束時(shí)越嚴(yán)謹(jǐn)提供服務(wù)時(shí)就越穩(wěn)定。希望這講的內(nèi)容能幫你少走一些彎路——至少別像我那次拼錯(cuò)參數(shù)名一樣在一個(gè)字段上浪費(fèi)大半個(gè)晚上。下次再遇到400、401這類報(bào)錯(cuò)的時(shí)候可以先按照我分享的排查順序走一遍大概率比你自己從頭猜要快。