Contract Testing cho Microservices: chặn breaking change trước khi vỡ production

Microservices thường không chết vì một lỗi thuật toán quá phức tạp. Chúng chết vì một service đổi contract mà service khác không biết. Team A rename field JSON, Team B parse theo field cũ. Team payment đổi enum trạng thái, team billing coi giá trị mới là invalid. Team order publish event version mới, consumer cũ silently drop message. Kết quả là production không sập toàn bộ ngay lập tức, mà rò rỉ lỗi theo kiểu nguy hiểm nhất: một phần request fail, một phần dữ liệu sai, một phần job bị retry mãi.

Vấn đề ở đây không phải “thiếu test” theo nghĩa chung chung. Nhiều hệ thống đã có unit test, integration test, thậm chí end-to-end test, nhưng vẫn để lọt breaking change giữa các service. Lý do là các loại test đó thường không kiểm soát tốt cam kết giao tiếp giữa producer và consumer.

Đó là chỗ của contract testing.

Bài này đi sâu vào contract testing dưới góc nhìn production engineering: contract là gì, vì sao integration test chưa đủ, khi nào dùng consumer-driven contract, cách xử lý API đồng bộ và event-driven async, cách đưa contract vào CI gate, và những anti-pattern khiến team có cảm giác an toàn giả.

Contract trong microservices thực ra là gì?

Khi hai service nói chuyện với nhau, “contract” là tập kỳ vọng mà cả hai bên ngầm đồng ý. Nó có thể gồm:

• URL, HTTP method, header, auth scheme;
• shape của request/response JSON;
• field nào bắt buộc, field nào optional;
• type, enum, range, nullability;
• semantic của error code;
• ordering, idempotency, retry behavior;
• versioning rule và compatibility rule;
• với event-driven system: schema của message, key, metadata, partition semantics, delivery expectation.

Điểm quan trọng: contract không chỉ là schema syntax. Nó còn là meaning.

Ví dụ producer đổi field status: "paid" thành status: "completed". Xét về JSON schema, field vẫn là string, test kiểu dữ liệu vẫn pass. Nhưng consumer đang map paid thành trạng thái gửi hàng. Về mặt nghiệp vụ, đó vẫn là breaking change.

Vì vậy contract testing không phải magic. Nó không thay thế thiết kế API tốt. Nó là một lớp kiểm soát để những thay đổi đáng lẽ phải được thương lượng giữa team không âm thầm lọt vào production.

Vì sao integration test và end-to-end test vẫn không đủ?

Đây là chỗ nhiều team hiểu nhầm.

Unit test chỉ xác nhận logic cục bộ

Unit test nói rằng service của bạn serialize đúng JSON theo assumption hiện tại. Nó không nói service khác có còn hiểu JSON đó hay không.

Integration test thường quá gần implementation

Nhiều integration test chạy service A với database hoặc mock dependency. Nếu mock response được viết tay trong repo service A, nó dễ drift khỏi behavior thật của service B. Bạn đang test code của mình tương thích với mock của chính mình, không phải với consumer thực.

End-to-end test quá ít, quá chậm và coverage thấp

E2E rất quan trọng nhưng không thể phủ mọi biến thể contract. Một suite E2E thường chỉ cover happy path chính. Nó khó bắt được các thay đổi như:

• field optional bị xoá;
• enum thêm giá trị mới nhưng consumer parse cứng;
• event metadata đổi tên;
• nullable thành non-null hoặc ngược lại;
• response thêm nested object làm parser strict fail.

Ngoài ra, E2E chạy chậm, phụ thuộc môi trường, dễ flaky, và thường được chạy sau khi code đã merge nhiều nơi.

Contract testing lấp khoảng trống giữa unit/integration nội bộ và E2E toàn hệ thống.

Contract testing là gì và nó giải bài toán nào?

Contract testing là cách encode kỳ vọng giao tiếp giữa consumer và provider thành artifact có thể verify tự động.

