Error Wrapper를 활용하기 위해 axios, @nestjs/common, typeorm 패키지가 추가로 필요할 수 있습니다.
API
@CircuitBreaker Method Decorator
Options
Member
Sub
Type
Required
Description
fallback
FunctionstringObject
required
CircuitBreaker state:Open 상태일 때 반환할 오류 또는 실행할 함수Function : 지정된 함수를 대신 실행합니다.String : 대신 실행할 현재 컨텍스트의 객체 내의 다른 method의 이름.eg) xxxxFallbackObject : 지정된 값을 즉시 응답합니다.
rules
Array<CircuitBreakerRule>
required
state:Open을 판단하기 위한 규칙들
exceptions
Array<typeof Error>
required
Exception 목록
times
number
required
기준 시간 내 exception 횟수
inSeconds
number
required
기준 시간(초)
fallbackForSeconds
number
required
state:Open -> state:HalfOpen 전까지 fallback으로 응답할 시간(초)
timeoutMilliSeconds
number
method의 실행이 지정된 시간(ms)보다 오래 걸릴 경우 내부적으로 ExecutionTimeoutError를 생성한다. rules 내에 ExecutionTimeoutError를 정의하여 CircuitBreaker에 영향을 줄 수 있다.
scope
CircuitBreakerScope
CircuitBreakerScope.DEFAULT : 컨텍스트를 무시하고 해당 method에서 발생하는 exception을 모두 catchCircuitBreakerScope.INSTANCE : 인스턴스 컨텍스트 내의 method에서 발생하는 exception만 catch
onCircuitOpen
(circuit: Circuit) => Promise<boolean>
state:Open이 될 때 호출되는 콜백. false를 리턴할 경우 state 변경이 되지 않는다.
onCircuitClose
(circuit: Circuit) => Promise<boolean>
state:Close가 될 때 호출되는 콜백. false를 리턴할 경우 state 변경이 되지 않는다.
에러가 발생했을때 호출되는 콜백. true가 리턴되면 에러가 무시되며, circuit에 영향을 주지 않는다.
onError
(error: any, circuit: Circuit) => Promise<void>
에러가 발생했을때 호출되는 콜백.
CircuitBreakerManager
CircuitBreakerManager.terminate()
CircuitBreaker Worker를 종료합니다. Worker가 종료되면 Circuit state 변경이 중지됩니다.
Usage
class Test {
@CircuitBreaker({
// state:Open일 경우 같은 인스턴스 내의 test1Fallback(...)를 실행합니다.
fallback: 'test1Fallback',
rules: [
// TypeormQueryTimeoutError, RequestTimeoutException, GatewayTimeoutException
// 에러가 60초 내에 10회 발생할 경우 state:Open이 되며 fallback이 수행됩니다.
{
exceptions: [TypeormQueryTimeoutError, RequestTimeoutException, GatewayTimeoutException],
times: 10,
inSeconds: 60
},
// BadGatewayException, TypeormConnectionFailedError, ServiceUnavailableException
// 에러가 5초 내에 30회 발생할 경우 state:Open이 되며 fallback이 수행됩니다.
{
exceptions: [BadGatewayException, TypeormConnectionFailedError, ServiceUnavailableException],
times: 30,
inSeconds: 5
}
],
// state:Open이 된 후 5초 후에 state:HalfOpen 상태가 되며 일부 호출이 정상적으로 수행됩니다.
// 이 때 에러가 발생하는 경우 다시 state:Open으로 변경되며 5초 후에 다시 state:HalfOpen으로 변경됩니다.
// state:HalfOpen 상태에서 정상적인 응답을 한 경우 state:Closed 상태가 됩니다.
fallbackForSeconds: 5,
})
test1(arg: string) {
if (arg === 'error') throw new BadGatewayException();
return arg;
}
test1Fallback(arg: string) {
return 'fallback';
}
@CircuitBreaker({
scope: CircuitBreakerScope.INSTANCE,
fallback: TestFallback.test2,
// method의 수행이 1000ms 이상이 걸리게 되면 ExecutionTimeoutError 에러가 기록됩니다.
// ExecutionTimeoutError는 throw 되지 않으며 circuit breaker 내부로만 전달됩니다.
timeoutMilliSeconds: 1000,
rules: [
{ exceptions: [BadGatewayException], times: 10, inSeconds: 5 },
{ exceptions: [ExecutionTimeoutError], times: 3, inSeconds: 10 }
],
fallbackForSeconds: 3,
})
test2(arg: string) {
if (arg === 'error') throw new BadGatewayException();
return arg;
}
}
class TestFallback {
static test2(arg: string) {
return arg;
}
}
Contributors
Error Wrapper
자주 쓰이는 기능들의 error wrapper를 제공합니다.
제공되는 Error Wrapper와 모든 종류의 Error를 @CircuitBreaker({ rules[].exceptions[...] })로 catch할 수 있습니다.
ExecutionTimeoutError
@CircuitBreaker({...}) 에 timeoutMilliSeconds를 설정한 경우, 설정된 시간보다 해당 method 수행 시간이 긴 경우 ExecutionTimeoutError가 발생합니다.
TypeORM
typeorm이 설치된 경우 QueryFailedError를 세분화합니다.
SQL 질의가 실패한 경우 접속 이슈인지 타임아웃인지 여부를 구분하여 에러를 캐치할 수 있습니다.
Source Error
Converted
Condition
QueryFailedError
TypeormConnectionFailedError
QueryFailedError.driverError에 connection 단어가 포함된 경우
QueryFailedError
TypeormQueryTimeoutError
QueryFailedError.driverError에 timeout 단어가 포함된 경우
Axios -> Nestjs HttpException
Axios는 에러 발생 시 AxiosError 한가지 형태로 에러를 반환하기 때문에 exception filter에 활용하기 어렵습니다.
AxiosError를 Nestjs의 HttpException 형태로 변환하여 CircuitBreaker의 룰로 활용하면 세밀한 룰 설정이 가능합니다.