김신건의 로그 - 위키 / spring

[JPA] fetch join: JOIN FETCH 로 연관 entity 즉시 로드

koa (김신건) — Thu, 02 Jul 2026 00:00:00 GMT

정의

fetch join 은 JPQL 에서 연관 entity 를 한 번의 SQL 로 함께 로드하는 문법. JOIN FETCH 로 선언한다.

SELECT p FROM Post p JOIN FETCH p.author

일반 JOIN 은 SQL JOIN 만 수행하고 결과 entity 만 반환한다. JOIN FETCH 는 JOIN 을 수행하면서 연관 entity 를 함께 로드해 [[spring-jpa-persistence-context|영속성 컨텍스트]] 에 등록한다. 이후 lazy proxy 접근 없이 필드 사용이 가능하다.

주된 목적은 [[n-plus-one-problem|N+1 쿼리 문제]] 해결이다. 매핑 자체는 LAZY 로 두고, 필요한 쿼리에서만 명시적으로 함께 가져오는 패턴.

관련 개념 정리는 [[spring-jpa-fetch-type]] 참고. FetchType.LAZY/EAGER 의 기본 동작과 EntityGraph, @BatchSize 대안은 그 페이지에서 다룬다.

시각화

{}

LAZY 만 사용 시 N+1 발생, JOIN FETCH 로 1쿼리에 해결하는 흐름.

기본 문법

INNER JOIN FETCH

List<Post> posts = em.createQuery("""
    SELECT p
    FROM Post p
    JOIN FETCH p.author
""", Post.class).getResultList();

발생 SQL:

INNER JOIN 이므로 author 가 없는 Post 는 결과에서 제외된다.

LEFT JOIN FETCH (LEFT OUTER JOIN FETCH)

FK 가 null 인 row 도 포함:

SELECT p FROM Post p LEFT JOIN FETCH p.author

발생 SQL 은 LEFT OUTER JOIN. author 가 없는 Post 는 author = null 로 채워져 반환된다.

optional 연관 (@ManyToOne(optional = true), nullable FK) 은 대부분 LEFT JOIN FETCH 가 안전하다.

fetch join 이 하는 일

Hibernate 관점에서 JOIN FETCH p.author 는 두 단계를 한 번에 처리:

SQL JOIN: INNER JOIN user a ON p.author_id = a.id
연관 entity 초기화: 조회된 author 를 즉시 영속성 컨텍스트에 로드하고 Post.author 필드에 세팅

이 결과:

post.getAuthor() 호출 시 lazy proxy 초기화 SELECT 가 발생하지 않는다
트랜잭션이 끝난 뒤 (detached 상태에서) 접근해도 LazyInitializationException 이 발생하지 않는다

JOIN vs JOIN FETCH 차이

-- (1) 일반 JOIN
SELECT p FROM Post p JOIN p.author a WHERE a.name = :name

-- (2) JOIN FETCH
SELECT p FROM Post p JOIN FETCH p.author WHERE p.author.name = :name

항목	JOIN	JOIN FETCH
SQL	`INNER JOIN`	`INNER JOIN` (동일)
SELECT 대상	조인 대상 컬럼 안 가져옴	조인 대상 컬럼 모두 가져옴
연관 entity 초기화	❌ (여전히 lazy proxy)	✅ (managed entity)
후속 lazy 초기화	있음 (N+1 가능)	없음
반환 타입	명시 대상만	명시 대상만 (author 는 내부 로딩)

일반 JOIN 은 WHERE 조건용, JOIN FETCH 는 조회 + 초기화용. 조건과 초기화를 모두 원하면 두 개를 조합할 수도 있다.

SELECT p
FROM Post p
JOIN FETCH p.author a
WHERE a.email LIKE :domain

같은 관계에 JOIN FETCH 한 번이면 조건도 걸 수 있다 (implicit alias 활용).

컬렉션 fetch join 과 카르테시안 곱

@OneToMany / @ManyToMany 컬렉션을 fetch join 하면 row 가 곱해진다.

@Entity
class Post {
    @Id Long id;
    @OneToMany(mappedBy = "post", fetch = FetchType.LAZY)
    List<Comment> comments = new ArrayList<>();
}

SELECT p FROM Post p JOIN FETCH p.comments

Hibernate 는 카르테시안 곱으로 부풀어난 row 를 그대로 넘긴다. 결과 List 에 같은 Post 인스턴스가 여러 번 등장한다. (인스턴스는 동일하다. == 비교는 true 다. 1차 캐시 덕분.)

DISTINCT 로 해결

SELECT DISTINCT p FROM Post p JOIN FETCH p.comments

Hibernate 는 두 곳에서 dedup 한다:

SQL 에 DISTINCT 붙임 (실제로는 대부분 무의미, Post 컬럼이 같아도 comment 컬럼이 다르니 SQL DISTINCT 로는 안 걸러짐)
결과 List 에서 같은 id 의 Post 인스턴스 제거 (핵심 동작)

Hibernate 6+ 는 SQL DISTINCT 를 기본으로 생략한다 (hibernate.query.passDistinctThrough=false 와 동일). 애초에 SQL 성능 문제라서 자동 회피.

hibernate.query.passDistinctThrough

spring:
  jpa:
    properties:
      hibernate:
        query.passDistinctThrough: false   # (Hibernate 5) SQL DISTINCT 생략

Hibernate 5 에서 fetch join + DISTINCT 성능 개선용. Hibernate 6+ 는 기본값이 false 라 신경 쓸 필요 없음.

MultipleBagFetchException

두 개 이상의 List (bag) 를 동시에 JOIN FETCH 하면 Hibernate 가 카르테시안 곱을 감당 못 해 예외를 던진다.

@Entity
class Post {
    @OneToMany(mappedBy = "post") List<Comment> comments;
    @OneToMany(mappedBy = "post") List<Tag> tags;
}

SELECT p FROM Post p
JOIN FETCH p.comments
JOIN FETCH p.tags     -- ❌ MultipleBagFetchException

이유: Post 3개, comment 5개, tag 4개면 카르테시안 곱은 3 * 5 * 4 = 60 row. 두 컬렉션의 index 를 잃어버려 dedup 순서를 보장할 수 없음.

해결 1: 하나만 `Set` 으로 변경

@OneToMany(mappedBy = "post") Set<Comment> comments;
@OneToMany(mappedBy = "post") List<Tag> tags;   // List 하나만 남김

Set 은 order 보장이 없어 Hibernate 가 다르게 다룬다. bag 은 List 만 해당.

해결 2: 하나만 fetch join, 나머지는 `@BatchSize` / EntityGraph

SELECT p FROM Post p JOIN FETCH p.comments

Tag 는 @BatchSize(size = 100) 나 별도 조회.

이게 실무에서 가장 흔한 패턴. 자세히는 [[spring-jpa-fetch-type#@BatchSize (Hibernate 확장)|@BatchSize 항목]] 참고.

해결 3: 두 단계 쿼리

// 1) posts 만 조회
List<Post> posts = em.createQuery("SELECT p FROM Post p", Post.class).getResultList();
List<Long> ids = posts.stream().map(Post::getId).toList();

// 2) 각 컬렉션 별도 IN 쿼리 (Hibernate 가 1차 캐시로 자동 매칭)
em.createQuery("SELECT p FROM Post p JOIN FETCH p.comments WHERE p.id IN :ids", Post.class)
  .setParameter("ids", ids).getResultList();

em.createQuery("SELECT p FROM Post p JOIN FETCH p.tags WHERE p.id IN :ids", Post.class)
  .setParameter("ids", ids).getResultList();

같은 트랜잭션 안에서 [[spring-jpa-persistence-context|영속성 컨텍스트]] 가 동일한 Post 인스턴스에 comments 와 tags 를 각각 채워준다.

Pageable + 컬렉션 fetch join = in-memory paging

Spring Data JPA 의 Pageable 을 컬렉션 fetch join 과 조합하면 Hibernate 가 경고 후 메모리에서 페이징한다.

@Query("SELECT p FROM Post p JOIN FETCH p.comments")
Page<Post> findAllWithComments(Pageable pageable);

로그:

HHH000104: firstResult/maxResults specified with collection fetch;
           applying in memory!

Hibernate 가 전체 row 를 메모리에 로드 후 잘라낸다. Post 100만 건 + comment 각 10개면 1천만 row 를 JVM 힙에 올린 뒤 잘라낸다. OOM 위험이 매우 크다.

해결 패턴 (2 단계 fetch)

// 1) id 만 paging (join fetch 없이)
@Query("SELECT p.id FROM Post p ORDER BY p.createdAt DESC")
Page<Long> findPostIds(Pageable pageable);

// 2) 그 id 들만 fetch join 으로 컬렉션 로드
@Query("SELECT p FROM Post p JOIN FETCH p.comments WHERE p.id IN :ids")
List<Post> findWithCommentsByIds(@Param("ids") List<Long> ids);

두 단계로 나누면 정확한 SQL LIMIT 이 걸린다.

컬렉션 아닌 fetch join 은 OK

@ManyToOne / @OneToOne 은 row 가 곱해지지 않으므로 Pageable 과 함께 사용해도 SQL 페이징이 정상 적용된다.

@Query("SELECT p FROM Post p JOIN FETCH p.author")
Page<Post> findAll(Pageable pageable);   // OK: LIMIT 정상 적용

Nested fetch join (여러 depth)

연쇄 fetch join 가능:

SELECT p
FROM Post p
JOIN FETCH p.author a
JOIN FETCH a.profile pr

Post + author + profile 을 한 쿼리에 로드. 3개 테이블 INNER JOIN.

주의:

단일 연관 (ToOne) 이 이어질 때는 무방
중간에 컬렉션이 껴 있으면 카르테시안 곱 폭발

-- ⚠️ 위험
SELECT p FROM Post p
JOIN FETCH p.comments c
JOIN FETCH c.author       -- comment 마다 author, row 곱해짐

정말 필요하다면 별도 조회로 분리하거나 EntityGraph 로 명시적으로 depth 제한.

Spring Data JPA @Query 통합

public interface PostRepository extends JpaRepository<Post, Long> {
    // 단일 fetch join
    @Query("SELECT p FROM Post p JOIN FETCH p.author WHERE p.id = :id")
    Optional<Post> findByIdWithAuthor(@Param("id") Long id);

    // countQuery 필수 (fetch join 은 count 만들 때 문제)
    @Query(
        value = "SELECT p FROM Post p LEFT JOIN FETCH p.author",
        countQuery = "SELECT COUNT(p) FROM Post p"
    )
    Page<Post> findAllWithAuthor(Pageable pageable);

    // 컬렉션 + DISTINCT
    @Query("SELECT DISTINCT p FROM Post p LEFT JOIN FETCH p.comments WHERE p.id IN :ids")
    List<Post> findAllWithCommentsByIds(@Param("ids") List<Long> ids);
}

countQuery 를 반드시 지정해야 하는 이유: Spring 이 자동 생성하는 count 쿼리에 JOIN FETCH 가 남으면 SQL syntax error (SELECT COUNT(p) FROM Post p JOIN FETCH p.author 는 표준 위반).

fetch join 이 적용되지 않는 경우

1. Native query

@Query(value = "SELECT * FROM post JOIN user ON ...", nativeQuery = true)

JOIN FETCH 는 JPQL 문법이라 native query 에는 없다. Native 는 그냥 SQL JOIN 이라 연관 초기화가 안 된다.

2. `@Modifying` UPDATE / DELETE

Bulk 쿼리는 [[spring-jpa-persistence-context|영속성 컨텍스트]] 를 우회하므로 fetch join 이 의미 없다.

3. Cross join

JPA 표준은 카르테시안 곱 명시적 cross join 을 fetch 로 표현 못 한다.

실전 패턴

패턴 1: 단건 상세 조회

@Query("""
    SELECT p FROM Post p
    LEFT JOIN FETCH p.author
    LEFT JOIN FETCH p.category
    WHERE p.id = :id
""")
Optional<Post> findDetail(@Param("id") Long id);

ToOne 두 개까지는 fetch join 안정적. 상세 페이지 최적화.

패턴 2: 목록 + 요약 정보

@Query("""
    SELECT p FROM Post p
    JOIN FETCH p.author
    WHERE p.status = 'PUBLISHED'
    ORDER BY p.publishedAt DESC
""")
Page<Post> findPublishedList(Pageable pageable);

목록에서 필요한 ToOne 관계만 fetch join. 댓글 등 컬렉션은 상세에서만 로드.

패턴 3: 컬렉션 + Pageable (2 단계)

@Query("SELECT p.id FROM Post p ORDER BY p.publishedAt DESC")
Page<Long> findIds(Pageable pageable);

@Query("""
    SELECT DISTINCT p FROM Post p
    LEFT JOIN FETCH p.comments
    WHERE p.id IN :ids
""")
List<Post> findWithComments(@Param("ids") List<Long> ids);

// 사용
Page<Long> ids = repo.findIds(pageable);
List<Post> posts = repo.findWithComments(ids.getContent());

메모리 페이징 우회 + 정확한 SQL LIMIT.

fetch join vs 대안 요약

상황	추천	이유
ToOne 단건 상세	fetch join	단순, 1 쿼리
ToOne 목록 + Pageable	fetch join	row 안 곱해져 SQL LIMIT OK
컬렉션 1 개 + 목록	`@EntityGraph` + DISTINCT	선언적
컬렉션 1 개 + Pageable	2 단계 (id → in)	in-memory paging 회피
컬렉션 2 개 이상	`@BatchSize` 또는 분리 fetch	MultipleBagFetchException 회피
조건에 따라 다름	ad-hoc `@EntityGraph(attributePaths=...)`	쿼리마다 결정

함정과 베스트 프랙티스

DISTINCT 는 필수 (컬렉션 fetch join): dedup 없으면 List 중복
Pageable + 컬렉션 fetch join 금지: in-memory paging → OOM 위험
countQuery 명시 (Spring Data JPA Page 반환 시)
컬렉션 2 개 이상 동시 fetch join 금지: MultipleBagFetchException
Set 으로 바꾸면 우회 가능하지만 순서 보장 사라짐: 도메인 요구사항에 따라 선택
Nested fetch join 은 ToOne 만 안전: ToMany 가 껴 있으면 row 폭발
Native query 는 fetch join 없음: 관계 초기화하려면 별도 조회 필요
WHERE p.author.name = ... 대신 명시 alias 로 조건: WHERE a.name = ..., 실수 방지
implicit path 로 부주의하게 조건 걸면 unnecessary JOIN 추가 발생 가능

[JPA] FetchType: LAZY vs EAGER, N+1, fetch join

koa (김신건) — Thu, 02 Jul 2026 00:00:00 GMT

정의

FetchType 은 JPA 가 연관 entity 를 언제 로드할지 결정하는 hint.

EAGER: entity 로딩 시 즉시 함께 SELECT
LAZY: 실제 사용 시점 (proxy 메서드 호출) 까지 미룸

기본값:

@OneToOne, @ManyToOne: EAGER (위험)
@OneToMany, @ManyToMany: LAZY

규칙: 모든 연관관계는 명시적으로 LAZY. EAGER 는 [[n-plus-one-problem|N+1]] 폭탄의 시작. spring-data-jpa 의 ## 관계와 fetch 가 개요라면, 이 페이지는 FetchType 매핑 자체와 해결 도구 개요를 다룬다. 개별 도구 상세는 [[spring-jpa-fetch-join|fetch join]] 과 [[n-plus-one-problem|N+1 쿼리 문제]] 참고.

시각화

{}

EAGER 가 만드는 N+1 → JOIN FETCH 로 1쿼리 해결.

EAGER 의 함정

@Entity
class Post {
    @Id Long id;
    String title;

    @ManyToOne                          // ← 기본 EAGER
    @JoinColumn(name = "author_id")
    User author;
}

List<Post> posts = em.createQuery("SELECT p FROM Post p", Post.class).getResultList();

발생 쿼리:

posts 100 개면 SQL 101 번. [[n-plus-one-problem|N+1]] (1번 + N번) 문제. 매번 author 가 필요한지 알 수 없어도 무조건 가져옴.

LAZY 전환

@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "author_id")
User author;

이제 posts.get(0).getAuthor().getName() 호출 시점에야 SQL 실행. 사용 안 하면 author SELECT 도 안 일어남.

함정: 트랜잭션 범위를 벗어나면 LazyInitializationException. spring-data-jpa 의 ## 함정 / 2. 트랜잭션 없이 lazy 참고. 해결 도구가 아래 fetch join / EntityGraph.

fetch join

JPQL 에서 명시적으로 함께 가져옴. 상세는 [[spring-jpa-fetch-join]] 참고. 이 절은 개요만 정리.

<CodeWithOutput language=“java” outputLanguage=“text” outputLabel=“실행된 SQL” code={`List posts = em.createQuery(""" SELECT p FROM Post p JOIN FETCH p.author """, Post.class).getResultList();

for (Post p : posts) { System.out.println(p.getAuthor().getName()); // 추가 쿼리 없음 }} output={SELECT p., u. FROM post p INNER JOIN user u ON p.author_id = u.id; — 단 1번 — author 접근은 이미 로딩된 데이터에서`} />

장점: 1번에 다 가져옴. 단점:

컬렉션 fetch join 시 중복 row (Post 1 + comments 5 → Post 가 5번 반환). DISTINCT 필요
Pageable 과 조합 시 컬렉션 fetch join 불가 (in-memory paging 으로 fallback)
MultipleBagFetchException: 컬렉션 2개 이상 동시 fetch join 시 카르테시안 폭발

@EntityGraph

쿼리마다 fetch join 작성하지 않고 선언적:

@Entity
@NamedEntityGraph(
    name = "Post.author",
    attributeNodes = @NamedAttributeNode("author")
)
class Post { ... }

// Repository
@EntityGraph(value = "Post.author", type = EntityGraphType.FETCH)
List<Post> findByCreatedAtAfter(LocalDateTime date);

Spring Data JPA 에서 가장 깔끔. ad-hoc EntityGraph 도 가능:

@EntityGraph(attributePaths = {"author", "comments"})
List<Post> findAll();

EAGER 와 차이: 그 쿼리에만 적용. 다른 곳에서는 여전히 LAZY.

@BatchSize (Hibernate 확장)

여러 LAZY proxy 를 한 번에 IN 쿼리로:

@OneToMany(mappedBy = "post", fetch = FetchType.LAZY)
@BatchSize(size = 100)
List<Comment> comments;

N+1 시나리오:

posts 50개 조회
for (post : posts) post.getComments().size();

@BatchSize 없으면:

1 (posts) + 50 (각 comments) = 51 쿼리

@BatchSize(size = 100) 있으면:

1 (posts) + 1 (WHERE post_id IN (1, 2, ..., 50)) = 2 쿼리

전역 설정도 가능: spring.jpa.properties.hibernate.default_batch_fetch_size=100.

EntityGraph 보다 덜 침투적. 컬렉션 paging 과도 잘 어울림. 첫 번째 N+1 방어선으로 추천.

fetch join vs EntityGraph vs @BatchSize 비교

방법	쿼리 수	코드 위치	Paging	컬렉션 중복
fetch join	1	JPQL	컬렉션 안 됨	DISTINCT 필요
@EntityGraph	1	Repository method	컬렉션 안 됨	DISTINCT 필요
@BatchSize	2 (IN 절)	Entity / 전역	OK	없음
LAZY 만	N+1	어디서든	OK	없음

실무 전략:

모든 연관 LAZY 로 선언
전역 default_batch_fetch_size=100 설정 (안전망)
List 조회 + 즉시 사용 시 @EntityGraph 명시
단건 + paging 시 LAZY + @BatchSize 조합
복잡한 join + projection 시 QueryDSL / native SQL

EntityGraph 의 두 모드

@EntityGraph(value = "Post.author", type = EntityGraphType.FETCH)   // 명시한 것만 EAGER, 나머지 LAZY
@EntityGraph(value = "Post.author", type = EntityGraphType.LOAD)    // 명시한 것 EAGER, 나머지는 entity 기본값

FETCH 가 더 예측 가능. LOAD 는 entity 의 EAGER 설정과 합쳐져 의도치 않은 추가 fetch 발생 가능.

실전 N+1 디버깅

일반적 N+1 원인 / 감지 / 해결 개요는 [[n-plus-one-problem]] 참고. 여기서는 Spring / Hibernate 환경 설정 위주.

spring:
  jpa:
    properties:
      hibernate:
        # 모든 SQL 로깅
        show_sql: true
        format_sql: true
        # 핵심: N+1 정적 분석 (warn 로그)
        session.events.log.LOG_QUERIES_SLOWER_THAN_MS: 100
logging:
  level:
    org.hibernate.SQL: DEBUG
    org.hibernate.orm.jdbc.bind: TRACE

p6spy, datasource-proxy 같은 도구가 더 깔끔. 통합 테스트에서 N+1 검출은 Hypersistence Utils 또는 직접 Statement count 측정.

함정과 베스트 프랙티스

EAGER 절대 사용 금지: 한번 EAGER 하면 그 entity 가 쓰이는 모든 쿼리에 영향
@OneToOne 도 LAZY 가능하지만 까다로움: optional=false + bytecode enhancement 필요
컬렉션 fetch join + Pageable = in-memory paging: 로그에 firstResult/maxResults specified with collection fetch; applying in memory! warning. 대용량 데이터에서 OOM 위험
DISTINCT 는 hibernate.query.passDistinctThrough=false 와 조합 시 SQL DISTINCT 안 보냄 (메모리 dedup 만)
OSIV (Open Session In View) 가 운영에서 켜져 있으면 LAZY 함정이 가려짐. 끄는 게 안전: spring.jpa.open-in-view=false
@BatchSize 가 만능 아님: 인-메모리 join 처럼 보이게 함, 대용량 IN 절은 DB 별 제한 (Postgres OK, Oracle 1000개 제한)

[Spring MVC] Argument Resolver: Custom HandlerMethodArgumentResolver

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

HandlerMethodArgumentResolver = 컨트롤러 메서드 인자를 어떻게 채울지 결정 하는 확장점. Spring 의 수십 개 표준 resolver + 커스텀 resolver 추가 가능.

{}

Filter chain 의 일반 직관. ArgumentResolver 도 체인 형태로 적합한 resolver 가 처리 (Chain of Responsibility 패턴).

표준 ArgumentResolver

어노테이션 / 타입	resolver
`@PathVariable`	PathVariableMethodArgumentResolver
`@RequestParam`	RequestParamMethodArgumentResolver
`@RequestBody`	RequestResponseBodyMethodProcessor
`@RequestHeader`	RequestHeaderMethodArgumentResolver
`@CookieValue`	ServletCookieValueMethodArgumentResolver
`@ModelAttribute`	ModelAttributeMethodProcessor
`Model`, `ModelMap`	ModelMethodProcessor
`Locale`	LocaleResolver
`HttpServletRequest`	ServletRequestMethodArgumentResolver
`Authentication`, `Principal`	AuthenticationPrincipalArgumentResolver
`MultipartFile`	RequestPartMethodArgumentResolver
`Pageable` (Spring Data)	PageableHandlerMethodArgumentResolver

흐름

sequenceDiagram
    autonumber
    participant DS as DispatcherServlet
    participant Adapter as RequestMappingHandlerAdapter
    participant Resolver as 각 ArgumentResolver
    participant Handler as Controller method
    participant ReturnValueHandler

    DS->>Adapter: handle(request, handler)
    Adapter->>Adapter: 인자 목록 검사
    loop 각 인자
        Adapter->>Resolver: supportsParameter(param)
        Resolver-->>Adapter: yes / no
        alt yes
            Adapter->>Resolver: resolveArgument(...)
            Resolver-->>Adapter: value
        end
    end
    Adapter->>Handler: invoke(args[])
    Handler-->>Adapter: return value
    Adapter->>ReturnValueHandler: handleReturnValue(return)

Custom ArgumentResolver: 예시

1. 어노테이션 정의

@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface CurrentUser { }

2. Resolver 구현

@Component
public class CurrentUserArgumentResolver implements HandlerMethodArgumentResolver {

    private final UserService userService;

    @Override
    public boolean supportsParameter(MethodParameter parameter) {
        return parameter.hasParameterAnnotation(CurrentUser.class)
            && parameter.getParameterType().equals(User.class);
    }

    @Override
    public Object resolveArgument(
        MethodParameter parameter,
        ModelAndViewContainer mavContainer,
        NativeWebRequest webRequest,
        WebDataBinderFactory binderFactory
    ) throws Exception {
        Authentication auth = (Authentication) webRequest.getUserPrincipal();
        if (auth == null || !auth.isAuthenticated()) return null;

        String username = auth.getName();
        return userService.findByUsername(username);
    }
}

3. 등록

@Configuration
public class WebConfig implements WebMvcConfigurer {

    private final CurrentUserArgumentResolver currentUserResolver;

    @Override
    public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
        resolvers.add(currentUserResolver);
    }
}

4. 사용

@RestController
public class UserController {

    @GetMapping("/me")
    public User me(@CurrentUser User user) {
        return user;
    }
}

사례: API Pagination

@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface ParsedPagination {
    int defaultSize() default 20;
    int maxSize() default 100;
}

public record Pagination(int page, int size, String sort) { }

@Component
public class PaginationResolver implements HandlerMethodArgumentResolver {

    @Override
    public boolean supportsParameter(MethodParameter parameter) {
        return parameter.getParameterType() == Pagination.class;
    }

    @Override
    public Object resolveArgument(...) {
        ParsedPagination ann = parameter.getParameterAnnotation(ParsedPagination.class);
        int defSize = ann != null ? ann.defaultSize() : 20;
        int maxSize = ann != null ? ann.maxSize() : 100;

        HttpServletRequest req = webRequest.getNativeRequest(HttpServletRequest.class);
        int page = parseInt(req.getParameter("page"), 1);
        int size = Math.min(parseInt(req.getParameter("size"), defSize), maxSize);
        String sort = req.getParameter("sort");

        return new Pagination(page, size, sort);
    }
}

@GetMapping("/users")
public List<User> list(@ParsedPagination Pagination p) {
    return userService.find(p);
}

ReturnValueHandler: 반환값 처리

@Component
public class ApiResponseReturnValueHandler implements HandlerMethodReturnValueHandler {

    private final HandlerMethodReturnValueHandler delegate;

    @Override
    public boolean supportsReturnType(MethodParameter returnType) {
        return returnType.hasMethodAnnotation(ApiResponse.class);
    }

    @Override
    public void handleReturnValue(
        Object returnValue,
        MethodParameter returnType,
        ModelAndViewContainer mavContainer,
        NativeWebRequest webRequest
    ) throws Exception {
        Map<String, Object> wrapped = Map.of(
            "success", true,
            "data", returnValue,
            "timestamp", Instant.now()
        );
        delegate.handleReturnValue(wrapped, returnType, mavContainer, webRequest);
    }
}

모든 컨트롤러 응답을 공통 래퍼 ({success, data, timestamp}) 로.

표준 vs Custom 비교

flowchart TD
    Q{언제 Custom?}
    Q --> Use1["1. 도메인 객체 자동 주입 (CurrentUser)"]
    Q --> Use2["2. 복잡 파라미터 파싱 (Pagination)"]
    Q --> Use3["3. 공통 컨텍스트 (Tenant, Trace ID)"]
    Q --> Use4["4. 외부 시스템 lookup (옛 ID → 최신 ID)"]
    NoUse[X 안 쓸 때]
    NoUse --> N1[1. @RequestParam, @PathVariable 로 충분]
    NoUse --> N2[2. 표준 어노테이션 1개로 표현 가능]

옛 방식 vs 새 방식

// ❌ 매 컨트롤러마다 코드 반복
@GetMapping("/me")
public User me(HttpServletRequest req) {
    String username = (String) req.getSession().getAttribute("username");
    if (username == null) throw new UnauthorizedException();
    return userService.findByUsername(username);
}

// ✓ Custom resolver 로 매 메서드 한 줄
@GetMapping("/me")
public User me(@CurrentUser User user) {
    return user;
}

흔한 함정

[!WARNING]

supportsParameter 너무 광범위 = 다른 인자도 처리 시도. 어노테이션 + 타입 둘 다 검사.

Resolver 에서 비즈니스 로직 = 단순 값 채우기 만. 비즈니스는 service.

HttpServletRequest 직접 의존 = 테스트 어려움. NativeWebRequest 추상화.

Resolver 등록 안 함 = 적용 안 됨. WebMvcConfigurer.addArgumentResolvers.

[Spring MVC] Content Negotiation: Accept 헤더, MediaType, ContentNegotiationStrategy

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Content Negotiation = *같은 endpoint 가 Accept 헤더 에 따라 다른 포맷 응답. JSON / XML / HTML / CSV 등.

결정 우선순위

flowchart TD
    Req[요청]
    Req --> Q1["1. URL 확장자 (.json, .xml) - 보안상 비활성 권장"]
    Q1 --> Q2["2. Query Parameter (?format=json) - 옵션"]
    Q2 --> Q3["3. Accept Header (application/json) - 표준"]
    Q3 --> Default[4. defaultContentType]

전략	활성
Path Extension	비추천 (옛, 보안 위험)
Query Parameter	옵션
Accept Header	표준 (REST API)
Default	fallback

기본 동작

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

    @GetMapping(value = "/{id}", produces = {
        MediaType.APPLICATION_JSON_VALUE,
        MediaType.APPLICATION_XML_VALUE
    })
    public User get(@PathVariable Long id) {
        return userService.findById(id);
    }
}

# JSON 응답
GET /users/1
Accept: application/json

# XML 응답
GET /users/1
Accept: application/xml

produces / consumes

@PostMapping(
    value = "/upload",
    consumes = MediaType.MULTIPART_FORM_DATA_VALUE,  // 받는 것
    produces = MediaType.APPLICATION_JSON_VALUE       // 보내는 것
)
public UploadResult upload(@RequestParam MultipartFile file) {
    return uploadService.process(file);
}

옵션	의미
`produces`	응답 Content-Type. Accept 와 매칭
`consumes`	요청 Content-Type. 클라이언트가 보내는 것

ContentNegotiationConfigurer

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void configureContentNegotiation(ContentNegotiationConfigurer cfg) {
        cfg
            .favorParameter(true)         // ?format=xml 지원
            .parameterName("format")
            .ignoreAcceptHeader(false)    // Accept 헤더 우선
            .defaultContentType(MediaType.APPLICATION_JSON)
            .mediaType("json", MediaType.APPLICATION_JSON)
            .mediaType("xml", MediaType.APPLICATION_XML)
            .mediaType("csv", MediaType.valueOf("text/csv"));
    }
}

HttpMessageConverter

flowchart LR
    Handler[Controller return] --> RVH[ReturnValueHandler]
    RVH --> Conv[HttpMessageConverter]
    Conv --> Accept[Accept 헤더 검사]
    Accept --> Pick{지원 converter 선택}
    Pick -->|application/json| Jackson[MappingJackson2HttpMessageConverter]
    Pick -->|application/xml| Xml[Jackson2XmlConverter]
    Pick -->|text/plain| String[StringHttpMessageConverter]
    Pick -->|application/cbor| Cbor[MappingJackson2CborHttpMessageConverter]
    Jackson --> Response[HTTP Response]

