Mẫu circuit breaker cho API bên thứ ba trong luồng công việc trực quan

Tại sao sự cố API bên thứ ba phá vỡ hơn một tính năng

Một API bên thứ ba thường nằm giữa công việc hàng ngày: xử lý thanh toán, kiểm tra địa chỉ, đồng bộ tồn kho, gửi tin nhắn, xác thực danh tính. Khi nhà cung cấp gặp sự cố, hiếm khi chỉ một nút bị ảnh hưởng. Nó có thể làm đóng băng cả những luồng cần phản hồi đó để tiếp tục.

Đó là lý do circuit breaker quan trọng. Đây không phải lý thuyết mà là cách thực tế để giữ các hoạt động cốt lõi chạy ngay cả khi tích hợp bị lỗi.

Chậm và sập gây hại theo cách khác nhau.

Khi một API chậm, workflow vẫn cố gắng thực thi, nhưng mọi bước phải chờ. Người dùng thấy màn hình quay tròn, đội hỗ trợ nhận ticket “bị kẹt”, và công việc nền dồn ứ. Chậm khó xử lý vì có thể trông giống như hệ thống của bạn bị lỗi.

Khi một API sập, bạn gặp timeout hoặc lỗi cứng. Điều đó rõ ràng hơn, nhưng thường nguy hiểm hơn vì workflow có xu hướng retry. Khi nhiều yêu cầu retry cùng lúc, bạn tạo ra một cơn bão lưu lượng khiến việc khôi phục khó hơn và có thể kéo hệ thống của bạn xuống.

Các triệu chứng thường xuất hiện nhanh: timeout, hàng đợi ngày càng lớn, cập nhật một phần, và nhiều thao tác dọn dẹp thủ công.

Tổn hại thực sự là phản ứng dây chuyền. Nếu một nhà cung cấp tính phí vận chuyển chậm, đặt hàng sẽ chậm vì workflow từ chối xác nhận đơn nếu thiếu báo giá. Nếu thanh toán sập, đội hỗ trợ có thể không phát được hoàn tiền mặc dù mọi thứ khác vẫn hoạt động.

Bạn không thể giả vờ như sự cố không tồn tại. Mục tiêu là thiết kế workflow với đường fallback rõ ràng, quy tắc chặn tạm thời, và cảnh báo để doanh nghiệp có thể tiếp tục nhận đơn, phục vụ khách hàng và ghi nhận công việc trong khi tích hợp phục hồi.

Circuit breaker nói đơn giản

Circuit breaker là công tắc an toàn cho các cuộc gọi API. Khi một dịch vụ bên thứ ba bắt đầu thất bại, breaker ngăn workflow của bạn liên tục đập vào nó. Thay vì biến một sự cố thành màn hình chậm, timeout và công việc kẹt, bạn kiểm soát phạm vi ảnh hưởng.

Một circuit breaker có ba kết quả đơn giản:

• Cho phép gọi khi nhà cung cấp có vẻ khỏe.
• Chặn gọi khi lỗi nhiều, và ngay lập tức đi theo đường fallback.
• Thử một vài cuộc gọi kiểm tra có giới hạn sau một khoảng pause để kiểm tra xem nhà cung cấp đã trở lại chưa.

Nếu thích nhãn, đó là “closed”, “open” và “half-open”. Tên không phải điểm chính. Điều quan trọng là tính dự đoán. Khi nhà cung cấp bị “ốm”, workflow của bạn nên hành xử giống nhau mỗi lần.

Điều này không che giấu lỗi. Bạn vẫn ghi nhận thất bại, hiển thị trạng thái rõ ràng cho người dùng hoặc đội vận hành, và cảnh báo người phù hợp. Bạn chọn fail fast, chuyển công việc sang phương án an toàn hơn, hoặc tạm dừng trước khi thử lại.

Chọn những cuộc gọi API không bao giờ được chặn công việc

Circuit breaker hiệu quả nhất khi bạn chọn lọc. Không phải mọi cuộc gọi nhà cung cấp đều cần bảo vệ đặc biệt. Bắt đầu với các bước mà nếu bị chặn sẽ ngăn tiền, đơn hàng hoặc truy cập khách hàng.

