Files
common-library/README.md

22 KiB

KriCommon Starter

Spring Boot 기반 사내 서비스에서 공통으로 사용하는 기능들을 모아둔 라이브러리입니다.
example-service 같은 개별 서비스는 이 라이브러리를 통해 다음과 같은 기능을 일관된 방식으로 재사용할 수 있습니다.

  • 공통 Security 자동 구성 (JWT + API Key, com.kri.common.security)
  • JWT 기반 인증/인가 (com.kri.common.auth.jwt)
  • 외부 API Key 인증 (com.kri.common.auth.apikey)
  • 공통 WebMvc 설정 (CORS + Swagger IP 접근 제어, com.kri.common.web)
  • 공통 Web 예외 처리 & 로깅 (ErrorAdvice, BusinessException, MDC/Trace)
  • Redis 큐 헬퍼 (com.kri.common.redis.RedisQueueHelper)
  • 스케줄링 활성화 (com.kri.common.scheduling)
  • 기본 logback 설정 (logback-spring.xml)

이 문서는 KriCommon을 사용하는 서비스(example-service) 기준으로 작성되었습니다.
(WebSocket 관련 기능은 현재 포함하지 않았으며, 추후 필요 시 별도 확장 예정입니다.)


1. 의존성 추가

1.1. Gradle 예시 (권장)

example-service/build.gradle:

repositories {
    mavenCentral()

    // Gitea 사내 Maven 레지스트리
    def giteaUser  = findProperty("giteaUser")  ?: ""
    def giteaToken = findProperty("giteaToken") ?: ""

    maven {
        name = "gitea"
        url = uri("https://gitea.kric.com/api/packages/KRi/maven")
        credentials {
            username = giteaUser
            password = giteaToken
        }
    }
}

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"

    // Swagger / OpenAPI UI
    implementation "org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0"

    // (필요 시) Redis
    implementation "org.springframework.boot:spring-boot-starter-data-redis"

    // KriCommon
    implementation "com.kri.common:starter:1.0.11"
}

~/.gradle/gradle.properties (또는 프로젝트 gradle.properties)에 자격 증명:

giteaUser=gitadmin
giteaToken=토큰값_여기에

주의 KriCommon은 java-library + compileOnly 위주로 구성되어 있어서 웹/시큐리티/Swagger/Redis Starter는 개별 서비스에서 직접 의존성을 추가해야 합니다.


2. 자동 구성(AutoConfiguration) 개요

KriCommon은 다음 AutoConfiguration 들을 제공합니다. 모두 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports에서 자동 등록됩니다.

클래스 역할 요약
com.kri.common.auth.jwt.JwtAutoConfiguration JwtProperties, ApiKeyProperties 바인딩 + JwtService, ApiKeyAuthFilter 자동 Bean 생성
com.kri.common.security.KriSecurityAutoConfiguration SecurityFilterChain 기본 구성(JWT + API Key 필터) + @EnableMethodSecurity
com.kri.common.web.CommonWebAutoConfiguration 공통 예외 처리(ErrorAdvice), TraceFilter 등록
com.kri.common.web.KriWebMvcAutoConfiguration CORS 기본 설정 + Swagger IP 접근 제어 Interceptor 등록
com.kri.common.swagger.KriSwaggerAutoConfiguration OpenAPI/Swagger 기본 설정 + JWT/API-Key SecurityScheme 등록
com.kri.common.redis.CommonRedisAutoConfiguration StringRedisTemplate, RedisQueueHelper 자동 구성 (RedisConnectionFactory 존재 시)
com.kri.common.scheduling.CommonSchedulingAutoConfiguration @EnableScheduling 자동 활성화

각 AutoConfiguration은 프로퍼티로 on/off 가능하며, 필요 시 서비스 쪽에서 Bean을 직접 정의하여 오버라이드 할 수 있습니다.


3. application.yml 예시

example-service/src/main/resources/application.yml:

spring:
  application:
    name: example-service

  datasource:
    # (서비스에서 실제 DB 설정)

  # Redis 사용 시 (선택)
  data:
    redis:
      host: localhost
      port: 6379

server:
  port: 8080

logging:
  file:
    path: logs
  level:
    root: INFO
    com.kri: DEBUG