Converter	기본 활성
`StringHttpMessageConverter`	text/*
`MappingJackson2HttpMessageConverter`	JSON (Jackson, 기본)
`MappingJackson2XmlHttpMessageConverter`	XML (jackson-dataformat-xml 의존)
`MappingJackson2CborHttpMessageConverter`	CBOR
`MappingJackson2SmileHttpMessageConverter`	Smile
`ByteArrayHttpMessageConverter`	byte[]
`ResourceHttpMessageConverter`	Resource (파일)
`ProtobufHttpMessageConverter`	Protobuf

등록 / 우선순위 변경

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        ObjectMapper mapper = JsonMapper.builder()
            .addModule(new JavaTimeModule())
            .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
            .build();

        converters.add(0, new MappingJackson2HttpMessageConverter(mapper));
    }
}

권장: extendMessageConverters (기본 유지 + 확장) vs configureMessageConverters (완전 교체).

Accept 의 quality value (q)

Accept: application/json;q=0.8, application/xml;q=0.9, text/html;q=0.7

q 우선순위: XML (0.9) → JSON (0.8) → HTML (0.7).

API Versioning by Accept

@GetMapping(value = "/users/{id}", produces = "application/vnd.example.v1+json")
public UserV1 getV1(@PathVariable Long id) { ... }

@GetMapping(value = "/users/{id}", produces = "application/vnd.example.v2+json")
public UserV2 getV2(@PathVariable Long id) { ... }

클라이언트가 Accept 헤더로 버전 선택. URL 깔끔. 자세한 건 [[api-versioning]].

CSV 응답 예시 (custom)

@Component
public class CsvHttpMessageConverter extends AbstractHttpMessageConverter<List<?>> {

    public CsvHttpMessageConverter() {
        super(MediaType.valueOf("text/csv"));
    }

    @Override
    protected boolean supports(Class<?> clazz) {
        return List.class.isAssignableFrom(clazz);
    }

    @Override
    protected void writeInternal(List<?> list, HttpOutputMessage out) throws IOException {
        try (PrintWriter w = new PrintWriter(out.getBody())) {
            // ... CSV 직렬화
        }
    }
}

GET /reports
Accept: text/csv

REST 응답 패턴

flowchart TD
    Accept[Accept 헤더]
    Accept -->|application/json| JSON
    Accept -->|application/xml| XML
    Accept -->|text/csv| CSV
    Accept -->|application/pdf| PDF[PDF render]
    Accept -->|text/html| Template[Thymeleaf]
    Accept -->|application/problem+json| Problem[ProblemDetail]

REST + 뷰 (옛 패턴)

같은 endpoint 가 HTML 뷰 + JSON 응답:

@Controller
public class UserController {

    @GetMapping(value = "/users/{id}", produces = MediaType.TEXT_HTML_VALUE)
    public String detailHtml(@PathVariable Long id, Model model) {
        model.addAttribute("user", userService.findById(id));
        return "users/detail";
    }

    @GetMapping(value = "/users/{id}", produces = MediaType.APPLICATION_JSON_VALUE)
    @ResponseBody
    public User detailJson(@PathVariable Long id) {
        return userService.findById(id);
    }
}

2026 시점 REST 와 view 분리 가 더 흔하다. 위 패턴은 옛 통합 컨트롤러.

흔한 함정

[!WARNING]

Path Extension 활성 = .json 으로 Accept 우회 + 보안 위험. 기본 비활성.

produces 누락 = 406 Not Acceptable 가능. 명시.

Jackson @JsonIgnore 누락 = 비밀번호 등 민감 정보 노출. DTO 패턴.

MediaType vs Accept = application/json vs application/*+json 매칭 주의.

[Spring MVC] Exception Handling: @ExceptionHandler, ControllerAdvice, ProblemDetail

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Spring MVC 의 예외 처리 3 계층:

@ExceptionHandler - 컨트롤러 내부
@ControllerAdvice / @RestControllerAdvice - 전역
ResponseEntityExceptionHandler 상속 - Spring 의 표준 예외 자동 처리

처리 우선순위

flowchart TB
    Ex[예외 발생]
    Ex --> C1["1. 컨트롤러 안 @ExceptionHandler"]
    C1 -->|매칭 안됨| C2["2. @ControllerAdvice 의 @ExceptionHandler"]
    C2 -->|매칭 안됨| C3["3. ResponseEntityExceptionHandler (Spring 표준)"]
    C3 -->|매칭 안됨| C4["4. ErrorController (BasicErrorController)"]
    C4 --> Default["기본 에러 응답 (HTML 또는 JSON)"]

컨트롤러 내부

@RestController
public class UserController {

    @GetMapping("/{id}")
    public User get(@PathVariable Long id) {
        return userService.findById(id);   // throws UserNotFoundException
    }

    @ExceptionHandler(UserNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ErrorResponse handleNotFound(UserNotFoundException ex) {
        return new ErrorResponse("USER_NOT_FOUND", ex.getMessage());
    }
}

컨트롤러 한 곳에서만 처리. 공통 예외 는 @ControllerAdvice 로.

@ControllerAdvice / @RestControllerAdvice

@RestControllerAdvice  // = @ControllerAdvice + @ResponseBody
public class GlobalExceptionHandler {

    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity<ProblemDetail> handleNotFound(UserNotFoundException ex) {
        ProblemDetail body = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
        body.setType(URI.create("https://example.com/probs/user-not-found"));
        body.setTitle("User Not Found");
        return ResponseEntity.status(404).body(body);
    }

    @ExceptionHandler(IllegalArgumentException.class)
    public ResponseEntity<ProblemDetail> handleIllegalArg(IllegalArgumentException ex) {
        return ResponseEntity.badRequest()
            .body(ProblemDetail.forStatusAndDetail(HttpStatus.BAD_REQUEST, ex.getMessage()));
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ProblemDetail> handleAll(Exception ex) {
        log.error("unhandled", ex);
        return ResponseEntity.internalServerError()
            .body(ProblemDetail.forStatusAndDetail(HttpStatus.INTERNAL_SERVER_ERROR, "내부 오류"));
    }
}

ControllerAdvice 범위

@RestControllerAdvice(basePackages = "com.example.api")
@RestControllerAdvice(assignableTypes = {UserController.class, OrderController.class})
@RestControllerAdvice(annotations = ApiV1.class)

큰 시스템에서 API v1 vs v2 별로 분리 가능.

ProblemDetail (RFC 7807, Spring 6+)

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://example.com/probs/validation",
  "title": "Validation failed",
  "status": 400,
  "detail": "Email is required",
  "instance": "/api/users",
  "errors": [
    { "field": "email", "code": "REQUIRED" }
  ]
}

2026 시점 REST API 의 에러 응답 표준. Spring 6 / Boot 3 부터 자동 활성.

@ExceptionHandler(BusinessException.class)
public ProblemDetail handle(BusinessException ex) {
    ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.UNPROCESSABLE_ENTITY, ex.getMessage());
    pd.setType(URI.create("https://example.com/probs/" + ex.getCode()));
    pd.setTitle(ex.getTitle());
    pd.setProperty("errorCode", ex.getCode());
    pd.setProperty("traceId", MDC.get("traceId"));
    return pd;
}

활성화 (Spring Boot)

spring:
  mvc:
    problemdetails:
      enabled: true   # Spring 6 default true

→ Spring 의 모든 표준 예외 가 자동 ProblemDetail 로 응답.

@Valid 실패 처리

@ExceptionHandler(MethodArgumentNotValidException.class)
public ProblemDetail handleValidation(MethodArgumentNotValidException ex) {
    ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.BAD_REQUEST, "검증 실패");
    pd.setProperty("errors", ex.getFieldErrors().stream()
        .map(e -> Map.of(
            "field", e.getField(),
            "rejected", e.getRejectedValue(),
            "message", e.getDefaultMessage()
        ))
        .toList());
    return pd;
}

ResponseEntityExceptionHandler 상속

Spring 의 수십 가지 표준 예외 (HttpMessageNotReadableException, HttpRequestMethodNotSupportedException 등) 처리.

@RestControllerAdvice
public class ApiExceptionHandler extends ResponseEntityExceptionHandler {

    @Override
    protected ResponseEntity<Object> handleMethodArgumentNotValid(
        MethodArgumentNotValidException ex,
        HttpHeaders headers,
        HttpStatusCode status,
        WebRequest request
    ) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail((HttpStatus) status, "Validation failed");
        pd.setProperty("errors", ex.getFieldErrors());
        return ResponseEntity.status(status).body(pd);
    }

    // 비즈니스 예외
    @ExceptionHandler(BusinessException.class)
    public ResponseEntity<ProblemDetail> handle(BusinessException ex) { ... }
}

옛 ErrorAttributes 와 비교

방식	의미
`ResponseEntity<...>` 반환	직접 응답 객체 만듦
`ProblemDetail`	RFC 7807 표준 (Spring 6+)
`ErrorAttributes`	`/error` endpoint 의 응답 데이터
`ErrorController`	옛 BasicErrorController override

2026 시점 ProblemDetail 이 표준. 옛 ErrorAttributes 는 HTML 에러 페이지 정도에만.

예외 분류 전략

flowchart TB
    Q{예외 종류}
    Q --> Biz["비즈니스 예외<br/>(BusinessException)"]
    Q --> Val["검증 예외<br/>(ValidationException)"]
    Q --> Sys["시스템 예외<br/>(DB, Network)"]
    Q --> Sec["보안 예외<br/>(Auth, AccessDenied)"]
    Biz --> B1["Status: 4xx<br/>(보통 422 또는 409)"]
    Val --> V1[400 + ProblemDetail with errors]
    Sys --> S1[500 + log + alert]
    Sec --> Se1[401 / 403]

보안 측면

@ExceptionHandler(Exception.class)
public ProblemDetail handleAll(Exception ex, WebRequest req) {
    String traceId = MDC.get("traceId");
    log.error("unhandled [{}]", traceId, ex);   // 내부 로그

    ProblemDetail pd = ProblemDetail.forStatusAndDetail(
        HttpStatus.INTERNAL_SERVER_ERROR,
        "내부 오류가 발생했습니다. 잠시 후 다시 시도해주세요."   // ← 일반화
    );
    pd.setProperty("traceId", traceId);   // 사용자 → 운영자 추적 가능
    return pd;
}

[!CAUTION] 예외 메시지 / stack trace 클라이언트 노출 금지. 내부 정보 (DB 구조, 파일 경로) 누출.

Logging + Tracing

@ExceptionHandler(BusinessException.class)
public ProblemDetail handle(BusinessException ex) {
    log.warn("biz: code={}, detail={}", ex.getCode(), ex.getMessage());
    return ProblemDetail.forStatusAndDetail(HttpStatus.UNPROCESSABLE_ENTITY, ex.getMessage());
}

예외 종류	로그 레벨
400 (검증, 입력)	INFO (정상 흐름)
401, 403	INFO 또는 WARN
404	INFO
422 (비즈니스)	WARN
500 (시스템)	ERROR + alert

흔한 함정

[!WARNING]

@ExceptionHandler 가 더 구체적인 예외부터 = Spring 이 최적 매칭. 단 순서가 보장 안 되니 명확한 클래스만.

Throwable 잡음 = Error (OOM 등) 까지 잡힘. Exception 까지만.

@RestControllerAdvice + 뷰 컨트롤러 = JSON 응답. @ControllerAdvice + String view 분리.

예외 안에서 다시 예외 = handler 가 recursion. 주의.

[Spring MVC] Form Handling: @ModelAttribute, DataBinder, conversion

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Form Handling = HTML form 의 요청 파라미터 → Java 객체 변환 + 검증 + 에러 처리. 핵심: @ModelAttribute + WebDataBinder + ConversionService.

기본 흐름

flowchart LR
    Form[HTML Form] -->|POST x=1&y=hello| Req[HttpServletRequest]
    Req --> Binder[WebDataBinder]
    Binder -->|타입 변환| Conv[ConversionService]
    Conv --> Obj[Form Object]
    Obj --> Validator[Bean Validator]
    Validator --> BR[BindingResult]
    Obj --> Handler[Controller method]
    BR --> Handler

자세한 BindingResult 는 [[spring-mvc-model-bindingresult]].

@ModelAttribute 의 3가지 역할

flowchart TB
    A["@ModelAttribute"]
    A --> R1["1. 핸들러 인자: form 객체 바인딩"]
    A --> R2["2. 메서드 어노테이션: 모든 핸들러에 attribute 추가"]
    A --> R3["3. 인자 이름 변경 (Model 안에 다른 이름)"]

1. 인자에서 (form 바인딩)

@PostMapping("/signup")
public String signup(@ModelAttribute SignupForm form,
                     BindingResult result) {
    if (result.hasErrors()) return "users/signup-form";
    ...
}

// @ModelAttribute 생략 가능 (default)
public String signup(SignupForm form, BindingResult result) { ... }

Spring 이 기본 생성자 + setter 또는 all-args constructor 로 객체 생성 + 요청 파라미터 매핑.

2. 메서드 어노테이션 (공통 attribute)

@Controller
public class UserController {

    @ModelAttribute("countries")
    public List<Country> countries() {
        return countryService.findAll();
    }

    @ModelAttribute
    public Locale locale(HttpServletRequest req) {
        return req.getLocale();
    }

    @GetMapping("/signup")
    public String signupForm(Model model) {
        // countries, locale 자동 추가됨
        model.addAttribute("signupForm", new SignupForm());
        return "users/signup-form";
    }
}

3. 이름 변경

public String signup(@ModelAttribute("signupForm") SignupForm form) {
    // Model 에 "signupForm" 이름으로 저장
    // 뷰의 th:object="${signupForm}" 와 매칭
}

default 이름 = 클래스 이름 소문자 첫글자 (signupForm).

WebDataBinder 의 동작

sequenceDiagram
    autonumber
    Form->>Servlet: POST email=koa@x.com&age=29
    Servlet->>DispatcherServlet: forward
    DispatcherServlet->>Resolver[ModelAttributeMethodProcessor]: arg resolve
    Resolver->>Binder[WebDataBinder]: bind(request, target)
    Binder->>Conv[ConversionService]: String "29" → Integer 29
    Binder->>Conv: String "koa@x.com" → String
    Conv-->>Binder: 변환 결과
    Binder->>Validator: @Valid 트리거
    Validator-->>Binder: ConstraintViolations
    Binder-->>Handler: Form + BindingResult

ConversionService 와 Formatter

기본 변환

Spring 이 자동 처리:

String "29"        → Integer 29
String "true"      → boolean true
String "2026-06-25" → LocalDate (LocaleContextHolder 의 locale)
String "12345"     → enum Status (name 기반)
String "1,2,3"     → List<Integer> (separator: comma)

커스텀 Formatter

@Component
public class MoneyFormatter implements Formatter<Money> {

    @Override
    public Money parse(String text, Locale locale) throws ParseException {
        // "1,234,567원" → Money
        long amount = Long.parseLong(text.replaceAll("[,원]", ""));
        return new Money(amount, Currency.KRW);
    }

    @Override
    public String print(Money money, Locale locale) {
        return String.format("%,d원", money.amount());
    }
}

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addFormatters(FormatterRegistry registry) {
        registry.addFormatter(new MoneyFormatter());
    }
}

이제 @RequestParam Money price 자동 변환.

@DateTimeFormat / @NumberFormat

public record OrderForm(
    @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm")
    LocalDateTime scheduledAt,

    @NumberFormat(pattern = "#,###")
    Long amount,

    @NumberFormat(style = NumberFormat.Style.CURRENCY)
    BigDecimal price
) { }

@InitBinder (커스텀 바인딩 설정)

@Controller
public class OrderController {

    @InitBinder
    public void initBinder(WebDataBinder binder) {
        // 1. 특정 필드 *바인딩 차단* (mass assignment 방어!)
        binder.setDisallowedFields("id", "createdAt", "user");

        // 2. *허용 필드만* 명시 (더 안전)
        binder.setAllowedFields("title", "amount", "deliveryAddress");

        // 3. 커스텀 editor 등록
        binder.registerCustomEditor(Date.class,
            new CustomDateEditor(new SimpleDateFormat("yyyy/MM/dd"), false));
    }
}

[!CAUTION] Mass Assignment 취약점: User.role 같이 민감 필드 가 form 으로 update 가능 하면 공격자가 admin 으로 승격. setDisallowedFields 또는 DTO 분리.

DTO 패턴 (권장)

// ✓ 안전: DTO 만 form 으로 받음
public record SignupForm(
    @NotBlank @Email String email,
    @NotBlank @Size(min = 8) String password,
    @NotBlank String name
) {
    public User toUser() {
        return new User(null, email, hashPassword(password), name, Role.USER);
    }
}

// ✗ 위험: Entity 를 form 으로 받지 말 것
@PostMapping("/signup")
public String signup(@ModelAttribute User user) { ... }   // role 까지 받음

Content Type 별 바인딩

Content-Type	바인딩
`application/x-www-form-urlencoded`	`@ModelAttribute` (또는 생략)
`multipart/form-data`	`@ModelAttribute` + `MultipartFile`
`application/json`	`@RequestBody` (Jackson)
`application/xml`	`@RequestBody` (Jackson XML)

// 파일 업로드
@PostMapping("/upload")
public String upload(@RequestParam("file") MultipartFile file,
                     @ModelAttribute UploadForm form) {
    file.transferTo(Path.of("/var/uploads/" + file.getOriginalFilename()));
    return "redirect:/files";
}

Spring MVC vs WebFlux 차이

	Spring MVC (Servlet)	WebFlux
바인딩	`WebDataBinder`	`WebExchangeDataBinder`
API	sync	reactive
본문	`@RequestBody DTO`	`Mono<DTO>`
Form	`@ModelAttribute`	동일 (reactive)

흔한 함정

[!WARNING]

DTO 없이 Entity 직접 바인딩 = mass assignment. 항상 DTO 분리.

@InitBinder 의 setAllowedFields/setDisallowedFields 둘 다 명시 = allowed 만 적용. 하나로.

type 변환 실패 시 메시지 = typeMismatch.fieldName i18n 메시지 미정의 → 기본 영문.

MultipartFile 의 기본 size limit = 1MB (기본). spring.servlet.multipart.max-file-size.

[Spring MVC] Model + BindingResult: 뷰 모델과 바인딩 오류 처리

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Model = 컨트롤러 → 뷰 (Thymeleaf, JSP) 로 데이터 전달. BindingResult = 요청 파라미터 → 객체 바인딩 결과 + 오류. 둘 다 Spring MVC 핸들러 메서드의 특별 인자.

[!IMPORTANT] REST API (@RestController) 는 JSON 응답 이라 Model 거의 사용 안 함. 전통 MVC (@Controller + 뷰 렌더링) 의 핵심.

Model 의 본질

flowchart LR
    Req[HTTP Request] --> Controller["@Controller 메서드"]
    Controller -->|model.addAttribute| Model
    Controller -->|return view_name| Resolver[ViewResolver]
    Model --> View[Thymeleaf / JSP]
    Resolver --> View
    View --> Response[HTML Response]

사용

@Controller
@RequestMapping("/users")
public class UserViewController {

    @GetMapping
    public String list(Model model) {
        model.addAttribute("users", userService.findAll());
        model.addAttribute("total", userService.count());
        return "users/list";   // → resolved → templates/users/list.html
    }

    @GetMapping("/{id}")
    public String detail(@PathVariable Long id, Model model) {
        User user = userService.findById(id);
        model.addAttribute("user", user);
        return "users/detail";
    }
}

<!-- templates/users/list.html -->
<table>
  <tr th:each="u : ${users}">
    <td th:text="${u.name}"></td>
  </tr>
</table>
<p th:text="${'Total: ' + total}"></p>

Model 의 4가지 사용 방법

방식	코드
`Model` 파라미터	`model.addAttribute("user", user)`
`ModelMap`	동일
`Map<String, Object>`	동일 (자동 변환)
`@ModelAttribute` 메서드	모든 핸들러 공통 attribute

@ModelAttribute("categories")
public List<Category> categories() {
    return categoryService.findAll();   // 모든 핸들러에서 자동 추가
}

ModelAndView

@GetMapping("/{id}")
public ModelAndView detail(@PathVariable Long id) {
    ModelAndView mv = new ModelAndView("users/detail");
    mv.addObject("user", userService.findById(id));
    return mv;
}

Model 분리 방식이 깔끔하지만 옛 스타일. 2026 시점 Model + return view_name 이 표준.

BindingResult: 바인딩 오류 처리

폼 전송 → 객체 바인딩 → 타입 변환 오류 + Validation 오류 가 BindingResult 에 모임.

@PostMapping("/signup")
public String signup(
    @ModelAttribute @Valid SignupForm form,
    BindingResult result,
    Model model
) {
    if (result.hasErrors()) {
        // 에러 정보 + 폼 데이터 유지하며 다시 폼 페이지로
        return "users/signup-form";
    }
    userService.signup(form);
    return "redirect:/users";
}

[!CAUTION] BindingResult 는 반드시 @Valid 또는 @ModelAttribute 인자 바로 다음 에 위치. 위치 잘못이면 MethodArgumentNotValidException 발생 (400).

// ✗ 잘못된 위치
public String signup(@Valid Form form, Model model, BindingResult result) { ... }

// ✓ 올바른 위치
public String signup(@Valid Form form, BindingResult result, Model model) { ... }

BindingResult 의 핵심 API

result.hasErrors();                      // 전체 에러
result.hasFieldErrors();                 // 필드 단위
result.hasGlobalErrors();                // 객체 전체 (cross-field)
result.hasFieldErrors("email");          // 특정 필드

result.getFieldErrors();                 // List<FieldError>
result.getFieldError("email");           // FieldError 또는 null
result.getAllErrors();                   // List<ObjectError>

result.rejectValue("email", "duplicate", "이미 사용 중인 이메일");
result.reject("invalid", "전체 객체 오류");

Error 객체

flowchart TB
    Errors[Errors interface]
    Errors --> Bind[BindingResult]
    Bind --> Field["FieldError<br/>(필드 단위)"]
    Bind --> Object["ObjectError<br/>(객체 전체)"]
    Field --> Fields["objectName, field, rejectedValue, codes, defaultMessage"]
    Object --> Objects["objectName, codes, defaultMessage"]

속성	의미
`objectName`	폼 객체 이름 (보통 `signupForm`)
`field`	필드 이름
`rejectedValue`	입력한 원본 값
`codes`	메시지 코드 우선순위 (i18n)
`defaultMessage`	기본 메시지

뷰에서 에러 표시 (Thymeleaf)

<form th:action="@{/signup}" th:object="${signupForm}" method="post">

  <input type="text" th:field="*{email}"
         th:classappend="${#fields.hasErrors('email')} ? 'is-invalid'" />
  <div class="error" th:if="${#fields.hasErrors('email')}"
       th:errors="*{email}"></div>

  <input type="password" th:field="*{password}" />
  <div class="error" th:errors="*{password}"></div>

  <!-- 전체 (global) 에러 -->
  <ul th:if="${#fields.hasGlobalErrors()}">
    <li th:each="err : ${#fields.globalErrors()}" th:text="${err}"></li>
  </ul>

  <button>가입</button>
</form>

자세한 Thymeleaf 는 [[spring-thymeleaf]].

Bind 메시지 (i18n)

# messages.properties
NotBlank.signupForm.email=이메일을 입력해주세요
Size.signupForm.password=비밀번호는 {2}자 이상 {1}자 이하
Email.signupForm.email=올바른 이메일 형식이 아닙니다

# typeMismatch 는 special
typeMismatch.signupForm.age=숫자만 입력 가능합니다
typeMismatch.java.lang.Integer=숫자 형식이 잘못되었습니다

Spring 이 자동으로 코드 우선순위 로 메시지 lookup.

RedirectAttributes (PRG 패턴)

@PostMapping
public String signup(
    @Valid SignupForm form,
    BindingResult result,
    RedirectAttributes redirectAttrs
) {
    if (result.hasErrors()) return "users/signup-form";

    User u = userService.signup(form);
    redirectAttrs.addAttribute("id", u.getId());          // URL 쿼리스트링
    redirectAttrs.addFlashAttribute("message", "가입 완료!"); // session 1회 유지

    return "redirect:/users/{id}";   // /users/42?id=42 (PathVariable + Query)
}

@GetMapping("/{id}")
public String detail(@PathVariable Long id, Model model) {
    // Flash attribute 가 자동으로 Model 에 들어감
    // 뷰에서 ${message} 로 사용 가능
    return "users/detail";
}

[!IMPORTANT] POST-Redirect-GET (PRG) 패턴. 폼 전송 후 redirect 로 새로고침 시 중복 제출 방지. Flash 로 일회성 메시지 전달.

동작 흐름

sequenceDiagram
    autonumber
    participant Browser
    participant DS as DispatcherServlet
    participant Handler as Controller method
    participant Binder as DataBinder
    participant Valid as Validator
    participant View as ViewResolver

    Browser->>DS: POST /signup (form data)
    DS->>Handler: invoke
    Handler->>Binder: bind request params → SignupForm
    Note over Binder: 타입 변환 오류 → BindingResult
    Binder->>Valid: @Valid 트리거
    Valid->>Valid: Hibernate Validator 실행
    Valid->>Binder: ConstraintViolations → BindingResult
    Binder-->>Handler: SignupForm + BindingResult
    alt hasErrors
        Handler->>Model: form + errors
        Handler-->>View: "users/signup-form"
        View-->>Browser: HTML (오류 메시지)
    else 성공
        Handler->>Model: Flash attributes
        Handler-->>View: "redirect:/users/{id}"
        View-->>Browser: 302 → /users/42
    end

REST 에서의 BindingResult

@RestController + @RequestBody @Valid 면 BindingResult 대신 MethodArgumentNotValidException 자동 발생. @ControllerAdvice 에서 처리.

@PostMapping
public User create(@RequestBody @Valid CreateUserDto dto) {
    // 위 메서드는 *BindingResult 없으면* 검증 실패 시 자동 예외
    return userService.create(dto);
}

// → @ExceptionHandler 에서 처리

자세한 건 [[spring-mvc-exception-handler]].

흔한 함정

[!WARNING]

BindingResult 위치 = @Valid 인자 바로 다음 이 아니면 작동 안 함.

Model 에서 민감 정보 노출 = model.addAttribute("user", user) → user 의 비밀번호가 HTML 에 노출.

@ModelAttribute 의 이름 충돌 = @ModelAttribute("signupForm") 와 뷰 th:object="${signupForm}" 이름 일치.

Flash attribute 가 사라짐 = redirect 직후 1회만. 뒤로가기 시 재호출하면 없음.

[Spring MVC] Thymeleaf: 서버 사이드 템플릿 엔진

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Thymeleaf = Java 서버 사이드 HTML 템플릿 엔진. natural template 철학 (브라우저에서 그대로 열어도 동작). Spring Boot 가 기본 권장 (Tiles, JSP, Velocity 후계).

Spring Boot 설정

implementation("org.springframework.boot:spring-boot-starter-thymeleaf")

위치	기본
`templates/`	템플릿 (resolve 시 자동 prefix)
`static/`	정적 (CSS, JS, 이미지)
Suffix	`.html`
Encoding	UTF-8
Cache	dev `false`, prod `true`

기본 문법

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
  <title th:text="${pageTitle}">기본 제목</title>
</head>
<body>
  <h1 th:text="${user.name}">홍길동</h1>
  <p>나이: <span th:text="${user.age}">30</span>세</p>

  <ul>
    <li th:each="item, stat : ${items}"
        th:class="${stat.first} ? 'first' : 'normal'">
      <span th:text="${stat.count}">1</span>:
      <span th:text="${item.name}">상품</span>
    </li>
  </ul>
</body>
</html>

th:text="${...}" 가 가장 핵심. 기본 텍스트 (“홍길동”, “30”) 는 브라우저에서 직접 열었을 때만 보이는 자리표시자.

표현식 4종

종류	예	의미
`${...}`	`${user.name}`	Variable (Model attribute)
`*{...}`	`*{name}`	Selection (`th:object` 안의 필드)
`#{...}`	`#{login.title}`	Message (i18n)
`@{...}`	`@{/users/{id}(id=${u.id})}`	URL (context path 자동)
`~{...}`	`~{fragments :: header}`	Fragment

URL 표현식 (`@{...}`)

<!-- context path 자동 prefix -->
<a th:href="@{/users}">목록</a>
<a th:href="@{/users/{id}(id=${u.id})}">상세</a>

<!-- query string -->
<a th:href="@{/search(q=${query}, page=${page+1})}">다음</a>

<!-- 절대 URL -->
<img th:src="@{~/img/logo.png}" />

조건문

<div th:if="${user.admin}">관리자 메뉴</div>
<div th:unless="${user.admin}">일반 사용자</div>

<!-- switch -->
<div th:switch="${user.role}">
  <p th:case="'admin'">관리자</p>
  <p th:case="'editor'">에디터</p>
  <p th:case="*">일반</p>
</div>

<!-- 삼항 -->
<span th:text="${user.active ? 'O' : 'X'}"></span>
<span th:class="${user.active ? 'badge-success' : 'badge-muted'}"></span>

반복 + iteration status

<tr th:each="u, stat : ${users}">
  <td th:text="${stat.index}">0</td>      <!-- 0부터 -->
  <td th:text="${stat.count}">1</td>      <!-- 1부터 -->
  <td th:text="${stat.size}">100</td>     <!-- 전체 크기 -->
  <td th:text="${stat.even ? 'even' : 'odd'}"></td>
  <td th:text="${stat.first ? '첫번째' : ''}"></td>
  <td th:text="${stat.last ? '마지막' : ''}"></td>
  <td th:text="${u.name}"></td>
</tr>

Spring 폼 통합

<form th:action="@{/signup}" th:object="${signupForm}" method="post">

  <!-- th:field 가 자동으로 id, name, value 박음 -->
  <input type="text" th:field="*{email}" />
  <input type="password" th:field="*{password}" />
  <input type="checkbox" th:field="*{newsletter}" />

  <select th:field="*{country}">
    <option th:each="c : ${countries}"
            th:value="${c.code}"
            th:text="${c.name}">한국</option>
  </select>

  <!-- 에러 표시 -->
  <div class="error" th:if="${#fields.hasErrors('email')}"
       th:errors="*{email}">에러 메시지</div>

  <button type="submit">가입</button>
</form>

자세한 form binding 은 [[spring-mvc-form-handling]].

Fragment (재사용)

<!-- templates/fragments/header.html -->
<header th:fragment="topbar(title)">
  <h1 th:text="${title}">제목</h1>
  <nav>...</nav>
</header>

<!-- 다른 페이지 -->
<body>
  <div th:replace="~{fragments/header :: topbar('대시보드')}"></div>

  <!-- 또는 th:insert (이 div 안에 fragment 삽입) -->
  <div th:insert="~{fragments/header :: topbar(${pageTitle})}"></div>
</body>

디렉티브	의미
`th:replace`	대체 (현재 태그가 fragment 로 교체)
`th:insert`	삽입 (현재 태그 안에 fragment)
`th:include` (deprecated)	replace 권장

Layout (template inheritance)

implementation("nz.net.ultraq.thymeleaf:thymeleaf-layout-dialect")

<!-- templates/layout/main.html -->
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org"
      xmlns:layout="http://www.ultraq.net.nz/thymeleaf/layout">
<head>
  <title layout:title-pattern="$CONTENT_TITLE - 사이트명">기본</title>
</head>
<body>
  <div th:replace="~{fragments/header :: topbar(${pageTitle})}"></div>

  <main layout:fragment="content">
    여기에 페이지별 내용
  </main>

  <div th:replace="~{fragments/footer :: footer}"></div>
</body>
</html>

<!-- templates/users/detail.html -->
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org"
      xmlns:layout="http://www.ultraq.net.nz/thymeleaf/layout"
      layout:decorate="~{layout/main}">
<head>
  <title>사용자 상세</title>
</head>
<body>
  <main layout:fragment="content">
    <h2 th:text="${user.name}"></h2>
    <p th:text="${user.email}"></p>
  </main>
</body>
</html>

표준 객체 (Utility Objects)

객체	용도
`#strings`	`#strings.toUpperCase(name)`, `#strings.isEmpty(...)`
`#numbers`	`#numbers.formatDecimal(price, 1, 2)`
`#dates`	`#dates.format(date, 'yyyy-MM-dd')`
`#temporals`	Java 8 Date/Time
`#calendars`	Calendar
`#objects`	`#objects.nullSafe(obj, default)`
`#bools`	`#bools.isTrue(value)`
`#arrays`, `#lists`, `#sets`, `#maps`	컬렉션
`#fields`	form 에러
`#httpServletRequest`	직접 request
`#authentication`	Spring Security

Security 통합

<div xmlns:sec="http://www.thymeleaf.org/extras/spring-security">

  <div sec:authorize="isAuthenticated()">
    <span sec:authentication="name">사용자</span>
    <a th:href="@{/logout}">로그아웃</a>
  </div>

  <div sec:authorize="hasRole('ADMIN')">
    <a th:href="@{/admin}">관리자</a>
  </div>

  <div sec:authorize="!isAuthenticated()">
    <a th:href="@{/login}">로그인</a>
  </div>

</div>

Inline (script + JSON 데이터)

<script th:inline="javascript">
  const user = /*[[${user}]]*/ {};
  const pageData = /*[[${pageData}]]*/ null;
  console.log(user.name);
</script>

Thymeleaf 가 JSON 변환 + JS 객체로 주입. SPA 의 초기 데이터 hydration 에 활용.

Live Reload (dev)

spring:
  thymeleaf:
    cache: false       # dev only
  devtools:
    restart:
      enabled: true

흔한 함정

[!WARNING]

