본문으로 건너뛰기

ElastiCORE Environment Configuration Guide (env.yml)

Overview​

env.yml is the ElastiCORE domain-specific environment configuration file that defines code generation modes, frameworks, namespaces, annotations, and more. Environment configuration information must be defined before DSL-based modeling.

Basic Structure​

elasticore:  # 또는 env: (레거시 형식)
  enable: true/false
  config:
    domainName: string
    framework: string
    mode: string
    j2ee: string
    # 모드별 추가 설정
  namespace:
    entity: package.path
    dto: package.path
    # 기타 네임스페이스

1. 기본 설정 (config)​

Required Settings​

config:
  domainName: myDomain        # 도메인명 (생성될 패키지와 파일명에 사용)
  framework: springboot       # 프레임워크 지정
  mode: jpa,uml              # 생성 모드 (콤마로 구분)
  j2ee: jakarta              # J2EE 스택 (jakarta/javax)

Framework Settings​

  • springboot: Spring Boot 최신 버전 (기본)

J2EE 스택 선택​

  • jakarta: Jakarta EE (Spring Boot 3.x 기본)
  • javax: Java EE (Spring Boot 2.x 기본) - 현재 SprintBoot 2버전은 지원하지 않기 때문에 해당 옵션은 deprecated 됨.

2. 생성 모드 (mode)​

2.1 JPA 모드​

mode: jpa

Generated Items:

  • JPA 엔티티 클래스
  • Spring Data JPA 리포지토리
  • 서비스 클래스
  • REST 컨트롤러

JPA 모드 세부 설정:

config:
  mode: jpa
  jpa:
    useQueryMethod: true     # 커스텀 쿼리 메서드 생성
  table:
    prefix: "tbl_"          # 테이블 접두사

2.2 UML 모드 (deprecated)​

mode: uml

Generated Items:

  • Mermaid 다이어그램
  • HTML 형태의 UML 문서
  • 엔티티 관계도

2.3 MongoDB 모드​

mode: mongo

Generated Items:

  • MongoDB 컬렉션 엔티티
  • Spring Data MongoDB 리포지토리
  • MongoDB 전용 서비스

MongoDB 모드 설정:

config:
  mode: mongo
  mongo:
    collection:
      prefix: "col_"        # 컬렉션 접두사

2.4 PX(ProductXpress) 모드​

mode: px

Generated Items:

  • PX 플랫폼 연동 모델 코드 자동 생성
  • .pxdpz 파일 기반 모델 처리

PX 모드 설정:

config:
  mode: px
  pxdpz:                    # PX 배포 파일 경로
    - C:\path\to\deployment1.pxdpz
    - C:\path\to\deployment2.pxdpz

3. 어노테이션 설정​

3.1 사용자 정의 어노테이션​

config:
  annotations:
    # ID 생성기 어노테이션
    genid: "genid(io.elasticore.springboot3.util.IdUtils.newId)"

    # 타입 변환 어노테이션
    stringarray: "@entity:Convert(converter = io.elasticore.springboot3.util.StringArrayConverter.class)"
    integerarray: "@entity:Convert(converter = io.elasticore.springboot3.util.IntegerArrayConverter.class)"

    # 커스텀 검증 어노테이션
    email: "@field:Email(message = 'Invalid email format')"
    phone: "@field:Pattern(regexp = '^[0-9-]+$', message = 'Invalid phone format')"

3.2 어노테이션 활용 예시​

# model.yml에서 사용
entity:
  User:
    fields:
      id: string @genid              # genid 어노테이션 적용
      tags: string[] @env:stringarray # stringarray 어노테이션 적용
      coords: int[] @env:integerarray # integerarray 어노테이션 적용
      email: string @env:email        # email 검증 어노테이션
      phone: string @env:phone        # phone 검증 어노테이션

3.3 어노테이션 적용 범위​

  • @entity:: 엔티티 클래스 레벨 어노테이션
  • @field:: 필드 레벨 어노테이션
  • @method:: 메서드 레벨 어노테이션

4. 템플릿 설정​

4.1 커스텀 템플릿 지정​

config:
  template:
    entity: custom/entity.tmpl      # 커스텀 엔티티 템플릿
    dto: custom/dto.tmpl           # 커스텀 DTO 템플릿
    service: custom/service.tmpl    # 커스텀 서비스 템플릿
    repository: custom/repository.tmpl
    controller: custom/controller.tmpl

4.2 테스트 코드 생성 설정​

ElastiCORE는 서비스 레이어에 대한 JUnit 5 기반 단위 테스트를 자동 생성합니다.

config:
  testCode:
    enabled: true                   # 테스트 코드 생성 활성화 (기본값: true)
    framework: junit5               # 테스트 프레임워크 (junit5 기본)
    mockFramework: mockito          # 목 프레임워크 (mockito 기본)

Generated Test Code Features:

  • JUnit 5 + Mockito 기반 단위 테스트
  • 복합키 엔티티 자동 처리 (composite key detection)
  • 자동 샘플 데이터 생성 (모든 필드 타입 지원)
  • CRUD 메서드 완전 테스트 커버리지
  • 검색 메서드 테스트 (List/Page 결과 모두 지원)
  • 성능 테스트 및 통합 스타일 테스트 포함

