Files
common-library/README.md

28 KiB

KriCommon 설정/기능 정리

KriCommon은 KRI 계열 Spring Boot 서비스에서 반복해서 쓰는 인증, 보안, 웹, Swagger, Redis, Excel, JSON, 날짜/시간, JPA 보조 기능을 모은 Java 17 라이브러리입니다.

라이브러리의 패키지는 역할에 따라 다음 4개 축으로 나뉩니다.

  • com.kri.common.autoconfigure: Spring Boot 자동 구성과 @ConfigurationProperties
  • com.kri.common.feature: 서비스 코드가 직접 import해서 쓰는 공개 기능
  • com.kri.common.runtime: 자동 구성으로 조립되는 필터, 컨버터, 어드바이스 등 내부 실행 요소
  • com.kri.common.endpoint: 설정에 따라 노출되는 공통 관리 API

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


빌드와 배포

  • Java: 17
  • Gradle plugins: java-library, maven-publish
  • Group: com.kri.common
  • Artifact: starter
  • Version: build.gradle의 commonVer
  • Spring Boot BOM: org.springframework.boot:spring-boot-dependencies:3.5.7
  • Publish target: Gitea Maven Packages
./gradlew compileJava
./gradlew publishReleasePublicationToGiteaRepository

배포 전에 checkGiteaPackageVersionNotExists 태스크가 같은 Maven package version이 이미 있는지 확인합니다. Gitea 인증은 Gradle property giteaUser, giteaToken 또는 환경 변수 GITEA_USER, GITEA_TOKEN을 사용합니다.


의존성 성격

이 라이브러리는 starter 형태지만 모든 런타임 의존성을 강제로 끌어오지 않습니다. 서비스가 실제로 쓰는 기능에 맞춰 Spring Boot starter를 함께 선언해야 합니다.

  • JWT: jjwt-api, jjwt-impl, jjwt-jackson
  • Security core: spring-security-core
  • Security web/config: compileOnly
  • Spring Web, Validation, AOP, Redis, JPA, Autoconfigure: compileOnly
  • Swagger/OpenAPI: compileOnly
  • JSON: Jackson Databind
  • Excel: Apache POI
  • Lombok: compileOnly/annotationProcessor

예를 들어 보안 필터 체인을 쓰는 서비스는 Spring Security Web/Config가 classpath에 있어야 하고, Swagger 자동 구성을 쓰는 서비스는 springdoc이 classpath에 있어야 합니다.


직접 import해서 쓰는 기능

인증/JWT

JwtService

import com.kri.common.feature.auth.jwt.JwtService;
import com.kri.common.feature.auth.dto.JwtUserClaimsDto;

JWT 발급, 파싱, claims 변환, Spring Security Authentication 변환을 담당합니다.

주요 메서드:

  • generateAccessToken(JwtUserClaimsDto userClaims)
  • generateRefreshToken(String userId)
  • parseToken(String token)
  • getClaims(String token)
  • toUserClaimsDto(Claims claims)
  • toUserClaimsDto(String token)
  • toAuthentication(JwtUserClaimsDto dto)
  • toAuthentication(String token)

JwtUserClaimsDto에 포함되는 필드는 userId, userCmpn, userTeam, userName, userRole입니다.

ApiKeyUserClaimsProvider

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

API Key를 JwtUserClaimsDto로 매핑하는 확장 인터페이스입니다.

Optional<JwtUserClaimsDto> findUserByApiKey(String apiKey);

서비스에서 직접 구현한 Bean을 등록하거나, kri.auth.apikey.enabled=true와 JPA 관련 classpath/설정을 통해 DB preload 기반 provider를 사용할 수 있습니다.

요청 사용자 컨텍스트

RequestUserContext

import com.kri.common.feature.web.RequestUserContext;

컨트롤러 파라미터로 선언하면 현재 인증 사용자와 client IP를 받을 수 있습니다. JwtService Bean이 있을 때 RequestUserContextArgumentResolver가 자동 등록됩니다.