th:cache: true (prod) 안 켜면 매 요청 파일 read. 운영 환경 반드시.

th:text vs th:utext = text 는 escape, utext 는 raw HTML. XSS 주의.

th:field 에러 = th:object 의 form 객체가 Model 에 없음. 컨트롤러에서 model.addAttribute("signupForm", new SignupForm()) 또는 빈 결과 시 다시 채움.

*{} 의 outside th:object = *{name} 은 th:object 밖에서 사용 불가. ${signupForm.name} 으로.

Thymeleaf vs JSP vs Mustache

	Thymeleaf	JSP	Mustache
Spring Boot 권장	예	비추천	옵션
Natural template	예	아니오	부분
로직	표현식 + dialect	scriptlet (X)	logicless
모더니즘	2026 표준	legacy	가볍지만 제한적
학습 곡선	중간	낮음	매우 낮음

[Spring Validation] Custom Validator: ConstraintValidator, Groups, cross-field

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

기본 @NotBlank, @Size 등으로 부족한 도메인 검증 을 ConstraintValidator 인터페이스 로 구현. 재사용 가능한 어노테이션 형태.

기본 validation 의 일반은 [[spring-validation]].

패턴 3가지

flowchart TB
    Q[Custom Validation]
    Q --> A1["1. Constraint Composition<br/>(기존 어노테이션 조합)"]
    Q --> A2["2. ConstraintValidator<br/>(완전 새 로직)"]
    Q --> A3["3. @AssertTrue<br/>(객체 메서드)"]

1. Constraint Composition

기존 어노테이션 조합 으로 새 어노테이션:

@Target({ FIELD, PARAMETER, METHOD })
@Retention(RUNTIME)
@NotBlank(message = "이메일을 입력하세요")
@Email(message = "올바른 이메일 형식이 아닙니다")
@Size(max = 100)
@ReportAsSingleViolation
@Constraint(validatedBy = {})
public @interface ValidEmail {
    String message() default "";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

다른 Bean Validation 어노테이션 의 조합. 별도 ConstraintValidator 불필요.

2. ConstraintValidator (완전 새 로직)

@Target({ FIELD, PARAMETER })
@Retention(RUNTIME)
@Constraint(validatedBy = PhoneNumberValidator.class)
public @interface PhoneNumber {
    String message() default "올바른 휴대폰 번호가 아닙니다";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};

    String country() default "KR";   // 어노테이션 옵션
}

public class PhoneNumberValidator implements ConstraintValidator<PhoneNumber, String> {

    private String country;

    @Override
    public void initialize(PhoneNumber annotation) {
        this.country = annotation.country();
    }

    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        if (value == null) return true;   // null 은 @NotNull 의 책임

        return switch (country) {
            case "KR" -> value.matches("^01[016789]-?\\d{3,4}-?\\d{4}$");
            case "US" -> value.matches("^\\+1[0-9]{10}$");
            default   -> false;
        };
    }
}

// 사용
public record SignupForm(
    @NotBlank @PhoneNumber String phone
) { }

동적 메시지 (ConstraintValidatorContext)

@Override
public boolean isValid(String value, ConstraintValidatorContext context) {
    if (value == null) return true;

    if (value.length() < 10) {
        context.disableDefaultConstraintViolation();
        context.buildConstraintViolationWithTemplate("최소 10자 이상이어야 합니다 (현재: " + value.length() + ")")
            .addConstraintViolation();
        return false;
    }
    return true;
}

3. @AssertTrue (객체 메서드)

public record PasswordChangeForm(
    @NotBlank String oldPassword,
    @NotBlank @Size(min = 8) String newPassword,
    @NotBlank String confirmPassword
) {
    @AssertTrue(message = "새 비밀번호와 확인이 일치해야 합니다")
    public boolean isPasswordConfirmed() {
        return newPassword != null && newPassword.equals(confirmPassword);
    }

    @AssertTrue(message = "새 비밀번호는 기존 비밀번호와 달라야 합니다")
    public boolean isPasswordDifferent() {
        return !newPassword.equals(oldPassword);
    }
}

가장 간단 한 cross-field validation. 단 에러가 객체 단위 (필드 매핑 불명확).

4. Class-level @Constraint

@Target({ TYPE })
@Retention(RUNTIME)
@Constraint(validatedBy = PasswordMatchValidator.class)
public @interface PasswordMatch {
    String message() default "비밀번호가 일치하지 않습니다";
    String passwordField() default "password";
    String confirmField() default "confirmPassword";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

public class PasswordMatchValidator implements ConstraintValidator<PasswordMatch, Object> {

    private String passwordField;
    private String confirmField;

    @Override
    public void initialize(PasswordMatch ann) {
        this.passwordField = ann.passwordField();
        this.confirmField = ann.confirmField();
    }

    @Override
    public boolean isValid(Object obj, ConstraintValidatorContext context) {
        BeanWrapper bw = new BeanWrapperImpl(obj);
        Object p1 = bw.getPropertyValue(passwordField);
        Object p2 = bw.getPropertyValue(confirmField);

        boolean valid = Objects.equals(p1, p2);
        if (!valid) {
            context.disableDefaultConstraintViolation();
            context.buildConstraintViolationWithTemplate(context.getDefaultConstraintMessageTemplate())
                .addPropertyNode(confirmField)
                .addConstraintViolation();
        }
        return valid;
    }
}

@PasswordMatch
public record SignupForm(
    @NotBlank String email,
    @NotBlank @Size(min = 8) String password,
    @NotBlank String confirmPassword
) { }

Cross-field 검증의 재사용 가능 한 형태.

Validation Groups

public interface OnCreate { }
public interface OnUpdate { }

public record UserForm(
    @Null(groups = OnCreate.class)
    @NotNull(groups = OnUpdate.class)
    Long id,

    @NotBlank(groups = { OnCreate.class, OnUpdate.class })
    String name,

    @NotBlank(groups = OnCreate.class)   // 생성 시만 필수
    String password
) { }

@PostMapping
public User create(@RequestBody @Validated(OnCreate.class) UserForm form) {
    return service.create(form);
}

@PutMapping("/{id}")
public User update(@RequestBody @Validated(OnUpdate.class) UserForm form) {
    return service.update(form);
}

[!IMPORTANT] @Valid 는 Default 그룹만 적용. Groups 사용 시 @Validated (Spring 어노테이션) 로.

@GroupSequence (순서 보장)

public interface First { }
public interface Second { }

@GroupSequence({ First.class, Second.class, Default.class })
public interface OrderedChecks { }

public record SignupForm(
    @NotBlank(groups = First.class)
    @Email(groups = Second.class)
    String email,

    @NotBlank(groups = First.class)
    @Size(min = 8, groups = Second.class)
    @PasswordStrength(groups = Default.class)
    String password
) { }

@PostMapping
public String signup(@Validated(OrderedChecks.class) SignupForm form, BindingResult result) { ... }

First 그룹 통과 → Second 그룹 → Default. 한 그룹 실패 시 다음 그룹 평가 안 함. 무거운 검증 (DB 조회 등) 을 뒤로 미루는 패턴.

ConstraintValidator + Spring DI

public class UniqueEmailValidator implements ConstraintValidator<UniqueEmail, String> {

    private final UserRepository userRepository;   // ← Spring bean injection

    public UniqueEmailValidator(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    @Override
    public boolean isValid(String email, ConstraintValidatorContext ctx) {
        if (email == null) return true;
        return !userRepository.existsByEmail(email);
    }
}

ConstraintValidator 도 Spring bean. DI 가능. 단 static 한 검증 만 어노테이션으로 표현하는 게 정통.

[!CAUTION] DB 조회 validation 은 N+1 같은 성능 함정 + 트랜잭션 외부 호출 위험. service layer 에서 검증 이 더 안전한 경우 많다.

Hibernate Validator 확장

어노테이션	의미
`@URL`	URL 형식
`@Length(min, max)`	String 길이 (Size 와 비슷)
`@Range(min, max)`	숫자 범위
`@CreditCardNumber`	신용카드
`@SafeHtml` (deprecated)	XSS 방어
`@ScriptAssert`	Java Script (SpEL)
`@CodePointLength`	코드포인트 단위 길이

흔한 함정

[!WARNING]

null 검증을 ConstraintValidator 안에서 = @NotNull 의 책임. null 이면 true 반환.

@Valid 와 Groups 함께 = @Valid 는 Default 만. @Validated 사용.

무거운 검증 (DB) = 매 요청 연쇄 호출 → service layer 권장.

@GroupSequence 의 순환 = 컴파일은 OK 인데 런타임 무한 루프. 검토.

[JPA] JPQL DTO Projection: constructor expression, interface, record

koa (김신건) — Wed, 24 Jun 2026 00:00:00 GMT

정의

DTO Projection 은 entity 전체가 아닌 필요한 컬럼만 query 해서 DTO 로 받기. 장점:

N+1 회피 (lazy 컬렉션 자동 무시)
entity 전체 hydration 비용 절감
API 응답에 맞춘 형태 (entity 그대로 반환은 anti-pattern)
read-only 의도 명확

JPQL 의 4가지 projection 방식 + Spring Data JPA 의 추가 옵션 2가지.

1. Constructor Expression (NEW)

JPQL 표준. DTO 클래스의 생성자 시그니처와 매칭:

public record UserSummary(Long id, String name, String email) {}

List<UserSummary> result = em.createQuery(
    "SELECT NEW com.example.UserSummary(u.id, u.name, u.email) FROM User u",
    UserSummary.class
).getResultList();

핵심:

FQCN (full class name) 필수: NEW com.example.UserSummary(...)
생성자 시그니처 정확히 일치: 순서 / 타입
record 권장 (Java 14+, immutable)
class 도 OK: ctor + getter 만 있으면

public class UserSummary {
    private final Long id;
    private final String name;
    private final String email;

    public UserSummary(Long id, String name, String email) { ... }
    // getter
}

장점:

표준 JPQL → 모든 provider 호환
타입 안전
가장 깔끔

단점:

FQCN 길어서 가독성 낮음
DTO 변경 시 query 수정 필요

NamedConstructorResult (native query)

@SqlResultSetMapping(
    name = "UserSummaryMapping",
    classes = @ConstructorResult(
        targetClass = UserSummary.class,
        columns = {
            @ColumnResult(name = "id", type = Long.class),
            @ColumnResult(name = "name"),
            @ColumnResult(name = "email")
        }
    )
)
@NamedNativeQuery(
    name = "User.summary",
    query = "SELECT id, name, email FROM users",
    resultSetMapping = "UserSummaryMapping"
)

native query 에서 DTO 매핑. 보일러플레이트 많음.

2. Interface-Based Projection (Spring Data JPA)

public interface UserSummary {
    Long getId();
    String getName();
    String getEmail();
}

public interface UserRepository extends JpaRepository<User, Long> {
    List<UserSummary> findAllProjectedBy();
    UserSummary findByEmail(String email);
}

Spring Data 가 자동으로 proxy 만들어 매핑. getter 이름이 entity field 와 일치 필요 (snake_case 가 아니라 camelCase).

Closed projection (필드만)

public interface UserSummary {
    Long getId();
    String getName();
}

Spring Data 가 SELECT 절을 최적화 → 필요한 컬럼만 쿼리.

Open projection (SpEL)

public interface UserSummary {
    Long getId();

    @Value("#{target.firstName + ' ' + target.lastName}")
    String getFullName();
}

SpEL 사용. 단점: 전체 entity 가 로드된 후 메서드 호출 (최적화 안 됨).

3. Class-Based Projection (DTO via Spring Data)

public record UserSummary(Long id, String name, String email) {}

public interface UserRepository extends JpaRepository<User, Long> {
    List<UserSummary> findAllProjectedBy();
}

Spring Data 가 매개변수 이름 → entity field 매칭 (record 의 component 이름 활용).

Spring Data JPA 3.x+ 가 가장 자연스러움.

4. Tuple

List<Tuple> results = em.createQuery(
    "SELECT u.id AS id, u.name AS name, u.email AS email FROM User u",
    Tuple.class
).getResultList();

for (Tuple t : results) {
    Long id = t.get("id", Long.class);
    String name = t.get("name", String.class);
}

DTO 클래스 불필요. 동적 쿼리 결과에 적합. 단점: 타입 안전성 낮음 (string key + cast).

5. Dynamic Projection (Spring Data JPA)

같은 메서드를 여러 projection 으로:

public interface UserRepository extends JpaRepository<User, Long> {
    <T> List<T> findByActiveTrue(Class<T> type);
}

// 사용
List<UserSummary> summary = repo.findByActiveTrue(UserSummary.class);
List<UserDetail> detail = repo.findByActiveTrue(UserDetail.class);
List<User> entities = repo.findByActiveTrue(User.class);   // entity 전체도

가장 유연. API 응답 형태에 따라 projection 동적 선택.

5가지 방식 비교

방식	표준	Spring Data 의존	타입 안전	보일러	추천도
Constructor expression (NEW)	JPQL 표준	X	✓	중간 (FQCN)	★★★
Interface projection	Spring Data	✓	✓	낮음	★★★★
Class projection (record)	Spring Data	✓	✓	낮음	★★★★★
Tuple	JPA 표준	X	✗	낮음	★★
Dynamic (`Class<T>`)	Spring Data	✓	✓	가장 낮음	★★★★★

Spring Data JPA 환경: dynamic projection + record 가 모던 best.

자주 보는 패턴

패턴 1: 화면별 DTO

// 리스트 화면
public record UserListItem(Long id, String name, String email) {}

// 상세 화면
public record UserDetail(Long id, String name, String email, String bio, Instant createdAt, int postCount) {}

public interface UserRepository extends JpaRepository<User, Long> {
    Page<UserListItem> findByActive(boolean active, Pageable pageable);

    @Query("""
        SELECT new com.example.UserDetail(
            u.id, u.name, u.email, u.bio, u.createdAt, SIZE(u.posts))
        FROM User u WHERE u.id = :id
    """)
    UserDetail findDetailById(@Param("id") Long id);
}

각 API 요구에 맞춘 projection. entity 그대로 반환은 over-fetch.

패턴 2: 통계 / 집계

public record UserPostStat(Long userId, String name, Long postCount, Long commentCount) {}

@Query("""
    SELECT new com.example.UserPostStat(
        u.id, u.name, COUNT(DISTINCT p), COUNT(DISTINCT c))
    FROM User u
    LEFT JOIN u.posts p
    LEFT JOIN u.comments c
    GROUP BY u.id, u.name
""")
List<UserPostStat> findUserStats();

집계 결과를 record 로 직접 받음.

패턴 3: nested DTO

public record OrderSummary(Long id, OrderUser user, BigDecimal total) {
    public record OrderUser(Long id, String name) {}
}

@Query("""
    SELECT new com.example.OrderSummary(
        o.id,
        new com.example.OrderSummary$OrderUser(u.id, u.name),
        o.total)
    FROM Order o JOIN o.user u
""")
List<OrderSummary> findAllSummary();

JPQL 의 NEW 안에 NEW 가능 (Hibernate). 가독성 낮으니 interface projection 이 더 깔끔할 수도.

함정

함정 1: Open projection 의 SELECT 최적화 안 됨

public interface UserSummary {
    Long getId();
    @Value("#{target.firstName + ' ' + target.lastName}")
    String getFullName();
}

SELECT u.id, u.first_name, u.last_name, u.email, ... (전체) → 메모리에서 SpEL 평가. closed projection 이 성능 우위.

함정 2: nested entity 의 lazy 함정

public interface PostSummary {
    Long getId();
    String getTitle();
    UserSummary getAuthor();   // nested projection

    interface UserSummary {
        Long getId();
        String getName();
    }
}

Spring Data 가 JOIN 자동 추가 (closed projection). 다만 getAuthor() 가 entity 면 lazy 함정 발생 가능.

함정 3: constructor expression 의 entity 인자

SELECT new com.example.PostSummary(p.id, p.title, p.author) FROM Post p

p.author 가 entity → 전체 hydration. 의도 안 맞으면:

SELECT new com.example.PostSummary(p.id, p.title, p.author.id, p.author.name) FROM Post p

scalar 만 사용.

함정 4: COUNT(DISTINCT) + JOIN FETCH

SELECT new ... (... COUNT(DISTINCT p) ...) FROM User u LEFT JOIN u.posts p
GROUP BY u.id

u.posts 가 LAZY 면 그냥 JOIN 으로 처리됨 (FETCH 아님). 의도와 다를 수 있음. EXPLAIN 으로 확인.

함정 5: Pageable + projection

Page<UserSummary> findByActive(boolean active, Pageable pageable);

count query 가 자동 생성. complex projection 이면 count 가 비효율적. @Query 의 countQuery 옵션:

@Query(value = "SELECT new ... FROM User u JOIN u.posts p ...",
       countQuery = "SELECT COUNT(DISTINCT u) FROM User u")
Page<UserStat> findStat(Pageable pageable);

Performance: projection 의 효과

시나리오	entity 로드	projection 로드	차이
단일 필드만 사용	100% 컬럼 SELECT + lazy 필드	필요 컬럼만 SELECT	DB I/O 절감
collection 사용 안 함	LAZY proxy 생성	무관	proxy 비용 절감
dirty checking 미사용	snapshot 저장	안 함	메모리 절감
트랜잭션 종료 후 사용	`LazyInitializationException` 위험	안전 (값만)	안정성

read-heavy API 에서 큰 차이. 권장: 모든 read API 가 projection 으로 응답, entity 그대로 반환 금지.

함정과 베스트 프랙티스

entity 그대로 API 반환 금지: projection 으로 분리
record 우선: immutable + 간결
closed projection (필드만) 이 SELECT 최적화 가능
dynamic projection (Class<T>) 이 가장 유연
constructor expression 의 FQCN 보일러: static import 또는 named query 활용
nested entity 인자 피하기: scalar 만 사용
Pageable + projection 의 count query 명시: 자동 count 비효율 시
DTO 가 API 계약: schema 변경 시 versioning 신중
@Transactional(readOnly = true) 가 projection 메서드의 기본

[JPA] JPQL: Jakarta Persistence Query Language

koa (김신건) — Wed, 24 Jun 2026 00:00:00 GMT

정의

JPQL 은 Jakarta Persistence 표준의 객체 지향 쿼리 언어. 문법은 SQL 과 유사하지만 entity 와 그 필드를 대상으로 작동 (table / column 아님).

SELECT u FROM User u WHERE u.email = :email

User : entity 클래스명 (JPA 가 매핑된 table 로 변환)
u : entity alias (필수)
u.email : entity 의 field (JPA 가 column 으로 변환)

Hibernate HQL 은 JPQL 의 superset (Hibernate 전용 확장 포함). 대부분 호환.

이 페이지는 JPQL 의 핵심 문법 + 함정. DTO projection 은 [[spring-jpql-projection]], 동적 쿼리는 [[spring-jpql-dynamic-queries]] 참고.

기본 SELECT

// Entity 통째로
em.createQuery("SELECT u FROM User u", User.class).getResultList();

// Scalar
em.createQuery("SELECT u.name FROM User u", String.class).getResultList();

// Multi-value (Object[])
em.createQuery("SELECT u.id, u.name FROM User u", Object[].class).getResultList();

DISTINCT:

em.createQuery("SELECT DISTINCT u FROM User u JOIN u.orders o", User.class);

FROM (entity, alias)

SELECT u FROM User u                    -- ✓
SELECT u FROM users u                   -- ❌ table 명 아님
SELECT FROM User u                      -- ❌ alias 필수

entity 명 == 클래스 simple name (default). @Entity(name = "...") 로 변경 가능.

WHERE

SELECT u FROM User u WHERE u.age >= 18
SELECT u FROM User u WHERE u.name LIKE 'A%'
SELECT u FROM User u WHERE u.role IN ('ADMIN', 'STAFF')
SELECT u FROM User u WHERE u.deletedAt IS NULL
SELECT u FROM User u WHERE u.createdAt BETWEEN :from AND :to
SELECT u FROM User u WHERE u.email LIKE CONCAT('%', :domain)

연산자:

비교: =, <>, <, <=, >, >=
논리: AND, OR, NOT
집합: IN, NOT IN, EXISTS, NOT EXISTS, ANY, ALL, SOME
패턴: LIKE, NOT LIKE (와일드카드 %, _)
NULL: IS NULL, IS NOT NULL
범위: BETWEEN

Parameter Binding

// Named (권장)
em.createQuery("SELECT u FROM User u WHERE u.name = :name", User.class)
    .setParameter("name", "Alice")
    .getResultList();

// Positional
em.createQuery("SELECT u FROM User u WHERE u.name = ?1", User.class)
    .setParameter(1, "Alice")
    .getResultList();

Named 권장 (:name): 가독성 + 같은 파라미터 재사용 가능 + 순서 변경에 안전.

❌ String concatenation 금지 (SQL injection):

// ❌ 절대 금지
String jpql = "SELECT u FROM User u WHERE u.name = '" + name + "'";

JOIN

SELECT p FROM Post p JOIN p.author a WHERE a.email = :email

p.author = Post.author 필드 (FK relationship). JOIN condition 은 매핑이 결정 (별도 ON 불필요).

JOIN 종류

Type	의미
`JOIN` (or `INNER JOIN`)	양쪽 다 존재
`LEFT JOIN`	왼쪽 모두 + 오른쪽 match (없으면 NULL)
`JOIN FETCH`	JOIN + 연관 entity 함께 로드 (N+1 해결)
`LEFT JOIN FETCH`	LEFT JOIN + fetch

ON 절 (JPA 2.1+)

기본 JOIN 외 추가 조건:

SELECT p FROM Post p LEFT JOIN p.comments c ON c.deletedAt IS NULL

JOIN FETCH (N+1 해결)

SELECT p FROM Post p JOIN FETCH p.author

SELECT p.*, a.* FROM post p
INNER JOIN user a ON p.author_id = a.id;
-- 1쿼리에 author 까지 로드, lazy 무시

자세한 N+1 패턴: [[spring-jpa-fetch-type]] 참고.

Implicit Join (path traversal)

SELECT p FROM Post p WHERE p.author.email = :email
-- 자동으로 INNER JOIN user 추가

편하지만 의도 흐릿. 명시적 JOIN 이 가독성 좋음.

GROUP BY / HAVING

SELECT a.email, COUNT(p) FROM Post p JOIN p.author a
GROUP BY a.email
HAVING COUNT(p) > 10

집계 함수: COUNT, SUM, AVG, MIN, MAX.

ORDER BY

SELECT u FROM User u ORDER BY u.createdAt DESC, u.id ASC
SELECT u FROM User u ORDER BY u.name NULLS FIRST       -- Hibernate 확장

NULLS FIRST / NULLS LAST 는 표준 (Jakarta Persistence 3.1+).

페이징

em.createQuery("SELECT u FROM User u ORDER BY u.id", User.class)
    .setFirstResult(20)
    .setMaxResults(10)
    .getResultList();

⚠️ 컬렉션 fetch join + setMaxResults 조합 = Hibernate 가 in-memory paging 경고:

HHH000104: firstResult/maxResults specified with collection fetch; applying in memory!

전체 row 를 메모리에 로드 후 잘라냄. 큰 데이터에서 OOM. 해결:

@EntityGraph + Slice (스칼라 JOIN 만)
두 단계 query (id 만 paging → 두 번째 query 로 fetch)

Built-in Functions

String

CONCAT(a, b) 또는 a || b (Hibernate)
SUBSTRING(s, start, length)
LENGTH(s)
LOWER(s), UPPER(s)
TRIM(s), TRIM(BOTH 'x' FROM s)
LOCATE(substr, s [, from]) (1-based)

Numeric

ABS(x), MOD(x, y), SQRT(x)
SIZE(collection): WHERE SIZE(p.comments) > 5

Date / Time

CURRENT_DATE, CURRENT_TIME, CURRENT_TIMESTAMP
EXTRACT(YEAR FROM date), EXTRACT(MONTH FROM date)
LOCAL DATE, LOCAL TIME, LOCAL DATETIME (Hibernate)

CASE

SELECT u.id,
       CASE WHEN u.age < 20 THEN 'teen'
            WHEN u.age < 30 THEN 'twenties'
            ELSE 'older'
       END
FROM User u

simple case:

CASE u.country WHEN 'KR' THEN 1 WHEN 'US' THEN 2 ELSE 0 END

COALESCE / NULLIF

SELECT COALESCE(u.nickname, u.name) FROM User u
SELECT NULLIF(u.score, 0) FROM User u   -- score 가 0 이면 NULL

Subquery

-- WHERE 절
SELECT u FROM User u
WHERE u.id IN (SELECT p.author.id FROM Post p WHERE p.createdAt > :date)

-- correlated
SELECT u FROM User u
WHERE EXISTS (SELECT 1 FROM Post p WHERE p.author = u AND p.featured = true)

-- ALL / ANY
SELECT u FROM User u WHERE u.score > ALL (SELECT s.threshold FROM Setting s)

JPA 2.1+ 부터는 FROM 절 subquery 도 일부 지원 (Hibernate 6+ 가 가장 잘).

Polymorphism (TYPE, TREAT)

@Entity @Inheritance(strategy = SINGLE_TABLE)
abstract class Animal {}

@Entity @DiscriminatorValue("CAT") class Cat extends Animal { int catSpecific; }
@Entity @DiscriminatorValue("DOG") class Dog extends Animal { int dogSpecific; }

SELECT a FROM Animal a                              -- 모두
SELECT a FROM Animal a WHERE TYPE(a) = Cat          -- Cat 만
SELECT a FROM Animal a WHERE TYPE(a) IN (Cat, Dog)

-- TREAT (다운캐스트)
SELECT a FROM Animal a WHERE TREAT(a AS Cat).catSpecific > 5

상속 매핑: [[spring-jpa-inheritance]] 참고.

TypedQuery vs Query

// TypedQuery: 타입 안전
TypedQuery<User> q1 = em.createQuery("SELECT u FROM User u", User.class);
List<User> users = q1.getResultList();   // 컴파일 시 타입 확인

// Query: untyped (legacy)
Query q2 = em.createQuery("SELECT u FROM User u");
List<?> raw = q2.getResultList();   // 캐스팅 필요

항상 TypedQuery 사용. 다중 컬럼은 Object[].class 또는 DTO projection.

NamedQuery (사전 정의)

@Entity
@NamedQuery(
    name = "User.findActiveSince",
    query = "SELECT u FROM User u WHERE u.active = true AND u.createdAt > :since"
)
class User { ... }

// 사용
TypedQuery<User> q = em.createNamedQuery("User.findActiveSince", User.class);
q.setParameter("since", oneMonthAgo);
List<User> result = q.getResultList();

장점:

시작 시점 JPQL 검증 (오류 = 시작 실패)
재사용
query 가 entity 와 함께 위치 (가독성)

Spring Data JPA 의 findBy* 도 내부적으로 동등한 query 컴파일.

Bulk UPDATE / DELETE

UPDATE User u SET u.active = false WHERE u.lastLogin < :cutoff
DELETE FROM User u WHERE u.deletedAt < :purgeBefore

em.createQuery("UPDATE User u SET u.active = false WHERE u.lastLogin < :cutoff")
    .setParameter("cutoff", oneYearAgo)
    .executeUpdate();

⚠️ 함정:

PersistenceContext 우회: 이미 managed 인 entity 와 동기화 안 됨. em.clear() 필요
cascade 무시: DELETE FROM Order 가 OrderItem 까지 안 지움. 자식 먼저 삭제 또는 native + ON DELETE CASCADE
dirty checking 우회: Hibernate 의 @Version 도 무시 (직접 set 필요)
@Modifying 어노테이션: Spring Data JPA 에서 필수

@Modifying
@Query("UPDATE User u SET u.active = false WHERE u.lastLogin < :cutoff")
int deactivateInactive(@Param("cutoff") LocalDate cutoff);

Native Query

JPQL 로 표현 안 되는 DB 특수 기능:

List<User> users = em.createNativeQuery(
    "SELECT * FROM users WHERE created_at > NOW() - INTERVAL '7 days'",
    User.class
).getResultList();

Postgres 의 INTERVAL, JSONB ->
Window function (ROW_NUMBER() OVER)
CTE (WITH x AS (...))
DB-specific dialect

단점: DB 종속, JPA 추상화 깨짐. 가능하면 JPQL 우선.

@SqlResultSetMapping 으로 결과 매핑:

@SqlResultSetMapping(
    name = "UserStats",
    classes = @ConstructorResult(
        targetClass = UserStat.class,
        columns = { @ColumnResult(name = "id", type = Long.class),
                    @ColumnResult(name = "post_count", type = Long.class) }
    )
)
@NamedNativeQuery(
    name = "User.stats",
    query = "SELECT u.id, COUNT(p.id) AS post_count FROM users u LEFT JOIN posts p ON p.author_id = u.id GROUP BY u.id",
    resultSetMapping = "UserStats"
)

Spring Data JPA 통합

public interface UserRepository extends JpaRepository<User, Long> {
    // 1. Query method (자동 생성)
    List<User> findByActiveTrue();

    // 2. @Query (JPQL)
    @Query("SELECT u FROM User u WHERE u.email LIKE %:domain")
    List<User> findByEmailDomain(@Param("domain") String domain);

    // 3. @Query nativeQuery
    @Query(value = "SELECT * FROM users WHERE age > :min", nativeQuery = true)
    List<User> findOlderThan(@Param("min") int min);

    // 4. Modifying (bulk)
    @Modifying
    @Query("UPDATE User u SET u.active = false WHERE u.lastLogin < :cutoff")
    int deactivate(@Param("cutoff") LocalDate cutoff);

    // 5. Pageable
    @Query("SELECT u FROM User u WHERE u.active = :active")
    Page<User> findByActive(@Param("active") boolean active, Pageable pageable);
}

함정과 베스트 프랙티스

entity 명 == 클래스명 (default): table 명 쓰면 에러
alias 필수: FROM User u
Named parameter (:name) 우선: positional 보다 가독성
String concatenation 절대 금지: SQL injection
컬렉션 fetch join + Pageable = 메모리 paging: warning 무시 위험
bulk update / delete 는 PC 우회: em.clear() + cascade 직접 처리
@Modifying 빠뜨리지 말 것 (Spring Data JPA)
NamedQuery 로 startup 검증: 운영 안전망
TypedQuery 만 사용: 컴파일 타입 안전
Implicit join (p.author.email) 보다 명시적 JOIN: 가독성
TYPE() / TREAT() 가 polymorphic query 의 표준

[JPA] 동적 쿼리: Criteria API, QueryDSL, Specification

koa (김신건) — Wed, 24 Jun 2026 00:00:00 GMT

정의

동적 쿼리 = 런타임 조건에 따라 WHERE / JOIN 이 달라지는 쿼리. 검색 필터, admin 도구, 리포팅 등에서 흔함.

// 정적: 모든 조건이 query 에 박혀 있음
List<User> findActiveByEmail(String email);

// 동적: 사용자 입력에 따라 조건 추가 / 제거
List<User> search(@Nullable String email, @Nullable String city, @Nullable Integer minAge, ...);

JPQL string concatenation 으로 만들 수도 있지만:

SQL injection 위험
가독성 ↓ (분기마다 + ” AND …”)
컴파일 타임 검증 X

해결책 3가지:

Criteria API (JPA 표준)
QueryDSL (가장 인기)
Spring Data Specification (Criteria API 의 래퍼)

각자 트레이드오프.

비교 한눈에

항목	Criteria API	QueryDSL	Specification
표준	JPA 표준	Third-party	Spring Data
가독성	낮음 (verbose)	높음 (SQL-like)	중간
타입 안전	부분 (metamodel 필요)	완전 (Q 클래스 생성)	부분
빌드 의존	없음 (또는 annotation processor)	annotation processor	없음
동적 조립	가능 (장황)	매우 쉬움 (`BooleanBuilder`)	가능 (`Specification.where`)
Spring 통합	직접	별도 설정	native
학습 곡선	가파름	완만	완만

현실: 새 프로젝트라면 QueryDSL 또는 Specification, legacy 코드면 Criteria API.

Criteria API 기본

@PersistenceContext
EntityManager em;

public List<User> search(String name, Integer minAge) {
    CriteriaBuilder cb = em.getCriteriaBuilder();
    CriteriaQuery<User> cq = cb.createQuery(User.class);
    Root<User> u = cq.from(User.class);

    List<Predicate> predicates = new ArrayList<>();
    if (name != null) {
        predicates.add(cb.like(u.get("name"), "%" + name + "%"));
    }
    if (minAge != null) {
        predicates.add(cb.greaterThanOrEqualTo(u.get("age"), minAge));
    }
    cq.where(predicates.toArray(new Predicate[0]));
    cq.orderBy(cb.desc(u.get("createdAt")));

    return em.createQuery(cq).getResultList();
}

문제:

u.get("name") : string 기반 (타입 안전 X, 오타 위험)
길고 verbose

해결: JPA Metamodel

hibernate-jpamodelgen 같은 annotation processor 가 User_ 같은 metamodel 생성:

annotationProcessor("org.hibernate.orm:hibernate-jpamodelgen")

// 자동 생성: User_.java
predicates.add(cb.like(u.get(User_.name), "%" + name + "%"));      // 타입 안전
predicates.add(cb.greaterThanOrEqualTo(u.get(User_.age), minAge));

여전히 boilerplate 많지만 타입 안전 ✓.

JOIN with Criteria

Join<User, Post> post = u.join("posts");
cq.select(u).where(cb.gt(cb.count(post), 10L));
cq.groupBy(u.get("id"));

JPQL 의 JOIN u.posts p 대응. fluent 하지만 가독성 ↓.

QueryDSL (가장 인기)

annotation processor 가 Q 클래스 자동 생성:

annotationProcessor("com.querydsl:querydsl-apt:5.0.0:jakarta")
annotationProcessor("jakarta.persistence:jakarta.persistence-api")
implementation("com.querydsl:querydsl-jpa:5.0.0:jakarta")

./gradlew compileJava → QUser, QPost 자동 생성.

@Repository
public class UserRepository {
    @PersistenceContext EntityManager em;

