作者  | 劉俊男 ?

契約維護的難題

如今微服務(wù)憑借其靈活、易開發(fā)、易擴展等優(yōu)勢深入人心，不同服務(wù)之間的集成和交互日漸繁多且復(fù)雜。這些服務(wù)之間交互的方式是多樣的，常見的有 HTTP 請求和消息隊列。在它們交互的過程中，會有服務(wù)的版本演進，交互信息的格式或方式就會產(chǎn)生變化，前后版本的接口可能并不兼容，甚至開發(fā)環(huán)境經(jīng)常會宕機更新，加之不同服務(wù)的開發(fā)進度有快有慢，各團隊的優(yōu)先級有高有低，在開發(fā)過程中，服務(wù)間交互方式的匹配性就成了一個問題。

這里，不同團隊之間，對服務(wù)間如何進行發(fā)送和接受消息所能達成的共同理解，我們稱之為契約 (contract)。如何采用一個合理的機制，維護服務(wù)間契約，使服務(wù)提供方和消費房能夠在不造成事故的前提下，保持各自的高效開發(fā)，越來越成為各團隊日常開發(fā)中要面對的問題。

契約測試

契約測試 (contract testing) 就是在這樣的背景下應(yīng)運而生，以下引用 Pact 官網(wǎng)的定義：

Contract testing is a technique for testing an integration point by checking each application in isolation to ensure the messages it sends or receives conform to a shared understanding that is documented in a "contract".

契約測試是一種測試集成點的技術(shù)，它通過隔離檢查每個應(yīng)用程序，以確保其發(fā)送或接收的消息，符合記錄在“契約”中的共同理解。

也就是說，在測試己方服務(wù)時，通過使用測試替身 (test double)，讓它能夠模仿我們所依賴的外界系統(tǒng)，返回相對真實的消息響應(yīng)，從而讓我方團隊在盡可能保證與外界系統(tǒng)兼容的前提下，避免受到外界系統(tǒng)宕機或開發(fā)新版本等影響，提升開發(fā)效率。再結(jié)合消費者驅(qū)動開發(fā)的優(yōu)勢，可以避免服務(wù)提供端浪費精力去實現(xiàn)不必要的功能，因此，很多團隊采用了消費者驅(qū)動的契約測試 (consumer-driven contract test) 的實踐。

在契約測試的幫助下，很多團隊真正提升了開發(fā)效率，掌握了自己的節(jié)奏，但也有些團隊發(fā)現(xiàn)效果并不明顯，因為契約測試帶來的收益并不是免費的。契約測試有著不少的開發(fā)成本，每有一個新的需求，新的接口，新的字段，或是老字段的可空性發(fā)生了改變，以及枚舉值的增加或減少，都需要增加或減少一些測試用例，然后在測試的過程中生成新的契約。這些契約大多以 OpenAPI 文檔的形式存在，作為兩個團隊日后討論的基準(zhǔn)。

契約測試驅(qū)動的合作流程

1. 消費方與提供方溝通，達成基本契約：增加一個接口，調(diào)用的時候傳一個 RequestDto，接口返回一個 ResponseDto，其中 RequestDto 和 ResponseDto 哪幾個字段要非空。
2. 消費方回去寫自己的契約測試，生成契約 (通常以 OpenApi doc 形式)，然后以契約測試驅(qū)動，開發(fā)自己的邏輯
3. 服務(wù)方拿到生成的契約，進行測試驅(qū)動開發(fā)，驗證契約是否被滿足

契約測試有時修改代價高

在使用契約測試時經(jīng)常有這樣的感受：比如，一些簡單的契約，比如非空字段和格式校驗等，每種情況都要專門的測試用例，而實現(xiàn)它卻只需要一個注解，有點得不償失。

更重要的是，隨著測試的編寫，生成的契約可能比當(dāng)時商討的更為簡單，比如一些 400, 401 等情況，有時并不會為每一個 API 寫足夠細(xì)節(jié)足夠詳盡的測試；也可能生成的契約比商討的更為詳細(xì)，比如消費方在編寫契約測試的過程中考慮到了更多的邊緣場景。因而每當(dāng)由以上情況導(dǎo)致修改契約時，我們都會重新溝通，再等待消費方重新寫契約測試，再生成契約，然后服務(wù)提供方再開發(fā)。這個從溝通到落地的閉環(huán)比較長，每次修改時，服務(wù)提供方需要等待消費方編寫測試，生成契約，然后消費方等待服務(wù)方按照契約開發(fā)完成，才能發(fā)布新的版本，這些等待都會拉低開發(fā)效率。

解決的思路

反饋周期長是我們經(jīng)常需要面對的問題，比如我們要搞快速迭代，定期 showcase，就是為了及時得到客戶的反饋；再比如我們搞結(jié)對編程，也是為了將 pull request 上可能出現(xiàn)的溝通提前，避免盲目開始之后又造成返工。這個時候我們再看開發(fā)流程時就會想，如果第一步的溝通可以直接產(chǎn)出固化的契約，足夠直觀和詳盡，讓雙方及早溝通，同時又可以使用自動化的方式約束消費方和服務(wù)方雙方，省掉重復(fù)瑣碎的契約測試，讓溝通過后雙方都可以直接開始開發(fā)就好了。

契約先行開發(fā)

