KriCommon 설정/기능 정리

개요

현재 패키지 구조는 아래 4축으로 정리되어 있습니다.

  • com.kri.common.autoconfigure: Spring Boot 자동 구성 진입점과 Properties
  • com.kri.common.feature: 서비스에서 직접 import/주입/구현하는 공개 기능
  • com.kri.common.runtime: 자동 구성에 의해 조립되어 동작하는 내부 실행 구성요소
  • com.kri.common.endpoint: yml 설정으로 자동 노출되는 공통 엔드포인트

설정 키는 kri.*만 사용합니다.


직접 import해서 사용하는 기능

인증/보안

com.kri.common.feature.auth.jwt.JwtService

import com.kri.common.feature.auth.jwt.JwtService;
import com.kri.common.feature.auth.dto.JwtUserClaimsDto;
  • 사용법: 빈 주입 후 generateAccessToken, generateRefreshToken, toAuthentication 호출
  • 설명: JWT 발급, 파싱, Authentication 변환을 처리합니다.

com.kri.common.feature.auth.dto.JwtUserClaimsDto

import com.kri.common.feature.auth.dto.JwtUserClaimsDto;
  • 사용법: builder로 사용자 정보를 생성해 JwtService에 전달
  • 설명: JWT 클레임 공통 DTO입니다.

com.kri.common.feature.auth.apikey.ApiKeyUserClaimsProvider

import com.kri.common.feature.auth.apikey.ApiKeyUserClaimsProvider;
  • 사용법: 서비스에서 구현체를 만들어 Bean 등록
  • 설명: API Key를 사용자 클레임으로 매핑하는 공개 확장 포인트입니다.

com.kri.common.feature.web.RequestUserContext

import com.kri.common.feature.web.RequestUserContext;
  • 사용법: 컨트롤러 파라미터로 선언
  • 설명: 현재 인증 사용자와 클라이언트 IP를 전달받는 요청 컨텍스트입니다.

웹/페이징

com.kri.common.feature.web.page.PageRequestDto

import com.kri.common.feature.web.page.PageRequestDto;
  • 사용법: 조회 API 요청 DTO로 사용
  • 설명: pageIndex, pageSize, sortBy, sortDir를 공통 형식으로 받습니다.

com.kri.common.feature.web.page.Pageables

import com.kri.common.feature.web.page.Pageables;
  • 사용법: Pageables.of(req, EntityOrDto.class)
  • 설명: 정렬 가능 필드를 검증해 Pageable 객체를 만듭니다.

com.kri.common.feature.web.page.PageResponseDto

import com.kri.common.feature.web.page.PageResponseDto;
  • 사용법: PageResponseDto.from(page)
  • 설명: Spring Data Page를 API 응답용 DTO로 감쌉니다.

Redis

com.kri.common.feature.redis.RedisQueueHelper

import com.kri.common.feature.redis.RedisQueueHelper;
  • 사용법: 자동 구성 빈 주입 후 enqueue, blockingDequeue 사용
  • 설명: Redis List 기반 큐 처리 헬퍼입니다.

HTTP/JSON/Excel

com.kri.common.feature.http.ExternalApiClient

import com.kri.common.feature.http.ExternalApiClient;
  • 사용법: new ExternalApiClient() 또는 커스텀 HttpClient로 생성
  • 설명: 문자열 body 기반의 경량 HTTP 클라이언트입니다.

com.kri.common.feature.http.ExternalApiResponse

import com.kri.common.feature.http.ExternalApiResponse;
  • 사용법: ExternalApiClient 응답 객체로 사용
  • 설명: statusCode, headers, body를 묶어 반환합니다.

com.kri.common.feature.json.JsonUtil

import com.kri.common.feature.json.JsonUtil;
  • 사용법: JSON 직렬화/역직렬화/맵 변환 수행
  • 설명: Jackson 보조 유틸입니다.

com.kri.common.feature.excel.ExcelMapper

import com.kri.common.feature.excel.ExcelMapper;
  • 사용법: DTO 리스트나 Map 리스트를 엑셀로 변환
  • 설명: 일반 처리와 대용량 스트리밍 읽기/쓰기를 지원합니다.

날짜/시간/JPA/Enum/유틸

  • com.kri.common.feature.datetime.*: 날짜/시간 처리 유틸과 Jackson 어노테이션
  • com.kri.common.feature.jpa.*: JPA 베이스 엔티티와 enum converter
  • com.kri.common.feature.enums.*: 코드값 기반 enum 인터페이스와 유틸
  • com.kri.common.feature.cache.*: 리스트/맵 캐시 베이스 클래스
  • com.kri.common.feature.file.FileUtil: 파일명/확장자 유틸
  • com.kri.common.feature.util.*: 문자열, 숫자, UUID 보조 유틸