    public List<User> search(String name, Integer minAge, String city) {
        JPAQueryFactory query = new JPAQueryFactory(em);
        QUser u = QUser.user;

        return query.selectFrom(u)
            .where(
                nameContains(name),
                ageGoe(minAge),
                cityEq(city)
            )
            .orderBy(u.createdAt.desc())
            .fetch();
    }

    private BooleanExpression nameContains(String name) {
        return name == null ? null : QUser.user.name.contains(name);
    }
    private BooleanExpression ageGoe(Integer age) {
        return age == null ? null : QUser.user.age.goe(age);
    }
    private BooleanExpression cityEq(String city) {
        return city == null ? null : QUser.user.city.eq(city);
    }
}

핵심: where() 에 null 전달하면 자동 무시 → 동적 쿼리 자연스러움. 메서드 분리로 재사용성 ↑.

QueryDSL + projection

public record UserSummary(Long id, String name, String email) {}

List<UserSummary> result = query
    .select(Projections.constructor(UserSummary.class, u.id, u.name, u.email))
    .from(u)
    .fetch();

// 또는 Projections.fields, Projections.bean

또는 직접 record constructor:

.select(new QUserSummary(u.id, u.name, u.email))   // Q-class for DTO

QueryDSL + Pageable

public Page<User> search(Pageable pageable) {
    JPAQueryFactory query = new JPAQueryFactory(em);
    QUser u = QUser.user;

    JPAQuery<User> base = query.selectFrom(u).where(predicates);

    List<User> content = base
        .offset(pageable.getOffset())
        .limit(pageable.getPageSize())
        .fetch();

    Long total = query.select(u.count()).from(u).where(predicates).fetchOne();

    return new PageImpl<>(content, pageable, total != null ? total : 0L);
}

count query 직접. Spring Data + QuerydslPredicateExecutor 통합도 가능.

Spring Data Specification

Spring Data 가 Criteria API 를 functional 하게 래핑:

public interface UserRepository extends JpaRepository<User, Long>, JpaSpecificationExecutor<User> {}

public class UserSpecs {
    public static Specification<User> nameContains(String name) {
        return (root, query, cb) -> name == null ? null : cb.like(root.get("name"), "%" + name + "%");
    }
    public static Specification<User> ageGoe(Integer minAge) {
        return (root, query, cb) -> minAge == null ? null : cb.greaterThanOrEqualTo(root.get("age"), minAge);
    }
    public static Specification<User> cityEq(String city) {
        return (root, query, cb) -> city == null ? null : cb.equal(root.get("city"), city);
    }
}

// 사용
List<User> users = userRepo.findAll(
    Specification.where(UserSpecs.nameContains(name))
        .and(UserSpecs.ageGoe(minAge))
        .and(UserSpecs.cityEq(city))
);

장점:

Spring Data 통합 (findAll, findOne, count, page)
별도 의존성 없음
composition (.and, .or, .not)

단점:

여전히 Criteria API 의 verbose 한 syntax

Specification 의 함수형 활용

public static Specification<User> matching(UserSearchCriteria c) {
    return Specification
        .where(nameContains(c.name()))
        .and(ageGoe(c.minAge()))
        .and(cityEq(c.city()))
        .and(activeIsTrue());
}

userRepo.findAll(matching(criteria), pageable);

검색 조건 객체 + Specification factory → 깔끔한 사용처.

QueryDSL 의 동적 조립 패턴

BooleanBuilder 사용:

BooleanBuilder builder = new BooleanBuilder();
if (name != null) builder.and(u.name.contains(name));
if (minAge != null) builder.and(u.age.goe(minAge));
if (city != null) builder.and(u.city.eq(city));

List<User> result = query.selectFrom(u).where(builder).fetch();

또는 where() 의 multi-arg + null 자동 무시 (앞 예시).

QueryDSL Subquery

JPAQuery<?> sub = JPAExpressions
    .select(post.author.id)
    .from(post)
    .where(post.createdAt.after(oneMonthAgo));

List<User> activeAuthors = query
    .selectFrom(u)
    .where(u.id.in(sub))
    .fetch();

QueryDSL CASE

NumberExpression<Integer> rank = new CaseBuilder()
    .when(u.score.gt(100)).then(1)
    .when(u.score.gt(50)).then(2)
    .otherwise(3);

query.select(u.name, rank).from(u).orderBy(rank.asc()).fetch();

CASE 표현식. JPQL 보다 자연스러움.

QueryDSL 의 native 함정 회피

// JPQL: 컬렉션 fetch join + Pageable = 메모리 paging
query.selectFrom(u).leftJoin(u.posts).fetchJoin()
    .offset(0).limit(10).fetch();   // ⚠️ 같은 함정

해결: 두 단계 query

// 1. id 만 페이징
List<Long> ids = query.select(u.id)
    .from(u)
    .where(...)
    .orderBy(u.createdAt.desc())
    .offset(pageable.getOffset())
    .limit(pageable.getPageSize())
    .fetch();

// 2. id 로 fetch join
List<User> users = query.selectFrom(u)
    .leftJoin(u.posts).fetchJoin()
    .where(u.id.in(ids))
    .orderBy(u.createdAt.desc())
    .fetch();

어떤 걸 골라야?

새 프로젝트?
├─ Spring Data 사용 + 간단한 동적 쿼리 → Specification
├─ 복잡한 동적 쿼리 + 가독성 우선 → QueryDSL
└─ 표준 우선 + verbosity 감수 → Criteria API

레거시 / 기존 코드?
├─ 이미 QueryDSL → 그대로 유지
├─ Criteria API → metamodel + 부분 리팩토링
└─ string JPQL concatenation → QueryDSL 마이그레이션 강력 권장

실무에서 가장 흔한 조합: Spring Data JPA + Specification (간단한 검색) + QueryDSL (복잡한 동적 / 통계 쿼리).

함정과 베스트 프랙티스

string concatenation 절대 금지: SQL injection + 컴파일 검증 X
QueryDSL 의 Q 클래스 빌드 캐싱 주의: gradle clean 후 재생성
Specification 의 (root, query, cb) -> null 패턴: 조건 없음 표현
Specification.where(null) 도 안전 (null 이면 모두 매칭)
Pageable + JOIN FETCH: 둘 다에서 메모리 paging 함정 동일
QueryDSL Projection.fields vs constructor: bean 기반은 setter 필요, record 면 constructor
subquery 는 IN 절 한정: WHERE EXISTS / NOT EXISTS 가 인덱스 활용 더 좋음
count query 명시: 큰 결과셋 + complex projection 시 자동 count 비효율
읽기 전용 쿼리는 @Transactional(readOnly = true): dirty checking 비용 절감

[JPA] @Embeddable, @Embedded, @Converter

koa (김신건) — Tue, 23 Jun 2026 00:00:00 GMT

정의

@Embeddable 은 별도 테이블 없이 entity 의 일부로 포함되는 값 객체 (Value Object). 같은 의미적 그룹의 필드들을 하나의 클래스로 추출.

AttributeConverter 는 entity 필드와 DB 컬럼 사이의 타입 변환 을 정의. 직렬화 / enum 매핑 / 암호화 / JSON 컬럼 처리에 사용.

둘 다 entity 의 표현력을 높이는 도구. 라이프사이클은 부모 entity 와 동일.

@Embeddable 기본

@Embeddable
public class Address {
    private String city;
    private String street;
    private String zipCode;

    protected Address() {}   // JPA 요구

    public Address(String city, String street, String zipCode) {
        this.city = city;
        this.street = street;
        this.zipCode = zipCode;
    }

    // getter / equals / hashCode
}

@Entity
class User {
    @Id Long id;
    String name;

    @Embedded
    Address address;
}

생성되는 DDL:

CREATE TABLE user (
    id        BIGINT PRIMARY KEY,
    name      VARCHAR(255),
    city      VARCHAR(255),
    street    VARCHAR(255),
    zip_code  VARCHAR(255)
);

별도 테이블 없음. 모든 컬럼이 user 테이블에 같이 들어감.

@AttributeOverride

같은 @Embeddable 을 한 entity 에서 여러 번 쓸 때 컬럼명 충돌 방지:

@Entity
class Order {
    @Id Long id;

    @Embedded
    Address billingAddress;

    @Embedded
    @AttributeOverrides({
        @AttributeOverride(name = "city",    column = @Column(name = "shipping_city")),
        @AttributeOverride(name = "street",  column = @Column(name = "shipping_street")),
        @AttributeOverride(name = "zipCode", column = @Column(name = "shipping_zip"))
    })
    Address shippingAddress;
}

billing 은 city/street/zip_code, shipping 은 shipping_city 등으로 매핑.

값 객체로서의 의미

// ❌ primitive 의 잔치
@Entity
class User {
    String addressCity;
    String addressStreet;
    String addressZipCode;
    String workCity;
    String workStreet;
    // ... 매번 도시 검증 로직 반복
}

// ✓ 의미 단위로 묶고 동작 부여
@Embeddable
class Address {
    String city, street, zipCode;
    public boolean isInSameCity(Address other) {
        return Objects.equals(city, other.city);
    }
}

DDD 의 Value Object 개념과 자연스럽게 매핑. 불변으로 만들면 동시성 안전.

불변 Address

@Embeddable
public class Address {
    @Column(updatable = false) private String city;
    @Column(updatable = false) private String street;
    @Column(updatable = false) private String zipCode;
    // setter 없음, 생성자만
}

또는 record (Hibernate 6+ 부분 지원):

@Embeddable
public record Address(String city, String street, String zipCode) {}

AttributeConverter

entity 필드 ↔ DB 컬럼 타입 변환:

@Converter
public class BooleanToYNConverter implements AttributeConverter<Boolean, String> {
    @Override
    public String convertToDatabaseColumn(Boolean attr) {
        return Boolean.TRUE.equals(attr) ? "Y" : "N";
    }

    @Override
    public Boolean convertToEntityAttribute(String db) {
        return "Y".equals(db);
    }
}

@Entity
class User {
    @Convert(converter = BooleanToYNConverter.class)
    boolean active;
}

DB 에 Y/N 저장, 자바에서 boolean 사용. legacy DB 호환에 흔함.

autoApply

@Converter(autoApply = true)
public class BooleanToYNConverter implements AttributeConverter<Boolean, String> { ... }

autoApply = true 면 같은 타입 (Boolean) 의 모든 필드에 자동 적용. @Convert 명시 불필요. 대신 의도와 다른 곳에도 적용될 위험.

흔한 Converter 패턴

enum 매핑

public enum Role { ADMIN, USER, GUEST }

@Converter(autoApply = true)
public class RoleConverter implements AttributeConverter<Role, String> {
    @Override
    public String convertToDatabaseColumn(Role r) {
        return r == null ? null : r.name();
    }

    @Override
    public Role convertToEntityAttribute(String db) {
        return db == null ? null : Role.valueOf(db);
    }
}

JPA 의 @Enumerated(EnumType.STRING) 으로도 가능하지만, converter 가 더 명시적 (DB 값 변경 시 안전).

List<String> → CSV

@Converter
public class StringListConverter implements AttributeConverter<List<String>, String> {
    @Override
    public String convertToDatabaseColumn(List<String> list) {
        return list == null ? null : String.join(",", list);
    }

    @Override
    public List<String> convertToEntityAttribute(String db) {
        return db == null || db.isEmpty() ? List.of() : List.of(db.split(","));
    }
}

@Entity
class Post {
    @Convert(converter = StringListConverter.class)
    List<String> tags;
}

작은 컬렉션을 한 컬럼으로. 검색 못 하는 게 단점 (별도 테이블이 정석).

JSON 컬럼 (PostgreSQL JSONB)

<CodeWithOutput language=“java” outputLanguage=“text” outputLabel=“DB row” code={`@Converter public class JsonbConverter implements AttributeConverter<Map<String, Object>, String> { static final ObjectMapper M = new ObjectMapper();

@Override
public String convertToDatabaseColumn(Map<String, Object> attr) {
    try { return M.writeValueAsString(attr); }
    catch (Exception e) { throw new IllegalArgumentException(e); }
}

@Override
public Map<String, Object> convertToEntityAttribute(String db) {
    if (db == null) return Map.of();
    try { return M.readValue(db, new TypeReference<>() {}); }
    catch (Exception e) { throw new IllegalArgumentException(e); }
}

}

@Entity class Event { @Convert(converter = JsonbConverter.class) @Column(columnDefinition = “jsonb”) Map<String, Object> payload; }} output={— INSERT INSERT INTO event (payload) VALUES (’{“userId”:42,“action”:“login”}’); — 컬럼 타입은 jsonb (PostgreSQL native JSON)`} />

Hibernate Types 라이브러리 (hypersistence-utils) 가 더 본격적인 JSONB 지원. 위 converter 는 간단한 경우.

암호화 컬럼

@Converter
public class EncryptedStringConverter implements AttributeConverter<String, String> {
    @Override
    public String convertToDatabaseColumn(String plain) {
        return Crypto.encrypt(plain);
    }

    @Override
    public String convertToEntityAttribute(String encrypted) {
        return Crypto.decrypt(encrypted);
    }
}

@Entity
class User {
    @Convert(converter = EncryptedStringConverter.class)
    String ssn;   // DB 에는 암호화돼 저장, 자바에는 평문
}

Spring 의 spring-security-rsa / Vault 와 조합. Hibernate 6+ 의 @ColumnTransformer 도 비슷.

@Embeddable 의 함정

equals / hashCode 필수

값 객체이므로 동등성은 필드 값 기준:

@Embeddable
class Address {
    String city, street, zipCode;

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Address a)) return false;
        return Objects.equals(city, a.city) && Objects.equals(street, a.street) && Objects.equals(zipCode, a.zipCode);
    }

    @Override
    public int hashCode() {
        return Objects.hash(city, street, zipCode);
    }
}

equals 가 없으면 dirty checking 이 항상 변경됐다고 판단 → 매번 UPDATE.

null 표현

모든 @Embeddable 필드가 null 이면 Hibernate 는 객체 자체를 null 로 취급. 일부만 null 이면 Address(city=Seoul, street=null, zipCode=null) 같은 부분 null 인스턴스.

@EmbeddedId

복합 키로도 사용 가능:

@Embeddable
class OrderItemId implements Serializable {
    @Column(name = "order_id") Long orderId;
    @Column(name = "product_id") Long productId;

    // equals + hashCode 필수
}

@Entity
class OrderItem {
    @EmbeddedId
    OrderItemId id;
}

복합 키 entity 는 Spring Data JPA 의 JpaRepository<OrderItem, OrderItemId> 처럼 ID 타입에 @EmbeddedId 클래스를 지정.

Converter 의 함정

@Convert 와 @Enumerated 동시 사용 금지: 한쪽만
Converter 안에서 다른 service 호출 금지: 매 SELECT/INSERT 마다 호출됨
autoApply = true 와 framework 어노테이션 충돌: 의도와 다른 곳에 적용될 수 있음
null 처리 명시적: convertToDatabaseColumn(null) 호출 가능
@Lob / @JdbcTypeCode 가 더 적합한 경우 있음 (CLOB, JSON 등)
검색 안 됨: List → CSV 같은 변환은 LIKE 검색만 가능, 정확한 매칭 불가능

함정과 베스트 프랙티스

@Embeddable 는 protected no-args ctor + final fields 권장
equals/hashCode 잊지 말 것 (dirty checking 영향)
@AttributeOverride 로 컬럼 재사용
AttributeConverter 는 stateless: 다른 Bean 주입 금지
JSON 컬럼은 hypersistence-utils 가 더 본격적
legacy DB 호환에 converter 가 가장 깔끔

[JPA] CascadeType과 orphanRemoval

koa (김신건) — Tue, 23 Jun 2026 00:00:00 GMT

정의

JPA 의 entity 연산 (persist, merge, remove, refresh, detach) 을 연관 entity 에 자동 전파 하는 메커니즘. @OneToMany(cascade = CascadeType.ALL) 같이 선언.

별개 개념인 orphanRemoval 은 부모 컬렉션에서 자식이 빠지면 자식 자체를 삭제. cascade = REMOVE 와 비슷해 보이지만 트리거 조건이 다르다.

잘못 쓰면:

ALL cascade + 양방향 연관 → 의도치 않은 삭제
orphanRemoval + 컬렉션 재할당 → 전체 삭제 후 재삽입

CascadeType 6가지

Type	전파되는 연산
`PERSIST`	`em.persist(parent)` 시 child 도 persist
`MERGE`	`em.merge(parent)` 시 child 도 merge
`REMOVE`	`em.remove(parent)` 시 child 도 remove
`REFRESH`	`em.refresh(parent)` 시 child 도 refresh
`DETACH`	`em.detach(parent)` 시 child 도 detach
`ALL`	위 다섯 + 향후 추가될 모든 cascade

기본은 cascade 없음. 명시적으로 설정해야 전파.

PERSIST cascade 예

@Entity
class Post {
    @Id @GeneratedValue Long id;
    String title;

    @OneToMany(mappedBy = "post", cascade = CascadeType.PERSIST)
    List<Comment> comments = new ArrayList<>();

    public void addComment(Comment c) {
        comments.add(c);
        c.setPost(this);
    }
}

@Entity
class Comment {
    @Id @GeneratedValue Long id;
    String body;
    @ManyToOne Post post;
}

cascade 없으면 TransientObjectException: comment 가 transient 상태인데 post 가 참조한다고 에러.

REMOVE cascade 와 함정

@OneToMany(mappedBy = "post", cascade = CascadeType.REMOVE)
List<Comment> comments;

em.remove(post) → 모든 comments 도 DELETE.

함정: 양방향 + 다른 entity 와 공유되면 의도치 않은 삭제:

@ManyToOne(cascade = CascadeType.REMOVE)   // ❌ 위험
User user;

em.remove(post) 호출 시 그 post 의 user 까지 삭제됨. user 가 다른 post 의 부모일 수도 있는데. @ManyToOne / @ManyToMany 에 REMOVE cascade 는 거의 항상 잘못된 설계.

규칙:

@OneToMany, @OneToOne 의 소유자 → 종속물 관계에만 REMOVE 적합
@ManyToOne, @ManyToMany 에 REMOVE 금지

orphanRemoval

부모의 컬렉션에서 자식이 제거 되면 자식 자체를 DELETE:

@OneToMany(mappedBy = "post", orphanRemoval = true)
List<Comment> comments;

cascade = REMOVE 와 다른 점:

cascade = REMOVE: 부모 자체가 삭제될 때만 트리거
orphanRemoval = true: 부모-자식 참조 관계가 끊어질 때마다 트리거 (부모는 살아 있어도)

cascade = ALL, orphanRemoval = true 조합이 가장 흔함: aggregate root 의 종속 entity 처럼 동작.

orphanRemoval 함정: 컬렉션 재할당

// ❌ 위험
post.comments = new ArrayList<>(newComments);

orphanRemoval = true 면 기존 컬렉션의 모든 원소가 orphan 으로 인식 → 전체 DELETE → 새로 INSERT. 변경된 원소만 update 하려는 의도와 다름.

올바른 패턴:

post.comments.clear();
post.comments.addAll(newComments);
// 또는 retainAll / removeAll 로 diff

양방향 연관과 cascade

@Entity
class Post {
    @OneToMany(mappedBy = "post", cascade = ALL, orphanRemoval = true)
    List<Comment> comments = new ArrayList<>();

    public void addComment(Comment c) {
        comments.add(c);
        c.setPost(this);   // 양방향 동기화 필수
    }

    public void removeComment(Comment c) {
        comments.remove(c);
        c.setPost(null);   // orphanRemoval 가 인식할 수 있게
    }
}

addComment / removeComment 같은 편의 메서드 로 양방향 일관성 유지. 직접 양쪽 setter 호출은 누락 위험.

CascadeType.MERGE 의 묘한 동작

merge 는 새 managed 인스턴스를 반환한다. cascade MERGE 가 있으면 자식도 merge 됨:

Post detached = ...;
detached.getComments().add(new Comment("new"));

@Transactional
public void update(Post detached) {
    Post managed = em.merge(detached);     // cascade MERGE 면 comments 도 merge
    // detached.getComments() 의 객체들은 여전히 detached
    // managed.getComments() 의 객체들이 새 managed
}

@Modifying @Query 로 직접 UPDATE 하면 cascade 도 dirty checking 도 안 일어남. 의도적으로 우회할 때만 사용.

종합 비교

시나리오	cascade	orphanRemoval
부모 persist 시 자식도 INSERT	PERSIST 또는 ALL	-
부모 remove 시 자식도 DELETE	REMOVE 또는 ALL	-
컬렉션에서 빠지면 자식 DELETE	-	true
부모 = aggregate root, 자식은 독립 의미 없음	ALL	true
외래키만 공유하는 독립 entity (User, Category)	(없음)	false

시나리오별 선택

시나리오 1: Order ↔ OrderItem (소유 관계)

OrderItem 은 Order 없이는 의미 없음. Order 삭제 → OrderItem 삭제 자연스러움. 컬렉션에서 빼면 DB 에서도 삭제.

@Entity
class Order {
    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
    List<OrderItem> items = new ArrayList<>();
}

cascade = ALL + orphanRemoval = true 조합. DDD aggregate root 패턴.

시나리오 2: Post ↔ Comment (느슨한 소유)

Comment 도 Post 종속이지만 한 번에 삭제하기엔 너무 많을 수 있음 (수십만 댓글). 대용량 환경:

@Entity
class Post {
    @OneToMany(mappedBy = "post", cascade = {PERSIST, MERGE})   // REMOVE 제외
    List<Comment> comments = new ArrayList<>();
}

Post 삭제 시 별도 batch / soft delete 패턴 사용. cascade REMOVE 면 트랜잭션이 거대해짐.

시나리오 3: Post ↔ Tag (다대다, 독립 entity)

Tag 는 여러 Post 가 공유. Post 삭제해도 Tag 살아야:

@Entity
class Post {
    @ManyToMany   // cascade 없음
    @JoinTable(name = "post_tag")
    Set<Tag> tags = new HashSet<>();
}

조인 테이블 row 만 정리됨. Tag 자체는 보존.

시나리오 4: Book ↔ BookCover (1:1 소유)

@Entity
class Book {
    @OneToOne(mappedBy = "book", cascade = ALL, orphanRemoval = true, fetch = LAZY, optional = false)
    BookCover cover;
}

optional = false + bytecode enhancement 로 LAZY 도 작동.

시나리오 5: User ↔ Profile (1:1, 분리 가능)

Profile 이 별도 의미 있으면 cascade 제한적:

@Entity
class User {
    @OneToOne(mappedBy = "user", cascade = PERSIST)   // 자동 저장만, 삭제는 명시적
    Profile profile;
}

시나리오 6: 양방향 동기화 편의 메서드

cascade 가 작동하려면 컬렉션 조작도 일관성 있게:

@Entity
class Order {
    @OneToMany(mappedBy = "order", cascade = ALL, orphanRemoval = true)
    List<OrderItem> items = new ArrayList<>();

    public void addItem(Product product, int qty) {
        OrderItem item = new OrderItem(this, product, qty);
        items.add(item);    // 양방향 동기화
    }

    public void removeItem(OrderItem item) {
        items.remove(item);
        item.detachFromOrder();   // orphan 으로 만들기
    }

    public void clearItems() {
        // ❌ items = new ArrayList<>() → 전체 orphan, 폭탄 INSERT
        // ✓
        items.clear();
    }
}

시나리오 7: 벌크 삭제는 cascade 우회

// JPQL 벌크 삭제는 cascade 무시
em.createQuery("DELETE FROM Order WHERE createdAt < :date")
  .setParameter("date", oneYearAgo)
  .executeUpdate();
// → OrderItem 은 그대로 남음! 외래키 위반.

해결: 자식 먼저 삭제하거나 native SQL + ON DELETE CASCADE 사용.

자주 보는 패턴

Aggregate Root

@Entity
class Order {
    @OneToMany(mappedBy = "order", cascade = ALL, orphanRemoval = true)
    List<OrderItem> items = new ArrayList<>();

    public void addItem(Product p, int qty) {
        items.add(new OrderItem(this, p, qty));
    }

    public void removeItem(OrderItem i) {
        items.remove(i);
    }
}

OrderItem 은 Order 외부에서 의미 없음 → 라이프사이클 일체. DDD aggregate root 패턴과 자연스럽게 매핑.

독립 entity 참조

@Entity
class Post {
    @ManyToOne                              // cascade 없음
    @JoinColumn(name = "category_id")
    Category category;
}

Category 는 Post 와 독립. Post 삭제해도 Category 살아있어야 함 = cascade 없음.

함정과 베스트 프랙티스

cascade = ALL 은 @OneToMany, @OneToOne 의 소유자에만
@ManyToOne / @ManyToMany 에 REMOVE 절대 금지
양방향 연관은 편의 메서드로 동기화
orphanRemoval + 컬렉션 재할당은 전체 삭제 + 재삽입 폭탄
@Modifying @Query 는 cascade 우회: 의도가 아니면 사용 금지
벌크 삭제 시 cascade 무시됨: delete from Order JPQL 은 자식 cascade 안 일어남. 직접 자식 먼저 삭제
flush 와 clear 사이 cascade 동작: 큰 그래프 persist 시 메모리 주의

[JPA] Entity Lifecycle Callbacks와 Auditing

koa (김신건) — Tue, 23 Jun 2026 00:00:00 GMT

정의

Entity 의 라이프사이클 (persist / update / load / remove) 특정 시점에 자동 호출되는 메서드. 두 가지 형태:

Entity 내부 메서드: @PrePersist, @PostPersist, @PreUpdate, @PostUpdate, @PostLoad, @PreRemove, @PostRemove
외부 listener 클래스: @EntityListeners(MyListener.class)

Spring Data 의 Auditing (@CreatedDate, @LastModifiedDate, @CreatedBy, @LastModifiedBy) 가 이걸 활용한 대표 사례.

7가지 콜백

어노테이션	호출 시점
`@PrePersist`	INSERT 직전 (em.persist 호출 직후 ~ INSERT 직전)
`@PostPersist`	INSERT 직후 (id 채워진 뒤)
`@PreUpdate`	UPDATE 직전 (dirty checking flush 시점)
`@PostUpdate`	UPDATE 직후
`@PreRemove`	DELETE 직전 (em.remove 호출 시점)
`@PostRemove`	DELETE 직후
`@PostLoad`	SELECT 후 entity 채워진 직후

Entity 내부 콜백

@Entity
class User {
    @Id Long id;
    String email;

    @Column(nullable = false, updatable = false)
    LocalDateTime createdAt;

    @Column(nullable = false)
    LocalDateTime updatedAt;

    @PrePersist
    void onCreate() {
        createdAt = updatedAt = LocalDateTime.now();
    }

    @PreUpdate
    void onUpdate() {
        updatedAt = LocalDateTime.now();
    }
}

EntityListener (외부 클래스)

여러 entity 에 같은 로직 적용:

public class AuditListener {
    @PrePersist
    public void onCreate(Object entity) {
        if (entity instanceof Auditable a) {
            a.setCreatedAt(LocalDateTime.now());
            a.setUpdatedAt(LocalDateTime.now());
        }
    }

    @PreUpdate
    public void onUpdate(Object entity) {
        if (entity instanceof Auditable a) {
            a.setUpdatedAt(LocalDateTime.now());
        }
    }
}

@Entity
@EntityListeners(AuditListener.class)
class User implements Auditable { ... }

Listener 안에서는 다른 entity 의 EntityManager 호출 금지 (재귀 flush 위험).

Spring Data Auditing

대부분의 경우 직접 콜백을 안 쓰고 Spring Data 의 AuditingEntityListener 사용:

@Configuration
@EnableJpaAuditing
public class JpaConfig {
    @Bean
    public AuditorAware<String> auditorAware() {
        return () -> Optional.ofNullable(SecurityContextHolder.getContext().getAuthentication())
            .filter(Authentication::isAuthenticated)
            .map(Authentication::getName);
    }
}

@MappedSuperclass
@EntityListeners(AuditingEntityListener.class)
public abstract class BaseTimeEntity {
    @CreatedDate
    @Column(nullable = false, updatable = false)
    LocalDateTime createdAt;

    @LastModifiedDate
    @Column(nullable = false)
    LocalDateTime updatedAt;

    @CreatedBy
    @Column(updatable = false)
    String createdBy;

    @LastModifiedBy
    String updatedBy;
}

@Entity
class User extends BaseTimeEntity {
    @Id Long id;
    String email;
}

@CreatedDate / @LastModifiedDate 는 시간, @CreatedBy / @LastModifiedBy 는 AuditorAware 가 반환한 값으로 자동 채워짐. 일반적으로 현재 로그인 사용자.

@MappedSuperclass 와 조합이 자연스러움 ([[spring-jpa-inheritance]]).

@PostLoad 활용

SELECT 직후 후처리:

@Entity
class User {
    String firstName;
    String lastName;

    @Transient
    String fullName;   // DB 에 없는 derived field

    @PostLoad
    void compose() {
        fullName = firstName + " " + lastName;
    }
}

매번 SELECT 후 자동. 단, dirty checking 대상 아님 (@Transient 라).

암호화 컬럼 복호화에도 사용:

@PostLoad
void decryptSensitive() {
    this.ssn = Crypto.decrypt(this.encryptedSsn);
}

AttributeConverter ([[spring-jpa-embedded-converter]]) 가 더 깔끔하긴 함.

콜백의 함정

트랜잭션 안에서만 호출됨

flush 시점에 호출되므로 트랜잭션 필수. 트랜잭션 없이 em.persist 호출하면 콜백도 안 일어남.

다른 entity 호출 금지

@PrePersist
void wrong() {
    em.persist(new AuditLog(...));   // ❌ 재귀 flush
}

콜백 안에서 EntityManager 작업 시 무한 루프 또는 ConcurrentModificationException. 대안: ApplicationEvent 발행해 트랜잭션 commit 후 처리 (@TransactionalEventListener).

dirty checking 와의 상호작용

@PreUpdate 안에서 필드 변경하면 그 변경도 UPDATE 에 포함. 단, 다시 dirty checking 이 일어나진 않음 (한 번의 flush 안에서 두 번 안 돌아감). 의도된 동작이지만 헷갈림.

상속 시 콜백 순서

부모 entity / @MappedSuperclass 의 콜백이 자식보다 먼저:

@PrePersist on @MappedSuperclass
   ↓
@PrePersist on parent entity (@Inheritance)
   ↓
@PrePersist on child entity
   ↓
EntityListener @PrePersist (@EntityListeners)

복수 listener 면 등록 순서대로. @ExcludeSuperclassListeners 로 부모 listener 비활성화 가능.

콜백 vs Hibernate Interceptor / EventListener

JPA 콜백은 entity 별. Hibernate 의 Interceptor / EventListener 는 전역. SaveOrUpdate 후 모든 entity 에 공통 로직 적용할 때 후자가 적합. 단, Hibernate 종속.

