作者  | 劉俊男 ?

契約維護的難題

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

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

契約測試

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

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".

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

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

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

契約測試驅動的合作流程

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

契約測試有時修改代價高

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

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

解決的思路

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

契約先行開發

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

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

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

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

契約先行模式下，團隊的溝通閉環

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

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

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

如果在開發的過程中，哪一方再出現細節問題，需要調整契約時，可以盡早找到另一方進行討論。此時由于雙方都已經進入開發，都了解一些相應的細節，討論內容更加具體，更加高效，而且討論產生的契約變動也會更早產生效果。

契約先行的適用場景

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

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

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

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

契約先行的成本

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

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

結論

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