Xử Lý Thất Bại Với Circuit Breaker Trong Spring Cloud | Lộ Trình Java Spring

Circuit breaker không phải là try/catch đẹp hơn. Nó là một máy trạng thái quyết định có cho lời gọi đi qua hay không, dựa trên lịch sử lỗi gần đây. Nếu bạn bọc một lời gọi bằng circuit breaker nhưng không có timeout, không có bulkhead và không ai đọc metric, bạn chỉ thêm phức tạp mà vẫn giữ nguyên đường dẫn đến sập dây chuyền.

Bài này dùng Spring Cloud Circuit Breaker 5.0.3 với Resilience4j 2.4.0 trên Spring Boot 4.1.2: mô hình trạng thái, các tham số quan trọng, một service gọi API xa có timeout và fallback, và những chỗ cấu hình sai khiến breaker tự gây sự cố.

Cập nhật 2026

  • Hystrix đã chết. Nó ngừng từ 2018 và bị gỡ khỏi Spring Cloud Netflix từ 2020. Resilience4j là implementation mặc định của abstraction Spring Cloud Circuit Breaker.
  • Prefix cấu hình đã đổi. Cấu hình nằm dưới resilience4j.circuitbreaker.instances.* và resilience4j.timelimiter.instances.*. Chuỗi kiểu spring.cloud.circuitbreaker.resilience4j.circuitbreaker.instances trong bài cũ không phải key hợp lệ.
  • Retry có sẵn trong Framework 7. Retry đơn giản trong cùng process dùng @Retryable và @EnableResilientMethods. Khi cần breaker, bulkhead, time limiter và metric cùng một chỗ, Resilience4j vẫn là lựa chọn đầy đủ.
  • Metric không tự xuất hiện. Phải có Actuator và resilience4j-micrometer; nếu không, breaker mở mà dashboard vẫn xanh.

Ba trạng thái và cách chuyển

Ba trạng thái, mỗi trạng thái trả lời một câu hỏi khác nhau.

CLOSED  --(tỷ lệ lỗi vượt ngưỡng)-->  OPEN
OPEN    --(hết waitDurationInOpenState)-->  HALF_OPEN
HALF_OPEN --(đủ calls thử thành công)-->  CLOSED
HALF_OPEN --(một call thử thất bại)-->  OPEN

CLOSED là trạng thái bình thường: lời gọi đi qua, breaker ghi thành công, thất bại và lời gọi chậm vào cửa sổ trượt. Khi tỷ lệ lỗi vượt failureRateThreshold và đã đủ minimumNumberOfCalls, nó chuyển sang OPEN.

OPEN là trạng thái bảo vệ: không lời gọi nào đi qua. Request nhận lỗi ngay — với Resilience4j là CallNotPermittedException — thay vì chờ service đang ốm. Đây là fail fast, không phải fallback tự động; fallback là việc của code gọi. Sau waitDurationInOpenState, breaker sang HALF_OPEN.

HALF_OPEN là phép thử có kiểm soát: chỉ permittedNumberOfCallsInHalfOpenState lời gọi được đi qua. Thành công đủ thì breaker đóng lại; một lời gọi thất bại thì nó mở ngay và bắt đầu lại chu kỳ chờ. Đặt số call thử quá cao biến half-open thành đợt tấn công thứ hai vào service vừa ngã.

Năm tham số quyết định hành vi

Tham số Ý nghĩa Mặc định
failureRateThreshold Tỷ lệ lỗi (%) trong cửa sổ để chuyển sang OPEN 50
slidingWindowSize Số lời gọi (COUNT_BASED) hoặc số giây (TIME_BASED) được xét 100, COUNT_BASED
minimumNumberOfCalls Số lời gọi tối thiểu trước khi bắt đầu tính tỷ lệ lỗi 100
waitDurationInOpenState Thời gian giữ OPEN trước khi thử HALF_OPEN 60 giây
permittedNumberOfCallsInHalfOpenState Số lời gọi được đi qua khi đang thử 10

COUNT_BASED trả lời “20 lời gọi gần nhất hỏng bao nhiêu”, phù hợp lưu lượng đều. TIME_BASED trả lời “60 giây qua hỏng bao nhiêu”, phù hợp lưu lượng biến động và bắt được sự cố kéo dài dù ít request. Với TIME_BASED, minimumNumberOfCalls vẫn tính theo số lời gọi.

Mặc định là 100 lời gọi và ngưỡng 50%. Endpoint ít dùng mất rất lâu mới đủ 100 call để breaker phản ứng; endpoint bận có thể mở vì một đợt lỗi mạng ngắn. Chọn cửa sổ theo nhịp traffic thật, không theo mặc định.

Vì sao timeout là một phần của mô hình