@GetMapping("/me")
public Object me(RequestUserContext user) {
  return user;
}

필드는 userId, userCmpn, userTeam, userName, userRole, clientIp이며, isAuthenticated()는 userId != null일 때 true를 반환합니다.

예외/페이징

BusinessException

서비스 레이어에서 HTTP 상태, 에러 코드, 메시지, 부가 정보를 함께 담아 던지는 런타임 예외입니다.

throw BusinessException.badRequest("INVALID_INPUT", "입력값이 올바르지 않습니다.");

팩토리 메서드:

  • badRequest
  • unauthorized
  • forbidden
  • notFound
  • conflict
  • validationError
  • internalError
  • of

with(String key, Object value)로 응답에 포함할 부가 정보를 추가할 수 있습니다.

PageRequestDto, Pageables, PageResponseDto

Pageable pageable = Pageables.of(req, ProjectEntity.class);
PageResponseDto<ProjectDto> response = PageResponseDto.from(page);

PageRequestDto 기본값:

  • pageIndex = 0
  • pageSize = 10
  • sortBy = "prjctIdx"
  • sortDir = "desc"

Pageables.of는 정렬 필드가 대상 클래스에 존재하는지 검증한 뒤 Pageable을 생성합니다.

Redis

RedisQueueHelper

import com.kri.common.feature.redis.RedisQueueHelper;

StringRedisTemplate 기반 Redis List 큐 helper입니다.

  • enqueue(String key, String value)
  • blockingDequeue(String key, Duration timeout)

kri.redis.enabled=true이고 RedisConnectionFactory가 있으면 자동 등록됩니다.

HTTP

ExternalApiClient, ExternalApiResponse

JDK HttpClient 기반 경량 HTTP client입니다.

ExternalApiClient client = new ExternalApiClient();
ExternalApiResponse res = client.post(url, headers, jsonBody);

ExternalApiMultipartPart를 사용해 multipart/form-data 업로드를 전송할 수 있습니다.

List<ExternalApiMultipartPart> parts = List.of(
    ExternalApiMultipartPart.formField("serviceCode", "demo"),
    ExternalApiMultipartPart.file("file", "한글-파일.txt", "text/plain", fileBytes)
);

ExternalApiResponse res = client.postMultipart(url, headers, parts);

multipart 요청에서는 전달한 headers의 Content-Type 값을 무시하고, 필요한 boundary를 포함한 Content-Type: multipart/form-data; boundary=... 값을 자동 생성합니다. multipart 파트 헤더와 텍스트 필드는 UTF-8로 인코딩하고, 파일 내용은 원본 byte[]로 전송합니다. ASCII와 non-ASCII 파일명 모두 원본 값을 quoted filename에 UTF-8 바이트로 전송하며, ASCII fallback이나 filename*는 추가하지 않습니다.

Content-Disposition: form-data; name="file"; filename="한글-파일.txt"

지원 메서드:

  • get
  • delete
  • post
  • put
  • patch
  • postMultipart
  • putMultipart

응답은 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 등을 처리할 수 있습니다.

패키지:

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;

설정 예:

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 예:

@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 목록에 연결합니다.

@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가 마지막입니다.

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는 전달하지 않습니다.

암호화와 해시

공개 API는 com.kri.common.feature.crypto.*에 있습니다. 중앙 키 DB를 사용하지 않으며, AES master key는 kri.crypto.aes.keys 설정 또는 각 호출의 masterKey로 전달합니다.

AES-256

기본 알고리즘은 인증 암호화인 AES_256_GCM입니다. masterKey와 salt를 PBKDF2WithHmacSHA256으로 처리해 256-bit AES key를 만들며, salt와 IV를 생략하면 안전한 난수로 자동 생성합니다. 기존 시스템 연동을 위해 salt와 IV를 직접 전달할 수도 있습니다.

