본문으로 건너뛰기

ElastiCORE Annotation Complete Guide

Overview​

Complete reference for all annotations used in ElastiCORE DSL with detailed usage and examples.

1. Entity Meta Annotation​

1.1 기본 엔티티 선언​

meta: entity
  • Description: 기본 JPA 엔티티로 선언
  • Generated Code: @Entity, @Table 포함

1.2 추상 엔티티​

meta: entity @abstract
  • Description: 상속 전용 추상 엔티티
  • Generated Code: abstract class로 생성
  • Usage: BaseEntity, AuditEntity 등 공통 필드 정의

1.3 엔티티 상속​

meta: entity @extend(ParentEntity)
  • Description: 부모 엔티티로부터 상속
  • Generated Code: extends ParentEntity
  • Example: 
    entity:
      AuditEntity:
        meta: entity @abstract @extend(BaseEntity)

1.4 REST API 노출​

meta: entity @expose
meta: entity @expose(pageSize)
  • Description: REST API로 노출하며 검색 DTO 자동 생성
  • Parameters: pageSize - 기본 페이지 크기
  • Default: 자동으로 검색 가능한 필드 생성 (string: like, datetime: between)
  • Generated Code: Entity, DTO, Repository, Service, Controller, SearchDTO 클래스 생성
  • Example: 
    Article:
      meta: entity @expose(50)  # 페이지당 50개 항목, 검색 DTO 생성
      fields:
        title: string(200)!     # 자동으로 like 검색 생성

1.5 서비스 레이어만 노출​

meta: entity @service
meta: entity @service(pageSize)
  • Description: Controller 없이 Service 레이어만 생성하며 검색 DTO 자동 생성
  • Parameters: pageSize - 기본 페이지 크기
  • Default: 자동으로 검색 가능한 필드 생성 (string: like, datetime: between)
  • Generated Code: Entity, DTO, Repository, Service, SearchDTO 클래스 생성 (Controller 제외)
  • Usage: 내부 서비스 로직에서만 사용하고 외부 REST API로 노출하지 않는 경우
  • Example: 
    InternalData:
      meta: entity @service(30)  # 페이지당 30개 항목, Controller 생성 안함
      fields:
        name: string(100)!
        value: string(500)

1.6 감사(Audit) 대상​

meta: entity @audited
  • Description: JPA Envers(dependency 설정필요) 를 통한 데이터 변경 이력 추적
  • Generated Code: @Audited 어노테이션 추가
  • Usage: 중요한 데이터의 변경 이력 관리

1.7 DTO 생성 표시​

meta: entity @dto
  • Description: 해당 엔티티에 대한 DTO 생성 가능 표시
  • Generated Code: 별도 DTO 클래스 생성

1.8 페이징 지원​

meta: entity @pageable
meta: entity @pageable(50)
  • Description: 페이징 처리 지원
  • Parameters: pageSize - 페이지당 항목 수
  • Default: 20
  • Generated Code: Pageable 매개변수를 받는 메서드 생성

1.9 임베디드 엔티티​

meta: entity @embeddable
  • Description: JPA Embeddable 엔티티로 선언
  • Generated Code: @Embeddable 어노테이션 추가
  • Usage: 주소, 좌표 등 값 객체

1.10 테이블명 지정​

meta: entity @table(tableName)
meta: entity @tbl(tableName)
  • Description: 데이터베이스 테이블명 명시적 지정
  • Parameters: name - 테이블명
  • Default: 엔티티명을 snake_case로 변환 (예: UserInfo → user_info)
  • Generated Code: @Table(name = "tableName")
  • Example: 
    Address:
      meta: entity @embeddable @table(customer_address)

    # 기본값 사용 예시 (UserProfile → user_profile 테이블)
    UserProfile:
      meta: entity

1.11 인덱스 정의​

meta: entity @Index(name="idx_name", columnList="col1,col2")
meta: entity @Index(name="idx_name", columnList="col1,col2", unique=true)
meta: entity @idx(name="idx_name", columnList="col1,col2")
  • Description: 데이터베이스 인덱스 정의
  • Parameters:
    • name: 인덱스명 (선택사항)
    • columnList: 컬럼 목록 (필수)
    • unique: 유니크 제약조건 (선택사항)
  • Default: unique=false
  • Generated Code: @Table 내 indexes 속성 추가
  • Example: 
    Message:
      meta: entity @Index(name="idx_msg_create_date", columnList="create_date")

    User:
      meta: entity @Index(name="idx_user_email", columnList="email", unique=true)