콜백 vs @TransactionalEventListener

콜백은 flush 시점 (트랜잭션 commit 이전). @TransactionalEventListener 는 commit 후. 외부 시스템 호출 (이메일, Kafka publish) 에는 후자가 안전:

@PostPersist
void onCreate() {
    // ❌ 트랜잭션 rollback 시 이메일은 이미 발송됨
    emailService.welcome(this);
}

// 더 안전한 패턴
@PostPersist
void onCreate() {
    events.publishEvent(new UserCreatedEvent(this.id));
}

@Component
class UserCreatedHandler {
    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    void handle(UserCreatedEvent e) {
        emailService.welcome(e.getId());
    }
}

함정과 베스트 프랙티스

시간 / Audit 은 Spring Data Auditing 권장: AuditingEntityListener + @EnableJpaAuditing
@PrePersist/@PreUpdate 에서 외부 시스템 호출 금지: 트랜잭션 rollback 시 일관성 깨짐
콜백 안에서 EntityManager 작업 금지: @TransactionalEventListener 로 분리
@PostLoad 는 derived field 계산에 유용 (AttributeConverter 보다 단순할 때)
@EntityListeners 의 listener 는 Spring Bean 아님: DI 안 됨 (생성자도 없는 게 안전)
- Spring 5.0+ BeanFactoryAware 트릭으로 가능하지만 권장 안 됨
콜백 시그니처 고정: 인스턴스 메서드는 무인자 (or Object entity), listener 는 Object entity 1개

[JPA] Optimistic Lock과 Pessimistic Lock

koa (김신건) — Tue, 23 Jun 2026 00:00:00 GMT

정의

동시 수정으로 데이터가 깨지는 상황을 막는 두 가지 전략:

Optimistic (낙관적): 충돌이 드물다고 가정, 커밋 직전에 version 비교로 검증. 충돌 시 예외.
Pessimistic (비관적): 충돌이 잦다고 가정, 읽는 순간 DB row 에 잠금. 다른 트랜잭션은 대기.

spring-data-jpa 의 ## 자주 보는 패턴 절에 간단한 예가 있다면, 이 페이지는 LockModeType 옵션과 트레이드오프를 깊이 다룬다.

Optimistic Lock: @Version

@Entity
class Product {
    @Id Long id;
    int stock;

    @Version
    Long version;   // Hibernate 가 자동 관리
}

매 UPDATE 마다 WHERE id = ? AND version = ? 조건 추가, 동시에 version = version + 1:

DB 락을 잡지 않음 → throughput 높음. 충돌 시 재시도 로직 필요.

@Version 필드 타입

@Version Long version;       // 권장 (음수 안 됨)
@Version Integer version;    // 권장
@Version Timestamp updatedAt;  // 가능하지만 정밀도 / 클럭 동기화 문제

권장은 Long 또는 Integer. timestamp 는 ms 단위 동시 update 에서 깨짐.

Retry 패턴

@Retryable(
    value = ObjectOptimisticLockingFailureException.class,
    maxAttempts = 3,
    backoff = @Backoff(delay = 50, multiplier = 2)
)
@Transactional
public void decreaseStock(Long productId, int qty) {
    Product p = repo.findById(productId).orElseThrow();
    p.setStock(p.getStock() - qty);
    // commit 시 version 검증
}

spring-retry 라이브러리로 자동 재시도. 무한 retry 금지 (요청 폭주 시 폭증).

LockModeType 8가지

Mode	의미
`NONE`	lock 없음 (기본)
`OPTIMISTIC`	트랜잭션 종료 시 version 검증
`OPTIMISTIC_FORCE_INCREMENT`	변경 없어도 version++ (강제 충돌 감지)
`READ`	= OPTIMISTIC (legacy 이름)
`WRITE`	= OPTIMISTIC_FORCE_INCREMENT (legacy)
`PESSIMISTIC_READ`	`SELECT ... FOR SHARE` (공유 lock)
`PESSIMISTIC_WRITE`	`SELECT ... FOR UPDATE` (배타 lock)
`PESSIMISTIC_FORCE_INCREMENT`	pessimistic + version++

대부분 OPTIMISTIC, OPTIMISTIC_FORCE_INCREMENT, PESSIMISTIC_WRITE 만 실무에서 쓰임.

OPTIMISTIC_FORCE_INCREMENT

연관 entity 의 변경이 부모의 version 도 올려야 할 때:

@Entity
class Order {
    @Version Long version;

    @OneToMany(mappedBy = "order")
    List<OrderItem> items;
}

@Transactional
public void addItem(Long orderId, Product p) {
    Order o = em.find(Order.class, orderId, LockModeType.OPTIMISTIC_FORCE_INCREMENT);
    o.getItems().add(new OrderItem(o, p));
    // OrderItem INSERT 만 일어나도 Order.version 증가
}

addItem 두 트랜잭션이 동시 실행되면 둘 다 version 증가 시도 → 한 쪽이 실패. 이게 없으면 둘 다 통과해 race 가능.

Pessimistic Lock

DB 에서 직접 row 잠금:

@Lock(LockModeType.PESSIMISTIC_WRITE)
@Query("SELECT p FROM Product p WHERE p.id = :id")
Optional<Product> findByIdForUpdate(@Param("id") Long id);

생성되는 SQL:

-- PostgreSQL / MySQL InnoDB
SELECT * FROM product WHERE id = ? FOR UPDATE;

-- Oracle
SELECT * FROM product WHERE id = ? FOR UPDATE;

다른 트랜잭션이 같은 row 에 FOR UPDATE / UPDATE / DELETE 시도하면 대기. lock 보유자가 commit/rollback 하면 해제.

Timeout

@Lock(LockModeType.PESSIMISTIC_WRITE)
@QueryHints({
    @QueryHint(name = "jakarta.persistence.lock.timeout", value = "5000")   // 5초
})
@Query("SELECT p FROM Product p WHERE p.id = :id")
Optional<Product> findByIdForUpdate(@Param("id") Long id);

대기 시간 초과 시 LockTimeoutException. timeout 0 은 즉시 실패 (NOWAIT).

DB 별 지원:

PostgreSQL: FOR UPDATE NOWAIT, FOR UPDATE SKIP LOCKED
MySQL 8+: FOR UPDATE NOWAIT, FOR UPDATE SKIP LOCKED
Oracle: FOR UPDATE NOWAIT, FOR UPDATE SKIP LOCKED

SKIP LOCKED 는 큐 패턴에 유용 (lock 잡힌 row 는 건너뛰고 다음 가져옴).

Optimistic vs Pessimistic 선택

항목	Optimistic	Pessimistic
충돌 빈도	드물 때	잦을 때
DB 락	없음	있음
Throughput	높음	낮음
Deadlock 위험	없음	있음
재시도 로직	필요	불필요
사용자 경험	다시 시도 요청 가능	대기
코드 복잡도	retry 필요	단순

규칙:

읽기 중심 + 충돌 드뭄: Optimistic
재고 차감, 좌석 예약 같은 hot row: Pessimistic
분산 환경 + 외부 시스템 호출: 두 가지 다 부족, distributed lock (Redis, Zookeeper) 고려

흔한 실수: 같은 트랜잭션 안 재조회

@Transactional
public void wrong(Long id) {
    Product p1 = repo.findById(id).orElseThrow();
    // ... 시간 걸리는 작업 ...
    Product p2 = repo.findById(id).orElseThrow();  // 1차 캐시에서 가져옴, p1 == p2
    p2.setStock(...);
}

1차 캐시 (spring-jpa-persistence-context) 때문에 두 번째 find 는 SQL 안 나감 = stale 데이터. 트랜잭션 시작 시점의 stock 으로 계산되는 함정. 트랜잭션을 짧게 유지하거나 em.refresh() 호출.

함정과 베스트 프랙티스

재고 차감 / 카운터 같은 lost update 회피에는 둘 다 가능
- read-heavy: optimistic + retry
- write-heavy: pessimistic
재시도는 idempotent 작업에만: 결제 API 호출 후 retry 면 중복 결제
OptimisticLockException 은 클라이언트에게 적절히 메시징: “다른 사람이 먼저 수정했습니다, 새로 고침 후 다시 시도”
pessimistic lock + long transaction = deadlock 폭탄: 트랜잭션 짧게
@Lock 은 query method 에 적용, 메서드 호출은 트랜잭션 안에서
FOR UPDATE SKIP LOCKED + LIMIT 1 가 큐 패턴 (spring-batch 도 비슷)
2차 캐시 + Optimistic: 2차 캐시는 version 정보도 캐싱 (Hibernate). 분산 환경에선 신중

[JPA] PersistenceContext vs PersistenceUnit 비교

koa (김신건) — Tue, 23 Jun 2026 00:00:00 GMT

정의

JPA 의 두 개념은 레벨이 다르다. 이름이 비슷해서 자주 혼동하지만:

PersistenceUnit = 설정 단위 (정적, 앱 1번)
PersistenceContext = 실행 단위 (동적, 트랜잭션마다)

비유:

PersistenceUnit = 공장 설계도 (어떤 DB, 어떤 entity, 어떤 옵션)
EntityManagerFactory = 공장 (설계도로 만들어진 thread-safe 객체, 앱 1개)
EntityManager = 공장의 작업자 (한 번에 한 트랜잭션 처리, 수많은 인스턴스)
PersistenceContext = 작업자의 작업대 (managed entity 보관, 1차 캐시)

한 줄 비교

항목	PersistenceUnit	PersistenceContext
정의 위치	앱 시작 시 1회 (config / persistence.xml)	트랜잭션 진입 시 자동
결과 객체	`EntityManagerFactory`	(EntityManager 내부 상태)
수	앱당 1~N개 (보통 1)	트랜잭션마다 1개, 동시 수많음
수명	JVM 라이프타임	트랜잭션 시작 ~ commit/rollback
Thread-safe	예 (EMF)	아니오 (단일 트랜잭션 = 단일 스레드)
무게	무거움 (entity 스캔, cache 초기화)	가벼움 (메모리 Map + entry)
어노테이션	`@PersistenceUnit`	`@PersistenceContext`
주입 타입	`EntityManagerFactory`	`EntityManager`
다루는 책임	DB 연결, dialect, entity 매핑, properties	1차 캐시, dirty checking, flush

시각화

[애플리케이션 시작]
   ↓
[PersistenceUnit 정의 로드]              ← 정적 (persistence.xml / Spring config)
   ↓ Persistence.createEntityManagerFactory("name")
[EntityManagerFactory 1개 생성]          ← 무거움, 앱 종료까지 유지
   │
   │ (트랜잭션마다)
   ↓ emf.createEntityManager()
[EntityManager + PersistenceContext]    ← 가벼움, 트랜잭션 끝나면 소멸
   │
   ├─ entity 매니지 (managed map)
   ├─ dirty checking
   ├─ action queue
   └─ flush
   │
   ↓ em.close() / 트랜잭션 commit
[소멸 - PC 비워짐]

코드로 비교

// PersistenceUnit 정의 (Spring Boot 자동)
@Configuration
public class JpaConfig {
    @Bean
    LocalContainerEntityManagerFactoryBean entityManagerFactory(DataSource ds) {
        return new LocalContainerEntityManagerFactoryBean();   // 한 번 생성
    }
}

// PersistenceContext 사용 (트랜잭션마다)
@Service
public class UserService {
    @PersistenceContext
    EntityManager em;   // ← Spring 이 proxy 주입, 매 트랜잭션마다 진짜 EM 매핑

    @Transactional
    public User find(Long id) {
        return em.find(User.class, id);   // 이 메서드 호출 = 새 PC 시작
        // 메서드 종료 = 트랜잭션 commit = PC 소멸
    }
}

@PersistenceContext 가 주입하는 EntityManager 는 shared proxy. 호출 시점에 현재 트랜잭션의 진짜 EM 으로 위임.

@PersistenceUnit vs @PersistenceContext

@Service
class FactoryService {
    @PersistenceUnit
    EntityManagerFactory emf;   // factory 자체 (앱 1개)

    @PersistenceContext
    EntityManager em;            // 트랜잭션 scope (매번 다름)

    public void doManual() {
        EntityManager fresh = emf.createEntityManager();
        try {
            fresh.getTransaction().begin();
            // 직접 트랜잭션 관리
            fresh.getTransaction().commit();
        } finally {
            fresh.close();
        }
    }

    @Transactional
    public void doSpring() {
        em.persist(new User("X"));   // 컨테이너가 트랜잭션 관리
    }
}

@PersistenceUnit 사용은 드물다. 거의 항상 @PersistenceContext + @Transactional 패턴.

다중성

PersistenceUnit 가 여러 개일 때

서로 다른 DB / entity set:

// orders PU
@Bean
LocalContainerEntityManagerFactoryBean ordersEmf(EntityManagerFactoryBuilder b, @Qualifier("ordersDs") DataSource ds) {
    return b.dataSource(ds).packages("com.example.orders").persistenceUnit("orders").build();
}

// analytics PU
@Bean
LocalContainerEntityManagerFactoryBean analyticsEmf(EntityManagerFactoryBuilder b, @Qualifier("analyticsDs") DataSource ds) {
    return b.dataSource(ds).packages("com.example.analytics").persistenceUnit("analytics").build();
}

각 PU 가 별도 EntityManagerFactory → 별도 EntityManager pool → 별도 PersistenceContext 생성. [[spring-boot-multi-datasource]] 참고.

@PersistenceContext(unitName = "orders") 로 어느 PU 의 EM 인지 선택:

@PersistenceContext(unitName = "orders")
EntityManager ordersEm;

@PersistenceContext(unitName = "analytics")
EntityManager analyticsEm;

PersistenceContext 가 여러 개일 때

같은 PU 안에서도 동시 트랜잭션 수만큼 PC 존재. 예: HTTP 100 동시 요청 → 100 트랜잭션 → 100 PC. 각자 독립 1차 캐시.

같은 entity (id=1) 가 동시에 100 PC 에 있을 수 있음. 각 PC 가 자기 snapshot 보유. 동시 update 충돌은 optimistic locking (@Version) 또는 pessimistic locking 으로 해결. [[spring-jpa-locking]].

책임 분리 요약

PersistenceUnit:
  └─ DB url, dialect, entity 스캔, hibernate.* properties,
      cache region factory, batch size, bootstrap mode

EntityManagerFactory:
  └─ EM 생성, 2nd-level cache, named queries 사전 컴파일,
      schema validation, connection pool 통합

EntityManager:
  └─ persist / find / merge / remove / detach API,
      JPQL query 실행, transaction 핸들

PersistenceContext:
  └─ Identity guarantee (1차 캐시),
      Dirty checking (snapshot 비교),
      Write-behind (action queue),
      Ordered flush (FK 의존성 분석)

각자 다른 추상화 레벨. 같은 layer 라고 묶으면 디버깅 시 혼란.

자주 보는 질문

Q: 왜 EntityManagerFactory 는 무겁고 EntityManager 는 가벼운가?

A: EMF 는 entity 메타데이터 + cache + named query 컴파일을 보유. EM 은 PC (HashMap) + Connection 1개 reference 만. EMF 는 모든 EM 이 공유하는 불변 데이터, EM 은 트랜잭션마다 변하는 가변 상태.

Q: @PersistenceContext 가 주입하는 EM 은 어떻게 트랜잭션마다 다른 인스턴스인가?

A: Spring 이 shared proxy 를 주입. 메서드 호출 시점에 TransactionSynchronizationManager 에서 현재 트랜잭션의 진짜 EM 을 조회 후 위임. 트랜잭션 없으면 새 EM 즉시 close.

Q: 트랜잭션 종료 후 entity 가 detached 되는 이유는?

A: PC 소멸. managed entity 의 reference 는 살아 있지만 어느 PC 에도 등록 안 됨 → setter 호출해도 변경 추적 안 됨 → 다음 트랜잭션에서 merge 로 다시 attach.

Q: 같은 PU 의 EM 두 개를 동시에 열면?

A: 두 개의 독립 PC. 같은 id (1) 의 User 도 두 PC 에 별도 인스턴스. 한 쪽 변경이 다른 쪽에 안 보임. flush 후 DB → refresh 해야 보임. 대부분 권장 안 함 (트랜잭션 = EM 1:1 패턴 유지).

Q: persistence.xml 없이 PU 정의는?

A: Spring Boot 의 LocalContainerEntityManagerFactoryBean + EntityManagerFactoryBuilder + application.yml 의 spring.jpa.* 옵션 조합. 실질적으로 persistence.xml 의 모든 항목 표현 가능.

함정과 베스트 프랙티스

@PersistenceContext 가 거의 항상 정답: @PersistenceUnit + 수동 EM 관리 안 함
@Transactional 과 함께: PC 의 수명 = 트랜잭션 수명
EntityManagerFactory 는 1개: 반복 생성 시 OOM + connection leak
PU 와 패키지 분리: 다중 PU 환경에서 entity 가 어느 PU 에 속하는지 명확히
@PersistenceContext(unitName=...) 명시: 멀티 PU 환경 필수
2개 PU 에 같은 entity 클래스 등록 금지: ambiguous 매핑
이름 헷갈리지 말 것: Unit = factory, Context = transaction scope

[JPA] PersistenceContext: 1차 캐시, dirty checking, flush

koa (김신건) — Tue, 23 Jun 2026 00:00:00 GMT

정의

PersistenceContext 는 EntityManager 가 관리하는 entity 의 메모리 저장소 + 변경 추적기. 트랜잭션 안에서만 살아 있다 (@Transactional 진입 시 생성, commit/rollback 시 소멸).

DB 와 분리해 이해:

DB: 영속 상태 (모든 트랜잭션에 공유, persistent)
PersistenceContext: 메모리 상태 (트랜잭션 1개 안에서만, transactional)

관련 비교 페이지: [[spring-jpa-context-vs-unit]] (PersistenceContext vs PersistenceUnit 명확히 구분).

시각화

{}

4개 상태 전이가 PC 와 DB 양쪽에서 어떻게 진행되는지 시간순으로 표시.

핵심 책임 4가지

책임	메커니즘	효과
Identity guarantee	같은 id → 같은 인스턴스 보장	`em.find(...)` 두 번 호출해도 `==` 비교 통과
Dirty checking	EntityEntry 가 snapshot 보관, flush 시 비교	setter 호출만으로 자동 UPDATE
Write-behind	persist/remove/dirty 변경 → action queue	INSERT/UPDATE 모아서 한 번에 flush
Ordered flush	FK 의존성 분석	INSERT → UPDATE → Collection 변경 → DELETE 순

이 4가지가 JPA 의 핵심. 모든 함정과 패턴은 이 네 가지에서 파생.

Entity 4가지 상태

[new/transient]   new User()                ← JPA 모름, PC 밖
       ↓ persist()
[managed]         PC 안에 보관, 변경 추적
       ↓ flush() / commit()
       └─→ DB 반영 (INSERT/UPDATE)
       ↓ remove()
[removed]         DELETE 대기, flush 시 DB 반영
       ↓ detach() / clear() / em 종료
[detached]        PC 밖, 변경 추적 안 됨, ID 는 유지
       ↑ merge()                            ← 새 managed 인스턴스 반환

코드 흐름:

EntityManager em = ...;
User u = new User("Alice");          // transient
em.persist(u);                       // managed (PC 등록)
u.setName("Bob");                    // 자동 추적
em.flush();                          // DB 반영 (UPDATE)
em.detach(u);                        // detached
u.setName("Carol");                  // 추적 안 됨
User merged = em.merge(u);           // 새 managed 인스턴스 반환
em.remove(merged);                   // removed

책임 1: Identity Guarantee (1차 캐시)

같은 트랜잭션 안에서 같은 id 의 entity 는 항상 같은 인스턴스:

두 번째 find 는 SQL 안 보냄. identity guarantee: 같은 PC 안에서 equals 가 아닌 == 비교 가능.

em.find vs em.getReference:

find: 즉시 SELECT, entity 또는 null
getReference: proxy 반환, 첫 메서드 호출 시 SELECT (lazy)

Post p = new Post();
p.setAuthor(em.getReference(User.class, authorId));   // User SELECT 안 함
em.persist(p);   // INSERT post 만

getReference 가 반환한 proxy 의 메서드를 호출하면 그때서야 SELECT. 존재하지 않는 id 면 EntityNotFoundException. 트랜잭션 밖에서 proxy 메서드 호출 = LazyInitializationException.

책임 2: Dirty Checking

managed entity 의 필드 변경은 자동 감지. setter 호출 후 별도 update 호출 불필요:

내부 동작:

find 시점에 EntityEntry 가 snapshot 저장 (필드 값 복사본)
트랜잭션 진행 중 setter 호출
flush 시점에 snapshot vs 현재 비교, 변경된 컬럼만 UPDATE

Cost: 모든 managed entity 의 모든 필드를 매번 비교. entity 수천 개면 성능 영향. 대용량 배치엔 StatelessSession (Hibernate, PC 자체를 끔).

책임 3: Write-Behind (action queue)

persist, remove, dirty 변경은 즉시 SQL 안 보내고 action queue 에 쌓임. flush 시점에 모아서 실행:

@Transactional
public void demo() {
    em.persist(new User("A"));      // INSERT 대기열
    em.persist(new User("B"));      // INSERT 대기열
    em.persist(new User("C"));      // INSERT 대기열
    // 아직 SQL 안 감
    // commit 시 한꺼번에 flush → 3 INSERT
}

Flush 시점 3가지

commit() 직전 (가장 흔함, default)
JPQL / Native query 실행 직전 (FlushModeType.AUTO, 기본)
em.flush() 명시 호출

em.persist(user);
em.createQuery("SELECT u FROM User u WHERE u.name = ?1", User.class)
  .setParameter(1, "Alice")
  .getSingleResult();
// 위 query 실행 직전에 user INSERT 됨
// (안 그러면 새로 persist 한 user 가 query 에 안 잡혀 결과 불일치)

FlushModeType.COMMIT 으로 자동 flush 끄면 명시 호출까지 SQL 안 나감. query 결과가 미반영 상태에 기반할 수 있어 위험.

책임 4: Ordered Flush

Hibernate 가 FK 의존성 분석 후 SQL 순서 자동 조정:

1. INSERT (parent → child 순서)
2. UPDATE
3. Collection element 삭제
4. Collection element INSERT
5. DELETE (child → parent)

UNIQUE 제약 + DELETE 후 INSERT 같은 경우 Constraint violation 가능 (둘 다 flush 시점에 같이 실행). em.flush() 명시 호출로 분리하거나 deferred constraint 사용.

merge: detached → managed

User detached = ...;       // 트랜잭션 밖에서 가져온 객체
@Transactional
public void update(User detached) {
    User managed = em.merge(detached);   // 새 managed 인스턴스 반환
    // detached 는 여전히 detached, managed 가 새로 만들어짐
}

함정: merge 는 새 인스턴스를 반환. 원본 reference 를 그대로 사용하면 변경 추적 안 됨:

em.merge(detached);
detached.setName("X");   // ❌ 추적 안 됨 (detached 그대로)

User m = em.merge(detached);
m.setName("X");          // ✓ dirty checking 됨

Spring Data JPA save():

id 없음 → persist 호출
id 있음 → merge 호출 (불필요한 SELECT 발생)

새 entity 에 미리 id 를 set 하면 의도와 달리 merge → 성능 손해. 직접 em.persist 호출하거나 Persistable 인터페이스 활용.

clear, detach: 메모리 관리

em.clear();      // PC 전체 비움 = 모든 entity detach
em.detach(u);    // 특정 entity 만

대용량 배치:

@Transactional
public void importMany(Stream<UserDto> input) {
    int i = 0;
    for (UserDto dto : input) {
        em.persist(new User(dto));
        if (++i % 1000 == 0) {
            em.flush();      // INSERT 보내고
            em.clear();      // PC 비우기
        }
    }
}

em.clear() 없으면 PC 에 entity 누적 → OOM. 1000 row 마다 flush + clear 패턴이 일반적.

트랜잭션 경계 = PC 경계

[트랜잭션 진입]
  ↓
[PersistenceContext 생성]
  ↓
[비즈니스 로직 (find, persist, merge, remove, dirty 변경)]
  ↓
[트랜잭션 commit]
  ├─→ PC 의 모든 dirty entity → flush → DB
  └─→ PC 소멸

규칙:

@Transactional 없이 EntityManager 사용 금지
트랜잭션 종료 = 모든 managed entity 자동 detached
새 트랜잭션 = 새 PC (다른 인스턴스)

OSIV (Open Session In View)

spring.jpa.open-in-view: true   # Spring Boot 기본

DispatcherServlet 진입 시 EntityManager 열고, view 렌더링까지 유지. lazy 로딩이 view layer 까지 가능.

운영 권장: false:

컨트롤러 / view 가 DB 커넥션 점유 → 풀 고갈
lazy 가 service 밖에서 일어남 (예측 어려움)
트랜잭션 경계가 흐려짐

false 로 두면 lazy 접근을 service 안 (@Transactional) 으로 강제. controller 는 Optional<DTO> 받아 매핑.

함정과 베스트 프랙티스

@Transactional 없이 EntityManager 사용 금지: 트랜잭션 = PC 수명
detached 객체 setter 변경은 무시: merge 후 반환된 새 인스턴스에 변경
StatelessSession (Hibernate) 대용량 배치 시: dirty checking 끔, PC 없음
em.flush() 명시 호출 신중: 예외 발생 위치를 옮기는 효과
1차 캐시는 트랜잭션 범위: 2차 캐시 (@Cacheable JPA L2) 는 다른 개념, 멀티 인스턴스 stale 위험
getReference 의 lazy + 트랜잭션 밖 호출 = LazyInitializationException
save 의 merge/persist 자동 판별 함정: id 가 있는 새 entity 는 persist 직접 호출
OSIV false + DTO projection: 가장 안전한 운영 패턴

[JPA] PersistenceUnit: EntityManagerFactory의 정의 단위

koa (김신건) — Tue, 23 Jun 2026 00:00:00 GMT

정의

PersistenceUnit 은 하나의 논리적 DB 연결 + entity 매핑 집합 을 정의한 단위. 결과물은 EntityManagerFactory 1개.

JPA 아키텍처의 계층:

PersistenceUnit  ← 설정 단위 (persistence.xml 또는 Spring config)
   ↓ 생성
EntityManagerFactory  ← 무거운 thread-safe 객체, 앱 1개
   ↓ createEntityManager()
EntityManager  ← 가벼운 단일 thread 객체, 트랜잭션마다 새로
   ↓ 보유
PersistenceContext  ← 1차 캐시 + dirty checking

spring-jpa-persistence-context 가 트랜잭션 범위의 메모리 저장소를 다룬다면, 이 페이지는 앱 시작 시점의 설정 / factory 단위 를 다룬다.

비교 페이지: [[spring-jpa-context-vs-unit]].

persistence.xml (표준 Jakarta Persistence)

순수 JPA 환경의 정석:

<!-- src/main/resources/META-INF/persistence.xml -->
<persistence xmlns="https://jakarta.ee/xml/ns/persistence" version="3.1">
    <persistence-unit name="primaryPU" transaction-type="RESOURCE_LOCAL">
        <provider>org.hibernate.jpa.HibernatePersistenceProvider</provider>
        <class>com.example.User</class>
        <class>com.example.Order</class>
        <exclude-unlisted-classes>false</exclude-unlisted-classes>
        <properties>
            <property name="jakarta.persistence.jdbc.url" value="jdbc:postgresql://localhost/db"/>
            <property name="jakarta.persistence.jdbc.user" value="app"/>
            <property name="jakarta.persistence.jdbc.password" value="secret"/>
            <property name="hibernate.dialect" value="org.hibernate.dialect.PostgreSQLDialect"/>
            <property name="hibernate.hbm2ddl.auto" value="validate"/>
            <property name="hibernate.show_sql" value="false"/>
        </properties>
    </persistence-unit>
</persistence>

EntityManagerFactory emf = Persistence.createEntityManagerFactory("primaryPU");
EntityManager em = emf.createEntityManager();

Spring Boot 환경에선 직접 작성 거의 안 함. Spring 이 LocalContainerEntityManagerFactoryBean 으로 동등한 기능 제공.

Spring Boot 의 PersistenceUnit (자동)

Spring Boot 의 JpaAutoConfiguration 이 자동 생성:

spring:
  datasource:
    url: jdbc:postgresql://localhost/db
    username: app
    password: ${DB_PASSWORD}
  jpa:
    properties:
      hibernate:
        dialect: org.hibernate.dialect.PostgreSQLDialect
        format_sql: true
    hibernate:
      ddl-auto: validate
    show-sql: false

내부적으로 LocalContainerEntityManagerFactoryBean Bean 자동 등록. persistence.xml 없이도 entity 자동 스캔 (@SpringBootApplication 패키지 기준).

명시적 등록:

@Configuration
public class JpaConfig {
    @Bean
    LocalContainerEntityManagerFactoryBean entityManagerFactory(
            DataSource dataSource,
            EntityManagerFactoryBuilder builder) {
        return builder
            .dataSource(dataSource)
            .packages("com.example.domain")
            .persistenceUnit("primary")
            .properties(Map.of(
                "hibernate.dialect", "org.hibernate.dialect.PostgreSQLDialect",
                "hibernate.hbm2ddl.auto", "validate"
            ))
            .build();
    }

    @Bean
    PlatformTransactionManager transactionManager(EntityManagerFactory emf) {
        return new JpaTransactionManager(emf);
    }
}

transaction-type: RESOURCE_LOCAL vs JTA

<persistence-unit name="..." transaction-type="RESOURCE_LOCAL">
<persistence-unit name="..." transaction-type="JTA">

타입	트랜잭션 관리	사용처
`RESOURCE_LOCAL`	JPA 가 직접 (`em.getTransaction().begin/commit`)	일반 Spring Boot, 단일 DB
`JTA`	외부 Transaction Manager (Java EE container, Atomikos, Narayana)	XA 분산 트랜잭션, EJB

Spring Boot 의 기본은 RESOURCE_LOCAL + JpaTransactionManager (Spring 의 transaction abstraction). JTA 는 별도 설정 필요 + 거의 안 씀.

@PersistenceUnit 어노테이션

EntityManagerFactory 자체를 주입받을 때:

@Service
public class MyService {
    @PersistenceUnit(unitName = "primary")
    private EntityManagerFactory emf;

    public void doWork() {
        EntityManager em = emf.createEntityManager();
        try {
            em.getTransaction().begin();
            // ...
            em.getTransaction().commit();
        } finally {
            em.close();
        }
    }
}

거의 안 씀. Spring Boot 에선 @PersistenceContext 또는 Repository 패턴 권장.

@PersistenceUnit vs @PersistenceContext:

@PersistenceUnit → EntityManagerFactory 주입 (factory)
@PersistenceContext → EntityManager 주입 (PC handle, 트랜잭션 scope)

복수 PersistenceUnit

서로 다른 DB / entity set 사용 시:

@Configuration
@EnableJpaRepositories(
    basePackages = "com.example.orders",
    entityManagerFactoryRef = "ordersEmf",
    transactionManagerRef = "ordersTm"
)
public class OrdersJpaConfig {
    @Bean
    LocalContainerEntityManagerFactoryBean ordersEmf(
            EntityManagerFactoryBuilder builder,
            @Qualifier("ordersDataSource") DataSource ds) {
        return builder.dataSource(ds)
            .packages("com.example.orders")
            .persistenceUnit("orders")
            .build();
    }

    @Bean
    PlatformTransactionManager ordersTm(@Qualifier("ordersEmf") EntityManagerFactory emf) {
        return new JpaTransactionManager(emf);
    }
}

@Configuration
@EnableJpaRepositories(
    basePackages = "com.example.analytics",
    entityManagerFactoryRef = "analyticsEmf",
    transactionManagerRef = "analyticsTm"
)
public class AnalyticsJpaConfig {
    @Bean
    LocalContainerEntityManagerFactoryBean analyticsEmf(
            EntityManagerFactoryBuilder builder,
            @Qualifier("analyticsDataSource") DataSource ds) {
        return builder.dataSource(ds)
            .packages("com.example.analytics")
            .persistenceUnit("analytics")
            .build();
    }

    @Bean
    PlatformTransactionManager analyticsTm(@Qualifier("analyticsEmf") EntityManagerFactory emf) {
        return new JpaTransactionManager(emf);
    }
}

각 entity 패키지는 분리. @Repository 도 각 패키지 안. [[spring-boot-multi-datasource]] 참고.

