1. 規(guī)格驅(qū)動(dòng)開(kāi)發(fā)到底在解決什么問(wèn)題第一次聽(tīng)到“規(guī)格驅(qū)動(dòng)開(kāi)發(fā)”這個(gè)詞很多人會(huì)下意識(shí)覺(jué)得它不過(guò)是“先寫文檔再寫代碼”的另一種說(shuō)法。但如果你真的在團(tuán)隊(duì)里推行過(guò)一陣子就會(huì)發(fā)現(xiàn)它跟傳統(tǒng)的“需求文檔驅(qū)動(dòng)”完全不是一回事。規(guī)格驅(qū)動(dòng)開(kāi)發(fā)的核心是把“規(guī)格”從一份給人看的說(shuō)明文檔變成一份機(jī)器可讀、可校驗(yàn)、可生成代碼或測(cè)試的唯一事實(shí)來(lái)源。換句話說(shuō)規(guī)格不再是附屬品而是整個(gè)開(kāi)發(fā)流程的主干。我最早接觸這個(gè)概念是在一個(gè)跨平臺(tái)數(shù)據(jù)同步的項(xiàng)目里。當(dāng)時(shí)團(tuán)隊(duì)有五個(gè)人前后端加移動(dòng)端接口字段改來(lái)改去每次改動(dòng)都要在群里喊一遍然后各自去改代碼、改文檔、改測(cè)試用例。結(jié)果就是文檔永遠(yuǎn)滯后于代碼測(cè)試用例永遠(yuǎn)覆蓋不全聯(lián)調(diào)的時(shí)候互相甩鍋。后來(lái)我們嘗試把接口定義抽出來(lái)用一種結(jié)構(gòu)化的格式統(tǒng)一描述再由工具自動(dòng)生成各端的模型代碼和基礎(chǔ)校驗(yàn)邏輯。那一瞬間很多扯皮的事情自然消失了。這就是規(guī)格驅(qū)動(dòng)開(kāi)發(fā)最樸素的價(jià)值讓規(guī)格成為可執(zhí)行的契約而不是墻上的標(biāo)語(yǔ)。它解決的問(wèn)題可以歸納為三類。第一類是信息衰減需求從產(chǎn)品經(jīng)理傳到開(kāi)發(fā)再傳到測(cè)試每經(jīng)過(guò)一層就丟失或扭曲一部分細(xì)節(jié)。第二類是重復(fù)勞動(dòng)同一份數(shù)據(jù)結(jié)構(gòu)要在后端、前端、測(cè)試、文檔里各寫一遍改一處就要同步四處。第三類是驗(yàn)證滯后很多問(wèn)題要到集成測(cè)試甚至上線后才暴露修復(fù)成本極高。規(guī)格驅(qū)動(dòng)開(kāi)發(fā)通過(guò)把規(guī)格前置并結(jié)構(gòu)化讓這三類問(wèn)題在源頭被壓縮。適合參考這套方法的人其實(shí)比想象中廣。不只是后端工程師前端、測(cè)試、技術(shù)文檔寫作者、甚至產(chǎn)品經(jīng)理都能從中受益。只要你的工作涉及多方協(xié)作、接口對(duì)齊、數(shù)據(jù)流轉(zhuǎn)規(guī)格驅(qū)動(dòng)開(kāi)發(fā)就能派上用場(chǎng)。它不挑語(yǔ)言不挑框架挑的是團(tuán)隊(duì)愿不愿意把“先對(duì)齊再動(dòng)手”這件事真正落地。2. 規(guī)格驅(qū)動(dòng)開(kāi)發(fā)的核心思路拆解2.1 規(guī)格為什么必須機(jī)器可讀傳統(tǒng)需求文檔是給人讀的人讀就有歧義。一句“用戶信息包含基本資料”不同人理解完全不同。規(guī)格驅(qū)動(dòng)開(kāi)發(fā)要求規(guī)格本身用結(jié)構(gòu)化格式描述比如 JSON Schema、OpenAPI、Protocol Buffers 的 IDL或者自定義的 DSL。機(jī)器可讀意味著兩件事一是可以被工具解析二是可以被校驗(yàn)。只有機(jī)器能讀懂才能自動(dòng)生成代碼、自動(dòng)生成測(cè)試、自動(dòng)檢測(cè)變更影響面。我見(jiàn)過(guò)不少團(tuán)隊(duì)把 OpenAPI 文檔寫得漂漂亮亮但從來(lái)不拿它生成任何東西只用來(lái)做展示。這其實(shí)還是文檔驅(qū)動(dòng)不是規(guī)格驅(qū)動(dòng)。真正的規(guī)格驅(qū)動(dòng)是你在規(guī)格文件里改一個(gè)字段名重新跑一次生成命令后端模型、前端類型定義、接口測(cè)試樁全部同步更新。如果做不到這一點(diǎn)規(guī)格就還是“死”的。2.2 單一事實(shí)來(lái)源的威力與代價(jià)單一事實(shí)來(lái)源是規(guī)格驅(qū)動(dòng)開(kāi)發(fā)的基石。所有下游產(chǎn)物都從規(guī)格派生不允許手工修改派生結(jié)果。這樣做的好處顯而易見(jiàn)一致性有了根本保障。但代價(jià)也很直接規(guī)格本身的變更變得極其敏感。改一個(gè)字段可能影響五六個(gè)模塊所以規(guī)格的版本管理、變更評(píng)審、兼容性檢查必須跟上。我的經(jīng)驗(yàn)是規(guī)格文件一定要納入版本控制并且每次變更都要走一次“影響面分析”。很多工具鏈支持在生成代碼時(shí)輸出變更報(bào)告告訴你哪些文件會(huì)受影響。如果沒(méi)有這個(gè)機(jī)制規(guī)格驅(qū)動(dòng)反而會(huì)變成災(zāi)難因?yàn)橐惶幮「膭?dòng)可能悄無(wú)聲息地破壞另一個(gè)端的邏輯。2.3 規(guī)格驅(qū)動(dòng)與測(cè)試驅(qū)動(dòng)、領(lǐng)域驅(qū)動(dòng)的邊界規(guī)格驅(qū)動(dòng)開(kāi)發(fā)經(jīng)常和測(cè)試驅(qū)動(dòng)開(kāi)發(fā)、領(lǐng)域驅(qū)動(dòng)設(shè)計(jì)混在一起談。它們有交集但側(cè)重點(diǎn)不同。測(cè)試驅(qū)動(dòng)開(kāi)發(fā)關(guān)注的是“先寫測(cè)試再寫實(shí)現(xiàn)”驅(qū)動(dòng)力來(lái)自測(cè)試用例。領(lǐng)域驅(qū)動(dòng)設(shè)計(jì)關(guān)注的是“用領(lǐng)域模型統(tǒng)一語(yǔ)言”驅(qū)動(dòng)力來(lái)自業(yè)務(wù)概念。規(guī)格驅(qū)動(dòng)開(kāi)發(fā)關(guān)注的是“用結(jié)構(gòu)化規(guī)格統(tǒng)一契約”驅(qū)動(dòng)力來(lái)自接口和數(shù)據(jù)定義。三者可以疊加使用。比如你先用領(lǐng)域驅(qū)動(dòng)設(shè)計(jì)梳理出核心概念再用規(guī)格驅(qū)動(dòng)開(kāi)發(fā)把這些概念固化成接口契約最后用測(cè)試驅(qū)動(dòng)開(kāi)發(fā)保證實(shí)現(xiàn)符合契約。但如果你只做規(guī)格驅(qū)動(dòng)不做領(lǐng)域建模規(guī)格可能會(huì)變得零碎只做測(cè)試驅(qū)動(dòng)不做規(guī)格約束測(cè)試用例可能覆蓋不全。理解它們的邊界才能組合出適合自己的工作流。3. 從零搭建一套規(guī)格驅(qū)動(dòng)工作流3.1 選型用什么格式描述規(guī)格選型沒(méi)有絕對(duì)標(biāo)準(zhǔn)但有幾個(gè)維度必須考慮。第一是生態(tài)成熟度有沒(méi)有現(xiàn)成的代碼生成器、校驗(yàn)器、文檔工具。第二是表達(dá)力能不能描述你需要的所有約束比如枚舉、范圍、嵌套、聯(lián)合類型。第三是學(xué)習(xí)成本團(tuán)隊(duì)能不能在一周內(nèi)上手。第四是版本兼容策略格式本身是否支持向后兼容的演進(jìn)。下面這張表是我在實(shí)際項(xiàng)目中對(duì)比過(guò)的幾種常見(jiàn)規(guī)格格式供你參考。格式表達(dá)力生態(tài)工具學(xué)習(xí)曲線適合場(chǎng)景OpenAPI中高非常豐富中等HTTP 接口、RESTful 服務(wù)JSON Schema高豐富中等數(shù)據(jù)結(jié)構(gòu)校驗(yàn)、配置定義Protocol Buffers高豐富中等偏高高性能 RPC、跨語(yǔ)言數(shù)據(jù)交換GraphQL SDL中高豐富中等圖狀數(shù)據(jù)查詢接口自定義 DSL取決于設(shè)計(jì)需自建高特定領(lǐng)域、特殊約束我個(gè)人的建議是如果你的場(chǎng)景是 HTTP 接口優(yōu)先考慮 OpenAPI如果是內(nèi)部服務(wù)間的高性能通信Protocol Buffers 更合適如果只是校驗(yàn)數(shù)據(jù)結(jié)構(gòu)JSON Schema 足夠。不要為了追求“統(tǒng)一”而強(qiáng)行用一種格式覆蓋所有場(chǎng)景那樣往往得不償失。3.2 目錄結(jié)構(gòu)與命名約定規(guī)格文件放哪里、怎么命名看似小事實(shí)則影響長(zhǎng)期維護(hù)。我推薦的做法是單獨(dú)建一個(gè)spec目錄與src平級(jí)。內(nèi)部按領(lǐng)域或模塊劃分子目錄每個(gè)規(guī)格文件用“領(lǐng)域-版本”命名比如user-v1.yaml、order-v2.yaml。版本號(hào)寫在文件名里而不是靠 Git 分支區(qū)分這樣生成代碼時(shí)可以明確指定版本。另外規(guī)格文件里一定要有info或metadata段落記錄負(fù)責(zé)人、最后更新日期、變更摘要。這些信息在排查問(wèn)題時(shí)非常有用。很多團(tuán)隊(duì)忽略這一點(diǎn)結(jié)果半年后沒(méi)人知道某個(gè)字段為什么是那個(gè)類型。3.3 代碼生成與校驗(yàn)的流水線設(shè)計(jì)流水線的基本邏輯是規(guī)格文件變更觸發(fā)校驗(yàn)校驗(yàn)通過(guò)后觸發(fā)代碼生成生成結(jié)果自動(dòng)提交或推送到各端倉(cāng)庫(kù)。校驗(yàn)包括語(yǔ)法校驗(yàn)、語(yǔ)義校驗(yàn)、兼容性校驗(yàn)。語(yǔ)法校驗(yàn)檢查格式是否合法語(yǔ)義校驗(yàn)檢查引用是否完整、類型是否匹配兼容性校驗(yàn)檢查新版本是否破壞了舊版本的契約。代碼生成要分端配置。后端生成模型類和接口骨架前端生成類型定義和請(qǐng)求函數(shù)測(cè)試端生成樁數(shù)據(jù)和基礎(chǔ)用例。生成結(jié)果不要手工修改如果發(fā)現(xiàn)生成結(jié)果不符合預(yù)期應(yīng)該回頭改規(guī)格或改生成模板而不是直接改生成物。這一點(diǎn)必須作為團(tuán)隊(duì)鐵律否則規(guī)格驅(qū)動(dòng)很快就會(huì)名存實(shí)亡。4. 實(shí)操過(guò)程中的關(guān)鍵細(xì)節(jié)與避坑指南4.1 規(guī)格變更的影響面分析怎么做影響面分析是規(guī)格驅(qū)動(dòng)開(kāi)發(fā)中最容易被忽視、也最容易出事的環(huán)節(jié)。我的做法是每次規(guī)格變更前先跑一次“差異分析”把新舊規(guī)格做結(jié)構(gòu)化對(duì)比輸出變更列表。然后根據(jù)變更類型判斷影響等級(jí)。字段新增通常是低風(fēng)險(xiǎn)字段刪除或類型修改是高危。對(duì)于高危變更必須人工評(píng)審并且要求各端負(fù)責(zé)人確認(rèn)。工具層面很多規(guī)格工具鏈自帶 diff 功能。如果沒(méi)有可以自己寫一個(gè)簡(jiǎn)單的腳本把規(guī)格解析成樹(shù)結(jié)構(gòu)遞歸對(duì)比節(jié)點(diǎn)。關(guān)鍵是要把變更報(bào)告存檔方便回溯。我踩過(guò)的坑是有一次改了一個(gè)枚舉值以為只影響后端結(jié)果前端有個(gè)硬編碼的映射表沒(méi)同步導(dǎo)致線上展示異常。從那以后我要求所有枚舉變更必須全端通知。4.2 生成代碼的可讀性與可調(diào)試性自動(dòng)生成的代碼往往可讀性差這是很多團(tuán)隊(duì)抵觸規(guī)格驅(qū)動(dòng)的原因之一。解決辦法有兩個(gè)一是優(yōu)化生成模板讓生成的代碼符合團(tuán)隊(duì)代碼規(guī)范加上必要的注釋和文檔鏈接二是保留手工擴(kuò)展點(diǎn)比如生成接口骨架后允許在單獨(dú)的擴(kuò)展文件里寫業(yè)務(wù)邏輯而不是直接改生成文件。調(diào)試時(shí)如果發(fā)現(xiàn)生成代碼有問(wèn)題第一反應(yīng)應(yīng)該是“規(guī)格是不是寫錯(cuò)了”或“模板是不是有 bug”而不是直接改生成物。我習(xí)慣在生成代碼頭部加一行注釋標(biāo)明來(lái)源規(guī)格文件和生成時(shí)間這樣排查時(shí)能快速定位。4.3 團(tuán)隊(duì)協(xié)作中的認(rèn)知對(duì)齊規(guī)格驅(qū)動(dòng)開(kāi)發(fā)不只是技術(shù)問(wèn)題更是協(xié)作問(wèn)題。最大的阻力往往來(lái)自“習(xí)慣”。有人覺(jué)得寫規(guī)格浪費(fèi)時(shí)間有人覺(jué)得生成代碼不可控有人擔(dān)心規(guī)格變更太頻繁。我的經(jīng)驗(yàn)是先在一個(gè)小模塊試點(diǎn)用實(shí)際效果說(shuō)話。當(dāng)大家看到聯(lián)調(diào)時(shí)間縮短、接口問(wèn)題減少、文檔自動(dòng)更新抵觸情緒自然會(huì)降低。另外規(guī)格評(píng)審要納入日常流程但不能太重。我通常要求規(guī)格變更走一個(gè)輕量級(jí)的合并請(qǐng)求至少有一個(gè)相關(guān)端的人 approve。這樣既保證了溝通又不至于拖慢節(jié)奏。5. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄5.1 規(guī)格與實(shí)現(xiàn)不一致怎么辦這是最常見(jiàn)的問(wèn)題。表現(xiàn)是規(guī)格里定義了某個(gè)字段但代碼里沒(méi)有或者類型不對(duì)。排查思路是先確認(rèn)生成流程是否跑過(guò)再確認(rèn)生成物是否被手工修改過(guò)最后確認(rèn)規(guī)格本身是否寫錯(cuò)。我建議在 CI 里加一個(gè)檢查步驟每次構(gòu)建時(shí)重新生成代碼并對(duì)比如果有差異就報(bào)錯(cuò)。這樣能強(qiáng)制保證規(guī)格與實(shí)現(xiàn)同步。5.2 生成代碼沖突怎么處理多人協(xié)作時(shí)生成代碼可能產(chǎn)生合并沖突。處理原則是不要手工解決生成代碼的沖突而是回到規(guī)格文件解決規(guī)格的沖突然后重新生成。如果規(guī)格本身沒(méi)有沖突只是生成時(shí)間不同導(dǎo)致的差異直接重新生成覆蓋即可。為了減少這類問(wèn)題我建議把生成代碼放在單獨(dú)的目錄并且標(biāo)記為“自動(dòng)生成請(qǐng)勿手工修改”。5.3 規(guī)格版本升級(jí)的兼容性策略規(guī)格演進(jìn)是必然的。兼容性策略有三種向后兼容、向前兼容、破壞性變更。向后兼容是新增字段不影響舊客戶端向前兼容是舊客戶端能忽略新字段破壞性變更則需要版本號(hào)升級(jí)和遷移計(jì)劃。我的建議是盡量只做向后兼容的變更破壞性變更必須走正式評(píng)審并且提供遷移窗口。規(guī)格文件里可以用deprecated標(biāo)記即將廢棄的字段給各端留出調(diào)整時(shí)間。下面這張表整理了我遇到過(guò)的典型問(wèn)題與應(yīng)對(duì)方法方便你快速查閱。問(wèn)題現(xiàn)象可能原因排查步驟解決建議生成代碼缺少字段規(guī)格未定義或生成器未更新檢查規(guī)格文件、重新生成補(bǔ)全規(guī)格更新生成器接口聯(lián)調(diào)類型不匹配各端生成時(shí)間不同步對(duì)比各端生成物版本統(tǒng)一觸發(fā)一次全量生成規(guī)格校驗(yàn)通過(guò)但運(yùn)行報(bào)錯(cuò)語(yǔ)義約束未覆蓋補(bǔ)充語(yǔ)義校驗(yàn)規(guī)則增加自定義校驗(yàn)器變更后舊客戶端異常破壞性變更未通知檢查變更報(bào)告回滾或提供兼容層生成代碼可讀性差模板未優(yōu)化檢查生成模板優(yōu)化模板增加注釋5.4 獨(dú)家避坑技巧第一個(gè)技巧規(guī)格文件里不要寫業(yè)務(wù)邏輯。規(guī)格只描述結(jié)構(gòu)和約束不要試圖用規(guī)格表達(dá)復(fù)雜的業(yè)務(wù)規(guī)則。業(yè)務(wù)規(guī)則應(yīng)該放在代碼里規(guī)格只負(fù)責(zé)契約。第二個(gè)技巧生成代碼的目錄要加入 .gitignore 的例外確保生成物被提交但又要標(biāo)記清楚。第三個(gè)技巧定期做一次“規(guī)格健康檢查”清理廢棄字段、統(tǒng)一命名風(fēng)格、更新文檔鏈接。第四個(gè)技巧給規(guī)格變更設(shè)置一個(gè)“冷靜期”高危變更提交后不要立即合并留出半天時(shí)間讓各端確認(rèn)。6. 規(guī)格驅(qū)動(dòng)開(kāi)發(fā)的適用邊界與個(gè)人體會(huì)規(guī)格驅(qū)動(dòng)開(kāi)發(fā)不是銀彈。它最適合的場(chǎng)景是多端協(xié)作、接口頻繁變更、數(shù)據(jù)契約復(fù)雜。如果你的項(xiàng)目是單人開(kāi)發(fā)、需求穩(wěn)定、沒(méi)有跨端同步問(wèn)題強(qiáng)行上規(guī)格驅(qū)動(dòng)反而會(huì)增加負(fù)擔(dān)。我見(jiàn)過(guò)一個(gè)三人小團(tuán)隊(duì)為了“規(guī)范”搞了一套復(fù)雜的規(guī)格生成流程結(jié)果每天花在維護(hù)規(guī)格上的時(shí)間比寫業(yè)務(wù)代碼還多這就本末倒置了。另一個(gè)邊界是規(guī)格驅(qū)動(dòng)開(kāi)發(fā)對(duì)工具鏈依賴較重。如果團(tuán)隊(duì)沒(méi)有能力維護(hù)生成器和校驗(yàn)器或者選用的格式生態(tài)不成熟落地會(huì)很痛苦。所以選型時(shí)一定要優(yōu)先考慮生態(tài)不要為了“先進(jìn)”而選冷門方案。我個(gè)人在實(shí)際操作中的體會(huì)是規(guī)格驅(qū)動(dòng)開(kāi)發(fā)最大的收益不是省了多少代碼而是減少了溝通成本和回歸風(fēng)險(xiǎn)。當(dāng)規(guī)格成為唯一事實(shí)來(lái)源很多爭(zhēng)論自然消失因?yàn)榇蠹铱吹氖峭环輺|西。但前提是這份規(guī)格必須被認(rèn)真對(duì)待不能淪為形式。我見(jiàn)過(guò)太多團(tuán)隊(duì)把規(guī)格當(dāng)擺設(shè)寫完就扔那還不如不寫。最后分享一個(gè)小技巧如果你剛開(kāi)始嘗試不要一上來(lái)就全量推行。選一個(gè)接口最不穩(wěn)定、聯(lián)調(diào)最痛苦的模塊先用規(guī)格驅(qū)動(dòng)的方式重做一遍。等大家嘗到甜頭再逐步推廣。這樣阻力最小效果最明顯。規(guī)格驅(qū)動(dòng)開(kāi)發(fā)本質(zhì)上是一種協(xié)作契約技術(shù)只是載體真正的難點(diǎn)在于讓團(tuán)隊(duì)接受“先對(duì)齊再動(dòng)手”的文化。