2. Field Annotations​

2.1 기본키 어노테이션​

@id​

fieldName: type @id
  • Description: JPA 기본키 지정
  • Generated Code: @Id

@sequence​

fieldName: long @id @sequence
  • Description: 자동 증가 시퀀스
  • Generated Code: @GeneratedValue(strategy = GenerationType.IDENTITY)

@genid​

fieldName: string @id @genid
  • Description: 사용자 정의 ID 생성기 사용
  • Generated Code: env.yml의 genid 설정 참조
  • 환경 설정: 
    annotations:
      genid: "genid(io.elasticore.springboot3.util.IdUtils.newId)"

2.2 데이터 제약 어노테이션​

@length(n) / @len(n) / @size(n) - 문자열 길이 제한 및 JPA Column 생성​

  • (중요) 타입(길이)와 같은 방식을 우선 최우선으로 사용. ex) string(10)
# 단순 길이 지정 (기존 방식)
fieldName: string(255)
fieldName: string @len(255)
fieldName: string @size(100)

# 복합 길이 매개변수 (최소/최대 동시 지정) - 최신 기능
title: string @size(min=5, max=200)             # 제목 (별칭 사용)

Description: 문자열 필드의 길이 제한을 설정하며 JPA Column과 Bean Validation을 자동 생성

Parameter Format:

  • 단순 매개변수: @length(50) - 최대 길이만 지정
  • 복합 매개변수: @length(min=3, max=50) - 최소/최대 길이 동시 지정
  • 별칭 지원: @len, @size 동일 기능

Compound Parameter Processing (최신 개선):

  • JPA Column: 항상 max 값을 length 속성으로 사용
  • Bean Validation: min, max 모두 @Size 어노테이션에 적용
  • 별칭 처리: length, len, size 모든 별칭에서 동일하게 작동
  • 타입 인식: Annotation.TYPE_KEY_VALUE와 TYPE_SINGLE_VALUE 자동 구분

@default(value) - 필드 기본값 설정 및 스마트 인용부호 처리​

# 불린 및 숫자 기본값
fieldName: boolean @default(true)
salary: double @default(0)
point: int @default(100)

# 문자열 기본값 - 스마트 인용부호 처리 (최신 개선 기능)
status: string @default("ACTIVE")           # 큰따옴표 - 그대로 유지
category: string @default('GENERAL')        # 작은따옴표 - 큰따옴표로 자동 변환
archiveStatus: string @default(COMPLETED)   # 인용부호 없음 - 자동 추가

# Enumeration 및 특수 기본값
processType: ProcessType @default(ProcessType.HANG)
indicator: Indicator @default(Indicator.YES)

@updatable(false)​

fieldName: datetime @updatable(false)
  • Description: 수정 불가능 필드
  • Generated Code: @Column(updatable = false)

@notnull​

fieldName: string @notnull
  • Description: NOT NULL 제약 조건
  • Generated Code: @Column(nullable = false)

2.3 검색 어노테이션​

@search(condition) / @searchable / @s / @srch / @filter​

ElastiCORE는 다양한 검색 조건을 지원하며, 각 조건별로 최적화된 쿼리와 SearchDTO 필드를 자동 생성합니다.

1. LIKE 검색 (@search(like))​
title: string @search(like)
productName: string @s(like)
  • Usage: 문자열 부분 일치 검색
  • 생성 쿼리: WHERE LOWER(title) LIKE LOWER('%검색어%')
  • SearchDTO 필드: title: string (단일 입력 필드)
2. 정확 일치 검색 (@search(eq))​
empNo: string @search(eq)
status: string @search(eq)
categoryId: long @search(eq)
  • Usage: 정확한 값 일치 검색
  • 생성 쿼리: WHERE empNo = :empNo
3. 범위 검색 (@search(between))​
createDate: datetime @search(between)
salary: double @search(between)
age: int @search(between)
  • Usage: 날짜나 숫자의 범위 검색
  • 생성 쿼리: WHERE createDate BETWEEN :createDateFrom AND :createDateTo
  • SearchDTO 필드:
    • createDateFrom: datetime (시작값)
    • createDateTo: datetime (종료값)
4. IN 검색 (@search(in))​
boardType: List<BoardType> @search(in)
categories: List<string> @search(in)
  • Usage: 여러 값 중 하나라도 일치하는 검색
  • 생성 쿼리: WHERE boardType IN (:boardTypeList)