# ===========================
# KRI 공통 설정
# ===========================
kri:
  auth:
    jwt:
      secret: "서비스별_실제_시크릿키_32자_이상"
      issuer: "kri-it"
      access-token-validity-seconds: 86400     # 24시간
      refresh-token-validity-seconds: 604800   # 7일
    apikey:
      enabled: true              # 외부 API Key 인증 사용 여부
      header-name: "X-API-Key"   # API Key 헤더 이름

  security:
    enabled: true
    # 인증 없이 허용할 URL 패턴들 (기본값 + 필요시 추가/override)
    public-paths:
      - "/v3/api-docs/**"
      - "/swagger-ui.html"
      - "/swagger-ui/**"
      - "/actuator/health"

  swagger:
    enabled: true
    title: "Example Service API"
    description: "Example Service OpenAPI Docs"
    version: "v1"
    base-package: "com.kri.example.api"

  webmvc:
    enabled: true
    ip:
      # 기본 CIDR(로컬 + 사내 대역)은 라이브러리 내부에 정의되어 있음
      # 여기서는 *추가* CIDR만 설정 (기본값은 그대로 유지)
      additional-cidrs:
        - "10.10.0.0/16"
        - "192.168.0.0/16"

common:
  web:
    enabled: true         # ErrorAdvice + TraceFilter
  redis:
    enabled: false        # RedisQueueHelper (필요 시 true)
  scheduling:
    enabled: false        # @EnableScheduling (필요 시 true)

4. 주요 기능 상세

4.1. JWT 설정 및 DTO (com.kri.common.auth.jwt)

4.1.1. JwtProperties

@ConfigurationProperties(prefix = "kri.auth.jwt")
public class JwtProperties {
    private String secret;                    // HMAC 시크릿 키 (기본값 존재, 서비스에서 override 권장)
    private String issuer = "kri-it";
    private long accessTokenValiditySeconds = 24 * 3600;
    private long refreshTokenValiditySeconds = 7 * 24 * 3600;
}

프로퍼티 요약

프로퍼티 타입 기본값 설명
kri.auth.jwt.secret String (기본값 있음) HMAC 서명용 시크릿(최소 32자 이상, 서비스별로 꼭 변경 추천)
kri.auth.jwt.issuer String kri-it 토큰 발급자
kri.auth.jwt.access-token-validity-seconds long 86,400 (24h) Access Token 만료(초)
kri.auth.jwt.refresh-token-validity-seconds long 604,800 (7일) Refresh Token 만료(초)

4.1.2. JwtUserClaimsDto

package com.kri.common.auth.jwt;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Builder;
import lombok.Value;

@Value
@Builder
@Schema(description = "JWT에 담기는 공통 사용자 정보")
public class JwtUserClaimsDto {

    @Schema(description = "사용자 ID (사내 시스템 기준 PK)", example = "user123")
    String userId;

    @Schema(description = "사용자 팀/조직명", example = "IT팀")
    String userTeam;

    @Schema(description = "사용자 이름", example = "홍길동")
    String userName;

    @Schema(description = "권한 레벨 (int)", example = "1")
    Integer role;
}

@Schema가 붙어 있어서, Swagger UI 상에서도 필드 설명이 자연스럽게 노출됩니다.

4.1.3. JwtService

주요 메서드:

public class JwtService {

    // Access Token 생성 (DTO → JWT 문자열)
    public String generateAccessToken(JwtUserClaimsDto userClaims);

    // Refresh Token 생성
    public String generateRefreshToken(String userId);

    // 토큰 파싱 & 검증
    public Claims getClaims(String token) throws JwtException;
    public JwtUserClaimsDto toUserClaimsDto(String token) throws JwtException;

    // Spring Security Authentication 변환
    public Authentication toAuthentication(JwtUserClaimsDto dto);
    public Authentication toAuthentication(String token) throws JwtException;
}

로그인 예시

@Service
@RequiredArgsConstructor
public class AuthService {

    private final JwtService jwtService;

    public String login(String username, String password) {
        // 1) 서비스에서 사용자 검증 (DB 조회 등)
        // 2) 검증 성공 시 공통 DTO 구성
        JwtUserClaimsDto claims = JwtUserClaimsDto.builder()
                .userId(username)
                .userTeam("IT팀")
                .userName("홍길동")
                .role(1)                      // 권한 레벨
                .build();

        // 3) Access Token 발급
        return jwtService.generateAccessToken(claims);
    }
}

