261008_01_ENH: 외부 API 및 bypass 원본 오류 응답 전파 기능 추가
This commit is contained in:
57
README.md
57
README.md
@@ -206,6 +206,20 @@ Content-Disposition: form-data; name="file"; filename="한글-파일.txt"
|
||||
|
||||
응답은 `statusCode`, `headers`, `body`를 제공합니다.
|
||||
|
||||
`getBody()`는 기존처럼 `Content-Type`의 charset(없거나 알 수 없으면 UTF-8)으로
|
||||
해석한 문자열을 반환하며, `getBodyBytes()`는 수신한 원본 바이트의 복사본을 반환합니다.
|
||||
charset 추출 시 다른 매개변수의 따옴표 내부 문자열은 charset 선언으로 취급하지 않습니다.
|
||||
직접 호출도 오류에서 후속 작업을 중단하려면 `requireSuccess()`를 사용합니다.
|
||||
|
||||
```java
|
||||
ExternalApiResponse response = client.put(url, headers, json).requireSuccess();
|
||||
String bulkSendKey = response.getBody();
|
||||
```
|
||||
|
||||
`requireSuccess()`는 2xx에서 같은 응답을 반환하고, 그 외 상태에서는
|
||||
`com.kri.common.feature.http.ExternalApiResponseException`을 던집니다.
|
||||
기존 호출은 명시적으로 검증하지 않으면 오류 상태도 응답 객체로 반환합니다.
|
||||
|
||||
#### `BypassClient`
|
||||
|
||||
Front에서 들어온 요청을 target API로 bypass하는 HTTP client입니다. 원본 method, query param,
|
||||
@@ -315,6 +329,47 @@ BypassResponse response = bypassClient.forward(
|
||||
`Host`, `Content-Length`, `Transfer-Encoding`, `Connection` 같은 hop-by-hop header는
|
||||
전달하지 않습니다.
|
||||
|
||||
HTTP/2 전용 `:status` 등 `:`로 시작하는 헤더도 전달하지 않습니다. 상태값은
|
||||
`BypassResponse.statusCode()`를 사용하며 일반 응답 헤더와 원본 바디는 유지합니다.
|
||||
|
||||
#### 원본 오류 응답 전달
|
||||
|
||||
대상별 `throw-on-error`의 기본값은 `false`이며, 기존처럼 비정상 HTTP 상태도
|
||||
`BypassResponse`로 반환합니다. 내부 서비스 처리에서 오류 이후 실행을 중단하려면
|
||||
해당 대상에만 활성화할 수 있습니다.
|
||||
|
||||
```yaml
|
||||
kri:
|
||||
http:
|
||||
bypass:
|
||||
enabled: true
|
||||
targets:
|
||||
nice:
|
||||
base-url: https://api.nice.example
|
||||
allowed-paths:
|
||||
- /v1/**
|
||||
throw-on-error: true
|
||||
```
|
||||
|
||||
활성화하면 응답 customizer 적용 후 최종 상태가 2xx가 아닐 때
|
||||
`ExternalApiResponseException`을 던집니다. 호출별 명시적 검증은
|
||||
`bypassClient.forward(...).requireSuccess()`로도 가능합니다. 연결 실패는 기존
|
||||
`BYPASS_CALL_FAILED` 처리이며, 원본 HTTP 응답이 없는 경우와 구분합니다.
|
||||
response customizer 안에서 `requireSuccess()`를 호출하거나 `ExternalApiResponseException`을
|
||||
던지면 그 예외를 그대로 전파합니다. 일반 customizer 실패는 기존 오류 처리를 유지합니다.
|
||||
|
||||
Spring MVC와 Servlet API가 있고 `kri.web.enabled=true`(기본값)이면
|
||||
`ExternalApiErrorAutoConfiguration`이 원본 응답 처리기를 자동 등록합니다.
|
||||
원본 HTTP 상태와 바디 바이트, `Content-Type`, `Content-Encoding`을 그대로 반환하므로
|
||||
상위 서비스의 오류 필드와 압축된 바디를 유지합니다. 쿠키·인증·전송 헤더는 오류
|
||||
처리기가 전달하지 않습니다. 오류 바디가 비어 있으면 빈 바디를 그대로 반환합니다.
|
||||
|
||||
공통 처리기는 이 전용 예외만 처리하며 일반 공통 오류 처리보다 먼저 적용됩니다.
|
||||
소비 서비스가 `externalApiResponseAdvice`라는 이름으로 자체 오류 처리기 Bean을
|
||||
제공하면 기본 등록을 대체할 수 있으며 runtime 구현에 의존할 필요가 없습니다.
|
||||
예외를 컨트롤러에서 명시적으로 처리할 수도 있습니다. Web이 비활성화되었거나 없는 환경에서는
|
||||
직접 예외를 처리해야 합니다. 원본 오류 바디의 외부 노출이 적절한 대상에만 활성화하세요.
|
||||
|
||||
### 암호화와 해시
|
||||
|
||||
공개 API는 `com.kri.common.feature.crypto.*`에 있습니다. 중앙 키 DB를 사용하지 않으며,
|
||||
@@ -764,6 +819,8 @@ other paths require both an allowed client IP and authentication. Exact IPs, CID
|
||||
|
||||
- `CommonWebAutoConfiguration`
|
||||
- `ErrorAdvice`
|
||||
- `ExternalApiErrorAutoConfiguration`
|
||||
- `ExternalApiResponseAdvice`
|
||||
- `TraceFilter`
|
||||
- `ServiceMdcAspect`
|
||||
- `RequestUserContextArgumentResolver`
|
||||
|
||||
Reference in New Issue
Block a user