EntityManagerFactory 의 무게

EntityManagerFactory emf = Persistence.createEntityManagerFactory("primaryPU");

내부에서 일어나는 일:

모든 @Entity 클래스 스캔 + 메타데이터 분석
mapping XML 파싱 (있다면)
second-level cache 초기화
query 사전 컴파일 (named queries)
connection pool 초기화

비싸다. 앱 시작 시 1번만 생성. close 안 하면 JVM 종료까지 살아 있음. 절대 createEntityManagerFactory 를 반복 호출하지 말 것.

EntityManager 는 가벼움 (PC 1개 + Connection 1개 reference). 트랜잭션마다 새로 생성하고 즉시 close.

Bootstrap Mode

spring:
  jpa:
    bootstrap-mode: deferred   # default / lazy / deferred

Mode	동작	사용처
`default`	시작 시 동기적으로 EMF 생성	보장된 startup, 작은 앱
`lazy`	첫 사용 시점에 생성	시작 시간 단축, 첫 요청 느림
`deferred`	백그라운드 thread 로 비동기 생성, 사용 시점에 대기	Spring Boot 권장 default

deferred 가 보통 최선. 대형 앱 (entity 수백개) 의 시작 시간 단축 + 첫 요청 안 막힘.

Properties (Hibernate 튜닝)

spring:
  jpa:
    properties:
      hibernate:
        dialect: org.hibernate.dialect.PostgreSQLDialect
        format_sql: true
        use_sql_comments: true
        jdbc:
          batch_size: 50            # batch INSERT/UPDATE
          batch_versioned_data: true
          time_zone: UTC
          fetch_size: 100
        order_inserts: true
        order_updates: true
        connection:
          provider_disables_autocommit: true
        cache:
          use_second_level_cache: true
          region.factory_class: org.hibernate.cache.jcache.JCacheRegionFactory
        query:
          plan_cache_max_size: 2048
          plan_parameter_metadata_max_size: 128
        statistics: false              # 운영 환경에선 보통 false

자주 쓰는 옵션:

batch_size: 50 : INSERT/UPDATE batch 처리 (성능 큰 영향)
order_inserts: true : batch hit 률 ↑
provider_disables_autocommit: true : HikariCP 와 조합 시 connection 획득 최적화
format_sql, use_sql_comments : dev 만, 운영은 비활성

Entity 스캔 범위

@Bean
LocalContainerEntityManagerFactoryBean emf(EntityManagerFactoryBuilder builder, DataSource ds) {
    return builder.dataSource(ds)
        .packages("com.example.domain", "com.example.shared")   // 명시
        .persistenceUnit("primary")
        .build();
}

@EntityScan 어노테이션도 가능:

@SpringBootApplication
@EntityScan(basePackages = "com.example.domain")
class App {}

명시 안 하면 @SpringBootApplication 패키지 + 하위만.

Persistence Provider

JPA 는 spec, 실제 구현은 provider:

spring:
  jpa:
    properties:
      hibernate.dialect: org.hibernate.dialect.PostgreSQLDialect

Provider	특징
Hibernate (기본)	가장 일반, Spring Boot 의 기본
EclipseLink	Jakarta EE reference impl
OpenJPA	Apache, deprecated 흐름

대부분 Hibernate. 다른 provider 교체는 거의 안 일어남.

함정과 베스트 프랙티스

EntityManagerFactory 는 앱 1개: 반복 생성 = 메모리 누수
Spring Boot 에선 persistence.xml 거의 불필요: LocalContainerEntityManagerFactoryBean 이 동등
bootstrap-mode: deferred 권장: 시작 시간 단축
hibernate.jdbc.batch_size 설정: 대량 INSERT 시 큰 효과
여러 PersistenceUnit 사용 시 패키지 분리 필수: entity 가 어느 PU 에 속하는지 명확히
@PersistenceUnit vs @PersistenceContext 혼동 주의: 후자가 보통 정답
transaction-type 은 RESOURCE_LOCAL: JTA 는 특수 상황만
2차 캐시 신중: 멀티 인스턴스에서 stale 위험, 정말 read-heavy 한 항목만

[JPA] 상속 전략: SINGLE_TABLE, JOINED, TABLE_PER_CLASS

koa (김신건) — Tue, 23 Jun 2026 00:00:00 GMT

정의

JPA 는 객체 상속 구조를 관계형 테이블로 매핑하는 3가지 전략 + 1가지 비매핑 옵션:

전략	테이블 구조	사용 시점
`SINGLE_TABLE` (기본)	1 테이블에 모든 자식 컬럼	자식 클래스가 적고 필드 공유 많음
`JOINED`	부모 1 + 자식별 1 테이블, JOIN	정규화 우선, 자식별 필드 많음
`TABLE_PER_CLASS`	자식별 독립 테이블 (부모 없음)	거의 안 씀
`@MappedSuperclass`	부모는 매핑 안 됨 (테이블 없음)	공통 필드만 상속

@MappedSuperclass 가 사실 가장 흔하게 쓰임. 다형성 query 가 필요할 때만 InheritanceType 진짜 상속을 쓴다.

@MappedSuperclass (실무에서 가장 흔함)

부모 클래스는 entity 가 아니고 공통 필드만 제공:

@MappedSuperclass
public abstract class BaseTimeEntity {
    @Id @GeneratedValue
    Long id;

    @CreatedDate
    @Column(nullable = false, updatable = false)
    LocalDateTime createdAt;

    @LastModifiedDate
    @Column(nullable = false)
    LocalDateTime updatedAt;
}

@Entity
class User extends BaseTimeEntity {
    String email;
}

@Entity
class Post extends BaseTimeEntity {
    String title;
}

BaseTimeEntity 는 테이블 없음. user, post 테이블에 각각 id, created_at, updated_at 컬럼이 추가됨. @EntityListeners(AuditingEntityListener.class) 와 조합해 자동 timestamp.

다형성 query 불가 (SELECT b FROM BaseTimeEntity b 안 됨). 단순 필드 공유 도구.

SINGLE_TABLE (InheritanceType 기본)

@Entity
@Inheritance(strategy = InheritanceType.SINGLE_TABLE)
@DiscriminatorColumn(name = "type")
abstract class Vehicle {
    @Id @GeneratedValue Long id;
    String name;
}

@Entity
@DiscriminatorValue("CAR")
class Car extends Vehicle {
    int doors;
}

@Entity
@DiscriminatorValue("BIKE")
class Bike extends Vehicle {
    boolean hasBasket;
}

생성 DDL:

CREATE TABLE vehicle (
    id         BIGINT PRIMARY KEY,
    type       VARCHAR(31),       -- DiscriminatorColumn
    name       VARCHAR(255),
    doors      INT,               -- Car
    has_basket BOOLEAN            -- Bike
);

모든 자식 필드가 한 테이블에 있고 NULL 허용. type 컬럼으로 인스턴스 종류 구분.

장점:

JOIN 없음, query 빠름
다형성 query 자연스러움 (SELECT v FROM Vehicle v)

단점:

자식 필드는 모두 nullable (자식의 NOT NULL 제약 불가)
자식 종류 늘면 테이블이 sparse 해짐
스키마 변경 잦음

자식 종류가 2-3개고 공통 필드가 대부분인 경우 최적.

JOINED

@Entity
@Inheritance(strategy = InheritanceType.JOINED)
abstract class Vehicle {
    @Id @GeneratedValue Long id;
    String name;
}

@Entity
class Car extends Vehicle {
    int doors;
}

@Entity
class Bike extends Vehicle {
    boolean hasBasket;
}

생성 DDL:

CREATE TABLE vehicle (
    id      BIGINT PRIMARY KEY,
    name    VARCHAR(255)
);
CREATE TABLE car (
    id      BIGINT PRIMARY KEY REFERENCES vehicle(id),
    doors   INT NOT NULL
);
CREATE TABLE bike (
    id          BIGINT PRIMARY KEY REFERENCES vehicle(id),
    has_basket  BOOLEAN NOT NULL
);

Query 시 JOIN:

장점:

정규화, NOT NULL 제약 가능
스키마가 깔끔

단점:

매번 JOIN, query 느림
INSERT 도 2번 (parent + child)

TABLE_PER_CLASS

@Entity
@Inheritance(strategy = InheritanceType.TABLE_PER_CLASS)
abstract class Vehicle {
    @Id @GeneratedValue Long id;
    String name;
}

@Entity
class Car extends Vehicle { int doors; }

@Entity
class Bike extends Vehicle { boolean hasBasket; }

생성 DDL: car, bike 테이블만. vehicle 테이블 없음. 부모 필드 (name) 가 자식 테이블에 복제.

다형성 query 시:

SELECT * FROM (
    SELECT id, name, doors, NULL as has_basket, 'Car' as type FROM car
    UNION ALL
    SELECT id, name, NULL as doors, has_basket, 'Bike' as type FROM bike
) v WHERE v.id = ?;

UNION ALL. 자식이 많아질수록 query 폭증. 거의 사용 안 함.

전략 비교

항목	SINGLE_TABLE	JOINED	TABLE_PER_CLASS
테이블 수	1	1 + N	N
JOIN	없음	있음	없음 (UNION)
Query 속도	빠름	보통	자식 많을수록 느림
NOT NULL 자식 컬럼	불가	가능	가능
Polymorphic query	자연스러움	자연스러움	UNION
스키마 변경	매번 ALTER	자식만 추가	자식만 추가
실무 추천	자식 2-3개 + 단순	정규화 우선	비추천

@DiscriminatorColumn / @DiscriminatorValue

SINGLE_TABLE 의 자식 구분:

@DiscriminatorColumn(
    name = "vehicle_type",
    discriminatorType = DiscriminatorType.STRING,   // STRING / CHAR / INTEGER
    length = 20
)
abstract class Vehicle { ... }

@DiscriminatorValue("CAR")
class Car extends Vehicle { ... }

JOINED 에서는 optional. 없어도 동작 (Hibernate 가 child 테이블 join 으로 추론).

다형성 query

// 모든 vehicle (자식 포함)
em.createQuery("SELECT v FROM Vehicle v", Vehicle.class);

// car 만
em.createQuery("SELECT c FROM Car c", Car.class);

// TYPE() function 으로 분기
em.createQuery("""
    SELECT v FROM Vehicle v WHERE TYPE(v) IN (:types)
""")
    .setParameter("types", Set.of(Car.class));

// TREAT (다운캐스트)
em.createQuery("""
    SELECT v FROM Vehicle v
    WHERE TREAT(v AS Car).doors >= 4
""");

TYPE(), TREAT() 가 다형성 query 도구. SINGLE_TABLE / JOINED 에서만 의미있고, MAPPED_SUPERCLASS 에서는 불가.

실무 권장

공통 필드만 공유: @MappedSuperclass (BaseTimeEntity 같은)
다형성 query 필요 + 자식 단순: SINGLE_TABLE
다형성 query 필요 + 자식 복잡 / 정규화 우선: JOINED
TABLE_PER_CLASS 는 피하기

함정과 베스트 프랙티스

@MappedSuperclass 부모는 abstract: 인스턴스화하면 entity 가 아닌데 entity 처럼 동작 시도
SINGLE_TABLE 의 NULL 컬럼은 검색 성능에 영향: 인덱스 사용 어려움
JOINED 의 child 만 select 도 join 발생 (id 컬럼이 fk 라서)
자식 entity 의 @DiscriminatorValue 누락: Hibernate 가 클래스명 사용 (변경 시 깨짐)
@Inheritance 는 root entity 에만: 중간 클래스에 또 붙이면 안 됨
@JoinColumn(name = "id") 명시: JOINED 의 FK 컬럼명 컨트롤
2nd level cache 와 상속: 캐싱 시 자식 클래스 결정 비용 추가

[Spring AI] RAG: Embedding, VectorStore, QuestionAnswerAdvisor

koa (김신건) — Tue, 23 Jun 2026 00:00:00 GMT

정의

RAG (Retrieval Augmented Generation) 는 LLM 의 지식 한계 (학습 cutoff, 사내 문서 부재) 를 극복하기 위해, 질문 시점에 외부 지식 베이스에서 관련 문서 검색 → prompt 에 첨부 → LLM 호출 하는 패턴.

Spring AI 의 핵심 컴포넌트:

EmbeddingModel: 텍스트 → 벡터 (보통 1536 차원). OpenAI text-embedding-3-small / large 등
VectorStore: 벡터 인덱싱 + 유사도 검색 (PgVector, Chroma, Redis, Pinecone, Weaviate, Qdrant, Milvus, MongoDB Atlas)
Document: 텍스트 + 메타데이터 chunk
DocumentReader / DocumentTransformer / DocumentWriter: ETL 파이프라인
QuestionAnswerAdvisor: ChatClient 에 RAG 통합 (검색 + context 첨부 자동화)

spring-ai-overview 가 ChatClient 기본을 다룬다면, 이 페이지는 벡터 검색 기반 RAG 의 ETL + 질의 파이프라인을 다룬다.

RAG 의 두 단계

[INDEXING (배치)]
원본 문서 → DocumentReader → 청크 분할 → EmbeddingModel → VectorStore
       (PDF, MD, HTML)    (DocumentSplitter)  (1536차원 벡터)   (인덱스)

[QUERY (런타임)]
사용자 질문 → EmbeddingModel → 유사도 top-k 검색 → 관련 청크 → ChatClient → LLM 응답
        (1벡터)            (cosine sim)        (3-5개)

의존성

implementation("org.springframework.ai:spring-ai-openai-spring-boot-starter:1.0.0")
implementation("org.springframework.ai:spring-ai-pgvector-store-spring-boot-starter:1.0.0")
// 또는 -chroma-store-, -redis-store-, -pinecone-store-, -weaviate-store-, -qdrant-store-, -milvus-store-

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      embedding:
        options:
          model: text-embedding-3-small
    vectorstore:
      pgvector:
        index-type: HNSW
        distance-type: COSINE_DISTANCE
        dimensions: 1536
  datasource:
    url: jdbc:postgresql://localhost/aidb

PgVector 는 PostgreSQL 의 pgvector extension. CREATE EXTENSION vector 한 번 실행하면 끝.

Indexing 파이프라인

@Service
class IndexingService {
    private final VectorStore vectorStore;
    private final EmbeddingModel embeddingModel;   // 자동 주입

    public void ingest(Path file) {
        // 1. Read
        DocumentReader reader = new TikaDocumentReader(file.toUri().toString());
        List<Document> raw = reader.get();

        // 2. Split (chunking)
        TokenTextSplitter splitter = new TokenTextSplitter(800, 350, 5, 10000, true);
        List<Document> chunks = splitter.apply(raw);

        // 3. Enrich (선택)
        KeywordMetadataEnricher enricher = new KeywordMetadataEnricher(chatModel, 5);
        chunks = enricher.apply(chunks);

        // 4. Write (embedding 자동 + 저장)
        vectorStore.add(chunks);   // 내부적으로 EmbeddingModel 호출 → INSERT
    }
}

Document reader 종류:

TikaDocumentReader: PDF, DOCX, PPTX, HTML, MD 등 (Apache Tika)
JsonReader: JSON 배열
TextReader: plain text
MarkdownDocumentReader: 마크다운 (heading 별 chunk)

Splitter 옵션:

TokenTextSplitter: 토큰 단위 (LLM tokenizer 기반)
DocumentByCharacterSplitter: 문자 단위
DocumentBySentenceSplitter: 문장 단위

Query 와 QuestionAnswerAdvisor

가장 간단한 RAG:

QuestionAnswerAdvisor 가 자동으로:

사용자 질문을 임베딩
VectorStore 에서 top-K 유사 문서 검색
검색 결과를 prompt 에 context 로 첨부
LLM 호출 → 응답
응답 객체에 출처 (citations) 메타데이터 첨부

수동 검색 (advisor 없이)

advisor 가 자동화하는 것을 명시적으로:

@Service
class ManualRag {
    private final VectorStore vectorStore;
    private final ChatClient chatClient;

    public String ask(String question) {
        List<Document> docs = vectorStore.similaritySearch(
            SearchRequest.builder()
                .query(question)
                .topK(5)
                .similarityThreshold(0.7)
                .filterExpression("category == 'spring-docs'")
                .build()
        );

        String context = docs.stream()
            .map(Document::getText)
            .collect(Collectors.joining("\n\n---\n\n"));

        return chatClient.prompt()
            .system("주어진 컨텍스트에 기반해서만 답변하세요. 모르면 모른다고 답하세요.")
            .user(u -> u.text("컨텍스트:\n{context}\n\n질문: {q}")
                .param("context", context)
                .param("q", question))
            .call()
            .content();
    }
}

수동의 장점: filter 표현식, hybrid 검색 (vector + keyword), 점수 가중치 조정 등 세밀 제어. advisor 는 80% 사용 사례를 한 줄로.

Metadata Filtering

List<Document> filtered = vectorStore.similaritySearch(
    SearchRequest.builder()
        .query("OAuth2 설정 방법")
        .filterExpression("source == 'spring-security-docs' && version >= 6")
        .topK(3)
        .build()
);

SQL-like 표현식 (==, !=, >, IN, &&, ||, NOT). 색인 시 메타데이터를 명시:

Document d = new Document("Security 설정 가이드 ...",
    Map.of("source", "spring-security-docs", "version", 6, "category", "auth"));
vectorStore.add(List.of(d));

VectorStore 비교

Store	운영 환경	특징
`PgVector`	PostgreSQL extension	DBA 친숙, ACID, 기존 PG 인프라 재사용
`Redis`	Redis Stack	빠른 검색, in-memory, persistence 가능
`Chroma`	단독 Python/Docker	dev 편의, embedded 가능
`Pinecone`	SaaS 만	scale, managed, 비용
`Weaviate`	self-host / cloud	hybrid 검색 (BM25 + vector)
`Qdrant`	Rust 기반	빠름, filtering 강력
`Milvus`	대규모	수십억 벡터, GPU 지원
`MongoDB Atlas`	Atlas 만	기존 MongoDB 와 통합

소규모 ~ 중규모: PgVector. 대규모 / 빠른 검색: Qdrant / Milvus. SaaS: Pinecone.

Advanced: Hybrid Search

vector + keyword 결합:

List<Document> results = vectorStore.similaritySearch(
    SearchRequest.builder()
        .query("Spring AI tool calling")
        .topK(10)
        .build()
);

// Reciprocal Rank Fusion 또는 keyword filter 결합
List<Document> filtered = results.stream()
    .filter(d -> d.getText().toLowerCase().contains("tool"))
    .toList();

Weaviate, Qdrant 는 native hybrid 지원. PgVector 는 tsvector 컬럼 + 별도 합산.

Re-ranking

top-K 검색 결과를 더 정확한 모델 (Cohere Rerank, jina-reranker) 로 재정렬:

List<Document> initial = vectorStore.similaritySearch(... topK=20 ...);
List<Document> reranked = rerankerClient.rerank(query, initial).stream()
    .limit(5)
    .toList();

Cost / latency 증가하지만 답변 품질 크게 개선.

Streaming RAG

ChatClient.stream() 와 결합:

Flux<String> answer = chatClient.prompt()
    .advisors(spec -> spec.advisors(new QuestionAnswerAdvisor(vs)))
    .user(question)
    .stream()
    .content();

검색은 단발, 응답만 토큰 스트림.

ETL 배치 패턴

대량 문서 인덱싱은 spring-batch ([[spring-batch]]) 와 자연스럽게 통합:

@Configuration
class IndexingJobConfig {
    @Bean
    Job indexingJob(JobRepository repo, Step ingestStep) {
        return new JobBuilder("indexing", repo).start(ingestStep).build();
    }

    @Bean
    Step ingestStep(JobRepository r, PlatformTransactionManager tx,
                    ItemReader<Path> reader, ItemWriter<Document> writer) {
        return new StepBuilder("ingest", r)
            .<Path, Document>chunk(50, tx)
            .reader(reader)
            .processor(this::readAndSplit)
            .writer(writer)
            .build();
    }

    Document readAndSplit(Path p) { ... }
}

함정과 베스트 프랙티스

chunk size 350~800 토큰 권장: 너무 작으면 context 부족, 크면 검색 정확도 ↓
chunk overlap 50~100 토큰: 문맥 단절 방지
embedding model 일관성: indexing 과 query 가 다른 모델이면 좌표계가 달라 검색 망가짐
similarity threshold 튜닝: 0.7~0.8 시작, 도메인에 따라 조정. 너무 높으면 결과 없음 위험
citations 표시: LLM 응답에 출처 (메타데이터) 함께 표시 = hallucination 감지
stale data 처리: 원본 문서 갱신 시 기존 청크 삭제 + 재인덱싱
embedding cost: text-embedding-3-small 도 대량 색인 시 비용. 캐싱 또는 self-host (instructor-xl) 검토
PII / 민감 데이터 색인 금지: vector store 에 들어가면 검색에 노출

[Spring AI] 개요: ChatClient, ChatModel, Prompt

koa (김신건) — Tue, 23 Jun 2026 00:00:00 GMT

정의

Spring AI 는 LLM (OpenAI, Anthropic, Vertex AI, Bedrock, Ollama 등) 을 Spring 스타일로 사용하게 해 주는 abstraction. 2024 년 GA (1.0), 2025-2026 년에 1.x 안정 시리즈 진행 중.

핵심 추상화:

ChatClient: 고수준 API, fluent DSL, advisor / tool / structured output 통합
ChatModel: 저수준 API, 단일 호출, provider-specific tuning
Prompt / PromptTemplate: 메시지 + system / user / assistant role
Embedding / VectorStore: RAG 의 양대 기반 (별도 페이지: [[spring-ai-rag]])
Advisor: ChatClient 호출 chain 에 끼어드는 plugin (RAG, 로깅, safe guard)
@Tool: function calling, 모델이 자바 메서드를 직접 호출
ChatMemory: 대화 이력 관리

LangChain4j 와 경쟁. Spring 사용자라면 통합 (@SpringBootApplication, @Autowired, 자동 설정) 측면에서 Spring AI 가 자연스러움.

의존성

// build.gradle.kts (Spring Boot 3.3+)
implementation("org.springframework.ai:spring-ai-openai-spring-boot-starter:1.0.0")
// 또는: spring-ai-anthropic-spring-boot-starter, -ollama-, -bedrock-, -vertex-ai-, -mistral-, -azure-openai-

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        options:
          model: gpt-4o-mini
          temperature: 0.7

자동 설정이 ChatModel, ChatClient.Builder 같은 Bean 을 등록.

ChatClient: 가장 흔한 사용

<CodeWithOutput language=“java” outputLanguage=“text” outputLabel=“응답 본문” code={`@RestController public class JokeController { private final ChatClient chatClient;

public JokeController(ChatClient.Builder builder) {
    this.chatClient = builder.build();
}

@GetMapping("/joke")
public String joke(@RequestParam String topic) {
    return chatClient.prompt()
        .user(u -> u.text("Tell me a short joke about {topic}").param("topic", topic))
        .call()
        .content();
}

}} output={GET /joke?topic=cats → “Why don’t cats play poker in the jungle? Too many cheetahs.”`} />

prompt() → user/system → call() → content() 의 fluent DSL. .stream() 으로 SSE 토큰 스트리밍도 가능.

System 메시지와 PromptTemplate

String response = chatClient.prompt()
    .system("당신은 친절한 Spring 강사입니다. 답변은 한국어, 코드 포함.")
    .user(u -> u.text("@Transactional 의 propagation 7가지를 표로 정리해 주세요"))
    .call()
    .content();

PromptTemplate 으로 분리하면 재사용:

@Component
class ReviewService {
    private final ChatClient client;
    private final PromptTemplate REVIEW = new PromptTemplate("""
        다음 코드를 리뷰해 주세요. 카테고리: 가독성, 성능, 보안.
        ```{language}
        {code}
        ```
        """);

    public String review(String language, String code) {
        return client.prompt(REVIEW.create(Map.of("language", language, "code", code)))
            .call()
            .content();
    }
}

ChatModel (저수준)

provider-specific 옵션이나 prompt 재사용이 필요 없는 단발성 호출:

@Service
class SimpleTextService {
    private final ChatModel model;   // OpenAiChatModel, AnthropicChatModel 등

    public String summarize(String input) {
        Prompt prompt = new Prompt(
            List.of(
                new SystemMessage("문서 요약 어시스턴트"),
                new UserMessage(input)
            ),
            OpenAiChatOptions.builder().withTemperature(0.0).withMaxTokens(200).build()
        );
        return model.call(prompt).getResult().getOutput().getContent();
    }
}

ChatClient 는 ChatModel 위에 얹은 편의 layer. 대부분 ChatClient 권장.

Structured Output

LLM 응답을 자바 객체로 직접 매핑:

record Recipe(String name, List<String> ingredients, List<String> steps) {}

Recipe recipe = chatClient.prompt()
    .user("Suggest a simple pasta recipe")
    .call()
    .entity(Recipe.class);

내부적으로 schema 를 prompt 에 추가하고 JSON 응답을 파싱. 실패 시 IllegalStateException 또는 retry advisor 와 조합.

List, Map 도 지원:

List<String> topics = chatClient.prompt()
    .user("List 5 trending Spring topics")
    .call()
    .entity(new ParameterizedTypeReference<List<String>>() {});

Function / Tool Calling

모델이 자바 메서드를 직접 호출:

@Component
class WeatherTools {
    @Tool(description = "Get current weather for a city in Celsius")
    public String getCurrentWeather(@ToolParam(description = "City name") String city) {
        return weatherApi.fetch(city);   // 실제 API
    }
}

@Service
class AssistantService {
    private final ChatClient client;
    private final WeatherTools weatherTools;

    public String ask(String question) {
        return client.prompt()
            .user(question)
            .tools(weatherTools)
            .call()
            .content();
    }
}

LLM 이 질문에 따라 getCurrentWeather("Seoul") 호출 → 결과를 받아 최종 응답 생성. 여러 함수 호출도 자동 chaining.

@Tool 의 description 이 모델에게 보내는 메타데이터. 명확하게 작성.

Streaming

Flux<String> stream = chatClient.prompt()
    .user("Write a long essay on JVM")
    .stream()
    .content();

stream.subscribe(System.out::print);

SSE 응답을 컨트롤러에서 그대로 클라이언트에 전달 (WebFlux 통합).

Advisor: chain 에 끼어드는 plugin

ChatClient 호출 전후로 동작. 내장 advisor:

Advisor	역할
`MessageChatMemoryAdvisor`	대화 이력 자동 첨부 (ChatMemory)
`PromptChatMemoryAdvisor`	메모리 + system prompt 결합
`QuestionAnswerAdvisor`	RAG (vector store 검색 + context 첨부, [[spring-ai-rag]] 참고)
`SafeGuardAdvisor`	입력 / 출력 검열 (금칙어, profanity)
`SimpleLoggerAdvisor`	요청 / 응답 로깅

ChatClient client = builder
    .defaultAdvisors(new SimpleLoggerAdvisor(), memoryAdvisor, ragAdvisor)
    .build();

각 호출마다도 .advisors(...) 로 추가 가능.

ChatMemory: 대화 이력

@Bean
ChatMemory chatMemory() {
    return new InMemoryChatMemory();   // 또는 JdbcChatMemory, RedisChatMemory
}

@Bean
ChatClient chatClient(ChatClient.Builder b, ChatMemory mem) {
    return b.defaultAdvisors(new MessageChatMemoryAdvisor(mem)).build();
}

// 사용
String reply1 = client.prompt()
    .advisors(spec -> spec.param(AbstractChatMemoryAdvisor.CHAT_MEMORY_CONVERSATION_ID_KEY, sessionId))
    .user("내 이름은 Alice")
    .call().content();

String reply2 = client.prompt()
    .advisors(spec -> spec.param(AbstractChatMemoryAdvisor.CHAT_MEMORY_CONVERSATION_ID_KEY, sessionId))
    .user("내 이름이 뭐였지?")
    .call().content();
// → "Alice 입니다."

conversationId 로 세션 분리. 메모리 종류:

InMemoryChatMemory: 프로세스 내, 휘발성
JdbcChatMemory: DB 영구
CassandraChatMemory, RedisChatMemory: 외부 저장소
Neo4jChatMemory: 그래프 기반 (관계 추적 가능)

Image / Audio

@Service
class ImageService {
    private final ImageModel imageModel;   // OpenAiImageModel (DALL-E 3) 등

    public byte[] generate(String description) {
        ImageResponse r = imageModel.call(
            new ImagePrompt(description,
                OpenAiImageOptions.builder()
                    .withModel("dall-e-3")
                    .withWidth(1024).withHeight(1024)
                    .build())
        );
        return Base64.getDecoder().decode(r.getResult().getOutput().getB64Json());
    }
}

Audio: OpenAiAudioTranscriptionModel (whisper), OpenAiAudioSpeechModel (TTS).

Observability

자동으로 Micrometer metric / trace 발행:

spring_ai_chat_client_request_seconds (히스토그램)
spring_ai_chat_client_request_tokens_total
spring_ai_chat_client_response_tokens_total
spring_ai_chat_client_response_finish_reason (counter)

management.tracing.sampling.probability=1.0 으로 trace 활성화 시 prompt / response 도 OTel span 으로 캡처 (민감 데이터 주의).

함정과 베스트 프랙티스

API key 는 환경 변수: application.yml 에 직접 쓰지 말 것
temperature / maxTokens 명시: 기본값 의존 시 provider 변경에 취약
structured output 실패 처리: 잘못된 JSON 응답 시 retry advisor + validation
tool calling 보안: LLM 이 호출하는 메서드는 부수효과 신중 (DB 쓰기 / 외부 API 등). audit / authorization 필수
streaming 의 응답 본문 길이 제한: timeout 설정
provider lock-in 회피: ChatClient 추상화만 사용, provider-specific options 지양
테스트는 ChatModel mock: 실제 LLM 호출은 비용

[Spring Boot] Actuator 커스텀: Endpoint, HealthIndicator, Metric

koa (김신건) — Tue, 23 Jun 2026 00:00:00 GMT

정의

Spring Boot Actuator 의 확장 포인트. 기본 endpoint (/health, /metrics, /info) 외에 도메인 정보 노출:

@Endpoint : 새로운 endpoint
HealthIndicator : /health 의 sub-health
InfoContributor : /info 추가 정보
MeterBinder : Micrometer metric

운영 모니터링 (Prometheus / Grafana / Datadog) + alerting 의 토대.

Custom Endpoint



@Component
@Endpoint(id = "feature-flags")
public class FeatureFlagsEndpoint {
    private final FeatureFlagService service;

    public FeatureFlagsEndpoint(FeatureFlagService service) {
        this.service = service;
    }

    @ReadOperation
    public Map<String, Boolean> flags() {
        return service.getAll();
    }

    @ReadOperation
    public Boolean specificFlag(@Selector String name) {
        return service.isEnabled(name);
    }

    @WriteOperation
    public void setFlag(@Selector String name, boolean enabled) {
        service.set(name, enabled);
    }

    @DeleteOperation
    public void clearFlag(@Selector String name) {
        service.remove(name);
    }
}

management:
  endpoints:
    web:
      exposure:
        include: feature-flags
  endpoint:
    feature-flags:
      access: read-write

접근:

GET /actuator/feature-flags → 전체
GET /actuator/feature-flags/checkout-v2 → 특정 flag
POST /actuator/feature-flags/checkout-v2 body {"enabled":true} → 토글
DELETE /actuator/feature-flags/checkout-v2 → 삭제

@Endpoint annotation 이 자동으로 /actuator/{id} 에 노출. @Selector 가 path variable. 인증 / 권한 = Spring Security 로.

Web-Only / JMX-Only

@WebEndpoint(id = "deploy-info")        // HTTP only
@JmxEndpoint(id = "thread-pool")        // JMX only

기본 @Endpoint 는 HTTP + JMX 양쪽.

Custom HealthIndicator

@Component
public class RedisHealthIndicator implements HealthIndicator {
    private final RedisConnectionFactory factory;

    public RedisHealthIndicator(RedisConnectionFactory factory) {
        this.factory = factory;
    }

    @Override
    public Health health() {
        try (var conn = factory.getConnection()) {
            String pong = new String(conn.ping());
            if ("PONG".equals(pong)) {
                return Health.up()
                    .withDetail("response", pong)
                    .withDetail("server", conn.getNativeConnection().toString())
                    .build();
            }
            return Health.down().withDetail("response", pong).build();
        } catch (Exception e) {
            return Health.down(e).build();
        }
    }
}

