IT 연구소

Spring Boot JPA Auditing(@CreatedDate 등)로 생성/수정 시간 자동 기록하기

IT Lab — Tue, 17 Mar 2026 20:00:23 +0900

Spring Boot 3.x에서 JPA Auditing으로 createdAt/updatedAt을 자동 채우는 방법과 베이스 엔티티 설계, 운영에서 자주 겪는 함정을 정리합니다.

도입 (문제 상황)

엔티티를 저장할 때마다 createdAt, updatedAt을 매번 세팅하다 보면, 한두 군데는 꼭 빠지기 마련입니다. 특히 배치/관리자 기능/테스트 코드에서 누락되면 “왜 어떤 데이터는 시간이 비어 있지?” 같은 운영 이슈로 이어지기도 해요. 이럴 때 JPA Auditing을 쓰면 생성/수정 시간을 거의 자동화할 수 있습니다.

핵심 개념 — Spring Boot JPA Auditing이 중요한 이유

JPA Auditing은 엔티티의 “언제 생성/수정됐는지(그리고 누가 했는지)” 같은 메타 정보를 영속성 이벤트 시점에 자동으로 채워주는 기능입니다. 핵심은 두 가지예요.

애플리케이션 코드에서 시간 세팅 책임을 제거합니다.
서비스/컨트롤러/배치 어디에서 저장하든, 엔티티가 persist/update 되는 순간에 동일한 규칙으로 값이 들어갑니다. 마치 “DB 트리거”처럼 동작하지만, 로직은 애플리케이션에 있어 테스트와 유지보수가 쉬워요.
베이스 엔티티로 표준화할 수 있습니다.
여러 엔티티에 createdAt, updatedAt 필드를 반복해서 만들지 않고, @MappedSuperclass 기반의 베이스 클래스로 공통화하면 누락도 줄고 일관성도 좋아집니다.

다만 “완전 자동”이라고 해서 아무 생각 없이 붙이면 운영에서 문제가 생길 수 있는 포인트도 있습니다. 대표적으로는:

시간대(UTC vs KST) 정책이 불명확해서 데이터가 뒤섞임
updatedAt이 기대대로 갱신되지 않는 케이스(변경 감지/더티체킹 조건)
DB 기본값/트리거와 Auditing이 충돌

아래 예제로 가장 흔한 형태(생성/수정 시간 자동화 + 베이스 엔티티)를 Spring Boot 3.x 기준으로 정리해 보겠습니다.

flowchart LR
  A["Service"] --> B["Repository save()"]
  B --> C["JPA EntityManager"]
  C --> D["AuditingEntityListener"]
  D --> E["@CreatedDate / @LastModifiedDate set"]
  E --> F["DB Insert/Update"]

JPA 저장/수정 이벤트에서 Auditing 리스너가 값을 채운 뒤 DB에 반영되는 흐름입니다.

코드 예제 — @CreatedDate/@LastModifiedDate 베이스 엔티티로 바로 적용하기

아래 코드는 그대로 복붙해서 실행 가능한 최소 구성입니다. (Java 17, Spring Boot 3.x)

build.gradle

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.3.2'
    id 'io.spring.dependency-management' version '1.1.6'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    runtimeOnly 'com.h2database:h2'

    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

tasks.named('test') {
    useJUnitPlatform()
}

application.yml

spring:
  datasource:
    url: jdbc:h2:mem:testdb;MODE=PostgreSQL;DB_CLOSE_DELAY=-1
    driver-class-name: org.h2.Driver
    username: sa
    password:

  jpa:
    hibernate:
      ddl-auto: create
    properties:
      hibernate:
        format_sql: true

logging:
  level:
    org.hibernate.SQL: debug

운영 DB를 쓰실 때도 Auditing 자체는 동일하지만, 시간대 정책(UTC 고정 등)은 별도로 정하시는 게 중요합니다.

Auditing 활성화 설정

package com.example.demo;

import org.springframework.context.annotation.Configuration;
import org.springframework.data.jpa.repository.config.EnableJpaAuditing;

@Configuration
@EnableJpaAuditing
public class JpaAuditingConfig {
}

베이스 엔티티 (생성/수정 시간)

package com.example.demo.domain;

import jakarta.persistence.Column;
import jakarta.persistence.EntityListeners;
import jakarta.persistence.MappedSuperclass;
import org.springframework.data.annotation.CreatedDate;
import org.springframework.data.annotation.LastModifiedDate;
import org.springframework.data.jpa.domain.support.AuditingEntityListener;

import java.time.Instant;

@MappedSuperclass
@EntityListeners(AuditingEntityListener.class)
public abstract class BaseTimeEntity {

    @CreatedDate
    @Column(name = "created_at", nullable = false, updatable = false)
    private Instant createdAt;

    @LastModifiedDate
    @Column(name = "updated_at", nullable = false)
    private Instant updatedAt;

    public Instant getCreatedAt() {
        return createdAt;
    }

    public Instant getUpdatedAt() {
        return updatedAt;
    }
}

Instant를 쓰면 시간대 혼선을 줄이기 좋습니다(UTC 기반).
createdAt은 updatable = false로 막아두면 실수로 덮어쓰는 사고를 줄일 수 있어요.

예시 엔티티/리포지토리

package com.example.demo.domain;

import jakarta.persistence.*;

@Entity
@Table(name = "posts")
public class Post extends BaseTimeEntity {

    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false)
    private String title;

    protected Post() {}

    public Post(String title) {
        this.title = title;
    }

    public Long getId() {
        return id;
    }

    public String getTitle() {
        return title;
    }

    public void changeTitle(String title) {
        this.title = title;
    }
}

package com.example.demo.domain;

import org.springframework.data.jpa.repository.JpaRepository;

public interface PostRepository extends JpaRepository<Post, Long> {
}

동작 확인용 컨트롤러

package com.example.demo.web;

import com.example.demo.domain.Post;
import com.example.demo.domain.PostRepository;
import org.springframework.transaction.annotation.Transactional;
import org.springframework.web.bind.annotation.*;

import java.time.Instant;
import java.util.Map;

@RestController
public class PostController {

    private final PostRepository postRepository;

    public PostController(PostRepository postRepository) {
        this.postRepository = postRepository;
    }

    @PostMapping("/posts")
    public Map<String, Object> create(@RequestParam String title) {
        Post saved = postRepository.save(new Post(title));
        return Map.of(
                "id", saved.getId(),
                "createdAt", saved.getCreatedAt(),
                "updatedAt", saved.getUpdatedAt()
        );
    }

    @Transactional
    @PatchMapping("/posts/{id}")
    public Map<String, Object> update(@PathVariable Long id, @RequestParam String title) {
        Post post = postRepository.findById(id).orElseThrow();
        Instant before = post.getUpdatedAt();

        post.changeTitle(title); // 더티체킹으로 update 발생 시 updatedAt 갱신

        return Map.of(
                "id", post.getId(),
                "updatedAtBefore", before,
                "updatedAtAfter", post.getUpdatedAt()
        );
    }
}

한눈에 정리: Auditing vs DB 기본값/트리거

운영에서 “어디에서 시간을 책임질지”를 먼저 정하시는 게 좋아요.

방식	장점	단점/주의	추천 상황
JPA Auditing	애플리케이션 표준화, 테스트 용이, 엔티티 단에서 일관적	시간대 정책 필요, 일부 업데이트 케이스에서 기대와 다를 수 있음	대부분의 Spring Boot/JPA 서비스
DB DEFAULT(now)	DB가 강제, 타 언어/도구로 넣어도 동일	수정 시간 자동화는 별도 처리 필요, DB 종속	생성 시간만 간단히 보장하고 싶을 때
DB Trigger	insert/update 모두 강제 가능	디버깅/테스트 어려움, 운영 변경 부담	다수 시스템이 같은 테이블을 갱신하는 환경

JPA Auditing과 DB 트리거/기본값 비교 개념도

실무 팁

실무에서는: 시간 타입/시간대(UTC)부터 먼저 합의해 보세요
LocalDateTime은 “시간대 정보가 없는 값”이라, 서버/배치/운영자 PC가 서로 다른 시간대를 쓰면 해석이 꼬일 수 있습니다. 가능하면 DB에는 Instant(UTC)로 저장하고, 화면/API 응답에서만 KST로 변환하는 방식이 운영 사고가 적습니다.
또한 createdAt/updatedAt 컬럼에는 인덱스가 필요한지(예: 최신순 조회, 기간 검색)를 초기에 같이 검토해 두는 편이 좋습니다.

실무에서는: updatedAt이 안 바뀌는 “정상 케이스”가 있습니다
@LastModifiedDate는 “업데이트 쿼리가 실제로 나갈 때” 갱신됩니다. 즉, 엔티티 값을 바꾸지 않았거나(더티 아님), 변경이 감지되지 않는 방식으로 수정했다면(예: 일부 네이티브 쿼리/벌크 업데이트) updatedAt이 기대대로 안 바뀔 수 있어요.

벌크 업데이트(JPQL update)는 영속성 컨텍스트를 우회하므로 Auditing도 우회합니다. 이런 경우 updated_at = now()를 쿼리에 명시하거나, 벌크 작업 후 clear() 전략을 포함해 설계해 보세요.

핵심 요약

JPA Auditing은 생성/수정 시간 기록을 저장 시점에 자동화해 누락과 중복 코드를 줄여줍니다.
@MappedSuperclass + BaseTimeEntity로 공통 필드를 표준화하는 게 가장 실용적입니다.
운영에서는 시간대(UTC) 정책과 벌크 업데이트 시 Auditing 우회 문제를 특히 주의하세요.

다음 글: [#20 QueryDSL 도입 전 꼭 알아야 할 것들]

Spring Boot 페이징과 정렬 실전 가이드 (성능 함정: Slice vs Page, count 최적화, keyset pagination)

IT Lab — Tue, 17 Mar 2026 10:00:10 +0900

Spring Boot 3.x + Spring Data JPA에서 Pageable을 제대로 쓰는 방법과 Page/Slice 선택 기준, count 쿼리 최적화, keyset pagination(커서 페이징)까지 실전 관점으로 정리합니다.

도입 (문제 상황)

목록 API를 만들 때 Pageable만 붙이면 끝일 것 같지만, 운영에 올리면 갑자기 DB가 느려지거나 count 쿼리가 병목이 되는 경우가 많습니다. 특히 “페이지 수를 보여줘야 해서 Page로 했는데 응답이 느려요” 같은 상황을 자주 겪으실 거예요. 이번 글에서는 페이징/정렬을 “되는 코드”가 아니라 “성능까지 고려한 코드”로 만드는 기준을 잡아봅니다.

핵심 개념: Spring Data JPA 페이징/정렬에서 진짜 중요한 것들

1) Pageable은 편하지만, Page는 공짜가 아닙니다

Pageable을 Repository 메서드에 받으면 Spring Data JPA가 limit/offset + order by를 자동으로 만들어 줍니다. 문제는 반환 타입이 Page<T>일 때입니다.

Page<T>는 totalElements, totalPages가 필요해서 추가로 count 쿼리를 실행합니다.
이 count 쿼리가 단순 테이블이면 괜찮지만, join / group by / distinct가 섞이면 갑자기 비싸질 수 있습니다.

반면 Slice<T>는 “다음 페이지가 있는지”만 판단하기 위해 한 건을 더 조회하는 방식이라 count 쿼리가 없습니다. 즉, “총 페이지 수”가 꼭 필요하지 않다면 Slice가 더 안전한 기본값이 됩니다.

2) Slice vs Page 선택 기준 (실무에서 자주 헷갈리는 부분)

아래 표처럼 “UI/요구사항” 기준으로 결정하시면 실수가 줄어듭니다.

구분	Page	Slice
totalElements/totalPages	제공함 (count 쿼리 필요)	제공 안 함
성능	count가 비싸면 느려짐	대체로 유리
적합한 UI	“1/123 페이지” 같은 페이지 네비게이션	“더보기”, 무한 스크롤
쿼리 특징	content 쿼리 + count 쿼리	content 쿼리(plus 1 row)

3) count 쿼리 최적화: “content 쿼리”와 분리해서 생각하기

Page를 써야 한다면, 핵심은 count 쿼리를 단순하게 만드는 것입니다.

content 조회는 필요한 join/fetch를 하더라도
count는 가능하면 join 없이, 혹은 최소한의 조건만으로 세는 게 좋습니다.

Spring Data JPA에서는 @Query(value=..., countQuery=...)로 content와 count를 분리할 수 있습니다. 이게 실무에서 가장 효과가 큰 최적화 포인트 중 하나입니다.

4) offset pagination의 함정과 keyset pagination(커서 페이징) 맛보기

page=5000처럼 offset이 커지면 DB는 “앞의 4999페이지를 건너뛰기” 위해 내부적으로 많은 작업을 하게 됩니다. 정렬 컬럼에 인덱스가 있어도 offset이 커질수록 비용이 증가하는 패턴이 흔합니다.

이때 대안이 keyset pagination(커서 기반)입니다.

offset 대신 “마지막으로 본 id/시간” 같은 커서를 넘깁니다.
where id < :cursor order by id desc limit :size 형태로 동작합니다.
큰 페이지로 갈수록 느려지는 문제가 줄어듭니다.

다만 “임의 페이지로 점프”는 어렵고, 커서 설계(정렬 키의 유일성 확보)가 필요합니다. 그래서 보통 무한 스크롤/피드형에 먼저 적용해 보시길 권합니다.

flowchart LR
  A["Client 요청"] --> B["Spring Data JPA"]
  B --> C["Offset pagination: limit/offset + order by"]
  B --> D["Keyset pagination: where key < cursor + limit"]
  C --> E["DB: offset 커질수록 부담 증가"]
  D --> F["DB: 인덱스 타고 다음 구간 조회"]

offset은 뒤로 갈수록 비싸지고, keyset은 “다음 구간”을 인덱스로 이어서 읽는 구조입니다.

Offset pagination과 keyset pagination의 성능 차이를 보여주는 개념도

코드 예제: Pageable, Slice vs Page, count 최적화, keyset pagination

아래 코드는 Spring Boot 3.x + Java 17 + Spring Data JPA 기준으로 바로 실행 가능한 예시입니다. H2로 동작하며, /posts/page, /posts/slice, /posts/keyset 세 가지 엔드포인트로 비교해 볼 수 있습니다.

build.gradle

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.3.2'
    id 'io.spring.dependency-management' version '1.1.6'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'

java {
    toolchain { languageVersion = JavaLanguageVersion.of(17) }
}

repositories { mavenCentral() }

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    runtimeOnly 'com.h2database:h2'
}

application.yml

spring:
  datasource:
    url: jdbc:h2:mem:demo;MODE=PostgreSQL;DB_CLOSE_DELAY=-1
    driver-class-name: org.h2.Driver
    username: sa
    password:
  jpa:
    hibernate:
      ddl-auto: create
    properties:
      hibernate:
        format_sql: true
  h2:
    console:
      enabled: true