Cách thực tế là theo dõi một yêu cầu người dùng từ đầu đến cuối. Ở đâu một timeout buộc người dùng bỏ cuộc hoặc tạo ra mớ hỗn độn đội bạn phải dọn sau đó?

Những cuộc gọi “không được chặn công việc cốt lõi” thường gồm thanh toán, vận chuyển và thực hiện, đăng nhập/SSO/MFA, OTP và tin nhắn xác nhận, và các kiểm tra tuân thủ gắn với phê duyệt.

Cũng tách bước hiển thị cho người dùng và công việc nền. Nếu ai đó đang chờ trên màn thanh toán, bạn cần quyết định nhanh: thành công, fallback, hoặc dừng với thông báo rõ ràng. Với công việc nền như đồng bộ số theo dõi, retry chậm hơn chấp nhận được miễn không chặn luồng chính.

Bắt đầu nhỏ để tránh lan rộng phạm vi. Bảo vệ 1–3 workflow trước, rồi mở rộng.

Xác định “fallback an toàn” trước khi xây dựng. Fallback tốt cụ thể và có thể kiểm thử:

• Thanh toán: lưu đơn ở trạng thái “payment pending” để không mất giỏ hàng.
• Vận chuyển: dùng mức giá cached, giá cố định, hoặc xác nhận đơn và hoãn mua nhãn.
• Xác thực: cho phép đăng nhập bằng mật khẩu khi SSO sập, hoặc chuyển sang xác minh qua email.
• Nhắn tin: đưa SMS vào hàng đợi và cung cấp đường thay thế nếu có thể.

Trong AppMaster’s Business Process Editor, điều này thường thành một nhánh rõ ràng: hoạt động lõi tiếp tục, trong khi bước phụ thuộc vendor đi theo một phương án thay thế được kiểm soát.

Trạng thái, ngưỡng và bộ đếm thời gian bạn có thể giải thích

Circuit breaker là công tắc an toàn. Hầu hết thời gian nó cho phép gọi. Khi nhà cung cấp bắt đầu lỗi, nó sẽ bật để bảo vệ workflow của bạn khỏi thời gian lãng phí và tích tụ lỗi.

Ba trạng thái

Closed là bình thường. Bạn gọi API và tiếp tục.

Nếu lỗi vượt ngưỡng, breaker chuyển sang Open. Bạn ngừng gọi nhà cung cấp trong một khoảng và ngay lập tức chuyển sang fallback (giá cache, đưa vào hàng đợi, luồng thay thế).

Sau thời gian cooldown, breaker vào Half-open. Bạn cho phép một số cuộc gọi thử. Nếu chúng thành công, trả về Closed. Nếu lỗi, quay lại Open.

Cần đo cái gì

Dùng tín hiệu phù hợp với kiểu lỗi nhà cung cấp:

• Timeout
• HTTP 5xx
• Độ trễ tăng (chậm đến mức không còn hữu dụng)
• Lỗi kết nối/DNS
• 429 rate limits

Trong công cụ workflow trực quan, các tín hiệu này thường map tới các kiểm tra đơn giản: status code, thời gian trôi qua, và đầu ra lỗi cụ thể.

Ngưỡng khởi tạo và hai bộ đếm thời gian quan trọng

Bắt đầu với con số dễ giải thích rồi tinh chỉnh theo lưu lượng thực. Ví dụ:

• Mở breaker nếu 5–10 cuộc gọi lỗi trong 30–60 giây.
• Hoặc mở nếu 20%–40% cuộc gọi lỗi trong một cửa sổ lăn.
• Xử lý độ trễ như lỗi khi nó vượt mức quy trình chịu được (thường 2–5 giây).

Rồi đặt hai bộ đếm:

• Cooldown time (Open): thường 30 giây đến 5 phút.
• Half-open test window: cho phép 1–5 cuộc gọi thử, hoặc cửa sổ thời gian ngắn như 10–30 giây.

