貨運(yùn)行業(yè)做SaaS和做普通企業(yè)管理系統(tǒng)最大的區(qū)別在哪里我先把話說(shuō)在前面不是功能堆得多而是架構(gòu)扛得住。一套系統(tǒng)要同時(shí)服務(wù)幾十上百家物流公司每家公司看到的都是自己的訂單、自己的司機(jī)、自己的賬單可底層跑的是同一套代碼、同一個(gè)數(shù)據(jù)庫(kù)集群——這種“看起來(lái)各用各的、實(shí)際上共用一套”的玩法就是多租戶架構(gòu)要解決的核心問(wèn)題。這篇博文圍繞我實(shí)際落地的一個(gè)SaaS化貨運(yùn)平臺(tái)展開(kāi)重點(diǎn)拆兩層內(nèi)容一是多租戶架構(gòu)從租戶識(shí)別、數(shù)據(jù)隔離到權(quán)限控制的完整鏈路怎么設(shè)計(jì)二是訂單中心、計(jì)費(fèi)中心、運(yùn)力池這三個(gè)核心模塊的關(guān)鍵源碼逐行怎么分析。適合正在做SaaS產(chǎn)品化改造的后端工程師、架構(gòu)師以及想把物流運(yùn)輸系統(tǒng)從單客戶定制升級(jí)成多租戶訂閱模式的同學(xué)參考。我盡量把每一步選的什么方案、為什么這么選、踩過(guò)什么坑都講清楚你們看完能直接拿去用。1. 項(xiàng)目背景與整體架構(gòu)拆解1.1 為什么貨運(yùn)系統(tǒng)一定要走SaaS化先說(shuō)行業(yè)現(xiàn)狀。傳統(tǒng)的物流運(yùn)輸管理系統(tǒng)基本都是定制開(kāi)發(fā)或者單租戶部署一家干線物流公司一套系統(tǒng)一套數(shù)據(jù)庫(kù)代碼庫(kù)還經(jīng)常因?yàn)榭蛻粜枨蟛煌植娉龊脦讉€(gè)版本。早期這么搞沒(méi)問(wèn)題客戶少、功能簡(jiǎn)單但問(wèn)題會(huì)隨著規(guī)模增長(zhǎng)越來(lái)越明顯。我接觸過(guò)一個(gè)做了七八年的運(yùn)輸管理系統(tǒng)代碼倉(cāng)庫(kù)里按客戶名建了五六套分支每套分支的訂單表字段都不完全一樣A客戶加了“是否需要回單”B客戶加了個(gè)“冷鏈溫度記錄”C客戶要“多點(diǎn)配送”。每加一個(gè)新客戶不是復(fù)制一份代碼再改就是在一堆if (customerType ...)里繼續(xù)堆邏輯。升級(jí)一個(gè)公共功能要在所有分支里各改一遍漏一個(gè)就是線上事故。這種模式運(yùn)維成本爆炸而且小物流公司根本養(yǎng)不起獨(dú)立的系統(tǒng)開(kāi)發(fā)團(tuán)隊(duì)他們也需要一套能按月付費(fèi)、開(kāi)箱即用的系統(tǒng)。SaaS化解決的就是這個(gè)問(wèn)題一套代碼、一套基礎(chǔ)服務(wù)所有租戶共用但邏輯上互相隔離。貨主登錄看到的是自己的發(fā)貨記錄司機(jī)看到的是自己的運(yùn)單平臺(tái)管理員看到的是全量數(shù)據(jù)。新接入一個(gè)租戶不是給它單獨(dú)部署一套實(shí)例而是開(kāi)一個(gè)租戶賬號(hào)、配置好它的計(jì)價(jià)規(guī)則和權(quán)限角色當(dāng)天就能用起來(lái)。我自己做這個(gè)項(xiàng)目的時(shí)候最深刻的體會(huì)是SaaS化不是把原來(lái)的單租戶系統(tǒng)加一個(gè)tenant_id字段這么簡(jiǎn)單。它是一個(gè)從表結(jié)構(gòu)設(shè)計(jì)、接口規(guī)范、權(quán)限模型、數(shù)據(jù)備份、消息隊(duì)列到定時(shí)任務(wù)全部要重新過(guò)一遍的架構(gòu)升級(jí)。標(biāo)題里說(shuō)的“多租戶架構(gòu)”絕不僅僅是數(shù)據(jù)庫(kù)隔離層面的事。1.2 多租戶隔離模式怎么選三種方案對(duì)比多租戶架構(gòu)第一個(gè)要拍板的問(wèn)題就是租戶之間在數(shù)據(jù)庫(kù)層面怎么隔離。這個(gè)決定直接關(guān)系到成本、擴(kuò)展性和運(yùn)維復(fù)雜度。行業(yè)里主流方案有三種我列個(gè)對(duì)比表你一看就明白。隔離方案數(shù)據(jù)隔離強(qiáng)度單租戶成本運(yùn)維復(fù)雜度適用場(chǎng)景獨(dú)立數(shù)據(jù)庫(kù)最強(qiáng)最高高每個(gè)庫(kù)都要監(jiān)控備份大型租戶、簽約大客戶、數(shù)據(jù)敏感共享數(shù)據(jù)庫(kù)、獨(dú)立Schema較強(qiáng)中中一套庫(kù)管理多套表結(jié)構(gòu)中型租戶要求一定程度隔離共享表、租戶ID區(qū)分最弱最低低共用表結(jié)構(gòu)小微租戶、標(biāo)準(zhǔn)業(yè)務(wù)場(chǎng)景絕大多數(shù)物流公司的主營(yíng)業(yè)務(wù)——運(yùn)單、車輛、司機(jī)、線路——業(yè)務(wù)流程是高度標(biāo)準(zhǔn)化的。所以我的選擇是默認(rèn)用共享表方案業(yè)務(wù)表統(tǒng)一帶tenant_id靠代碼層強(qiáng)制隔離少數(shù)頭部大租戶確實(shí)有數(shù)據(jù)私有化要求或者它的訂單量級(jí)實(shí)在太大會(huì)單獨(dú)給它拆一個(gè)獨(dú)立數(shù)據(jù)庫(kù)也就是“共享為主、獨(dú)立為輔”的混合策略。為什么這么選我給你算筆賬。假設(shè)平臺(tái)有三百家租戶每家平均一天一千單。共享表方案只需要一套訂單表加一個(gè)租戶ID索引數(shù)據(jù)庫(kù)連接池、緩存、備份都統(tǒng)一管理。如果三百家全部獨(dú)立數(shù)據(jù)庫(kù)光連接數(shù)就夠嗆更別說(shuō)備份、升級(jí)、遷移的工作量中小團(tuán)隊(duì)根本扛不住。而少數(shù)大租戶獨(dú)立庫(kù)是劃算的因?yàn)樗鼈兊膯瘟靠赡苷既脚_(tái)的三成以上獨(dú)立出來(lái)能避免互相影響也方便定制?；谶@個(gè)決策整個(gè)系統(tǒng)的設(shè)計(jì)原則就定了所有業(yè)務(wù)表必須包含tenant_id字段所有寫(xiě)SQL的地方必須保證租戶隔離條件不缺失所有跨租戶的數(shù)據(jù)查詢必須走專門(mén)的平臺(tái)管理接口禁止在業(yè)務(wù)接口里傳遞其他租戶ID。1.3 系統(tǒng)整體模塊地圖SaaS化貨運(yùn)平臺(tái)不是一個(gè)簡(jiǎn)單的CRUD項(xiàng)目它至少要包含下面幾大塊租戶中心租戶的注冊(cè)、開(kāi)通、套餐配置、狀態(tài)管理是整個(gè)多租戶體系的基礎(chǔ)基礎(chǔ)資料中心司機(jī)、車輛、線路、客戶檔案、貨物類型的統(tǒng)一管理訂單中心運(yùn)單從創(chuàng)建、分配、運(yùn)輸?shù)胶炇盏娜芷诠芾碚{(diào)度中心運(yùn)力池維護(hù)、自動(dòng)派單、人工調(diào)度、異常改派計(jì)費(fèi)中心計(jì)價(jià)規(guī)則配置、運(yùn)費(fèi)計(jì)算、費(fèi)用明細(xì)生成結(jié)算中心對(duì)賬、司機(jī)結(jié)算單生成、付款狀態(tài)跟蹤報(bào)表中心各租戶的運(yùn)單量、收入、成本、時(shí)效統(tǒng)計(jì)模塊之間的依賴關(guān)系我用一句話概括租戶中心管“誰(shuí)在用”基礎(chǔ)資料管“有什么資源”訂單中心管“產(chǎn)生了什么業(yè)務(wù)”調(diào)度中心管“誰(shuí)來(lái)干”計(jì)費(fèi)結(jié)算中心管“賺了多少錢(qián)”。這五條線串起來(lái)就是一個(gè)貨運(yùn)SaaS的主干。我在拆分這些模塊時(shí)最看重的一點(diǎn)是訂單狀態(tài)不能被計(jì)費(fèi)邏輯和調(diào)度邏輯直接亂改。后面源碼分析你就能看到訂單狀態(tài)機(jī)是單獨(dú)封裝的其他模塊只能通過(guò)領(lǐng)域服務(wù)的方法來(lái)改變訂單狀態(tài)不允許自己update order set status ...一把梭。2. 多租戶架構(gòu)落地租戶識(shí)別與數(shù)據(jù)隔離2.1 租戶上下文如何從HTTP請(qǐng)求傳到數(shù)據(jù)庫(kù)多租戶架構(gòu)的第一道關(guān)卡是確定“當(dāng)前請(qǐng)求屬于哪個(gè)租戶”。這個(gè)信息最早上游起源于登錄用戶的租戶歸屬——一個(gè)用戶登錄時(shí)后端校驗(yàn)完賬號(hào)密碼就從它的用戶信息里拿到tenantId。后續(xù)整個(gè)請(qǐng)求生命周期里所有查詢和寫(xiě)入都要帶上這個(gè)標(biāo)識(shí)。我用的方案是ThreadLocal結(jié)合攔截器。簡(jiǎn)單畫(huà)一下結(jié)構(gòu)public class TenantContext { private static final ThreadLocalString TENANT_ID new ThreadLocal(); public static void setTenantId(String tenantId) { TENANT_ID.set(tenantId); } public static String getTenantId() { return TENANT_ID.get(); } public static void clear() { TENANT_ID.remove(); } }攔截器在HTTP請(qǐng)求進(jìn)入Controller之前解析Token從Token里解出租戶ID寫(xiě)入TenantContext請(qǐng)求結(jié)束在afterCompletion里調(diào)用clear()清理。這樣Controller層、Service層、DAO層所有代碼都能通過(guò)TenantContext.getTenantId()拿到當(dāng)前的租戶標(biāo)識(shí)不用每個(gè)接口都手動(dòng)傳參數(shù)。注意ThreadLocal看著簡(jiǎn)單坑卻不少。最典型的兩個(gè)問(wèn)題一是線程池復(fù)用導(dǎo)致租戶上下文串了二是用完沒(méi)清理導(dǎo)致內(nèi)存泄漏或臟數(shù)據(jù)。第一個(gè)問(wèn)題在異步場(chǎng)景里特別容易出現(xiàn)。比如訂單創(chuàng)建后發(fā)MQ消息給調(diào)度中心MQ的消費(fèi)線程池里的線程是復(fù)用的。如果消費(fèi)任務(wù)里沒(méi)有設(shè)置TenantContext那這個(gè)線程處理完A租戶的消息后到處理B租戶的消息時(shí)上下文里可能還殘留著A租戶的ID。解決辦法是每次MQ消費(fèi)入口顯式設(shè)置租戶上下文并且在消費(fèi)完finally中清理。第二個(gè)問(wèn)題是clear()必須放進(jìn)finally里否則請(qǐng)求拋出異常時(shí)上下文不會(huì)被清理長(zhǎng)連接線程會(huì)把上一次的租戶ID帶到下一次請(qǐng)求查出來(lái)的數(shù)據(jù)就是串的。我見(jiàn)過(guò)線上事故就是這個(gè)問(wèn)題導(dǎo)致的一個(gè)司機(jī)登錄后看到的運(yùn)單是另一個(gè)公司的嚇?biāo)廊恕?.2 DAO層自動(dòng)注入租戶條件攔截器源碼怎么拼SQL確定了租戶上下文的傳遞下一個(gè)核心問(wèn)題就是不能每個(gè)SQL都手動(dòng)寫(xiě)where tenant_id ?。項(xiàng)目里上百個(gè)Mapper方法手寫(xiě)必然漏。我采用的是MyBatis攔截器方案在SQL執(zhí)行前自動(dòng)解析和拼接租戶條件。先定義一個(gè)注解用來(lái)標(biāo)記哪些表不需要租戶隔離Documented Target({ElementType.TYPE, ElementType.METHOD}) Retention(RetentionPolicy.RUNTIME) public interface TenantIgnore { }然后在MyBatis的攔截器里對(duì)查詢語(yǔ)句做處理Intercepts({ Signature(type Executor.class, method update, args {MappedStatement.class, Object.class}), Signature(type Executor.class, method query, args {MappedStatement.class, Object.class, RowBounds.class, ResultHandler.class}) }) public class TenantLineInterceptor implements Interceptor { Override public Object intercept(Invocation invocation) throws Throwable { // 1. 判斷是否被 TenantIgnore 標(biāo)記標(biāo)記了直接放行 // 2. 從 TenanatContext 取租戶ID取不到直接放行可能是不需要租戶隔離的基礎(chǔ)數(shù)據(jù)操作 // 3. 改寫(xiě) SQL在 WHERE 后拼接 AND tenant_id ? // 4. 給 PreparedStatement 設(shè)置參數(shù) return invocation.proceed(); } }SQL改寫(xiě)邏輯上我用的是JSqlParser這類工具把原始SQL解析成抽象語(yǔ)法樹(shù)找到對(duì)應(yīng)的表名在WHERE條件前面加上租戶條件。這里有一個(gè)細(xì)節(jié)要特別強(qiáng)調(diào)不是所有表都加租戶條件。比如系統(tǒng)級(jí)的字典表、租戶套餐配置表本身是全平臺(tái)共享的加上租戶條件反而查不到數(shù)據(jù)。所以TenantIgnore注解是必須的而且要在項(xiàng)目啟動(dòng)時(shí)掃描一遍所有Mapper檢查哪些表既沒(méi)有被租戶表白名單包含、又沒(méi)有加注解直接啟動(dòng)報(bào)錯(cuò)把漏配的問(wèn)題扼殺在編譯期。另外一個(gè)很重要的工程實(shí)踐是索引。共享表方案下所有業(yè)務(wù)表的數(shù)據(jù)都在一張表里tenant_id必須和其他業(yè)務(wù)唯一鍵組成聯(lián)合索引。舉個(gè)例子訂單表的索引不是只建order_no而是要建uk_tenant_order (tenant_id, order_no)。道理很簡(jiǎn)單如果只建order_no唯一索引兩個(gè)租戶的訂單號(hào)都是DD20250600001時(shí)直接就沖突了。復(fù)合唯一索引既保證了租戶內(nèi)的單號(hào)唯一又保證了跨租戶不互相干擾。2.3 權(quán)限與數(shù)據(jù)范圍的聯(lián)動(dòng)設(shè)計(jì)租戶隔離不等于權(quán)限控制。租戶隔離解決的是“A租戶不能看B租戶的數(shù)據(jù)”權(quán)限控制解決的是“同一個(gè)租戶里不同角色能看的數(shù)據(jù)范圍不一樣”。我實(shí)際用的是經(jīng)典的RBAC模型加數(shù)據(jù)范圍。一個(gè)租戶下的角色可以分為幾類租戶管理員能看全租戶數(shù)據(jù)調(diào)度員能看自己負(fù)責(zé)的線路和車輛司機(jī)只能看自己承接的運(yùn)單。數(shù)據(jù)范圍的實(shí)現(xiàn)不是簡(jiǎn)單在SQL里拼條件而是通過(guò)一個(gè)數(shù)據(jù)權(quán)限注解Documented Retention(RetentionPolicy.RUNTIME) Target(ElementType.METHOD) public interface DataScope { // 數(shù)據(jù)范圍類型ALL / DEPARTMENT_VEHICLE / ONLY_SELF DataScopeType value() default DataScopeType.ALL; }在AOP攔截器里根據(jù)當(dāng)前登錄用戶的角色和數(shù)據(jù)范圍類型自動(dòng)把額外的過(guò)濾條件加到SQL上。它與租戶條件疊加的時(shí)候SQL最終會(huì)變成where tenant_id ? and driver_id ?。這兩層條件要一起生效缺一個(gè)都不行。這里我想提醒一句數(shù)據(jù)權(quán)限和租戶隔離是兩個(gè)獨(dú)立維度一定要拆開(kāi)設(shè)計(jì)。如果把它們混在一個(gè)攔截器里后面調(diào)整權(quán)限模型或者調(diào)整租戶隔離策略時(shí)候拆起來(lái)非常痛苦。我第一版就是圖省事寫(xiě)在一起的后來(lái)加了個(gè)“按線路配數(shù)據(jù)權(quán)限”的需求改得頭皮發(fā)麻。3. 核心模塊源碼分析訂單中心與狀態(tài)機(jī)3.1 訂單模型字段怎么設(shè)計(jì)既靈活又統(tǒng)一訂單模塊是整個(gè)貨運(yùn)平臺(tái)的中樞。貨主下單之后從報(bào)價(jià)、派車、取貨、干線運(yùn)輸?shù)胶炇账辛鞒潭家杂唵螢楹诵牧鬓D(zhuǎn)。我先把訂單相關(guān)的核心表結(jié)構(gòu)梳理一下。訂單主表字段大致分幾類基礎(chǔ)信息order_no租戶內(nèi)唯一單號(hào)、tenant_id、order_type整車/零擔(dān)/冷鏈等、goods_type、weight、volume、pieces地址信息start_province、start_city、start_address、end_province、end_city、end_address、planned_distance時(shí)效信息expect_pickup_time、expect_delivery_time、actual_pickup_time、actual_delivery_time狀態(tài)信息status、current_node、cancel_reason、reject_reason來(lái)源信息channelAPP/小程序/接口/人工錄入、customer_id、platform_order_no此外還有兩張擴(kuò)展表訂單貨物明細(xì)表一單多貨和訂單運(yùn)費(fèi)明細(xì)表運(yùn)費(fèi)、裝卸費(fèi)、等候費(fèi)等。我強(qiáng)烈建議不要把所有信息塞進(jìn)訂單主表原因不是范式強(qiáng)迫癥而是貨運(yùn)場(chǎng)景里一對(duì)多的情況實(shí)在太常見(jiàn)。一車貨發(fā)往三個(gè)不同城市的客戶這在零擔(dān)場(chǎng)景下天天見(jiàn)如果把貨物和費(fèi)用全塞在主表里拆單和計(jì)費(fèi)邏輯會(huì)被字段結(jié)構(gòu)活活逼瘋。3.2 訂單狀態(tài)機(jī)從下單到簽收的流轉(zhuǎn)規(guī)則訂單狀態(tài)是訂單中心最容易做崩的地方。如果每個(gè)狀態(tài)流轉(zhuǎn)都散落在Service層不同的方法里用一堆if (order.status 1 ...)判斷項(xiàng)目到后期會(huì)出現(xiàn)“這個(gè)狀態(tài)應(yīng)該能取消但代碼里忘了放行”之類的隱蔽bug。我在項(xiàng)目里用枚舉加狀態(tài)流轉(zhuǎn)表來(lái)實(shí)現(xiàn)狀態(tài)機(jī)核心代碼大致是這樣public enum OrderStatus { PENDING(10, 待接單), ACCEPTED(20, 已接單), PENDING_PICKUP(30, 待取貨), IN_TRANSIT(40, 運(yùn)輸中), PENDING_SIGN(50, 待簽收), SIGNED(60, 已簽收), CANCELED(90, 已取消), EXCEPTION(99, 異常處理中); private final int code; private final String desc; }每個(gè)業(yè)務(wù)方法要修改訂單狀態(tài)的時(shí)候統(tǒng)一走領(lǐng)域服務(wù)public class OrderStatusService { private static final MapString, ListOrderStatus TRANSITIONS new HashMap(); static { // 待接單 - 已接單 / 已取消 TRANSITIONS.put(10-20, Arrays.asList(...)); // 已接單 - 待取貨 / 已取消 // 運(yùn)輸中 - 待簽收 / 異常處理中 // 異常處理中 - 運(yùn)輸中 / 已取消 } public void transition(Order order, OrderStatus target) { String key order.getStatus().getCode() - target.getCode(); if (!TRANSITIONS.containsKey(key)) { throw new IllegalStateException(非法狀態(tài)流轉(zhuǎn): key); } order.setStatus(target); } }為什么用狀態(tài)機(jī)因?yàn)橛唵蔚牧鬓D(zhuǎn)不是線性的。正常流程是待接單-已接單-待取貨-運(yùn)輸中-待簽收-已簽收但中間隨時(shí)可能插入異常分支客戶取消、司機(jī)拒單、貨物破損、天氣延誤。這些分支和主流程之間要有清晰、可控的轉(zhuǎn)換關(guān)系。狀態(tài)機(jī)把流轉(zhuǎn)規(guī)則集中在一個(gè)地方管理任何非法流轉(zhuǎn)直接拋異常日志里能明確看到誰(shuí)想從“運(yùn)輸中”改到“已簽收”——這明顯是邏輯漏洞。還有一點(diǎn)經(jīng)驗(yàn)業(yè)務(wù)狀態(tài)不要只用字符串或者數(shù)字散落在代碼里要配合狀態(tài)變更歷史表一起用。每次狀態(tài)變更都記錄一條流水order_id、from_status、to_status、operator_type、operator_id、change_reason、create_time。后面排查問(wèn)題的時(shí)候這張表是救命稻草。有一次客戶投訴說(shuō)“我明明沒(méi)收到貨系統(tǒng)卻顯示已簽收”我直接查狀態(tài)流水發(fā)現(xiàn)是某個(gè)腳本批量調(diào)用把狀態(tài)改錯(cuò)了十分鐘定位到問(wèn)題靠的全是流水。3.3 拆單、合單與改派的源碼邏輯訂單中心除了狀態(tài)流轉(zhuǎn)還有幾個(gè)繞不開(kāi)的業(yè)務(wù)邏輯拆單、合單、改派。拆單場(chǎng)景最常見(jiàn)的是一票貨物有多個(gè)收貨地址。核心邏輯是按收貨城市分組把原來(lái)的父訂單拆成多個(gè)子訂單。這里的關(guān)鍵是父訂單本身的金額怎么分?jǐn)傋佑唵沃g怎么關(guān)聯(lián)運(yùn)費(fèi)怎么重新計(jì)算。我的做法是拆單時(shí)保留父單實(shí)體但父單狀態(tài)變?yōu)椤耙巡鸱帧苯痤~清零實(shí)際業(yè)務(wù)流轉(zhuǎn)全部走子單子單通過(guò)parent_order_no關(guān)聯(lián)。合單則相反同一發(fā)貨地、同一收貨地、要求時(shí)效接近的多個(gè)訂單合并成一個(gè)運(yùn)單由一個(gè)司機(jī)承運(yùn)。合單不是簡(jiǎn)單把兩個(gè)訂單的金額相加而要重新按合并后的貨物總重、總體積計(jì)價(jià)。這里要特別小心合單前必須校驗(yàn)兩個(gè)訂單有沒(méi)有沖突貨物類型是否兼容常溫貨和冷鏈貨不能合并甚至要考慮貨物是否超載。我見(jiàn)過(guò)一次線上合單事故兩個(gè)訂單各1噸合單后總重2.5噸調(diào)度員沒(méi)注意就把單派給了一輛核載2噸的4米2車最終以超載拒運(yùn)收?qǐng)觥Ｋ院蠁芜壿嬂锉仨氂兄亓?、體積、車型匹配的校驗(yàn)而且合并后要重新跑一遍運(yùn)力匹配不能直接把原來(lái)某個(gè)司機(jī)的運(yùn)單合并給另一個(gè)司機(jī)。改派邏輯相對(duì)簡(jiǎn)單但要注意權(quán)限邊界只有調(diào)度員角色能改派司機(jī)不能自行轉(zhuǎn)單。改派時(shí)的關(guān)鍵操作是同時(shí)改訂單的driver_id和車輛 ID并且新增一條調(diào)度流水記錄誰(shuí)改的、從哪個(gè)司機(jī)改到哪個(gè)司機(jī)、原因是什么方便運(yùn)費(fèi)結(jié)算時(shí)的責(zé)任劃分。4. 核心模塊源碼分析計(jì)費(fèi)中心與規(guī)則引擎4.1 計(jì)價(jià)規(guī)則為何一定要配置化貨運(yùn)計(jì)價(jià)是所有運(yùn)輸系統(tǒng)中的“萬(wàn)惡之源”因?yàn)槊考夜径加凶约旱膱?bào)價(jià)算法。有的按重量、有的按體積、有的按里程、有的按車次還有的是“起步價(jià)加噸公里價(jià)”的復(fù)合模式。如果計(jì)價(jià)邏輯在全代碼里寫(xiě)死每接入一個(gè)新租戶就得改一次代碼SaaS就搞不下去了。對(duì)應(yīng)的設(shè)計(jì)思路是“計(jì)價(jià)規(guī)則引擎”。核心抽象是策略接口public interface PricingRule { // 判斷當(dāng)前規(guī)則是否適用 boolean supports(PricingContext context); // 計(jì)算運(yùn)費(fèi) BigDecimal calculate(PricingContext context); }然后每種計(jì)價(jià)方式一個(gè)實(shí)現(xiàn)類Component public class WeightBasedPricingRule implements PricingRule { Override public boolean supports(PricingContext context) { return WEIGHT.equals(context.getPricingType()); } Override public BigDecimal calculate(PricingContext context) { BigDecimal unitPrice context.getUnitPrice(); BigDecimal weight context.getTotalWeight(); return unitPrice.multiply(weight); } }配置層面每個(gè)租戶可以在后臺(tái)配置計(jì)價(jià)方式、單價(jià)、起步價(jià)、階梯價(jià)格。訂單創(chuàng)建時(shí)計(jì)價(jià)引擎讀取租戶的配置動(dòng)態(tài)選擇對(duì)應(yīng)的規(guī)則實(shí)現(xiàn)。這樣做的好處是新租戶接入時(shí)只需要在后臺(tái)配置計(jì)價(jià)模板不需要發(fā)版、不需要改代碼真正做到了“開(kāi)箱即用”。計(jì)價(jià)規(guī)則配置化之后還有一層要考慮同一個(gè)租戶下不同線路的報(bào)價(jià)可能不同。比如華東線每噸200元東北線每噸300元。所以計(jì)價(jià)配置上不能只掛在租戶級(jí)別要支持“租戶線路”級(jí)別的配置。我的做法是配置表設(shè)三檔優(yōu)先級(jí)全局模板 區(qū)域模板 線路模板計(jì)價(jià)引擎按優(yōu)先級(jí)取最高匹配級(jí)的配置。4.2 從計(jì)費(fèi)快照到費(fèi)用明細(xì)的完整鏈路有個(gè)很容易忽略但是非常重要的點(diǎn)費(fèi)用計(jì)算的結(jié)果必須存快照。什么意思就是說(shuō)訂單簽收那一刻算出來(lái)的運(yùn)費(fèi)是1300元那它就是1300元。哪怕后來(lái)管理員修改了計(jì)價(jià)規(guī)則把單價(jià)從200改成250歷史訂單的運(yùn)費(fèi)也不應(yīng)該變。實(shí)現(xiàn)思路是在訂單費(fèi)用表里把計(jì)算時(shí)的規(guī)則快照存下來(lái)public class OrderFee { private String orderNo; private String tenantId; private String feeType; // 運(yùn)費(fèi)/裝卸費(fèi)/等候費(fèi)/保價(jià)費(fèi) private String pricingRuleId; // 計(jì)算用的規(guī)則ID private BigDecimal unitPrice; // 計(jì)算時(shí)的單價(jià)快照 private BigDecimal quantity; // 計(jì)算時(shí)的數(shù)量 private BigDecimal amount; // 最終金額 private String snapshotJson; // 整個(gè)規(guī)則上下文的快照 }snapshotJson字段里面存的是計(jì)算當(dāng)時(shí)的完整上下文包括貨物類型、重量、體積、起終點(diǎn)、計(jì)價(jià)規(guī)則版本。后續(xù)如果對(duì)賬有爭(zhēng)議或者司機(jī)投訴“運(yùn)費(fèi)算錯(cuò)了”我們可以直接調(diào)出快照看看當(dāng)時(shí)到底是怎么算出來(lái)的。這個(gè)快照機(jī)制幫我擋住了無(wú)數(shù)次的扯皮。費(fèi)用明細(xì)和賬單是兩回事。費(fèi)用明細(xì)是一筆一筆的費(fèi)用記錄賬單是給貨主看的匯總單據(jù)。我的賬單生成邏輯是一個(gè)訂單的所有費(fèi)用明細(xì)按費(fèi)用類型匯總生成賬單賬單狀態(tài)有“待確認(rèn)”“已確認(rèn)”“已支付”。結(jié)算中心在賬單確認(rèn)后生成應(yīng)收記錄。4.3 平臺(tái)與司機(jī)的對(duì)賬清分邏輯SaaS貨運(yùn)平臺(tái)是中間平臺(tái)從貨主那里收運(yùn)費(fèi)再向承運(yùn)司機(jī)支付運(yùn)輸報(bào)酬。中間的差價(jià)就是平臺(tái)利潤(rùn)。這里有一個(gè)非常核心的對(duì)賬需求平臺(tái)的錢(qián)和第三方的錢(qián)要對(duì)平。主要包括兩類流水平臺(tái)應(yīng)收流水貨主支付了多少錢(qián)司機(jī)應(yīng)付流水平臺(tái)要給司機(jī)結(jié)算多少錢(qián)支付渠道流水第三方支付平臺(tái)的收款回調(diào)我對(duì)賬模塊的處理流程是定時(shí)任務(wù)拉取一段時(shí)間內(nèi)的平臺(tái)應(yīng)收單和支付渠道流水按平臺(tái)訂單號(hào)金額匹配匹配上的標(biāo)記為“已核銷”匹配不上的進(jìn)入“差異池”差異池里的記錄由運(yùn)營(yíng)人工處理可能是渠道手續(xù)費(fèi)差異、可能是退款、可能是系統(tǒng)漏單對(duì)賬的代碼核心是匹配邏輯簡(jiǎn)單版本如下public class ReconciliationService { public void reconcile(LocalDate bizDate) { ListReceiptRecord receipts receiptMapper.selectByDate(bizDate); ListChannelTransaction transactions channelMapper.selectByDate(bizDate); for (ReceiptRecord receipt : receipts) { // 嘗試按平臺(tái)單號(hào)和金額精確匹配 OptionalChannelTransaction matched transactions.stream() .filter(t - t.getOrderNo().equals(receipt.getOrderNo())) .filter(t - t.getAmount().compareTo(receipt.getAmount()) 0) .findFirst(); if (matched.isPresent()) { markMatched(receipt.getId(), matched.get().getId()); } else { markDifference(receipt.getId(), 金額不一致或渠道無(wú)記錄); } } } }司機(jī)結(jié)算單的生成是另一條鏈路訂單簽收后系統(tǒng)按承運(yùn)司機(jī)、結(jié)算周期按單/按天/按周把司機(jī)的應(yīng)得收入?yún)R總成結(jié)算單。這里司機(jī)和貨主的計(jì)價(jià)是分開(kāi)的平臺(tái)向貨主收1300元給司機(jī)結(jié)算可能是1100元差價(jià)200元是平臺(tái)收入。兩套價(jià)目表相互獨(dú)立規(guī)則引擎分別配置不能混在一起。4.4 司機(jī)結(jié)算單生成流程實(shí)操司機(jī)結(jié)算單生成是一個(gè)典型的集成流程我列一下它要經(jīng)過(guò)的狀態(tài)節(jié)點(diǎn)等待生成訂單已簽收等待下一個(gè)結(jié)算周期已生成結(jié)算單創(chuàng)建完成包含一個(gè)或多個(gè)訂單的明細(xì)待審核財(cái)務(wù)審核結(jié)算單核對(duì)金額和運(yùn)單明細(xì)待支付審核通過(guò)等待推送支付支付中已調(diào)用支付接口已支付支付回調(diào)確認(rèn)完成支付異常打款失敗觸發(fā)人工處理這個(gè)流程里最容易出問(wèn)題的節(jié)點(diǎn)是“已生成”到“待審核”因?yàn)榻Y(jié)算單有可能包含多張運(yùn)單每張運(yùn)單的狀態(tài)必須全部是“已簽收”。只要有一張單處于“異常處理中”整張結(jié)算單就不能進(jìn)入審核。我在代碼里用了一個(gè)校驗(yàn)方法生成結(jié)算單前先遍歷所有關(guān)聯(lián)訂單狀態(tài)不滿足的訂單直接踢出結(jié)算單并把異常情況記錄到結(jié)算單備注里。支付回調(diào)的狀態(tài)同步也要注意。支付結(jié)果必須通過(guò)回調(diào)更新不能靠發(fā)起支付響應(yīng)成功就更新?tīng)顟B(tài)。因?yàn)橹Ц肚赖恼鎸?shí)結(jié)果可能延遲只有回調(diào)到達(dá)才代表錢(qián)真到了司機(jī)賬戶。5. 核心模塊源碼分析運(yùn)力池與調(diào)度中心5.1 司機(jī)、車輛、線路的租戶化建?；A(chǔ)資料中心的建模比訂單要簡(jiǎn)單一些套路是一樣的所有表帶tenant_id。但有一些貨運(yùn)特有的業(yè)務(wù)規(guī)則要注意。司機(jī)表tenant_id、driver_name、phone、id_card_no脫敏存儲(chǔ)、driving_type、status空閑/運(yùn)輸中/休假/禁用、score車輛表tenant_id、plate_no、vehicle_type車型、load_weight、load_volume、status可用/在途/維修/禁用司機(jī)和車輛的綁定關(guān)系一個(gè)司機(jī)可以綁定多輛車但一輛車同一時(shí)間只能被一個(gè)司機(jī)使用?？紤]到換班場(chǎng)景綁定關(guān)系表要有生效時(shí)間和失效時(shí)間。我在設(shè)計(jì)時(shí)沒(méi)有把“當(dāng)前綁定車輛”直接放司機(jī)表里而是單獨(dú)一張driver_vehicle_binding表這樣一條司機(jī)記錄可以關(guān)聯(lián)多條車輛記錄同時(shí)通過(guò)is_active字段標(biāo)記當(dāng)前默認(rèn)車輛換車時(shí)只需要改一條記錄的激活標(biāo)記不需要?jiǎng)铀緳C(jī)主表。還有一個(gè)容易被忽略的細(xì)節(jié)身份證號(hào)、手機(jī)號(hào)這類敏感字段無(wú)論從數(shù)據(jù)庫(kù)存儲(chǔ)到日志輸出都要做脫敏。司機(jī)手機(jī)號(hào)在日志里出現(xiàn)完整號(hào)段這種事故被客戶投訴一次就夠了。我的習(xí)慣是在實(shí)體類上定義SensitiveField注解Jackson序列化和日志切面統(tǒng)一脫敏日志里永遠(yuǎn)只看到138****1234這種格式。5.2 運(yùn)力池匹配邏輯車型、距離、評(píng)分多重篩選運(yùn)力池是調(diào)度中心的核心。它本質(zhì)上是一個(gè)“當(dāng)前租戶下所有可用運(yùn)力”的集合作引。訂單創(chuàng)建后調(diào)度中心從運(yùn)力池里找到合適的司機(jī)來(lái)承運(yùn)。匹配邏輯的核心排序維度我總結(jié)為四層車型匹配訂單要求6米8車就絕不能派4米2車地理位置司機(jī)當(dāng)前位置離裝貨地越近越優(yōu)先歷史評(píng)分同樣距離下評(píng)分高的司機(jī)關(guān)單率低優(yōu)先派活躍度最近48小時(shí)有完單記錄的司機(jī)優(yōu)先排除長(zhǎng)期不接單的匹配邏輯示例public ListDriverVehicle matchDrivers(Order order) { String tenantId TenantContext.getTenantId(); // 第一步租戶內(nèi)所有可用車輛 ListDriverVehicle candidates driverVehicleMapper .selectAvailableByTenant(tenantId); // 第二步過(guò)濾車型和載重 candidates candidates.stream() .filter(dv - dv.getVehicleType().equals(order.getRequireVehicleType())) .filter(dv - dv.getLoadWeight().compareTo(order.getTotalWeight()) 0) .collect(Collectors.toList()); // 第三步按距離排序按經(jīng)緯度計(jì)算距離省略具體實(shí)現(xiàn) candidates.sort(Comparator.comparingDouble(dv - GeoUtils.calcDistance(order.getStartLat(), order.getStartLng(), dv.getCurrentLat(), dv.getCurrentLng()))); return candidates; }自動(dòng)匹配結(jié)果不能直接當(dāng)最終派單結(jié)果這很重要。平臺(tái)上一旦出現(xiàn)自動(dòng)派單給一個(gè)評(píng)分極低的司機(jī)貨主基本就跑了。所以我的設(shè)計(jì)是“自動(dòng)匹配生成候選列表調(diào)度員在列表中確認(rèn)或改派”。完全無(wú)人化的自動(dòng)派單需要足夠的數(shù)據(jù)積累和信用體系支撐貨運(yùn)行業(yè)信用體系不成熟前人工兜底是必須的。5.3 調(diào)度臺(tái)的人工干預(yù)設(shè)計(jì)調(diào)度臺(tái)的人工干預(yù)能力包括手工指派、線路改派、強(qiáng)制派單。手工指派的核心是權(quán)限控制調(diào)度員只能選擇自己負(fù)責(zé)的線路范圍內(nèi)的司機(jī)不能看到全租戶的司機(jī)列表。數(shù)據(jù)范圍在這里和權(quán)限模型聯(lián)動(dòng)正好用到了前面講到的DataScope注解。強(qiáng)制派單的場(chǎng)景比較特殊司機(jī)已經(jīng)拒絕接單但平臺(tái)的運(yùn)營(yíng)判斷這個(gè)運(yùn)單必須由該司機(jī)承擔(dān)于是強(qiáng)制派給司機(jī)。這里需要給司機(jī)一個(gè)“強(qiáng)制派單”的明確標(biāo)識(shí)并且在司機(jī)端的訂單列表里顯示“調(diào)度強(qiáng)制指派如有異議請(qǐng)聯(lián)系調(diào)度臺(tái)”。強(qiáng)制派單的次數(shù)要記錄作為司機(jī)月度考核的一個(gè)負(fù)面指標(biāo)。如果不做次數(shù)統(tǒng)計(jì)強(qiáng)制派單就會(huì)被濫用司機(jī)體驗(yàn)會(huì)很差最終導(dǎo)致司機(jī)流失。調(diào)度流水同樣要走獨(dú)立的變更歷史記錄便于事后審計(jì)和績(jī)效追溯。我見(jiàn)過(guò)很多團(tuán)隊(duì)做調(diào)度中心時(shí)只設(shè)計(jì)了訂單狀態(tài)和司機(jī)信息沒(méi)有調(diào)度日志表結(jié)果司機(jī)投訴“為啥給我派這單”的時(shí)候完全查不到依據(jù)。一張調(diào)度流水表按時(shí)間順序記錄每次派單、改派、強(qiáng)制派單操作能解決大量客服糾紛。6. 實(shí)際踩坑與排查實(shí)錄6.1 我遇到過(guò)的租戶隔離問(wèn)題這部分分享幾個(gè)實(shí)際線上踩坑案例都是血淚教訓(xùn)希望能幫你們繞過(guò)去。第一個(gè)是定時(shí)任務(wù)不經(jīng)過(guò)攔截器導(dǎo)致數(shù)據(jù)無(wú)租戶ID。當(dāng)時(shí)有一個(gè)“超時(shí)未接單自動(dòng)取消”的定時(shí)任務(wù)直接調(diào)用訂單Service但沒(méi)有經(jīng)過(guò)HTTP請(qǐng)求TenantContext是空的。這個(gè)任務(wù)把所有租戶的超時(shí)訂單都掃出來(lái)了但沒(méi)有租戶ID的條件更新時(shí)把tenant_id更新成空串導(dǎo)致一批訂單在下一次查詢時(shí)從任何租戶里都查不出來(lái)。排查方法很簡(jiǎn)單掃訂單表發(fā)現(xiàn)一批tenant_id is null和tenant_id 的記錄。第二個(gè)是線程池復(fù)用導(dǎo)致租戶上下文串了。MQ消費(fèi)端接入了一個(gè)新的異步處理器我在消費(fèi)邏輯里忘了設(shè)置租戶上下文結(jié)果線程池上一個(gè)任務(wù)留下的租戶ID被新任務(wù)繼續(xù)使用。最終導(dǎo)致司機(jī)端一個(gè)查詢請(qǐng)求拿到了另一個(gè)租戶的訂單列表。這個(gè)問(wèn)題的排查比第一個(gè)更難因?yàn)閿?shù)據(jù)看起來(lái)沒(méi)有丟只是“臟”你必須事后比對(duì)日志才能發(fā)現(xiàn)上下文沒(méi)有正確切換。第三個(gè)是手動(dòng)SQL沒(méi)有走攔截器。報(bào)表模塊有大量的聯(lián)表查詢、子查詢、UNION這些SQL在MyBatis攔截器里的解析邏輯對(duì)UNION支持不完善我當(dāng)時(shí)直接在白名單里讓報(bào)表SQL繞過(guò)了租戶條件結(jié)果報(bào)表數(shù)據(jù)串得一塌糊涂。后來(lái)補(bǔ)丁是把報(bào)表SQL改成必須顯式傳入租戶ID拼到SQL里不允許繞過(guò)。第四個(gè)問(wèn)題是SQL改寫(xiě)對(duì)子查詢的處理。MyBatis攔截器在改寫(xiě)SQL時(shí)如果不小心處理子查詢會(huì)把租戶條件同時(shí)拼到子查詢和外層查詢里結(jié)果造成where tenant_id ? and order_id in (select order_id from order where tenant_id ?)這種重復(fù)條件?？雌饋?lái)不致命但一旦子查詢里的表別名叫錯(cuò)了SQL直接報(bào)列名不明確線上直接報(bào)警。6.2 排查問(wèn)題的方法與速查表遇到租戶數(shù)據(jù)異常先別急著改代碼我通常按這個(gè)順序排查看接口日志請(qǐng)求的租戶ID是什么返回的數(shù)據(jù)里有沒(méi)有跨租戶的ID看SQL日志執(zhí)行的SQL有沒(méi)有帶上租戶條件帶上的條件值是不是當(dāng)前租戶看調(diào)用鏈這個(gè)請(qǐng)求是從HTTP進(jìn)來(lái)的還是MQ消息還是定時(shí)任務(wù)看線程上下文確認(rèn)TenantContext在當(dāng)前調(diào)用鏈路的各個(gè)節(jié)點(diǎn)是否都正確設(shè)置我把常見(jiàn)的現(xiàn)象和原因整理成一張排查表你們可以截圖保存現(xiàn)象可能原因排查步驟查詢結(jié)果為空租戶條件值傳錯(cuò)或傳成了空檢查請(qǐng)求Token里租戶ID是否正常檢查上下文設(shè)置處查詢結(jié)果串租戶線程池復(fù)用上下文未清理或未設(shè)置查MQ消費(fèi)入口和異步線程包裝層插入數(shù)據(jù)沒(méi)有租戶ID定時(shí)任務(wù)/回調(diào)接口未設(shè)置上下文查任務(wù)調(diào)度入口和回調(diào)處理入口SQL報(bào)列名不明確攔截器改寫(xiě)SQL時(shí)子查詢處理不正確打開(kāi)SQL日志檢查改寫(xiě)前后的SQL報(bào)表數(shù)據(jù)異常手動(dòng)SQL繞過(guò)攔截器檢查是否在報(bào)表查詢中顯式拼接租戶條件6.3 架構(gòu)層面的經(jīng)驗(yàn)總結(jié)走完整個(gè)SaaS化貨運(yùn)平臺(tái)的落地我把最重要的幾條經(jīng)驗(yàn)放到最后說(shuō)這些比任何一段源碼都值錢(qián)。第一租戶隔離方案一定要在項(xiàng)目第一天就定下來(lái)。中途從單租戶改成共享表技術(shù)可行但要花三倍的測(cè)試時(shí)間。所有表加tenant_id所有索引變成“租戶ID業(yè)務(wù)鍵”的復(fù)合索引這個(gè)工作越早做越輕松。第二不要為了架構(gòu)而架構(gòu)。很多團(tuán)隊(duì)一聽(tīng)說(shuō)SaaS就覺(jué)得必須上獨(dú)立數(shù)據(jù)庫(kù)反而把自己搞死。實(shí)際做下來(lái)90%以上的租戶共享一套服務(wù)完全沒(méi)問(wèn)題少數(shù)高端、大額、定制化租戶才需要獨(dú)立部署。技術(shù)選型脫離商業(yè)場(chǎng)景就是耍流氓。第三多租戶SaaS的測(cè)試成本遠(yuǎn)高于單租戶系統(tǒng)。單租戶系統(tǒng)只需要驗(yàn)證功能對(duì)不對(duì)多租戶要驗(yàn)證功能、隔離性、權(quán)限范圍、數(shù)據(jù)統(tǒng)計(jì)、并發(fā)隔離。我強(qiáng)烈建議測(cè)試環(huán)境里至少準(zhǔn)備三個(gè)租戶的數(shù)據(jù)交叉驗(yàn)證每次發(fā)布前跑一遍“租戶A登錄不能看到租戶B數(shù)據(jù)”的冒煙測(cè)試用例。第四訂單、計(jì)費(fèi)、調(diào)度三個(gè)模塊在邊界上最容易打架。訂單狀態(tài)機(jī)統(tǒng)一管理計(jì)費(fèi)模塊通過(guò)計(jì)費(fèi)流水與訂單交互調(diào)度模塊通過(guò)與訂單領(lǐng)域服務(wù)協(xié)作完成派單絕不允許模塊間直接修改對(duì)方的表數(shù)據(jù)。這個(gè)約束寫(xiě)進(jìn)開(kāi)發(fā)規(guī)范比寫(xiě)進(jìn)代碼注釋有用得多。最后再分享一個(gè)處理多租戶異步任務(wù)的小技巧所有MQ消息體里必須帶上tenantId字段消費(fèi)者收到消息第一時(shí)間設(shè)置租戶上下文再加finally清理。這比依賴調(diào)用鏈傳遞上下文要可靠得多因?yàn)樗灰蕾嚲€程池里的執(zhí)行環(huán)境消息是顯式攜帶了租戶歸屬的。我后來(lái)把所有異步任務(wù)都按這個(gè)規(guī)范重寫(xiě)了一遍租戶相關(guān)的線上事故從此基本絕跡。