management:
  endpoint:
    health:
      show-details: always   # 또는 when-authorized
      show-components: always

/actuator/health:

{
  "status": "UP",
  "components": {
    "redis": {
      "status": "UP",
      "details": { "response": "PONG", "server": "..." }
    },
    "db": { "status": "UP" },
    "diskSpace": { "status": "UP", "details": { ... } }
  }
}

Reactive HealthIndicator

@Component
public class ApiHealthIndicator implements ReactiveHealthIndicator {
    private final WebClient client;

    @Override
    public Mono<Health> health() {
        return client.get().uri("/health")
            .retrieve()
            .bodyToMono(String.class)
            .map(body -> Health.up().withDetail("response", body).build())
            .onErrorResume(e -> Mono.just(Health.down(e).build()));
    }
}

WebFlux 환경에서 non-blocking health check.

Health 가 K8s probe 와 통합

management:
  endpoint:
    health:
      probes:
        enabled: true
        add-additional-paths: true   # /livez, /readyz 같은 단축 path
  health:
    livenessstate:
      enabled: true
    readinessstate:
      enabled: true

/actuator/health/liveness → 컨테이너 재시작
/actuator/health/readiness → 트래픽 라우팅

[[spring-boot-container-deployment]] 참고.

InfoContributor

@Component
public class GitInfoContributor implements InfoContributor {
    @Override
    public void contribute(Info.Builder builder) {
        builder.withDetail("git", Map.of(
            "commit", System.getenv("GIT_COMMIT"),
            "branch", System.getenv("GIT_BRANCH"),
            "build-time", Instant.now().toString()
        ));
    }
}

management:
  endpoints:
    web:
      exposure:
        include: info
  info:
    env:
      enabled: true
    git:
      mode: full
    build:
      enabled: true

/actuator/info:

{
  "git": { "commit": "abc1234", "branch": "main" },
  "build": { "artifact": "my-app", "version": "1.0.0" }
}

Custom Metric (Micrometer)




@Service
public class OrderService {
    private final Counter orderCounter;
    private final Timer placementTimer;

    public OrderService(MeterRegistry registry) {
        this.orderCounter = Counter.builder("orders.placed.total")
            .description("Total number of orders placed")
            .tag("source", "web")
            .register(registry);

        this.placementTimer = Timer.builder("orders.placement.duration")
            .description("Time to place an order")
            .register(registry);
    }

    public Order place(Cart cart) {
        return placementTimer.record(() -> {
            Order order = doPlace(cart);
            orderCounter.increment();
            return order;
        });
    }
}

management:
  metrics:
    distribution:
      percentiles-histogram:
        orders.placement.duration: true
      percentiles:
        orders.placement.duration: 0.5, 0.95, 0.99
      slo:
        orders.placement.duration: 100ms, 200ms, 500ms
  endpoints:
    web:
      exposure:
        include: metrics, prometheus

/actuator/metrics/orders.placed.total:

{
  "name": "orders.placed.total",
  "measurements": [{"statistic": "COUNT", "value": 42}],
  "availableTags": [{"tag": "source", "values": ["web"]}]
}

/actuator/prometheus: Prometheus scrape 형식.

MeterBinder (Bean 등록)

@Component
public class CacheMetrics implements MeterBinder {
    private final CacheManager cacheManager;

    @Override
    public void bindTo(MeterRegistry registry) {
        for (String name : cacheManager.getCacheNames()) {
            Cache cache = cacheManager.getCache(name);
            registry.gauge("cache.size",
                Tags.of("name", name),
                cache, c -> c.size());
        }
    }
}

자동으로 모든 등록된 MeterBinder 를 MeterRegistry 에 bind.

@Timed / @Counted

@RestController
class UserController {
    @Timed(value = "user.find", percentiles = {0.5, 0.95})
    @GetMapping("/users/{id}")
    public User find(@PathVariable Long id) { ... }

    @Counted("user.create")
    @PostMapping("/users")
    public User create(@RequestBody User u) { ... }
}

@EnableAspectJAutoProxy + spring-boot-starter-aop 필요. 메서드 단위 metric 자동 측정.

운영 보안

management:
  server:
    port: 9090           # 별도 port (보안 그룹으로 격리)
  endpoints:
    web:
      base-path: /admin   # /actuator 대신
      exposure:
        include: health, info, metrics, prometheus
        exclude: env, beans, mappings   # 민감 정보 제외
  endpoint:
    health:
      show-details: when-authorized
      show-components: when-authorized

Spring Security 와 조합:

@Bean
SecurityFilterChain actuatorSecurity(HttpSecurity http) throws Exception {
    return http
        .securityMatcher(EndpointRequest.toAnyEndpoint())
        .authorizeHttpRequests(a -> a
            .requestMatchers(EndpointRequest.to("health", "info")).permitAll()
            .anyRequest().hasRole("ACTUATOR"))
        .httpBasic(Customizer.withDefaults())
        .build();
}

/health 만 public, 나머지는 인증 + ACTUATOR role.

Trace + Span 정보 노출

OpenTelemetry 통합 시 metric 에 traceId 가 자동으로:

@Bean
ObservationFilter traceContextFilter() {
    return ctx -> {
        TraceContext trace = currentTrace();
        if (trace != null) {
            ctx.addHighCardinalityKeyValue(KeyValue.of("trace_id", trace.traceId()));
        }
        return ctx;
    };
}

Grafana 의 exemplar 로 metric → trace 점프.

함정과 베스트 프랙티스

@Endpoint(id) 는 kebab-case: /actuator/{id}
민감 endpoint 별도 port: production network 격리
/health 만 public: 나머지는 인증
HealthIndicator 가 외부 시스템 호출 시 timeout 명시: actuator 가 hang 위험
metric 이름은 dot notation + tag 활용: 카르테시안 곱 폭발 주의
high-cardinality tag 금지 (user_id): Prometheus 폭발
@Timed 만 사용: @Counted 는 Timer 의 count 와 중복
MeterRegistryCustomizer 로 공통 tag: application, region 등
K8s probe 와 분리: liveness 가 외부 의존성 health 까지 검사하면 cascade 재시작

[Spring Boot] Build Plugins: Maven, Gradle, Executable JAR, OCI Image

koa (김신건) — Tue, 23 Jun 2026 00:00:00 GMT

정의

Spring Boot 의 빌드 플러그인은 표준 jar 가 아닌 executable jar (fat jar / uber jar) 생성. 추가로 OCI 이미지, native image, layered jar 등 production 패키징 지원.

핵심 goal:

Executable JAR: java -jar app.jar 로 실행 가능 (내장 Tomcat 포함)
Layered JAR: Docker layer 최적화
OCI Image (bootBuildImage): Dockerfile 없이 Cloud Native Buildpacks 로 이미지 생성
Native Image: GraalVM AOT 컴파일

Maven Plugin 기본

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <version>${spring-boot.version}</version>
            <configuration>
                <mainClass>com.example.MyApplication</mainClass>
                <executable>true</executable>
                <layers>
                    <enabled>true</enabled>
                </layers>
            </configuration>
        </plugin>
    </plugins>
</build>

주요 goal:

mvn spring-boot:run : 개발 실행
mvn package : executable jar 빌드 (target/app-1.0.0.jar)
mvn spring-boot:build-image : OCI 이미지 생성
mvn spring-boot:start / :stop : background 실행 (통합 테스트용)

Gradle Plugin 기본

plugins {
    id("org.springframework.boot") version "3.4.0"
    id("io.spring.dependency-management") version "1.1.7"
    java
}

springBoot {
    mainClass.set("com.example.MyApplication")
    buildInfo()    // META-INF/build-info.properties 생성
}

주요 task:

./gradlew bootRun : 개발 실행
./gradlew bootJar : executable jar 빌드 (build/libs/app-1.0.0.jar)
./gradlew bootBuildImage : OCI 이미지 생성
./gradlew bootBuildInfo : build info 생성

Executable JAR 구조

app.jar (zip)
├── META-INF/
│   ├── MANIFEST.MF              ← Main-Class: org.springframework.boot.loader.JarLauncher
│   └── build-info.properties
├── BOOT-INF/
│   ├── classes/                 ← 내 코드 + 리소스
│   ├── lib/                     ← 모든 의존성 jar
│   └── classpath.idx
└── org/springframework/boot/loader/   ← JarLauncher