5. 대소비교 검색 (@search(gt), @search(lt), @search(gte), @search(lte))​
price: double @search(gte)         # 이상
maxPrice: double @search(lte)      # 이하
minAge: int @search(gt)            # 초과
score: double @search(lt)          # 미만
  • Usage: 숫자/날짜 대소 비교
  • 생성 쿼리:
    • gte: WHERE price >= :price
    • lte: WHERE price <= :price
    • gt: WHERE price > :price
    • lt: WHERE price < :price
6. NULL 검색 (@search(null), @search(notnull))​
description: string @search(null)
lastLogin: datetime @search(notnull)
  • Usage: NULL 값 존재 여부 검색
7. 별칭 사용 및 조합​
name: string @s(like)              # @search와 동일
status: string @srch(eq)           # @search와 동일  
category: string @filter(in)       # @search와 동일
8. 기본값 동작 (자동 선택)​
title: string                      # 자동으로 @search(like) 적용
createDate: datetime               # 자동으로 @search(between) 적용
status: StatusEnum                 # 자동으로 @search(eq) 적용
tags: List<string>                 # 자동으로 @search(in) 적용
9. 생성되는 SearchDTO 예시​
# 원본 엔티티
entity:
  Product:
    meta: entity @expose(20)
    fields:
      productId: long @id @sequence
      name: string(200)! @search(like)
      price: double @search(between)
      category: CategoryEnum @search(in)
      createDate: datetime @search(between)
      isActive: boolean @search(eq)

# 자동 생성되는 SearchDTO
dto:
  ProductSearchDTO:
    fields:
      name: string                        # 부분 일치 검색
      priceFrom: double                   # 가격 최소값
      priceTo: double                     # 가격 최대값
      createDateFrom: datetime            # 생성일 시작
      createDateTo: datetime              # 생성일 종료
      category: List<CategoryEnum>        # 카테고리 다중 선택
      isActive: boolean                   # 활성 상태
      pageNumber: int                     # 기본값: 0
      pageSize: int                       # 기본값: 20
      sortCode: string                    # 정렬 필드
10. 검색 조건 조합 활용​
entity:
  Order:
    meta: entity @expose(30)
    fields:
      orderNo: string(20) @search(eq)        # 주문번호 정확 검색
      customerName: string @search(like)     # 고객명 부분 검색  
      orderDate: datetime @search(between)   # 주문일 범위 검색
      status: OrderStatus @search(in)        # 상태 다중 선택
      amount: double @search(gte)            # 금액 이상 검색
      isPaid: boolean @search(eq)            # 결제여부 정확 검색

2.4 참조 어노테이션​

@ref(fieldPath)​

boardName: string @ref(board.name)          # 단순 참조
boardTypeName: string @ref(board.boardType.name)  # 중첩 참조
  • Description: 다른 엔티티의 필드 참조
  • Usage: DTO에서 관련 엔티티의 필드값 가져오기

@dtype(type)​

articles: List<Article> @dtype(List<ArticleDTO>)
  • Description: DTO 전환시 DTO에서 사용할 타입 명시
  • Usage: 순환 참조 방지 및 타입 안전성

2.5 JPA 관계 어노테이션​

@OneToMany​

articles: List<Article> @dtype(List<ArticleDTO>) @OneToMany(mappedBy="board")
  • Generated Code: @OneToMany(mappedBy = "board")

@ManyToOne​

board: Board @ManyToOne
  • Generated Code: @ManyToOne

@ManyToMany​

roles: List<Role> @ManyToMany
users: List<User> @ManyToMany(mappedBy="roles")
  • Generated Code: @ManyToMany

@OneToOne​

profile: UserProfile @OneToOne
  • Generated Code: @OneToOne

@Embedded​

address: Address @Embedded
coordinates: Location @Embedded
  • Description: JPA Embeddable 객체 임베딩
  • Generated Code: @Embedded
  • Example: 
    User:
      fields:
        personalInfo: PersonalInfo @Embedded
        homeAddress: Address @Embedded
        workAddress: Address @Embedded

@cascade(type)​

parameters: List<ParamInfo> @ManyToMany @cascade(ALL)
parts: List<CarPart> @cascade(PERSIST)
  • Types: ALL, PERSIST, MERGE, REMOVE
  • Generated Code: cascade = CascadeType.ALL

@relation(mappedBy="fieldName")​

address: Address @relation(mappedBy="market_post_id")
  • Description: 양방향 관계에서 주인이 아닌 쪽 지정

2.6 JPA 컬럼 매핑​