logging:
  level:
    org.hibernate.SQL: debug
    org.hibernate.orm.jdbc.bind: trace

도메인: Post

package com.example.demo;

import jakarta.persistence.*;
import java.time.Instant;

@Entity
@Table(indexes = {
        @Index(name = "idx_post_created_id", columnList = "createdAt, id")
})
public class Post {

    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false)
    private String title;

    @Column(nullable = false)
    private Instant createdAt;

    protected Post() {}

    public Post(String title, Instant createdAt) {
        this.title = title;
        this.createdAt = createdAt;
    }

    public Long getId() { return id; }
    public String getTitle() { return title; }
    public Instant getCreatedAt() { return createdAt; }
}

Repository: Page / Slice / countQuery 분리 / keyset

package com.example.demo;

import org.springframework.data.domain.*;
import org.springframework.data.jpa.repository.*;
import org.springframework.data.repository.query.Param;

public interface PostRepository extends JpaRepository<Post, Long> {

    // 1) Page: count 쿼리가 함께 나감
    Page<Post> findByTitleContainingIgnoreCase(String keyword, Pageable pageable);

    // 2) Slice: count 쿼리 없이 다음 페이지 여부만 판단
    Slice<Post> findSliceByTitleContainingIgnoreCase(String keyword, Pageable pageable);

    // 3) Page + countQuery 최적화 예시
    // content 쿼리는 정렬/조건을 유지하되, count는 가볍게 분리할 수 있음
    @Query(
        value = """
            select p
            from Post p
            where lower(p.title) like lower(concat('%', :keyword, '%'))
            """,
        countQuery = """
            select count(p.id)
            from Post p
            where lower(p.title) like lower(concat('%', :keyword, '%'))
            """
    )
    Page<Post> searchPageOptimizedCount(@Param("keyword") String keyword, Pageable pageable);

    // 4) Keyset pagination: "id desc" 기준 커서 페이징 맛보기
    @Query("""
        select p
        from Post p
        where (:cursorId is null or p.id < :cursorId)
        order by p.id desc
    """)
    Slice<Post> findNextByIdDesc(@Param("cursorId") Long cursorId, Pageable pageable);
}

Controller

package com.example.demo;

import org.springframework.data.domain.*;
import org.springframework.web.bind.annotation.*;

import java.util.Map;

@RestController
@RequestMapping("/posts")
public class PostController {

    private final PostRepository postRepository;

    public PostController(PostRepository postRepository) {
        this.postRepository = postRepository;
    }

    // Page 예시: totalElements/totalPages 필요할 때
    @GetMapping("/page")
    public Map<String, Object> page(
            @RequestParam(defaultValue = "") String q,
            @PageableDefault(size = 20, sort = "id", direction = Sort.Direction.DESC) Pageable pageable
    ) {
        Page<Post> page = postRepository.searchPageOptimizedCount(q, pageable);

        return Map.of(
                "contentSize", page.getContent().size(),
                "totalElements", page.getTotalElements(),
                "totalPages", page.getTotalPages(),
                "hasNext", page.hasNext(),
                "contentIds", page.getContent().stream().map(Post::getId).toList()
        );
    }

    // Slice 예시: 무한 스크롤/더보기
    @GetMapping("/slice")
    public Map<String, Object> slice(
            @RequestParam(defaultValue = "") String q,
            @PageableDefault(size = 20, sort = "id", direction = Sort.Direction.DESC) Pageable pageable
    ) {
        Slice<Post> slice = postRepository.findSliceByTitleContainingIgnoreCase(q, pageable);

        return Map.of(
                "contentSize", slice.getContent().size(),
                "hasNext", slice.hasNext(),
                "contentIds", slice.getContent().stream().map(Post::getId).toList()
        );
    }

    // Keyset pagination: cursorId를 넘겨서 다음 묶음을 가져옴
    @GetMapping("/keyset")
    public Map<String, Object> keyset(
            @RequestParam(required = false) Long cursorId,
            @RequestParam(defaultValue = "20") int size
    ) {
        // keyset에서는 정렬이 고정되는 경우가 많아 Pageable에 sort를 외부 입력으로 받지 않는 편이 안전합니다.
        Pageable pageable = PageRequest.of(0, size);

        Slice<Post> slice = postRepository.findNextByIdDesc(cursorId, pageable);
        Long nextCursor = slice.getContent().isEmpty()
                ? null
                : slice.getContent().get(slice.getContent().size() - 1).getId();

        return Map.of(
                "cursorId", cursorId,
                "nextCursorId", nextCursor,
                "hasNext", slice.hasNext(),
                "contentIds", slice.getContent().stream().map(Post::getId).toList()
        );
    }
}

데이터 초기화 (실행 시 더미 데이터 생성)

package com.example.demo;

import org.springframework.boot.CommandLineRunner;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.time.Instant;
import java.util.stream.IntStream;

@Configuration
public class DataInit {

    @Bean
    CommandLineRunner init(PostRepository postRepository) {
        return args -> {
            if (postRepository.count() > 0) return;

            Instant now = Instant.now();
            IntStream.rangeClosed(1, 500).forEach(i -> {
                postRepository.save(new Post("post " + i, now.minusSeconds(i)));
            });
        };
    }
}

애플리케이션 엔트리포인트

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

호출 예시

Page: GET /posts/page?q=post&page=0&size=20&sort=id,desc
Slice: GET /posts/slice?q=post&page=0&size=20&sort=id,desc
Keyset:
- 첫 페이지: GET /posts/keyset?size=20
- 다음 페이지: GET /posts/keyset?cursorId=481&size=20 (응답의 nextCursorId를 이어서 사용)

실무 팁

실무에서는: “Page를 기본값”으로 두지 말고, UI 요구사항부터 확인해 보세요

페이지 네비게이션(총 페이지 수 노출)이 꼭 필요할 때만 Page를 쓰는 편이 안전합니다.
무한 스크롤/더보기라면 Slice로 시작하면 count 병목을 원천적으로 피할 수 있습니다.
특히 검색 조건이 복잡해질수록 count는 예상보다 비싸집니다(조인/중복 제거가 끼면 더 심해요).

실무에서는: 정렬(sort)을 그대로 외부 입력으로 노출할 때 화이트리스트를 두는 게 좋습니다

Pageable의 sort 파라미터를 그대로 받으면, 인덱스가 없는 컬럼 정렬로 인해 느려질 수 있습니다.
컨트롤러에서 허용할 정렬 키를 제한하거나, 아예 정렬을 고정하고(예: id desc, createdAt desc) 필요한 경우에만 옵션을 열어두는 방식이 운영에서 안정적입니다.
keyset pagination은 “정렬 키가 유일해야” 페이지 중복/누락이 줄어듭니다. 보통 (createdAt, id)처럼 타이브레이커를 함께 쓰는 패턴을 고려해 보세요.

핵심 요약

Page는 편하지만 count 쿼리 비용이 숨어 있어, 느려질 여지가 큽니다.
“총 페이지 수”가 필요 없으면 Slice가 더 안전한 선택입니다.
offset이 커지는 목록은 keyset pagination을 검토해 보세요.

다음 글: [#19 JPA Auditing(@CreatedDate 등)로 자동 기록]

Spring Boot JPA N+1 문제 원인과 해결 전략 (fetch join / EntityGraph / 배치 사이즈)

IT Lab — Mon, 16 Mar 2026 21:28:03 +0900

Spring Boot 3.x에서 JPA N+1 문제가 발생하는 조건을 정리하고, fetch join과 @EntityGraph로 해결하는 방법, 그리고 batch size로 보완하는 실무 전략을 예제 코드로 설명합니다.

도입 (문제 상황)

목록 API 하나 만들었을 뿐인데, 로컬에서는 빠르다가 데이터가 조금만 늘면 갑자기 DB 쿼리가 수십~수백 번 나가는 경험을 하실 때가 있습니다. 로그를 보면 “주 쿼리 1번 + 연관 엔티티 조회 쿼리 N번” 패턴이 반복되는데, 이게 대표적인 N+1 문제입니다.

핵심 개념: N+1이 왜 생기고, 무엇을 선택해야 하나요?

N+1은 “연관 로딩 전략”과 “조회 방식”이 맞물릴 때 발생합니다. 보통은 @ManyToOne(fetch = LAZY) / @OneToMany(fetch = LAZY)로 지연 로딩을 해두고(이 자체는 권장), 목록을 가져온 뒤 화면/DTO 구성 과정에서 연관 필드를 접근하면서 추가 쿼리가 터집니다.

예를 들어 Order 목록을 20개 조회한 뒤, 각 주문의 member.getName()을 접근하면:

주문 목록 1번 쿼리
각 주문의 member 로딩 20번 쿼리(영속성 컨텍스트에 없는 경우) → 총 21번이 됩니다.

여기서 중요한 포인트는 “LAZY가 나쁘다”가 아니라, LAZY를 유지하되 ‘필요한 화면’에서만 계획적으로 한 번에 가져오도록 조회 쿼리를 설계하는 것입니다. 해결책은 크게 3가지 축으로 정리할 수 있습니다.

전략	언제 쓰면 좋은가요?	장점	주의점
`fetch join`	특정 화면/기능에서 연관 데이터를 확실히 같이 써야 할 때	쿼리 1번으로 끝내기 쉬움, 명시적	컬렉션 fetch join은 페이징이 위험(메모리 페이징/중복 row)
`@EntityGraph`	“기본 쿼리는 유지”하면서 연관 로딩만 옵션으로 붙이고 싶을 때	Repository 메서드에 선언적으로 적용	내부적으로 fetch join과 유사, 컬렉션 + 페이징 이슈는 동일
Batch Size (`default_batch_fetch_size` / `@BatchSize`)	fetch join이 곤란(페이징, 다양한 화면)하지만 N+1을 줄이고 싶을 때	N+1을 1+N/batch로 완화, 페이징과 공존	“완전 제거”가 아니라 “완화”, IN 쿼리 크기/DB 부하 고려

요청 처리 관점에서 N+1이 터지는 흐름

N+1은 보통 “조회 시점”이 아니라 “연관 필드 접근 시점”에 발생합니다. 그래서 컨트롤러/서비스에서 DTO 변환을 하는 순간 갑자기 쿼리가 늘어납니다.

flowchart LR
  A["Controller"] --> B["Service: findOrders()"]
  B --> C["Repository: select orders (1 query)"]
  A --> D["DTO mapping: order.member.name access"]
  D --> E["Lazy loading: select member (N queries)"]

위 다이어그램은 “조회 1번 후 DTO 매핑에서 지연 로딩이 연쇄적으로 발생”하는 전형적인 N+1 흐름입니다.

N+1 문제 흐름을 보여주는 간단한 요청-조회-지연로딩 구조 다이어그램

코드 예제: fetch join / @EntityGraph / 배치 사이즈까지 한 번에 실행해보기

아래 예제는 Spring Boot 3.x + Java 17 + Hibernate(JPA) 기준입니다. H2로 실행 가능하게 구성했고, Order -> Member (ManyToOne) / Order -> OrderItem (OneToMany) 관계에서 N+1을 재현한 뒤 해결합니다.

build.gradle

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.3.2'
    id 'io.spring.dependency-management' version '1.1.6'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

repositories { mavenCentral() }

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    runtimeOnly 'com.h2database:h2'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

application.yml

spring:
  datasource:
    url: jdbc:h2:mem:nplus1;MODE=MySQL;DB_CLOSE_DELAY=-1
    driver-class-name: org.h2.Driver
    username: sa
    password:

  jpa:
    hibernate:
      ddl-auto: create
    properties:
      hibernate:
        format_sql: true
        highlight_sql: true
        show_sql: true
        # 배치 사이즈 전략(전역): 지연 로딩 컬렉션/프록시를 IN 쿼리로 묶어서 가져옵니다.
        default_batch_fetch_size: 100

엔티티

package com.example.nplus1.domain;

import jakarta.persistence.*;
import java.util.ArrayList;
import java.util.List;

@Entity
@Table(name = "members")
public class Member {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;

    protected Member() {}
    public Member(String name) { this.name = name; }

    public Long getId() { return id; }
    public String getName() { return name; }
}

package com.example.nplus1.domain;

import jakarta.persistence.*;

@Entity
@Table(name = "orders")
public class Order {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    // 실무 기본값: LAZY
    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "member_id")
    private Member member;

    protected Order() {}
    public Order(Member member) { this.member = member; }

    public Long getId() { return id; }
    public Member getMember() { return member; }
}

package com.example.nplus1.domain;

import jakarta.persistence.*;

@Entity
@Table(name = "order_items")
public class OrderItem {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String itemName;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "order_id")
    private Order order;

    protected OrderItem() {}
    public OrderItem(Order order, String itemName) {
        this.order = order;
        this.itemName = itemName;
    }

    public Long getId() { return id; }
    public String getItemName() { return itemName; }
}

예제는 핵심을 위해 OrderItem 컬렉션 매핑을 생략했습니다(컬렉션 fetch join 페이징 이슈를 설명하기 위함). 실무에서는 Order에 @OneToMany(mappedBy="order")가 있을 가능성이 높고, 그 경우 N+1이 더 자주 터집니다.

Repository: 기본 조회 / fetch join / EntityGraph

package com.example.nplus1.repository;

import com.example.nplus1.domain.Order;
import org.springframework.data.jpa.repository.EntityGraph;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;

import java.util.List;

public interface OrderRepository extends JpaRepository<Order, Long> {

    // 1) 기본 조회: 이후 member 접근 시 N+1 발생 가능
    List<Order> findTop20ByOrderByIdAsc();

    // 2) fetch join: 필요한 연관을 명시적으로 한 번에 로딩
    @Query("select o from Order o join fetch o.member order by o.id asc")
    List<Order> findTop20WithMemberFetchJoin();

    // 3) EntityGraph: 선언적으로 fetch 옵션 부여(내부적으로 fetch join과 유사)
    @EntityGraph(attributePaths = "member")
    List<Order> findTop20ByOrderByIdAscWithGraph();
}

DTO + Service

package com.example.nplus1.web;

public record OrderResponse(Long orderId, String memberName) { }

package com.example.nplus1.service;

import com.example.nplus1.repository.OrderRepository;
import com.example.nplus1.web.OrderResponse;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import java.util.List;

@Service
@Transactional(readOnly = true)
public class OrderQueryService {
    private final OrderRepository orderRepository;

    public OrderQueryService(OrderRepository orderRepository) {
        this.orderRepository = orderRepository;
    }

    public List<OrderResponse> nPlusOneCase() {
        return orderRepository.findTop20ByOrderByIdAsc()
                .stream()
                // 여기서 member 접근 시점에 추가 쿼리가 발생할 수 있습니다.
                .map(o -> new OrderResponse(o.getId(), o.getMember().getName()))
                .toList();
    }

    public List<OrderResponse> fetchJoinCase() {
        return orderRepository.findTop20WithMemberFetchJoin()
                .stream()
                .map(o -> new OrderResponse(o.getId(), o.getMember().getName()))
                .toList();
    }