Circuit breaker đếm lỗi trả về. Một lời gọi treo không trả về gì cả: nó không tăng bộ đếm thất bại, không làm breaker mở, nhưng vẫn giữ thread và connection của bạn. Đó là lỗi nguy hiểm nhất trong microservices, vì nó vô hình với breaker.

Vì vậy mô hình đầy đủ gồm ba lớp. TimeLimiter đặt trần thời gian và hủy future khi quá hạn. Bulkhead (cần thêm resilience4j-bulkhead) giới hạn số lời gọi đồng thời, để thread bị giữ có trần. Circuit breaker mới là lớp quyết định ngắt sau khi có đủ bằng chứng lỗi.

Factory bật TimeLimiter mặc định cho mỗi breaker. Cấu hình qua resilience4j.timelimiter.instances.catalog.timeoutDuration, hoặc tắt bằng spring.cloud.circuitbreaker.resilience4j.disable-time-limiter: true. Đừng tắt mà không thay bằng timeout ở HTTP client.

Với RestClient đồng bộ, TimeLimiter chỉ hủy future đang chạy; nó không biến socket read thành có hạn. Vẫn cần connect timeout và read timeout trên HTTP client — TimeLimiter là lớp bảo hiểm cuối, không phải thay thế.

Tầng trừu tượng của Spring Cloud

Dependency tối thiểu cho ứng dụng servlet:

<dependency>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-starter-circuitbreaker-resilience4j</artifactId>
</dependency>

Ứng dụng reactive dùng spring-cloud-starter-circuitbreaker-reactor-resilience4j. Version do BOM spring-cloud-dependencies 2025.1.4 quyết định; đừng tự ghim version lẻ.

Abstraction có hai interface: CircuitBreakerFactory cho code blocking và ReactiveCircuitBreakerFactory cho Mono/Flux. Cả hai tạo breaker theo id bằng create("catalog"), hoặc theo cặp id + group bằng create("catalog", "external"). Id chính là tên instance trong cấu hình; group cho phép nhiều breaker dùng chung một bộ tham số.

Factory áp TimeLimiter, đọc cấu hình instance và đăng ký breaker vào registry để metric hoạt động — hành vi nhất quán thay vì mỗi nơi tự new một CircuitBreaker.

Code: gọi API xa có breaker, timeout và fallback

Giả sử service catalog gọi dịch vụ báo giá. Lời gọi đi qua factory, nên TimeLimiter và cấu hình instance được áp tự động.

// File: src/main/java/com/example/shop/catalog/CatalogGateway.java
package com.example.shop.catalog;

import org.springframework.cloud.client.circuitbreaker.CircuitBreakerFactory;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestClient;

@Service
public class CatalogGateway {

    private final RestClient restClient;
    private final CircuitBreakerFactory<?, ?> circuitBreakers;

    public CatalogGateway(RestClient.Builder builder,
                          CircuitBreakerFactory<?, ?> circuitBreakers) {
        this.restClient = builder.baseUrl("http://catalog-service:8080").build();
        this.circuitBreakers = circuitBreakers;
    }

    public Quote quote(String sku) {
        return circuitBreakers.create("catalog")
                .run(() -> restClient.get()
                                .uri("/api/quotes/{sku}", sku)
                                .retrieve()
                                .body(Quote.class),
                        throwable -> Quote.unavailable(sku));
    }
}

Fallback là Function<Throwable, Quote>, nhận mọi lỗi: timeout, lỗi HTTP, hoặc CallNotPermittedException khi mạch mở. Nó không phân biệt nguyên nhân, nên phải đủ an toàn để chạy trong mọi trường hợp.

Cấu hình YAML

# File: src/main/resources/application.yml
resilience4j:
  circuitbreaker:
    metrics:
      enabled: true
    configs:
      default:
        slidingWindowType: COUNT_BASED
        slidingWindowSize: 20
        minimumNumberOfCalls: 10
        failureRateThreshold: 50
        waitDurationInOpenState: 30s
        permittedNumberOfCallsInHalfOpenState: 3
        registerHealthIndicator: true
    instances:
      catalog:
        baseConfig: default
        slowCallDurationThreshold: 2s
        slowCallRateThreshold: 60
  timelimiter:
    instances:
      catalog:
        timeoutDuration: 2s
        cancelRunningFuture: true

Tại sao 20/10/50? Cửa sổ 20 đủ để một lỗi đơn lẻ không làm mạch mở, nhưng đủ nhanh để phát hiện service chết. Tối thiểu 10 ngăn breaker kết luận từ hai request đầu của pod vừa khởi động. Ngưỡng 50% nghĩa là một nửa số lời gọi phải hỏng; nếu hệ thống chấp nhận 10% lỗi, mạch sẽ mở quá muộn.