import com.kri.common.feature.crypto.aes.AesCryptoService;
import com.kri.common.feature.crypto.aes.AesDecryptRequest;
import com.kri.common.feature.crypto.aes.AesEncryptRequest;
import com.kri.common.feature.crypto.aes.AesEncryptedValue;
import com.kri.common.feature.crypto.aes.AesEncryptedValueCodec;
import com.kri.common.feature.crypto.aes.TagLayout;

AesEncryptedValue encrypted = aesCryptoService.encrypt(
    AesEncryptRequest.builder(plainBytes)
        .masterKey(masterKey)
        .salt(salt)
        .iv(iv)
        .aad(aad)
        .tagLayout(TagLayout.DETACHED)
        .build()
);

String storedValue = AesEncryptedValueCodec.encode(encrypted);
AesEncryptedValue decoded = AesEncryptedValueCodec.decode(storedValue);
byte[] restored = aesCryptoService.decrypt(
    AesDecryptRequest.builder(decoded)
        .masterKey(masterKey)
        .aad(aad)
        .build()
);
  • GCM tag는 ciphertext 결합형 APPENDED 또는 별도 필드형 DETACHED를 지원합니다.
  • GCM tag는 생략할 수 없습니다. tag가 없는 기존 데이터는 명시적으로 AES_256_CBC_PKCS5를 선택해야 하며, CBC는 변조를 감지하지 못하므로 신규 데이터에 권장하지 않습니다.
  • GCM IV는 12바이트, CBC IV는 16바이트이고 salt는 최소 16바이트입니다.
  • 호출자가 IV를 직접 전달하면 동일한 key에서 IV가 중복되지 않도록 호출 서비스가 보장해야 합니다.
  • AAD는 GCM에서만 지원하며 복호화할 때 암호화 시점과 동일한 값을 전달해야 합니다.
  • 암호화 결과는 format version, algorithm, key ID, KDF iteration, salt, IV, ciphertext 및 tag 정보를 포함합니다.

일반 digest와 BCrypt

import com.kri.common.feature.crypto.hash.AdaptiveHashService;
import com.kri.common.feature.crypto.hash.DigestAlgorithm;
import com.kri.common.feature.crypto.hash.DigestEncoding;
import com.kri.common.feature.crypto.hash.DigestService;

String checksum = digestService.digest(
    bytes,
    DigestAlgorithm.SHA_256,
    DigestEncoding.HEX_LOWER
);

String encodedSecret = adaptiveHashService.hash("secret-value");
boolean matched = adaptiveHashService.matches("secret-value", encodedSecret);

DigestService는 MD5, SHA-1, SHA-256, SHA-512와 HEX 소문자/대문자, Base64 출력을 지원합니다. MD5와 SHA-1 enum 이름은 각각 MD5_LEGACY, SHA_1_LEGACY이며 기존 데이터 검증과 연동에만 사용해야 합니다. AdaptiveHashService는 BCrypt 기반이며 비밀번호뿐 아니라 PIN, 복구 코드, API Secret 같은 짧은 비밀값 검증에 사용할 수 있습니다. BCrypt 결과에는 salt가 포함되며 일반적인 구현의 72바이트 입력 제한을 고려해야 합니다.

JSON

JsonUtil

Jackson ObjectMapper를 명시적으로 받아 JSON 변환을 수행하는 static helper입니다.

  • toMap
  • parseJsonToMap
  • toJson
  • toPrettyJson
  • fromJson
  • deepCopy
  • convert

Excel

ExcelColumn

DTO 필드와 Excel 컬럼을 매핑하는 애너테이션입니다.

@ExcelColumn(header = "사용자 ID", order = 1, width = 20)
private String userId;
  • header: Excel 헤더명
  • order: 컬럼 순서
  • width: 문자 폭 기준 너비, -1이면 기본 auto size 흐름 사용

ExcelMapper