Ý tưởng cốt lõi:

1. Consumer mô tả mình cần gì từ provider. 2. Provider verify rằng mình vẫn đáp ứng được kỳ vọng đó. 3. Thay đổi chỉ được merge/release nếu contract còn compatible.

Lợi ích lớn nhất không phải là “thêm test coverage”. Lợi ích thật là biến một cam kết liên-team vốn mơ hồ thành một release gate có kiểm chứng.

Producer-driven vs consumer-driven contract

Có hai hướng phổ biến.

Producer-driven contract

Provider publish OpenAPI, GraphQL schema, protobuf schema, AsyncAPI hoặc event schema. Consumer codegen hoặc validate theo schema này.

Ưu điểm:

• trung tâm hóa đặc tả;
• hợp với platform có nhiều consumer;
• dễ governance với API public.

Nhược điểm:

• schema có thể đúng về cú pháp nhưng không phản ánh kỳ vọng thực của từng consumer;
• provider dễ thêm field hoặc đổi semantic mà nghĩ là safe;
• consumer thường không có tiếng nói rõ trong release gate.

Consumer-driven contract

Consumer viết contract dựa trên đúng dữ liệu mà mình cần. Contract này sau đó được provider verify.

Ví dụ service frontend-backend hoặc order-service nói rõ:

• cần endpoint `GET /users/:id`;
• cần field `id`, `email`, `status`;
• `status` phải thuộc tập giá trị tương thích;
• khi user không tồn tại phải trả `404` với body shape X.

Ưu điểm:

• phản ánh nhu cầu thực của consumer;
• bắt được breaking change sát với use case hơn;
• giảm over-specification từ phía provider.

Nhược điểm:

• governance phức tạp hơn khi có nhiều consumer;
• artifact contract nhiều lên;
• nếu consumer mô tả quá chi tiết, provider bị khóa tay không cần thiết.

Trong môi trường nội bộ microservices, consumer-driven contract (CDC) thường đem lại nhiều giá trị nhất cho các dependency quan trọng.

Những breaking change phổ biến mà contract test nên chặn

Một số thay đổi nhìn có vẻ nhỏ nhưng rất hay gây incident:

HTTP/JSON API

• đổi tên field;
• đổi kiểu từ string sang number hoặc ngược lại;
• field từng luôn có giờ trở thành null;
• xoá field cũ vì nghĩ “không ai dùng nữa”;
• enum thêm giá trị mới nhưng consumer parse cứng;
• đổi default sort/order khiến consumer paginate sai;
• đổi semantics `404` thành `200` với object rỗng;
• đổi auth header hoặc scope requirement.

Event-driven / queue / Kafka

• đổi tên event hoặc topic;
• đổi key schema làm partitioning thay đổi;
• thêm field bắt buộc cho consumer downstream;
• consumer cũ không chịu được field thiếu hoặc nested shape mới;
• producer publish event version mới nhưng không giữ backward compatibility;
• consumer assume ordering toàn cục thay vì theo partition key.

gRPC / protobuf

• re-use field number;
• đổi semantic enum;
• remove field mà consumer cũ còn đọc;
• đổi optional/repeated theo cách generator cũ parse khác.

Contract test không chặn mọi lỗi runtime, nhưng nó chặn được lớp lỗi “hai bên không còn nói cùng một ngôn ngữ”.

Pact và mô hình consumer-driven contract cho HTTP API

Pact là công cụ nổi tiếng nhất cho CDC trên HTTP. Dù bạn có dùng Pact hay không, mô hình của nó khá hữu ích để hiểu tư duy.

Flow điển hình:

1. Consumer test tạo ra pact file mô tả interaction. 2. Pact file được publish vào broker/repository. 3. Provider trong CI pull pact về và verify với provider state tương ứng. 4. Nếu verify fail, thay đổi của provider không được release.

Ví dụ consumer không cần toàn bộ response của provider. Nó chỉ cần:

