# KriCommon Starter Spring Boot 기반 사내 서비스에서 공통으로 사용하는 기능들을 모아둔 라이브러리입니다. `example-service` 같은 개별 서비스는 이 라이브러리를 통해 다음과 같은 기능을 **일관된 방식으로 재사용**할 수 있습니다. - JWT 기반 인증/인가 (`com.kri.common.auth.jwt`) - 외부 API Key 인증 (`com.kri.common.auth.apikey`) - 공통 Web 예외 처리 & 로깅 (`com.kri.common.web`) - Redis 큐 헬퍼 (`com.kri.common.redis`) - 스케줄링 활성화 (`com.kri.common.scheduling`) - 기본 logback 설정 이 문서는 **KriCommon을 사용하는 서비스(example-service)** 기준으로 작성되었습니다. --- ## 1. 환경 요구사항 - **Java 17** - **Spring Boot 3.5.x** (KriCommon 내부 BOM: `org.springframework.boot:spring-boot-dependencies:3.5.7`) - **Servlet 기반 Spring MVC** (WebFlux 미지원) --- ## 2. 의존성 추가 ### 2.1. Gitea Maven Registry 설정 `example-service/build.gradle`: ```groovy repositories { mavenCentral() maven { name = "gitea" url = uri("http://10.10.10.11:3000/api/packages/KRi/maven") allowInsecureProtocol = true credentials { username = findProperty("giteaUser") ?: "" password = findProperty("giteaToken") ?: "" } } } ``` `gradle.properties` (루트 또는 사용자 홈): ```properties giteaUser=gitadmin giteaToken=YOUR_GITEA_TOKEN # 실제 토큰으로 교체 ``` > **Tip** > - 토큰을 깃이나 공유 저장소에 올리지 않도록 주의하세요. > - 실제로는 환경 변수 또는 CI/CD 시크릿을 사용해 주입하는 것을 권장합니다. ### 2.2. Starter 라이브러리 의존성 ```groovy dependencies { // 필수 Spring Boot 의존성 (예시) implementation 'org.springframework.boot:spring-boot-starter-web' implementation 'org.springframework.boot:spring-boot-starter-security' implementation 'org.springframework.boot:spring-boot-starter-validation' implementation 'org.springframework.boot:spring-boot-starter-aop' implementation 'org.springframework.boot:spring-boot-starter-data-redis' // Swagger / OpenAPI (선택, 문서화용) implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0' // ✅ KriCommon Starter implementation 'com.kri.common:starter:1.0.1' } ``` --- ## 3. 구성 요소 개요 KriCommon 은 크게 5가지 축으로 나뉩니다. 1. **인증/인가** - JWT, API Key를 모두 공통 DTO(`JwtUserClaimsDto`) 기반으로 정규화 2. **Web 공통 기능** - 예외 처리, traceId/MDC, AOP 기반 service/handler 로깅 3. **Redis 큐 지원** - 간단한 Redis List 기반 큐 컨슈머/프로듀서 유틸 4. **스케줄링 활성화** - 서비스에서 직접 `@EnableScheduling` 선언 없이 property 로 on/off 5. **로깅/Logback 기본 설정** - traceId, service, handler, thread 정보가 통일된 패턴으로 출력 각 기능은 **프로퍼티 + AutoConfiguration + 유틸 Bean** 조합으로 제공되며, 서비스는 필요한 부분만 선택적으로 활성화하면 됩니다. --- ## 4. 설정 예시 (application.yml) `example-service/src/main/resources/application.yml` 기본 예시는 다음과 같습니다. ```yaml server: port: 8080 spring: application: name: example-service logging: file: path: ./logs kri: auth: jwt: secret: "CHANGE_ME_TO_A_SECURE_SECRET_32+CHARS" issuer: "kri-it" # 내부 시스템 간 통신에 사용할 고정 토큰 (선택) internal-fixed-token: "VERY_SECURE_INTERNAL_TOKEN_VALUE" # 고정 토큰 사용 시 SecurityContext 에 올릴 기본 계정정보 internal-user-id: "SYSTEM_EXAMPLE" internal-user-team: "IT" internal-user-name: "Example Internal System" internal-user-role: 999 apikey: enabled: true # API Key 인증 사용 여부 header-name: "X-API-Key" # API Key 헤더 이름 common: web: enabled: true # 공통 Web 구성 사용 여부 (기본 true) redis: enabled: false # RedisQueueHelper 사용 시 true scheduling: enabled: false # @Scheduled 사용 시 true ``` ### 4.1. `kri.auth.jwt` 속성 요약 | 프로퍼티 | 타입 | 기본값 | 설명 | | ---------------------------------------- | -------- | ---------------------------------- | ---- | | `kri.auth.jwt.secret` | String | (기본값 있음, 서비스에서 override 권장) | HMAC 서명에 사용할 시크릿 키 (최소 32자 이상) | | `kri.auth.jwt.issuer` | String | `"kri-it"` | 토큰 발급자(issuer) | | `kri.auth.jwt.access-token-validity-seconds` | long | `24 * 3600` | Access Token 유효 시간(초) | | `kri.auth.jwt.refresh-token-validity-seconds` | long | `7 * 24 * 3600` | Refresh Token 유효 시간(초) | ### 4.2. `kri.auth.apikey` 속성 요약 | 프로퍼티 | 타입 | 기본값 | 설명 | | ------------------------------ | ------- | ---------- | ---- | | `kri.auth.apikey.enabled` | boolean | `false` | API Key 인증 기능 활성화 여부 | | `kri.auth.apikey.header-name` | String | `X-API-Key`| API Key 를 읽을 HTTP 헤더 이름 | ### 4.3. `common.*` 속성 요약 | 프로퍼티 | 타입 | 기본값 | 설명 | | -------------------------- | ------- | ------ | ---- | | `common.web.enabled` | boolean | `true` | Web 예외/로깅/필터 자동 구성 여부 | | `common.redis.enabled` | boolean | `false`| RedisQueueHelper 자동 구성 여부 | | `common.scheduling.enabled`| boolean | `false`| `@EnableScheduling` 자동 적용 여부 | --- ## 5. JWT 기능 상세 (`com.kri.common.auth.jwt`) ### 5.1. JwtUserClaimsDto JWT 에 들어가는 **표준 Payload** 를 정의하는 DTO입니다. ```java @Schema( name = "JwtUserClaimsDto", description = "JWT에 포함되는 사용자 정보 (T_USER 기준)" ) @Value @Builder public class JwtUserClaimsDto { @Schema(description = "사용자 ID (T_USER.USER_ID)") String userId; @Schema(description = "팀 코드 또는 팀명 (T_USER.USER_TEAM)") String userTeam; @Schema(description = "사용자 이름 (T_USER.USER_NM)") String userName; @Schema(description = "권한 코드 (T_USER.ROLL, INTEGER)") Integer role; } ``` > Swagger/OpenAPI 를 사용하는 서비스에서는 > 이 DTO를 반환 타입이나 요청 타입에 사용하면 자동으로 문서화됩니다. ### 5.2. JwtService 주요 메서드 JwtService 는 다음과 같은 역할을 합니다. 1. **Access Token 발급** 2. **Refresh Token 발급** 3. **토큰 파싱 및 검증** 4. **토큰 → JwtUserClaimsDto/Authentication 변환** 핵심 메서드 요약: ```java public class JwtService { // Access Token 생성 public String generateAccessToken(JwtUserClaimsDto userClaims); // Refresh Token 생성 (subject = userId) public String generateRefreshToken(String userId); // 토큰 파싱 + 서명/만료 검증 public Jws parseToken(String token) throws JwtException; // Claims 추출 public Claims getClaims(String token) throws JwtException; // Claims -> DTO public JwtUserClaimsDto toUserClaimsDto(Claims claims); // 토큰 -> DTO public JwtUserClaimsDto toUserClaimsDto(String token) throws JwtException; // DTO -> Authentication (Spring Security) public Authentication toAuthentication(JwtUserClaimsDto dto); // 토큰 -> Authentication public Authentication toAuthentication(String token) throws JwtException; } ``` ### 5.3. 로그인 흐름 예시 ```java @Service @RequiredArgsConstructor public class AuthService { private final JwtService jwtService; public String login(String userId, String password) { // 1) userId/password 검증 및 T_USER 조회 // 예시용 더미 값 String userTeam = "TEAM_A"; String userName = "홍길동"; Integer role = 1; JwtUserClaimsDto claims = JwtUserClaimsDto.builder() .userId(userId) .userTeam(userTeam) .userName(userName) .role(role) .build(); // 2) Access Token 발급 return jwtService.generateAccessToken(claims); } } ``` ### 5.4. JWT 인증 필터 예시 (서비스 측 구현) KriCommon 은 **JwtAuthenticationFilter 구현은 제공하지 않습니다.** 서비스마다 요구사항이 다르기 때문에, 아래와 같이 `JwtService` 를 사용하는 커스텀 필터를 작성해 연결하는 방식을 권장합니다. ```java @RequiredArgsConstructor public class JwtAuthenticationFilter extends OncePerRequestFilter { private final JwtService jwtService; @Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException { if (SecurityContextHolder.getContext().getAuthentication() == null) { String header = request.getHeader("Authorization"); if (header != null && header.startsWith("Bearer ")) { String token = header.substring("Bearer ".length()); Authentication auth; if (jwtService.isInternalFixedToken(token)) { auth = jwtService.createInternalAuthentication(); } else { auth = jwtService.toAuthentication(token); } SecurityContextHolder.getContext().setAuthentication(auth); } } filterChain.doFilter(request, response); } } ``` SecurityConfig 에 등록: ```java http.addFilterBefore(jwtAuthenticationFilter(), UsernamePasswordAuthenticationFilter.class); ``` --- ## 6. API Key 인증 (`com.kri.common.auth.apikey`) ### 6.1. 설계 개요 - 외부 시스템에서 발급한 API Key가 `X-API-Key` 헤더로 들어오는 경우를 처리하기 위한 기능입니다. - KriCommon 은: - 헤더에서 Key를 읽고 - `ApiKeyUserClaimsProvider` 에 Key를 전달하여 - 유효한 경우 `JwtUserClaimsDto` → `Authentication` 을 생성해 SecurityContext에 세팅합니다. - 각 서비스는 **오직 "이 Key가 누구 것인지"만 구현**하면 됩니다. ### 6.2. ApiKeyUserClaimsProvider (서비스에서 구현) ```java public interface ApiKeyUserClaimsProvider { /** * API Key 로 사용자 정보를 조회한다. * * @param apiKey 요청 헤더에서 받은 API Key * @return 유효한 키면 JwtUserClaimsDto, 아니면 Optional.empty() */ Optional findUserByApiKey(String apiKey); } ``` 구현 예시: ```java @Service @RequiredArgsConstructor public class ApiKeyUserClaimsProviderImpl implements ApiKeyUserClaimsProvider { // private final ApiKeyMapper apiKeyMapper; @Override public Optional findUserByApiKey(String apiKey) { // TODO: DB 조회(MyBatis)로 교체 if ("EXTERNAL_KEY_1".equals(apiKey)) { return Optional.of( JwtUserClaimsDto.builder() .userId("partnerA") .userTeam("EXT") .userName("외부 파트너 A") .role(10) .build() ); } return Optional.empty(); } } ``` ### 6.3. ApiKeyAuthFilter (공통 필터) KriCommon 에서 제공하는 필터는 다음과 같이 동작합니다. 1. `kri.auth.apikey.enabled=false` 이면 아무 작업도 하지 않음 2. 이미 SecurityContext에 Authentication 이 있으면 패스 3. 설정된 헤더(`kri.auth.apikey.header-name`)에서 Key를 읽음 4. `ApiKeyUserClaimsProvider` 로 조회 5. DTO가 반환되면 `JwtService.toAuthentication(dto)`로 Authentication 생성 서비스 측에서는 단지 **필터를 SecurityConfig 에 추가**하면 됩니다. ```java @Configuration @EnableWebSecurity @RequiredArgsConstructor public class SecurityConfig { private final ApiKeyAuthFilter apiKeyAuthFilter; @Bean public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception { http .csrf(csrf -> csrf.disable()) .sessionManagement(sm -> sm.sessionCreationPolicy(SessionCreationPolicy.STATELESS)) .authorizeHttpRequests(auth -> auth .requestMatchers("/swagger-ui/**", "/v3/api-docs/**", "/actuator/health").permitAll() .anyRequest().authenticated() ); // JWT 필터가 있다면 순서 조정 가능 http.addFilterBefore(apiKeyAuthFilter, UsernamePasswordAuthenticationFilter.class); return http.build(); } } ``` --- ## 7. Web 공통 기능 (`com.kri.common.web`) ### 7.1. ErrorAdvice & BusinessException - `BusinessException` 은 비즈니스 로직에서 발생시키는 커스텀 예외입니다. - `ErrorAdvice` 가 이를 캐치하여 **`ProblemDetail` 기반 JSON 응답**으로 변환합니다. 사용 예: ```java if (!true) { throw BusinessException.of( HttpStatus.BAD_REQUEST, "INVALID_PARAM", "요청 파라미터가 유효하지 않습니다." ).with("field", "name"); } ``` 응답 예 (대략적인 형태): ```json { "status": 400, "title": "INVALID_PARAM", "detail": "요청 파라미터가 유효하지 않습니다.", "field": "name", "traceId": "c5b2b6ab...", "timestamp": "2025-01-01T12:34:56.789+09:00" } ``` > 실제 필드 구조는 `ErrorAdvice` 구현을 참고하십시오. ### 7.2. TraceFilter / MDC - `TraceFilter` - 요청마다 `traceId` 를 생성 또는 `X-Request-Id` 헤더에서 재사용 - MDC 에 `traceId` 세팅 - `MdcHandlerConfig` - HandlerInterceptor 를 사용해 `handler` 정보를 MDC에 기록 (`Controller#method`) - `ServiceMdcAspect` - `@Service` 메서드 호출 시 `service` MDC 필드에 기록 (`Service#method`) 이 정보는 기본 logback 패턴(또는 서비스에서 override한 패턴)에 포함되어 로그 상에서 **요청 단위/메서드 단위 추적**을 쉽게 만들 수 있습니다. --- ## 8. Redis 큐 (`com.kri.common.redis`) ### 8.1. 활성화 조건 - `common.redis.enabled=true` - `RedisConnectionFactory` Bean 이 존재 (보통 `spring-boot-starter-data-redis` + `spring.data.redis.*` 설정) > 두 조건이 충족되면 `CommonRedisAutoConfiguration` 이 > `StringRedisTemplate` 및 `RedisQueueHelper` 를 자동으로 등록합니다. ### 8.2. RedisQueueHelper 사용 예시 ```java @Service @RequiredArgsConstructor public class JobQueueService { private final RedisQueueHelper redisQueueHelper; public void enqueueJob(String jobId) { redisQueueHelper.enqueue("job-queue", jobId); } public String dequeueJob() { // 최대 5초 동안 대기 return redisQueueHelper.blockingDequeue("job-queue", Duration.ofSeconds(5)); } } ``` **권장 패턴** - Producer: 서비스/컨트롤러에서 업무 이벤트를 큐에 적재 - Consumer: @Scheduled 또는 별도 Thread에서 blockingDequeue 로 작업 수행 --- ## 9. 스케줄링 (`com.kri.common.scheduling`) ### 9.1. 활성화 방법 ```yaml common: scheduling: enabled: true ``` 이 설정만 켜면: - `CommonSchedulingAutoConfiguration` 이 `@EnableScheduling` 을 적용합니다. - 서비스 코드에서는 평소처럼 `@Scheduled` 만 선언하면 됩니다. 예: ```java @Component public class ExampleScheduler { @Scheduled(fixedDelay = 10_000) public void doSomething() { // 10초마다 실행 } } ``` > 장점: > - 서비스마다 `@EnableScheduling` 애노테이션 중복 선언을 피할 수 있음 > - 프로퍼티로 스케줄링 on/off 제어가 쉬워짐 --- ## 10. 로깅 / logback KriCommon 은 기본적인 `logback-spring.xml` 을 제공합니다. - 콘솔 로그 + 파일 로그(rolling) - MDC 값 포함: - `traceId` - `handler` (Controller 메서드) - `service` (Service 메서드) - thread, level, logger 등 서비스에서 **직접 `logback-spring.xml` 을 제공하면 해당 설정이 우선 적용**되므로, 필요하면 KriCommon의 설정을 복사 후 서비스에 맞게 수정해서 사용하는 것을 권장합니다. --- ## 11. Swagger / OpenAPI KriCommon 의 일부 DTO(`JwtUserClaimsDto` 등)에는 `io.swagger.v3.oas.annotations.media.Schema` 어노테이션이 포함되어 있습니다. `example-service` 에서 springdoc-openapi 를 사용한다면, 다음과 같이 사용할 수 있습니다. ```java @RestController public class MeController { @Operation(summary = "현재 로그인 사용자 정보 조회") @GetMapping("/api/me") public JwtUserClaimsDto me() { return JwtUserClaimsDto.builder() .userId("demo") .userTeam("TEAM") .userName("데모 사용자") .role(1) .build(); } } ``` Swagger UI 에서: - DTO 이름: `JwtUserClaimsDto` - 각 필드별 설명: `@Schema(description = "...")` 내용이 그대로 노출됩니다. --- ## 12. 신규 서비스 적용 체크리스트 `example-service` 같은 신규 서비스에서 KriCommon 을 사용할 때, 다음 순서대로 점검하면 됩니다. 1. **Gradle 설정** - Gitea Maven registry 추가 - `implementation 'com.kri.common:starter:1.0.1'` 추가 2. **application.yml** - `kri.auth.jwt.secret` 최소 32자 이상으로 설정 - 필요 시 `internal-fixed-token` 및 내부 계정 정보 설정 - API Key 인증이 필요하면 `kri.auth.apikey.enabled=true` 및 header-name 지정 - Web/Redis/Scheduling 사용 여부에 따라 `common.*` 설정 3. **SecurityConfig** - `ApiKeyAuthFilter` (공통) 필터 체인에 추가 - JWT 인증이 필요하면 `JwtService` 기반 커스텀 JwtAuthenticationFilter 구현 후 추가 4. **ApiKeyUserClaimsProvider 구현** - DB/설정 파일 등에서 API Key → JwtUserClaimsDto 매핑 로직 작성 5. **로그/예외 확인** - 의도한 형태로 ProblemDetail, traceId, service/handler 로그가 찍히는지 확인 6. **Swagger** - springdoc-openapi 설정 후, 공통 DTO가 API 스펙에 잘 노출되는지 확인 이 문서를 기반으로, 각 서비스 팀은 **인증, 로깅, 스케줄링, Redis 큐 구조를 공통 규약에 맞춰 재사용**할 수 있습니다.