Generated Test Method Example:

@Test
@DisplayName("findById - should return entity when found")
void findById_ShouldReturnEntityWhenFound() {
    // 자동 생성된 테스트 로직
}

@Test
@DisplayName("save - should save and return new entity")
void save_ShouldSaveAndReturnNewEntity() {
    // 자동 생성된 테스트 로직
}

// 복합키 엔티티의 경우 자동으로 복합키 처리 로직 생성
@Test
@DisplayName("update - should update existing entity")
void update_ShouldUpdateExistingEntity() {
    ContractDriverId id = new ContractDriverId(contractNo, seqNo);
    // ... 테스트 로직
}

5. 네임스페이스 설정​

5.1 기본 네임스페이스​

namespace:
  entity: io.company.domain.entity           # 엔티티 패키지
  dto: io.company.domain.dto                # DTO 패키지
  enumeration: io.company.domain.enums      # 열거형 패키지
  repository: io.company.domain.repository   # 리포지토리 패키지
  service: io.company.domain.service        # 서비스 패키지
  control: io.company.domain.controller     # 컨트롤러 패키지
  port: io.company.domain.port              # 포트 패키지
  proto: io.company.proto                   # Protocol Buffer 패키지

5.2 네임스페이스 명명 규칙​

표준 패턴:

  • {기본패키지}.{도메인}.{타입}
  • 예: io.elasticore.blueprint.domain.bbs.entity

권장 구조:

namespace:
  entity: com.company.{domain}.entity
  dto: com.company.{domain}.dto
  enumeration: com.company.{domain}.enums
  repository: com.company.{domain}.repository
  service: com.company.{domain}.service
  control: com.company.{domain}.controller

6. 데이터소스 설정​

6.1 다중 데이터소스​

config:
  datasources:
    main:                                    # 기본 데이터소스
      driver: org.h2.Driver
      url: jdbc:h2:mem:testdb
      username: sa
      password: ""
    
    legacy:                                  # 레거시 데이터소스
      driver: com.mysql.cj.jdbc.Driver
      url: jdbc:mysql://localhost:3306/legacy
      username: root
      password: password
    
    analytics:                               # 분석용 데이터소스
      driver: org.postgresql.Driver
      url: jdbc:postgresql://localhost:5432/analytics
      username: analyst
      password: secret

6.2 데이터소스 사용​

# transaction port에서 사용
transaction:
  port:
    MainService:
      meta: dbms @datasource("main")         # main 데이터소스 사용
      
    LegacyService:
      meta: dbms @datasource("legacy")       # legacy 데이터소스 사용

7. 환경별 설정 예시​

7.1 Spring Boot 3 + JPA 환경​

elasticore:
  enable: true
  config:
    domainName: userManagement
    framework: springboot
    mode: jpa,uml
    j2ee: jakarta
    lombok: true
    
    jpa:
      useQueryMethod: true
      showSql: true
    
    table:
      prefix: "um_"
    
    testCode:
      enabled: true
      framework: junit5
      mockFramework: mockito
    
    interface:
      pageable: "com.company.common.CustomPageable"
      sortable: "com.company.common.CustomSortable"
    
    annotations:
      genid: "genid(io.elasticore.springboot3.util.IdUtils.newId)"
      audit: "@entity:EntityListeners(AuditingEntityListener.class)"
  
  namespace:
    entity: com.company.user.entity
    dto: com.company.user.dto
    enumeration: com.company.user.enums
    repository: com.company.user.repository
    service: com.company.user.service
    control: com.company.user.controller

7.2 MongoDB 환경​

env:
  config:
    mode: mongo,uml
    framework: springboot
    lombok: true
    domainName: dataStore
    j2ee: jakarta
    
    mongo:
      collection:
        prefix: "ds_"
      connection:
        database: datastore
        host: localhost
        port: 27017
  
  namespace:
    entity: com.company.data.entity
    dto: com.company.data.dto
    enumeration: com.company.data.enums
    repository: com.company.data.repository
    service: com.company.data.service

7.3 PX 플랫폼 연동 환경​

env:
  config:
    mode: px
    framework: springboot:2.7
    lombok: true
    domainName: calculation
    
    pxdpz:
      - C:\px\deployments\CalculationDeployment_0_0@_0_1_Operation.pxdpz
      - C:\px\deployments\CalculationDeployment_0_0@_0_1_traditional.pxdpz
    
    template:
      entity: custom/px_entity.tmpl
      dto: elasticore-template/px/dto.tmpl
  
  namespace:
    entity: io.company.px.entity
    dto: io.company.px.dto
    enumeration: io.company.px.enums

7.4 마이크로서비스 환경​