4.2. API Key 인증 (com.kri.common.auth.apikey)

4.2.1. ApiKeyProperties

@ConfigurationProperties(prefix = "kri.auth.apikey")
public class ApiKeyProperties {
    private boolean enabled = false;
    private String headerName = "X-API-Key";
}

프로퍼티 요약

프로퍼티 타입 기본값 설명
kri.auth.apikey.enabled boolean false API Key 인증 기능 사용 여부
kri.auth.apikey.header-name String X-API-Key API Key 를 읽을 HTTP 헤더 이름

4.2.2. ApiKeyUserClaimsProvider (서비스 구현 필요)

public interface ApiKeyUserClaimsProvider {

    /**
     * API Key 로 사용자 정보를 조회한다.
     *
     * @param apiKey 요청 헤더에서 받은 API Key
     * @return 유효한 키면 JwtUserClaimsDto, 아니면 Optional.empty()
     */
    Optional<JwtUserClaimsDto> findUserByApiKey(String apiKey);
}

서비스 구현 예시 (example-service)

@Component
@RequiredArgsConstructor
public class ExampleApiKeyUserClaimsProvider implements ApiKeyUserClaimsProvider {

    @Override
    public Optional<JwtUserClaimsDto> findUserByApiKey(String apiKey) {
        // 1) 사내 외부 파트너용 API Key 테이블 조회
        // 2) 유효하면 JwtUserClaimsDto 로 매핑
        if ("DEMO-KEY-1234".equals(apiKey)) {
            return Optional.of(
                    JwtUserClaimsDto.builder()
                            .userId("external-partner")
                            .userTeam("External")
                            .userName("외부 파트너")
                            .role(9)
                            .build()
            );
        }
        return Optional.empty();
    }
}

4.2.3. ApiKeyAuthFilter

X-API-Key(또는 설정된 헤더)로부터 API Key를 읽고, ApiKeyUserClaimsProvider를 통해 사용자 정보를 조회한 뒤, JwtService를 사용해 Authentication을 세팅하는 필터입니다.

이 필터는 JwtAutoConfiguration / KriSecurityAutoConfiguration를 통해 자동 Bean 등록되고, SecurityFilterChain에서 JWT 필터보다 먼저 동작하도록 설정됩니다.


4.3. Security 기본 구성 (com.kri.common.security)

4.3.1. KriSecurityProperties

@ConfigurationProperties(prefix = "kri.security")
public class KriSecurityProperties {

    private boolean enabled = true;

    // 인증 없이 허용할 URL 패턴들
    private List<String> publicPaths = List.of(
            "/v3/api-docs/**",
            "/swagger-ui.html",
            "/swagger-ui/**"
    );
}

프로퍼티 요약

프로퍼티 타입 기본값 (일부) 설명
kri.security.enabled boolean true 공통 Security 자동 구성 사용 여부
kri.security.public-paths List Swagger 관련 패턴 포함 permitAll() 로 열어둘 URL 목록

서비스에서 Swagger 외에 /actuator/health 같은 것들도 열고 싶다면:

kri:
  security:
    public-paths:
      - "/v3/api-docs/**"
      - "/swagger-ui.html"
      - "/swagger-ui/**"
      - "/actuator/health"
      - "/auth/login"

4.3.2. KriSecurityAutoConfiguration

특징:

  • @AutoConfiguration(before = SecurityAutoConfiguration.class)

  • @EnableMethodSecurity(jsr250Enabled = true, prePostEnabled = true)

  • SecurityFilterChain 기본 구성:

    • httpBasic().disable()
    • formLogin().disable()
    • csrf().disable()
    • cors(Customizer.withDefaults())
    • SessionCreationPolicy.STATELESS
    • public-paths 는 permitAll(), 나머지는 authenticated()
    • ApiKeyAuthFilter → JwtAuthenticationFilter 순으로 필터 체인에 추가

메소드 레벨 권한 예시

@RestController
@RequestMapping("/api/example")
public class ExampleController {

    // 누구나 접근 가능하게 열고 싶다면:
    @jakarta.annotation.security.PermitAll
    @GetMapping("/public")
    public String publicApi() { ... }

    // 특정 권한 레벨 사용 (예: ROLE_1)
    @org.springframework.security.access.prepost.PreAuthorize("hasRole('1')")
    @GetMapping("/admin-only")
    public String adminOnly() { ... }
}