    public List<OrderResponse> entityGraphCase() {
        return orderRepository.findTop20ByOrderByIdAscWithGraph()
                .stream()
                .map(o -> new OrderResponse(o.getId(), o.getMember().getName()))
                .toList();
    }
}

Controller

package com.example.nplus1.web;

import com.example.nplus1.service.OrderQueryService;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@RestController
public class OrderController {
    private final OrderQueryService service;

    public OrderController(OrderQueryService service) {
        this.service = service;
    }

    @GetMapping("/orders/n-plus-one")
    public List<OrderResponse> nPlusOne() {
        return service.nPlusOneCase();
    }

    @GetMapping("/orders/fetch-join")
    public List<OrderResponse> fetchJoin() {
        return service.fetchJoinCase();
    }

    @GetMapping("/orders/entity-graph")
    public List<OrderResponse> entityGraph() {
        return service.entityGraphCase();
    }
}

초기 데이터 로더

package com.example.nplus1;

import com.example.nplus1.domain.Member;
import com.example.nplus1.domain.Order;
import jakarta.persistence.EntityManager;
import org.springframework.boot.CommandLineRunner;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.transaction.annotation.Transactional;

@Configuration
public class DataInit {

    @Bean
    CommandLineRunner init(EntityManager em) {
        return args -> initData(em);
    }

    @Transactional
    void initData(EntityManager em) {
        for (int i = 1; i <= 20; i++) {
            Member m = new Member("member-" + i);
            em.persist(m);

            Order o = new Order(m);
            em.persist(o);
        }
        em.flush();
        em.clear();
    }
}

실행 후:

/orders/n-plus-one 호출: orders 1번 + members 최대 20번(상황에 따라) 로그가 찍힐 수 있습니다.
/orders/fetch-join, /orders/entity-graph 호출: 대체로 1번 쿼리로 해결됩니다.

배치 사이즈 전략은 어디에 효과가 있나요?

위 예제처럼 ManyToOne만 있는 경우에도 배치 로딩이 동작할 수 있지만, 실무에서 더 체감되는 구간은 컬렉션(OneToMany) 지연 로딩입니다. 예를 들어 주문 20개를 조회한 뒤 각 주문의 orderItems.size()를 접근하면 원래는 1 + 20 쿼리인데, default_batch_fetch_size=100이면 대략 1 + 1(또는 몇 번)로 줄어듭니다.
즉, 배치 사이즈는 “N+1을 없애는 칼”이라기보다 “N을 뭉쳐서 덜 아프게 만드는 진통제”에 가깝습니다.

[IMAGE_PROMPT] 위치: 코드 예제 섹션의 배치 사이즈 설명 문단 아래 alt: default_batch_fetch_size로 N개의 지연 로딩 쿼리가 IN 쿼리 몇 번으로 합쳐지는 그림 prompt: clean minimal tech blog style white background infographic showing N+1 queries collapsing into fewer batched IN queries using default_batch_fetch_size, simple database icon and query bubbles, minimal text style: infographic [/IMAGE_PROMPT]

실무 팁

실무에서는: fetch join과 페이징은 특히 조심해 보세요
컬렉션(OneToMany)에 fetch join을 걸고 Pageable을 적용하면, SQL row가 뻥튀기되어 DB 페이징이 깨지거나(중복 row) Hibernate가 메모리에서 페이징하려고 시도할 수 있습니다. 목록 + 페이징이 필요하면 보통은

루트 엔티티만 페이징 조회 → 2) 필요한 연관은 배치 로딩으로 완화
같은 2단계 접근이 안전합니다.

실무에서는: “화면/유스케이스 단위”로 로딩 전략을 고르세요
엔티티의 fetch 타입을 EAGER로 바꿔서 응급처치하는 경우가 있는데, 이는 다른 화면에서 불필요한 조인/쿼리를 유발해 더 큰 성능 문제로 돌아오는 일이 많습니다(공식적으로도 EAGER 남용은 비추천입니다).
대신 Repository 레벨에서

이 화면은 fetch join
저 API는 @EntityGraph
페이징 목록은 batch size
처럼 조회 메서드 단위로 의도를 드러내는 방식이 유지보수에 유리합니다.

핵심 요약: N+1은 “조회 후 DTO/뷰 구성 중 지연 로딩 접근”에서 터지는 경우가 가장 흔합니다.
fetch join과 @EntityGraph는 “필요한 연관을 한 번에” 가져오는 1차 해결책이고, 배치 사이즈는 페이징/다양한 화면에서 N+1을 완화하는 현실적인 보완책입니다.
EAGER로 덮기보다 “유스케이스별 조회 전략”으로 제어해 보세요.

다음 글: #18 페이징과 정렬 실전(성능 함정 포함)

Spring Boot JPA 엔티티 설계 원칙(연관관계 포함) — 실무에서 덜 고생하는 기본기

IT Lab — Thu, 12 Mar 2026 20:00:45 +0900

Spring Boot 3.x 기준으로 JPA 엔티티를 설계할 때 꼭 지켜야 할 원칙(식별자 전략, 연관관계 방향, Lazy 기본, 엔티티 코드 규칙)을 예제 코드로 정리합니다.

도입 (문제 상황)

Spring Data JPA로 Repository는 금방 만들었는데, 엔티티 설계에서부터 막히는 경우가 많아요. 연관관계를 어디에 두어야 할지, LAZY로 두면 언제 터지고 EAGER로 두면 왜 느려지는지, 식별자는 어떤 전략이 안전한지 고민이 시작됩니다. 이 글에서는 “나중에 운영에서 덜 고생하는” 엔티티 설계 원칙을 기준으로 정리해 볼게요.

핵심 개념 (Spring Boot JPA 엔티티 설계 원칙)

1) 엔티티는 “DB 테이블”이 아니라 “도메인 모델”로 설계합니다

엔티티는 단순 DTO가 아니라 상태와 규칙을 가진 도메인 객체에 가까워요. 너무 많은 필드를 공개(setter 남발)하면, 변경 지점이 흩어져서 버그가 늘어납니다.
실무에서는 기본 생성자는 protected, 변경은 **의미 있는 메서드(예: changeAddress)**로 제한하는 방식이 유지보수에 유리합니다.

2) 식별자(@Id) 전략: 기본은 `IDENTITY`보다 `SEQUENCE`/`UUID`를 고민합니다

JPA 식별자는 “엔티티 동일성”의 기준이라서, 전략 선택이 성능/운영에 영향을 줍니다.

MySQL 계열: 보통 IDENTITY(auto_increment)를 많이 씁니다. 다만 IDENTITY는 INSERT 후에야 PK를 알 수 있어 배치 INSERT 최적화가 제한될 수 있습니다(하이버네이트가 한 번에 모아서 INSERT하기 어려움).
PostgreSQL/Oracle: SEQUENCE가 자연스럽고, JPA도 최적화 옵션(allocations)을 활용하기 좋습니다.
분산 환경/마이그레이션: 숫자 증가 PK 대신 UUID(또는 ULID 등)를 고려하면 충돌 위험을 줄일 수 있습니다. 대신 인덱스/정렬 비용이 늘 수 있어요.

아래 표처럼 “DB/요구사항”에 맞춰 선택하는 게 안전합니다.

전략	장점	단점/주의	추천 상황
`IDENTITY`	단순, MySQL에 익숙	배치 INSERT 최적화 제약, INSERT 전 id 없음	단순 CRUD, MySQL
`SEQUENCE`	성능/최적화 유리, INSERT 전 id 확보 가능	DB가 시퀀스를 지원해야 함	PostgreSQL/Oracle, 트래픽 많은 서비스
`UUID`	분산/병합에 강함	인덱스 비대, 정렬 비용	멀티 리전/데이터 병합/외부 노출 PK 회피

3) 연관관계 방향: “조회가 필요한 쪽”에 두되, 양방향은 최소화합니다

JPA 연관관계 주인과 mappedBy 개념 다이어그램

연관관계는 설계의 핵심인데, 요점은 이거예요.

단방향이 기본입니다. 필요할 때만 양방향을 씁니다.
양방향은 편해 보이지만, 관리 포인트가 늘어요(연관관계 편의 메서드, 무한 루프 직렬화, 예기치 않은 로딩 등).
“항상 함께 조회”가 아니라면, 컬렉션을 무작정 열어두지 않는 편이 안전합니다.

또 하나 중요한 사실: JPA에서 연관관계의 주인은 외래키를 가진 쪽(@ManyToOne) 입니다.
즉, Order -> Member는 Order가 주인이 되고, Member.orders는 보통 mappedBy로 읽기 전용에 가깝습니다.

flowchart LR
  A["Order(주인, FK 보유)"] -->|ManyToOne| B["Member"]
  B -->|OneToMany(mappedBy)| A

연관관계의 주인은 외래키를 가진 쪽이며, 반대편은 mappedBy로 매핑합니다.

4) Lazy 로딩은 기본값처럼 사용합니다(특히 ToOne/ToMany 모두)

JPA 기본값을 그대로 쓰면 위험한 지점이 있습니다.

@ManyToOne, @OneToOne의 기본 fetch는 EAGER 입니다. 그대로 두면 예상치 못한 조인/추가 쿼리로 성능이 흔들릴 수 있어요.
그래서 실무에서는 ToOne도 명시적으로 fetch = LAZY 를 붙이는 습관이 중요합니다.
@OneToMany/@ManyToMany는 기본이 LAZY지만, 컬렉션 접근 시점에 쿼리가 나가므로 서비스 계층에서 트랜잭션 범위를 의식해야 합니다.

다음 글(#17)에서 다룰 N+1 문제가 여기서 시작되는 경우가 많습니다.

5) equals/hashCode, toString, JSON 직렬화는 조심합니다

엔티티에 toString()을 자동 생성해 연관관계를 찍으면, LAZY 로딩이 터지거나 무한 루프가 날 수 있어요.
equals/hashCode를 연관관계/가변 필드 기반으로 만들면 Set/Map에서 동작이 이상해집니다.
실무에서는 식별자 기반(단, 영속화 전 null 고려) 또는 비즈니스 키(유일/불변) 기반으로 신중히 선택합니다.
API 응답은 엔티티를 그대로 내보내기보다 DTO로 변환하는 편이 안전합니다(직렬화 중 프록시 초기화 문제 예방).

코드 예제 (Spring Boot 3.x / Java 17, 연관관계 + Lazy + 식별자 전략)

아래 코드는 “주문(Order)–회원(Member)–주문상품(OrderItem)–상품(Product)” 모델로, 연관관계 방향과 LAZY 기본 원칙을 담은 실행 가능한 예제입니다.

build.gradle

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.3.2'
    id 'io.spring.dependency-management' version '1.1.6'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'

java {
    toolchain { languageVersion = JavaLanguageVersion.of(17) }
}

repositories { mavenCentral() }

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    runtimeOnly 'com.h2database:h2'

    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

tasks.named('test') { useJUnitPlatform() }

application.yml

spring:
  datasource:
    url: jdbc:h2:mem:testdb;MODE=PostgreSQL;DB_CLOSE_DELAY=-1
    driver-class-name: org.h2.Driver
    username: sa
    password:

  jpa:
    hibernate:
      ddl-auto: create
    properties:
      hibernate:
        format_sql: true
        highlight_sql: true
        use_sql_comments: true

logging:
  level:
    org.hibernate.SQL: debug
    org.hibernate.orm.jdbc.bind: trace

엔티티 코드

package com.example.demo.domain;

import jakarta.persistence.*;
import java.util.ArrayList;
import java.util.List;

@Entity
@Table(name = "members")
public class Member {

    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false)
    private String name;

    // 양방향은 필요할 때만: 여기서는 "회원의 주문 목록 조회"가 잦다고 가정
    @OneToMany(mappedBy = "member", orphanRemoval = true)
    private final List<Order> orders = new ArrayList<>();

    protected Member() {}

    public Member(String name) {
        this.name = name;
    }

    public Long getId() { return id; }
    public String getName() { return name; }

    // 연관관계 편의 메서드(양쪽 동기화)
    void addOrder(Order order) {
        orders.add(order);
    }
}

package com.example.demo.domain;

import jakarta.persistence.*;
import java.util.ArrayList;
import java.util.List;

@Entity
@Table(name = "orders")
public class Order {

    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    // ToOne은 기본이 EAGER이므로 반드시 LAZY 명시
    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(name = "member_id")
    private Member member;

    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
    private final List<OrderItem> orderItems = new ArrayList<>();

    protected Order() {}

    private Order(Member member) {
        this.member = member;
        member.addOrder(this);
    }

    public static Order create(Member member) {
        return new Order(member);
    }

    public Long getId() { return id; }
    public Member getMember() { return member; }
    public List<OrderItem> getOrderItems() { return orderItems; }

    public void addItem(Product product, int quantity) {
        OrderItem item = OrderItem.create(this, product, quantity);
        orderItems.add(item);
    }
}

package com.example.demo.domain;

import jakarta.persistence.*;

@Entity
@Table(name = "order_items")
public class OrderItem {

    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    // ToOne LAZY 명시
    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(name = "order_id")
    private Order order;

    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(name = "product_id")
    private Product product;

    @Column(nullable = false)
    private int quantity;

    protected OrderItem() {}

    private OrderItem(Order order, Product product, int quantity) {
        this.order = order;
        this.product = product;
        this.quantity = quantity;
    }

    public static OrderItem create(Order order, Product product, int quantity) {
        return new OrderItem(order, product, quantity);
    }

    public Long getId() { return id; }
}

package com.example.demo.domain;

import jakarta.persistence.*;

@Entity
@Table(name = "products")
public class Product {

    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false)
    private String name;

    protected Product() {}

    public Product(String name) {
        this.name = name;
    }

    public Long getId() { return id; }
    public String getName() { return name; }
}

Repository + 간단 실행(Controller)

package com.example.demo.repository;

import com.example.demo.domain.Member;
import org.springframework.data.jpa.repository.JpaRepository;

public interface MemberRepository extends JpaRepository<Member, Long> {}

package com.example.demo.repository;

import com.example.demo.domain.Product;
import org.springframework.data.jpa.repository.JpaRepository;

public interface ProductRepository extends JpaRepository<Product, Long> {}

package com.example.demo.repository;

import com.example.demo.domain.Order;
import org.springframework.data.jpa.repository.JpaRepository;

public interface OrderRepository extends JpaRepository<Order, Long> {}

package com.example.demo.web;

import com.example.demo.domain.Member;
import com.example.demo.domain.Order;
import com.example.demo.domain.Product;
import com.example.demo.repository.MemberRepository;
import com.example.demo.repository.OrderRepository;
import com.example.demo.repository.ProductRepository;
import org.springframework.transaction.annotation.Transactional;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/demo")
public class DemoController {

    private final MemberRepository memberRepository;
    private final ProductRepository productRepository;
    private final OrderRepository orderRepository;