Apache POI 기반 Excel 읽기/쓰기 helper입니다.

주요 기능:

  • DTO 리스트를 Workbook으로 쓰기
  • Workbook을 DTO 리스트로 읽기
  • Map<String, ?> 리스트를 Excel로 쓰기
  • Excel을 List<Map<String, String>>으로 읽기
  • SXSSFWorkbook 기반 대용량 스트리밍 쓰기
  • SAX 기반 대용량 스트리밍 읽기
  • streaming writer를 열어 row를 점진적으로 append

StreamingReadOptions

스트리밍 읽기 옵션입니다.

  • sheetName
  • sheetIndex
  • headerRowIndex
  • headerNormalizer

기본값은 첫 번째 sheet, header row index 1, header normalizer identity입니다.

날짜/시간

DateTimeUtil

KST/UTC 기준 날짜 시간 변환 helper입니다.

주요 기능:

  • 현재 KST 날짜/시간 반환
  • Instant를 KST 문자열, ZonedDateTime, LocalDateTime, LocalDate로 변환
  • yyyy-MM-dd, yyyy-MM-dd HH:mm:ss, ISO datetime 형식 검증
  • 문자열을 Instant, LocalDate, LocalDateTime으로 파싱

LenientLocalDateTime

Jackson 역직렬화에서 여러 날짜/시간 입력을 허용하기 위한 필드 애너테이션입니다. 내부적으로 LenientLocalDateTimeDeserializer를 사용합니다.

Enum

CodeEnum<T>, CodeEnumUtils

코드값을 갖는 enum의 공통 인터페이스와 변환 helper입니다.

public enum Status implements CodeEnum<String> {
  ACTIVE("A");

  private final String code;

  @Override
  public String getCode() {
    return code;
  }
}

Status status = CodeEnumUtils.fromCode(Status.class, "A");

웹 자동 구성은 request parameter/path variable의 문자열 값을 CodeEnum 구현 enum으로 변환하는 CodeEnumConverter를 등록합니다. Swagger 자동 구성은 CodeEnum schema/parameter 설명도 보강합니다.

JPA

AbstractCodeEnumConverter

JPA AttributeConverter 구현을 쉽게 만들기 위한 추상 클래스입니다.

BaseUuidEntity

UUID 기반 JPA base entity입니다.

EntityColumnAccessor

JPA @Column(name = "...") 기준으로 entity 필드를 읽고 쓰는 reflection helper입니다.

  • get
  • set
  • setForInsert
  • setForUpdate

Cache base class

AbstractMapCache<K, V>, AbstractListCache<T>

메모리 캐시 구현을 위한 base class입니다. 구현체는 데이터를 로딩하는 protected 메서드를 구현하고, 필요 시 loadOnStartup, reload, clear, put/add 계열 메서드를 사용합니다.

File/String/Number/Common utility

FileUtil

  • sanitizeFileName
  • getExtension
  • extractFileNameFromPath

StringUtil

  • null/blank 검사
  • 이메일/숫자 정규화
  • 기본 텍스트/이메일 형식 검사
  • HTML, JSON, CSV, Excel formula escape

NumericUtil

  • numeric 문자열 검사
  • short/int/long 안전 파싱
  • 숫자만 추출해 Integer로 파싱

CollectionUtil

  • Map, Collection empty 검사

CommonUtil

  • UUID 문자열 생성

yml로 설정하는 자동 구성

전체 예시

