先說(shuō)一個(gè)我自己的感受大部分代碼腐化不是從業(yè)務(wù)邏輯開(kāi)始的而是從“依賴了一個(gè)不該依賴的外部接口”開(kāi)始的。很多時(shí)候我們寫(xiě)功能特別順手直接調(diào)第三方SDK、老系統(tǒng)接口、或者另一個(gè)團(tuán)隊(duì)的服務(wù)參數(shù)照著文檔填異常隨手拋?zhàn)侄沃苯佑门芷饋?lái)沒(méi)問(wèn)題就算完事。直到某一天外部服務(wù)升級(jí)協(xié)議、換了返回結(jié)構(gòu)、或者干脆下線舊接口你才發(fā)現(xiàn)自己系統(tǒng)里有幾十處調(diào)用在跟著改而且每一處都改得提心吊膽。適配器模式要解決的核心問(wèn)題就是把這種“變化”隔離在系統(tǒng)邊界之外。它的思想很簡(jiǎn)單讓業(yè)務(wù)代碼只依賴自己定義的穩(wěn)定接口而把所有外部的東西塞進(jìn)一個(gè)適配層里由適配層去消化變化、翻譯差異、轉(zhuǎn)換模型。這篇文章我不會(huì)從類(lèi)圖開(kāi)始講因?yàn)橹v類(lèi)圖的資料已經(jīng)夠多了。我想結(jié)合這些年做接口對(duì)接、老系統(tǒng)改造的真實(shí)經(jīng)驗(yàn)把適配器到底隔離什么、為什么值得用、怎么一步步落地以及最容易把自己繞進(jìn)去的幾個(gè)坑全部攤開(kāi)說(shuō)清楚。適合正在接第三方服務(wù)的開(kāi)發(fā)適合在維護(hù)老系統(tǒng)的團(tuán)隊(duì)也適合做設(shè)計(jì)決策時(shí)擔(dān)心“改一處炸一片”的架構(gòu)師參考。1. 先弄明白“變化”是什么適配器才不是空談1.1 適配器真正在處理的三種變化很多講適配器模式的文章一上來(lái)就畫(huà)三個(gè)類(lèi)名然后說(shuō)“這就是適配器”但看完你會(huì)發(fā)現(xiàn)還是不知道在項(xiàng)目里哪里該用。問(wèn)題就出在沒(méi)有先回答一個(gè)更根本的問(wèn)題適配器到底在隔離什么“變化”根據(jù)我自己的項(xiàng)目經(jīng)驗(yàn)它要處理的“變化”主要有三類(lèi)。第一類(lèi)是外部依賴自身的演進(jìn)。第三方服務(wù)升級(jí)版本、調(diào)整參數(shù)名、增加鑒權(quán)方式、甚至直接下線某個(gè)老接口這些都不是你能控制的。你唯一能控制的是自己系統(tǒng)內(nèi)部的改動(dòng)范圍。如果沒(méi)有適配層這種變化就會(huì)順著調(diào)用鏈一路傳染到所有業(yè)務(wù)模塊里。第二類(lèi)是同類(lèi)外部服務(wù)之間的差異。比如你接了兩家云存儲(chǔ)、兩個(gè)短信服務(wù)商或者多個(gè)支付渠道。它們做的是同一類(lèi)事情但API風(fēng)格、數(shù)據(jù)結(jié)構(gòu)、鑒權(quán)方式、錯(cuò)誤碼體系統(tǒng)統(tǒng)不一樣。適配器在這里的角色像是把“各國(guó)插座標(biāo)準(zhǔn)”統(tǒng)一成“我們內(nèi)部的插頭規(guī)格”讓上層代碼看到的永遠(yuǎn)是同一個(gè)樣子。第三類(lèi)是外部模型和內(nèi)部模型之間的差異。外部SDK可能用“分”做金額單位業(yè)務(wù)系統(tǒng)用“元”外部狀態(tài)碼是“0成功、1失敗、2處理中”業(yè)務(wù)系統(tǒng)理解的是“SUCCESS、FAILED、PROCESSING”外部訂單號(hào)帶有廠商前綴而內(nèi)部訂單號(hào)有自己的長(zhǎng)度限制。這些差異看著小但如果散落在每個(gè)調(diào)用點(diǎn)每次轉(zhuǎn)換都可能出錯(cuò)。適配器模式之所以叫“適配器”就是因?yàn)樗鼘ｉT(mén)用來(lái)解決“接口形態(tài)不匹配”的問(wèn)題。它不去改變外部系統(tǒng)的行為也不改變自己系統(tǒng)的業(yè)務(wù)規(guī)則它在中間做翻譯兩邊都保持原樣。這和一個(gè)電源轉(zhuǎn)換頭的邏輯完全一樣——墻上的插座不會(huì)變你的設(shè)備插頭也不會(huì)變中間加一個(gè)轉(zhuǎn)接頭就都能用了。1.2 適配器模式的結(jié)構(gòu)一句話說(shuō)清楚適配器的標(biāo)準(zhǔn)結(jié)構(gòu)里有四個(gè)角色但真正理解它只需要抓住一句話調(diào)用方依賴自己的端口接口適配器負(fù)責(zé)把外部接口嫁接到這個(gè)端口上。Target也就是端口Port是調(diào)用方真正依賴的抽象接口由你系統(tǒng)內(nèi)部定義語(yǔ)義也必須由你來(lái)定。比如PaymentPort。Adaptee被適配的現(xiàn)有對(duì)象可能是第三方SDK、遺留系統(tǒng)的遠(yuǎn)程接口、或者另一個(gè)服務(wù)暴露的API。Adapter適配器本體實(shí)現(xiàn)Target接口內(nèi)部包裝Adaptee把外部調(diào)用轉(zhuǎn)成內(nèi)部語(yǔ)義。Client使用Target接口的業(yè)務(wù)代碼它完全不感知Adaptee的存在。這里的關(guān)鍵是端口接口的定義權(quán)必須在自己手里。如果你直接把外部SDK暴露出來(lái)的接口當(dāng)成本系統(tǒng)接口讓所有業(yè)務(wù)代碼去編譯依賴它那這個(gè)SDK的任何一個(gè)變化都會(huì)變成你的系統(tǒng)變化。反過(guò)來(lái)如果你先定義了業(yè)務(wù)真正需要的接口再讓適配器去適配外面的世界再怎么變業(yè)務(wù)代碼的編譯產(chǎn)物都可以一動(dòng)不動(dòng)。1.3 適配器和防腐層的關(guān)系聊適配器的時(shí)候經(jīng)常會(huì)冒出來(lái)另一個(gè)詞防腐層。很多人把它們當(dāng)成一回事實(shí)際上粒度不一樣。防腐層是領(lǐng)域驅(qū)動(dòng)設(shè)計(jì)里常用的一個(gè)邊界概念它保護(hù)核心領(lǐng)域不受外部上下文污染除了接口轉(zhuǎn)換還會(huì)包含協(xié)議翻譯、數(shù)據(jù)校驗(yàn)、模型映射、外部服務(wù)的開(kāi)關(guān)與容錯(cuò)。適配器是防腐層最常見(jiàn)的落地手段之一但防腐層更強(qiáng)調(diào)“邊界”適配器更強(qiáng)調(diào)“轉(zhuǎn)換”。你完全可以在一個(gè)防腐層里面放多個(gè)適配器分別對(duì)應(yīng)不同的外部服務(wù)。也可以只做一個(gè)適配器哪怕它只承擔(dān)了一次協(xié)議轉(zhuǎn)換。它們不是替代關(guān)系而是層次關(guān)系。把這個(gè)概念理清楚之后你再看網(wǎng)上的爭(zhēng)議文章就會(huì)發(fā)現(xiàn)絕大多數(shù)爭(zhēng)論都是因?yàn)榘堰@兩個(gè)概念混在一起了。我在做邊界設(shè)計(jì)時(shí)一般會(huì)先識(shí)別“哪里是防腐邊界”再?zèng)Q定“邊界上需要幾個(gè)適配器”順序不要反。2. 為什么說(shuō)隔離變化比消滅變化更務(wù)實(shí)2.1 你能控制的范圍往往比想象中小很多剛工作沒(méi)幾年的同學(xué)都有一個(gè)理想化的習(xí)慣看到外部接口不順眼就想著讓外部團(tuán)隊(duì)改改到符合自己的使用習(xí)慣。比如字段命名不規(guī)范、狀態(tài)碼含義模糊、沒(méi)有超時(shí)控制、文檔更新滯后。這些問(wèn)題確實(shí)存在但現(xiàn)實(shí)是外部系統(tǒng)是別的團(tuán)隊(duì)在維護(hù)它的演進(jìn)節(jié)奏不會(huì)為你的適配感負(fù)責(zé)。老系統(tǒng)改造的場(chǎng)景里更明顯。遺留系統(tǒng)的接口不能動(dòng)因?yàn)檫€有大量老業(yè)務(wù)依賴數(shù)據(jù)表結(jié)構(gòu)不能改因?yàn)閹装賯€(gè)查詢都在用。你能做的只有在新系統(tǒng)和老系統(tǒng)之間加一層翻譯。所以我在多次實(shí)踐中把設(shè)計(jì)心態(tài)理順了隔離變化不是消滅變化消滅變化是幻想隔離變化才是工程。外部世界你改不了你能控制的是把外部變化的影響控制在一個(gè)薄層里讓它不要在核心業(yè)務(wù)里到處流竄。這就是適配器最大的價(jià)值也是“隔離”二字的真正含義。2.2 隔離帶來(lái)的三個(gè)具體好處第一是可測(cè)試。業(yè)務(wù)代碼依賴的是自己定義的端口接口你完全可以在單元測(cè)試?yán)镉靡粋€(gè)模擬實(shí)現(xiàn)替代真實(shí)的第三方調(diào)用。不需要起動(dòng)外部服務(wù)不需要準(zhǔn)備真實(shí)的測(cè)試賬號(hào)更不需要擔(dān)心測(cè)試環(huán)境網(wǎng)絡(luò)抖動(dòng)。這一點(diǎn)在寫(xiě)業(yè)務(wù)單測(cè)的時(shí)候非常舒服你會(huì)發(fā)現(xiàn)業(yè)務(wù)模塊的測(cè)試基本不需要再M(fèi)ock外部SDK了端口后面掛的本來(lái)就是假實(shí)現(xiàn)。第二是可替換。哪天你發(fā)現(xiàn)當(dāng)前的外部服務(wù)費(fèi)用太高、穩(wěn)定性太差、或者不再維護(hù)要切換到另一個(gè)同類(lèi)服務(wù)理論上只需要寫(xiě)一個(gè)新的適配器換上去業(yè)務(wù)代碼一行都不用動(dòng)。我在現(xiàn)實(shí)中經(jīng)歷過(guò)一次支付渠道切換整個(gè)切換花了三天其中兩天半在寫(xiě)新適配器業(yè)務(wù)側(cè)真正改動(dòng)的代碼收斂在兩個(gè)配置項(xiàng)和一個(gè)開(kāi)關(guān)上。如果沒(méi)有適配層這個(gè)時(shí)間至少要放大五倍。第三是可演進(jìn)。因?yàn)槎丝诮涌诘恼Z(yǔ)義是業(yè)務(wù)側(cè)的你可以讓接口向著自己系統(tǒng)的業(yè)務(wù)語(yǔ)言進(jìn)化。比如你可以在端口里定義一個(gè)queryTransferStatus方法而外部SDK可能叫g(shù)etTrade(queryOrderRequest)。名字不重要重要的是業(yè)務(wù)代碼讀起來(lái)像業(yè)務(wù)而不是像接口文檔。系統(tǒng)的長(zhǎng)期維護(hù)性很大程度就體現(xiàn)在這種“業(yè)務(wù)代碼能否自解釋”上。2.3 適配器不是銀彈什么時(shí)候不該上隔離變化很香但不是所有場(chǎng)景都要上適配器。如果外部接口非常穩(wěn)定、改動(dòng)頻率極低、系統(tǒng)生命周期又短那硬套一層適配器反而是過(guò)度設(shè)計(jì)的開(kāi)始。我曾經(jīng)接手過(guò)一個(gè)內(nèi)部工具項(xiàng)目里面調(diào)了一個(gè)登錄服務(wù)接口三年沒(méi)變過(guò)但前任硬是給這個(gè)登錄服務(wù)加了三層接口抽象、適配器、封裝Facade每個(gè)方法都是三層轉(zhuǎn)發(fā)。結(jié)果代碼可讀性極差調(diào)試一個(gè)問(wèn)題要跨三層斷點(diǎn)。判斷標(biāo)準(zhǔn)我用一個(gè)公式變化概率乘以影響范圍。只有在你判斷這個(gè)外部依賴有較大概率會(huì)變或者影響范圍很大時(shí)適配器才物有所值。給“永遠(yuǎn)不會(huì)變的只讀服務(wù)”加適配器跟“為了明天可能下雨就買(mǎi)一輛水陸兩用車(chē)”差不多。別為虛構(gòu)的明天設(shè)計(jì)這是隔離變化設(shè)計(jì)里最需要克制的一點(diǎn)。3. 核心實(shí)戰(zhàn)場(chǎng)景第三方支付接口的適配層設(shè)計(jì)3.1 場(chǎng)景還原為什么不能直接調(diào)SDK我拿一個(gè)最常見(jiàn)的場(chǎng)景舉例給業(yè)務(wù)系統(tǒng)接入在線支付。一開(kāi)始你對(duì)接了某個(gè)支付服務(wù)商它的SDK提供了下單、退款、查詢等方法。業(yè)務(wù)團(tuán)隊(duì)為了趕工期直接在訂單模塊、退款模塊里四處調(diào)用這個(gè)SDK。一開(kāi)始沒(méi)什么問(wèn)題但很快你發(fā)現(xiàn)幾個(gè)隱患SDK的請(qǐng)求對(duì)象和響應(yīng)對(duì)象到處出現(xiàn)在業(yè)務(wù)代碼里代碼被第三方實(shí)現(xiàn)深度“綁架”異常處理不一致有的地方直接拋ThirdApiException有的地方捕獲后翻譯成自己的錯(cuò)誤碼風(fēng)格混亂退款和下單的返回狀態(tài)語(yǔ)義不統(tǒng)一有的接口返回“成功”是指“提交成功”有的是“處理成功”。一旦業(yè)務(wù)代碼散落著外部SDK的類(lèi)型換服務(wù)商或者升級(jí)SDK就會(huì)變成一場(chǎng)災(zāi)難。你必須在每個(gè)調(diào)用點(diǎn)去核對(duì)第三方返回值、異常類(lèi)型、字段映射稍微漏一個(gè)地方生產(chǎn)環(huán)境就會(huì)冒出一堆詭異問(wèn)題。適配器模式在這里不是可選項(xiàng)而是基本盤(pán)。3.2 端口先行先定義你的系統(tǒng)需要的接口正確做法是先忘掉那個(gè)支付SDK回到業(yè)務(wù)本身。問(wèn)一個(gè)問(wèn)題訂單系統(tǒng)、退款系統(tǒng)、賬務(wù)系統(tǒng)它們真正需要支付能力做什么答案大多是三件事發(fā)起支付、查詢結(jié)果、發(fā)起退款。于是你定義一個(gè)干凈的業(yè)務(wù)端口public interface PaymentPort { PaymentResult createPayment(PaymentCommand command); PaymentResult queryPayment(String bizOrderNo); PaymentResult refund(PaymentCommand command); }這個(gè)接口有幾個(gè)特點(diǎn)值得注意。第一參數(shù)是我方業(yè)務(wù)模型比如PaymentCommand里有bizOrderNo內(nèi)部訂單號(hào)、amountBigDecimal元、paySubject商品描述而不是第三方SDK里的供應(yīng)商編號(hào)、分單位金額、渠道編號(hào)等概念。第二返回值統(tǒng)一成PaymentResult業(yè)務(wù)層只用code、message、外部交易號(hào)即可不需要理會(huì)第三方的各種回調(diào)數(shù)據(jù)結(jié)構(gòu)。第三方法簽名以業(yè)務(wù)語(yǔ)義命名閱讀代碼的人不會(huì)產(chǎn)生理解偏差。我把這樣的接口稱為“端口”因?yàn)樗菢I(yè)務(wù)領(lǐng)域和外部世界之間一條定義明確的連接線。端口里面聲明什么、不聲明什么直接決定了后面變化侵入系統(tǒng)的面積。3.3 適配器實(shí)現(xiàn)的關(guān)鍵代碼有了端口接下來(lái)寫(xiě)支付服務(wù)商的適配器。適配器的職責(zé)就是把外部SDK的調(diào)用方式“翻譯”成端口定義的方式。我給出一個(gè)典型骨架語(yǔ)言用Java描述其他語(yǔ)言的思路完全一致public class PayProviderXAdapter implements PaymentPort { private final PayProviderXClient client; public PayProviderXAdapter(PayProviderXClient client) { this.client client; } Override public PaymentResult createPayment(PaymentCommand command) { try { BuildPayRequest req new BuildPayRequest(); // 單位轉(zhuǎn)換元 - 分 req.setAmount(toCents(command.getAmount())); req.setBizOrderNo(command.getBizOrderNo()); req.setSubject(command.getPaySubject()); PayResponse resp client.pay(req); return PaymentResult.of(resp.isSuccess(), codeOf(resp.getStatus()), resp.getTradeNo()); } catch (PayProviderXTimeoutException e) { // 外部超時(shí)理論上訂單狀態(tài)未知需要查詢確認(rèn)不能直接算失敗 throw new PaymentPortUncertainException(provider timeout, e); } catch (PayProviderXRejectedException e) { // 業(yè)務(wù)拒絕余額不足、風(fēng)控?cái)r截等 throw new PaymentPortBusinessException(e.getMessage(), e); } } Override public PaymentResult refund(PaymentCommand command) { // 同樣的翻譯邏輯 } }你別小看這個(gè)代碼片段里面每一個(gè)細(xì)節(jié)都是在實(shí)戰(zhàn)中打磨出來(lái)的。金額單位必須在這里轉(zhuǎn)一次避免業(yè)務(wù)層到處做“元轉(zhuǎn)分”。外部超時(shí)不能簡(jiǎn)單當(dāng)作失敗因?yàn)榈谌娇赡芤呀?jīng)扣款成功了所以拋出一個(gè)“不確定”異常讓上層走查詢補(bǔ)償流程。第三方業(yè)務(wù)拒絕要翻譯成業(yè)務(wù)拒絕讓上層能拿到可讀的錯(cuò)誤語(yǔ)義。這些決策看起來(lái)很瑣碎但它們決定了整個(gè)系統(tǒng)的邊界質(zhì)量。3.4 模擬適配器不只是測(cè)試玩具按同樣的端口再寫(xiě)一個(gè)模擬適配器public class MockPaymentPort implements PaymentPort { Override public PaymentResult createPayment(PaymentCommand command) { if (1.equals(command.getBizOrderNo())) { // 模擬一個(gè)被風(fēng)控拒絕的場(chǎng)景 throw new PaymentPortBusinessException(mock risk reject); } return PaymentResult.of(true, TRADE_SUCCESS, MOCK command.getBizOrderNo()); } Override public PaymentResult refund(PaymentCommand command) { return PaymentResult.of(true, SUCCESS, MOCK_REFUND command.getBizOrderNo()); } }很多人把模擬適配器只當(dāng)成單元測(cè)試的玩具其實(shí)它的價(jià)值遠(yuǎn)不止測(cè)試。在前后端并行開(kāi)發(fā)、聯(lián)調(diào)環(huán)境不穩(wěn)定的時(shí)候業(yè)務(wù)模塊可以直接掛上模擬適配器先跑通流程等真實(shí)服務(wù)準(zhǔn)備好了再切換過(guò)去。想模擬第三方超時(shí)、風(fēng)控拒絕、重復(fù)回調(diào)都能在模擬實(shí)現(xiàn)里輕松構(gòu)造。我自己在項(xiàng)目里還會(huì)給模擬適配器加上延遲參數(shù)用來(lái)模擬真實(shí)網(wǎng)絡(luò)延遲讓前端體驗(yàn)接近真實(shí)的交互耗時(shí)。需要注意的是模擬適配器不能偷偷留在生產(chǎn)環(huán)境里。它在開(kāi)發(fā)環(huán)境是利器在生產(chǎn)環(huán)境就是事故導(dǎo)火索。我見(jiàn)過(guò)一個(gè)團(tuán)隊(duì)測(cè)試完忘改配置導(dǎo)致線上支付流程走的是模擬通道雖然最終沒(méi)有真扣款但對(duì)用戶已經(jīng)造成了明顯業(yè)務(wù)影響。所以切換邏輯要干凈最好通過(guò)配置中心控制并且配置變更要帶上線審批和監(jiān)控告警。4. 完整實(shí)操過(guò)程從一個(gè)老系統(tǒng)開(kāi)始做適配改造4.1 第一步梳理調(diào)用點(diǎn)找到變與不變的分界線做適配改造尤其是給老系統(tǒng)做改造不能上來(lái)就寫(xiě)抽象接口得先盤(pán)點(diǎn)現(xiàn)狀。我通常會(huì)做三件事找出所有第三方調(diào)用點(diǎn)列出外部接口的參數(shù)和返回結(jié)構(gòu)再標(biāo)記哪些字段是業(yè)務(wù)真正關(guān)心的。在調(diào)用點(diǎn)梳理過(guò)程中你會(huì)發(fā)現(xiàn)一個(gè)規(guī)律同一個(gè)外部接口常常被多個(gè)模塊反復(fù)調(diào)用而且每個(gè)模塊對(duì)返回結(jié)果的使用方式還不一樣。有的模塊關(guān)心外部單號(hào)有的關(guān)心狀態(tài)碼有的關(guān)心金額有的只關(guān)心是否成功。這些使用者都是你定義端口的參考對(duì)象。變與不變的分界線怎么找我建議以“業(yè)務(wù)世界”為準(zhǔn)。業(yè)務(wù)不關(guān)心第三方SDK怎么傳參它只關(guān)心“支付發(fā)起成功沒(méi)有”“退款到賬沒(méi)有”。所以端口接口應(yīng)該表達(dá)業(yè)務(wù)狀態(tài)而不應(yīng)該表達(dá)外部調(diào)用。簡(jiǎn)單說(shuō)如果你的端口方法簽名里出現(xiàn)了某個(gè)具體供應(yīng)商的名稱、字段、錯(cuò)誤碼那這個(gè)端口就沒(méi)有設(shè)計(jì)到位。4.2 第二步寫(xiě)適配器骨架把轉(zhuǎn)換規(guī)則列成表格動(dòng)手寫(xiě)編碼之前先把轉(zhuǎn)換規(guī)則列出來(lái)。我習(xí)慣在項(xiàng)目文檔里維護(hù)三張表形式類(lèi)似這樣業(yè)務(wù)字段端口側(cè)供應(yīng)商字段SDK側(cè)轉(zhuǎn)換規(guī)則bizOrderNoout_trade_no直接映射amount元amount分乘以100取整paySubjectbody截?cái)嗟?28字符供應(yīng)商返回狀態(tài)業(yè)務(wù)狀態(tài)說(shuō)明TRADE_SUCCESSSUCCESS明確成功TRADE_CLOSEDFAILED系統(tǒng)關(guān)閉WAIT_BUYER_PAYPROCESSING等待支付UNKNOWNUNCERTAIN需查詢確認(rèn)異常類(lèi)型業(yè)務(wù)異常后續(xù)處理建議超時(shí)異常UncertaintyException發(fā)起查詢或?qū)~業(yè)務(wù)拒絕BusinessException提示用戶簽名異常InfraException告警檢查配置限流錯(cuò)誤RetryableException延遲重試或降級(jí)有了這三張表適配器的代碼寫(xiě)起來(lái)就是純粹的“翻譯”不太容易漏邏輯。更重要的是這三張表沉淀下來(lái)之后下一次換供應(yīng)商新適配器的開(kāi)發(fā)會(huì)快很多因?yàn)闃I(yè)務(wù)側(cè)要什么已經(jīng)是確定的只需填表映射。4.3 第三步異常翻譯與監(jiān)控埋點(diǎn)適配器里最容易忽略的不是主流程而是異常翻譯。很多代碼在外層兜底捕獲了一個(gè)Exception卻不知道怎么處理。真實(shí)的情況是外部異常至少分四類(lèi)技術(shù)異常超時(shí)、連接失敗、簽名錯(cuò)誤、業(yè)務(wù)異常余額不足、風(fēng)控拒絕、狀態(tài)不確定異常請(qǐng)求超時(shí)但可能已經(jīng)處理、編程異常參數(shù)非法、配置錯(cuò)誤。這四類(lèi)異常在上層看來(lái)處理策略完全不同不能在適配器里一鍋燴成RuntimeException。我處理的原則是端口接口只拋業(yè)務(wù)語(yǔ)義的異常。適配器要對(duì)每一種外部錯(cuò)誤做翻譯把技術(shù)異常包裝成基礎(chǔ)設(shè)施異常把業(yè)務(wù)異常翻譯成業(yè)務(wù)錯(cuò)誤把不確定異常單獨(dú)建模。這會(huì)讓上層代碼的錯(cuò)誤處理邏輯變得很清晰而不會(huì)出現(xiàn)上層到處 catch 第三方異常類(lèi)的情況。監(jiān)控埋點(diǎn)在適配器里也比在業(yè)務(wù)層里做更合適。每次調(diào)用記錄耗時(shí)、成功/失敗、失敗原因這些指標(biāo)天然和外部依賴綁定。我在適配器里加了簡(jiǎn)單的計(jì)數(shù)器上線后能直觀看到每個(gè)供應(yīng)商的可用率。一旦某個(gè)供應(yīng)商出問(wèn)題監(jiān)控圖上立刻能看出來(lái)而不是等到業(yè)務(wù)報(bào)障才發(fā)現(xiàn)。4.4 第四步雙實(shí)現(xiàn)切換與回歸測(cè)試?yán)舷到y(tǒng)改造最怕一次性一刀切切過(guò)去就回不來(lái)。我的做法是構(gòu)建雙實(shí)現(xiàn)并存機(jī)制保留舊的直連調(diào)用邏輯新適配器通過(guò)配置開(kāi)關(guān)決定是否啟用。配置中心的開(kāi)關(guān)打開(kāi)后讓一小部分流量先走適配器觀察業(yè)務(wù)指標(biāo)和日志確認(rèn)沒(méi)問(wèn)題再逐步切完。在回歸測(cè)試上我會(huì)重點(diǎn)驗(yàn)證幾類(lèi)場(chǎng)景正常成功鏈路、金額為0的邊界、超時(shí)后重查鏈路、第三方返回業(yè)務(wù)拒絕、重復(fù)退款、回調(diào)亂序。這些測(cè)試用例盡量用模擬適配器來(lái)測(cè)業(yè)務(wù)層用真實(shí)供應(yīng)商小額度來(lái)驗(yàn)證適配器本身。兩者結(jié)合既能保障業(yè)務(wù)邏輯穩(wěn)定又能驗(yàn)證真實(shí)接入正確性。這個(gè)改造過(guò)程看起來(lái)環(huán)節(jié)多但每一步都不難難的是沉住氣把調(diào)用點(diǎn)梳理清楚。很多團(tuán)隊(duì)改造失敗不是適配器寫(xiě)得有問(wèn)題而是根本沒(méi)盤(pán)點(diǎn)清楚哪些地方在用外部接口結(jié)果切配置之后漏了幾個(gè)調(diào)用點(diǎn)導(dǎo)致線上出現(xiàn)問(wèn)題。5. 踩坑實(shí)錄適配器寫(xiě)歪了以后的樣子5.1 坑一適配器里堆滿業(yè)務(wù)規(guī)則適配器最典型的腐爛方式就是寫(xiě)著寫(xiě)著把業(yè)務(wù)規(guī)則也塞進(jìn)去了。比如外部狀態(tài)為SUCCESS時(shí)適配器里順便做了一個(gè)“如果訂單金額大于1000元就走人工審核”的判斷或者適配器里直接操作了數(shù)據(jù)庫(kù)修改訂單狀態(tài)。這些規(guī)則一旦埋進(jìn)適配器就會(huì)變得難以測(cè)試、難以復(fù)用還會(huì)讓適配器層變成一個(gè)新的“大泥球”。為什么會(huì)出現(xiàn)這個(gè)坑因?yàn)閷?xiě)代碼的時(shí)候覺(jué)得這個(gè)判斷順手放這里最方便不用再去改別的類(lèi)。代價(jià)是邊界被悄悄模糊了適配器不再是純粹的翻譯層而是承擔(dān)了業(yè)務(wù)編排職責(zé)。我的糾偏經(jīng)驗(yàn)是給適配器設(shè)定一個(gè)紀(jì)律它只能做四件事——參數(shù)映射、調(diào)用外部服務(wù)、響應(yīng)映射、異常翻譯。任何超出這四件事的邏輯一律放到適配器之外的業(yè)務(wù)服務(wù)里。評(píng)判標(biāo)準(zhǔn)很簡(jiǎn)單如果適配器里出現(xiàn)“if 金額 xxx”這類(lèi)業(yè)務(wù)分支就該重構(gòu)。5.2 坑二把外部異常直接拋給上層還有一個(gè)非常常見(jiàn)的坑就是適配器捕獲異常之后不做翻譯直接把第三方異常原樣拋出去。外面看日志還好但業(yè)務(wù)模塊的 catch 就遭殃了。業(yè)務(wù)層為了處理第三方異常你得引用對(duì)方的異常類(lèi)型為了拿到錯(cuò)誤詳情你得解析第三方錯(cuò)誤對(duì)象。這等于把外部依賴的細(xì)節(jié)從適配器泄漏給了全部調(diào)用方。我在一個(gè)遺留系統(tǒng)里看過(guò)這樣的代碼業(yè)務(wù)層同時(shí) catch 了兩家供應(yīng)商的異常類(lèi)型還在 switch 里分別處理錯(cuò)誤碼。每加一個(gè)供應(yīng)商業(yè)務(wù)層就要加一組 case這就是沒(méi)有做異常翻譯的后果。適配器的異常出口應(yīng)該是自解釋的上層看到一個(gè)PaymentPortBusinessException就知道這是“業(yè)務(wù)可以處理的失敗”看到技術(shù)異常就知道得走降級(jí)邏輯。5.3 坑三適配器實(shí)例狀態(tài)混亂造成線程安全問(wèn)題適配器在大多數(shù)情況下應(yīng)該是無(wú)狀態(tài)的但有些人習(xí)慣在適配器里保存某個(gè)本次請(qǐng)求的上下文比如請(qǐng)求ID、用戶ID。一旦這個(gè)適配器被多個(gè)線程共享這些字段就會(huì)被互相覆蓋輕則日志串號(hào)重則把A用戶的請(qǐng)求參數(shù)拼到B用戶的請(qǐng)求里。我見(jiàn)過(guò)一個(gè)真實(shí)事故適配器里一個(gè)成員變量保存了訂單號(hào)然后業(yè)務(wù)用異步線程池去調(diào)用支付多筆訂單并發(fā)時(shí)訂單號(hào)互相污染導(dǎo)致扣錯(cuò)了款。排查到根因后把成員變量全部改成方法參數(shù)傳遞問(wèn)題才徹底消失。所以要牢記適配器實(shí)例本身是單例擴(kuò)用的臨時(shí)數(shù)據(jù)必須走方法參數(shù)不能存成員變量。如果需要保存請(qǐng)求上下文要使用獨(dú)立的上下文容器而不是直接定義在適配器里。5.4 坑四為適配而適配純粹的過(guò)度設(shè)計(jì)和前面幾個(gè)坑相反還有一種失敗是搞了一堆不必要的抽象。比如系統(tǒng)里只有一個(gè)外部服務(wù)這個(gè)服務(wù)也很穩(wěn)定但設(shè)計(jì)者還是畫(huà)了三層接口配了四個(gè)適配器類(lèi)然后到處聲明“為未來(lái)擴(kuò)展做好準(zhǔn)備”。結(jié)果是任何人讀代碼都要在多層間接里跳來(lái)跳去還沒(méi)等到那個(gè)“未來(lái)”團(tuán)隊(duì)已經(jīng)被維護(hù)成本拖垮了。判斷是不是過(guò)度設(shè)計(jì)我會(huì)看一個(gè)信號(hào)適配器的文件名里是不是全部帶同一個(gè)動(dòng)詞比如XxxAdapter、YyyAdapter、ZzzAdapter但其中至少有兩個(gè)方法體是完全一樣的轉(zhuǎn)發(fā)。如果出現(xiàn)這個(gè)信號(hào)說(shuō)明抽象粒度有問(wèn)題不如先合并或者刪掉一層。5.5 排查適配層問(wèn)題的檢查清單經(jīng)驗(yàn)沉淀后我給團(tuán)隊(duì)整理過(guò)一份適配層自查清單每次代碼評(píng)審都拿出來(lái)對(duì)著過(guò)一遍外部SDK類(lèi)型是否出現(xiàn)在端口接口和業(yè)務(wù)代碼里出現(xiàn)即視為泄漏。適配器里是否存在業(yè)務(wù)分支、數(shù)據(jù)庫(kù)操作、狀態(tài)判斷存在即視為越權(quán)。外部異常類(lèi)是否被上層直接引用參考所有 catch 的異常類(lèi)型。單位轉(zhuǎn)換、字段映射是否只出現(xiàn)一次重復(fù)出現(xiàn)就是隱患。適配器是否可單測(cè)可測(cè)試的標(biāo)準(zhǔn)是不依賴真實(shí)外部服務(wù)。換一個(gè)供應(yīng)商業(yè)務(wù)側(cè)需要改幾行理想答案是0行。這份清單雖然簡(jiǎn)單但能擋住大部分適配層的低級(jí)問(wèn)題。我在多次評(píng)審里發(fā)現(xiàn)真正被攔下來(lái)的代碼問(wèn)題其實(shí)都是這些看起來(lái)基礎(chǔ)的規(guī)則被忽略了。6. 適配器與鄰接模式邊界劃分和配合6.1 策略模式和適配器一起用適配器負(fù)責(zé)把外部接口翻譯成內(nèi)部端口策略模式負(fù)責(zé)讓同一端口下多個(gè)實(shí)現(xiàn)可以靈活選擇。兩者經(jīng)常一起出現(xiàn)。比如你定義了SmsPort然后寫(xiě)了ProviderAAdapter和ProviderBAdapter再按流量比例切換或按地區(qū)路由這就是策略調(diào)適配器。沒(méi)有適配器策略模式的選擇對(duì)象會(huì)變成各種外部SDK接口語(yǔ)義差異會(huì)放大沒(méi)有策略模式你每次想切供應(yīng)商就得改適配器的實(shí)例化代碼。它們的關(guān)注點(diǎn)不同適配器解決的是“長(zhǎng)什么樣”的問(wèn)題策略解決的是“選哪個(gè)”的問(wèn)題。在代碼結(jié)構(gòu)上就是兩層策略層持有端口引用適配器實(shí)現(xiàn)端口。這個(gè)組合幾乎覆蓋了所有“多供應(yīng)商接入”的需求。6.2 門(mén)面與適配器簡(jiǎn)化不等于轉(zhuǎn)譯門(mén)面和適配器經(jīng)常被搞混因?yàn)樗鼈兌伎梢园b某個(gè)復(fù)雜的子系統(tǒng)。區(qū)分方式很簡(jiǎn)單適配器是為了讓“本來(lái)不兼容的接口變得兼容”門(mén)面是為了讓“一堆復(fù)雜的交互變得簡(jiǎn)單”。比如你有一個(gè)短信服務(wù)、一個(gè)郵件服務(wù)、一個(gè)站內(nèi)信服務(wù)然后做一個(gè)通知門(mén)面上層調(diào)一個(gè)send()就完成多渠道通知這是門(mén)面。而針對(duì)其中某一家短息服務(wù)商做協(xié)議翻譯那是適配器。門(mén)面可能沒(méi)有外部兼容問(wèn)題它只是簡(jiǎn)化。適配器則有明確的兩側(cè)協(xié)議不兼容才需要翻譯。在系統(tǒng)設(shè)計(jì)時(shí)常見(jiàn)的情況是門(mén)面后面再掛適配器門(mén)面提供統(tǒng)一入口適配器負(fù)責(zé)對(duì)接不同供應(yīng)商。這兩者的協(xié)作會(huì)讓邊界更清晰但如果混用代碼讀起來(lái)就會(huì)很迷糊。6.3 代理與適配器控制訪問(wèn)與協(xié)議轉(zhuǎn)換代理模式也和適配器很像都持有目標(biāo)對(duì)象都包了一層。但代理的核心目的是控制訪問(wèn)比如延遲加載、訪問(wèn)控制、日志記錄它不改變接口形態(tài)適配器的核心目的是轉(zhuǎn)換接口它必須改變接口形態(tài)。所以在實(shí)現(xiàn)上有一個(gè)簡(jiǎn)單判斷法客戶端拿到的對(duì)象接口和代理持有的目標(biāo)對(duì)象接口是否一致一致是代理不一致是適配器。實(shí)際項(xiàng)目中我也會(huì)把兩者疊起來(lái)先用適配器把外部接口翻譯成內(nèi)部端口然后在適配器外包一層監(jiān)控代理統(tǒng)計(jì)調(diào)用指標(biāo)。這樣適配器仍然專注于翻譯代理專注橫切關(guān)注點(diǎn)各司其職。6.4 模板方法固定適配流程策略處理差異性如果適配多個(gè)供應(yīng)商時(shí)發(fā)現(xiàn)它們的調(diào)用流程高度相似只是細(xì)節(jié)不同可以用模板方法模式把流程固定下來(lái)把差異部分交給子類(lèi)實(shí)現(xiàn)。比如不管是哪個(gè)支付服務(wù)商調(diào)用流程都是“組裝請(qǐng)求、發(fā)請(qǐng)求、解析響應(yīng)、處理異?！敝皇墙M裝方式不同、解析方式不同。做成一個(gè)抽象的BasePaymentAdapter提供process()模板子類(lèi)只需實(shí)現(xiàn)buildRequest()和parseResponse()能大幅減少重復(fù)代碼。但這個(gè)優(yōu)化有兩個(gè)前提流程確實(shí)高度一致并且你有多個(gè)適配器。如果只有兩個(gè)適配器模板方法也可以但一定要警惕“為了復(fù)用而硬抽出公共父類(lèi)”那會(huì)讓父子類(lèi)關(guān)系變得很別扭。做過(guò)的系統(tǒng)越多我越發(fā)現(xiàn)一個(gè)規(guī)律真正讓項(xiàng)目長(zhǎng)期穩(wěn)定的往往不是復(fù)雜的業(yè)務(wù)模型而是這些看起來(lái)不起眼的隔離層。適配器就是典型代表它的實(shí)現(xiàn)成本不高收益卻非常直接——外部世界再亂業(yè)務(wù)代碼依然可以保持自己的語(yǔ)言和節(jié)奏。我的建議是在項(xiàng)目里第一次出現(xiàn)“后面可能要換供應(yīng)商”“這個(gè)接口是別的團(tuán)隊(duì)維護(hù)的”這種話時(shí)就順手把適配器建起來(lái)。就算最終沒(méi)換成你也會(huì)得到一個(gè)更干凈的測(cè)試接口和一個(gè)更容易解釋的系統(tǒng)邊界。設(shè)計(jì)這東西很多時(shí)候圖的就是關(guān)鍵時(shí)刻不用抓瞎。