Files
common-library/README.md

707 lines
22 KiB
Markdown

# 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`:
```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`)에 자격 증명:
```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`:
```yaml
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
```java
@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
```java
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
주요 메서드:
```java
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;
}
```
**로그인 예시**
```java
@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
```java
@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 (서비스 구현 필요)
```java
public interface ApiKeyUserClaimsProvider {
/**
* API Key 로 사용자 정보를 조회한다.
*
* @param apiKey 요청 헤더에서 받은 API Key
* @return 유효한 키면 JwtUserClaimsDto, 아니면 Optional.empty()
*/
Optional<JwtUserClaimsDto> findUserByApiKey(String apiKey);
}
```
**서비스 구현 예시 (`example-service`)**
```java
@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
```java
@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<String> | Swagger 관련 패턴 포함 | `permitAll()` 로 열어둘 URL 목록 |
서비스에서 Swagger 외에 `/actuator/health` 같은 것들도 열고 싶다면:
```yaml
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` 순으로 필터 체인에 추가
**메소드 레벨 권한 예시**
```java
@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
```java
@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" 버튼에 노출
서비스에서 필요한 것은:
```gradle
dependencies {
implementation "org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0"
implementation "com.kri.common:starter:1.0.11"
}
```
그리고 `application.yml`에:
```yaml
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
```java
@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 설정
```java
@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<String> | 기본 CIDR 목록에 *추가*할 CIDR 리스트 |
예시:
```yaml
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
```java
@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
```java
@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 사용 예시
```java
@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`)
```java
@AutoConfiguration
@EnableScheduling
@ConditionalOnProperty(prefix = "common.scheduling", name = "enabled", havingValue = "true")
public class CommonSchedulingAutoConfiguration { }
```
**프로퍼티**
| 프로퍼티 | 타입 | 기본값 | 설명 |
| --------------------------- | ------- | ----- | -------------------------- |
| `common.scheduling.enabled` | boolean | false | `@EnableScheduling` 활성화 여부 |
서비스 쪽에서는 단순히:
```yaml
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')")` 등 사용