kri:
  auth:
    jwt:
      secret: "replace-with-service-secret-at-least-32-bytes"
      issuer: "kri-it"
      access-token-validity-seconds: 86400
      refresh-token-validity-seconds: 604800
    apikey:
      enabled: false
      header-name: "X-API-Key"
      allowed-paths: []
      excluded-paths: []
      service-code: "example-service"
      preload-on-startup: false
      admin-api-enabled: false
      admin-allow-ips:
        - "127.0.0.1/32"
        - "localhost"
        - "0:0:0:0:0:0:0:1"
      db:
        url: "jdbc:mysql://localhost:3306/kri_common?characterEncoding=UTF-8"
        username: "app"
        password: "secret"
        driver-class-name: "com.mysql.cj.jdbc.Driver"
      jpa:
        show-sql: false
        format-sql: false
  crypto:
    aes:
      active-key-id: "key-2026"
      keys:
        key-2026: "replace-with-a-service-master-key"
      algorithm: AES_256_GCM
      tag-layout: APPENDED
      kdf:
        iterations: 600000
        salt-length: 16
    hash:
      bcrypt:
        strength: 12
  security:
    enabled: true
    allowed-ips:
      - "127.0.0.1"
      - "10.0.0.0/8"
    public-paths:
      - "/v3/api-docs/**"
      - "/swagger-ui.html"
      - "/swagger-ui/**"
  swagger:
    enabled: true
    title: "KRI API"
    description: "KRI Common API Docs"
    version: "v1"
    base-package:
      - "com.example.api"
    allowed-ips:
      - "127.0.0.1"
      - "localhost"
  web:
    enabled: true
    mdc:
      enabled: true
  redis:
    enabled: false
  scheduling:
    enabled: false
  error:
    expose:
      handler: false
      service: false

운영 서비스에서는 JWT secret, API Key DB 접속 정보, Swagger/API Key admin 허용 IP를 반드시 서비스 환경에 맞게 override해야 합니다.

kri.crypto

  • aes.active-key-id: 직접 master key를 전달하지 않았을 때 사용할 key ID
  • aes.keys: key ID별 master key. 복호화 호환을 위해 교체 전 key도 필요한 기간 동안 유지
  • aes.algorithm: 기본값 AES_256_GCM
  • aes.tag-layout: 기본값 APPENDED
  • aes.kdf.iterations: PBKDF2 반복 횟수, 기본값 600000
  • aes.kdf.salt-length: 자동 생성 salt 길이, 기본값 16
  • hash.bcrypt.strength: 기본 BCrypt cost, 기본값 12, 허용 범위 4..31

kri.crypto.enabled 설정은 없습니다. Crypto API Bean은 항상 자동 구성되며, YML 키가 없어도 호출 시 master key를 직접 전달할 수 있습니다. 설정과 호출 양쪽에 키가 있으면 직접 전달한 키가 우선합니다. master key를 소스에 커밋하거나 로그와 예외에 출력하지 마십시오.

kri.auth.jwt

관련 클래스:

  • JwtAutoConfiguration
  • JwtProperties
  • JwtService

기능:

  • JwtProperties를 바탕으로 JwtService Bean 등록
  • access token, refresh token 유효 시간 설정
  • issuer, HMAC secret 설정

기본값은 개발 편의를 위한 값이므로 운영에서는 secret을 반드시 교체해야 합니다.

kri.auth.apikey

관련 클래스:

  • ApiKeyProperties
  • ApiKeyJpaAutoConfiguration
  • ApiKeyPreloadAutoConfiguration
  • ApiKeyAdminAutoConfiguration
  • ApiKeyAuthFilter
  • PreloadedApiKeyUserClaimsProvider

기능:

  • enabled=true일 때 API Key 인증 기능 활성화
  • header-name으로 API Key를 읽을 HTTP header 지정
  • allowed-paths가 한 개 이상이면 일치하는 요청에서만 API Key 인증 시도
  • excluded-paths와 일치하는 요청은 허용 여부와 관계없이 API Key 인증에서 제외
  • JPA repository를 통해 서비스별 활성 API Key를 preload cache로 적재
  • ApiKeyAuthFilter가 API Key를 Authentication으로 변환
  • admin-api-enabled=true일 때 내부 reload/cache endpoint 노출

API Key를 일부 API에서만 인증 수단으로 허용하려면 다음처럼 설정합니다.