@PermitAll / @PreAuthorize 사용이 가능하며, URL 패턴 기반 예외 처리는 kri.security.public-paths 로 관리합니다.


4.4. Swagger / OpenAPI (com.kri.common.swagger)

4.4.1. KriSwaggerProperties

@ConfigurationProperties(prefix = "kri.swagger")
public class KriSwaggerProperties {
    private boolean enabled = true;
    private String title = "KRI API";
    private String description = "KRI Common API Docs";
    private String version = "v1";
    private String basePackage;  // 문서화할 base package (null 이면 전체)
}

4.4.2. KriSwaggerAutoConfiguration

  • OpenAPI Bean을 생성하며, Info(title, description, version) 설정

  • GroupedOpenApi Bean 생성

    • group = "kri-api"
    • basePackage 가 설정되어 있으면 해당 패키지만 스캔
  • Swagger Security 설정:

    • HTTP Bearer JWT (BearerAuth)
    • API Key 스키마 (ApiKeyAuth) — kri.auth.apikey.enabled=true 일 때 등록
    • 전역 SecurityRequirement 추가 → Swagger UI "Authorize" 버튼에 노출

서비스에서 필요한 것은:

dependencies {
    implementation "org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0"
    implementation "com.kri.common:starter:1.0.11"
}

그리고 application.yml에:

kri:
  swagger:
    enabled: true
    title: "Example Service API"
    description: "example-service OpenAPI Docs"
    version: "v1"
    base-package: "com.kri.example.api"

이렇게 하면 Swagger UI에서 JWT / API Key 입력 후 전체 API에 공통으로 헤더가 붙는 형태로 동작합니다.


4.5. WebMvc + IP 접근 제어 (com.kri.common.web)

4.5.1. KriWebMvcAutoConfiguration

@AutoConfiguration
@EnableConfigurationProperties(KriIpAccessProperties.class)
@ConditionalOnProperty(prefix = "kri.webmvc", name = "enabled", havingValue = "true", matchIfMissing = true)
@RequiredArgsConstructor
public class KriWebMvcAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public IpAccessControlService ipAccessControlService(KriIpAccessProperties props) {
        return new IpAccessControlService(props);
    }

    @Bean
    @ConditionalOnMissingBean
    public IpAccessControlInterceptor ipAccessControlInterceptor(IpAccessControlService svc) {
        return new IpAccessControlInterceptor(svc);
    }

    @Bean
    public WebMvcConfigurer kriWebMvcConfigurer(ObjectProvider<IpAccessControlInterceptor> ipAccessControlInterceptorProvider) {
        return new WebMvcConfigurer() {
            @Override
            public void addCorsMappings(CorsRegistry registry) {
                registry.addMapping("/**")
                        .allowedOriginPatterns("*")
                        .allowedMethods("GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS")
                        .allowedHeaders("*")
                        .allowCredentials(true);
            }

            @Override
            public void addInterceptors(InterceptorRegistry registry) {
                ipAccessControlInterceptorProvider.ifAvailable(interceptor ->
                        registry.addInterceptor(interceptor)
                                .order(1)
                                .addPathPatterns("/swagger-ui/**", "/v3/api-docs/**")
                );
            }
        };
    }
}

4.5.2. KriIpAccessProperties & IP 설정

@ConfigurationProperties(prefix = "kri.webmvc.ip")
public class KriIpAccessProperties {

    private final List<String> defaultCidrs = List.of(
            "127.0.0.1/32",
            "::1/128",
            "1.235.195.0/24",
            "211.254.145.128/25",
            "175.45.203.213/32"
    );

    private List<String> additionalCidrs = new ArrayList<>();

    public List<String> getEffectiveCidrs() {
        return Stream.concat(defaultCidrs.stream(), additionalCidrs.stream())
                .distinct()
                .collect(Collectors.toList());
    }
}

프로퍼티 요약

프로퍼티 타입 설명
kri.webmvc.enabled boolean CORS 및 Swagger IP 제어 자동 구성 on/off
kri.webmvc.ip.additional-cidrs List 기본 CIDR 목록에 추가할 CIDR 리스트

예시:

kri:
  webmvc:
    enabled: true
    ip:
      additional-cidrs:
        - "10.10.0.0/16"
        - "192.168.0.0/16"