@Column / @col / @db​

postNo: string(5) @Column(name="post_no", length=5)
carYear: Integer @Column(name="car_year")
username: string @col(unique=true)
email: string @db(name="email_addr", length=100)
  • Parameters:
    • name: 컬럼명
    • length: 컬럼 길이
    • unique: 유니크 제약조건
    • nullable: NULL 허용 여부
  • Default:
    • name: 필드명을 snake_case로 변환 (예: userName → user_name)
    • length: 필드 타입에서 지정한 길이 또는 기본값
    • unique: false
    • nullable: true

2.7 필드 검증 어노테이션​

@pattern​

email: string @pattern(regexp="^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$", message="유효한 이메일 주소를 입력하세요")
phoneNumber: string @pattern(regexp="^\\d{3}-\\d{4}-\\d{4}$", message="전화번호 형식은 000-0000-0000 입니다")
  • Description: Bean Validation의 @Pattern 어노테이션 자동 생성
  • Parameters:
    • regexp: 정규식 패턴 (필수)
    • message: 검증 실패 시 오류 메시지 (필수)
  • 프레임워크 호환성: Jakarta/Javax 패키지 자동 선택 (env.yml의 j2ee 설정에 따름)
  • 생성되는 Java 코드: 
    @javax.validation.constraints.Pattern(
      regexp="^[a-zA-Z0-9_]{3,50}$",
      msg="사용자명은 3-50자의 영문, 숫자, 언더스코어만 가능합니다"
    )
    private String username;

@min / @max - 숫자 범위 검증 및 Bean Validation 생성​

age: int @min(18) @max(65)
salary: double @min(0) @max(1000000)
price: double @min(0.01) @max(999999.99)
quantity: int @min(0) @max(999999)

Description: 숫자 타입 필드의 값 범위를 제한하고 Bean Validation 어노테이션을 자동 생성

Parameters and Applicable Types:

  • @min(값): 허용되는 최솟값 (포함)
  • @max(값): 허용되는 최댓값 (포함)
  • 적용 타입: int, long, double, float, BigDecimal, BigInteger

Auto-generated Code:

@Min(18)
@Max(65)
private Integer age;

@DecimalMin("0")
@DecimalMax("1000000")
private BigDecimal salary;

@Size와의 구분:

  • @min/@max: 숫자 값의 범위 제한 (예: 나이 18~65세)
  • @minsize/@length: 문자열이나 컬렉션의 크기 제한 (예: 문자열 길이 3~50자)

2.9 커스텀 기능 어노테이션​

@function.get​

fullName: string @function.get("getFullName")
displayName: string @function.get("generateDisplayName")
  • Description: 필드의 커스텀 Getter 메서드 지정

@function.set​

password: string @function.set("setEncryptedPassword")
email: string @function.set("setNormalizedEmail")
  • Description: 필드의 커스텀 Setter 메서드 지정

2.10 Spring Data JPA 감사 어노테이션​

@jpa:CreatedDate​

createDate: datetime @jpa:org.springframework.data.annotation.CreatedDate
  • Generated Code: @CreatedDate

@jpa:CreatedBy​

createdBy: string(20) @jpa:org.springframework.data.annotation.CreatedBy
  • Generated Code: @CreatedBy

@jpa:LastModifiedDate​

lastModifiedDate: datetime @jpa:org.springframework.data.annotation.LastModifiedDate
  • Generated Code: @LastModifiedDate

@jpa:LastModifiedBy​

lastModifiedBy: string(20) @jpa:org.springframework.data.annotation.LastModifiedBy
  • Generated Code: @LastModifiedBy

2.11 감사 제외​

@notaudited​

temporaryData: string @notaudited
  • Generated Code: @NotAudited

2.12 환경 설정 참조​

@env:annotationName​

coordinates: int[] @env:integerarray
tags: string[] @env:stringarray
userId: string @env:genid
  • Description: env.yml의 annotations 설정 참조
  • Usage: 재사용 가능한 커스텀 어노테이션

3. DTO 어노테이션​

3.1 템플릿 기반 DTO​

dto:
  ArticleDTO:
    meta: dto @template(Article)
    fields:
      createDate: --  # 필드 제외
  • @template(EntityName): 기반 엔티티 지정, 또는 참조하는 다른 template 정의를 그대로 복사되어 필드 정보가 그대로 복사된다.
  • --: 템플릿에서 상속받은 특정 필드 제외

3.2 검색 DTO​