JarLauncher 가 BOOT-INF/classes + BOOT-INF/lib/*.jar 를 classpath 에 추가 후 MyApplication.main() 호출. nested jar 지원.

Layered JAR (Docker 최적화)

기본 executable jar 는 하나의 큰 layer = 의존성 한 줄 바뀌어도 전체 layer 재빌드.

Layered 활성화:

tasks.bootJar {
    layered {
        enabled.set(true)
    }
}

생성된 jar 안에 BOOT-INF/layers.idx:

- "dependencies":
  - "BOOT-INF/lib/spring-core-6.x.jar"
  - ...
- "spring-boot-loader":
  - "org/springframework/boot/loader/"
- "snapshot-dependencies":
  - "BOOT-INF/lib/my-snapshot.jar"
- "application":
  - "BOOT-INF/classes/"
  - "META-INF/"

추출:

java -Djarmode=layertools -jar app.jar extract --destination extracted

Dockerfile:

FROM eclipse-temurin:21-jre AS builder
WORKDIR /app
COPY app.jar app.jar
RUN java -Djarmode=layertools -jar app.jar extract --destination extracted

FROM eclipse-temurin:21-jre
WORKDIR /app
COPY --from=builder /app/extracted/dependencies/ ./
COPY --from=builder /app/extracted/spring-boot-loader/ ./
COPY --from=builder /app/extracted/snapshot-dependencies/ ./
COPY --from=builder /app/extracted/application/ ./
ENTRYPOINT ["java", "org.springframework.boot.loader.launch.JarLauncher"]

dependency layer 가 자주 안 바뀌어 cache hit. application layer 만 매 빌드 변경 → push 시간 단축.

OCI Image (Buildpacks, Dockerfile 없이)

mvn spring-boot:build-image
# 또는
./gradlew bootBuildImage

자동 생성:

JDK 선택 (Paketo Buildpack)
멀티 stage 최적화
non-root user
CA cert / timezone
entrypoint

설정:

tasks.bootBuildImage {
    imageName.set("my-app:${version}")
    builder.set("paketobuildpacks/builder-jammy-base")
    environment.set(mapOf(
        "BP_JVM_VERSION" to "21",
        "BPE_DELIM_JAVA_TOOL_OPTIONS" to " ",
        "BPE_APPEND_JAVA_TOOL_OPTIONS" to "-XX:+UseG1GC"
    ))
    publish.set(false)
}

docker build 보다 훨씬 빠르고 보안 강화. Spring 권장.

Native Image (GraalVM AOT)

plugins {
    id("org.graalvm.buildtools.native") version "0.10.6"
}

graalvmNative {
    binaries {
        named("main") {
            imageName.set("my-app")
            mainClass.set("com.example.MyApplication")
            buildArgs.add("--no-fallback")
        }
    }
}

./gradlew nativeCompile      # 실행 binary
./gradlew nativeBuildImage   # native image OCI

장점: 시작 30ms, 메모리 절감 (~100MB → ~50MB). 단점:

빌드 오래 (수 분~10분)
reflection 메타데이터 명시 (Spring 6.x 가 자동 hint 생성)
일부 라이브러리 호환성

서버리스 (AWS Lambda) / 빠른 스케일 환경에 적합. [[spring-native]] 참고.

Build Info (Actuator info endpoint 노출)

springBoot {
    buildInfo {
        properties {
            artifact.set("my-app")
            version.set(project.version.toString())
            additional.set(mapOf(
                "commit" to gitCommit(),
                "buildTime" to Instant.now().toString()
            ))
        }
    }
}

management:
  info:
    git:
      mode: full
    build:
      enabled: true
  endpoints:
    web:
      exposure:
        include: info

/actuator/info 에 build/git 정보 노출. 운영 환경에서 버전 추적.

의존성 BOM

dependencies {
    implementation(platform("org.springframework.boot:spring-boot-dependencies:3.4.0"))
    implementation("org.springframework.boot:spring-boot-starter-web")
    // 버전 명시 안 함, BOM 이 관리
}

Spring Boot BOM 이 호환되는 라이브러리 버전 결정. 충돌 회피. Maven 은 dependencyManagement 로 동일.

CI / CD 최적화

# .github/workflows/build.yml
- uses: gradle/actions/setup-gradle@v4
  with:
    cache-disabled: false
- run: ./gradlew bootJar
- run: ./gradlew bootBuildImage --publishImage \
    -Pjib.to.image=ghcr.io/${{ github.repository }}:${{ github.sha }}

bootBuildImage 가 Docker daemon 또는 docker-less (Kaniko) 환경 모두 지원.

함정과 베스트 프랙티스

executable jar 권장: WAR 는 legacy. embedded 서버 활용
layered jar + Dockerfile 또는 bootBuildImage: 둘 중 하나. Buildpacks 가 권장
native image 는 빌드 시간 비용: 모든 빌드 X, release 만
BOM 의존성 관리: 직접 버전 명시는 충돌 위험
spring-boot-configuration-processor: IDE 자동완성
build-info + git-commit-id-plugin: 운영 환경 버전 추적
bootRun 의 --args=...: 개발 중 profile 전환
Gradle parallel + build cache: 빌드 속도 개선
dev tools : production 에서 제외 (developmentOnly)

[Spring Boot] Database Initialization: schema.sql, Flyway, Liquibase

koa (김신건) — Tue, 23 Jun 2026 00:00:00 GMT

정의

DB 스키마 / 데이터를 application 시작 시점에 자동 설정하는 메커니즘. 세 가지 접근:

schema.sql / data.sql (Spring Boot 내장, 단순)
Hibernate ddl-auto (JPA 기반, 자동)
Flyway / Liquibase (migration 도구, 운영 권장)

운영 환경 표준: Flyway 또는 Liquibase. schema.sql / ddl-auto 는 dev/test 만.

schema.sql / data.sql (단순)

src/main/resources/
├── schema.sql           ← DDL (CREATE TABLE 등)
├── data.sql             ← DML (INSERT 등)
├── schema-h2.sql        ← DB 별 (h2)
└── schema-postgresql.sql ← DB 별 (postgresql)

Spring Boot 가 시작 시점에 자동 실행:

-- schema.sql
CREATE TABLE IF NOT EXISTS users (
    id BIGSERIAL PRIMARY KEY,
    email VARCHAR(255) UNIQUE NOT NULL,
    name VARCHAR(255)
);

-- data.sql
INSERT INTO users (email, name) VALUES
    ('alice@example.com', 'Alice'),
    ('bob@example.com', 'Bob');

spring:
  sql:
    init:
      mode: always           # always | embedded | never
      platform: postgresql   # schema-{platform}.sql 활성화
      continue-on-error: false

mode:

embedded (기본): H2 / HSQLDB / Derby 만
always: 모든 DB
never: 비활성

JPA 와 함께 쓰면 순서 주의:

spring:
  jpa:
    defer-datasource-initialization: true   # JPA 가 ddl 만든 뒤 data.sql 실행

ddl-auto (JPA / Hibernate)

spring:
  jpa:
    hibernate:
      ddl-auto: validate

값	동작
`none`	아무것도 안 함 (운영 권장)
`validate`	entity 매핑이 DB 와 일치하는지 검증, 불일치 시 시작 실패
`update`	차이를 ALTER 로 적용 (위험, 데이터 보존)
`create`	drop + create (데이터 손실!)
`create-drop`	시작 시 create + 종료 시 drop (테스트만)

운영: validate 또는 none 만. update 는 의도치 않은 schema 변경 위험.

ddl-auto 와 schema.sql 동시 사용 금지 (충돌). migration 도구를 쓰면 둘 다 끔.

Flyway (권장)

implementation("org.flywaydb:flyway-core")
implementation("org.flywaydb:flyway-database-postgresql")   // Postgres 17+ 필요

spring:
  flyway:
    enabled: true
    locations: classpath:db/migration
    baseline-on-migrate: true   # 기존 DB 에서 처음 적용 시
    validate-on-migrate: true
    schemas: public
  jpa:
    hibernate:
      ddl-auto: validate         # Flyway 가 schema, JPA 는 검증만

migration 파일 명명 규칙:

src/main/resources/db/migration/
├── V1__init.sql                        ← versioned (한 번만)
├── V2__add_users_email_unique.sql
├── V3__seed_default_admin.sql
└── R__refresh_views.sql                ← repeatable (변경 시 재실행)

V{version}__{description}.sql: 버전 (한 번만)
R__{description}.sql: repeatable (체크섬 변경 시 다시 실행)
U{version}__{description}.sql: undo (Flyway Teams 만)

예: V1__init.sql

CREATE TABLE users (
    id          BIGSERIAL PRIMARY KEY,
    email       VARCHAR(255) UNIQUE NOT NULL,
    name        VARCHAR(255),
    created_at  TIMESTAMP NOT NULL DEFAULT now(),
    updated_at  TIMESTAMP NOT NULL DEFAULT now()
);

CREATE INDEX idx_users_created_at ON users(created_at);

예: V2__add_posts.sql

CREATE TABLE posts (
    id          BIGSERIAL PRIMARY KEY,
    user_id     BIGINT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    title       VARCHAR(255) NOT NULL,
    body        TEXT,
    created_at  TIMESTAMP NOT NULL DEFAULT now()
);

CREATE INDEX idx_posts_user_id ON posts(user_id);

Flyway metadata 테이블

Flyway 가 자동 생성:

flyway_schema_history
├── installed_rank
├── version
├── description
├── type
├── script
├── checksum
├── installed_by
├── installed_on
├── execution_time
└── success

같은 V{version} 이 다시 실행되면 checksum 비교. 변경 감지 시 시작 실패 (run 후 .sql 수정 = 안 됨).

자주 보는 명령

# 상태 확인
./gradlew flywayInfo

# 강제 baseline (기존 DB 에서 처음 도입)
./gradlew flywayBaseline

# 마이그레이션 실행
./gradlew flywayMigrate

# checksum repair (checksum 깨졌을 때)
./gradlew flywayRepair

운영 환경에선 application 시작 시 자동 migrate. CI / CD 단계에서 flyway info 로 확인 후 deploy.

Liquibase

implementation("org.liquibase:liquibase-core")

spring:
  liquibase:
    enabled: true
    change-log: classpath:db/changelog/db.changelog-master.yaml

# db/changelog/db.changelog-master.yaml
databaseChangeLog:
  - include:
      file: db/changelog/changes/001-init.yaml
  - include:
      file: db/changelog/changes/002-add-users.yaml

# 001-init.yaml
databaseChangeLog:
  - changeSet:
      id: 001-create-users
      author: alice
      changes:
        - createTable:
            tableName: users
            columns:
              - column:
                  name: id
                  type: BIGSERIAL
                  constraints:
                    primaryKey: true
              - column:
                  name: email
                  type: VARCHAR(255)
                  constraints:
                    nullable: false
                    unique: true
              - column:
                  name: name
                  type: VARCHAR(255)
      rollback:
        - dropTable:
            tableName: users

또는 native SQL:

- changeSet:
    id: 001-create-users
    author: alice
    changes:
      - sqlFile:
          path: db/changelog/sql/001-init.sql

Flyway vs Liquibase

항목	Flyway	Liquibase
형식	SQL native	YAML/XML/JSON (또는 SQL)
학습 곡선	낮음 (DBA 친숙)	중간
rollback	Teams (paid)	OSS
DB 추상화	약함	강함 (multi-DB)
커뮤니티	큼	큼
Spring Boot 통합	자동	자동

Flyway: SQL 익숙, 단일 DB, 빠른 시작. Liquibase: rollback 필요, multi-DB 추상화, enterprise.

자주 보는 패턴

Testcontainers + Flyway

@SpringBootTest
@Testcontainers
class PostRepositoryTest {
    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine");

    @DynamicPropertySource
    static void registerPgProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", postgres::getJdbcUrl);
        registry.add("spring.datasource.username", postgres::getUsername);
        registry.add("spring.datasource.password", postgres::getPassword);
    }

    @Test
    void test() {
        // Flyway 가 컨테이너 DB 에 자동 migration → 진짜 schema 로 테스트
    }
}

각 테스트 클래스마다 fresh DB + 모든 migration 적용. 실 환경과 동일한 schema 검증.

운영 환경 zero-downtime migration

위험한 변경 (column drop, NOT NULL 추가) 은 단계 분리:

V10__add_new_email_column.sql       (NULL 허용)
V11__backfill_email.sql              (데이터 채우기)
[배포: 새 코드가 new_email 쓰기 시작]
V12__make_new_email_not_null.sql    (제약 추가)
V13__drop_old_email_column.sql      (삭제)

application 코드 배포와 migration 순서 신중. expand-contract 패턴.

환경별 migration 제외

dev 만 seed 데이터:

db/migration/
├── V1__schema.sql                ← 모든 환경
├── V2__seed_test_users.sql       ← dev / test 만

# application-prod.yml
spring:
  flyway:
    locations: classpath:db/migration/prod

# application-dev.yml
spring:
  flyway:
    locations:
      - classpath:db/migration
      - classpath:db/seed

함정과 베스트 프랙티스

운영: ddl-auto=validate + Flyway/Liquibase: 자동 DDL 금지
schema.sql 은 dev/test 만: 운영은 migration 도구
V{version} 파일 수정 금지: checksum 깨짐, 새 V{n+1} 파일로 수정
data.sql 의 INSERT 는 IDEMPOTENT 하게: INSERT ... ON CONFLICT (Postgres) / ON DUPLICATE KEY UPDATE (MySQL)
baseline-on-migrate: 기존 DB 에서 Flyway 도입 시 한 번만 true
zero-downtime 위해 단계 분리: expand-contract 패턴
migration 도구 + Testcontainers: 실 DB 로 테스트
DB 별 SQL 차이 (PostgreSQL vs MySQL): Liquibase 의 추상화 또는 Flyway 의 ${flyway:database} placeholder 활용
JPA entity 변경 시 항상 migration 동반: validate 가 startup 실패로 알려줌

[Spring Boot] Deployment: 전통 WAR, Cloud, Systemd

koa (김신건) — Tue, 23 Jun 2026 00:00:00 GMT

정의

컨테이너 / K8s 외의 Spring Boot 배포 옵션:

Traditional WAR: 외부 Tomcat / Jetty (legacy 환경)
systemd service: VM / bare-metal
Cloud Foundry: PaaS, cf push
Heroku: PaaS, git push
AWS Elastic Beanstalk: AWS managed
AWS Lambda: serverless (native image 추천)
Azure App Service / Google App Engine

[[spring-boot-container-deployment]] 가 Docker/K8s 중심이라면 이 페이지는 그 외.

Traditional WAR (legacy)

기존 외부 Tomcat / WebSphere 인프라:

plugins {
    war
    id("org.springframework.boot") version "3.4.0"
}

dependencies {
    providedRuntime("org.springframework.boot:spring-boot-starter-tomcat")
    // 외부 Tomcat 이 제공
}

Application 클래스:

@SpringBootApplication
public class MyApplication extends SpringBootServletInitializer {
    @Override
    protected SpringApplicationBuilder configure(SpringApplicationBuilder b) {
        return b.sources(MyApplication.class);
    }

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

SpringBootServletInitializer 가 servlet 3.0+ container 와 통합. 기존 Tomcat 의 webapps/ 에 war 복사.

대부분 신규 프로젝트는 executable jar + container 권장. WAR 은 legacy 호환 전용.

systemd Service (VM / bare-metal)

# /etc/systemd/system/my-app.service
[Unit]
Description=My Spring Boot App
After=network.target

[Service]
User=spring
Group=spring
WorkingDirectory=/opt/my-app
ExecStart=/usr/bin/java -jar /opt/my-app/app.jar
SuccessExitStatus=143
Restart=always
RestartSec=10
Environment="SPRING_PROFILES_ACTIVE=prod"
EnvironmentFile=/etc/my-app/env
StandardOutput=append:/var/log/my-app/app.log
StandardError=append:/var/log/my-app/error.log

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable my-app
sudo systemctl start my-app
sudo journalctl -u my-app -f

기능:

자동 재시작 (Restart=always)
로그 통합 (journald)
환경 변수 분리
non-root 사용자

executable jar 를 service 로 등록한 가장 흔한 VM 배포 패턴.

자동 등록 (`executable = true`)

tasks.bootJar {
    archiveFileName.set("app.jar")
    manifest {
        attributes["Implementation-Title"] = "my-app"
    }
}

// Spring Boot 의 fully executable jar
springBoot {
    buildInfo()
}

// build.gradle.kts
tasks.bootJar {
    launchScript()    // jar 가 자체 실행 가능 → ./app.jar
}

./app.jar start | stop | status 가능. systemd 의 ExecStart=/opt/my-app/app.jar 만으로 충분.

Cloud Foundry

cf push my-app -p build/libs/app.jar

manifest.yml:

applications:
  - name: my-app
    memory: 1G
    instances: 3
    buildpack: java_buildpack
    env:
      SPRING_PROFILES_ACTIVE: prod
      JBP_CONFIG_OPEN_JDK_JRE: '{ jre: { version: 21.+ } }'
    services:
      - postgres-db
      - redis-cache
    routes:
      - route: api.example.com

Buildpack 이 JDK / app server 알아서 구성. Spring Boot 가 Cloud Foundry 환경 자동 감지 (spring-boot-cloudfoundry 의존성).

Heroku

# Procfile
web: java -Dserver.port=$PORT $JAVA_OPTS -jar build/libs/app.jar

git push heroku main

system.properties:

java.runtime.version=21

Heroku 가 빌드 + 실행. $PORT 환경 변수 자동 주입. JAVA_OPTS 로 메모리 / GC 튜닝.

application-heroku.yml:

server:
  port: ${PORT}
spring:
  datasource:
    url: ${JDBC_DATABASE_URL}

heroku addons:create heroku-postgresql 후 자동 환경 변수.

AWS Elastic Beanstalk

eb init -p java my-app
eb create my-app-prod
eb deploy

.ebextensions/01-options.config:

option_settings:
  aws:elasticbeanstalk:application:environment:
    SPRING_PROFILES_ACTIVE: prod
    JAVA_TOOL_OPTIONS: "-Xmx768m"
  aws:elasticbeanstalk:container:tomcat:jvmoptions:
    JVM Options: "-Xms256m"

WAR (Tomcat) 또는 jar (Procfile) 둘 다 지원. Auto Scaling Group + ELB + RDS 통합.

AWS Lambda (Native Image 권장)

GraalVM native:

plugins {
    id("org.graalvm.buildtools.native") version "0.10.6"
}

빠른 cold start (수십 ms). 또는 SnapStart (Java 21 Runtime):

@SpringBootApplication
public class LambdaHandler implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
    private static final SpringApplicationBuilder builder = new SpringApplicationBuilder(LambdaHandler.class);
    private static ConfigurableApplicationContext ctx;

    @Override
    public APIGatewayProxyResponseEvent handleRequest(APIGatewayProxyRequestEvent event, Context context) {
        if (ctx == null) ctx = builder.web(WebApplicationType.NONE).run();
        // route to controller
        return new APIGatewayProxyResponseEvent().withStatusCode(200).withBody("hello");
    }
}

spring-cloud-function-adapter-aws 가 자동 통합:

implementation("org.springframework.cloud:spring-cloud-function-adapter-aws")

application.yml:

spring:
  main:
    web-application-type: none
  cloud:
    function:
      definition: handleRequest

서버리스에서 cold start 가 critical 이면 native image, 안 그러면 SnapStart 로도 충분.

Reverse Proxy + load balancer

운영 환경 일반 패턴:

Client → CDN / WAF → ALB / nginx → Spring Boot (Tomcat) → DB
                  ↑ TLS terminate    ↑ plain HTTP

Spring 의 forward-headers-strategy: native 가 X-Forwarded-* 처리:

server:
  forward-headers-strategy: native

또는 framework 가 신뢰하는 reverse proxy 명시:

server.tomcat:
  remoteip:
    remote-ip-header: X-Forwarded-For
    protocol-header: X-Forwarded-Proto
    internal-proxies: 10\\.\\d+\\.\\d+\\.\\d+

CI / CD Pipeline

전형적인 GitHub Actions:

name: deploy
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          java-version: 21
          distribution: temurin
      - uses: gradle/actions/setup-gradle@v4
      - run: ./gradlew test bootJar
      - run: ./gradlew bootBuildImage --publishImage \
          -Pjib.to.image=ghcr.io/${{ github.repository }}:${{ github.sha }}
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
      - run: aws ecs update-service --cluster prod --service my-app --force-new-deployment

함정과 베스트 프랙티스

신규 프로젝트는 jar + container: WAR 는 legacy
systemd 로 VM 배포: 자동 재시작 + 로그 통합
PaaS (Heroku, CF, App Engine): 빠른 시작, 비용 / vendor lock-in
reverse proxy 사용: TLS / WAF / rate limit / static cache 분리
forward-headers-strategy: native: 클라이언트 IP / scheme 정확 추출
buildpack / OCI image: Dockerfile 부담 ↓ ([[spring-boot-build-plugins]])
graceful shutdown: 모든 환경에서 in-flight 요청 보호
native image (Lambda 등 cold start critical): 서버리스 적합
logs 는 stdout (12-factor): 파일 + rotation 은 OS 책임

[Spring Boot] Docker / Kubernetes 배포

koa (김신건) — Tue, 23 Jun 2026 00:00:00 GMT

정의

Spring Boot 앱을 컨테이너로 배포. 두 가지 주류:

Docker / Docker Compose: 단일 호스트, 개발 + 소규모 운영
Kubernetes: 멀티 호스트, orchestration, scaling, self-healing

Spring Boot 3+ 의 변경:

Cloud Native Buildpacks 가 Dockerfile 작성 거의 불필요
Liveness / Readiness probe 가 actuator endpoint 로 표준화
Graceful shutdown 이 K8s lifecycle 과 자연스럽게 통합

Dockerfile (수동)

전통적 multi-stage:

FROM eclipse-temurin:21-jdk-alpine AS builder
WORKDIR /app
COPY gradle/ gradle/
COPY gradlew build.gradle.kts settings.gradle.kts ./
RUN ./gradlew dependencies --no-daemon
COPY src/ src/
RUN ./gradlew bootJar --no-daemon

FROM eclipse-temurin:21-jre-alpine
WORKDIR /app
RUN addgroup -S spring && adduser -S spring -G spring
USER spring:spring
COPY --from=builder /app/build/libs/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

핵심:

multi-stage: 빌드 환경 분리 → 최종 이미지 작음
alpine / distroless: 보안 + 크기 축소
non-root user: 컨테이너 escape 위험 감소
layered jar 활용 시 더 최적화 (이전 페이지 참고)

Cloud Native Buildpacks (권장)

Dockerfile 없이:

mvn spring-boot:build-image
# 또는
./gradlew bootBuildImage

자동으로:

적절한 JDK 선택
security patch
non-root user
entrypoint
multi-arch 이미지

훨씬 빠르고 안전. Spring 권장. [[spring-boot-build-plugins]] 참고.

Docker Compose 통합 (Spring Boot 3.1+)

# compose.yaml
services:
  app:
    image: my-app:latest
    ports: ["8080:8080"]
    depends_on:
      - postgres
      - redis
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${DB_PASSWORD}
  redis:
    image: redis:7-alpine

dependencies {
    developmentOnly("org.springframework.boot:spring-boot-docker-compose")
}

developmentOnly 면 production jar 에 제외됨. 개발 환경에서 bootRun 시 compose 자동 기동 + connection 자동 주입.

spring:
  docker:
    compose:
      enabled: true
      file: compose.yaml
      lifecycle-management: start_and_stop

profiles 도 지원: compose --profile dev up.

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: my-app
          image: ghcr.io/example/my-app:1.0.0
          ports:
            - containerPort: 8080
          env:
            - name: SPRING_PROFILES_ACTIVE
              value: prod
            - name: SPRING_DATASOURCE_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: db-secret
                  key: password
          envFrom:
            - configMapRef:
                name: app-config
          resources:
            requests:
              memory: "512Mi"
              cpu: "250m"
            limits:
              memory: "1Gi"
              cpu: "1000m"
          livenessProbe:
            httpGet:
              path: /actuator/health/liveness
              port: 8080
            initialDelaySeconds: 30
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /actuator/health/readiness
              port: 8080
            initialDelaySeconds: 10
            periodSeconds: 5
          startupProbe:
            httpGet:
              path: /actuator/health/liveness
              port: 8080
            failureThreshold: 30
            periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
  name: my-app
spec:
  selector:
    app: my-app
  ports:
    - port: 80
      targetPort: 8080
  type: ClusterIP

Liveness / Readiness / Startup Probe

Spring Boot 2.3+ 가 actuator 에 K8s probe 표준화:

management:
  endpoint:
    health:
      probes:
        enabled: true
      show-details: when-authorized
  health:
    livenessstate:
      enabled: true
    readinessstate:
      enabled: true

endpoint:

/actuator/health/liveness : app 이 응답 가능? 실패 = 컨테이너 재시작
/actuator/health/readiness : 트래픽 받을 준비? 실패 = LB 에서 제외 (재시작 안 함)
/actuator/health : 통합 상태

각 상태 의미:

State	의미	예시
`LivenessState.CORRECT`	정상	OK
`LivenessState.BROKEN`	복구 불가	OOM, deadlock
`ReadinessState.ACCEPTING_TRAFFIC`	받을 수 있음	OK
`ReadinessState.REFUSING_TRAFFIC`	받을 수 없음	DB 연결 끊김, 시작 중

코드로 상태 변경:

@Service
class HealthControl {
    @Autowired ApplicationAvailability availability;
    @Autowired ApplicationEventPublisher events;

    public void markUnavailable() {
        AvailabilityChangeEvent.publish(events, this, ReadinessState.REFUSING_TRAFFIC);
    }
}

Graceful Shutdown

server:
  shutdown: graceful
spring:
  lifecycle:
    timeout-per-shutdown-phase: 30s

K8s 종료 흐름:

terminationGracePeriodSeconds (기본 30s) 카운트다운 시작
SIGTERM 전송
Spring 이 readiness REFUSING_TRAFFIC 으로 변경 → LB 제외
진행 중 요청 완료 대기 (timeout-per-shutdown-phase)
컨테이너 종료

K8s 의 preStop hook 으로 5초 대기 → readiness 가 LB 에서 빠지는 시간 확보:

lifecycle:
  preStop:
    exec:
      command: ["sh", "-c", "sleep 5"]

ConfigMap + Secret

ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  SPRING_PROFILES_ACTIVE: prod
  SERVER_PORT: "8080"
  application.yml: |
    spring:
      datasource:
        url: jdbc:postgresql://postgres/myapp

Secret:

apiVersion: v1
kind: Secret
metadata:
  name: db-secret
type: Opaque
data:
  password: <base64>

마운트 방식:

env var: envFrom: configMapRef / secretRef
파일: volumeMounts + Spring 의 spring.config.import: configtree:/etc/secrets/

Spring Cloud Kubernetes

implementation("org.springframework.cloud:spring-cloud-starter-kubernetes-client-config")

ConfigMap / Secret 을 PropertySource 로 자동 로딩. reload watch 지원:

spring:
  cloud:
    kubernetes:
      reload:
        enabled: true
        mode: polling
        period: 30s

@RefreshScope Bean 이 ConfigMap 변경 시 재생성.

Helm Chart

Chart.yaml:

apiVersion: v2
name: my-app
version: 1.0.0
appVersion: "1.0.0"

templates/deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}
spec:
  replicas: {{ .Values.replicaCount }}
  template:
    spec:
      containers:
        - name: app
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          resources: {{- toYaml .Values.resources | nindent 12 }}

values.yaml:

replicaCount: 3
image:
  repository: ghcr.io/example/my-app
  tag: 1.0.0
resources:
  requests: { memory: 512Mi, cpu: 250m }
  limits: { memory: 1Gi, cpu: 1000m }

helm install my-app ./chart -f values-prod.yaml
helm upgrade my-app ./chart --set image.tag=1.0.1

HPA (Horizontal Pod Autoscaler)

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: my-app
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: my-app
  minReplicas: 3
  maxReplicas: 20
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70

CPU / memory / custom metric (Prometheus Adapter) 기반.

Ingress + TLS

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  tls:
    - hosts: [api.example.com]
      secretName: api-tls
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: my-app
                port: { number: 80 }

cert-manager 가 자동 cert 갱신. Spring 은 plain HTTP 만 받음 ([[spring-boot-ssl-https]] 참고).

함정과 베스트 프랙티스

non-root user: 보안 + K8s security context 호환
graceful shutdown 필수: in-flight 요청 손실 방지
readiness 와 liveness 분리: 일시적 문제로 재시작 폭주 회피
resource limits 명시: OOM kill 보다 명시적 한계
resource requests = QoS: Burstable / Guaranteed 차이
secret 은 ConfigMap 에 X: 별도 Secret 또는 ExternalSecrets / Vault
로그는 stdout only: sidecar / DaemonSet 가 수집
JVM 힙 vs 컨테이너 메모리: -XX:MaxRAMPercentage=75 (전체 메모리의 75% 만 힙)
Spring Cloud Kubernetes 의 reload: 운영 환경 검증 필요
Spring Boot 의 OCI image (Buildpacks) 사용: Dockerfile 관리 부담 ↓

[Spring Boot] Embedded Web Server 설정과 튜닝

koa (김신건) — Tue, 23 Jun 2026 00:00:00 GMT

정의

Spring Boot 의 starter 가 내장 서버를 함께 번들. 별도 WAR 배포 / 외부 Tomcat 불필요.

기본 매핑:

spring-boot-starter-web → Tomcat (기본)
spring-boot-starter-webflux → Netty
spring-boot-starter-jetty → Jetty
spring-boot-starter-undertow → Undertow

같은 starter 안에서 교체:

implementation("org.springframework.boot:spring-boot-starter-web") {
    exclude(module = "spring-boot-starter-tomcat")
}
implementation("org.springframework.boot:spring-boot-starter-jetty")

기본 설정

server:
  port: 8080
  servlet:
    context-path: /api          # 모든 경로 prefix
  forward-headers-strategy: native   # reverse proxy 뒤 X-Forwarded-* 처리
  compression:
    enabled: true
    mime-types: text/html, application/json
    min-response-size: 1024
  http2:
    enabled: true
  error:
    whitelabel:
      enabled: false

server.port=0 면 random port (테스트에서 흔히 사용).

Tomcat 튜닝

server:
  tomcat:
    threads:
      max: 200                  # 동시 처리 thread
      min-spare: 10
    accept-count: 100           # 큐
    max-connections: 8192       # 동시 연결
    connection-timeout: 20s
    keep-alive-timeout: 60s
    max-keep-alive-requests: 100
    max-http-form-post-size: 2MB
    max-swallow-size: 2MB       # 거부 요청의 본문 읽기 제한
    uri-encoding: UTF-8
    accesslog:
      enabled: true
      pattern: "%t %a \"%r\" %s %b"
      directory: /var/log/tomcat

threads.max 의미

worker thread 수. 요청마다 1 thread 점유. Tomcat 의 blocking 모델이므로:

low-traffic, 빠른 응답: 50~200
high-traffic, DB call 느림: 500~1000
virtual thread 활성화 시 (Spring Boot 3.2+): 의미 사라짐

max-connections vs threads.max

max-connections > threads.max 가 정상. 연결은 keep-alive 로 유지되지만 worker 가 부족하면 큐잉. accept-count 만큼 큐.

virtual thread (Spring Boot 3.2+)

spring:
  threads:
    virtual:
      enabled: true

Tomcat worker pool 이 virtual thread 사용. threads.max 영향 없음. [[spring-virtual-threads]] 참고.

Netty 튜닝 (WebFlux)

server:
  netty:
    connection-timeout: 20s
    idle-timeout: 60s
    max-keep-alive-requests: 1000
spring:
  reactor:
    netty:
      pool:
        max-connections: 10000
        max-idle-time: 30s

Netty 는 이벤트 루프 기반. thread 수 적음 (보통 CPU core × 2). 동시 처리는 connection 수가 결정.

WebFlux + Netty 가 reactive non-blocking 시 가장 자연스러움. [[spring-webflux]] 참고.

Jetty / Undertow

server:
  jetty:
    threads:
      max: 200
      min: 8
    accesslog:
      enabled: true
  undertow:
    threads:
      io: 4
      worker: 64
    buffer-size: 16384

Undertow 는 XNIO 기반. Tomcat 보다 메모리 효율적, throughput 우수.

다이나믹 customization

application.yml 로 안 되는 세밀 조정:

@Component
public class TomcatCustomizer implements WebServerFactoryCustomizer<TomcatServletWebServerFactory> {
    @Override
    public void customize(TomcatServletWebServerFactory factory) {
        factory.addConnectorCustomizers(connector -> {
            connector.setProperty("relaxedQueryChars", "[]|");   // 특수문자 허용
            connector.setProperty("disableUploadTimeout", "false");
            connector.setProperty("connectionUploadTimeout", "120000");
        });

        factory.addContextCustomizers(context -> {
            context.setCookieProcessor(new Rfc6265CookieProcessor());
        });

        factory.setProtocol("org.apache.coyote.http11.Http11AprProtocol");   // APR
    }
}

WebServerFactoryCustomizer<T> Bean 으로 등록. 시작 시 자동 적용.

동적 port

@SpringBootApplication
class App {
    public static void main(String[] args) {
        ConfigurableApplicationContext ctx = SpringApplication.run(App.class, args);
        int port = ctx.getWebServer().getPort();
        System.out.println("Started on port " + port);
    }
}

테스트:

@SpringBootTest(webEnvironment = RANDOM_PORT)
class IntegrationTest {
    @LocalServerPort int port;   // 자동 주입
}

Graceful Shutdown

server:
  shutdown: graceful
spring:
  lifecycle:
    timeout-per-shutdown-phase: 30s

신규 연결 거부
진행 중 요청 완료 대기 (최대 30s)
이후 강제 종료

K8s terminationGracePeriodSeconds 와 맞춤. preStop hook 도 활용.

HTTP/2

server:
  http2:
    enabled: true
  ssl:
    enabled: true
    key-store: classpath:keystore.p12
    key-store-password: ${KEYSTORE_PASSWORD}

HTTP/2 는 보통 SSL 필요 (h2). plaintext HTTP/2 (h2c) 는 reverse proxy 뒤.

Compression

server:
  compression:
    enabled: true
    mime-types:
      - text/html
      - text/xml
      - text/plain
      - text/css
      - text/javascript
      - application/javascript
      - application/json
    min-response-size: 1024

응답 크기 > 1KB 이면 gzip. JSON / HTML / CSS 압축으로 대역폭 절약.

CDN / reverse proxy 가 압축한다면 끄기.

CORS (전역)

@Configuration
class WebConfig implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")
            .allowedOrigins("https://app.example.com")
            .allowedMethods("GET", "POST", "PUT", "DELETE")
            .allowedHeaders("*")
            .allowCredentials(true)
            .maxAge(3600);
    }
}

Spring Security 도 함께 사용 시 SecurityFilterChain 에 cors 활성화 필요:

.cors(c -> c.configurationSource(corsSource))

Static resources

spring:
  web:
    resources:
      static-locations: classpath:/static/, classpath:/public/
      cache:
        period: 30d
        cachecontrol:
          max-age: 30d
          must-revalidate: true
      add-mappings: true
mvc:
  static-path-pattern: /static/**

production: long cache + content hash (Vite / webpack [name].[hash].js).

Error pages

server:
  error:
    whitelabel:
      enabled: false
    include-message: always
    include-binding-errors: always
    include-stacktrace: on-param   # ?trace=true 일 때만
    include-exception: false

전역 @ControllerAdvice 또는 ErrorController 로 custom.

모니터링

management:
  endpoints:
    web:
      exposure:
        include: health, metrics, info, threaddump
  metrics:
    enable:
      tomcat: true
      jvm: true

Tomcat 의 thread pool / connection 상태 → Prometheus / Grafana.

함정과 베스트 프랙티스

production: graceful shutdown + 적절한 timeout
Tomcat threads.max 는 DB connection pool size 와 균형 (worker > pool)
CDN / reverse proxy 뒤 면 forward-headers-strategy: native 필수
HTTPS terminate 위치: 보통 reverse proxy. Spring 은 plain HTTP 받음
virtual thread 활성화 시 worker pool 튜닝 무의미해짐
embedded server 선택: 대부분 기본 Tomcat 으로 충분. 특수 요구 (메모리 ↓, 비동기 ↑) 시만 교체
Netty 와 WebFlux 페어: blocking 코드 섞으면 의미 없음. 모든 단계 reactive 여야

[Spring Boot] Hibernate Naming Strategy

koa (김신건) — Tue, 23 Jun 2026 00:00:00 GMT

정의

Hibernate 가 entity 클래스 / 필드명 → DB table / column 명으로 변환하는 규칙. 두 단계로 분리:

단계	역할	인터페이스
Implicit	entity / field 가 `@Table` / `@Column` 명시 없을 때 논리적 이름 생성 (예: `User` → `User`)	`ImplicitNamingStrategy`
Physical	논리적 이름을 실제 DB 식별자 로 변환 (예: `User` → `user`, `createdAt` → `created_at`)	`PhysicalNamingStrategy`

Spring Boot 의 기본:

Implicit: SpringImplicitNamingStrategy (entity = 클래스명, column = 필드명)
Physical: CamelCaseToUnderscoresNamingStrategy (camelCase → snake_case, 모두 소문자)

따라서 User.createdAt → 테이블 user, 컬럼 created_at. 명시적 어노테이션 없어도 모던 SQL 컨벤션 자동 적용.

자동 변환 예

@Entity
class UserAccount {
    @Id Long id;
    String firstName;
    String lastName;
    LocalDateTime createdAt;
    String OAuthToken;
}

기본 매핑 결과:

CREATE TABLE user_account (
    id           BIGINT PRIMARY KEY,
    first_name   VARCHAR(255),
    last_name    VARCHAR(255),
    created_at   TIMESTAMP,
    o_auth_token VARCHAR(255)    -- 주의: 연속 대문자 분해됨
);

연속 대문자 (OAuthToken) 가 o_auth_token 으로 변환되는 점 주의. 의도와 다르면 @Column(name = "oauth_token") 명시.

설정 파일에서 변경

spring:
  jpa:
    hibernate:
      naming:
        physical-strategy: org.hibernate.boot.model.naming.PhysicalNamingStrategyStandardImpl
        implicit-strategy: org.hibernate.boot.model.naming.ImplicitNamingStrategyLegacyJpaImpl

옵션	동작
`SpringPhysicalNamingStrategy` 또는 `CamelCaseToUnderscoresNamingStrategy` (기본)	camelCase → snake_case
`PhysicalNamingStrategyStandardImpl`	변환 안 함 (논리명 그대로)
커스텀 클래스	직접 구현

Hibernate 6+ 부터 SpringPhysicalNamingStrategy 가 CamelCaseToUnderscoresNamingStrategy 의 alias 처럼 동작.

legacy DB 호환 (변환 안 함)

기존 DB 가 CreatedAt, UserAccount 처럼 PascalCase 면:

spring:
  jpa:
    hibernate:
      naming:
        physical-strategy: org.hibernate.boot.model.naming.PhysicalNamingStrategyStandardImpl

이제 entity 의 식별자가 DB 에 그대로 매핑. @Column 어노테이션 거의 불필요해진다.

커스텀 Physical Strategy

특정 패턴 (예: prefix tbl_, 모든 컬럼 lowercase) 적용:

public class PrefixedPhysicalNamingStrategy implements PhysicalNamingStrategy {
    @Override
    public Identifier toPhysicalCatalogName(Identifier name, JdbcEnvironment ctx) { return name; }
    @Override
    public Identifier toPhysicalSchemaName(Identifier name, JdbcEnvironment ctx) { return name; }
    @Override
    public Identifier toPhysicalTableName(Identifier name, JdbcEnvironment ctx) {
        if (name == null) return null;
        return Identifier.toIdentifier("tbl_" + camelToSnake(name.getText()));
    }
    @Override
    public Identifier toPhysicalSequenceName(Identifier name, JdbcEnvironment ctx) {
        return Identifier.toIdentifier("seq_" + camelToSnake(name.getText()));
    }
    @Override
    public Identifier toPhysicalColumnName(Identifier name, JdbcEnvironment ctx) {
        return Identifier.toIdentifier(camelToSnake(name.getText()).toLowerCase());
    }

    private String camelToSnake(String s) {
        return s.replaceAll("([a-z])([A-Z])", "$1_$2").toLowerCase();
    }
}

spring:
  jpa:
    hibernate:
      naming:
        physical-strategy: com.example.PrefixedPhysicalNamingStrategy

결과:

User → tbl_user
OrderItem → tbl_order_item
createdAt → created_at

다른 strategy 비교

SpringPhysicalNamingStrategy (Spring Boot 기본)

UserAccount.firstName → user_account.first_name

가장 흔한 modern SQL convention.

PhysicalNamingStrategyStandardImpl (Hibernate 기본)

UserAccount.firstName → UserAccount.firstName

논리명 그대로. 식별자 그대로 유지하려는 legacy DB 용.

LegacyJpaImpl

@Table(name="UserAccount")  // 명시 안 하면 클래스명 그대로
class UserAccount { ... }

JPA 2.0 이전 스타일.

Implicit Naming 의 역할

@JoinColumn 명시 안 했을 때 외래키 컬럼명 생성:

@Entity
class Post {
    @ManyToOne
    User author;   // @JoinColumn 없음
}

SpringImplicitNamingStrategy 가 적용 → author_id 자동 생성. 일반적으로 만족스러움.

@OneToMany(mappedBy="...") 의 join 테이블 명, @ElementCollection 컬렉션 테이블 명 등도 implicit 이 결정.

@Column / @Table 명시 vs 자동

// 자동 변환 의존
@Column
String firstName;   // → first_name

// 명시
@Column(name = "first_name")
String firstName;   // 동일하지만 명시적

규칙:

새 프로젝트: 자동 변환 의존, @Column 생략
legacy DB / 컬럼명 특수 패턴: @Column(name=...) 명시
migration 도구 (Flyway, Liquibase) 와 entity 의 컬럼명 일치 강제: 명시 권장

실행 시점에 검증

spring:
  jpa:
    hibernate:
      ddl-auto: validate   # entity 매핑 vs DB 스키마 비교, 불일치 시 시작 실패

운영 환경 권장. naming strategy 가 의도와 다르면 시작 시점에 즉시 발견.

DDL 생성 모드별 영향

spring:
  jpa:
    hibernate:
      ddl-auto: create-drop   # 시작 시 drop + create, naming strategy 가 컬럼명 결정
    properties:
      hibernate:
        physical_naming_strategy: ...

ddl-auto:

create, create-drop: strategy 가 컬럼명 결정 → DB 에 반영
update: 기존 컬럼명 + strategy 둘 다 영향, 충돌 위험
validate: strategy 가 만드는 이름이 DB 에 있는지 비교
none (운영 권장): strategy 가 SELECT/INSERT 만들 때 컬럼명 사용

함정과 베스트 프랙티스

ddl-auto=update 와 strategy 변경 동시 금지: 기존 컬럼명과 새 컬럼명 둘 다 시도하면 schema 가 깨짐
운영: ddl-auto=validate or none + Flyway/Liquibase: 자동 DDL 위험, migration 도구로 관리
@Column(name=...) 와 strategy 의 우선순위: 어노테이션이 항상 이김
연속 대문자 함정: OAuthToken → o_auth_token. 의도 안 맞으면 명시
MySQL 의 case sensitivity 차이: Linux 는 case sensitive, Windows / Mac 은 insensitive. 항상 lowercase 사용 (기본 strategy 가 그렇게 함)
Postgres reserved word: user, order, group 등은 quote 필요. table name 으로 안 쓰는 게 안전
strategy 변경은 신중: 기존 entity 들의 매핑 일괄 변경됨

자주 보는 시나리오

시나리오 1: 새 Spring Boot 프로젝트

spring:
  jpa:
    hibernate:
      ddl-auto: create-drop   # 개발만

기본 SpringPhysicalNamingStrategy 가 알아서 snake_case. 손 댈 필요 없음.

시나리오 2: legacy Oracle DB (UPPER_CASE)

spring:
  jpa:
    hibernate:
      naming:
        physical-strategy: org.hibernate.boot.model.naming.PhysicalNamingStrategyStandardImpl

@Entity
@Table(name = "USER_ACCOUNT")
class UserAccount {
    @Column(name = "FIRST_NAME") String firstName;
}

명시적 @Table / @Column 사용.

시나리오 3: Multi-tenant prefix

public class TenantPrefixedNamingStrategy implements PhysicalNamingStrategy {
    @Override
    public Identifier toPhysicalTableName(Identifier name, JdbcEnvironment ctx) {
        String tenant = TenantContext.current();
        return Identifier.toIdentifier(tenant + "_" + name.getText());
    }
    // ...
}

tenant 별 별도 테이블 (위험한 패턴, 보통 row-level tenancy 가 낫지만 가능).

[Spring Boot] Logging: Logback, Log4j2, Structured Logging

koa (김신건) — Tue, 23 Jun 2026 00:00:00 GMT

정의

Spring Boot 의 기본 로거는 Logback (spring-boot-starter 가 자동 포함). SLF4J facade 위에서 동작.

교체 가능:

spring-boot-starter-log4j2: Log4j2 (높은 처리량, async logger)
java.util.logging: 비권장
SLF4J adapter 로 commons-logging 흡수

대부분 그대로 Logback 사용. 운영 환경에서는 structured JSON 로깅 + MDC + 외부 수집기 (ELK, Loki, CloudWatch) 와 조합.

기본 application.yml 설정

logging:
  level:
    root: INFO
    com.example: DEBUG
    org.springframework.web: INFO
    org.hibernate.SQL: DEBUG
    org.hibernate.orm.jdbc.bind: TRACE
  pattern:
    console: "%d{HH:mm:ss.SSS} %-5level [%thread] %logger{36} - %msg%n"
    file: "%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread] %logger{36} - %msg%n"
  file:
    name: ./logs/app.log
  logback:
    rollingpolicy:
      max-file-size: 10MB
      max-history: 30
      total-size-cap: 1GB
      file-name-pattern: "./logs/app-%d{yyyy-MM-dd}.%i.log"

대부분 use case 는 yml 만으로 충분. xml 은 복잡한 패턴 / appender 필요할 때.

logback-spring.xml (고급)

src/main/resources/logback-spring.xml:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <include resource="org/springframework/boot/logging/logback/defaults.xml"/>
    <property name="LOG_PATH" value="./logs"/>

    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} %-5level [%thread] %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${LOG_PATH}/app.log</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <fileNamePattern>${LOG_PATH}/app-%d{yyyy-MM-dd}.%i.log.gz</fileNamePattern>
            <maxFileSize>10MB</maxFileSize>
            <maxHistory>30</maxHistory>
            <totalSizeCap>1GB</totalSizeCap>
        </rollingPolicy>
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread] %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <appender name="ASYNC_FILE" class="ch.qos.logback.classic.AsyncAppender">
        <queueSize>2048</queueSize>
        <discardingThreshold>0</discardingThreshold>
        <appender-ref ref="FILE"/>
    </appender>

    <springProfile name="dev">
        <root level="DEBUG">
            <appender-ref ref="CONSOLE"/>
        </root>
    </springProfile>

    <springProfile name="prod">
        <root level="INFO">
            <appender-ref ref="ASYNC_FILE"/>
        </root>
    </springProfile>
</configuration>

핵심:

<springProfile> : profile 별 설정
AsyncAppender : I/O 가 핫 스레드 안 막음 (운영 권장)
SizeAndTimeBasedRollingPolicy : 크기 + 날짜 동시 rollover
.gz 확장자: 자동 압축

Structured JSON Logging (운영 권장)

Plain text 로그는 grep 으로 분석. JSON 은 ELK / Loki / Datadog 같은 수집기가 native 파싱.

Spring Boot 3.4+ 내장 지원

logging:
  structured:
    format:
      console: ecs        # Elastic Common Schema
      file: ecs

옵션: ecs, gelf, logstash. 코드 변경 없이 JSON 전환.

Logstash encoder (수동)

implementation("net.logstash.logback:logstash-logback-encoder:7.4")

<appender name="JSON" class="ch.qos.logback.core.ConsoleAppender">
    <encoder class="net.logstash.logback.encoder.LogstashEncoder">
        <fieldNames>
            <timestamp>@timestamp</timestamp>
            <message>message</message>
            <level>level</level>
        </fieldNames>
        <customFields>{"app":"my-app","env":"prod"}</customFields>
        <includeMdc>true</includeMdc>
    </encoder>
</appender>

출력 예:

{"@timestamp":"2026-06-23T10:00:00.123Z","level":"INFO","logger_name":"c.e.OrderService","thread_name":"http-nio-8080-exec-1","message":"order placed","app":"my-app","env":"prod","mdc":{"traceId":"abc123","userId":"42"}}

MDC (Mapped Diagnostic Context)

스레드별 컨텍스트 (request id, user id 등). 자동으로 모든 로그에 첨부:


@Component
public class MdcFilter extends OncePerRequestFilter {
    @Override
    protected void doFilterInternal(HttpServletRequest req, HttpServletResponse resp, FilterChain chain)
            throws IOException, ServletException {
        MDC.put("requestId", UUID.randomUUID().toString());
        MDC.put("clientIp", req.getRemoteAddr());
        try {
            chain.doFilter(req, resp);
        } finally {
            MDC.clear();   // 반드시 정리 (ThreadLocal 누수 방지)
        }
    }
}

pattern 에서 사용:

pattern: "%d{HH:mm:ss.SSS} [%X{requestId}] %-5level %logger{36} - %msg%n"

%X{key} 가 MDC 값. 같은 요청의 모든 로그가 requestId 공유 → 추적 용이.

OpenTelemetry / Micrometer Tracing 통합

Spring Boot 3+ 의 자동 통합:

management:
  tracing:
    sampling:
      probability: 1.0
  endpoints:
    web:
      exposure:
        include: prometheus

traceId, spanId 가 자동으로 MDC 에 추가. 모든 로그에 분산 추적 ID 첨부. Tempo / Jaeger / Zipkin 으로 수집.

@Async 와 MDC

@Async 메서드는 별도 스레드 → MDC 비어 있음. TaskDecorator 로 복사:

public class MdcCopyDecorator implements TaskDecorator {
    @Override
    public Runnable decorate(Runnable runnable) {
        Map<String, String> context = MDC.getCopyOfContextMap();
        return () -> {
            try {
                if (context != null) MDC.setContextMap(context);
                runnable.run();
            } finally {
                MDC.clear();
            }
        };
    }
}

@Bean
TaskExecutor taskExecutor() {
    ThreadPoolTaskExecutor exec = new ThreadPoolTaskExecutor();
    exec.setTaskDecorator(new MdcCopyDecorator());
    exec.initialize();
    return exec;
}

[[spring-request-context]] 참고.

Log4j2 교체

implementation("org.springframework.boot:spring-boot-starter") {
    exclude(module = "spring-boot-starter-logging")
}
implementation("org.springframework.boot:spring-boot-starter-log4j2")

log4j2-spring.xml:

<?xml version="1.0" encoding="UTF-8"?>
<!-- mdx-component: Configuration -->

    <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
            <!-- mdx-component: PatternLayout -->
        </Console>
    </Appenders>
    <Loggers>
        <Root level="INFO">
            <!-- mdx-component: AppenderRef -->
        </Root>
    </Loggers>

Log4j2 장점:

async logger 가 logback 보다 빠름 (Disruptor 기반)
LMAX queue 로 zero allocation
정형식 message: logger.info("user {} placed order {}", userId, orderId) 가 lazy 평가

컨테이너 / K8s 환경

logging:
  pattern:
    console: "%d{ISO8601} %-5level [%thread] %logger{36} - %msg%n"
  level:
    root: INFO
  file:
    name:    # 빈 값 = 파일 출력 비활성

K8s 패턴: stdout 만 출력. 컨테이너가 자체 수집 (Fluentd, Promtail). 파일 로깅 + sidecar 패턴은 deprecated.

비밀번호 / 민감 정보 masking

logger.info("Login attempt: user={}, password={}", username, password);   // ❌ 평문 노출

해결:

로그 메시지에서 명시적으로 제외
@JsonIgnore (직렬화 시) + @ToString.Exclude (Lombok)
Logback 의 filter 로 정규식 마스킹

<appender name="MASKED" class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
    <pattern>%replace(%msg){'(password|ssn)=\\S+', '$1=***'}%n</pattern>
</appender>

동적 log level 변경 (Actuator)

management:
  endpoints:
    web:
      exposure:
        include: loggers

# 현재 level 조회
curl http://localhost:8080/actuator/loggers/com.example

# 변경
curl -X POST http://localhost:8080/actuator/loggers/com.example \
  -H "Content-Type: application/json" \
  -d '{"configuredLevel":"DEBUG"}'

재시작 없이 운영 중 디버그 토글. ([[spring-actuator]] 참고)

함정과 베스트 프랙티스

운영: structured JSON + 수집기: plain text 분석은 한계
MDC 는 try/finally 로 clear: ThreadLocal 누수 방지
@Async / virtual thread 와 MDC: TaskDecorator 필수
AsyncAppender 운영 권장: I/O 가 핫 스레드 막지 않게
password / secret 절대 로그 금지: 정규식 마스킹 안전망
개발: DEBUG, 운영: INFO/WARN: profile 별 분리
<springProfile> 활용: logback xml 안에서 환경 분기
컨테이너: stdout only: 파일 / sidecar 패턴 deprecated
로그 분산 추적 (traceId) 가 modern 운영 표준

김신건의 로그 - 위키 / spring

[JPA] fetch join: JOIN FETCH 로 연관 entity 즉시 로드

정의

시각화

기본 문법

INNER JOIN FETCH

LEFT JOIN FETCH (LEFT OUTER JOIN FETCH)

fetch join 이 하는 일

JOIN vs JOIN FETCH 차이

컬렉션 fetch join 과 카르테시안 곱

DISTINCT 로 해결

hibernate.query.passDistinctThrough

MultipleBagFetchException

해결 1: 하나만 Set 으로 변경

해결 2: 하나만 fetch join, 나머지는 @BatchSize / EntityGraph

해결 3: 두 단계 쿼리

Pageable + 컬렉션 fetch join = in-memory paging

해결 패턴 (2 단계 fetch)

컬렉션 아닌 fetch join 은 OK

Nested fetch join (여러 depth)

Spring Data JPA @Query 통합

fetch join 이 적용되지 않는 경우

1. Native query

2. @Modifying UPDATE / DELETE

3. Cross join

실전 패턴

패턴 1: 단건 상세 조회

패턴 2: 목록 + 요약 정보

패턴 3: 컬렉션 + Pageable (2 단계)

fetch join vs 대안 요약

함정과 베스트 프랙티스

관련 위키

[JPA] FetchType: LAZY vs EAGER, N+1, fetch join

정의

시각화

EAGER 의 함정

LAZY 전환

fetch join

@EntityGraph

@BatchSize (Hibernate 확장)

fetch join vs EntityGraph vs @BatchSize 비교

EntityGraph 의 두 모드

실전 N+1 디버깅

함정과 베스트 프랙티스

관련 위키

[Spring MVC] Argument Resolver: Custom HandlerMethodArgumentResolver

정의

표준 ArgumentResolver

흐름

Custom ArgumentResolver: 예시

1. 어노테이션 정의

2. Resolver 구현

3. 등록

4. 사용

사례: API Pagination

ReturnValueHandler: 반환값 처리

표준 vs Custom 비교

옛 방식 vs 새 방식

흔한 함정

관련 위키

[Spring MVC] Content Negotiation: Accept 헤더, MediaType, ContentNegotiationStrategy

정의

결정 우선순위

기본 동작

produces / consumes

ContentNegotiationConfigurer

HttpMessageConverter

등록 / 우선순위 변경

Accept 의 quality value (q)

API Versioning by Accept

CSV 응답 예시 (custom)

REST 응답 패턴

REST + 뷰 (옛 패턴)

흔한 함정

관련 위키

[Spring MVC] Exception Handling: @ExceptionHandler, ControllerAdvice, ProblemDetail

정의

처리 우선순위

컨트롤러 내부

@ControllerAdvice / @RestControllerAdvice

해결 1: 하나만 `Set` 으로 변경

해결 2: 하나만 fetch join, 나머지는 `@BatchSize` / EntityGraph

2. `@Modifying` UPDATE / DELETE

URL 표현식 (`@{...}`)