    public DemoController(MemberRepository memberRepository,
                          ProductRepository productRepository,
                          OrderRepository orderRepository) {
        this.memberRepository = memberRepository;
        this.productRepository = productRepository;
        this.orderRepository = orderRepository;
    }

    @PostMapping("/seed")
    @Transactional
    public String seed() {
        Member member = memberRepository.save(new Member("kim"));
        Product p1 = productRepository.save(new Product("keyboard"));
        Product p2 = productRepository.save(new Product("mouse"));

        Order order = Order.create(member);
        order.addItem(p1, 1);
        order.addItem(p2, 2);

        orderRepository.save(order);
        return "ok";
    }

    @GetMapping("/orders/{id}")
    @Transactional(readOnly = true)
    public String read(@PathVariable Long id) {
        Order order = orderRepository.findById(id).orElseThrow();

        // LAZY 로딩은 접근 시점에 쿼리가 나갑니다(트랜잭션 안에서 안전)
        String memberName = order.getMember().getName();
        int itemCount = order.getOrderItems().size();

        return "orderId=" + order.getId() + ", member=" + memberName + ", items=" + itemCount;
    }
}

실무 팁

실무에서는: 엔티티의 기본 규칙을 “템플릿”으로 정해두면 편합니다

ToOne은 무조건 fetch = LAZY를 명시해 보세요(기본 EAGER 함정 회피).
기본 생성자는 protected, setter는 최소화, 생성/변경 메서드로 의도를 드러내면 유지보수 비용이 줄어듭니다.
API 응답은 엔티티 직접 반환 대신 DTO 변환을 기본 규칙으로 두는 편이 안전합니다(프록시/순환참조 방지).

실무에서는: 양방향 연관관계는 “읽기 모델”에서 특히 조심합니다

양방향을 늘리면 편의는 생기지만, N+1/직렬화/연관관계 동기화 같은 비용도 같이 따라옵니다.
“정말 필요한 화면/쿼리”가 생길 때 fetch join이나 EntityGraph로 해결하는 접근이 더 예측 가능합니다. (다음 글 #17에서 이어집니다)

핵심 요약: 엔티티는 도메인 모델로 설계하고 setter를 줄이세요.
핵심 요약: 연관관계는 단방향 + ToOne LAZY를 기본으로, 양방향은 최소화하세요.
핵심 요약: 식별자 전략은 DB/운영 요구에 맞춰 선택하고, 기본값의 함정을 의식하세요.

다음 글: [#17 N+1 문제 원인과 해결(fetch join/EntityGraph)]

Spring Boot에서 Spring Data JPA 시작하기: Repository 인터페이스(CrudRepository/JpaRepository)와 쿼리 메서드, 페이징 기본

IT Lab — Thu, 12 Mar 2026 10:00:42 +0900

Spring Boot 3.x에서 Spring Data JPA Repository 인터페이스를 선택하고(CrudRepository/JpaRepository), 쿼리 메서드와 Pageable로 페이징을 빠르게 적용하는 실전 시작 가이드입니다.

1) 도입 (문제 상황)

JPA로 CRUD를 만들려고 보면, “EntityManager로 직접 다 짜야 하나요?” 같은 고민이 먼저 생깁니다. 또 목록 API를 만들 때마다 페이징/정렬을 매번 수동으로 처리하다 보면 코드가 금방 지저분해져요. 이럴 때 Spring Data JPA의 Repository 인터페이스를 제대로 잡아두면 시작 속도가 확 달라집니다.

2) 핵심 개념 — Spring Data JPA Repository가 중요한 이유

Spring Data JPA의 핵심은 “반복되는 데이터 접근 코드를 인터페이스 선언만으로 표준화”하는 데 있어요. 구현체를 직접 만들지 않아도, 런타임에 프록시가 생성되어 CRUD, 페이징, 정렬, 쿼리 메서드(메서드 이름 기반 쿼리)까지 제공합니다.

CrudRepository vs JpaRepository, 무엇을 선택할까?

CrudRepository: 정말 최소 CRUD에 집중한 인터페이스입니다. 저장/조회/삭제 같은 기본 기능만 필요하면 충분합니다.
JpaRepository: CrudRepository를 포함하고, JPA에 특화된 기능(예: flush(), 배치 삭제, getReferenceById() 등)을 더 제공합니다. 실무에서는 대부분 JpaRepository를 기본으로 선택하는 편입니다.

아래 표처럼 “기능 범위” 관점으로 보면 선택이 쉬워요.

구분	CrudRepository	PagingAndSortingRepository	JpaRepository
기본 CRUD	O	O	O
페이징/정렬	X	O	O
JPA 특화 기능(flush 등)	X	X	O
실무 기본 선택	제한적	제한적	가장 흔함

쿼리 메서드(Query Method): “메서드 이름이 곧 쿼리”

findByEmail(...), findByStatusAndCreatedAtAfter(...)처럼 메서드 이름을 규칙에 맞게 만들면, Spring Data가 JPQL을 생성합니다.
비유하자면 “SQL을 직접 쓰기 전에, 규칙 기반 검색 UI(필터)를 먼저 제공받는 느낌”이에요. 빠르게 시작할 수 있고, 단순 조회는 코드가 매우 깔끔해집니다.

다만 이름이 너무 길어지거나 복잡한 조인이 필요해지면 유지보수가 어려워지니, 그때는 @Query(JPQL) 또는 Querydsl 같은 대안을 검토하는 흐름이 자연스럽습니다.

페이징 기본: Page vs Slice

Spring Data JPA Pageable로 페이징/정렬이 적용되는 흐름

페이징은 Pageable 하나로 정리됩니다.

Page: 전체 개수(count 쿼리)가 필요할 때 사용합니다. getTotalElements(), getTotalPages() 등을 제공합니다. (보통 count 쿼리가 추가로 나갑니다)
Slice: “다음 페이지가 있는지” 정도만 필요할 때 사용합니다. count 쿼리를 줄여 성능에 유리할 수 있어요.

요청 파라미터로 ?page=0&size=20&sort=createdAt,desc 같은 형태를 그대로 받을 수 있어서, 목록 API 표준화에 특히 좋습니다.

flowchart LR
  C["Client"] --> R["Controller: Pageable 파라미터 바인딩"]
  R --> S["Service: 비즈니스 규칙"]
  S --> J["Repository: JpaRepository"]
  J --> D["DB"]
  D --> J --> S --> R --> C

위 다이어그램은 Spring Data JPA에서 페이징 요청이 흘러가는 전형적인 경로를 보여줍니다.

3) 코드 예제 — 복붙해서 실행 가능한 Spring Boot 3.x + JPA Repository + 쿼리 메서드 + 페이징

아래 예제는 “회원 목록을 상태/이메일로 검색하고 페이징한다”는 가장 흔한 패턴입니다. H2 인메모리 DB로 바로 실행 가능하게 구성했습니다.

build.gradle

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.3.2'
    id 'io.spring.dependency-management' version '1.1.6'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'

    runtimeOnly 'com.h2database:h2'

    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

tasks.named('test') {
    useJUnitPlatform()
}

application.yml

spring:
  datasource:
    url: jdbc:h2:mem:testdb;MODE=PostgreSQL;DB_CLOSE_DELAY=-1
    driver-class-name: org.h2.Driver
    username: sa
    password:

  jpa:
    hibernate:
      ddl-auto: create
    properties:
      hibernate:
        format_sql: true

  h2:
    console:
      enabled: true

logging:
  level:
    org.hibernate.SQL: debug
    # 운영에서는 바인딩 로그가 민감할 수 있어요. 개발 환경에서만 제한적으로 사용하세요.
    org.hibernate.orm.jdbc.bind: trace

도메인(Entity)

package com.example.demo.member;

import jakarta.persistence.*;
import java.time.Instant;

@Entity
@Table(name = "members", indexes = {
        @Index(name = "idx_members_email", columnList = "email"),
        @Index(name = "idx_members_status_created", columnList = "status,createdAt")
})
public class Member {

    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true, length = 100)
    private String email;

    @Enumerated(EnumType.STRING)
    @Column(nullable = false, length = 20)
    private MemberStatus status = MemberStatus.ACTIVE;

    @Column(nullable = false, updatable = false)
    private Instant createdAt = Instant.now();

    protected Member() { }

    public Member(String email, MemberStatus status) {
        this.email = email;
        this.status = status;
    }

    public Long getId() { return id; }
    public String getEmail() { return email; }
    public MemberStatus getStatus() { return status; }
    public Instant getCreatedAt() { return createdAt; }
}

package com.example.demo.member;

public enum MemberStatus {
    ACTIVE, INACTIVE
}

Repository: JpaRepository + 쿼리 메서드 + 페이징

package com.example.demo.member;

import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.data.jpa.repository.JpaRepository;

public interface MemberRepository extends JpaRepository<Member, Long> {

    // 쿼리 메서드: 상태로 페이징 조회
    Page<Member> findByStatus(MemberStatus status, Pageable pageable);

    // 쿼리 메서드: 이메일 부분 검색 + 페이징
    Page<Member> findByEmailContainingIgnoreCase(String emailKeyword, Pageable pageable);

    // 조건 조합도 가능 (복잡해지면 @Query/Querydsl 고려)
    Page<Member> findByStatusAndEmailContainingIgnoreCase(MemberStatus status, String emailKeyword, Pageable pageable);
}

Service

package com.example.demo.member;

import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
public class MemberService {

    private final MemberRepository memberRepository;

    public MemberService(MemberRepository memberRepository) {
        this.memberRepository = memberRepository;
    }

    @Transactional(readOnly = true)
    public Page<Member> search(MemberStatus status, String q, Pageable pageable) {
        if (status != null && q != null && !q.isBlank()) {
            return memberRepository.findByStatusAndEmailContainingIgnoreCase(status, q.trim(), pageable);
        }
        if (status != null) {
            return memberRepository.findByStatus(status, pageable);
        }
        if (q != null && !q.isBlank()) {
            return memberRepository.findByEmailContainingIgnoreCase(q.trim(), pageable);
        }
        return memberRepository.findAll(pageable);
    }

    @Transactional
    public void seed() {
        if (memberRepository.count() > 0) return;

        memberRepository.save(new Member("alice@example.com", MemberStatus.ACTIVE));
        memberRepository.save(new Member("bob@example.com", MemberStatus.INACTIVE));
        memberRepository.save(new Member("carol@example.com", MemberStatus.ACTIVE));
        memberRepository.save(new Member("dave@example.com", MemberStatus.ACTIVE));
        memberRepository.save(new Member("erin@example.com", MemberStatus.INACTIVE));
    }
}

Controller: Pageable 자동 바인딩으로 페이징 API 만들기

package com.example.demo.member;

import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/members")
public class MemberController {

    private final MemberService memberService;

    public MemberController(MemberService memberService) {
        this.memberService = memberService;
    }

    // 예: /members?page=0&size=2&sort=createdAt,desc&status=ACTIVE&q=ex
    @GetMapping
    public Page<MemberResponse> list(
            @RequestParam(required = false) MemberStatus status,
            @RequestParam(required = false) String q,
            Pageable pageable
    ) {
        Page<Member> result = memberService.search(status, q, pageable);
        return result.map(MemberResponse::from);
    }
}

package com.example.demo.member;

import java.time.Instant;

public record MemberResponse(Long id, String email, MemberStatus status, Instant createdAt) {
    public static MemberResponse from(Member m) {
        return new MemberResponse(m.getId(), m.getEmail(), m.getStatus(), m.getCreatedAt());
    }
}

애플리케이션 시작 시 더미 데이터 넣기

package com.example.demo;

import com.example.demo.member.MemberService;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;

@SpringBootApplication
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }

    @Bean
    CommandLineRunner init(MemberService memberService) {
        return args -> memberService.seed();
    }
}

실행 후 아래처럼 호출해 보세요.

GET /members?page=0&size=2&sort=createdAt,desc
GET /members?status=ACTIVE&page=0&size=10
GET /members?q=example&page=0&size=10
GET /members?status=ACTIVE&q=ex&page=0&size=10&sort=email,asc

4) 실무 팁

실무에서는
쿼리 메서드는 “짧고 단순한 검색”까지만 쓰는 게 유지보수에 유리합니다.
findByStatusAndEmailContainingIgnoreCaseAndCreatedAtAfterAnd...처럼 길어지기 시작하면, 요구사항 변경 때 메서드 폭발이 생겨요. 이 시점부터는 @Query(JPQL)로 명시하거나, 동적 조건이 많다면 Querydsl을 검토해 보세요.

실무에서는
Page는 count 쿼리 비용을 꼭 의식해야 합니다. 목록 화면에서 “전체 페이지 수/총 건수”가 꼭 필요하지 않다면 Slice로 바꾸는 것만으로도 트래픽이 큰 서비스에서 DB 부담이 줄어듭니다. 특히 조인이 많은 조회는 count가 더 비쌀 수 있어요.

핵심 요약: JpaRepository는 CRUD+페이징+JPA 특화 기능까지 제공해 실무 기본 선택으로 적합합니다.
핵심 요약: 쿼리 메서드는 빠른 시작에 좋지만, 길어지면 @Query/Querydsl로 전환하는 기준을 잡아두세요.
핵심 요약: 페이징은 Pageable로 표준화하고, total count가 필요 없으면 Slice로 비용을 줄일 수 있습니다.

다음 글: [JPA 엔티티 설계 원칙(연관관계 포함)]

Spring Boot에서 @Transactional 제대로 쓰기(전파/읽기전용) — 프록시부터 실수까지

IT Lab — Wed, 11 Mar 2026 20:00:13 +0900

Spring Boot 3.x에서 @Transactional이 프록시로 동작하는 방식, readOnly의 실제 효과, 전파 옵션(Propagation) 선택 기준과 현업에서 자주 하는 실수를 코드로 정리합니다.

도입 (문제 상황)

서비스 메서드에 @Transactional을 붙였는데도 “왜 롤백이 안 되지?” 혹은 “readOnly로 했는데도 업데이트 쿼리가 나가네?” 같은 상황을 한 번쯤 겪으셨을 거예요. 특히 계층형 구조(Controller/Service/Repository)를 잘 나눠도, 트랜잭션 경계가 어긋나면 데이터 정합성이 쉽게 깨집니다.
이번 글에서는 @Transactional이 **어떻게 동작하는지(프록시)**부터 readOnly의 진짜 의미, 전파 옵션 선택, 자주 하는 실수를 실무 관점으로 정리해 봅니다.

핵심 개념: Spring Boot @Transactional이 “왜” 중요한가

@Transactional은 단순히 “DB 작업을 묶는 애노테이션”이 아니라, **데이터 변경의 원자성(Atomicity)**과 **일관성(Consistency)**을 지키는 경계선입니다. 이 경계가 애매하면 다음 문제가 자주 생깁니다.

