Một sản phẩm bán hàng cần gửi đơn đã duyệt sang hệ thống vận hành. Backend đã dựng endpoint, nhưng hai đội dùng tên trạng thái khác nhau. Bên gửi thử lại khi quá thời gian chờ, bên nhận lại tạo thêm một đơn mới.
Phần chưa chốt là hành vi giữa hai hệ thống: dữ liệu bắt buộc, kết quả thành công, lỗi có thể thử lại và khóa nhận biết yêu cầu đã xử lý.
Mô tả tính năng chưa đủ để bắt đầu tích hợp
Luồng nghiệp vụ giải thích người dùng muốn đạt kết quả gì. Đặc tả API giải thích hai hệ thống trao đổi dữ liệu ra sao. Test case xác nhận hành vi đã chạy đúng hay chưa. Ba phần liên quan nhưng không thay thế nhau.
Một ticket ghi “gửi đơn hàng sang vận hành sau khi sales duyệt” vẫn để lại câu hỏi về trạng thái duyệt, dữ liệu thiếu, cách trả lỗi và nơi người vận hành kiểm tra. Nếu chỉ hỏi khi dev bắt đầu kết nối, mỗi đội sẽ tự điền phần còn thiếu theo cách riêng. Bài cách chuyển ghi chú sản phẩm thành spec và test case giúp làm rõ yêu cầu tính năng. Với tích hợp, đội cần thêm hợp đồng tại ranh giới hệ thống.
Nội dung nào phải có trong đặc tả API?
Tài liệu cần nói rõ sự kiện kích hoạt, chiều dữ liệu, nơi giữ bản ghi chính và kết quả nghiệp vụ. Mỗi trường trong request và response phải có kiểu dữ liệu, điều kiện bắt buộc, giá trị cho phép cùng ý nghĩa. Ví dụ mẫu cần đủ gần dữ liệu thật để QA dùng làm fixture, nhưng phải bỏ thông tin nhạy cảm.
Lỗi nên được chia theo hành động xử lý. Dữ liệu thiếu cần sửa đầu vào, lỗi phụ thuộc tạm thời có thể thử lại, còn lỗi xác thực phải dừng và cảnh báo người phụ trách cấu hình. Một thông báo lỗi chung không cho bên gọi biết bước tiếp theo.
Cách xử lý timeout, retry và yêu cầu trùng
Bên gọi có thể hết thời gian chờ dù bên nhận đã xử lý xong. Nếu gửi lại mà không có khóa định danh ổn định, một đơn hàng có thể được tạo nhiều lần. Đặc tả phải chốt thời gian chờ, số lần thử lại và cách nhận biết cùng một yêu cầu.
Khóa chống trùng nên gắn với hành động nghiệp vụ, không dựa vào thời điểm gửi. Khi nhận lại cùng khóa, hệ thống trả kết quả cũ hoặc trạng thái hiện tại. Nếu nội dung đã thay đổi, API cần từ chối để đội kiểm tra nguồn dữ liệu.
Quy trình chốt đặc tả trước khi viết phần tích hợp
1. Chọn một luồng nghiệp vụ cụ thể
Product mô tả sự kiện bắt đầu, trạng thái đầu vào và kết quả cần có. Các luồng khác mục đích được tách riêng.
2. Xác định trách nhiệm của từng hệ thống
Đội chốt bên tạo định danh, nơi giữ dữ liệu chính và người xử lý ngoại lệ.
3. Viết ví dụ thành công trước
Engineering tạo request và response mẫu. Product kiểm tra ý nghĩa, QA xác nhận có thể dùng để kiểm thử.
4. Liệt kê lỗi và hành động tiếp theo
Đội rà dữ liệu thiếu, trạng thái sai, thiếu quyền và lỗi phụ thuộc. Mỗi lỗi phải chỉ rõ bên xử lý và khả năng thử lại.
5. Chốt cơ chế gửi lại và thay đổi phiên bản
Tech lead chốt timeout, retry, khóa chống trùng và cách duy trì khả năng tương thích.
6. Chuyển đặc tả thành kiểm thử
QA và engineering dùng ví dụ đã duyệt để tạo contract test, mock hoặc fixture.
Quyền truy cập phải bám theo tác vụ
API tạo đơn không nên mặc nhiên có quyền sửa khách hàng, xóa dữ liệu hoặc đọc toàn bộ lịch sử. Thông tin xác thực chỉ có quyền cần cho luồng đã chốt. Nếu yêu cầu đi qua nhiều dịch vụ, log cần giữ mã tương quan nhưng không ghi dữ liệu nhạy cảm nguyên dạng.
Thay đổi API mà không làm hỏng bên đang sử dụng
Thêm trường tùy chọn thường ít rủi ro hơn đổi tên hoặc xóa trường cũ. Đặc tả cần nêu giá trị mặc định và thời điểm trường trở thành bắt buộc. Với thay đổi không tương thích, đội phải chốt phiên bản mới, thời gian chạy song song và tiêu chí ngừng phiên bản cũ. Đây cũng là một phần của quản lý thay đổi phạm vi MVP, vì chỉnh sửa API có thể làm đổi dữ liệu, test case và mốc bàn giao.
Checklist trước khi hai phía bắt đầu tích hợp
Dữ liệu và hành vi
- Đã có request và response mẫu cho trường hợp thành công.
- Trường bắt buộc, trường tùy chọn và giá trị hợp lệ đã rõ.
- Nguồn dữ liệu chính cùng quy tắc cập nhật đã được xác nhận.
- Mỗi nhóm lỗi đều chỉ ra hành động tiếp theo.
Kỹ thuật và bàn giao
- Timeout, retry và khóa chống trùng đã được chốt.
- Quyền truy cập chỉ bao phủ tác vụ cần thiết.
- QA có thể dựng test mà không phải hỏi lại yêu cầu.
- Cách thay đổi phiên bản và thông báo cho bên sử dụng đã rõ.
Tiêu chí hoàn thành phải kiểm tra được từ hai phía
Một yêu cầu mẫu trả kết quả đúng chưa đủ để hoàn thành tích hợp. Hai đội cần kiểm tra dữ liệu sai, lỗi tạm thời, gửi trùng, thiếu quyền và khả năng truy vết. Mỗi kết quả phải quan sát được qua trạng thái hoặc log.
Nếu đội đang chuẩn bị một sản phẩm có nhiều tích hợp, hãy chốt đặc tả theo từng luồng và đưa chúng vào cùng nhịp duyệt với backlog. Dịch vụ Product Development của Auranium có thể hỗ trợ làm rõ phạm vi, API, test case và tiêu chí bàn giao trước khi đội bắt đầu phát triển.