slowCallDurationThreshold: 2s cùng slowCallRateThreshold: 60 mở rộng mô hình sang lỗi hiệu năng: 60% lời gọi chậm hơn 2 giây cũng đủ ngắt. TimeLimiter 2 giây là trần cuối; read timeout của HTTP client nên thấp hơn hoặc bằng con số này.

Property có ưu tiên cao hơn Customizer viết bằng Java; đừng chia cấu hình giữa YAML và bean rồi tự hỏi tại sao giá trị không đổi.

Fallback: ba quy tắc

Fallback là nơi mô hình bị phá hỏng nhiều nhất. Ba quy tắc:

  • Không gọi mạng. Fallback gọi service khác, database khác hoặc chính service đang ốm sẽ tạo vòng lỗi mới. Nó phải là code cục bộ, nhanh, không I/O.
  • Không ném exception. Fallback ném lỗi che lỗi gốc bằng lỗi khó debug hơn, và lớp gọi mất khả năng phân biệt “mạch mở” với “fallback hỏng”.
  • Không giấu dữ liệu cũ. Trả cache cũ là hợp lý, nhưng phải kèm dấu hiệu stale: true hoặc header tương đương. Trả dữ liệu cũ như mới là sự cố nghiệp vụ im lặng.

Khi mạch mở: làm gì và không làm gì

Khi breaker OPEN, hệ thống đã quyết định service đích không đáng thử trong vài chục giây tới. Các lựa chọn hợp lý:

  • Fail fast với mã lỗi rõ. Trả 503 kèm Retry-After để client biết đây là lỗi tạm thời.
  • Trả cache có đánh dấu. Chấp nhận dữ liệu cũ trong thời gian có hạn, kèm metadata.
  • Degrade chức năng. Ẩn widget gợi ý, trả danh sách rỗng, giữ luồng mua hàng chính.
  • Chuyển sang bất đồng bộ. Ghi yêu cầu vào queue và xử lý sau, nếu nghiệp vụ cho phép.

Và những việc không nên làm:

  • Retry storm. Retry dày đặc khi mạch mở chỉ tạo lưu lượng vô ích; mỗi lần thử đều bị chặn tức thì. Nếu có retry, bỏ qua CallNotPermittedException.
  • Fallback gọi lại service đích. Đây là retry trá hình, không backoff và không giới hạn.
  • Restart để “reset” breaker. Breaker không phải bộ đếm cần xóa; restart che mất nguyên nhân và thêm downtime.
  • Nới ngưỡng ngay khi mạch mở. Nếu mạch mở đúng, nới ngưỡng chỉ làm service đích nhận thêm tải lúc nó yếu nhất.

Decorator cho code không đi qua Spring Cloud

Không phải mọi lời gọi đều đi qua CircuitBreakerFactory. Với batch job, CLI hay worker, bạn lấy breaker từ registry và tự bọc supplier; fallback phải xử lý ở lớp gọi.

// File: src/main/java/com/example/shop/inventory/InventoryGateway.java
package com.example.shop.inventory;

import java.util.function.Supplier;

import io.github.resilience4j.circuitbreaker.CircuitBreaker;
import io.github.resilience4j.circuitbreaker.CircuitBreakerRegistry;
import io.github.resilience4j.retry.Retry;
import io.github.resilience4j.retry.RetryRegistry;
import org.springframework.stereotype.Component;
import org.springframework.web.client.RestClient;

@Component
public class InventoryGateway {

    private final RestClient restClient;
    private final CircuitBreaker breaker;
    private final Retry retry;

    public InventoryGateway(RestClient.Builder builder,
                            CircuitBreakerRegistry breakers,
                            RetryRegistry retries) {
        this.restClient = builder.baseUrl("http://inventory-service:8080").build();
        this.breaker = breakers.circuitBreaker("inventory");
        this.retry = retries.retry("inventory");
    }

    public int available(String sku) {
        Supplier<Integer> call = () -> restClient.get()
                .uri("/api/stock/{sku}", sku)
                .retrieve()
                .body(Integer.class);

        Supplier<Integer> guarded = Retry.decorateSupplier(retry,
                CircuitBreaker.decorateSupplier(breaker, call));

        return guarded.get();
    }
}

Retry.decorateSupplier và CircuitBreaker.decorateSupplier trả về Supplier mới, chưa chạy gì cho đến khi gọi get(). Thứ tự lồng nhau quyết định điều bạn đếm: retry ngoài breaker thì mỗi lần thử lại đều được ghi nhận; breaker ngoài retry thì cả chuỗi là một lời gọi logic.

TimeLimiter trong Resilience4j 2.x làm việc với Future hoặc CompletionStage, không cắt lời gọi blocking trên thread hiện tại:

TimeLimiter timeLimiter = TimeLimiter.of(Duration.ofSeconds(2));
Supplier<CompletionStage<Quote>> call = timeLimiter.decorateCompletionStage(
        scheduler, () -> quoteClient.quoteAsync(sku));

