260710_01_ENH: API Bypass 기능 추가

This commit is contained in:
2026-07-10 12:05:04 +09:00
parent 68dba04fd6
commit 94ea2592a7
15 changed files with 1155 additions and 1 deletions

109
README.md
View File

@@ -183,6 +183,115 @@ ExternalApiResponse res = client.post(url, headers, jsonBody);
응답은 `statusCode`, `headers`, `body`를 제공합니다.
#### `BypassClient`
Front에서 들어온 요청을 target API로 bypass하는 HTTP client입니다. 원본 method, query param,
header, body를 기반으로 target URL만 재조립하고, target 응답의 status/header/body bytes를
`BypassResponse`로 반환합니다. 응답 controller에서는 `ResponseEntity<byte[]>`로 내려주면
front는 `Content-Type`에 따라 JSON, text, blob 등을 처리할 수 있습니다.
패키지:
```java
import com.kri.common.feature.http.bypass.BypassClient;
import com.kri.common.feature.http.bypass.BypassForwardOptions;
import com.kri.common.feature.http.bypass.BypassRequestCustomizer;
import com.kri.common.feature.http.bypass.BypassResponse;
import com.kri.common.feature.http.bypass.BypassResponseCustomizer;
```
설정 예:
```yaml
kri:
http:
bypass:
enabled: true
targets:
nice:
base-url: https://api.nice.example
strip-prefix: /api/bypass/nice
allowed-paths:
- /v1/**
request-customizers:
- niceAuthCustomizer
response-customizers:
- niceResponseCustomizer
```
Controller 예:
```java
@RestController
@RequestMapping("/api/bypass/nice")
public class NiceBypassController {
private final BypassClient bypassClient;
public NiceBypassController(BypassClient bypassClient) {
this.bypassClient = bypassClient;
}
@RequestMapping("/**")
public ResponseEntity<byte[]> bypass(
HttpServletRequest request,
@RequestBody(required = false) byte[] body
) {
BypassResponse response = bypassClient.forward("nice", request, body);
return ResponseEntity
.status(response.statusCode())
.headers(response.httpHeaders())
.body(response.body());
}
}
```
Target별 request/response customizer는 소비 서비스에서 Bean으로 등록하고,
`application.yml`의 customizer bean name 목록에 연결합니다.
```java
@Bean
BypassRequestCustomizer niceAuthCustomizer() {
return (request, context) -> request.toBuilder()
.header("Authorization", "Bearer ${token}")
.queryParam("clientId", "contact")
.build();
}
@Bean
BypassResponseCustomizer niceResponseCustomizer() {
return (response, context) -> response.toBuilder()
.header("X-Bypass-Target", context.targetName())
.build();
}
```
요청 1회성 customizer도 `BypassForwardOptions`로 추가할 수 있습니다. 적용 순서는
target 설정 customizer가 먼저이고, per-request customizer가 마지막입니다.
```java
BypassResponse response = bypassClient.forward(
"nice",
request,
body,
BypassForwardOptions.builder()
.attribute("loginUserId", user.userId())
.requestCustomizer((bypassRequest, context) -> bypassRequest.toBuilder()
.header("X-User-Id", context.attribute("loginUserId", String.class))
.build())
.responseCustomizer((bypassResponse, context) -> bypassResponse.toBuilder()
.header("X-Handled-By", "contact-server")
.build())
.build()
);
```
보안상 front가 full target URL을 직접 넘기지 않게 하고, controller에서는 `targetName`을 서버
코드로 고정하는 것을 권장합니다. `allowed-paths`로 호출 가능한 path를 제한하고, 원본 요청의
`Host`, `Content-Length`, `Transfer-Encoding`, `Connection` 같은 hop-by-hop header는
전달하지 않습니다.
### JSON
#### `JsonUtil`