{
  "id": "u_123",
  "email": "a@example.com",
  "status": "active"
}

Consumer không nên over-specify những field không dùng. Nếu contract bắt provider trả đúng 40 field hiện tại, mọi refactor thêm metadata đều có thể làm test vô ích trở nên giòn.

Nguyên tắc quan trọng:

• **specify what matters to consumer**;
• **do not freeze irrelevant implementation detail**.

Provider state: điểm hay bị làm ẩu

Khi verify contract, provider cần dựng được state phù hợp. Ví dụ:

• user tồn tại và active;
• user không tồn tại;
• order đã paid;
• payment provider timeout;
• tenant bị disable.

Nhiều team làm provider state theo cách seed database khó bảo trì hoặc call thẳng external dependency thật. Điều này khiến contract verification chậm, flaky và mất niềm tin.

Tốt hơn là:

• provider state setup ở mức fixture ổn định;
• tách clear boundary giữa state preparation và interaction verification;
• tránh phụ thuộc hệ thống ngoài không kiểm soát được;
• không dùng production snapshot thật trừ khi đã sanitize kỹ.

Nếu provider state setup quá phức tạp, thường đó là tín hiệu API boundary đang rối hoặc service đang ôm quá nhiều trách nhiệm.

Contract testing cho event-driven system khó hơn HTTP, nhưng còn đáng làm hơn

Trong hệ thống event-driven, lỗi contract còn nguy hiểm hơn vì chúng thường không fail ngay ở request path. Producer publish message thành công, queue vẫn xanh, nhưng consumer parse fail âm thầm, hoặc drop message vào dead-letter queue sau vài giờ.

Với event-driven contract, cần kiểm soát ít nhất 4 lớp:

1. Schema compatibility — field, type, enum, nullability; 2. Semantic compatibility — ý nghĩa business của event; 3. Metadata compatibility — event name, version, source, correlation ID; 4. Delivery assumptions — ordering, idempotency, retry, duplicate handling.

Schema registry không phải silver bullet

Kafka/Avro/Protobuf teams thường dùng schema registry để enforce compatibility. Đây là nền tảng tốt, nhưng chưa đủ.

Schema registry có thể nói rằng schema mới backward-compatible theo rule kỹ thuật. Nhưng nó không biết rằng consumer hiện tại đang hiểu status=paid theo nghĩa “đủ điều kiện ship hàng”, còn producer đổi semantics thành “payment authorized but not captured”.

Vì vậy với event-driven system, nên kết hợp:

• schema compatibility check;
• contract/integration test ở mức consumer behavior;
• idempotency test;
• replay test với sample event thật đã sanitize.

Backward compatibility: quy tắc sống còn cho producer

Nếu producer có nhiều consumer, producer phải xem backward compatibility là mặc định, không phải ngoại lệ.

Một số quy tắc thực chiến:

• thêm field mới thường an toàn hơn xoá field cũ;
• consumer nên tolerate unknown field;
• đừng đổi meaning của field cũ nếu chưa version rõ;
• enum mới chỉ an toàn nếu consumer không parse cứng;
• field optional tốt hơn field required khi rollout dần;
• deprecation phải có thời gian chuyển tiếp và audit consumer usage.

Với API đồng bộ, cách rollout an toàn thường là:

1. thêm field mới; 2. giữ field cũ một thời gian; 3. cập nhật consumer; 4. theo dõi usage; 5. chỉ xoá field cũ khi đã xác nhận không còn ai dùng.

Với event, rollout còn cần cẩn thận hơn vì message đã publish không sửa lại được. Khi semantics đổi lớn, phát event version mới hoặc topic mới thường an toàn hơn “lén đổi format trên topic cũ”.

Contract testing nên đứng ở đâu trong CI/CD?

Nếu contract testing chỉ chạy kiểu best-effort sau merge, giá trị của nó giảm mạnh. Nó nên là một release gate có chủ đích.

Cho consumer

Trong CI của consumer:

• chạy consumer test tạo contract artifact;
• publish contract vào broker/repo nội bộ;
• gắn version với commit SHA/build number;
• đánh dấu environment hoặc branch phù hợp.

Cho provider

Trong CI của provider:

• pull contract của các consumer liên quan;
• verify tất cả contract cần support;
• fail build nếu contract quan trọng fail;
• publish result để platform/team khác thấy trạng thái compatibility.

Trước deploy production

Trước khi promote artifact lên production, nên trả lời được câu hỏi: version này đã verify tương thích với những consumer nào?

Pact gọi ý tưởng này bằng can-i-deploy. Dù không dùng đúng tool đó, bạn vẫn nên có capability tương tự: một bước xác nhận “artifact sắp release không phá các contract đã biết”.

Contract testing không thay thế observability

Có contract test rồi vẫn có thể dính incident. Ví dụ:

• latency tăng khiến timeout dù contract đúng;
• provider trả field đúng nhưng dữ liệu business sai;
• consumer parse được event nhưng xử lý side effect lỗi;
• dependency thứ ba thay đổi behavior bên dưới provider.

Vì vậy contract testing nên được gắn với observability:

• log version của contract hoặc API schema khi có deploy;
• gắn trace theo endpoint/event version;
• theo dõi parse error rate, deserialization failure, unknown enum rate;
• monitor dead-letter queue và retry spike;
• alert khi consumer gặp schema mismatch hoặc validation fail.

Một incident pattern rất hay gặp là: deploy provider thành công, health check xanh, nhưng 20 phút sau DLQ tăng vì consumer cũ không hiểu message mới. Nếu bạn chỉ nhìn HTTP 5xx sẽ không thấy gì.

Anti-pattern: mock quá đẹp, production quá đau

1. Consumer mock response lý tưởng hơn đời thật

Mock của consumer thường chỉ chứa field đẹp và đủ. Production response thì có null, chuỗi rỗng, enum mới, timestamp lệch format, pagination edge case. Contract phải phản ánh những thứ consumer thực sự cần handle, không phải một bản demo sạch bóng.

2. Over-specify toàn bộ payload

Nếu consumer chỉ cần 3 field mà contract lock cả 30 field, provider sẽ cực khó tiến hóa. Team sẽ ghét contract test vì thấy nó chặn refactor vô nghĩa. Contract tốt nên chặt ở chỗ quan trọng và lỏng ở chỗ không liên quan.

3. Chỉ test happy path

Nếu contract chỉ mô tả 200 OK, bạn vẫn dễ vỡ khi provider đổi behavior 404, 409, 422, 429 hoặc timeout fallback. Với dependency critical, error contract cũng là contract.

4. Không có owner cho contract cũ

Consumer đã chết hoặc không còn deploy nữa nhưng contract vẫn nằm trong broker và chặn provider release. Điều này tạo “contract zombie”. Cần policy lifecycle: contract nào còn active, contract nào hết hạn, ai phê duyệt xoá.

5. Xem schema registry là đủ

Như đã nói, schema compatibility ở syntax không đồng nghĩa compatibility ở business meaning.

Khi nào contract testing đáng đầu tư mạnh nhất?

Contract testing không phải thứ phải áp vào mọi integration nhỏ nhất. Nó đáng đầu tư nhất khi có một hoặc nhiều dấu hiệu sau:

• nhiều team deploy độc lập;
• service critical thay đổi thường xuyên;
• incident do API/event drift đã từng xảy ra;
• E2E chậm và không đáng tin cậy;
• event-driven architecture có nhiều consumer ẩn;
• mobile/web/client release cadence khác backend;
• hệ thống có external partner API cần compatibility dài hạn.

Nếu app monolith nhỏ, một repo, một team, release đồng bộ, contract testing có thể chưa phải ưu tiên số một. Nhưng khi bắt đầu tách service và deploy độc lập, chi phí thiếu contract test tăng rất nhanh.

