# Khi API của khách đổi, Pact báo trước khi tích hợp của bạn vỡ

> Contract sinh ra từ chính test của bạn, nên khách được thêm field thoải mái và chỉ bị chặn khi phá đúng phần bạn dùng.

Bản gốc: https://fdetimes.net/vi/cong-cu/pact-contract-testing-api-cua-khach/

Trong Pact, không ai ngồi viết contract bằng tay. Contract tự sinh ra khi test tự động của bên gọi API chạy, và đó là lý do công cụ này hợp với FDE hơn hầu hết các cách kiểm thử tích hợp khác.

Bạn hẳn quen với tình huống này: tích hợp của bạn gọi vào hệ thống của khách, chạy ổn suốt nhiều tuần, rồi một sáng nó vỡ vì team bên kia đổi tên một field.

Không ai báo trước, vì họ không biết code của bạn đang dùng field đó. Pact ghi lại chính xác những gì phía bạn đang dùng và đưa danh sách ấy vào CI của họ, nên lỗi lộ ra trước lúc deploy chứ không phải sau.

## Pact thật ra kiểm tra cái gì?

Trang tài liệu chính thức của Pact, do Pact Foundation duy trì, gọi nó là công cụ code-first để kiểm thử tích hợp HTTP và message bằng contract test. Hai vai cần nắm là consumer và provider. Pact định nghĩa consumer là ứng dụng dùng chức năng hoặc dữ liệu của một ứng dụng khác để làm việc của mình.

Tại dự án của khách, consumer thường là bạn: agent, pipeline dữ liệu hay service tích hợp do bạn viết. Provider là API của khách. Vì contract sinh ra từ test của consumer, nó chỉ chứa những gì consumer thật sự dùng. Phần còn lại, provider được đổi tùy ý.

**Điểm mấu chốt:** Contract tốt nhất chỉ ghi lại những gì bạn thật sự dùng, không hơn.

Ý tưởng này có trước Pact khá lâu. Năm 2006, Ian Robinson viết bài "Consumer-Driven Contracts: A Service Evolution Pattern" trên trang của Martin Fowler, gọi loại contract phía provider được định hình bởi nhu cầu của consumer là consumer-driven contract. Pact biến pattern đó thành công cụ chạy được.

## Một ví dụ từ đầu đến cuối

Thử hình dung bạn đang làm tích hợp với service đơn hàng của một khách bán lẻ. Endpoint lấy một đơn hàng trả về 30 field, nhưng code của bạn chỉ đọc 3 field: mã đơn, trạng thái và tổng tiền. Đó chính là contract bạn cần giữ.

Bước một, bạn viết consumer test cho đúng request đó và khai báo response mong đợi chỉ gồm 3 field kia. Phác thảo dưới đây chỉ minh họa nội dung kịch bản, không theo cú pháp của thư viện Pact nào:

```text
Khi consumer gửi:   GET /orders/123
Provider phải trả:  status 200
Body có ít nhất:    order_id, status, total
```

Khi test chạy, Pact dựng một mock provider: nó so request thật mà code của bạn gửi với request mong đợi, rồi trả về response đã khai báo. Code của bạn xử lý response đó như thật, và kết quả của lần chạy là một pact file.

Bước hai diễn ra bên phía khách. Pact file được dùng để verify provider thật: Pact gửi lại từng request trong file vào service của họ và kiểm tra response. Theo tài liệu của Pact, bước verify pass nếu mỗi response chứa ít nhất dữ liệu đã mô tả trong contract.

Hãy xem điều gì xảy ra khi khách đổi API theo hai cách. Họ thêm field thứ 31 cho chương trình khách hàng thân thiết: verify vẫn pass, vì 3 field bạn cần vẫn còn. Họ đổi tên field trạng thái: verify fail ngay trong CI của họ, trước khi bản đó lên production và trước khi tích hợp của bạn vỡ lúc nửa đêm.

## Ba lỗi hay gặp khi viết contract đầu tiên

Lỗi phổ biến nhất là khai báo cả 30 field chỉ vì API trả về 30 field. Contract khi đó trói khách vào cả 27 field bạn không hề đọc, mỗi thay đổi vô hại bên họ đều làm verify đỏ, và chẳng bao lâu team của khách coi bước verify là tiếng ồn.

Quy tắc đơn giản: mở code của bạn ra, field nào có dòng đọc thì mới đưa vào contract.

Lỗi thứ hai ngược lại: viết consumer test, sinh pact file, rồi dừng ở đó. Mock provider chỉ chứng minh code của bạn xử lý đúng response bạn tự mô tả. Giá trị thật chỉ đến khi pact file được dùng để verify provider thật, nên đừng tính việc xong cho tới khi bước verify chạy được bên khách.