기본 CIDR(127.0.0.1, ::1, 사내 대역 등)은 라이브러리 안에 고정되어 있고, 서비스에서는 추가 CIDR만 설정하면 됩니다.

4.5.3. CommonWebAutoConfiguration

@AutoConfiguration
@ConditionalOnProperty(name = "common.web.enabled", matchIfMissing = true)
public class CommonWebAutoConfiguration {

    @Bean
    public ErrorAdvice errorAdvice() { ... }

    @Bean
    public FilterRegistrationBean<TraceFilter> traceFilter() { ... }
}
  • ErrorAdvice: @RestControllerAdvice 형태의 글로벌 예외 처리
  • TraceFilter: HTTP 요청마다 X-Request-Id 및 MDC traceId 설정
  • 추가로 MDC 핸들러/Service AOP를 통해 로그에 handler/service 정보 포함

4.6. Redis 큐 (com.kri.common.redis)

4.6.1. CommonRedisAutoConfiguration

@AutoConfiguration
@ConditionalOnClass(RedisTemplate.class)
@ConditionalOnProperty(prefix = "common.redis", name = "enabled", havingValue = "true")
@ConditionalOnBean(RedisConnectionFactory.class)
public class CommonRedisAutoConfiguration {

    @Bean @ConditionalOnMissingBean
    public StringRedisTemplate stringRedisTemplate(RedisConnectionFactory cf) { ... }

    @Bean @ConditionalOnMissingBean
    public RedisQueueHelper redisQueueHelper(StringRedisTemplate rt) { ... }
}

프로퍼티

프로퍼티 타입 기본값 설명
common.redis.enabled boolean false RedisQueueHelper 사용 여부

4.6.2. RedisQueueHelper 사용 예시

@Service
@RequiredArgsConstructor
public class ExportQueueService {

    private final RedisQueueHelper redisQueueHelper;

    public void pushJob(String jobJson) {
        redisQueueHelper.push("export:jobs", jobJson);
    }

    public String popJob() {
        return redisQueueHelper.pop("export:jobs");
    }
}

4.7. 스케줄링 (com.kri.common.scheduling)

@AutoConfiguration
@EnableScheduling
@ConditionalOnProperty(prefix = "common.scheduling", name = "enabled", havingValue = "true")
public class CommonSchedulingAutoConfiguration { }

프로퍼티

프로퍼티 타입 기본값 설명
common.scheduling.enabled boolean false @EnableScheduling 활성화 여부

서비스 쪽에서는 단순히:

common:
  scheduling:
    enabled: true

만 지정하면, @Scheduled 애노테이션을 사용할 수 있습니다.


4.8. 로그 설정 (logback-spring.xml)

  • app.name (없으면 기본값 app)
  • logging.file.path (없으면 logs)

을 활용해서 로그 디렉토리와 패턴을 설정합니다.

traceId, handler, service 등 MDC 정보가 포함된 공통 패턴을 사용하도록 되어 있으며, 서비스에서 별도의 logback-spring.xml을 두면 그 설정이 우선합니다.


5. example-service 적용 요약

  1. 의존성 추가

    • Spring Boot Web / Security / Validation / (필요시) Redis / Swagger
    • implementation "com.kri.common:starter:1.0.11"
  2. application.yml 구성

    • kri.auth.jwt.* : 시크릿/만료시간 설정
    • kri.auth.apikey.* : API Key 사용 여부 및 헤더 이름
    • kri.security.public-paths : 로그인/헬스체크/Swagger 등 열어둘 URL 설정
    • kri.swagger.* : title/description/base-package 설정
    • kri.webmvc.ip.additional-cidrs : Swagger 접근 허용 IP 대역 추가
    • common.redis.enabled, common.scheduling.enabled 등 필요 시 on
  3. 로그인 엔드포인트 구현

    • 사용자 검증 후 JwtUserClaimsDto를 만들어 JwtService.generateAccessToken() 호출
    • Controller에서 JWT를 응답으로 내려줌
  4. 외부 API Key 사용 시

    • ApiKeyUserClaimsProvider 구현체를 Bean으로 등록
    • kri.auth.apikey.enabled=true 설정
  5. 권한 제어

    • URL 레벨: kri.security.public-paths (기본 + 추가)
    • 메소드 레벨: @PermitAll, @PreAuthorize("hasRole('1')") 등 사용