這里說的契約先行，指的是在寫所有代碼之前，把我們溝通好的契約手寫出來，或者通過一些圖形化工具生成出來，比如手寫或生成一個 yaml 格式的 OpenAPI 文檔，這樣溝通的產(chǎn)出足夠直觀。把這個文檔放在代碼庫中維護，然后以它為依據(jù)，通過自動化流水線生成各方的溝通組件(sdk)，既能使雙方同時開始開發(fā)，又能對雙方進行約束。

以下以 Java + Spring 為例，通過使用 OpenAPI generator 工具生成代碼，達到以上效果。

對于消費方來說，流水線可以根據(jù)定好的契約，生成封裝好的 client 類，它提供一個簡單的方法，這個方法包含了 RestTemplate 的參數(shù)和邏輯，以及對應(yīng)的 RequestDto/ResponseDto。消費方開發(fā)人員只需要關(guān)注己方業(yè)務(wù)需要，將合適的參數(shù)傳給該方法，無需關(guān)注這些參數(shù)是用于 path 還是用于 body，該方法會以合適的方式與服務(wù)方溝通。同時我們可以定制化生成的方法，對非空字段進行校驗，達到約束效果。

對服務(wù)方來說，流水線可以生成對應(yīng)的 Controller 組件，http path 和方法的匹配等，服務(wù)方只需要復(fù)寫相應(yīng)的方法來完成自己的業(yè)務(wù)需求，無需關(guān)心傳進來的參數(shù)是屬于 path、header 或者是 body。由于定制化生成的 server 端 sdk 嚴(yán)格根據(jù)契約生成了合適的注解，比如 @NotNull?, @Size?, @Pattern 等，Spring 可以自動對注解進行校驗，server 端就可以自動拒絕不符合契約的請求。同時，由于生成的 ResponseDto 也帶有響應(yīng) validation 注解，我們也可以對服務(wù)端返回的 ResponseDto 進行約束。

契約先行模式下，團隊的溝通閉環(huán)

這樣以來，團隊的合作流程如下：

1. 消費方與提供方溝通，達成契約，并在契約代碼庫中一起提交契約代碼，即 OpenAPI doc。然后觸發(fā)流水線，生成各方代碼 sdk。
2. 雙方各自引入 sdk 進入開發(fā)。

通過觀察以上流程可以發(fā)現(xiàn)，與契約測試相比，該流程提前對溝通結(jié)果進行了直觀的固化，使雙方基于細(xì)節(jié)的溝通提前，從而將反饋周期縮短，減少返工概率。另外，契約一旦提交，自動生成的 server 端和 client 端 sdk 也同時可用，消除了開發(fā)過程中消費方和服務(wù)方之間的依賴，兩端可以并行開發(fā)，減少等待時間，提升開發(fā)效率。

如果在開發(fā)的過程中，哪一方再出現(xiàn)細(xì)節(jié)問題，需要調(diào)整契約時，可以盡早找到另一方進行討論。此時由于雙方都已經(jīng)進入開發(fā)，都了解一些相應(yīng)的細(xì)節(jié)，討論內(nèi)容更加具體，更加高效，而且討論產(chǎn)生的契約變動也會更早產(chǎn)生效果。

契約先行的適用場景

契約先行開發(fā)并非銀彈，它在解決特定場景下的問題時，才更“劃得來”。

比如契約應(yīng)簡單直接。 一些非空校驗，格式要求，簡單的字段間匹配，使用契約先行和生成代碼都是低投入高回報，生成的代碼具有非常好的約束性。但是如果契約中包含了豐富的業(yè)務(wù)邏輯，不容易在單個 OpenAPI doc 中描述的，還是手寫契約測試更加明晰，維護性也更好。

再比如我們使用的編程語言或框架需要得到 OpenAPI generator 良好的支持。 如果不能根據(jù)契約生成好用的代碼，或者在生成代碼的過程中需要做過多的定制化，那么該方法可能并不適用，或者并不劃算。

在開發(fā)過程中需要有健全的集成測試或者組件測試。 上述生成的代碼中，雖然 sdk 可以對服務(wù)間的通信進行合法性約束，但是很多單元測試并不能提前發(fā)現(xiàn)問題。比如在 server 端，我們生成的 @NotNull 等注解，需要把 Spring 啟動，且測試用例對業(yè)務(wù)邏輯具有足夠的覆蓋，才能及早發(fā)現(xiàn)問題，避免線上報錯。

契約先行的成本

天下沒有免費的午餐，在帶來上述優(yōu)勢的同時，契約先行開發(fā)也會帶來一些成本。

最主要的成本是 OpenAPI generator 的學(xué)習(xí)成本。目前 OpenAPI generator 雖然已經(jīng)可以支撐大多數(shù)的語言和框架，但是要做到足夠好用，還需要對生成代碼進行一些定制化，這些定制化需要一些時間投入。

結(jié)論

在服務(wù)間合作開發(fā)的過程中，為了維護契約的有效性，適用契約測試可以讓不同團隊之間的開發(fā)在一定程度上解耦。在一定場景下，使用契約先行的合作方式可能更高效，比如契約足夠簡單直接，開發(fā)使用的技術(shù)適用于生成的代碼，開發(fā)過程中已經(jīng)有足夠的集成測試或組件測試時，契約先行可以縮短團隊間的反饋閉環(huán)，減少等待時間，提升開發(fā)效率。