From 534380f6b2f7dbf69436f9a5c47ccfa922e507c6 Mon Sep 17 00:00:00 2001 From: kric_jspark Date: Fri, 21 Nov 2025 15:35:09 +0900 Subject: [PATCH] =?UTF-8?q?251121=5F01=5FENH=20:=20JWT=20=EC=88=98?= =?UTF-8?q?=EC=A0=95,=20CodeEnum=20=EC=B6=94=EA=B0=80,=20API=20=ED=86=B5?= =?UTF-8?q?=EC=8B=A0=20=EB=AA=A8=EB=93=88=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 68 +++++++++++++ build.gradle | 5 +- .../com/kri/common/auth/jwt/JwtService.java | 11 +-- .../kri/common/auth/jwt/JwtUserClaimsDto.java | 2 +- .../java/com/kri/common/enums/CodeEnum.java | 5 + .../com/kri/common/enums/CodeEnumUtils.java | 20 ++++ .../kri/common/http/ExternalApiClient.java | 99 +++++++++++++++++++ .../kri/common/http/ExternalApiResponse.java | 36 +++++++ .../common/jpa/AbstractCodeEnumConverter.java | 27 +++++ 9 files changed, 265 insertions(+), 8 deletions(-) create mode 100644 src/main/java/com/kri/common/enums/CodeEnum.java create mode 100644 src/main/java/com/kri/common/enums/CodeEnumUtils.java create mode 100644 src/main/java/com/kri/common/http/ExternalApiClient.java create mode 100644 src/main/java/com/kri/common/http/ExternalApiResponse.java create mode 100644 src/main/java/com/kri/common/jpa/AbstractCodeEnumConverter.java diff --git a/README.md b/README.md index c31ab3d..f9b0a32 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,74 @@ Spring Boot 기반 사내 서비스에서 공통으로 사용하는 기능들을 - 스케줄링 활성화 (`com.kri.common.scheduling`) - 기본 logback 설정 (`logback-spring.xml`) +### 공용 HTTP 클라이언트: ExternalApiClient + +외부 API와 통신하기 위한 경량 공용 모듈을 제공합니다. 추가 의존성 없이 Java 17의 `java.net.http.HttpClient`를 사용합니다. + +- 패키지: `com.kri.common.http` +- 주요 클래스: `ExternalApiClient`, `ExternalApiResponse` + +지원 메서드(문자열 body 기반) +- `ExternalApiResponse get(String url, Map headers)` +- `ExternalApiResponse post(String url, Map headers, String body)` +- `ExternalApiResponse put(String url, Map headers, String body)` +- `ExternalApiResponse patch(String url, Map headers, String body)` +- `ExternalApiResponse delete(String url, Map headers)` + +기본 동작 +- 연결 타임아웃: 10초, 요청 타임아웃: 30초 +- body가 있고 `Content-Type` 헤더가 없으면 자동으로 `application/json; charset=utf-8` 설정 +- 예외 발생 시 `RuntimeException`으로 래핑하여 전달하며, `InterruptedException` 발생 시 인터럽트 플래그를 복원 + +응답 객체(`ExternalApiResponse`) +- 필드: `statusCode`(int), `headers`(Map>), `body`(String) +- 정적 팩토리: `ExternalApiResponse.of(int, HttpHeaders, String)` + +간단 사용 예시 + +```java +import com.kri.common.http.ExternalApiClient; +import com.kri.common.http.ExternalApiResponse; +import java.util.Map; + +ExternalApiClient client = new ExternalApiClient(); + +// POST 예시 +ExternalApiResponse postResp = client.post( + "https://api.example.com/items", + Map.of("X-API-KEY", "your-key"), + "{\"name\":\"sample\"}" +); +int status = postResp.getStatusCode(); +String body = postResp.getBody(); + +// GET 예시 +ExternalApiResponse getResp = client.get( + "https://api.example.com/items/123", + Map.of("Authorization", "Bearer token") +); +if (getResp.getStatusCode() == 200) { + System.out.println(getResp.getBody()); +} +``` + +고급 사용: 커스텀 HttpClient/타임아웃 + +```java +import java.net.http.HttpClient; +import java.time.Duration; + +HttpClient httpClient = HttpClient.newBuilder() + .connectTimeout(Duration.ofSeconds(5)) + .build(); + +ExternalApiClient client = new ExternalApiClient(httpClient, Duration.ofSeconds(15)); +``` + +주의사항 +- 메서드 시그니처는 문자열 기반 body를 사용하므로, JSON 외 포맷을 전송할 경우 적절한 `Content-Type`을 직접 지정하세요. +- 대용량 응답이 예상된다면 현재 구현은 `BodyHandlers.ofString()`을 사용한다는 점에 유의하세요. + 이 문서는 **KriCommon을 사용하는 서비스(`example-service`)** 기준으로 작성되었습니다. (WebSocket 관련 기능은 현재 포함하지 않았으며, 추후 필요 시 별도 확장 예정입니다.) diff --git a/build.gradle b/build.gradle index c85f931..8b2a88a 100644 --- a/build.gradle +++ b/build.gradle @@ -4,7 +4,7 @@ plugins { } //버전 변경은 여기서 -def commonVer = "1.0.16" +def commonVer = "1.0.21" group = 'com.kri.common' version = commonVer @@ -44,6 +44,9 @@ dependencies { compileOnly 'io.swagger.core.v3:swagger-models:2.2.25' compileOnly 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0' + // JPA AttributeConverter, Entity 등 인터페이스용 + compileOnly "jakarta.persistence:jakarta.persistence-api:3.1.0" + // Lombok compileOnly 'org.projectlombok:lombok' annotationProcessor 'org.projectlombok:lombok' diff --git a/src/main/java/com/kri/common/auth/jwt/JwtService.java b/src/main/java/com/kri/common/auth/jwt/JwtService.java index de1de89..031e238 100644 --- a/src/main/java/com/kri/common/auth/jwt/JwtService.java +++ b/src/main/java/com/kri/common/auth/jwt/JwtService.java @@ -60,14 +60,13 @@ public class JwtService { claims.put("userId", dto.getUserId()); claims.put("userTeam", dto.getUserTeam()); claims.put("userName", dto.getUserName()); - claims.put("role", dto.getRole()); + claims.put("role", dto.getUserRole()); return claims; } // ====================================================== // 토큰 생성 (DTO 기반) // ====================================================== - /** * JwtUserClaimsDto 기반 Access Token 생성 * - subject = userId @@ -131,13 +130,13 @@ public class JwtService { // 숫자는 Integer / Long 등으로 들어올 수 있으니 Number로 받았다가 intValue() Number roleNumber = claims.get("role", Number.class); - Integer role = roleNumber != null ? roleNumber.intValue() : null; + Integer userRole = roleNumber != null ? roleNumber.intValue() : null; return JwtUserClaimsDto.builder() .userId(userId) .userTeam(userTeam) .userName(userName) - .role(role) + .userRole(userRole) .build(); } @@ -164,8 +163,8 @@ public class JwtService { String principal = dto.getUserId(); List authorities = new ArrayList<>(); - if (dto.getRole() != null) { - String authority = "ROLE_" + dto.getRole(); + if (dto.getUserRole() != null) { + String authority = "ROLE_" + dto.getUserRole(); authorities.add(new SimpleGrantedAuthority(authority)); } diff --git a/src/main/java/com/kri/common/auth/jwt/JwtUserClaimsDto.java b/src/main/java/com/kri/common/auth/jwt/JwtUserClaimsDto.java index 203acfb..e315fc3 100644 --- a/src/main/java/com/kri/common/auth/jwt/JwtUserClaimsDto.java +++ b/src/main/java/com/kri/common/auth/jwt/JwtUserClaimsDto.java @@ -22,5 +22,5 @@ public class JwtUserClaimsDto { String userName; @Schema(description = "권한 코드") - Integer role; + Integer userRole; } diff --git a/src/main/java/com/kri/common/enums/CodeEnum.java b/src/main/java/com/kri/common/enums/CodeEnum.java new file mode 100644 index 0000000..8d88c74 --- /dev/null +++ b/src/main/java/com/kri/common/enums/CodeEnum.java @@ -0,0 +1,5 @@ +package com.kri.common.enums; + +public interface CodeEnum { + T getCode(); +} \ No newline at end of file diff --git a/src/main/java/com/kri/common/enums/CodeEnumUtils.java b/src/main/java/com/kri/common/enums/CodeEnumUtils.java new file mode 100644 index 0000000..7cd8f1e --- /dev/null +++ b/src/main/java/com/kri/common/enums/CodeEnumUtils.java @@ -0,0 +1,20 @@ +package com.kri.common.enums; + +public final class CodeEnumUtils { + + private CodeEnumUtils() {} + + public static & CodeEnum, V> E fromCode(Class enumClass, V code) { + if (code == null) return null; + + for (E e : enumClass.getEnumConstants()) { + if (e.getCode().equals(code)) { + return e; + } + } + + throw new IllegalArgumentException( + "Unknown code [" + code + "] for enum class " + enumClass.getName() + ); + } +} \ No newline at end of file diff --git a/src/main/java/com/kri/common/http/ExternalApiClient.java b/src/main/java/com/kri/common/http/ExternalApiClient.java new file mode 100644 index 0000000..0b043ad --- /dev/null +++ b/src/main/java/com/kri/common/http/ExternalApiClient.java @@ -0,0 +1,99 @@ +package com.kri.common.http; + +import java.io.IOException; +import java.net.URI; +import java.net.http.HttpClient; +import java.net.http.HttpRequest; +import java.net.http.HttpResponse; +import java.time.Duration; +import java.util.Map; + +/** + * 간단한 외부 API 통신 모듈. + * - url, 추가 헤더, body를 받아 호출합니다. + * - GET, POST, PUT, PATCH, DELETE 메서드를 제공합니다. + * - body는 문자열(JSON 등) 기준입니다. + */ +public class ExternalApiClient { + + private final HttpClient httpClient; + private final Duration requestTimeout; + + /** + * 기본 생성자 (커넥션 풀/타임아웃 기본값 세팅) + */ + public ExternalApiClient() { + this(HttpClient.newBuilder() + .connectTimeout(Duration.ofSeconds(10)) + .build(), Duration.ofSeconds(30)); + } + + /** + * 사용자 지정 HttpClient/요청 타임아웃으로 생성 + */ + public ExternalApiClient(HttpClient httpClient, Duration requestTimeout) { + this.httpClient = httpClient; + this.requestTimeout = requestTimeout == null ? Duration.ofSeconds(30) : requestTimeout; + } + + public ExternalApiResponse get(String url, Map headers) { + return send("GET", url, headers, null); + } + + public ExternalApiResponse delete(String url, Map headers) { + return send("DELETE", url, headers, null); + } + + public ExternalApiResponse post(String url, Map headers, String body) { + return send("POST", url, headers, body); + } + + public ExternalApiResponse put(String url, Map headers, String body) { + return send("PUT", url, headers, body); + } + + public ExternalApiResponse patch(String url, Map headers, String body) { + return send("PATCH", url, headers, body); + } + + private ExternalApiResponse send(String method, String url, Map headers, String body) { + try { + HttpRequest.Builder builder = HttpRequest.newBuilder() + .uri(URI.create(url)) + .timeout(requestTimeout) + .method(method, buildBodyPublisher(method, body)); + + // 추가 헤더 설정 + if (headers != null) { + headers.forEach((k, v) -> { + if (k != null && v != null) builder.header(k, v); + }); + } + + // body가 있고 Content-Type이 없다면 기본 application/json + if (body != null && (headers == null || !headers.keySet().stream() + .map(String::toLowerCase).anyMatch("content-type"::equals))) { + builder.header("Content-Type", "application/json; charset=utf-8"); + } + + HttpRequest request = builder.build(); + HttpResponse resp = httpClient.send(request, HttpResponse.BodyHandlers.ofString()); + return ExternalApiResponse.of(resp.statusCode(), resp.headers(), resp.body()); + } catch (IOException | InterruptedException e) { + // 인터럽트 복원 + if (e instanceof InterruptedException) Thread.currentThread().interrupt(); + throw new RuntimeException("External API 호출 중 오류가 발생했습니다: " + e.getMessage(), e); + } + } + + private static HttpRequest.BodyPublisher buildBodyPublisher(String method, String body) { + // GET/DELETE 등 body 없는 메서드는 noBody 사용 + if (body == null || body.isEmpty()) { + return switch (method) { + case "POST", "PUT", "PATCH" -> HttpRequest.BodyPublishers.ofString(""); + default -> HttpRequest.BodyPublishers.noBody(); + }; + } + return HttpRequest.BodyPublishers.ofString(body); + } +} diff --git a/src/main/java/com/kri/common/http/ExternalApiResponse.java b/src/main/java/com/kri/common/http/ExternalApiResponse.java new file mode 100644 index 0000000..0c7cdbc --- /dev/null +++ b/src/main/java/com/kri/common/http/ExternalApiResponse.java @@ -0,0 +1,36 @@ +package com.kri.common.http; + +import java.net.http.HttpHeaders; +import java.util.List; +import java.util.Map; + +/** + * 외부 API 호출 결과를 단순하게 담는 DTO. + */ +public class ExternalApiResponse { + private final int statusCode; + private final Map> headers; + private final String body; + + public ExternalApiResponse(int statusCode, Map> headers, String body) { + this.statusCode = statusCode; + this.headers = headers; + this.body = body; + } + + public int getStatusCode() { + return statusCode; + } + + public Map> getHeaders() { + return headers; + } + + public String getBody() { + return body; + } + + public static ExternalApiResponse of(int status, HttpHeaders headers, String body) { + return new ExternalApiResponse(status, headers.map(), body); + } +} diff --git a/src/main/java/com/kri/common/jpa/AbstractCodeEnumConverter.java b/src/main/java/com/kri/common/jpa/AbstractCodeEnumConverter.java new file mode 100644 index 0000000..7b18ecb --- /dev/null +++ b/src/main/java/com/kri/common/jpa/AbstractCodeEnumConverter.java @@ -0,0 +1,27 @@ +package com.kri.common.jpa; + +import com.kri.common.enums.CodeEnum; +import com.kri.common.enums.CodeEnumUtils; +import jakarta.persistence.AttributeConverter; + +public abstract class AbstractCodeEnumConverter< + E extends Enum & CodeEnum, + V + > implements AttributeConverter { + + private final Class enumClass; + + protected AbstractCodeEnumConverter(Class enumClass) { + this.enumClass = enumClass; + } + + @Override + public V convertToDatabaseColumn(E attribute) { + return attribute == null ? null : attribute.getCode(); + } + + @Override + public E convertToEntityAttribute(V dbData) { + return CodeEnumUtils.fromCode(enumClass, dbData); + } +} \ No newline at end of file