Chỉ dùng cho API trả về CompletionStage; với RestClient đồng bộ, read timeout vẫn là bắt buộc.

Metric và Actuator

Để thấy breaker qua metric, cần ba thứ: Actuator, resilience4j-micrometer, và một registry metric.

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
  <groupId>io.github.resilience4j</groupId>
  <artifactId>resilience4j-micrometer</artifactId>
</dependency>
management:
  endpoints:
    web:
      exposure:
        include: health,metrics,prometheus
  endpoint:
    health:
      show-details: always

Metric chính gồm resilience4j.circuitbreaker.state — một gauge cho mỗi trạng thái, tag state là closed, open hoặc half_open, giá trị 1 khi đang active — và resilience4j.circuitbreaker.calls với tag kind là successful, failed, not_permitted. Cả hai có tag name để phân biệt instance. Với Prometheus, thêm micrometer-registry-prometheus.

Ba thứ đáng đặt alert: not_permitted tăng liên tục (mạch đang chặn thật), gauge state=open bằng 1, và failure.rate dao động quanh ngưỡng (ngưỡng đặt quá sát lưu lượng thực).

Sáu cái bẫy

  • Bọc lời gọi cục bộ, nhanh, không thể hỏng độc lập. Breaker thêm nhiễu, mở vì lỗi nghiệp vụ (validation, null) và không bảo vệ được gì. Chỉ bọc lời gọi qua process boundary: HTTP, broker, database ngoài hệ thống.
  • Ngưỡng và cửa sổ sai. Cửa sổ 5 với tối thiểu 3 nghĩa là hai lỗi làm mạch mở; cửa sổ 100 với endpoint 10 request/phút khiến breaker mất hàng giờ mới phản ứng. Chọn theo lưu lượng đo được.
  • Không có timeout. Breaker không thấy lời gọi treo nên không bao giờ mở; thread và connection cạn dần. TimeLimiter cộng read timeout ở client, bulkhead làm trần cứng.
  • Fallback ném lỗi hoặc gọi mạng. Lỗi gốc bị che, và fallback thành dependency mới có thể sập. Fallback phải là hàm thuần, cục bộ, luôn trả về giá trị.
  • Breaker không đi kèm bulkhead. Khi mạch còn đóng hoặc half-open, một service chậm vẫn giữ thread; số thread chờ có thể bằng số request đến. Bulkhead đặt trần đồng thời.
  • Metric không xuất ra ngoài. Không Actuator, không resilience4j-micrometer, không dashboard: bạn chỉ biết breaker mở khi khách hàng gọi. Xuất metric trước khi bật breaker ở production.

Chọn công cụ nào

Công cụ Dùng khi Đừng dùng khi
Timeout / TimeLimiter Mọi lời gọi qua mạng, không có ngoại lệ Bạn tin rằng service đích không bao giờ chậm
Retry Lỗi tạm thời, thao tác idempotent, có backoff và jitter Lỗi kéo dài, thao tác không idempotent, hoặc mạch đang mở
Circuit breaker Dependency bên ngoài có thể hỏng theo đợt, cần ngừng thử để nó hồi Lời gọi cục bộ, nhanh, hoặc lỗi nghiệp vụ tất định
Bulkhead Cần giới hạn số lời gọi đồng thời để bảo vệ thread pool Chỉ cần giới hạn tổng lưu lượng, không cần giới hạn đồng thời

Retry và breaker thường đi cùng nhau, nhưng không thay nhau. Retry xử lý lỗi nhất thời của một lời gọi; breaker xử lý tình trạng hỏng kéo dài của cả dependency. Ghép sai thứ tự biến retry thành công cụ khuếch đại tải lúc service đích đang hấp hối.

Checklist

  • Ghim Spring Cloud 2025.1.4 và Boot 4.1.2; dùng starter spring-cloud-starter-circuitbreaker-resilience4j.
  • Mỗi breaker có TimeLimiter hoặc read timeout ở HTTP client; không có ngoại lệ.
  • Chọn cửa sổ và ngưỡng theo lưu lượng thật; đặt minimumNumberOfCalls đủ cao để tránh mở sớm.
  • Fallback cục bộ, không gọi mạng, không ném lỗi, đánh dấu dữ liệu cũ nếu có.
  • Bật Actuator + resilience4j-micrometer, alert cho not_permitted trước khi release; test cả ba nhánh thành công, lỗi và mạch mở.

Đi tiếp trong series: Spring Cloud là gì để nắm release train, gọi dịch vụ với OpenFeign và bài cũ về Hystrix như tài liệu lịch sử, không phải hướng dẫn cho code mới. Toàn bộ thứ tự bài nằm ở Spring Boot Roadmap.