Đồng bộ đơn hàng qua API thường vướng ngay khi hai hệ gọi cùng một việc bằng hai cách khác nhau. Một bên vừa nhận đơn, bên kia đã xem đó là dữ liệu cần xử lý. Nếu không chốt nghĩa từ đầu, đội kỹ thuật sửa mãi vẫn lệch.
Chúng tôi thường bắt đầu bằng một sơ đồ ngắn, rồi mới viết mã. Sơ đồ ấy trả lời ba câu: đơn đang ở đâu, đã được kéo chưa, và bên nào có quyền sửa.
Đơn hàng đi qua những trạng thái nào
Người mới thường nhìn trạng thái như một nhãn để hiển thị. Với đội tích hợp, đó là tín hiệu quyết định dữ liệu được ghi, chờ hay xử lý lại. Hiểu sai một nhãn sẽ kéo theo cả chuỗi quyết định sai.
Mona.Academy, nền tảng SaaS bán khóa học online của The MONA Group, công khai nhóm API Đơn hàng & Thanh toán. Nhóm này nằm trong chín nhóm tài liệu API công khai. Đây là điểm đội kỹ thuật cần đọc trước khi tự đặt quy ước nội bộ.
Chúng tôi không tự bịa tên trạng thái rồi gán ngược cho dữ liệu nguồn. Đội ngũ giữ nguyên giá trị nhận được, kèm bản ghi thô để đối chiếu. Sau đó, chúng tôi mới ánh xạ sang cách gọi của hệ nội bộ.
Ở hệ nội bộ, chúng tôi thường chia luồng theo ý nghĩa xử lý. Một đơn vừa được ghi nhận khác với đơn đang chờ kiểm tra. Đơn đã hoàn tất cũng khác dữ liệu cần dừng hoặc xem lại. Đây là quy ước của đội triển khai, không phải tên trạng thái do Mona.Academy công bố.
Mỗi quy ước cần đi kèm điều kiện vào và điều kiện ra. Đừng ghi kiểu “đã xong” rồi để mỗi người hiểu một nghĩa. Hãy mô tả dữ liệu nào khiến đơn chuyển bước, và dữ liệu nào buộc nó đứng lại.
Gọi đúng tên mốc thời gian và trạng thái
Khi cần xác nhận phạm vi nền tảng, đội kỹ thuật nên bắt đầu từ Mona Academy chính thức. Trang chủ giúp đặt API vào đúng bối cảnh sản phẩm. Việc triển khai chi tiết vẫn phải bám tài liệu kỹ thuật được cấp.
Mốc thời gian cũng cần được gọi đúng tên. Thời điểm hệ nội bộ nhận dữ liệu không đồng nghĩa thời điểm trạng thái phát sinh ở nguồn. Nếu phản hồi có mốc thời gian, chúng tôi lưu đúng mốc ấy. Nếu không có, đội ngũ chỉ ghi giờ tiếp nhận của chính mình.
Trước khi viết bộ chuyển trạng thái, chúng tôi lập một bảng làm việc nội bộ. Mỗi dòng có giá trị gốc, nghĩa đã xác minh và hành động được phép. Trạng thái lạ phải đi vào hàng chờ kiểm tra, thay vì tự rơi vào nhánh thành công.
Kéo đơn về hệ nội bộ mà không trùng
Sau khi hiểu trạng thái, bài toán tiếp theo là nhận cùng một đơn nhiều lần mà dữ liệu vẫn sạch. Việc gọi lại API vốn không đáng sợ. Phần đáng ngại nằm ở thao tác ghi thiếu khóa chống trùng.
Chúng tôi chọn khóa nhận diện từ dữ liệu mà phản hồi thực sự trả về. Tên trường phải lấy đúng trong tài liệu, không đoán theo thói quen. Khóa ấy được lưu cùng nguồn gọi để tránh hai nguồn dùng chung một giá trị.
Trong cơ sở dữ liệu, khóa này cần một ràng buộc chống trùng. Nói đời thường, hệ thống phải từ chối tạo bản sao nếu chiếc “chứng minh thư” ấy đã tồn tại. Mã ứng dụng chỉ kiểm tra trước vẫn chưa đủ, vì hai tiến trình có thể ghi gần như cùng lúc.
Ràng buộc chống trùng nằm ở cơ sở dữ liệu
Để quan sát bảng và khóa, đội kỹ thuật có thể đọc quản lý cơ sở dữ liệu bằng Navicat. Công cụ chỉ giúp nhìn rõ hơn. Quy tắc chống trùng vẫn phải được thiết kế trong dữ liệu.
Khi bản ghi đã có, chúng tôi không tạo thêm đơn mới. Chúng tôi so phần dữ liệu vừa nhận với bản đang lưu. Phần được phép đổi mới được cập nhật; phần do hệ nội bộ quản lý được giữ nguyên.
Mỗi lần nhận dữ liệu, đội ngũ lưu cả bản thô và bản đã chuẩn hóa. Bản thô cho biết nguồn gửi gì. Bản chuẩn hóa giúp phần mềm nội bộ đọc theo một khuôn ổn định.
Người phụ trách hạ tầng có thể xem thêm cách hệ quản trị dữ liệu vận hành. Nội dung này giải thích vì sao ràng buộc phải nằm gần nơi lưu trữ. Lớp ứng dụng có thể lỗi hoặc chạy song song. Cơ sở dữ liệu vẫn là chốt kiểm tra cuối.
Tách rõ năm base URL trong cấu hình
Năm base URL công khai cần được tách rõ trong cấu hình. Base URL là địa chỉ gốc để mã nguồn ghép với đường dẫn API cụ thể. Đội ngũ không nên trộn chúng vào một biến rồi đổi thủ công khi chạy.
- saas-api.mona.academy: base URL chính, dùng cho các tác vụ API chung.
- khanhhungacademy-api.monamedia.net: một base URL riêng được công khai trong tài liệu.
- saas-email.mona.academy: base URL dành cho nhóm tác vụ liên quan tới email.
- verify-domain.mona.academy: base URL phục vụ việc xác minh tên miền.
- api.vietqr.io: base URL còn lại, nằm ngoài hệ thống MONA, phục vụ mã QR thanh toán.
Việc tách cấu hình không có nghĩa năm địa chỉ làm cùng một việc. Đội kỹ thuật chỉ gọi đúng địa chỉ mà tài liệu của tác vụ chỉ ra. Tên miền gợi ý điều gì cũng không đủ để thay thế mô tả chính thức.
Mỗi lượt kéo đơn nên có nhật ký riêng. Nhật ký ghi nguồn gọi, thời điểm nhận, kết quả xử lý và lý do bỏ qua. Mục tiêu là giúp người trực hệ thống lần được đường đi.
Đội ngũ cũng tách lỗi gọi API khỏi lỗi ghi dữ liệu. Một bên là chưa nhận được phản hồi phù hợp. Bên còn lại là đã nhận, nhưng quy tắc nội bộ không chấp nhận.
Khi chạy lại, chương trình phải đọc khóa nhận diện trước khi ghi. Nó cũng cần kiểm tra nội dung và trạng thái đã lưu. Nhờ vậy, cùng dữ liệu không tạo thêm đơn hoặc kích hoạt xử lý thừa.
Xử lý chênh lệch dữ liệu giữa hai hệ
Dữ liệu sạch lúc vừa kéo về chưa bảo đảm hai hệ sẽ luôn giống nhau. Một lượt gọi có thể dở dang. Một trạng thái cũng có thể đến sau trạng thái khác. Vì thế, đội ngũ cần một đường đối soát riêng.
Đối soát là đặt hai ảnh chụp dữ liệu cạnh nhau để tìm điểm khác. Chúng tôi không sửa ngay mọi chênh lệch. Trước hết, hệ thống phải chỉ ra trường nào lệch, giá trị nào cũ và nguồn nào vừa cung cấp dữ liệu.
Lấy tài liệu API làm căn cứ, không đoán theo kinh nghiệm cũ
Muốn xác nhận tên endpoint, cách xác thực hoặc cấu trúc phản hồi, chúng tôi mở tài liệu API Mona.Academy. Tài liệu là căn cứ cho mã tích hợp. Kinh nghiệm cũ chỉ giúp đặt câu hỏi đúng, không thay cho dữ liệu đang được công khai.
Đội kỹ thuật nên viết rõ hệ nào làm nguồn cho từng nhóm dữ liệu. Một trường có thể theo dữ liệu nguồn, còn trường nội bộ vẫn do bên nhận quản lý. Khi chưa chốt quyền quyết định, chương trình không nên tự sửa qua lại.
Chúng tôi chia chênh lệch thành ba hướng xử lý bằng ngôn ngữ nội bộ. Chênh lệch đã có luật thì hệ thống tự áp dụng. Chênh lệch chưa rõ đi vào hàng chờ. Dữ liệu không còn khác sau lần đọc lại được đóng mà không ghi thêm.
Ghi chép rõ để người khác đọc vẫn hiểu
Hàng chờ cần đủ thông tin để một người khác đọc vẫn hiểu. Chúng tôi đặt cạnh giá trị nguồn, giá trị nội bộ và quy tắc đã áp dụng. Cách ghi chép này gần với việc xây một kho kiến thức cộng đồng cho đội kỹ thuật. Lỗi đã hiểu thì không phải đoán lại.
Với dữ liệu đến không đúng thứ tự, mốc phát sinh và mốc tiếp nhận phải được xem riêng. Bản đến sau chưa chắc mới hơn về nghiệp vụ. Nếu phản hồi không cung cấp đủ căn cứ, đội ngũ giữ chênh lệch để kiểm tra.
Mỗi quy tắc sửa lệch cần chạy lại an toàn. Nghĩa là áp dụng hai lần vẫn cho cùng kết quả như một lần. Đặc tính này giúp đội vận hành khôi phục sau lỗi mà không tạo thêm bản ghi.
Chúng tôi hay thử ba tình huống trước khi bàn giao. Một đơn được nhận lặp lại, một trạng thái cũ đến muộn, và một giá trị nguồn chưa có luật ánh xạ. Đây là bài thử của hệ nội bộ, không phải mô tả tính năng sẵn có của Mona.Academy.
Sau mỗi bài thử, đội ngũ đọc nhật ký theo đường đi của đơn. Nếu phải mở nhiều nơi mới hiểu lỗi, nhật ký đang thiếu ngữ cảnh. Nếu nhật ký lộ thông tin không cần thiết, phạm vi ghi lại đang quá rộng.
Luồng đồng bộ đơn hàng qua API đáng tin cậy không dựa vào một lần gọi thành công. Nó dựa vào nghĩa trạng thái rõ, khóa chống trùng và cách xử lệch có kiểm soát. Ba phần ấy phải dùng chung một bộ quy ước.
Khi bắt tay làm, hãy chốt sơ đồ trạng thái trước rồi mới viết thao tác ghi. Sau đó, đội kỹ thuật thử chạy lại cùng dữ liệu và cố ý đưa vào một chênh lệch. Nếu hệ thống giải thích được từng quyết định, luồng đã đủ rõ để vận hành.