Mẫu rollout contract-safe cho API thay đổi lớn

Giả sử service user muốn đổi response profile:

Cách rủi ro

• đổi field cũ ngay trên endpoint hiện tại;
• merge và deploy;
• chờ xem consumer có lỗi không.

Cách an toàn hơn

1. Audit consumer nào đang dùng endpoint. 2. Viết/refresh consumer contract cho behavior hiện tại. 3. Provider verify contract cũ vẫn pass. 4. Thêm field mới hoặc version mới theo hướng backward-compatible. 5. Cho consumer opt-in sang behavior mới. 6. Quan sát production: parse error, fallback rate, latency. 7. Khi mọi consumer đã migrate, mới deprecate contract cũ.

Điều quan trọng là migration path phải được thiết kế như một thay đổi sản phẩm nội bộ, không phải một refactor thuần kỹ thuật.

Contract testing cho AI/agent tool calling cũng cùng bản chất

Dù bài này tập trung microservices truyền thống, nguyên lý contract cũng áp dụng rất mạnh cho AI engineering. Một tool call interface thực chất là contract giữa agent và tool runtime:

• tên tool;
• input schema;
• required/optional fields;
• error behavior;
• retry semantics;
• version compatibility.

Nếu tool team đổi schema âm thầm, agent có thể không crash rõ ràng mà chỉ giảm task success rate. Vì vậy contract testing là một tư duy rất đáng mang sang AI agent stack, nơi “integration drift” còn dễ bị bỏ qua hơn backend thường.

Checklist production cho contract testing

Trước khi nói rằng hệ thống của bạn đã có contract testing nghiêm túc, hãy kiểm tra:

• Contract nào là critical release gate, contract nào chỉ advisory?
• Consumer có mô tả cả happy path lẫn error path quan trọng không?
• Provider verify contract ở CI trước khi deploy chưa?
• Có capability kiểu `can-i-deploy` hay chưa?
• Có backward compatibility rule rõ cho API/event không?
• Có policy cleanup contract zombie không?
• Có monitor parse error, unknown enum, schema mismatch, DLQ không?
• Event có idempotency/replay test tối thiểu không?
• Team có biết khi nào cần version mới thay vì sửa contract cũ không?
• Incident postmortem có truy được breaking change ở contract layer không?

Kết luận

Microservices cho phép team deploy nhanh hơn, nhưng cũng biến integration boundary thành nơi dễ phát sinh lỗi âm thầm nhất. Nếu chỉ dựa vào mock tự viết, integration test cục bộ và một ít E2E, bạn đang đặt nhiều niềm tin vào may mắn hơn là vào release discipline.

Contract testing không làm hệ thống miễn nhiễm incident. Nhưng nó tạo ra một hàng rào rất thực dụng: đừng cho producer ship thay đổi mà consumer quan trọng không còn hiểu. Với những tổ chức đã chạm ngưỡng nhiều service, nhiều team, nhiều pipeline độc lập, đây không còn là “testing nâng cao”. Nó là hạ tầng tối thiểu để giữ tốc độ release mà không đánh đổi bằng sự bất ngờ trong production.

---

Internal link plan

• Anchor: **Distributed Tracing cho Microservices**

• Anchor: **REST API Design Checklist**

• Anchor: **Outbox Pattern trong Backend**

• Anchor: **Database Migration Zero Downtime**

• Anchor: **Incident Postmortem**

• Anchor: **LLM Structured Outputs với JSON Schema**

Social distribution angle

• **LinkedIn/Facebook hook:** “Microservice không phải cứ có integration test là an toàn. Một field đổi tên âm thầm có thể không làm 5xx tăng ngay, nhưng đủ để dữ liệu downstream hỏng cả ngày.”
• **Short angle:** 5 breaking change thường gặp giữa microservices mà unit test không bắt được.
• **Carousel idea:** Contract là gì → vì sao E2E chưa đủ → consumer-driven contract → event schema compatibility → CI release gate.