Mục tiêu rõ ràng: fail fast khi nhà cung cấp không ổn, phục hồi tự động khi họ trở lại.

Từng bước: xây một circuit breaker trong workflow trực quan

Lựa chọn thiết kế quan trọng nhất là đưa quyết định “liệu chúng ta có gọi vendor ngay bây giờ không?” vào một chỗ, không rải khắp các workflow.

1) Đặt cuộc gọi nhà cung cấp sau một khối tái sử dụng

Tạo một sub-process (khối workflow tái sử dụng) mà mọi workflow dùng khi cần nhà cung cấp đó. Trong AppMaster, điều này tương ứng với một Business Process bạn có thể gọi từ endpoint hoặc automation. Giữ cho nó hẹp: nhận input, thực hiện yêu cầu nhà cung cấp, trả về kết quả rõ ràng thành công/thất bại.

2) Theo dõi lỗi theo thời gian, không chỉ đếm số lần

Ghi lại từng kết quả kèm timestamp. Lưu những thứ như last success, last failure, failures trong một cửa sổ, trạng thái hiện tại, và thời hạn cooldown.

Lưu các trường này vào bảng để breaker tồn tại sau khởi động lại và nhất quán giữa nhiều instance. PostgreSQL qua Data Designer phù hợp tốt cho việc này.

3) Định nghĩa thay đổi trạng thái bạn sẽ tuân theo mỗi lần

Giữ quy tắc đơn giản. Ví dụ: nếu 5 lỗi xảy ra trong 2 phút, chuyển sang Open. Khi Open, bỏ qua cuộc gọi nhà cung cấp cho tới khi cooldown hết. Sau cooldown, vào Half-open và cho một lần thử có kiểm soát. Nếu thành công, đóng breaker. Nếu thất bại, mở lại.

4) Phân nhánh workflow: đường vendor vs đường fallback

Trước khi gọi vendor, kiểm tra trạng thái đã lưu:

• Closed: gọi vendor rồi cập nhật success hoặc failure.
• Open: bỏ qua cuộc gọi và chạy fallback.
• Half-open: cho phép một thử có giới hạn, rồi quyết định đóng hay mở lại.

Ví dụ: nếu API mua nhãn vận chuyển sập, fallback có thể tạo đơn với trạng thái “Label pending” và đưa vào job retry, thay vì chặn checkout hoặc công việc kho.

5) Chia sẻ giữa các workflow

Nếu bạn có nhiều workflow và server, chúng phải đọc và ghi cùng một trạng thái breaker. Nếu không, một instance có thể tiếp tục dội nhà cung cấp trong khi instance khác đã quyết định tạm dừng.

Các đường fallback giữ công việc tiếp tục

Circuit breaker chỉ hữu ích nếu bạn quyết định chuyện gì xảy ra khi cuộc gọi bị chặn. Một fallback tốt giữ người dùng tiến bước, bảo vệ dữ liệu, và làm cho việc dọn dẹp sau này dễ đoán.

Chọn fallback phù hợp với nhiệm vụ. Nếu nhà cung cấp giá vận chuyển sập, bạn có thể không cần giá chính xác để chấp nhận đơn. Trong workflow trực quan, chuyển bước API lỗi sang nhánh fallback vẫn đưa ra kết quả có thể dùng được.

Thực tế, fallback thường là một trong các dạng sau:

• Dùng giá đã biết gần nhất (với giới hạn độ tươi rõ ràng).
• Dùng ước tính an toàn, kèm nhãn rõ ràng.
• Chuyển sang kiểm tra thủ công.
• Đưa công việc vào hàng đợi để retry sau (async job).

Trải nghiệm người dùng quan trọng như logic. Đừng hiển thị lỗi mơ hồ. Nói rõ chuyện đã xảy ra và người dùng có thể làm gì tiếp theo: “Chúng tôi không xác nhận được mức phí ngay lúc này. Bạn có thể đặt hàng với chi phí vận chuyển ước tính, hoặc lưu để kiểm tra.”

Cũng phân biệt outage ngắn và dài. Outage ngắn (phút) thường là “tiếp tục, retry nền”. Outage dài (giờ) có thể cần hành vi nghiêm ngặt hơn như kiểm tra thủ công hoặc phê duyệt.