일부만 커밋되고 일부는 실패(부분 성공) → 장애 대응이 매우 어려움
읽기 API가 의도치 않게 쓰기 락/플러시를 유발 → 성능 저하
트랜잭션이 중첩되면서 롤백 규칙이 꼬임 → “왜 롤백 안 됨?” 이슈

1) 프록시 기반 동작: “호출 경로”가 핵심입니다

Spring의 선언적 트랜잭션은 기본적으로 AOP 프록시로 구현됩니다. 즉, 빈을 감싼 프록시가 메서드 호출 전후로 트랜잭션을 시작/커밋/롤백합니다.

sequenceDiagram
  participant C as "Controller"
  participant P as "Service Proxy"
  participant S as "Service Target"
  participant TM as "Transaction Manager"
  participant R as "Repository"

  C->>P: "call service()"
  P->>TM: "begin"
  P->>S: "invoke"
  S->>R: "DB access"
  P->>TM: "commit/rollback"

Spring 트랜잭션 프록시가 요청을 가로채 트랜잭션을 시작/커밋하는 흐름

프록시가 “가로채서” 트랜잭션을 열고 닫는 흐름입니다.

여기서 중요한 포인트는 프록시를 거쳐야만 @Transactional이 적용된다는 점입니다. 그래서 아래가 대표적인 함정입니다.

같은 클래스 내부에서 this.someTxMethod()로 호출(= self-invocation)하면 프록시를 우회 → 트랜잭션이 안 걸릴 수 있음
private 메서드에 붙여도 보통 의미 없음(프록시가 가로채기 어려움)
Bean으로 관리되지 않는 객체에 붙여도 적용되지 않음

2) readOnly=true: “쓰기 금지”가 아니라 “쓰기 최적화 힌트”에 가깝습니다

@Transactional(readOnly = true)는 DB에 “절대 쓰지 마”를 강제하는 만능 스위치가 아닙니다. 보통 다음 효과를 기대할 수 있습니다.

(JPA/Hibernate) Flush 모드 조정 등으로 불필요한 변경 감지를 줄여 성능에 도움
DB 드라이버/DB 설정에 따라 read-only 트랜잭션 최적화가 적용될 수도 있음(항상 보장되진 않음)

하지만 다음은 오해입니다.

readOnly를 붙이면 UPDATE/INSERT가 무조건 막힌다 → 아닙니다. (환경/구현체에 따라 다르고, 애플리케이션 레벨에서 완전 차단을 보장하지 않습니다)
readOnly면 트랜잭션이 없는 것과 같다 → 아닙니다. 트랜잭션은 열립니다. (일관된 읽기, Lazy 로딩 등에서 의미가 큼)

정리하면 readOnly는 “안전장치”라기보다 “성능과 의도를 표현하는 설정”에 가깝습니다. 정말 쓰기를 막고 싶다면 DB 권한/분리(읽기 전용 계정, 리드 레플리카) 같은 운영 설계가 필요합니다.

3) 전파(Propagation): “이미 트랜잭션이 있을 때” 어떻게 할지 결정합니다

전파 옵션은 “현재 호출이 기존 트랜잭션 안에서 실행되는가?”를 다룹니다. 실무에서 자주 쓰는 옵션만 비교하면 다음과 같습니다.

전파 옵션	기존 트랜잭션이 있으면	없으면	주 사용처
REQUIRED(기본)	기존에 참여	새로 생성	대부분의 서비스 메서드
REQUIRES_NEW	기존을 잠시 중단하고 새로 생성	새로 생성	“로그는 반드시 남겨야 함” 같은 독립 커밋
SUPPORTS	있으면 참여	트랜잭션 없이 실행	읽기 API에서 선택적으로
MANDATORY	반드시 참여	예외 발생	“무조건 트랜잭션 안”을 강제할 때
NEVER	트랜잭션이 있으면 예외	트랜잭션 없이 실행	트랜잭션을 절대 열면 안 되는 작업(드묾)

특히 REQUIRES_NEW는 강력하지만 비용이 있습니다. 커넥션을 새로 확보하고(혹은 별도 트랜잭션을 열고) 기존 트랜잭션과 운명을 분리하므로, 남용하면 성능/데드락/일관성 측면에서 복잡해집니다.

4) 롤백 규칙: “어떤 예외에서 롤백되는가”

Spring의 기본 규칙은 다음입니다.

RuntimeException / Error → 롤백
Checked Exception → 커밋(기본)

Checked Exception에서도 롤백하려면 rollbackFor를 명시해야 합니다. 이 때문에 “예외는 났는데 커밋돼 버림” 이슈가 종종 발생합니다.

코드 예제: 전파/읽기전용/프록시 함정까지 한 번에 재현하기 (Spring Boot 3.x)

아래 예제는 H2 + Spring Data JPA로 구성했고, 실행 후 간단한 엔드포인트 호출로 다음을 확인할 수 있습니다.

readOnly=true에서 쓰기를 시도했을 때의 동작(환경에 따라 “막힘”이 보장되지 않음을 체감)
REQUIRES_NEW로 감사 로그를 “독립 커밋”하는 패턴
같은 클래스 내부 호출(self-invocation)로 @Transactional이 적용되지 않는 함정

build.gradle

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.3.2'
    id 'io.spring.dependency-management' version '1.1.6'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

repositories { mavenCentral() }

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    runtimeOnly 'com.h2database:h2'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

tasks.named('test') { useJUnitPlatform() }

application.yml

spring:
  datasource:
    url: jdbc:h2:mem:txdb;MODE=PostgreSQL;DB_CLOSE_DELAY=-1
    driver-class-name: org.h2.Driver
    username: sa
    password:
  jpa:
    hibernate:
      ddl-auto: create-drop
    properties:
      hibernate:
        format_sql: true
  h2:
    console:
      enabled: true

logging:
  level:
    org.hibernate.SQL: debug
    org.hibernate.orm.jdbc.bind: trace

도메인/리포지토리

package com.example.tx;

import jakarta.persistence.*;
import java.time.Instant;

@Entity
public class Member {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true)
    private String email;

    protected Member() {}

    public Member(String email) {
        this.email = email;
    }

    public Long getId() { return id; }
    public String getEmail() { return email; }
    public void changeEmail(String email) { this.email = email; }
}

@Entity
public class AuditLog {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false)
    private String message;

    @Column(nullable = false)
    private Instant createdAt = Instant.now();

    protected AuditLog() {}

    public AuditLog(String message) {
        this.message = message;
    }

    public Long getId() { return id; }
    public String getMessage() { return message; }
    public Instant getCreatedAt() { return createdAt; }
}

package com.example.tx;

import org.springframework.data.jpa.repository.JpaRepository;

import java.util.Optional;

public interface MemberRepository extends JpaRepository<Member, Long> {
    Optional<Member> findByEmail(String email);
}

public interface AuditLogRepository extends JpaRepository<AuditLog, Long> {
}

서비스: 전파/읽기전용/프록시 함정

REQUIRED와 REQUIRES_NEW 전파로 트랜잭션이 중단/분리되는 개념도

package com.example.tx;

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;

@Service
public class MemberService {

    private final MemberRepository memberRepository;
    private final AuditService auditService;

    public MemberService(MemberRepository memberRepository, AuditService auditService) {
        this.memberRepository = memberRepository;
        this.auditService = auditService;
    }

    // 기본 전파(REQUIRED): 대부분의 쓰기 로직은 이 패턴이 기본값입니다.
    @Transactional
    public Long register(String email) {
        Member saved = memberRepository.save(new Member(email));
        return saved.getId();
    }

    // readOnly는 "쓰기 금지"가 아니라 "읽기 최적화 힌트"에 가깝습니다.
    @Transactional(readOnly = true)
    public String findEmailAndTryToWrite(Long memberId, String newEmail) {
        Member m = memberRepository.findById(memberId)
                .orElseThrow(() -> new IllegalArgumentException("not found"));

        // 의도적으로 수정 시도: 환경에 따라 flush 시점에 예외가 나거나,
        // 또는 특정 설정에서는 UPDATE가 나갈 수도 있습니다(= readOnly가 강제 차단이 아님).
        m.changeEmail(newEmail);

        return m.getEmail();
    }

    // 전파 예시: 메인 로직은 실패해도 감사 로그는 남기고 싶은 경우
    @Transactional
    public void changeEmailWithAudit(Long memberId, String newEmail) {
        Member m = memberRepository.findById(memberId)
                .orElseThrow(() -> new IllegalArgumentException("not found"));

        m.changeEmail(newEmail);

        // 감사 로그는 독립 트랜잭션으로 커밋
        auditService.writeRequiresNew("email change requested: memberId=" + memberId);

        // 일부러 실패시켜 롤백 유도
        throw new RuntimeException("boom - main tx rollback");
    }

    // 프록시 함정: 같은 클래스 내부 호출은 프록시를 우회할 수 있습니다.
    public void outerCallsInnerDirectly(Long memberId, String newEmail) {
        // 아래 호출은 this.innerTransactional(...)과 동일한 경로가 될 수 있어
        // @Transactional이 기대대로 적용되지 않는 대표 케이스입니다.
        innerTransactional(memberId, newEmail);
    }

    @Transactional
    public void innerTransactional(Long memberId, String newEmail) {
        Member m = memberRepository.findById(memberId)
                .orElseThrow(() -> new IllegalArgumentException("not found"));
        m.changeEmail(newEmail);
    }
}

package com.example.tx;

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;

@Service
public class AuditService {

    private final AuditLogRepository auditLogRepository;

    public AuditService(AuditLogRepository auditLogRepository) {
        this.auditLogRepository = auditLogRepository;
    }

    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void writeRequiresNew(String message) {
        auditLogRepository.save(new AuditLog(message));
    }
}

컨트롤러: 호출용 엔드포인트

package com.example.tx;

import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/tx")
public class TxController {

    private final MemberService memberService;
    private final MemberRepository memberRepository;
    private final AuditLogRepository auditLogRepository;

    public TxController(MemberService memberService,
                        MemberRepository memberRepository,
                        AuditLogRepository auditLogRepository) {
        this.memberService = memberService;
        this.memberRepository = memberRepository;
        this.auditLogRepository = auditLogRepository;
    }

    @PostMapping("/members")
    public Long register(@RequestParam String email) {
        return memberService.register(email);
    }

    @PostMapping("/readonly-write")
    public String readOnlyWrite(@RequestParam Long memberId, @RequestParam String newEmail) {
        return memberService.findEmailAndTryToWrite(memberId, newEmail);
    }

    @PostMapping("/requires-new")
    public String requiresNew(@RequestParam Long memberId, @RequestParam String newEmail) {
        try {
            memberService.changeEmailWithAudit(memberId, newEmail);
            return "ok";
        } catch (Exception e) {
            long auditCount = auditLogRepository.count();
            String currentEmail = memberRepository.findById(memberId).map(Member::getEmail).orElse("n/a");
            return "main rolled back, auditCount=" + auditCount + ", emailNow=" + currentEmail;
        }
    }

    @PostMapping("/self-invocation")
    public String selfInvocation(@RequestParam Long memberId, @RequestParam String newEmail) {
        memberService.outerCallsInnerDirectly(memberId, newEmail);
        return "called";
    }
}

실행/확인 방법(간단)

회원 생성
POST /tx/members?email=a@a.com
REQUIRES_NEW 확인
POST /tx/requires-new?memberId=1&newEmail=b@b.com
→ 메인 변경은 롤백되어 이메일이 그대로일 수 있지만, 감사 로그는 auditCount=1처럼 남는 것을 확인할 수 있습니다.
self-invocation 함정은 로그/디버깅으로 확인해 보세요.
/tx/self-invocation 호출 시 innerTransactional이 프록시를 거치지 않으면 트랜잭션 경계가 기대와 달라질 수 있습니다. (이 케이스는 “왜 트랜잭션이 안 열렸지?”를 재현할 때 유용합니다.)

실무 팁

실무에서는
트랜잭션은 Service 계층에만 두는 규칙을 먼저 세우는 게 좋습니다. Controller에 @Transactional을 붙이면 웹 요청 범위 전체가 트랜잭션이 되어, 불필요하게 길어지고(외부 API 호출/파일 처리까지 포함), 락 경합이나 커넥션 고갈로 이어지기 쉽습니다. Repository에는 보통 붙이지 않아도 됩니다(호출자가 트랜잭션을 열어주는 구조가 더 예측 가능해요).

실무에서는
REQUIRES_NEW는 “감사 로그/알림 기록” 같은 독립 커밋이 반드시 필요한 곳에만 제한적으로 쓰는 게 안전합니다. 남용하면 트랜잭션이 쪼개져서 “메인 데이터는 롤백됐는데 부가 데이터는 남는” 상태가 늘어나고, 운영 중 정합성 이슈로 되돌아오는 경우가 많습니다. 정말 필요한지 먼저 질문해 보시고, 필요하다면 “왜 분리 커밋이 맞는가”를 코드 주석/문서로 남겨두는 편이 좋습니다.

핵심 요약

@Transactional은 프록시 기반이라 프록시를 거치는 호출 경로가 아니면 적용되지 않을 수 있습니다.
readOnly=true는 대개 최적화 힌트이며 “쓰기 완전 차단”을 보장하지 않습니다.
전파 옵션은 트랜잭션 중첩의 규칙이며, REQUIRES_NEW는 강력하지만 정합성/운영 비용을 동반합니다.

다음 글: #15 Spring Data JPA 시작(Repository 인터페이스)

Spring Boot 계층형 구조(Controller/Service/Repository) 잘 나누는 법 — 책임 분리와 DTO/엔티티 경계

IT Lab — Wed, 11 Mar 2026 10:00:46 +0900

Spring Boot 3에서 Controller/Service/Repository를 깔끔하게 분리하는 기준과 DTO/엔티티 경계, 서비스 레이어 규칙을 실무 관점에서 정리합니다.

도입 (문제 상황)

기능이 몇 개 없을 때는 Controller에서 Repository를 바로 호출해도 잘 돌아가지만, 요구사항이 늘어나면 “이 로직은 어디에 둬야 하지?”가 빠르게 문제가 됩니다. 특히 DTO와 엔티티를 섞어 쓰기 시작하면, 작은 변경에도 여러 계층이 같이 흔들리면서 유지보수가 어려워져요.

핵심 개념: Spring Boot 레이어드 아키텍처에서 “경계”를 지키는 기준

Controller/Service/Repository를 나누는 목적은 “코드를 예쁘게 분류”하는 게 아니라 변경의 파급 범위를 줄이는 것입니다. 각 계층이 책임을 넘지 않도록 경계를 세워두면, 요구사항이 커져도 구조가 무너지지 않습니다.

Spring Boot Controller 책임: HTTP를 도메인 호출로 번역하기

Controller는 웹 어댑터입니다. 아래 역할에 집중하면 됩니다.

요청을 DTO로 받기(@RequestBody, @ModelAttribute)
검증(Validation)과 인증/인가 결과를 바탕으로 서비스 호출
서비스 결과를 응답 DTO로 변환해 반환
HTTP 상태 코드/헤더/에러 응답 형태 결정