yml로 설정하는 기능

전체 예시

kri:
  auth:
    jwt:
      # JWT 서명용 시크릿. 32바이트 이상 권장
      secret: "32byte-over-secret-value-required"
      # 토큰 발급자 식별자
      issuer: "kri-it"
      # Access Token 만료 시간(초)
      access-token-validity-seconds: 86400
      # Refresh Token 만료 시간(초)
      refresh-token-validity-seconds: 604800
    apikey:
      # API Key 인증 기능 활성화
      enabled: true
      # API Key를 읽을 HTTP 헤더명
      header-name: "X-API-Key"
      # preload 대상 서비스 코드
      service-code: "example-service"
      # 서버 시작 시 API Key 캐시 적재 여부
      preload-on-startup: true
      # 내부 관리용 API 노출 여부
      admin-api-enabled: false
      admin-allow-ips:
        # 내부 관리 API 접근 허용 CIDR
        - "127.0.0.1/32"
      db:
        # API Key 전용 DB 접속 URL
        url: "jdbc:mysql://localhost:3306/kri_common"
        # API Key 전용 DB 계정
        username: "app"
        # API Key 전용 DB 비밀번호
        password: "secret"
        # JDBC 드라이버 클래스
        driver-class-name: "com.mysql.cj.jdbc.Driver"
      jpa:
        # Hibernate SQL 로그 출력 여부
        show-sql: false
        # Hibernate SQL 포맷팅 여부
        format-sql: false
  security:
    # 기본 Security 자동구성 활성화
    enabled: true
    public-paths:
      # 인증 없이 허용할 공개 경로
      - "/v3/api-docs/**"
      - "/swagger-ui/**"
  swagger:
    # Swagger/OpenAPI 자동구성 활성화
    enabled: true
    # 문서 타이틀
    title: "Example API"
    # 문서 설명
    description: "Example API Docs"
    # 문서 버전 표시값
    version: "v1"
    # Swagger 스캔 대상 base package
    base-package: "com.example.api"
    allowed-ips:
      # Swagger UI / API Docs 접근 허용 IP
      - "127.0.0.1"
  web:
    # 공통 웹 예외/trace 필터 활성화
    enabled: true
    mdc:
      # handler/service MDC 기록 활성화
      enabled: true
  redis:
    # Redis 보조 기능 활성화
    enabled: true
  scheduling:
    # @Scheduled 사용을 위한 스케줄링 활성화
    enabled: true
  error:
    expose:
      # 에러 응답에 handler 정보 포함 여부
      handler: false
      # 에러 응답에 service 정보 포함 여부
      service: false

항목별 정리

kri.auth.jwt

  • 대상: JWT 생성/검증
  • 사용 대상 클래스: JwtAutoConfiguration, JwtProperties, JwtService
  • 설명: issuer, access/refresh 만료 시간, JWT secret을 제어합니다.

kri.auth.apikey

  • 대상: API Key 인증, preload 캐시, 내부 관리용 endpoint
  • 사용 대상 클래스: ApiKeyJpaAutoConfiguration, ApiKeyPreloadAutoConfiguration, ApiKeyAdminAutoConfiguration
  • 설명: API Key 헤더, preload, admin API 노출, 전용 DB 연결을 제어합니다.

kri.security

  • 대상: 기본 Spring Security 필터체인
  • 사용 대상 클래스: KriSecurityAutoConfiguration, KriSecurityProperties
  • 설명: 공개 경로와 JWT/API Key 필터 적용 여부를 제어합니다.

kri.swagger

  • 대상: OpenAPI 문서, Swagger 접근 제어
  • 사용 대상 클래스: KriSwaggerAutoConfiguration, KriSwaggerProperties
  • 설명: 문서 메타정보와 스캔 패키지, 허용 IP를 제어합니다.

kri.web

  • 대상: 공통 예외 응답, traceId, MDC
  • 사용 대상 클래스: CommonWebAutoConfiguration
  • 설명: ErrorAdvice, TraceFilter, MDC 관련 구성을 켜고 끕니다.

kri.redis

  • 대상: Redis 큐 헬퍼
  • 사용 대상 클래스: CommonRedisAutoConfiguration
  • 설명: Redis 연결 빈이 있을 때 RedisQueueHelper를 자동 등록합니다.