kri:
  auth:
    apikey:
      enabled: true
      header-name: X-API-Key
      service-code: kric-contact-service
      allowed-paths:
        - /api/v1/list/update/**
        - /api/v1/external/**
      excluded-paths:
        - /api/v1/external/admin/**

경로 설정의 동작은 다음과 같습니다. 두 설정이 겹치면 excluded-paths가 우선합니다.

allowed-paths excluded-paths API Key 인증 대상
비어 있음 비어 있음 기존처럼 모든 요청
비어 있음 설정됨 제외 패턴과 일치하지 않는 요청
설정됨 비어 있음 허용 패턴과 일치하는 요청
설정됨 설정됨 허용 패턴과 일치하면서 제외 패턴과 일치하지 않는 요청

하위 호환 규칙과 매칭 방식은 다음과 같습니다.

  • 각 속성의 미설정, null, 빈 목록 또는 공백 패턴만 있는 목록은 해당 경로 제한을 적용하지 않습니다.
  • allowed-paths에 유효한 패턴이 하나 이상이면 그중 하나와 일치하는 요청만 인증 대상이 됩니다.
  • excluded-paths에 유효한 패턴이 하나 이상이면 그중 하나와 일치하는 요청은 항상 인증 대상에서 제외됩니다.
  • Spring 경로 패턴을 사용하며 *는 한 경로 구간, **는 하위 경로 전체와 매칭합니다.
  • HTTP method는 구분하지 않고, context path와 query string은 매칭 대상에서 제외합니다.
  • 패턴은 /로 시작해야 하며 잘못된 패턴은 애플리케이션 기동 시 오류로 처리됩니다.
  • 두 설정은 API Key 인증 필터의 적용 범위만 제한합니다. 경로를 공개하거나 접근 권한을 직접 부여하지 않습니다.
  • 공개 경로는 별도 설정인 kri.security.public-paths로 관리합니다.

주의:

  • DB preload 방식은 JPA와 DataSource 관련 classpath가 필요합니다.
  • JPA classpath가 없으면 DB preload 자동 구성만 건너뛰며, 서비스가 직접 등록한 ApiKeyUserClaimsProvider는 사용할 수 있습니다.
  • service-code가 비어 있으면 preload cache는 비어 있게 됩니다.
  • admin API는 IP allowlist를 통과해야 합니다.

kri.security

allowed-ips is optional. When it is empty, the default security chain behaves as before. When it has values, public-paths require an allowed client IP but no authentication, and all other paths require both an allowed client IP and authentication. Exact IPs, CIDR values, and localhost are supported.

관련 클래스:

  • KriSecurityAutoConfiguration
  • KriSecurityProperties
  • JwtAuthenticationFilter
  • ApiKeyAuthFilter

기능:

  • 기본 Spring Security filter chain 등록
  • HTTP Basic, CSRF 비활성화
  • CORS 기본 활성화
  • stateless session policy 적용
  • public-paths는 permitAll
  • 나머지 요청은 인증 필요
  • API Key filter가 있으면 먼저 적용하고, 그 다음 JWT filter 적용
  • @EnableMethodSecurity(jsr250Enabled=true, prePostEnabled=true) 활성화

서비스가 자체 SecurityFilterChain Bean을 등록하면 이 라이브러리의 기본 filter chain은 생성되지 않습니다.

kri.swagger

관련 클래스:

  • KriSwaggerAutoConfiguration
  • KriSwaggerProperties
  • SwaggerIpFilter
  • CodeEnumModelConverter
  • CodeEnumOpenApiCustomizer

기능:

  • OpenAPI metadata 설정
  • Bearer JWT와 API Key security scheme 등록
  • GroupedOpenApi group kri-api 생성
  • /api/**, /internal/** 경로 문서화
  • base-package가 있으면 해당 패키지만 scan
  • API Key admin API가 활성화되면 내부 admin endpoint package도 scan
  • Swagger UI/API docs 접근 IP 제한
  • CodeEnum 구현 enum의 schema/parameter 설명 보강

kri.web

관련 클래스:

  • CommonWebAutoConfiguration
  • ErrorAdvice
  • TraceFilter
  • ServiceMdcAspect
  • RequestUserContextArgumentResolver
  • CodeEnumConverter

기능:

  • 공통 예외 응답 처리
  • 요청별 trace filter 등록
  • handler/service 정보를 MDC에 기록
  • RequestUserContext 컨트롤러 argument resolver 등록
  • 전체 CORS mapping 등록
  • CodeEnum converter 등록

kri.web.enabled 기본값은 true, kri.web.mdc.enabled 기본값은 true입니다.

kri.redis

관련 클래스:

  • CommonRedisAutoConfiguration
  • RedisQueueHelper

kri.redis.enabled=true, RedisTemplate classpath, RedisConnectionFactory Bean이 모두 있을 때 RedisQueueHelper를 등록합니다. 기본값은 false입니다.

kri.scheduling

관련 클래스:

  • CommonSchedulingAutoConfiguration

kri.scheduling.enabled=true일 때 Spring scheduling을 활성화합니다. 기본값은 false입니다.

kri.error.expose.*

관련 클래스:

  • ErrorAdvice

공통 에러 응답에 handler/service MDC 정보를 포함할지 제어합니다.

  • kri.error.expose.handler
  • kri.error.expose.service

자동 노출 endpoint

API Key admin

클래스:

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

노출 조건:

  • kri.auth.apikey.enabled=true
  • kri.auth.apikey.admin-api-enabled=true
  • PreloadedApiKeyUserClaimsProvider Bean 존재

Endpoint:

  • POST /internal/apikey/reload: DB에서 API Key cache 재적재
  • GET /internal/apikey/cache: 현재 메모리 cache 조회, API Key는 mask 처리

접근 제어:

  • kri.auth.apikey.admin-allow-ips
  • 기본 허용값은 local address 계열
  • 허용되지 않은 IP는 403
  • admin API가 비활성화된 상태에서는 404

자동 구성 목록

자동 구성 목록은 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
  • com.kri.common.autoconfigure.crypto.CryptoAutoConfiguration

사용 시 권장 기준

  • 서비스 코드에서는 가능한 한 feature 패키지의 타입만 직접 사용합니다.
  • runtime 패키지는 자동 구성으로 조립되는 내부 구현으로 보고 직접 의존을 피합니다.
  • 운영 환경에서는 기본 JWT secret과 API Key DB 설정을 사용하지 않습니다.
  • AES 신규 데이터는 GCM을 사용하고, MD5·SHA-1·AES-CBC는 레거시 호환 범위로 제한합니다.
  • 자체 보안 정책이 필요한 서비스는 직접 SecurityFilterChain Bean을 등록해 기본 구성을 대체합니다.
  • Swagger 접근 제한은 운영망/관리망 정책에 맞춰 allowed-ips를 명시합니다.
  • 대용량 Excel은 일반 Workbook 변환보다 streaming API를 우선 검토합니다.
  • 배포 전 ./gradlew compileJava로 컴파일을 확인합니다.

변경 이력

  • 2026-08-06: beta.1.6.3에서 non-ASCII multipart 파일명을 ASCII fallback/ filename* 없이 원본 filename의 UTF-8 바이트로 전송하도록 복원했습니다.
  • 2026-08-06: beta.1.6.2에서 non-ASCII multipart 파일명에 ASCII filename fallback과 UTF-8 filename*를 추가했습니다.
  • 2026-08-04: kri.auth.apikey.allowed-paths와 kri.auth.apikey.excluded-paths를 추가했습니다. 미설정·null·빈 목록은 기존 전역 API Key 인증 동작을 유지하며, 제외 패턴은 허용 패턴보다 우선합니다.