這個開發團隊把API文檔"外包"給代碼，結果省了300小時

去年有個做SaaS的朋友跟我吐槽：他們團隊前后端扯皮扯了整整兩周，最后發現是接口字段對不上——前端要的userId，后端傳的是id。這種破事在2024年還在發生，而解決方案其實早就在那兒了。

先寫合同，再蓋房子

最近Dev.to上有個叫「合同驅動開發」（Contract-Driven Development）的思路在傳。說白了，就是蓋樓前先畫好圖紙，而不是邊砌磚邊改設計。

傳統做法：后端吭哧吭哧寫接口，前端等著調，調完發現字段對不上，開會扯皮，改代碼，再測，再扯。合同驅動反過來：先把API的「合同」——也就是結構——釘死。端點（endpoints）有哪些、請求（request）長什么樣、響應（response）返回什么，全部寫成一份OpenAPI規范的JSON文件。

這份文件就成了團隊的「憲法」。前端不用等后端寫完就能照著mock數據開工，后端照著合同實現就行，測試也能自動生成。

最爽的是文檔自動跟著代碼走，不會再出現「代碼改了三天，文檔還是上個月版本」的尷尬。

技術棧：Express+Zod+tRPC的三人轉

實際落地需要幾樣東西配合。Express當底座，Zod負責數據校驗——你定義一次schema，輸入輸出自動檢查，不用寫一堆if-else手動判空。

tRPC是TypeScript團隊的利器，前后端共享類型定義，改接口時編譯器直接報錯，而不是等到運行時才發現undefined。trpc-openapi這個包把tRPC和OpenAPI打通，最終吐出一份openapi.json。

裝上這些：

npm install express zod @trpc/server @trpc/server/adapters/express trpc-openapi

TypeScript用戶再加：

npm install -D typescript ts-node @types/node @types/express

完事之后，Swagger這類工具能直接讀取生成的JSON，界面漂亮的文檔就有了。不是手寫維護的，是代碼吐出來的。

省下的時間從哪來

這種模式的核心收益是消除「隱性債務」。前后端同步問題、文檔過時問題、接口理解偏差問題，本質上都是溝通成本。合同驅動把它們前置到設計階段一次性解決。

有個細節很妙：Zod的schema定義既是校驗邏輯，也是類型定義，還是文檔來源。一份代碼干三份活，這很產品經理思維——能復用的絕不重寫。

當然，原作者也留了問號：「還沒完整落地，不確定大型項目后期會不會變復雜。」這是實話。任何架構都有適用邊界，合同驅動在接口頻繁變動的早期階段可能顯得笨重，但在團隊協作、長期維護場景下，前期多寫的幾十行schema能換回后期少開的幾十場會。

你現在的項目，前后端協作最大的卡點在哪？是接口定義，還是測試覆蓋，還是別的什么？