Cuối cùng, theo dõi mọi fallback để dễ đối chiếu sau này. Ít nhất, ghi loại fallback, chi tiết yêu cầu gốc, những gì trả về cho người dùng (và có phải ước tính hay không), và trạng thái để theo dõi.

Quy tắc chặn tạm thời và retry thông minh

Retries không kiểm soát có thể biến vấn đề nhỏ của vendor thành sự cố thực sự. Khi nhiều workflow retry cùng lúc, chúng tạo ra spike (vấn đề “thundering herd”). Nhà cung cấp chậm hơn, hàng đợi tăng, và bạn cháy hạn mức.

Retry nên dự đoán được và có giới hạn, và phải tôn trọng trạng thái breaker. Chính sách thực tế:

• Giữ max retries thấp (thường 2–3).
• Dùng exponential backoff (ví dụ 2s, 8s, 30s).
• Thêm jitter để các retry không đồng bộ.
• Giới hạn tổng thời gian retry (ví dụ 60–90 giây).
• Nếu breaker là Open, không retry; đi thẳng vào fallback.

Chặn tạm thời liên quan nhưng khác biệt. Dùng cho trường hợp phản hồi nói “không thể làm được ngay bây giờ.” Các quy tắc phổ biến:

• 429 rate limit: chặn theo Retry-After (hoặc một cửa sổ an toàn cố định).
• 401/403 lỗi xác thực: chặn cho tới khi làm mới credentials, rồi thử một lần.
• 5xx liên tục: chặn tạm, rồi cho phép một thử nhỏ.

Trong thời gian chặn, quyết định chuyện gì với công việc đang chạy: đưa vào hàng đợi, đổi hướng, hoặc giảm chất lượng phục vụ (ví dụ, chấp nhận đơn nhưng hoãn gửi SMS).

Cảnh báo phải nói bạn cần làm gì

Circuit breaker chỉ hữu ích nếu có người biết sớm và biết phải làm gì. Mục tiêu không phải là tạo tiếng ồn mà là một thông điệp rõ ràng khi hành vi thay đổi: cuộc gọi bị chặn, fallback hoạt động, hoặc breaker mở lâu hơn dự kiến.

Kích hoạt mặc định tốt:

• Cảnh báo khi breaker mở.
• Cảnh báo nếu nó mở quá thời gian giới hạn.
• Cảnh báo khi lỗi tăng mạnh ngay cả trước khi nó mở.

Làm cho cảnh báo có thể hành động. Bao gồm vendor và endpoint, trạng thái hiện tại và khi nào thay đổi, người dùng sẽ cảm nhận thế nào, workflow đang làm gì bây giờ (chặn, retry, fallback), và một bước tiếp theo đề xuất.

Chuyển cảnh báo theo mức độ nghiêm trọng. API bổ sung không quan trọng có thể gửi email. Thanh toán, đăng nhập hoặc gửi đơn thường xứng đáng với page. Trong AppMaster điều này map rõ ràng tới các nhánh gửi email, Telegram hoặc SMS dựa trên flag severity.

Theo dõi một tập nhỏ chỉ số để biết bạn có phục hồi hay không: số cuộc gọi bị chặn và mức sử dụng fallback theo vendor thường là đủ.

Kịch bản ví dụ: nhà cung cấp sập mà không dừng đơn hàng

Một lỗi phổ biến: nhà cung cấp giá vận chuyển sập đúng lúc khách đang thanh toán. Nếu workflow của bạn bắt buộc phải có giá trực tiếp khi tạo đơn, một sự cố có thể dừng toàn bộ đơn hàng.

Trong ngày bình thường, đơn được tạo, rồi workflow yêu cầu giá trực tiếp, và đơn lưu với hãng và giá chọn.

Khi nhà cung cấp lỗi, cuộc gọi timeout hoặc trả về 5xx. Khi ngưỡng của bạn chạm (ví dụ 5 lỗi trong 2 phút), breaker mở.