elasticore:
  enable: true
  config:
    domainName: orderService
    framework: springboot
    mode: jpa,uml,java
    j2ee: jakarta
    
    microservice:
      enabled: true
      port: 8080
      contextPath: /api/v1/orders
    
    jpa:
      useQueryMethod: true
      database: mysql
    
    annotations:
      genid: "genid(io.company.common.util.IdGenerator.generate)"
      trace: "@method:Traced"
      cache: "@method:Cacheable(value = 'default')"
  
  namespace:
    entity: io.company.order.entity
    dto: io.company.order.dto
    enumeration: io.company.order.enums
    repository: io.company.order.repository
    service: io.company.order.service
    control: io.company.order.controller
    port: io.company.order.port

8. 고급 설정​

8.1 환경 변수 참조​

config:
  domainName: ${DOMAIN_NAME:defaultDomain}
  framework: ${FRAMEWORK:springboot}
  
namespace:
  entity: ${BASE_PACKAGE:io.elasticore}.${DOMAIN_NAME:domain}.entity

8.2 조건부 설정​

config:
  mode: jpa,uml
  dev:
    mode: jpa,uml,java
  prod:
    mode: jpa

8.3 플러그인 설정​

config:
  plugins:
    swagger:
      enabled: true
      version: 3.0
    mapstruct:
      enabled: true
      componentModel: spring
    querydsl:
      enabled: true

8.4 Custom Interface 설정​

ElastiCORE는 SearchDTO에서 사용하는 Pageable과 SortableObject 인터페이스를 커스터마이징할 수 있습니다.

config:
  interface:
    pageable: "com.company.common.MyPageable"
    sortable: "com.company.common.MySortableObject"

기본 동작 (설정하지 않은 경우):

  • io.elasticore.springboot3.dto.PageableObject 자동 생성
  • io.elasticore.springboot3.dto.SortableObject 자동 생성

커스텀 인터페이스 사용 시:

  • 지정된 인터페이스를 import하여 사용
  • 기본 인터페이스 클래스는 생성하지 않음
  • SearchDTO에서 커스텀 인터페이스 타입 사용

사용 예시:

config:
  interface:
    pageable: "com.company.common.CustomPageable"
    sortable: "com.company.common.CustomSortable"

커스텀 인터페이스 구현 예시:

public interface CustomPageable {
    Pageable getPageable();
    void setPageable(Pageable pageable);
}

public interface CustomSortable {
    Sort getSort();
    void setSort(Sort sort);
}

활용 시나리오:

  • 기업 표준 인터페이스 사용
  • 기존 프로젝트와의 호환성 유지
  • 추가적인 페이징/정렬 기능 확장

9. 모범 사례​

9.1 도메인 분리​

  • 원칙: 각 도메인마다 독립적인 env.yml 유지
  • 네이밍: 도메인명은 비즈니스 의미가 명확한 이름 사용
  • 패키지: 도메인별로 독립적인 패키지 구조

9.2 환경별 설정​

# 개발용 설정
elasticore:
  enable: true
  config:
    domainName: ${DOMAIN_NAME:testDomain}
    mode: jpa,uml,java  # 개발시 모든 산출물 생성
    
# 운영용 설정  
elasticore:
  enable: true
  config:
    domainName: ${DOMAIN_NAME:prodDomain}
    mode: jpa          # 운영시 필요한 것만 생성

9.3 성능 최적화​

config:
  jpa:
    batchSize: 100
    fetchSize: 50
    useQueryMethod: false    # 불필요한 쿼리 메서드 생성 방지

10. 문제 해결 가이드​

10.1 활성화 문제​

elasticore:
  enable: true  # false인 경우 코드 생성이 비활성화됨

10.2 버전 호환성​

# Spring Boot 3.x 환경  
config:
  framework: springboot
  j2ee: jakarta

10.3 네임스페이스 충돌​

# 잘못된 예
namespace:
  entity: com.company.entity  # 너무 일반적
  
# 올바른 예
namespace:
  entity: com.company.order.entity  # 도메인별 분리

10.4 레거시 형식 지원​

# 구형식 (여전히 지원됨)
env:
  config:
    # 설정 내용

# 신형식 (권장)
elasticore:
  config:
    # 설정 내용

11. 설정 검증​

11.1 필수 항목 체크리스트​

  • domainName 설정
  • framework 지정
  • mode 선택
  • j2ee 스택 지정
  • 모든 필요한 namespace 정의

11.2 권장 설정 체크리스트​

  • lombok: true 설정 (코드 간소화)
  • 환경별 설정 분리
  • 의미있는 도메인명 사용
  • 일관된 패키지 네이밍

11.3 신규 기능 체크리스트​

  • testCode.enabled: true 설정 (자동 테스트 코드 생성)
  • 복합키 엔티티 테스트 검증
  • Custom Interface 활용 (필요시)
  • 테스트 커버리지 확인

11.4 테스트 관련 권장 사항​

  • 복합키 엔티티: 자동 생성되는 테스트 코드에서 복합키 처리 로직 확인
  • 샘플 데이터: 자동 생성되는 샘플 데이터가 비즈니스 로직에 적합한지 검토
  • 테스트 실행: ./gradlew test 명령으로 생성된 테스트 코드 정상 동작 확인
  • 커스터마이징: 필요시 생성된 테스트 코드를 비즈니스 요구사항에 맞게 수정