English | 한국어

iso20022lib-core (ISO20022 코어 모듈)
✔ ️iso20022lib-spring (스프링 확장 모듈)
iso20022-editor (웹 기반 ISO20022 에디터)

ISO20022 Spring Module

ISO20022 Spring Module은 ISO20022 Core 라이브러리를 Spring Boot 애플리케이션에 쉽게 통합할 수 있는 기능 제공. Spring Boot의 자동 구성 메커니즘을 활용하여 설정을 단순화하고 Spring 프레임워크와의 원활한 통합 지원.

주요 기능

• 자동 구성: Spring Boot의 auto-configuration 기능을 활용한 자동 초기화
• 외부 설정 지원: application.properties 또는 application.yml 파일을 통한 설정
• 호환성 검증: Core 라이브러리와의 버전 호환성 자동 검증
• 통합 테스트: 시작 시 라이브러리 기능성 확인 테스트 자동 수행

설치 방법

Gradle

dependencies {
    implementation 'com.innilabs:iso20022lib-core:0.6.6-SNAPSHOT'
    implementation 'com.innilabs:iso20022lib-spring:0.6.6-SNAPSHOT'
}

Maven

<dependencies>
    <dependency>
        <groupId>com.innilabs</groupId>
        <artifactId>iso20022lib-core</artifactId>
        <version>0.6.6-SNAPSHOT</version>
    </dependency>
    <dependency>
        <groupId>com.innilabs</groupId>
        <artifactId>iso20022lib-spring</artifactId>
        <version>0.6.6-SNAPSHOT</version>
    </dependency>
</dependencies>

설정 방법

기본 설정

Spring Boot 애플리케이션에서 ISO20022 Spring Module을 사용하기 위한 별도의 코드는 필요 없음. 의존성만 추가하면 자동으로 구성.

외부 설정

application.properties 또는 application.yml 파일에서 다음 속성을 사용하여 라이브러리 동작 커스터마이징 가능:

iso20022:
  # 일반 설정
  encoding: UTF-8                    # 메시지 인코딩 (기본값: UTF-8)
  timezone: Asia/Jakarta             # 날짜/시간 처리 기본 시간대 (기본값: Asia/Jakarta)
  hash-key: secretiso20022          # 해시/HMAC 생성 비밀키 (기본값: secretiso20022)
  
  # 검증 설정
  validation:
    schema: false                    # 스키마 검증 활성화 여부 (기본값: false)
  
  # XML 포맷 설정
  xml:
    pretty-print: true              # XML 출력 시 가독성 포맷팅 적용 (기본값: false)
  
  # JSON 포맷 설정
  json:
    pretty-print: false             # JSON 출력 시 가독성 포맷팅 적용 (기본값: false)
  
  # 파일 처리 설정
  file:
    policy: overwrite               # 기존 파일 처리 정책: FAIL, OVERWRITE, SKIP (기본값: FAIL)
  
  # 복합 메시지(MessageEnvelope) 설정
  envelope:
    root-name: envelope             # 최상위 XML 요소 이름 (기본값: envelope)
    header-prefix: head             # 헤더 요소 접두어 (기본값: head)
    body-prefix: doc                # 본문 요소 접두어 (기본값: doc)
    
    # 복합 메시지 XML 설정
    xml:
      indentation: 4                # XML 들여쓰기 공백 수 (기본값: 4)
      standalone: true              # XML standalone 속성 설정 (기본값: true)

속성 상세 가이드

동작 메커니즘

Spring Module은 다음 과정을 통해 ISO20022 라이브러리를 자동으로 구성:

1. 모듈 검출: Spring Boot는 클래스패스에서 ISO20022 Spring Module을 감지
2. 버전 검증: Core 라이브러리와의 버전 호환성 확인
3. 설정 로드: application.properties 또는 application.yml에서 설정 로드
4. 구성 생성: 로드된 설정을 기반으로 ISO20022 구성 객체 생성
5. 초기화: ISO20022ConfigHolder에 생성된 구성 설정
6. 테스트: 라이브러리 기능 검증을 위한 간단한 테스트 수행

예외 처리

Spring Module은 다음과 같은 예외 유형을 정의:

• ISO20022SpringException: 최상위 예외 클래스
  • ConfigurationException: 구성 관련 오류
  • VersionIncompatibleException: 버전 호환성 오류
  • InitializationException: 초기화 실패 오류

예외 처리 예시:

try {
    // ISO20022 라이브러리 사용
} catch (ISO20022SpringException.VersionIncompatibleException e) {
    // 버전 호환성 문제 처리
    logger.error("Core 라이브러리와 Spring 모듈 버전 불일치: {}", e.getMessage());
} catch (ISO20022SpringException e) {
    // 기타 Spring 모듈 오류 처리
    logger.error("ISO20022 Spring 모듈 오류: {}", e.getMessage());
}

버전 호환성

Spring Module은 Core 라이브러리와의 버전 호환성을 자동으로 검증. 호환되지 않는 버전을 사용할 경우 애플리케이션 시작 시 VersionIncompatibleException 예외 발생.

각 Spring Module 버전에는 호환되는 Core 라이브러리의 최소/최대 버전이 지정되어 있음. 자세한 호환성 정보는 버전 호환성 체크 페이지를 참고.

주의사항

1. 단일 구성: ISO20022ConfigHolder는 애플리케이션당 한 번만 초기화 가능. 이미 초기화된 경우 추가 초기화 시도는 무시.
2. 스레드 안전성: Spring Module은 스레드 안전한 방식으로 라이브러리를 초기화.
3. 버전 일관성: Core 라이브러리와 Spring Module의 버전을 일치시켜 호환성 문제 방지.

문제 해결

자동 구성이 작동하지 않는 경우

• Spring Boot의 자동 구성이 활성화되어 있는지 확인
• 클래스패스에 ISO20022 Spring Module이 포함되어 있는지 확인
• 다른 구성 요소가 ISO20022ConfigHolder를 수동으로 초기화하지 않았는지 확인

버전 호환성 오류

• Core 라이브러리와 Spring Module의 버전이 호환되는지 확인
• 동일한 메이저 및 마이너 버전 사용 권장

설정 속성이 적용되지 않는 경우

• application.properties 또는 application.yml 파일이 올바른 경로에 있는지 확인
• 속성 이름과 값이 정확하게 지정되었는지 확인
• Spring Boot의 프로필 설정 확인

© 2025 INNILABS. All rights reserved.