Khi Open, workflow ngừng gọi nhà cung cấp trong một cửa sổ ngắn (ví dụ 10 phút). Điều đó ngăn nhà cung cấp lỗi kéo checkout của mọi người xuống.

Thay vì chặn checkout, fallback có thể:

• Áp mức phí cố định (hoặc ước tính an toàn).
• Tạo đơn vẫn xong.
• Đánh dấu là “Shipping rate pending” để tính lại sau.
• Lưu chi tiết lỗi nhà cung cấp để theo dõi.

Trong AppMaster, đây là một nhánh rõ ràng trong Business Process Editor, được hỗ trợ bởi các trường Data Designer như shipping_rate_status và shipping_rate_source.

Kiểm tra nhanh trước khi phát hành

Circuit breaker nên hành xử giống nhau khi chịu áp lực như khi demo. Trước khi phát hành, xác nhận cơ bản:

• Ngưỡng và cooldown được ghi chép và dễ thay đổi.
• Trạng thái Open chặn gọi ngay lập tức (không chờ timeout nhà cung cấp).
• Hành vi fallback an toàn cho tiền và cam kết với khách.
• Half-open probe giới hạn ở vài cuộc gọi thử.
• Logs cho thấy thời điểm và ảnh hưởng dễ trả lời.

Dành thêm thời gian cho an toàn fallback. Fallback “giữ công việc tiếp tục” cũng có thể tạo rủi ro tài chính. Nếu nhà cung cấp thanh toán sập, đánh dấu đơn là đã thanh toán rất nguy hiểm. Cách an toàn hơn là “payment pending” kèm thông điệp rõ ràng cho khách.

Kiểm thử khôi phục chủ động. Ép lỗi, theo dõi breaker mở, chờ cooldown, và xác nhận Half-open chỉ gửi probe nhỏ. Nếu probe thành công, nó nên đóng nhanh. Nếu probe thất bại, nó nên mở lại mà không tràn nhà cung cấp.

Logs của bạn nên trả lời, trong dưới một phút: ai bị ảnh hưởng, khi nào bắt đầu, bước workflow nào kích hoạt breaker, và fallback nào được dùng.

Bước tiếp theo: triển khai mẫu trong AppMaster

Chọn một tích hợp có thể gây hại hoạt động hàng ngày nếu nó lỗi (thanh toán, nhãn vận chuyển, SMS, CRM sync). Xây breaker end-to-end cho một cuộc gọi đó trước. Khi đội tin tưởng hành vi, lặp lại mẫu cho nhà cung cấp tiếp theo.

Trong AppMaster, mô hình trạng thái breaker trong PostgreSQL dùng Data Designer. Giữ đơn giản: một bản ghi cho mỗi vendor (hoặc endpoint) với các trường như state, failure_count, last_failure_at, open_until, và last_error ngắn.

Rồi triển khai logic trong Business Process Editor với các nhánh rõ ràng. Rõ ràng đánh bại khôn ngoan.

Thứ tự xây thực tế:

1. Kiểm tra trạng thái breaker và chặn cuộc gọi khi open_until ở tương lai.
2. Gọi API nhà cung cấp và ghi lại cả output thành công lẫn lỗi.
3. Khi thành công, reset counters và đóng breaker.
4. Khi thất bại, tăng counters và mở breaker khi đạt ngưỡng.
5. Chuyển các luồng hướng tới người dùng sang fallback (đưa vào hàng đợi, dùng dữ liệu cache, hoặc cho xử lý thủ công).

Ghi lại quyết định fallback bằng ngôn ngữ đơn giản để support và ops biết người dùng thấy gì.

Khi breaker mở, thông báo cho người chịu trách nhiệm bằng các module messaging của AppMaster (email, SMS, Telegram). Bao gồm những gì quan trọng: vendor, endpoint, trạng thái, và hành động khuyến nghị đầu tiên.

Nếu bạn xây workflow trong AppMaster, appmaster.io là nơi thực tế để bắt đầu vì cùng một Business Process trực quan có thể phục vụ endpoint, job nền và cảnh báo với một trạng thái breaker chung.