dto:
  ArticleSearchDTO:
    meta: dto @searchable(entity=Article, pageSize=50)
    # 또는
    meta: dto @searchable(entity=Article, pageSize=50, pageable=true)
  • @searchable: 검색 전용 DTO 생성
  • Parameters:
    • entity: 대상 엔티티명 (필수)
    • pageSize: 페이지 크기 (기본값: 100)
    • pageable: 페이징 활성화 여부 (기본값: true)
  • 생성 필드:
    • pageNumber: 페이지 번호 (기본값: 0)
    • pageSize: 페이지 크기 (설정한 값)
    • sortCode: 정렬 필드명

3.3 다중 템플릿 상속​

dto:
  CarProfileInfoDTO:
    meta: dto @template(CarProfileDTO,CarInfoDTO)
  • Description: 여러 DTO를 조합하여 새로운 DTO 생성

3.4 JSON 관련 어노테이션​

@json / @jsonproperty​

userName: string @json("user_name")
fullName: string @jsonproperty("full_name")
createDate: datetime @json("created_at")
  • Description: JSON 직렬화/역직렬화시 사용할 프로퍼티명 지정
  • Generated Code: @JsonProperty("property_name")

@jsonSerialize​

amount: BigDecimal @jsonSerialize(using=com.example.MoneySerializer)
  • Description: 커스텀 JSON 직렬화기 클래스 지정
  • Generated Code: @JsonSerialize(using = CustomSerializer.class)

@jsoninclude / @includejson​

optionalField: string @jsoninclude
description: string @includejson
  • Description: JSON 직렬화에 포함될 조건 설정

3.5 검색 관련 어노테이션​

@searchBypass​

dto:
  UserDTO:
    fields:
      internalId: string @searchBypass
      tempData: string @searchBypass
  • Description: 검색 DTO 생성 시 해당 필드를 검색 조건에서 제외

4. Enumeration Annotations​

4.1 기본 열거형​

enumeration:
  BoardType:
    meta: enum @db(code) @json(code)
  • @db(fieldName): 데이터베이스 저장 필드
  • @json(fieldName): JSON 직렬화 필드

4.2 필드 제약​

enumeration:
  BoardType:
    fields:
      code: string(2)  # 최대 길이 제한

5. Port Annotations​

5.1 데이터베이스 포트​

port:
  BoardService:
    meta: dbms @datasource("main")
  • dbms: 데이터베이스 직접 연동
  • @datasource(name): 데이터소스 지정

5.2 HTTP 포트​

port:
  ExternalApiPort:
    meta: http @url("https://api.example.com")
  • http: HTTP API 연동
  • @url(baseUrl): 기본 URL 지정

5.3 인증 설정​

port:
  SecureApiPort:
    meta: http @url("https://api.example.com") @auth(API-KEY-123)
  • @auth(credentials): 인증 정보

5.4 HTTP 메서드 어노테이션​

methods:
  getUserInfo:
    meta: method @get("/users/{userId}")
  createUser:
    meta: method @post("/users")
  updateUser:
    meta: method @put("/users/{userId}")
  deleteUser:
    meta: method @delete("/users/{userId}")
  • 지원 메서드: @get, @post, @put, @delete, @patch

5.5 HTTP 엔드포인트​

methods:
  complexMethod:
    meta: method @HttpEndpoint(url="/api/complex", method="POST")
    params:
      body: RequestData @body
  • @HttpEndpoint: 상세한 HTTP 설정
  • @body: 요청 본문 매개변수

6. 프로토콜 버퍼 어노테이션​

6.1 gRPC 서비스​

service:
  UserService:
    meta: proto @server @client
  • proto: Protocol Buffer 기반
  • @server: gRPC 서버 코드 생성
  • @client: gRPC 클라이언트 코드 생성

7. 복합 어노테이션 예시​

7.1 완전한 엔티티 정의 - 최신 기능 활용 예시​