반대로, Controller가 하면 곤란한 일은 다음과 같습니다.

트랜잭션 경계 관리(대부분 Service에서)
비즈니스 규칙(“재고가 0이면 주문 불가” 같은 규칙)
JPA 엔티티를 그대로 응답으로 내보내기(지연 로딩, 순환 참조, 내부 필드 노출 위험)

Spring Boot Service 책임: 유스케이스(업무 흐름)와 규칙의 집합

Service는 “무엇을 할지”를 표현하는 계층입니다. 흔히 유스케이스 단위로 메서드가 생기고, 내부에서 여러 Repository/외부 연동을 조합합니다.

비즈니스 규칙과 흐름(유스케이스) 구현
트랜잭션 경계 설정(@Transactional)
도메인 모델(엔티티) 조작 및 상태 변경
외부 시스템 호출이 있다면 실패/재시도/보상 같은 정책을 한 곳에 모으기

Service 레이어 규칙을 한 문장으로 정리하면 이렇습니다.
“Controller는 얇게, Service는 규칙을 갖고, Repository는 저장만 한다.”

Spring Boot Repository 책임: 저장소 접근을 캡슐화하기

Repository는 데이터 접근을 숨기는 레이어입니다.

엔티티 단위 CRUD, 조회 쿼리 제공
쿼리 최적화(fetch join, projection 등) 책임
비즈니스 규칙을 넣지 않기(“삭제 가능 여부 판단” 같은 로직은 Service로)

DTO/엔티티 경계: “택배 상자(DTO)”와 “실제 상품(엔티티)”를 섞지 않기

DTO는 계층 사이를 오가는 “운반용 상자”이고, 엔티티는 “실제 도메인 상태”입니다. 상자(DTO)를 그대로 창고(Repository/JPA)에 넣거나, 상품(엔티티)을 그대로 고객(HTTP 응답)에 보내면 문제가 생깁니다.

엔티티를 API 응답으로 직접 노출하면
- 내부 필드가 새는 보안 이슈
- LAZY 로딩으로 N+1/예외가 발생
- 양방향 연관관계로 JSON 무한 루프
반대로 요청 DTO를 엔티티처럼 여기면
- 검증/정규화/규칙 적용이 누락되기 쉽고
- “API 스펙 변경”이 “도메인 변경”으로 전염됩니다

한눈에 비교: 계층별 책임과 금지사항

계층	주 책임	주로 다루는 타입	하면 안 되는 것(대표)
Controller	HTTP ↔ 유스케이스 연결	Request/Response DTO	비즈니스 규칙, 엔티티 직접 반환
Service	유스케이스/규칙/트랜잭션	엔티티, 도메인 값 객체	HTTP 세부사항(상태코드 등), DB 쿼리 최적화 세부
Repository	데이터 접근/쿼리	엔티티, Projection	비즈니스 규칙, DTO 중심 설계(무분별한 DTO 저장)

코드 예제: 회원 가입/조회로 보는 Controller-Service-Repository 분리 (Spring Boot 3.x)

아래 예제는 “회원 가입”과 “회원 단건 조회”를 통해 DTO/엔티티 경계와 서비스 규칙을 보여줍니다. 그대로 복붙해서 실행할 수 있게 H2 기준으로 구성했습니다.

// build.gradle (Gradle Groovy)
plugins {
    id 'java'
    id 'org.springframework.boot' version '3.3.2'
    id 'io.spring.dependency-management' version '1.1.6'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'

java {
    toolchain { languageVersion = JavaLanguageVersion.of(17) }
}

repositories { mavenCentral() }

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-validation'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'

    runtimeOnly 'com.h2database:h2'

    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

tasks.named('test') { useJUnitPlatform() }

# application.yml
spring:
  datasource:
    url: jdbc:h2:mem:testdb;MODE=PostgreSQL;DB_CLOSE_DELAY=-1
    driver-class-name: org.h2.Driver
    username: sa
    password:
  jpa:
    hibernate:
      ddl-auto: create
    properties:
      hibernate:
        format_sql: true
  h2:
    console:
      enabled: true

logging:
  level:
    org.hibernate.SQL: debug

1) 엔티티: 도메인 상태와 규칙은 엔티티/서비스에서 관리

package com.example.demo.member;

import jakarta.persistence.*;

@Entity
@Table(name = "members", uniqueConstraints = {
        @UniqueConstraint(name = "uk_member_email", columnNames = "email")
})
public class Member {

    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, length = 100)
    private String email;

    @Column(nullable = false, length = 30)
    private String name;

    protected Member() { }

    private Member(String email, String name) {
        this.email = email;
        this.name = name;
    }

    public static Member create(String email, String name) {
        // 엔티티는 "상태를 가진 객체"이므로 생성 시점 불변조건을 지키는 데 유리합니다.
        return new Member(email, name);
    }

    public Long getId() { return id; }
    public String getEmail() { return email; }
    public String getName() { return name; }
}

2) DTO: API 스펙은 DTO가 책임지고, 엔티티와 분리

package com.example.demo.member.api;

import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;

public class MemberDtos {

    public record CreateRequest(
            @NotBlank @Email String email,
            @NotBlank @Size(max = 30) String name
    ) {}

    public record CreateResponse(Long id) {}

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

3) Repository: 저장/조회만 담당

package com.example.demo.member;

import org.springframework.data.jpa.repository.JpaRepository;

import java.util.Optional;

public interface MemberRepository extends JpaRepository<Member, Long> {
    Optional<Member> findByEmail(String email);
    boolean existsByEmail(String email);
}

4) Service: 유스케이스 + 규칙 + 트랜잭션 경계

package com.example.demo.member;

import com.example.demo.member.api.MemberDtos;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
public class MemberService {

    private final MemberRepository memberRepository;

    public MemberService(MemberRepository memberRepository) {
        this.memberRepository = memberRepository;
    }

    @Transactional
    public MemberDtos.CreateResponse signUp(MemberDtos.CreateRequest req) {
        // 비즈니스 규칙: 이메일은 유일해야 한다
        if (memberRepository.existsByEmail(req.email())) {
            throw new IllegalArgumentException("이미 사용 중인 이메일입니다.");
        }

        Member saved = memberRepository.save(Member.create(req.email(), req.name()));
        return new MemberDtos.CreateResponse(saved.getId());
    }

    @Transactional(readOnly = true)
    public MemberDtos.DetailResponse getMember(Long id) {
        Member member = memberRepository.findById(id)
                .orElseThrow(() -> new IllegalArgumentException("회원을 찾을 수 없습니다. id=" + id));

        // 엔티티를 직접 반환하지 않고 응답 DTO로 변환
        return new MemberDtos.DetailResponse(member.getId(), member.getEmail(), member.getName());
    }
}

5) Controller: HTTP 처리 + DTO 바인딩/검증 + 서비스 호출

package com.example.demo.member.api;

import com.example.demo.member.MemberService;
import jakarta.validation.Valid;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.net.URI;

@RestController
@RequestMapping("/api/members")
public class MemberController {

    private final MemberService memberService;

    public MemberController(MemberService memberService) {
        this.memberService = memberService;
    }

    @PostMapping
    public ResponseEntity<MemberDtos.CreateResponse> signUp(@Valid @RequestBody MemberDtos.CreateRequest req) {
        MemberDtos.CreateResponse res = memberService.signUp(req);
        return ResponseEntity
                .created(URI.create("/api/members/" + res.id()))
                .body(res);
    }

    @GetMapping("/{id}")
    public ResponseEntity<MemberDtos.DetailResponse> getMember(@PathVariable Long id) {
        return ResponseEntity.ok(memberService.getMember(id));
    }
}

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

요청 흐름 다이어그램(Controller/Service/Repository)

sequenceDiagram
  participant C as "Controller"
  participant S as "Service"
  participant R as "Repository"
  participant DB as "Database"

  C->>S: "DTO로 요청 전달"
  S->>R: "엔티티 조회/저장 요청"
  R->>DB: "SQL 실행"
  DB-->>R: "결과 반환"
  R-->>S: "엔티티 반환"
  S-->>C: "응답 DTO 반환"
  C-->>C: "HTTP 응답 생성"

Controller는 HTTP를 처리하고, Service는 규칙/흐름을, Repository는 DB 접근을 담당한다는 흐름을 보여줍니다.

[IMAGE_PROMPT] 위치: "요청 흐름 다이어그램" 바로 아래 alt: Controller-Service-Repository 책임 분리 개념도 prompt: clean minimal tech blog style white background layered architecture diagram showing Controller Service Repository Database with arrows, emphasize responsibilities separation, no dense text style: diagram [/IMAGE_PROMPT]

실무 팁

실무에서는: “Service가 비대해질 때” 유스케이스 단위로 쪼개 보세요

MemberService에 모든 회원 관련 기능을 넣기 시작하면 금방 1,000줄이 됩니다. 이때는 MemberSignUpService, MemberQueryService처럼 유스케이스/관심사 기준으로 분리하면 테스트도 쉬워지고 충돌도 줄어듭니다.
단, 너무 잘게 쪼개서 “서비스가 서비스 호출” 형태로 꼬이면 오히려 추적이 어려워질 수 있으니, 팀의 복잡도에 맞는 적정 분리가 중요합니다.

DTO와 Entity 경계(택배 상자와 상품) 비유 일러스트

실무에서는: DTO↔엔티티 매핑 위치를 팀 규칙으로 고정해 두는 게 효과가 큽니다

권장: Controller는 요청 DTO를 그대로 Service로 전달, Service에서 엔티티 생성/변환을 담당(유스케이스 규칙과 함께 관리).
조회 성능이 중요할 때는 Repository에서 Projection으로 DTO를 바로 조회하는 전략도 가능하지만, 이 경우 “읽기 모델”로 명확히 구분해 두지 않으면 계층 경계가 흐려지기 쉽습니다(예: MemberQueryRepository/MemberReadModel 같은 네이밍).

핵심 요약: Controller는 HTTP에 집중하고, Service는 유스케이스/규칙/트랜잭션을 책임지며, Repository는 저장소 접근만 담당합니다.
핵심 요약: DTO와 엔티티 경계를 지키면 API 변경이 도메인/DB까지 번지는 일을 줄일 수 있습니다.
핵심 요약: 서비스가 커지면 “도메인 기준”이 아니라 “유스케이스 기준”으로 분리해 보세요.

다음 글: #14 @Transactional 제대로 쓰기(전파/읽기전용)

Spring Boot 검증(Validation)과 에러 응답 표준화: @Valid부터 @ControllerAdvice까지

IT Lab — Tue, 10 Mar 2026 20:00:02 +0900

Spring Boot 3에서 @Valid, BindingResult, @ControllerAdvice로 입력 검증을 적용하고, 공통 에러 응답 포맷을 설계해 일관된 API를 만드는 방법을 정리합니다.

도입 (문제 상황)

API를 만들다 보면 “필수값이 빠졌는데 500이 떨어져요”, “어떤 API는 errors 배열이고 어떤 API는 message 하나예요” 같은 상황을 자주 만나게 됩니다. 검증은 넣었는데 응답 포맷이 제각각이라 프런트/모바일에서 예외 처리가 더 어려워지기도 해요. 이 글에서는 Spring Boot 3 기준으로 검증과 에러 응답을 한 번에 정리해 보겠습니다.

핵심 개념: Spring Boot Validation이 중요한 이유와 표준화 포인트

검증(Validation)은 단순히 “값이 비었는지”를 확인하는 기능이 아니라, 계약(Contract) 을 지키게 만드는 장치입니다. 클라이언트가 잘못된 요청을 보내면 서버는 예측 가능한 방식으로 거절해야 하고(보통 400), 그 거절 응답은 모든 API에서 일관돼야 합니다.

1) @Valid / @Validated: “검증 트리거”를 어디에 거는가

@Valid는 주로 요청 DTO(@RequestBody, @ModelAttribute) 에 붙여 검증을 트리거합니다.
컨트롤러 메서드 파라미터에 @Valid를 붙이면, Spring이 바인딩 후 Bean Validation(Jakarta Validation)을 실행합니다.
그룹 검증이 필요하면 @Validated를 고려하지만, 일반적인 CRUD에서는 @Valid만으로 충분한 경우가 많습니다.

2) BindingResult: 예외를 던질지, 컨트롤러에서 처리할지

@Valid 대상 바로 뒤에 BindingResult(또는 Errors)를 두면 검증 실패 시 예외를 던지지 않고 컨트롤러로 흐름이 들어옵니다.
반대로 BindingResult가 없으면 검증 실패 시 보통 MethodArgumentNotValidException(JSON 바디) 또는 BindException(쿼리/폼)이 발생하고, 이를 전역 예외 처리로 표준화하기 좋습니다.

실무에서는 “모든 검증 실패는 전역에서 같은 포맷으로 응답”이 목표라면, 컨트롤러에서 BindingResult로 분기하지 않고 예외 기반으로 통일하는 편이 유지보수에 유리한 경우가 많습니다(특정 화면에서만 커스텀 처리 필요할 때만 BindingResult를 씁니다).

3) @ControllerAdvice: 에러 응답의 ‘관문’을 하나로 모으기

@ControllerAdvice + @ExceptionHandler는 컨트롤러 전반에서 발생하는 예외를 한 곳에서 잡아 HTTP 상태 코드, 에러 코드, 메시지, 필드 오류 목록을 표준화합니다.

특히 검증 실패는 “필드별로 무엇이 왜 틀렸는지”가 중요합니다. 메시지 하나로 뭉개면 디버깅도 어렵고 UX도 나빠져요. 그래서 보통 다음처럼 나눕니다.

top-level: timestamp, path, errorCode, message
details: fieldErrors[{field, rejectedValue, reason}] 또는 violations

4) 공통 에러 포맷 설계: “프런트가 분기하지 않게”

아래 항목은 에러 포맷을 설계할 때 자주 쓰는 체크리스트입니다.

항목	권장 이유	예시
errorCode	화면/클라이언트가 안정적으로 분기	`VALIDATION_FAILED`, `RESOURCE_NOT_FOUND`
message	사람에게 보여줄 요약	`"요청 값이 올바르지 않습니다."`
fieldErrors	폼/필드 하이라이트에 필요	`[{ "field":"email", "reason":"must be a well-formed email address" }]`
path	어떤 API에서 났는지 추적	`"/api/users"`
traceId(선택)	로그 상관관계	`"a1b2c3..."`

에러 포맷은 “예쁘게”보다 “안정적으로”가 핵심입니다. 버전이 바뀌어도 errorCode와 fieldErrors 구조가 유지되면 클라이언트는 덜 고생합니다.

flowchart TD
  A["Client request"] --> B["Spring MVC binding"]
  B --> C{"Validation pass?"}
  C -- "Yes" --> D["Controller logic"]
  C -- "No" --> E["Exception (MethodArgumentNotValidException)"]
  E --> F["@ControllerAdvice handler"]
  F --> G["Standard error response (400)"]

Spring Boot Validation error handling flow illustration

