코드비플랫, CODEPLAT, codebplat, XBRL, xbrl, 전자공시, 공시

ClearOps-Core

Spring Boot 애플리케이션을 위한 공통 운영 기능 라이브러리

개요

ClearOps-Core는 Spring Boot 기반 마이크로서비스에서 공통적으로 필요한 운영 기능을 제공하는 Java 라이브러리입니다.

감사 로깅, 알림 전송, 페이지네이션 등의 기능을 자동 설정을 통해 손쉽게 통합할 수 있습니다.

Version: 0.0.16-SNAPSHOT

Group: kr.co.codebplat

Java Version: 25

주요 기능

1. 감사 로깅 (Audit Logging)

REST API 요청/응답을 자동으로 기록하는 AOP 기반 감사 로깅
요청 정보(HTTP 메서드, URI, 헤더, 파라미터, 본문) 및 응답 정보(실행 시간, 상태, 응답 본문) 기록
민감 정보(비밀번호, 토큰, 쿠키 등) 자동 마스킹
MDC(Mapped Diagnostic Context)를 통한 로그 추적

주요 클래스:

AuditLoggingAspect: REST 컨트롤러 메서드 실행을 감싸 감사 로그를 생성
AuditLog: 감사 로그 데이터 모델
LogMessage: 시스템 로그 전송용 메시지 모델
LogLevel: 로그 심각도 수준 정의

설정:

audit:
  logging:
    enabled: true  # 감사 로깅 활성화 (기본값: false)

2. 로그 롤오버 및 외부 저장소 연동

Logback 롤링 정책을 확장하여 로그 파일 롤오버 시 자동으로 외부 저장소에 업로드
오브젝트 스토리지, 메시지 큐 등과 연동 가능

주요 클래스:

ObjectStorageRollingPolicy: 롤오버 후 파일을 외부 저장소로 전송
LogMessageRepository: 로그 파일 수집/색인/전송 인터페이스

3. 알림 전송 (Notification)

다양한 채널(이메일, 메신저, 푸시 등)을 통한 알림 전송 추상화
우선순위 기반 알림 전송
확장 가능한 인터페이스 설계

주요 클래스:

NotificationSender<T>: 알림 전송 인터페이스
NotificationMessage: 알림 메시지 모델
NotificationPriority: 알림 우선순위 정의
NoOpSender: 기본 No-Operation 전송기

4. 공통 지원 유틸리티

페이지네이션: 표준화된 페이지 응답 인터페이스
- Pagination<T>: 페이지네이션 결과 인터페이스
- SimplePagination<T>: 기본 페이지네이션 구현
컬렉션 응답: 페이징 없는 단순 컬렉션 응답
- CollectionResponse<T>: 컬렉션 응답 래퍼
검증 유틸리티: 전제 조건 검증
- Preconditions: 파라미터 검증 헬퍼
정렬: 정렬 방향 정의
- SortDirection: ASC/DESC 열거형

설치 및 사용법

1. 의존성 추가

Gradle:

dependencies {
    implementation 'kr.co.codebplat:clear-ops-core:0.0.16-SNAPSHOT'
}

repositories {
    maven {
        url = {maven repository url}
        credentials {
            username = {maven repository 로그인 사용자}
            password = {maven repository 로그인 비밀번호}
        }
        allowInsecureProtocol = true
    }
}

Maven:

<dependency>
    <groupId>kr.co.codebplat</groupId>
    <artifactId>clear-ops-core</artifactId>
    <version>0.0.16-SNAPSHOT</version>
</dependency>

<repository>
    <id>{maven repository id}</id>
    <url>{maven repository url}</url>
</repository>

2. 자동 설정 활성화

ClearOps-Core는 Spring Boot Auto-Configuration을 사용합니다.

CoreAutoConfiguration이 자동으로 kr.co.codebplat.clear.ops 패키지를 스캔하여 필요한 빈을 등록합니다.

별도 설정 없이 의존성만 추가하면 자동으로 활성화됩니다.

3. 감사 로깅 사용

application.yml 설정:

audit:
  logging:
    enabled: true

컨트롤러 예제:

@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping("/{id}")
    public UserResponse getUser(@PathVariable Long id) {
        // 요청/응답이 자동으로 로깅됩니다
        return userService.findById(id);
    }

    @PostMapping
    public UserResponse createUser(@RequestBody UserRequest request) {
        // 민감 정보(password 등)는 자동으로 마스킹됩니다
        return userService.create(request);
    }
}

4. 알림 전송 구현

알림 전송기 구현:

@Component
public class EmailNotificationSender implements NotificationSender<EmailNotificationMessage> {

    @Override
    public boolean supports(NotificationMessage request) {
        return request instanceof EmailNotificationMessage;
    }

    @Override
    public void send(EmailNotificationMessage message) {
        // 이메일 전송 로직 구현
    }
}

사용 예제:

@Service
public class NotificationService {

    private final List<NotificationSender> senders;

    public void sendNotification(NotificationMessage message) {
        senders.stream()
                .filter(sender -> sender.supports(message))
                .findFirst()
                .ifPresent(sender -> sender.send(message));
    }
}

5. 페이지네이션 사용

@RestController
@RequestMapping("/api/products")
public class ProductController {

    @GetMapping
    public Pagination<ProductResponse> getProducts(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") int size) {

        return productService.findAll(page, size);
    }
}

6. 로그 저장소 구현

외부 저장소에 로그를 전송하려면 LogMessageRepository 인터페이스를 구현합니다:

@Component
public class S3LogRepository implements LogMessageRepository {

    @Override
    public void accept(Path logFilePath) {
        // S3에 로그 파일 업로드 로직
    }
}

기술 스택

Spring Boot: 4.0.0
Spring Framework: 6.x
Java: 25
Logback: 로깅 프레임워크
SpringDoc OpenAPI: 3.0.0 (API 문서화)
Micrometer: Prometheus 메트릭 수집
Jetty: 내장 서블릿 컨테이너

빌드 및 배포

빌드

./gradlew clean build

로컬 Maven 저장소에 배포

./gradlew publishToMavenLocal

Nexus 저장소에 배포

./gradlew publish \
  -PmavenUsername=your-username \
  -PmavenPassword=your-password

라이선스

작성자

김민규 (minkyu.kim@codebplat.co.kr)
김태훈 (thkim0214@codebplat.co.kr)
추민영 (chu35my@codebplat.co.kr)

이전글Graph Mode