entity:
  User:
    meta: entity @expose(20) @audited @Index(name="idx_user_email", columnList="email")
    fields:
      userId: long @id @sequence
      username: string(50) @search(like) @default("new_user") @pattern(regexp="^[a-zA-Z0-9_]{3,50}$", message="사용자명은 3-50자의 영문, 숫자, 언더스코어만 가능합니다")
      email: string(150) @search(eq) @Column(unique=true) @pattern(regexp="^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$", message="유효한 이메일 주소를 입력하세요")
      password: string(255) @minsize(8) @function.set("setEncryptedPassword") @default('temporary123')
      displayName: string(100) @function.get("generateDisplayName")
      firstName: string(50) @default('이름')
      lastName: string(50) @default(성씨)
      status: UserStatus @default(UserStatus.ACTIVE)
      isActive: boolean @default(true)
      isEmailVerified: boolean @default(false)
      roles: List<Role> @dtype(List<RoleDTO>) @ManyToMany @cascade(ALL)
      personalInfo: PersonalInfo @Embedded
      createdDate: datetime @updatable(false) @jpa:org.springframework.data.annotation.CreatedDate @default(now())
      lastModifiedDate: datetime @jpa:org.springframework.data.annotation.LastModifiedDate
      lastLoginDate: datetime @search(between)
      registrationIp: string(4%) @default("127.0.0.1")
      profile: UserProfile @OneToOne @cascade(ALL)

7.2 감사 기반 엔티티 - 최신 기능 활용​

entity:
  AuditableEntity:
    meta: entity @abstract @audited
    fields:
      createdDate: datetime @updatable(false) @jpa:org.springframework.data.annotation.CreatedDate
      createdBy: string(20) @updatable(false) @jpa:org.springframework.data.annotation.CreatedBy
      lastModifiedDate: datetime @jpa:org.springframework.data.annotation.LastModifiedDate
      lastModifiedBy: string(20) @jpa:org.springframework.data.annotation.LastModifiedBy
      version: long @Column(name="version_no") @Version

7.3 복합 검색 DTO - 고급 검색 기능 활용​

dto:
  UserSearchDTO:
    meta: dto @searchable(entity=User, pageSize=25, pageable=true)
    fields:
      creditScore: int @search(between) @min(300) @max(850)
      statusList: List<UserStatus> @search(in)
      roles: List<Role> @search(in)
      isActive: boolean @search(eq)
      isEmailVerified: boolean @search(eq)
      createdDate: datetime @search(between)

7.4 JSON 및 DTO 종합 예시​

dto:
  UserResponseDTO:
    meta: dto @template(User)
    fields:
      userId: long @searchBypass
      userName: string(50) @json("user_name")
      emailAddress: string(150) @jsonproperty("email")
      displayName: string @function.get("generateDisplayName") @default("사용자")
      firstName: string @json("first_name") @default('이름')
      fullName: string @json("full_name") @default(전체이름)

8. 파라미터 처리 패턴​

8.1 점 표기법 (Dot Notation)​

ElastiCORE는 어노테이션 파라미터 접근에 점 표기법을 사용합니다:

meta: dto @searchable(entity=User, pageSize=50, pageable=true)

# 내부 처리:
# searchable.entity → "User"
# searchable.pageSize → "50"  
# searchable.pageable → "true"

8.2 기본값 처리 로직​

// 코드 예시: @pageable 어노테이션 처리
String pageSizeVal = metaInfo.getMetaAnnotationValue("pageable");
if(pageSizeVal == null)
    pageSizeVal = "20";  // 기본값 적용

8.3 파라미터 검증​

  • 숫자 파라미터는 파싱 실패 시 기본값 사용
  • 필수 파라미터 누락 시 컴파일 오류 발생
  • 타입 불일치 시 기본값으로 대체

9. 주의사항 및 모범 사례​

9.1 어노테이션 순서​

  • 메타 어노테이션이 먼저 오고, 필드별 어노테이션이 뒤에 옴
  • 관련성 있는 어노테이션끼리 그룹화

9.2 성능 고려사항​

  • @search 어노테이션 사용 시 적절한 인덱스 설정
  • @cascade(ALL) 사용 시 성능 영향 고려
  • 큰 컬렉션에는 @expose 페이지 크기 조정
  • @pageable 기본값(20)보다 큰 값 사용 시 메모리 사용량 고려

9.3 데이터 일관성​

  • 양방향 관계 설정 시 @relation(mappedBy) 올바르게 사용
  • @updatable(false)와 감사 어노테이션 조합 활용
  • @Column 매개변수와 필드 타입 길이 일치 확인

9.4 기본값 활용​

  • @table 어노테이션: 엔티티명 → snake_case 자동 변환
  • @Column 어노테이션: 필드명 → snake_case 자동 변환
  • @search 어노테이션: 필드 타입별 최적 검색 조건 자동 선택

9.5 보안 고려사항​

  • 민감한 필드는 @notaudited 사용 고려
  • API 노출 시 @expose 페이지 크기 적절히 제한
  • @searchable 사용 시 과도한 pageSize 설정 주의