Lỗi thứ ba là chỉ viết một kịch bản "đường đẹp". Nếu code của bạn cũng xử lý trường hợp không tìm thấy đơn hàng, đó là một kịch bản riêng cần có trong contract, vì Pact chỉ bảo vệ những gì bạn đã viết test.

## Chặn deploy bằng một exit code

Pact file cần nơi để lưu và chia sẻ, và đó là việc của Pact Broker. Broker nắm quan hệ phụ thuộc giữa các ứng dụng, nên lệnh can-i-deploy có thể trả lời một câu hỏi rất cụ thể: phiên bản sắp deploy có tương thích với các phiên bản ứng dụng khác đang chạy ở môi trường đích hay không.

Câu trả lời là exit code: 0 là được deploy, 1 là không. Vì thế nó cắm thẳng vào bất kỳ pipeline nào mà không cần ai đọc báo cáo. Nếu khách cần SSO, quản lý người dùng hay giao diện tốt hơn, tài liệu của Pact mô tả PactFlow là một bản fork thương mại của Pact Broker.

## Pact không thay được gì

Giới hạn đầu tiên nằm ngay trong cách Pact tự mô tả. FAQ của dự án nói đây là "contract by examples", khác với một schema mô tả mọi trạng thái có thể có. Pact chỉ bảo vệ những kịch bản bạn đã viết test; field nào bạn quên khai báo thì nó không giữ giùm.

Giới hạn thứ hai: FAQ liệt kê các trường hợp Pact không hợp, trong đó có API có quá nhiều consumer đến mức không thể duy trì quan hệ trực tiếp với từng bên. Một API công khai cho hàng nghìn khách thuộc loại này. Một service nội bộ của khách mà tích hợp của bạn là một trong vài consumer thì rất hợp.

Giới hạn thứ ba là chuyện con người, không phải chuyện kỹ thuật. Pact chỉ có giá trị khi team của khách đồng ý chạy bước verify trong CI của họ. Lời khuyên thực tế: đừng mở đầu bằng "cài Pact đi", mà bằng một sự cố cụ thể và một contract nhỏ đã viết sẵn cho đúng endpoint gây ra sự cố đó.

## Nên học gì trước

Bắt đầu bằng hai vai consumer và provider, vì mọi thứ khác xoay quanh chúng. Sau đó viết một consumer test cho một endpoint HTTP bằng thư viện Pact ứng với ngôn ngữ của dự án; Pact được làm cho nhiều ngôn ngữ, chẳng hạn pact-js cho TypeScript, nên hiếm khi bạn phải đổi stack.

Đọc kỹ pact file sinh ra, rồi mới đến Broker và can-i-deploy. Nếu tích hợp của bạn đi qua hàng đợi thay vì HTTP, để phần message pact, có từ bản đặc tả V3, cho sau khi đã quen luồng HTTP.

Với CV, một dòng như "đưa contract test vào CI của khách, chặn thay đổi API làm vỡ tích hợp trước khi deploy" nói được nhiều hơn chữ "Pact" trong mục kỹ năng. Khi đọc tin tuyển dụng FDE, những cụm như "integration với hệ thống của khách" hay "độ tin cậy của tích hợp" là chỗ bạn kể câu chuyện này.

Tích hợp với khách hiếm khi vỡ vì code của bạn sai. Nó thường vỡ vì hai team không biết đối phương đang dựa vào điều gì, và một pact file chính là cách viết điều đó ra để máy kiểm tra hộ.

**Thử ngay tuần này:**

- Chọn một tích hợp đang gọi API của khách, liệt kê đúng những field code của bạn đọc, và so với số field API trả về.
- Viết một consumer test Pact bằng ngôn ngữ của dự án cho một endpoint duy nhất, rồi mở pact file sinh ra để đọc.
- Hỏi team của khách xem CI của họ có chạy thêm được một bước verify không, trước khi đề xuất Pact chính thức.

## Nguồn

- [Pact Docs (docs.pact.io)](https://docs.pact.io/)

- [How Pact works](https://docs.pact.io/getting_started/how_pact_works)

- [Can I Deploy - Pact Docs](https://docs.pact.io/pact_broker/can_i_deploy)

- [Pact FAQ](https://docs.pact.io/faq)

- [Pact Foundation · GitHub](https://github.com/pact-foundation)

- [pact-foundation/pact-specification](https://github.com/pact-foundation/pact-specification)

- [Consumer-Driven Contracts: A Service Evolution Pattern](https://martinfowler.com/articles/consumerDrivenContracts.html)