kri.scheduling

  • 대상: 스케줄링 활성화
  • 사용 대상 클래스: CommonSchedulingAutoConfiguration
  • 설명: 서비스에서 @Scheduled를 사용할 수 있게 합니다.

kri.error.expose.*

  • 대상: 에러 응답의 MDC 부가 정보 노출
  • 사용 대상 클래스: ErrorAdvice
  • 설명: handler, service 정보를 응답에 포함할지 제어합니다.

자동 구성에 의해 동작하는 내부 런타임 구성요소

아래 패키지는 서비스에서 직접 import해서 쓰기보다는, 자동 구성에 의해 조립되어 동작하는 내부 구현입니다.

  • com.kri.common.runtime.auth.apikey
    • ApiKeyAuthFilter
    • PreloadedApiKeyUserClaimsProvider
    • persistence.entity
    • persistence.repository
  • com.kri.common.runtime.security
    • JwtAuthenticationFilter
  • com.kri.common.runtime.swagger
    • SwaggerIpFilter
  • com.kri.common.runtime.web
    • CodeEnumConverter
    • ErrorAdvice
    • IpUtil
    • RequestUserContextArgumentResolver
    • TraceFilter
    • ServiceMdcAspect

자동 노출 endpoint

com.kri.common.endpoint.auth.apikey.ApiKeyAdminController

  • 노출 조건: kri.auth.apikey.admin-api-enabled=true 그리고 PreloadedApiKeyUserClaimsProvider 빈 존재
  • 경로: /internal/apikey/reload, /internal/apikey/cache
  • 설명: preload 캐시 재적재와 현재 캐시 조회를 위한 내부 관리용 endpoint입니다.

Migration Guide

  • kri.webmvc.enabled 설정은 제거하고 kri.web.enabled만 사용합니다.
  • kri.webmvc.ip.* 설정은 제거하고 Swagger IP 제어는 kri.swagger.allowed-ips만 사용합니다.
  • 프록시 환경에서는 API Key admin API와 Swagger가 모두 IpUtil 기준으로 클라이언트 IP를 해석합니다. kri.auth.apikey.admin-allow-ips 값을 다시 확인하세요.
  • 내부 클래스를 직접 import하고 있었다면 아래처럼 경로를 변경해야 합니다.
    • com.kri.common.runtime.webmvc.CodeEnumConverter -> com.kri.common.runtime.web.CodeEnumConverter
    • com.kri.common.runtime.webmvc.IpUtil -> com.kri.common.runtime.web.IpUtil
    • com.kri.common.runtime.webmvc.RequestUserContextArgumentResolver -> com.kri.common.runtime.web.RequestUserContextArgumentResolver
  • 아래 클래스와 설정 객체는 제거되었습니다.
    • com.kri.common.autoconfigure.webmvc.KriWebMvcAutoConfiguration
    • com.kri.common.autoconfigure.webmvc.KriIpAccessProperties
    • com.kri.common.runtime.web.IpAccessControlInterceptor
    • com.kri.common.runtime.web.IpAccessControlService
    • com.kri.common.runtime.web.MdcHandlerConfig
  • Swagger 문서의 인증 표시는 BearerAuth와 ApiKeyAuth를 동시에 요구하지 않고, 둘 중 하나로 인증 가능한 형태로 바뀌었습니다.

AutoConfiguration 목록

src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

  • com.kri.common.autoconfigure.auth.jwt.JwtAutoConfiguration
  • com.kri.common.autoconfigure.auth.apikey.ApiKeyJpaAutoConfiguration
  • com.kri.common.autoconfigure.auth.apikey.ApiKeyPreloadAutoConfiguration
  • com.kri.common.autoconfigure.auth.apikey.ApiKeyAdminAutoConfiguration
  • com.kri.common.autoconfigure.security.KriSecurityAutoConfiguration
  • com.kri.common.autoconfigure.web.CommonWebAutoConfiguration
  • com.kri.common.autoconfigure.swagger.KriSwaggerAutoConfiguration
  • com.kri.common.autoconfigure.redis.CommonRedisAutoConfiguration
  • com.kri.common.autoconfigure.scheduling.CommonSchedulingAutoConfiguration

검토 메모

  • ApiKeyProperties의 DB 기본값, JwtProperties의 secret 기본값은 의도적으로 유지 중입니다.
  • 문서 기준 패키지명은 현재 리팩터링 결과인 autoconfigure / feature / runtime / endpoint를 따릅니다.
  • 컴파일 검증은 .\gradlew.bat compileJava 기준으로 통과했습니다.
Description
No description provided
Readme 1 MiB
Languages
Java 100%