검증 실패는 예외로 모아 @ControllerAdvice에서 공통 포맷으로 응답하는 흐름입니다.

코드 예제: @Valid + @ControllerAdvice로 공통 에러 응답 만들기 (복붙 실행)

아래 예제는 Spring Boot 3.x(Java 17)에서 바로 실행 가능한 최소 구성입니다.

build.gradle

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.3.2'
    id 'io.spring.dependency-management' version '1.1.6'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-validation' // Jakarta Validation
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

tasks.named('test') {
    useJUnitPlatform()
}

application.yml (선택)

server:
  port: 8080
spring:
  jackson:
    serialization:
      write-dates-as-timestamps: false

예제 API: 회원 가입 요청 DTO + 컨트롤러

package com.example.demo.user;

import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;

public record CreateUserRequest(
        @NotBlank(message = "이메일은 필수입니다.")
        @Email(message = "이메일 형식이 올바르지 않습니다.")
        String email,

        @NotBlank(message = "비밀번호는 필수입니다.")
        @Size(min = 8, message = "비밀번호는 8자 이상이어야 합니다.")
        String password,

        @NotBlank(message = "이름은 필수입니다.")
        @Size(max = 20, message = "이름은 20자 이하여야 합니다.")
        String name
) {}

package com.example.demo.user;

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

package com.example.demo.user;

import jakarta.validation.Valid;
import org.springframework.web.bind.annotation.*;

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

    @PostMapping
    public CreateUserResponse create(@RequestBody @Valid CreateUserRequest request) {
        // 예제이므로 저장 로직은 생략하고 고정 응답
        return new CreateUserResponse(1L, request.email(), request.name());
    }
}

공통 에러 응답 포맷 + 전역 예외 처리(@ControllerAdvice)

package com.example.demo.error;

import com.fasterxml.jackson.annotation.JsonInclude;

import java.time.Instant;
import java.util.List;

@JsonInclude(JsonInclude.Include.NON_NULL)
public record ApiErrorResponse(
        Instant timestamp,
        int status,
        String errorCode,
        String message,
        String path,
        List<FieldErrorItem> fieldErrors
) {
    public record FieldErrorItem(
            String field,
            Object rejectedValue,
            String reason
    ) {}
}

package com.example.demo.error;

import jakarta.servlet.http.HttpServletRequest;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.FieldError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

import java.time.Instant;
import java.util.List;

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ApiErrorResponse> handleValidation(
            MethodArgumentNotValidException ex,
            HttpServletRequest request
    ) {
        List<ApiErrorResponse.FieldErrorItem> fieldErrors = ex.getBindingResult()
                .getFieldErrors()
                .stream()
                .map(this::toFieldErrorItem)
                .toList();

        ApiErrorResponse body = new ApiErrorResponse(
                Instant.now(),
                HttpStatus.BAD_REQUEST.value(),
                "VALIDATION_FAILED",
                "요청 값이 올바르지 않습니다.",
                request.getRequestURI(),
                fieldErrors
        );

        return ResponseEntity.badRequest().body(body);
    }

    private ApiErrorResponse.FieldErrorItem toFieldErrorItem(FieldError fe) {
        Object rejected = fe.getRejectedValue();
        return new ApiErrorResponse.FieldErrorItem(
                fe.getField(),
                rejected,
                fe.getDefaultMessage()
        );
    }
}

실행 & 테스트

정상 요청:

curl -X POST http://localhost:8080/api/users \
  -H 'Content-Type: application/json' \
  -d '{"email":"dev@example.com","password":"password123","name":"kim"}'

검증 실패 요청(비밀번호 짧음, 이메일 형식 오류):

curl -X POST http://localhost:8080/api/users \
  -H 'Content-Type: application/json' \
  -d '{"email":"not-email","password":"123","name":""}'

예상 응답(예시):

{
  "timestamp": "2026-03-09T10:12:30.123Z",
  "status": 400,
  "errorCode": "VALIDATION_FAILED",
  "message": "요청 값이 올바르지 않습니다.",
  "path": "/api/users",
  "fieldErrors": [
    { "field": "email", "rejectedValue": "not-email", "reason": "이메일 형식이 올바르지 않습니다." },
    { "field": "password", "rejectedValue": "123", "reason": "비밀번호는 8자 이상이어야 합니다." },
    { "field": "name", "rejectedValue": "", "reason": "이름은 필수입니다." }
  ]
}

실무 팁

실무에서는
BindingResult를 남발하면 에러 포맷이 퍼집니다. 화면별로 “이 컨트롤러만 다른 에러 형태”가 생기기 쉬워요. 특별한 이유가 없다면 검증 실패는 예외로 통일하고, @ControllerAdvice에서 한 번에 포맷을 맞추는 쪽이 운영 비용이 낮습니다.

실무에서는
에러 메시지(localization)와 에러 코드(errorCode)를 분리해 두는 게 안전합니다. 사용자에게 보여줄 문구는 바뀔 수 있지만, 클라이언트 분기 기준인 errorCode는 최대한 고정해야 합니다. 메시지는 i18n(메시지 소스)로 관리하고, errorCode는 enum/상수로 관리해 보세요.

핵심 요약

@Valid로 검증을 트리거하고, 검증 실패는 전역 예외 처리로 모아 표준화하는 게 유지보수에 유리합니다.
@ControllerAdvice에서 MethodArgumentNotValidException을 잡아 fieldErrors 기반의 공통 포맷을 만드세요.
에러 응답은 errorCode(기계용)와 message(사람용)를 분리하면 변경에 강해집니다.

다음 글: [계층형 구조(Controller/Service/Repository) 잘 나누는 법]

Spring Boot 요청/응답 바인딩(@RequestBody, @ModelAttribute) 실전 가이드

IT Lab — Tue, 10 Mar 2026 10:00:25 +0900

Spring Boot 3에서 폼/쿼리/JSON 바인딩 차이와 Jackson 설정 포인트, null 처리 전략을 실전 코드로 정리합니다.

도입 (문제 상황)

API를 만들다 보면 “같은 DTO인데 왜 어떤 요청은 바인딩이 되고, 어떤 요청은 400이 나지?” 같은 상황을 자주 만나게 됩니다. 특히 폼 전송/쿼리스트링은 잘 되는데 JSON은 갑자기 실패하거나, null 처리 때문에 업데이트 API가 의도치 않게 값을 지워버리는 일도 생깁니다. 이번 글에서는 Spring Boot에서 요청/응답 바인딩을 실전 관점으로 정리해 봅니다.

핵심 개념: Spring Boot 바인딩이 갈리는 지점 (@RequestBody vs @ModelAttribute)

RequestBody와 ModelAttribute 바인딩 흐름 비교 다이어그램

Spring MVC에서 바인딩은 크게 두 갈래로 나뉩니다.

@ModelAttribute 계열: 요청 파라미터(query string), 폼 데이터(application/x-www-form-urlencoded, multipart/form-data)를 이름 기준으로 객체 필드에 채웁니다. 내부적으로 WebDataBinder가 동작합니다.
@RequestBody 계열: 요청 본문(body)을 메시지 컨버터(HttpMessageConverter) 로 읽습니다. JSON이면 보통 Jackson(MappingJackson2HttpMessageConverter)이 DTO로 역직렬화합니다.

이 차이가 중요한 이유는 다음과 같습니다.

실패 지점이 다릅니다.

@ModelAttribute: 타입 변환 실패(예: "abc" → int)는 바인딩 에러로 쌓이고, 컨트롤러 진입 후 BindingResult/예외 처리로 이어집니다.
@RequestBody: JSON 파싱/역직렬화 단계에서 실패하면 컨트롤러 진입 전에 400(Bad Request)로 떨어지기 쉽습니다.

null의 의미가 달라집니다.

@ModelAttribute는 “파라미터가 아예 없으면” 보통 해당 필드는 null(또는 primitive면 기본값)로 남습니다.
@RequestBody는 “필드가 JSON에 없으면 null”, “필드가 있고 null이면 null”인데, 이 둘을 구분해야 PATCH/부분 업데이트에서 안전합니다.

Jackson 설정이 API의 계약을 바꿉니다.
예를 들어 응답에서 null 필드를 숨길지(NON_NULL), 날짜 포맷을 통일할지, unknown field를 허용할지 같은 설정은 클라이언트와의 호환성에 직접 영향을 줍니다.

한눈에 비교: 폼/쿼리 vs JSON 바인딩

구분	주 사용 어노테이션	입력 형태	동작 메커니즘	자주 나는 이슈
쿼리스트링/폼	`@ModelAttribute` (또는 생략)	`?name=...` / `x-www-form-urlencoded`	DataBinder 기반 필드 매핑	타입 변환 오류, 파라미터 누락 시 기본값 문제
멀티파트 폼	`@ModelAttribute` + `MultipartFile`	`multipart/form-data`	DataBinder + MultipartResolver	파일/필드 혼합 시 DTO 설계 난이도
JSON 본문	`@RequestBody`	`application/json`	HttpMessageConverter(Jackson)	JSON 파싱 오류, unknown field, null 처리/부분 업데이트

코드 예제: 폼/쿼리/JSON 바인딩 + Jackson 설정 + null 처리 전략

아래 예제는 그대로 복사해서 실행할 수 있는 Spring Boot 3.x 프로젝트입니다.
(패키지명은 편하신 대로 바꾸셔도 됩니다.)

build.gradle

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.3.2'
    id 'io.spring.dependency-management' version '1.1.6'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

tasks.named('test') {
    useJUnitPlatform()
}

application.yml (Jackson 핵심 설정 포인트)

spring:
  jackson:
    # 응답에서 null 필드를 숨기고 싶을 때 (API 응답을 더 깔끔하게)
    default-property-inclusion: non_null

    # 알 수 없는 필드가 들어오면 실패시키는 옵션
    # 운영에서는 "엄격 모드"가 계약 위반을 빨리 잡아줘서 유리한 경우가 많습니다.
    deserialization:
      fail-on-unknown-properties: true

    # 날짜/시간 직렬화 기본 동작(ISO-8601) 유지
    serialization:
      write-dates-as-timestamps: false

요청 바인딩 데모 컨트롤러

package com.example.binding;

import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonSetter;
import com.fasterxml.jackson.annotation.Nulls;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;

import java.util.Optional;

@RestController
@RequestMapping("/api")
public class BindingController {

    // 1) 쿼리스트링/폼 바인딩: @ModelAttribute
    // 예: GET /api/search?keyword=spring&page=1
    @GetMapping("/search")
    public SearchRequest search(@ModelAttribute SearchRequest request) {
        return request;
    }

    // 예: POST /api/form (Content-Type: application/x-www-form-urlencoded)
    // body: name=kim&age=20
    @PostMapping(path = "/form", consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)
    public UserFormRequest form(UserFormRequest request) { // @ModelAttribute 생략 가능
        return request;
    }

    // 2) JSON 바인딩: @RequestBody
    // 예: POST /api/users (Content-Type: application/json)
    @PostMapping("/users")
    public CreateUserRequest create(@RequestBody CreateUserRequest request) {
        return request;
    }

    // 3) 멀티파트: DTO + 파일을 섞을 때는 @ModelAttribute가 자연스럽습니다.
    @PostMapping(path = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public UploadRequest upload(@ModelAttribute UploadRequest request) {
        // 파일은 request.file()로 접근
        return request;
    }

    // 4) 부분 업데이트(PATCH)에서 null 처리 전략 예시
    // - "필드가 아예 없다" = 변경하지 않음
    // - "필드가 null이다" = 정책에 따라 (허용 시) null로 변경
    @PatchMapping("/users/{id}")
    public String patch(@PathVariable long id, @RequestBody UpdateUserRequest request) {
        // 실무에서는 여기서 서비스 레이어로 내려가 병합(merge) 로직을 수행합니다.
        // 예시에서는 의미만 보여주기 위해 문자열로 반환합니다.
        return "id=" + id +
                ", name=" + request.name().map(v -> "SET(" + v + ")").orElse("NO_CHANGE") +
                ", nickname=" + request.nickname().map(v -> "SET(" + v + ")").orElse("NO_CHANGE");
    }

    // ===== DTOs =====

    public record SearchRequest(
            String keyword,
            Integer page
    ) {}

    public record UserFormRequest(
            String name,
            Integer age
    ) {}

    public record CreateUserRequest(
            String email,
            String name
    ) {}

    public record UploadRequest(
            String title,
            MultipartFile file
    ) {}

    /**
     * PATCH용 DTO에서 "필드 부재"와 "null"을 구분하고 싶을 때 Optional을 활용하는 패턴입니다.
     * - JSON에 필드가 없으면 Optional.empty()
     * - JSON에 필드가 있고 값이 있으면 Optional.of(value)
     * - JSON에 필드가 있고 null이면: 아래 @JsonSetter로 Optional.empty()로 들어오게(=정책) 만들 수 있습니다.
     *
     * 주의: "null을 명시적으로 보내서 값을 지우는 기능"이 필요하면 이 정책을 바꾸거나 별도 표현이 필요합니다.
     */
    public record UpdateUserRequest(
            @JsonSetter(nulls = Nulls.AS_EMPTY)
            Optional<String> name,

            @JsonSetter(nulls = Nulls.AS_EMPTY)
            Optional<String> nickname
    ) {}
}

실행/테스트용 요청 예시

쿼리 바인딩

curl "http://localhost:8080/api/search?keyword=spring&page=1"

폼 바인딩

curl -X POST "http://localhost:8080/api/form" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "name=kim&age=20"

JSON 바인딩

curl -X POST "http://localhost:8080/api/users" \
  -H "Content-Type: application/json" \
  -d '{"email":"a@b.com","name":"kim"}'

PATCH에서 “필드 없음” vs “null” 확인

# name만 변경
curl -X PATCH "http://localhost:8080/api/users/1" \
  -H "Content-Type: application/json" \
  -d '{"name":"new-name"}'

# name을 null로 보냄 (현재 예제 정책에서는 Optional.empty() 처리 = NO_CHANGE로 간주)
curl -X PATCH "http://localhost:8080/api/users/1" \
  -H "Content-Type: application/json" \
  -d '{"name":null}'

flowchart TD
  A["HTTP Request"] --> B["HandlerMapping"]
  B --> C["HandlerAdapter"]
  C --> D{"Binding Type"}
  D -->| "@ModelAttribute" | E["WebDataBinder\n(query/form -> object)"]
  D -->| "@RequestBody" | F["HttpMessageConverter\n(Jackson JSON -> object)"]
  E --> G["Controller Method"]
  F --> G["Controller Method"]
  G --> H["Response (Jackson serialize)"]

요청 데이터가 어디에서 어떻게 객체로 변환되는지(바인딩 지점)를 보여주는 흐름도입니다.

실무 팁

실무에서는: PATCH/부분 업데이트에서 null 정책을 먼저 문서로 고정해 두세요

“필드 미포함 = 변경 없음”은 대부분의 API가 기대하는 동작입니다.
“null 전송 = 값 삭제”를 허용할지 여부는 민감합니다(특히 개인정보/필수값). 허용한다면 별도 엔드포인트(예: /nickname:clear) 나 명시적 연산 모델(JSON Patch) 을 고려해 보세요.
Optional을 쓰는 방식은 간단하지만, “null을 삭제로 해석”해야 하는 요구가 생기면 DTO/정책을 다시 손봐야 합니다.

실무에서는: Jackson의 fail-on-unknown-properties를 환경별로 다르게 운영하기도 합니다

클라이언트가 여러 버전으로 섞여 들어오는 환경에서는 unknown field를 무조건 400으로 만들면 장애처럼 보일 수 있습니다.
반대로 내부 B2B/사내 API라면 엄격 모드가 계약 위반을 빨리 잡아줘서 유지보수성이 좋아집니다.
타협안으로는 로그/모니터링으로 unknown field를 탐지하고, 일정 기간 후 엄격 모드로 전환하는 전략이 현실적입니다.

핵심 요약

@ModelAttribute는 쿼리/폼, @RequestBody는 JSON 본문을 컨버터(Jackson)로 바인딩합니다.
Jackson 설정은 “API 계약”에 해당하므로 null/unknown field 정책을 명확히 정해야 합니다.
부분 업데이트에서는 “필드 부재 vs null”을 구분하는 전략(Optional 등)을 먼저 정해 두는 게 안전합니다.

다음 글: #12 검증(Validation)과 에러 응답 표준화

Spring Boot에서 @Controller vs @RestController 제대로 구분하기 (View 렌더링과 JSON 응답 기준)

IT Lab — Mon, 9 Mar 2026 20:00:38 +0900

Spring Boot 3에서 @Controller와 @RestController의 차이를 View 렌더링/JSON 응답 관점에서 정리하고, ResponseEntity 사용 기준과 실무 컨벤션까지 예제로 확인합니다.

도입 (문제 상황)

페이지는 잘 떠야 하는데 갑자기 JSON이 내려오거나, 반대로 API를 만들었는데 뷰 이름을 찾다가 404가 나는 경험을 해 보셨을 거예요. 특히 “컨트롤러는 그냥 컨트롤러 아닌가?”라고 생각하고 @Controller와 @RestController를 섞어 쓰면, 작은 차이가 운영에서 큰 장애로 번지기도 합니다.

핵심 개념: Spring Boot에서 @Controller와 @RestController 차이가 중요한 이유

결론부터 말하면, 두 애노테이션의 차이는 “반환값을 무엇으로 해석하느냐”에 있습니다.

@Controller
기본적으로 View 렌더링(템플릿) 을 위한 컨트롤러입니다. 메서드가 String을 반환하면 “응답 본문 문자열”이 아니라 뷰 이름으로 해석됩니다.
JSON을 내려주고 싶으면 메서드나 클래스에 @ResponseBody를 붙여 “반환값을 HTTP Body로 쓰겠다”를 명시해야 합니다.
@RestController
@Controller + @ResponseBody의 합성 애노테이션입니다. 즉, 반환값은 기본적으로 항상 HTTP Body로 직렬화되어 내려갑니다(보통 JSON).
API 서버를 만들 때 의도가 분명해지고, 실수로 뷰 리졸버를 타는 사고를 줄여줍니다.

이 차이는 단순 취향 문제가 아니라, 요청 처리 파이프라인에서 어떤 HandlerMethodReturnValueHandler가 동작하느냐를 바꿉니다. “문자열을 반환했는데 왜 JSON이 아니지?” 같은 혼란은 여기서 시작합니다.

아래 표로 빠르게 정리해 보겠습니다.

구분	@Controller	@RestController
기본 목적	View 렌더링(MVC)	API(JSON 등)
반환값 기본 해석	View 이름(예: `"home"`)	Response Body(JSON 직렬화)
JSON 응답	`@ResponseBody` 필요	기본으로 JSON
실수 포인트	`String` 반환 시 뷰로 해석되어 404/템플릿 오류	View 렌더링하려다 문자열이 그대로 내려감
추천 사용처	SSR/템플릿(Thymeleaf 등)	REST API, BFF API

그리고 실무에서 자주 엮이는 주제가 ResponseEntity입니다.

ResponseEntity는 언제 쓰는 게 맞을까요?

ResponseEntity<T>는 “바디(T) + 상태코드 + 헤더”를 한 번에 제어하는 도구입니다. 다음 상황이면 쓰는 게 자연스럽습니다.

상태코드를 명확히 제어해야 할 때 (201 Created, 204 No Content, 404 Not Found 등)
Location 헤더 같은 응답 헤더를 세팅해야 할 때
성공/실패 케이스에 따라 응답 형태가 달라질 때(단, 과도한 남발은 피하는 게 좋아요)

반대로, 항상 200 OK에 단순 JSON만 내려가는 API라면 DTO를 그대로 반환해도 충분합니다. 코드가 짧아지고, 읽기도 쉬워집니다.

flowchart TD
  A["Controller method return value"] --> B{"Annotation type?"}
  B -->| "@Controller" | C{"Has @ResponseBody?"}
  C -->| "No" | D["ViewResolver renders template"]
  C -->| "Yes" | E["HttpMessageConverter writes body (JSON)"]
  B -->| "@RestController" | E

Controller와 RestController 반환 흐름 요약 다이어그램

반환값이 뷰로 갈지(JSON로) 바디로 갈지 결정되는 흐름입니다.

코드 예제: View 렌더링(@Controller) vs JSON 응답(@RestController) + ResponseEntity 기준

아래 예제는 Spring Boot 3.x(Java 17) 기준으로 그대로 복붙해 실행할 수 있게 구성했습니다. /web은 뷰 렌더링, /api는 JSON API를 보여줍니다.

build.gradle

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.3.2'
    id 'io.spring.dependency-management' version '1.1.6'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-thymeleaf' // View 렌더링 예제용
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

tasks.named('test') {
    useJUnitPlatform()
}

application.yml

spring:
  thymeleaf:
    cache: false # 예제에서는 즉시 반영을 위해 비활성화(운영에서는 true 권장)
server:
  port: 8080

실행 클래스

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApp {
    public static void main(String[] args) {
        SpringApplication.run(DemoApp.class, args);
    }
}

View 렌더링 컨트롤러(@Controller)

package com.example.demo.web;

import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class PageController {

    @GetMapping("/web")
    public String page(Model model) {
        model.addAttribute("message", "This is a server-rendered view.");
        return "home"; // templates/home.html 을 찾습니다.
    }

    @GetMapping("/web/json")
    @org.springframework.web.bind.annotation.ResponseBody
    public Message jsonFromController() {
        // @Controller에서도 @ResponseBody를 붙이면 JSON 응답이 됩니다.
        return new Message("JSON from @Controller + @ResponseBody");
    }

    public record Message(String text) {}
}

API 컨트롤러(@RestController) + ResponseEntity

package com.example.demo.api;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.net.URI;

@RestController
@RequestMapping("/api/messages")
public class MessageApiController {

    @GetMapping("/{id}")
    public MessageResponse get(@PathVariable long id) {
        // 단순 조회: 200 OK + JSON이면 DTO 반환만으로 충분한 경우가 많습니다.
        return new MessageResponse(id, "hello");
    }

    @PostMapping
    public ResponseEntity<MessageResponse> create(@RequestBody CreateMessageRequest req) {
        // 생성: 201 Created + Location 헤더를 주고 싶다면 ResponseEntity가 깔끔합니다.
        long newId = 1L; // 예제용
        var body = new MessageResponse(newId, req.text());

        return ResponseEntity
                .created(URI.create("/api/messages/" + newId))
                .body(body);
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> delete(@PathVariable long id) {
        // 삭제 성공: 204 No Content는 ResponseEntity가 의도가 분명합니다.
        return ResponseEntity.noContent().build();
    }

    public record CreateMessageRequest(String text) {}
    public record MessageResponse(long id, String text) {}
}

Thymeleaf 템플릿: resources/templates/home.html

<!doctype html>
<html lang="en">
<head>
    <meta charset="UTF-8"/>
    <title>Home</title>
</head>
<body>
<h1 th:text="${message}">placeholder</h1>
<p>Try: <a href="/web/json">/web/json</a></p>
<p>Try: <a href="/api/messages/1">/api/messages/1</a></p>
</body>
</html>

실행 후 확인

GET http://localhost:8080/web → HTML(View 렌더링)
GET http://localhost:8080/web/json → JSON (Controller + ResponseBody)
GET http://localhost:8080/api/messages/1 → JSON (RestController)
POST http://localhost:8080/api/messages with body {"text":"hi"} → 201 + Location 헤더

실무 팁

실무에서는: “패키지/URL로 역할을 분리”하는 컨벤션이 사고를 줄여줍니다

com.example.xxx.web 패키지에는 @Controller만 두고, URL도 /web, /admin, /pages처럼 뷰 성격이 드러나게 잡아두면 혼선이 줄어듭니다.
com.example.xxx.api 패키지에는 @RestController만 두고, URL도 /api/**로 고정해 두면 “여긴 무조건 JSON”이라는 기대가 생깁니다.
한 클래스에서 뷰와 API를 섞으면(특히 String 반환) 리뷰/운영에서 실수가 자주 나옵니다.

실무에서는: ResponseEntity를 “기본값”으로 두기보다 “필요할 때만” 쓰는 게 유지보수에 유리합니다

모든 메서드가 ResponseEntity<...>면 상태코드/헤더 제어가 쉬워 보이지만, 단순 조회까지 장황해져서 가독성이 떨어질 수 있습니다.
추천 기준:
- 조회(항상 200) → DTO 반환
- 생성(201, Location) / 삭제(204) / 조건부 응답(404/409 등) → ResponseEntity
에러 응답은 컨트롤러에서 매번 처리하기보다 @RestControllerAdvice로 공통화하면 일관성이 좋아집니다(다음 글의 바인딩 주제와도 연결됩니다).

핵심 요약

@Controller는 기본이 View 렌더링, @RestController는 기본이 JSON(Response Body)입니다.
ResponseEntity는 상태코드/헤더를 “의도적으로” 제어해야 할 때 특히 유용합니다.
패키지/URL 컨벤션으로 View와 API를 분리하면 운영 사고가 크게 줄어듭니다.

다음 글: [#11 요청/응답 바인딩(@RequestBody, @ModelAttribute) 실전]

IT 연구소

Spring Boot JPA Auditing(@CreatedDate 등)로 생성/수정 시간 자동 기록하기

도입 (문제 상황)

핵심 개념 — Spring Boot JPA Auditing이 중요한 이유

코드 예제 — @CreatedDate/@LastModifiedDate 베이스 엔티티로 바로 적용하기

build.gradle

application.yml

Auditing 활성화 설정

베이스 엔티티 (생성/수정 시간)

예시 엔티티/리포지토리

동작 확인용 컨트롤러

한눈에 정리: Auditing vs DB 기본값/트리거

실무 팁

Spring Boot 페이징과 정렬 실전 가이드 (성능 함정: Slice vs Page, count 최적화, keyset pagination)

도입 (문제 상황)

핵심 개념: Spring Data JPA 페이징/정렬에서 진짜 중요한 것들

1) Pageable은 편하지만, Page는 공짜가 아닙니다

2) Slice vs Page 선택 기준 (실무에서 자주 헷갈리는 부분)

3) count 쿼리 최적화: “content 쿼리”와 분리해서 생각하기

4) offset pagination의 함정과 keyset pagination(커서 페이징) 맛보기

코드 예제: Pageable, Slice vs Page, count 최적화, keyset pagination

build.gradle

application.yml

도메인: Post

Repository: Page / Slice / countQuery 분리 / keyset

Controller

데이터 초기화 (실행 시 더미 데이터 생성)

애플리케이션 엔트리포인트

호출 예시

실무 팁

Spring Boot JPA N+1 문제 원인과 해결 전략 (fetch join / EntityGraph / 배치 사이즈)

도입 (문제 상황)

핵심 개념: N+1이 왜 생기고, 무엇을 선택해야 하나요?

요청 처리 관점에서 N+1이 터지는 흐름

코드 예제: fetch join / @EntityGraph / 배치 사이즈까지 한 번에 실행해보기

build.gradle

application.yml

엔티티

Repository: 기본 조회 / fetch join / EntityGraph

DTO + Service

Controller

초기 데이터 로더

배치 사이즈 전략은 어디에 효과가 있나요?

실무 팁

Spring Boot JPA 엔티티 설계 원칙(연관관계 포함) — 실무에서 덜 고생하는 기본기

도입 (문제 상황)

핵심 개념 (Spring Boot JPA 엔티티 설계 원칙)

1) 엔티티는 “DB 테이블”이 아니라 “도메인 모델”로 설계합니다

2) 식별자(@Id) 전략: 기본은 IDENTITY보다 SEQUENCE/UUID를 고민합니다

3) 연관관계 방향: “조회가 필요한 쪽”에 두되, 양방향은 최소화합니다

4) Lazy 로딩은 기본값처럼 사용합니다(특히 ToOne/ToMany 모두)

5) equals/hashCode, toString, JSON 직렬화는 조심합니다

코드 예제 (Spring Boot 3.x / Java 17, 연관관계 + Lazy + 식별자 전략)

build.gradle

application.yml

엔티티 코드

Repository + 간단 실행(Controller)

실무 팁

Spring Boot에서 Spring Data JPA 시작하기: Repository 인터페이스(CrudRepository/JpaRepository)와 쿼리 메서드, 페이징 기본

1) 도입 (문제 상황)

2) 핵심 개념 — Spring Data JPA Repository가 중요한 이유

CrudRepository vs JpaRepository, 무엇을 선택할까?

쿼리 메서드(Query Method): “메서드 이름이 곧 쿼리”

페이징 기본: Page vs Slice

3) 코드 예제 — 복붙해서 실행 가능한 Spring Boot 3.x + JPA Repository + 쿼리 메서드 + 페이징

build.gradle

application.yml

도메인(Entity)

Repository: JpaRepository + 쿼리 메서드 + 페이징

Service

Controller: Pageable 자동 바인딩으로 페이징 API 만들기

애플리케이션 시작 시 더미 데이터 넣기

4) 실무 팁

Spring Boot에서 @Transactional 제대로 쓰기(전파/읽기전용) — 프록시부터 실수까지

도입 (문제 상황)

핵심 개념: Spring Boot @Transactional이 “왜” 중요한가

1) 프록시 기반 동작: “호출 경로”가 핵심입니다

2) readOnly=true: “쓰기 금지”가 아니라 “쓰기 최적화 힌트”에 가깝습니다

3) 전파(Propagation): “이미 트랜잭션이 있을 때” 어떻게 할지 결정합니다

4) 롤백 규칙: “어떤 예외에서 롤백되는가”

2) 식별자(@Id) 전략: 기본은 `IDENTITY`보다 `SEQUENCE`/`UUID`를 고민합니다