SecurityFilterChain은 DispatcherServlet 앞단에서 요청을 가로채는 필터 체인이다

Spring MVC는 요청이 들어오면 DispatcherServlet이 컨트롤러로 라우팅해주는데, Spring Security는 그보다 먼저 동작하는 서블릿 필터들의 묶음(체인)으로 끼어든다. 그래서 컨트롤러 코드는 보안 로직을 전혀 몰라도 되고, 필터 단계에서 "이 요청을 통과시킬지 말지"가 이미 결정된다.

@Bean
SecurityFilterChain filterChain(HttpSecurity http,
                                CustomAccessDeniedHandler customAccessDeniedHandler) {
    http
        .authorizeHttpRequests(auth -> auth
            .requestMatchers("/").permitAll()
            .requestMatchers("/error/**").permitAll()
            .requestMatchers("/free/1", "/free/2").hasRole("PREMIUM")
            .anyRequest().authenticated()
        )
        .formLogin(form -> form
            .loginPage("/login")
            .loginProcessingUrl("/login")
            .usernameParameter("username")
            .passwordParameter("password")
            .defaultSuccessUrl("/")
            .failureUrl("/login?error")
            .permitAll()
        )
        .logout(logout -> logout
            .logoutUrl("/logout")
            .logoutSuccessUrl("/login?logout")
            .invalidateHttpSession(true)
            .deleteCookies("JSESSIONID")
        )
        .exceptionHandling(ex -> ex
            .accessDeniedHandler(customAccessDeniedHandler));
    return http.build();
}

HttpSecurity는 이 필터 체인을 조립하는 빌더다. authorizeHttpRequests, formLogin, logout 같은 메서드를 체이닝해서 하나씩 규칙을 쌓고, 마지막에 http.build()를 호출하면 실제로 동작하는 SecurityFilterChain 빈이 완성된다.

어떻게 동작하는지 (동작 순서)

1. 요청이 들어오면 인증 필터들을 거치면서 "이 사용자가 누구인지"(Authentication)를 확인한다.
2. authorizeHttpRequests에 등록된 규칙을 위에서부터 순서대로 검사해서 "이 요청을 허용할지"(Authorization)를 결정한다.
3. 허용되면 그제서야 DispatcherServlet으로 넘어가서 평소처럼 컨트롤러가 실행된다.
4. 인증이 안 됐으면 로그인 페이지로, 인증은 됐는데 권한이 부족하면 AccessDeniedHandler로 빠진다.

왜 컨트롤러가 아니라 필터에서 막는지

만약 인가 체크를 각 컨트롤러 메서드 안에서 if (권한 없음) return 403; 식으로 직접 짜면, 컨트롤러가 100개면 그 체크 로직을 100번 반복하게 되고 하나라도 빠뜨리면 그게 바로 보안 구멍이 된다. 필터 단에서 URL 패턴 기준으로 일괄 관리하면 규칙이 한 곳에 모이고, 새 컨트롤러를 추가해도 규칙만 추가하면 되니 빠뜨릴 걱정이 줄어든다.

authorizeHttpRequests의 규칙은 등록된 순서대로 먼저 매치되는 것이 이긴다

.authorizeHttpRequests(auth -> auth
        .requestMatchers("/").permitAll()
        .requestMatchers("/error/**").permitAll()
        .requestMatchers("/free/1", "/free/2").hasRole("PREMIUM")
        .anyRequest().authenticated()
)

이 블록은 위에서 아래로 순서대로 읽힌다. /는 누구나(permitAll), /free/1과 /free/2는 PREMIUM 역할을 가진 사용자만, 나머지는 로그인만 되어 있으면(authenticated) 통과시킨다.

왜 순서가 중요한지

만약 .anyRequest().authenticated()를 맨 위에 놓으면 그 아래 있는 /free/1에 대한 hasRole("PREMIUM") 규칙은 절대 실행되지 않는다. anyRequest()가 모든 경로에 이미 매치되어버려서 뒤에 있는 더 구체적인 규칙까지 요청이 도달하지 못하기 때문이다. 그래서 이런 설정은 항상 "더 구체적인 경로가 먼저, 가장 넓은 범위(anyRequest)가 마지막"이라는 원칙을 지켜야 한다.

직접 확인해본 것

application.yaml을 보면 app.security.role: ADMIN으로 되어 있는데, 정작 /free/1, /free/2는 hasRole("PREMIUM")을 요구한다. 즉 지금 등록된 admin 계정으로 로그인해도 두 경로는 403이 난다. 역할 이름이 스펙(SecurityProperty)과 인가 규칙(SecurityConfig) 두 군데에 나뉘어 있다 보니 이렇게 서로 어긋나기 쉽다는 걸 직접 겪었다. 나중에 실제 프로젝트에서는 역할 상수를 한 군데(enum 등)로 모아둬야겠다고 느꼈다.

사용자 정보는 InMemoryUserDetailsManager에 UserDetails 객체로 등록한다

@Bean
InMemoryUserDetailsManager userDetailService(
        SecurityProperty p,
        PasswordEncoder passwordEncoder
) {
    UserDetails admin = User.builder()
            .username(p.username())
            .password(passwordEncoder.encode(p.password()))
            .roles(p.role())
            .build();
    return new InMemoryUserDetailsManager(admin);
}

Spring Security는 로그인 폼에서 넘어온 아이디/비밀번호를 검증할 때 UserDetailsService라는 인터페이스를 통해 "이 아이디를 가진 사용자 정보를 가져와줘"라고 요청한다. InMemoryUserDetailsManager는 이 인터페이스를 구현한 가장 단순한 형태로, DB 없이 메모리에 사용자 목록을 들고 있다가 그 요청에 응답해준다.

User.builder()로 만드는 UserDetails는 아이디, (암호화된) 비밀번호, 역할(role) 세 가지를 최소한으로 담는 값 객체다. .roles(p.role())을 호출하면 내부적으로 ROLE_ADMIN처럼 ROLE_ 접두사를 자동으로 붙여준다. 그래서 hasRole("PREMIUM")을 쓸 때도 "ROLE_PREMIUM"이라고 직접 쓰지 않아도 되는 것이다.

왜 굳이 DB 없이 인메모리로 시작하는지

Spring Security를 처음 배울 때는 "인증/인가 흐름 자체"를 이해하는 게 목적이지, 회원 DB 스키마를 설계하는 게 목적이 아니다. InMemoryUserDetailsManager를 쓰면 DB 연결 없이도 로그인 폼 → 인증 → 인가로 이어지는 전체 파이프라인을 바로 눈으로 확인할 수 있다. 실제 서비스로 넘어갈 때는 이 자리를 JPA 기반의 UserDetailsService 구현체로 바꿔 끼우기만 하면 되는 구조라, 지금 배운 흐름이 그대로 재사용된다.

어떻게 설정값을 외부에서 주입받는지

SecurityProperty는 이렇게 생겼다.

@ConfigurationProperties(prefix = "app.security")
public record SecurityProperty(
        String username,
        String password,
        String role
) {
}

application.yaml의 app.security.username, app.security.password, app.security.role 값을 자동으로 이 record에 매핑해준다. 클래스 상단에 @ConfigurationProperties만 붙여도 되는 이유는, SecApplication에 @ConfigurationPropertiesScan이 붙어 있어서 Spring이 앱을 띄울 때 이런 record/클래스를 찾아 자동으로 빈으로 등록해주기 때문이다. 계정 정보를 자바 코드에 하드코딩하지 않고 설정 파일로 빼두면, 나중에 운영 환경에서는 환경 변수(${SECURITY_USER}처럼)로 갈아끼우기만 하면 되니 코드를 건드릴 필요가 없다.

비밀번호는 평문이 아니라 PasswordEncoder를 거쳐 저장한다

@Bean
public PasswordEncoder passwordEncoder() {
    return PasswordEncoderFactories.createDelegatingPasswordEncoder();
}

그리고 사용자를 만들 때도 passwordEncoder.encode(p.password())로 감싸서 넣는다. 즉 application.yaml에는 admin1234라는 평문이 적혀 있지만, 실제로 메모리에 등록되는 UserDetails의 비밀번호는 해시된 문자열이다.

어떻게 DelegatingPasswordEncoder가 동작하는지

createDelegatingPasswordEncoder()로 만든 인코더는 인코딩할 때 문자열 앞에 {bcrypt} 같은 접두사를 붙인다. 그래서 나중에 로그인 시도가 들어와서 비밀번호를 비교할 때, 저장된 해시 문자열의 접두사를 보고 "아, 이건 bcrypt로 인코딩된 거구나"를 판단해서 그에 맞는 알고리즘으로 검증한다. 이 덕분에 나중에 더 강력한 알고리즘으로 정책이 바뀌어도 기존에 저장된 다른 방식의 해시들과 공존할 수 있다.

왜 BCryptPasswordEncoder를 직접 쓰지 않고 이걸 쓰는지

코드에 주석 처리된 new BCryptPasswordEncoder()를 보면, 처음엔 그냥 BCrypt를 직접 쓰려고 했던 흔적이 남아있다. 문제는 BCrypt 하나만 고정해서 쓰면 나중에 알고리즘을 교체하고 싶을 때(예: 더 안전한 알고리즘이 나왔을 때) 기존 사용자들의 비밀번호 해시를 어떻게 처리할지가 골치아파진다. DelegatingPasswordEncoder는 알고리즘을 문자열에 태그로 남겨두는 방식이라 이런 마이그레이션에 유연하다는 걸 이번에 찾아보면서 알게 됐다. 그래서 Spring Security 공식 문서에서도 특별한 이유가 없으면 이 팩토리 메서드를 기본값으로 쓰라고 권장한다.

폼 로그인은 loginPage와 loginProcessingUrl을 분리해서 이해해야 헷갈리지 않는다

.formLogin(form -> form
        .loginPage("/login")
        .loginProcessingUrl("/login")
        .usernameParameter("username")
        .passwordParameter("password")
        .defaultSuccessUrl("/")
        .failureUrl("/login?error")
        .permitAll()
)

loginPage("/login")은 "로그인 폼 화면을 보여주는 GET 요청 주소"이고, loginProcessingUrl("/login")은 "그 폼이 제출됐을 때(POST) Spring Security가 가로채서 실제 인증을 처리하는 주소"다. 이번 프로젝트에서는 둘 다 /login으로 같은 경로를 쓰지만, 실제로는 서로 다른 HTTP 메서드(GET vs POST)에 대한 설정이라 값이 같아도 괜찮다.

@Controller
@RequestMapping("/login")
public class LoginController {
    @GetMapping
    public String login() {
        return "login";
    }
    // 별도로 post를 만들 필요는 없음
}

그래서 컨트롤러에는 @GetMapping만 있고 POST 핸들러가 없다. /login으로 오는 POST 요청은 컨트롤러까지 가지도 않고 Spring Security의 인증 필터가 중간에서 가로채서 처리해버리기 때문이다.

왜 login.html의 form도 신경 써서 봐야 하는지

<form th:action="@{/login}" method="post">
    <input name="username" placeholder="username">
    <input type="password" name="password" placeholder="password">
    <button>로그인</button>
</form>

usernameParameter("username"), passwordParameter("password") 설정은 "이 파라미터 이름으로 넘어온 값을 아이디/비밀번호로 취급하겠다"는 약속이다. 폼의 input name 속성이 이 값과 정확히 일치해야만 Spring Security가 값을 읽어갈 수 있다. 이름이 하나라도 다르면 로그인 시도 자체가 인식이 안 되고 계속 로그인 실패로 튕겨나가는데, 처음에는 원인을 못 찾다가 이 매핑 관계를 알고 나서야 이해가 됐다.

어떻게 성공/실패가 갈리는지

로그인이 성공하면 defaultSuccessUrl("/")에 따라 메인 페이지로 리다이렉트되고, 실패하면 failureUrl("/login?error")로 돌아간다. 쿼리 파라미터 ?error는 화면에서 "아이디/비밀번호가 틀렸다"는 안내를 보여줄 때 사용할 수 있는 신호다(지금 login.html에는 아직 이 처리를 추가하지 않았는데, 다음에 th:if로 에러 메시지를 붙여봐야겠다).

로그아웃은 기본적으로 POST만 허용하고, 세션과 쿠키까지 함께 정리한다

.logout(logout -> logout
        .logoutUrl("/logout")
        .logoutSuccessUrl("/login?logout")
        .invalidateHttpSession(true)
        .deleteCookies("JSESSIONID")
)

<a href="/logout">로그아웃 (GET -> X)</a>
<form th:action="@{/logout}" method="post">
    <button>로그아웃 (POST)</button>
</form>

index.html에 일부러 GET 링크와 POST 폼을 둘 다 만들어놨는데, 실제로 눌러보면 GET 링크는 동작하지 않고 POST 버튼만 로그아웃이 된다.

왜 GET으로 로그아웃이 안 되는지

로그아웃을 GET으로 열어두면 <img src="/logout">처럼 그냥 페이지 안에 링크나 이미지 태그만 심어도 사용자가 모르는 사이에 로그아웃(혹은 더 위험한 작업)이 실행될 수 있다. 이런 공격을 CSRF(사이트 간 요청 위조)라고 부르는데, Spring Security는 상태를 변경하는 요청(로그인, 로그아웃 등)은 기본적으로 POST와 CSRF 토큰 검증을 요구해서 이런 위조 요청을 막는다. 그래서 로그아웃 버튼은 반드시 <form method="post">로 감싸야 한다는 걸 이번에 직접 눈으로 확인했다.

어떻게 세션 정리가 이루어지는지

invalidateHttpSession(true)는 서버 쪽 세션(HttpSession)을 무효화해서 세션에 저장돼 있던 로그인 정보를 완전히 날려버린다. deleteCookies("JSESSIONID")는 브라우저에 내려간 세션 쿠키까지 지우라고 응답 헤더에 지시를 담는다. 둘 중 하나만 하면 서버는 로그아웃 처리했는데 브라우저에는 예전 세션 쿠키가 남아있는 식의 애매한 상태가 될 수 있어서, 이 둘을 같이 설정하는 게 맞다는 걸 알게 됐다.

인가 실패는 AccessDeniedHandler로 원하는 화면으로 보낼 수 있다

@Component
public class CustomAccessDeniedHandler implements AccessDeniedHandler {
    @Override
    public void handle(
            HttpServletRequest request,
            HttpServletResponse response,
            AccessDeniedException accessDeniedException) throws IOException, ServletException {
        response.sendRedirect("/");
    }
}

로그인은 했지만 권한이 부족해서 막히는 경우(예: PREMIUM 역할이 필요한 페이지에 ADMIN 계정으로 접근), Spring Security는 기본적으로 403 에러 페이지를 보여준다. 그런데 여기서는 AccessDeniedHandler를 직접 구현해서 403 페이지 대신 메인 페이지(/)로 그냥 리다이렉트하도록 바꿔놨다.

.exceptionHandling(ex -> ex
        .accessDeniedHandler(customAccessDeniedHandler));

이렇게 exceptionHandling에 등록해줘야 필터 체인이 기본 403 처리 대신 이 핸들러를 사용한다.

왜 인증 실패와 인가 실패를 다르게 다뤄야 하는지

"로그인이 안 된 사용자"(비인증, AuthenticationException)와 "로그인은 했지만 권한이 없는 사용자"(인가 실패, AccessDeniedException)는 서로 다른 상황이다. 전자는 로그인 페이지로 보내는 게 자연스럽고, 후자는 이미 로그인된 사용자니까 로그인 페이지로 다시 보내는 게 오히려 어색하다. 그래서 Spring Security도 이 둘을 AuthenticationEntryPoint와 AccessDeniedHandler라는 서로 다른 인터페이스로 분리해서 처리하게 만들어 놨다는 걸 이번에 코드를 뜯어보면서 이해했다.

오늘 삽질하며 배운 것 (요약 메모)

• authorizeHttpRequests는 순서가 곧 우선순위다. anyRequest()는 항상 제일 마지막에 둬야 한다.
• 설정 파일의 역할 이름(app.security.role)과 인가 규칙의 역할 이름(hasRole(...))은 서로 다른 곳에 적혀 있어서, 값이 어긋나도 컴파일 에러가 나지 않는다. 실행해보고 403이 뜨는 걸 보고서야 눈치챘다. 나중에는 역할 이름을 enum이나 상수로 한 곳에 모아둬야겠다.
• 로그아웃은 GET으로 절대 안 뚫린다는 걸 직접 링크를 눌러보고 확인했다. CSRF 방어 때문이라는 걸 알고 나니 왜 POST 폼으로 감싸야 하는지 납득이 됐다.
• .roles("PREMIUM")을 쓰면 내부적으로 ROLE_PREMIUM으로 저장된다는 걸 몰랐다면 hasAuthority("ROLE_PREMIUM")과 hasRole("PREMIUM")을 헷갈렸을 것 같다.

사용자 입력을 이미지 생성용 프롬프트로 바꾸는 프롬프트 개선 단계

이 서비스에서 사용자가 입력창에 쓴 문장은 곧바로 이미지 생성 모델로 가지 않는다. 그 전에 LLM을 한 번 거쳐서 "이미지 생성 모델이 잘 알아듣는 형태"로 번역/재구성되는 단계가 있다. 이 역할을 하는 ChatClient는 다음과 같이 정의되어 있다.

// ImageGenConfig.java
@Bean
ChatClient promptImproveClient(ChatModel model) {
    return ChatClient.builder(model)
            .defaultSystem("""
                    - 전달받은 내용을 500자 이내의 영문으로 된 이미지 생성용 프롬프트로 개선
                    - 특징이 잘 드러나게 자세하지만 간결한 표현으로 구성
                    """)
            .defaultOptions(ChatOptions.builder()
                    .temperature(0.3)
                    .maxTokens(1000))
            .build();
}

ChatClient.builder(model)로 만든 빌더에 defaultSystem(...)을 붙이면, 이 클라이언트로 보내는 모든 요청 앞에 저 시스템 프롬프트가 항상 깔린다. 즉 매번 "영문으로, 500자 이내로, 이미지 생성용 프롬프트로 바꿔줘"라고 반복해서 적어줄 필요 없이, 사용자가 입력한 원문만 user()로 넘기면 된다. temperature를 0.3으로 낮게 잡은 것도 눈여겨볼 부분인데, 이 값이 높을수록 모델이 매번 다른 표현을 창의적으로 골라내고, 낮을수록 비슷한 입력에는 비슷한 스타일의 결과를 안정적으로 낸다. 프롬프트 번역·재구성처럼 "매번 다르게 나오면 곤란한" 작업에는 창의성보다 일관성이 중요하므로 이 값을 낮추었다.

실제 호출부는 ImageGenService에 있다.

public String improvePrompt(String prompt) {
    String improved = promptImproveClient
            .prompt().user(prompt)
            .call().content();
    System.out.println("old = " + prompt);
    System.out.println("new = " + improved);
    return improved;
}

.prompt().user(prompt)로 사용자 메시지를 세팅하고 .call().content()로 문자열 응답만 뽑아낸다. Spring AI의 ChatClient는 스트리밍(.stream())이나 구조화된 응답(.entity(...))도 지원하지만, 여기서는 그냥 텍스트 하나만 필요하니 가장 단순한 형태를 쓴 것이다.

이 호출이 실제로 어디로 가는지는 application-ai.yaml을 보면 이렇다.

spring:
  ai:
    openai:
      api-key: ${GROQ_API_KEY}
      base-url: https://api.groq.com/openai/v1
      chat:
        model: openai/gpt-oss-120b

의존성은 spring-ai-starter-model-openai인데 base-url은 OpenAI가 아니라 Groq을 가리킨다. Groq이 OpenAI와 같은 Chat Completions API 스펙을 그대로 흉내 내주기 때문에, OpenAI 전용으로 짜인 클라이언트 코드를 한 줄도 안 바꾸고 base-url과 api-key만 갈아끼워서 재사용할 수 있는 것이다. 모델 이름의 openai/gpt-oss-120b도 헷갈리기 쉬운데, OpenAI가 만든 비공개 모델이 아니라 OpenAI가 오픈소스로 공개한 gpt-oss-120b를 Groq이 자체 LPU 인프라에 올려서 아주 빠르게 서빙해주는 것이다. 프롬프트를 다듬는 정도의 가벼운 작업이라 최상급 모델까지는 필요 없고, 대신 Groq 특유의 저지연 추론 덕분에 이미지 생성 전에 LLM 호출을 한 단계 더 끼워 넣어도 사용자가 느끼는 전체 대기 시간에 큰 부담을 주지 않는다는 점까지 고려된 조합으로 보인다.

Spring AI가 아니라 커스텀 RestClient로 이미지 생성 API를 직접 두드리는 구조

프롬프트가 준비되면 실제 이미지를 만들 차례인데, 이 부분은 Spring AI의 ImageModel 추상화를 쓰지 않는다. 대신 순수한 RestClient로 Cloudflare Workers AI의 REST 엔드포인트를 직접 호출한다. Spring AI의 이미지 생성 추상화는 OpenAI DALL-E 계열을 기준으로 만들어져 있어서, Cloudflare Workers AI처럼 지원 대상이 아닌 provider는 표준 API로 감쌀 방법이 없기 때문이다.

먼저 이 호출 전용 RestClient 빈을 보자.

// ImageGenConfig.java
@Bean
RestClient cfWorkersAiClient(RestClient.Builder b, CFProperty p) {
    HttpClientSettings settings = HttpClientSettings.defaults()
            .withTimeouts(
                    Duration.ofSeconds(5),   // connection - 요청은 금방 보내야 하니까
                    Duration.ofSeconds(60)   // read - 이미지 처리는 오래 걸릴 수 있으니까
            );
    String baseUrl = "https://api.cloudflare.com/client/v4/accounts/%s/ai".formatted(p.accountId());
    return b.clone()
            .baseUrl(baseUrl)
            .defaultHeader(HttpHeaders.AUTHORIZATION, "Bearer %s".formatted(p.apiToken()))
            .requestFactory(ClientHttpRequestFactoryBuilder.detect().build(settings))
            .build();
}

baseUrl에 계정 전용 AI 엔드포인트를 미리 박아두고 defaultHeader로 인증 토큰까지 심어뒀기 때문에, 이 빈을 주입받는 쪽에서는 매 요청마다 URL 전체와 인증 헤더를 신경 쓸 필요 없이 뒤에 붙는 경로(/run/{model})만 신경 쓰면 된다.

타임아웃을 connection 5초, read 60초로 다르게 잡은 것도 의미가 있는데, "요청을 보내는 것"과 "이미지 생성이 끝나서 응답이 돌아오는 것"은 걸리는 시간의 성격이 완전히 다르기 때문이다. 연결 자체는 금방 되거나 실패하지만, 이미지 생성은 모델이 실제로 그림을 그리는 동안 서버가 응답을 들고 있어야 하므로 read 쪽에 훨씬 여유를 준 것이다.

실제 호출은 서비스 계층에 있다.

public GenResultDTO invokeImage(String prompt) {
    String modelName = "@cf/black-forest-labs/flux-1-schnell";
    GenResultDTO result = aiClient.post()
            .uri("/run/%s".formatted(modelName))
            .contentType(MediaType.APPLICATION_JSON)
            .body(new GenRequestDTO(prompt, 4))
            .retrieve()
            .body(GenResultDTO.class);
    return result;
}

GenRequestDTO(prompt, 4)에서 steps를 4로 준 것도 아무 값이나 고른 게 아니다. flux-1-schnell은 이름 그대로 "빠른(schnell)" 버전으로, 몇 단계 안 되는 적은 스텝만으로도 충분히 쓸만한 품질이 나오도록 설계된 모델이다. Flux의 일반 모델이 수십 스텝을 도는 것과 비교하면, steps=4는 이 모델의 특성에 맞춰 속도를 최대한 끌어올린 값이다.

응답을 담는 GenResultDTO도 구조를 보면 설계 의도가 드러난다.

public record GenResultDTO(boolean success, ImageResult result, List<CFMessage> errors) {
    public record ImageResult(String image) { } // base64
    public record CFMessage(int code, String message) { }
}

Cloudflare API는 성공하든 실패하든 HTTP 200으로 응답하면서success 플래그와 errors 배열로 결과를 구분하는 패턴을 쓰는데, 이 DTO는 그 두 경우를 모두 담을 수 있게 필드를 미리 만들어뒀다.

다만 지금 코드에서는 result.success()나 result.errors()를 실제로 검사하는 곳이 없어서, 이 필드들은 아직 "언젠가 쓰려고 만들어둔" 상태로 남아 있다(9번 항목에서 다시 다룬다).

base64로 받은 이미지를 디코딩해서 S3 호환 스토리지에 올리는 저장 로직

Cloudflare가 돌려주는 이미지는 바이너리 파일이 아니라 base64로 인코딩된 문자열이다. 이걸 그대로 DB 텍스트 컬럼에 넣어버릴 수도 있지만, 그러면 컬럼 하나가 수십~수백 KB짜리 문자열을 매번 들고 있어야 해서 조회·백업 성능이 나빠지고, 애초에 브라우저에 이미지를 서빙하기에도 적합하지 않다.

그래서 이 프로젝트는 이미지 바이트 자체는 오브젝트 스토리지에 두고, DB에는 "어디에 저장했는지"를 가리키는 키(파일명)만 남기는 방식을 쓴다.

public String upload(GenResultDTO result) {
    String filename = "%s.jpg".formatted(UUID.randomUUID());
    byte[] bytes = Base64.getDecoder().decode(result.result().image());
    InputStream data = new ByteArrayInputStream(bytes);
    ObjectMetadata metadata = ObjectMetadata.builder()
            .contentType(MediaType.IMAGE_JPEG_VALUE)
            .build();
    s3Template.upload(bucket, filename, data, metadata);
    return filename; // 호출 시 Key 값 filename만 return
}

순서를 그대로 따라가 보면, Base64.getDecoder().decode(...)로 문자열을 실제 바이트 배열로 되돌리고, 그 바이트 배열을 ByteArrayInputStream으로 감싸서 S3Template.upload(...)가 요구하는 InputStream 형태로 맞춘다. 파일명은 UUID.randomUUID()로 매번 새로 만들기 때문에 여러 사용자가 동시에 이미지를 생성해도 파일명이 겹칠 걱정이 없다. 업로드가 끝나면 이 filename(=S3의 key)만 반환값으로 돌려주고, 이 값이 나중에 GenImage 엔티티에 저장된다.

여기서 "S3"라는 이름이 붙어 있지만 실제로는 AWS S3가 아니다. application-file.yaml을 보면 이게 드러난다.

spring:
  cloud:
    aws:
      s3:
        endpoint: ${STORAGE_ENDPOINT}
        region: ${STORAGE_REGION}
        path-style-access-enabled: true

spring-cloud-aws-starter-s3는 "S3 API 규격을 따르는 스토리지라면 AWS가 아니어도 endpoint만 바꿔서 붙일 수 있게" 해주는 라이브러리다. 그 덕분에 .env.dev.sample에 적힌 것처럼 실제로는 Supabase Storage의 S3 호환 엔드포인트(https://*.storage.supabase.co/storage/v1/s3)를 그대로 연결해서 쓰고 있다.

path-style-access-enabled: true는 요청 URL 형태를 bucket.endpoint.com/key(virtual-hosted style)가 아니라 endpoint.com/bucket/key(path style)로 만들라는 옵션인데, AWS가 아닌 S3 호환 스토리지들은 대체로 path style만 지원하기 때문에 켜줘야하는 설정이다.

이미지를 스토리지 URL로 직접 노출하지 않고 컨트롤러가 대신 내려주는 방식

템플릿에서 이미지 태그가 가리키는 주소를 보면 스토리지 주소가 아니라 이 애플리케이션 자신의 경로다.

<!-- gen/page.html -->
<img th:src="@{/gen/{f}(f=${result.filename})}" width="240" alt="생성된 이미지">

브라우저가 이 <img>를 렌더링하려고 요청을 보내면, 그 요청은 스토리지가 아니라 우리 서버의 /gen/{filename}으로 간다. 그걸 받는 쪽은 이렇게 되어 있다.

// ImageGenController.java
@GetMapping("/{filename}")
public ResponseEntity<Resource> download(@PathVariable String filename) {
    return ResponseEntity.ok()
            .contentType(MediaType.IMAGE_JPEG)
            .body(imageGenService.download(filename));
}

// ImageGenService.java
public Resource download(String filename) {
    return s3Template.download(bucket, filename);
}

컨트롤러는 filename을 받아 서비스에 넘기고, 서비스는 s3Template.download(bucket, filename)로 스토리지에서 실제 파일을 가져와 Resource로 감싸 돌려준다. 컨트롤러는 그 Resource를 Content-Type: image/jpeg로 응답 바디에 그대로 실어 보낸다. 즉 브라우저 입장에서는 이미지가 어느 스토리지에 저장돼 있는지 전혀 알 필요가 없고, 항상 우리 서버를 거쳐서만 이미지를 받는다.

이렇게 한 겹을 끼워두면 버킷 자체는 비공개로 유지하면서도 인증·로깅 같은 접근 제어를 애플리케이션 레이어에 자유롭게 얹을 수 있고, 나중에 스토리지를 다른 곳으로 옮기더라도(예: Supabase → AWS S3) 프론트엔드 코드는 한 글자도 바꿀 필요가 없다.

<!--/* [[${result.result.image}]] */-->
<!--/* <img th:src="'data:image/jpeg;base64,' + ${result.result.image}" */-->
<!--/* width="240" alt="생성된 이미지"> */-->

초기 버전은 Cloudflare가 돌려준 base64 문자열을 data:image/jpeg;base64,... 형태로 <img>에 직접 꽂아 넣는 방식이었다. 구현은 훨씬 간단하지만, 페이지를 새로고침할 때마다 base64 문자열 전체를 다시 실어 날라야 해서 무겁고, 무엇보다 "예전에 만든 이미지 목록을 다시 보여주기" 기능을 만들려면 그 긴 문자열을 어딘가에 영구히 저장해두는 수밖에 없다. S3에 저장하고 key만 DB에 남기는 지금 구조로 바꾸면서 이 문제가 자연스럽게 함께 해결된 셈이다.

프롬프트 개선부터 DB 저장까지 하나로 묶은 generateImage()의 흐름

지금까지 본 네 단계(프롬프트 개선 → 이미지 생성 → 업로드 → DB 저장)를 실제로 이어붙이는 진입점이 ImageGenService.generateImage()다.

@Transactional
public ImageResultDTO generateImage(String prompt) {
    String improved = improvePrompt(prompt);
    GenResultDTO result = generate(improved);
    String key = upload(result);
    repository.save(GenImage.builder()
            .filename(key)
            .prompt(prompt)
            .improved(improved)
            .build());
    return new ImageResultDTO(key, prompt, improved);
}

코드를 그대로 읽으면 "프롬프트를 개선하고 → 그 결과로 이미지를 만들고 → 업로드해서 key를 얻고 → 원본 프롬프트·개선된 프롬프트·key를 한 행으로 저장한다"는 흐름이 그대로 보인다. 이 메서드 전체에 @Transactional을 붙인 이유는 "이미지 생성까지는 다 됐는데 DB 저장만 실패해서 어정쩡한 데이터가 남는" 상황을 막고 싶었기 때문이다.

다만 여기서 짚고 넘어가야 할 부분이 있다. @Transactional이 실제로 보장해주는 건 DB 커넥션의 커밋/롤백뿐이고, 그 안에서 호출하는 외부 HTTP API(LLM 호출, 이미지 생성, S3 업로드)는 전혀 롤백 대상이 아니다. 즉 마지막 repository.save(...)가 실패해서 트랜잭션이 롤백되더라도, 이미 Cloudflare에 만들어달라고 요청해서 비용이 발생한 이미지와 이미 S3에 올라간 파일은 그대로 남는다. 게다가 read timeout을 60초까지 열어둔 이미지 생성 API 호출이 트랜잭션 범위 안에 있다는 것은, 그 시간 동안 DB 커넥션 풀에서 커넥션 하나를 계속 붙잡고 놓아주지 않는다는 뜻이기도 하다. 느린 외부 API 호출과 DB 트랜잭션을 한 메서드에 같이 두면 늘 따라오는 트레이드오프다.

@ConfigurationProperties record로 Cloudflare 설정값을 묶은 방식

Cloudflare 연동에 필요한 값은 계정 ID와 API 토큰 두 개인데, 이 둘을 각각 @Value로 따로 주입받는 대신 하나의 타입으로 묶어뒀다.

@ConfigurationProperties(prefix = "app.cf")
public record CFProperty(String accountId, String apiToken) {
}

prefix = "app.cf"이므로 application-ai.yaml의 app.cf.account-id, app.cf.api-token 값이 각각 accountId, apiToken으로 바인딩된다. (스프링의 relaxed binding 덕분에 케밥 케이스 YAML 키가 카멜 케이스 필드에 자동으로 매핑된다). 이 클래스를 빈으로 등록하기 위한 별도의 @Bean 메서드는 어디에도 없는데, 대신 애플리케이션 클래스에 이런 애노테이션이 붙어 있다.

@SpringBootApplication
@ConfigurationPropertiesScan
public class ImagegenApplication { ... }

@ConfigurationPropertiesScan이 클래스패스를 스캔하면서 @ConfigurationProperties가 붙은 타입을 자동으로 찾아 빈으로 등록해주기 때문에, CFProperty는 별도 설정 없이도 ImageGenConfig.cfWorkersAiClient(RestClient.Builder b, CFProperty p)에서 바로 주입받아 쓸 수 있다. 두 값을 항상 세트로 다뤄야 한다는 사실이 record라는 타입 하나로 명확하게 드러나고, record는 필드가 모두 final이라 한 번 값이 채워지면 실수로 바뀔 일도 없다.

다만 같은 파일에서 S3 버킷 이름은 조금 다른 방식으로 주입받는다.

@Value("${app.sb.bucket}")
private String bucket;

버킷 이름은 값이 하나뿐이라 굳이 별도 타입을 만들지 않고 필드에 바로 주입한 것인데, 일관성만 놓고 보면 이것도 CFProperty처럼 작은 record로 뽑아냈어도 괜찮았을 부분이다.

prompt, improved 컬럼 길이를 넉넉하게 잡아둔 엔티티 설계

GenImage 엔티티는 사용자가 입력한 원본 프롬프트와 LLM이 다듬은 프롬프트를 함께 저장한다.

@Entity
public class GenImage {
    @Id @GeneratedValue
    private Long id;
    private String filename;
    @Column(length = 2000)
    private String prompt;
    @Column(length = 2000)
    private String improved;
}

prompt, improved 두 컬럼에만 @Column(length = 2000)이 붙어 있다. 사용자가 입력하는 원본 프롬프트는 컨트롤러의 @Size(max = 500)으로 500자까지만 들어오도록 막혀 있지만, LLM이 돌려주는 개선된 프롬프트는 상황이 다르다. "500자 이내로 써줘"라는 요청은 시스템 프롬프트로 모델에게 부탁한 것일 뿐 강제되는 규칙이 아니라서, 모델이 이 지침을 넘겨서 응답할 가능성을 배제할 수 없다. JPA/Hibernate가 문자열 컬럼에 기본으로 잡는 길이(255자)로는 이 값을 안전하게 담기 어렵기 때문에 여유 있게 2000자로 늘려잡은 것이다. 반면 filename은 애플리케이션이 직접 UUID + ".jpg" 형태로 만드는 고정 길이 값이라 굳이 길이를 조정할 필요가 없어 기본값 그대로 남아 있다.

이 스키마는 마이그레이션 도구 없이 application-db.yaml의 hibernate.ddl-auto: update 설정을 통해 애플리케이션이 뜰 때마다 자동으로 맞춰진다.

Part 1에서 이미지와 PDF를 Vector Store에 저장하는 방법을 배웠다면, 이번에는 저장된 Document를 실제 질문과 비교해서 검색하는 방법을 학습했다.

이번 프로젝트에서 핵심적으로 사용한 것은 다음과 같다.

• VectorStore
• similaritySearch()
• SearchRequest
• topK
• similarityThreshold
• 이미지 RAG 검색 결과 DTO
• PDF RAG에서 QuestionAnswerAdvisor를 활용한 검색

즉, 단순히 데이터를 Vector Store에 저장하는 것에서 끝나는 것이 아니라 사용자의 질문과 의미적으로 가까운 Document를 찾아오는 과정을 구현했다.

VectorStore의 similaritySearch

이미지 RAG에서는 다음과 같이 VectorStore에서 검색을 수행한다.

SearchRequest request = SearchRequest.builder()
        .query(query)
        .topK(3)
        .similarityThreshold(0.5)
        .build();

List<Document> results =
        imageVectorStore.similaritySearch(request);

여기서 핵심은 similaritySearch()다.

사용자가 검색어를 입력하면 해당 검색어를 기반으로 Vector Store에서 유사한 Document를 찾아온다.

사용자 검색어
     ↓
Vector Store 검색
     ↓
유사도가 높은 Document
     ↓
List<Document>

SearchRequest로 검색 조건 지정하기

이번 프로젝트에서는 단순히 문자열만 전달하는 것이 아니라 SearchRequest를 사용해서 검색 조건을 지정했다.

SearchRequest request = SearchRequest.builder()
        .query(query)
        .topK(3)
        .similarityThreshold(0.5)
        .build();

각 옵션의 의미는 다음과 같다.

따라서 이 코드는

검색어와 유사도가 충분히 높은 Document 중 최대 3개를 가져온다.

라고 이해할 수 있다.

topK의 역할

topK()는 검색 결과의 최대 개수를 결정한다.

이번 프로젝트의 이미지 검색에서는 다음과 같이 설정되어 있다.

.topK(3)

따라서 검색 결과가 아무리 많더라도 최대 3개의 Document만 가져온다.

검색 결과
 ├─ Document 1
 ├─ Document 2
 ├─ Document 3
 ├─ Document 4
 └─ Document 5

        ↓ topK(3)

최종 결과
 ├─ Document 1
 ├─ Document 2
 └─ Document 3

여기서 중요한 것은 topK가 반드시 3개를 반환한다는 의미는 아니라는 것이다.

similarityThreshold 조건까지 적용되기 때문에 조건을 만족하는 Document가 2개라면 2개만 반환될 수 있다.

similarityThreshold의 역할

다음 설정은 검색 결과의 최소 유사도 기준이다.

.similarityThreshold(0.5)

검색된 Document의 유사도가 너무 낮다면 결과에서 제외한다.

개념적으로 보면 다음과 같다.

검색 결과

Document A → 0.91
Document B → 0.76
Document C → 0.61
Document D → 0.42
Document E → 0.31

similarityThreshold = 0.5

                ↓

Document A → 포함
Document B → 포함
Document C → 포함
Document D → 제외
Document E → 제외

따라서 topK와 similarityThreshold는 서로 다른 역할을 한다.

similarityThreshold
→ "얼마나 비슷해야 검색 결과로 인정할 것인가?"

topK
→ "인정된 결과를 최대 몇 개 가져올 것인가?"

이미지 RAG에서는 검색 결과를 DTO로 변환

이미지 RAG에서는 검색된 Document를 그대로 사용하는 것이 아니라 ImageRagSearchResult로 표현한다.

실제 DTO는 다음과 같다.

public record ImageRagSearchResult(
        String caption,
        String publicUrl
) {
}

여기에는 두 가지 정보가 들어간다.

• caption: 이미지에 대해 생성된 설명
• publicUrl: Supabase Storage에 저장된 이미지 URL

즉, 이미지 검색 결과는 단순히 "비슷한 벡터가 발견됐다"에서 끝나는 것이 아니라 검색된 이미지의 설명과 실제 이미지를 확인할 수 있는 정보로 구성된다.

PDF RAG에서는 검색을 QuestionAnswerAdvisor와 연결

PDF RAG에서는 검색 결과를 직접 다루는 방식 외에 QuestionAnswerAdvisor를 이용해서 RAG 검색과 답변 생성을 연결한다.

업로드된 PDF의 Chunk가 Vector Store에 저장되어 있기 때문에 사용자의 질문이 들어오면 관련 Document를 검색하고 이를 질문에 활용할 수 있다.

PDF RAG에서 사용하는 검색 조건 역시 다음과 같이 SearchRequest를 기반으로 구성되어 있다.

SearchRequest.builder()
        .topK(3)
        .similarityThreshold(0.5)
        .build()

여기서 중요한 점은 검색 결과를 LLM에게 그냥 전부 전달하는 것이 아니라 검색 조건을 통해 관련성이 높은 Document를 선별한다는 것이다.

Vector Search에서 중요한 두 가지

이번 프로젝트에서 Vector Search를 구현하면서 가장 중요하게 이해한 것은 다음 두 가지다.

① 검색 결과의 개수

.topK(3)

얼마나 많은 Document를 가져올지 결정한다.

② 검색 결과의 관련성

.similarityThreshold(0.5)

어느 정도 이상 유사한 Document만 검색 결과로 사용할지 결정한다.

둘을 함께 사용하면 다음과 같은 형태가 된다.

                    검색어
                      │
                      ▼
               Vector Search
                      │
             ┌────────┴────────┐
             │                 │
       유사도 기준 확인       결과 개수 제한
             │                 │
    threshold = 0.5       topK = 3
             │                 │
             └────────┬────────┘
                      ▼
                검색 결과

Image RAG와 PDF RAG의 검색 방식

이번 프로젝트에서는 이미지와 PDF가 모두 Vector Search를 사용하지만, 검색 결과를 활용하는 방식에는 차이가 있다.

즉, 검색 자체의 핵심 원리는 동일하고 검색된 Document를 어떻게 활용하는지가 다르다.

Vector Search를 직접 구현하면서 알게 된 것

Vector Search는 단순히

similaritySearch(query)

한 줄로 끝나는 기능처럼 보이지만 실제로는 검색 결과를 어떻게 제한할 것인지 결정하는 것이 중요하다.

이번 프로젝트에서는

SearchRequest.builder()
        .query(query)
        .topK(3)
        .similarityThreshold(0.5)
        .build();

처럼 검색 조건을 명시적으로 구성했다.

이를 통해

검색어
 ↓
유사도 비교
 ↓
threshold 기준으로 필터링
 ↓
topK만큼 결과 선택
 ↓
RAG에서 활용

이라는 검색 과정을 이해할 수 있었다.

이번 Part 2에서 가장 중요하게 배운 것은 Vector Store에 문서를 저장하는 것과 저장된 문서를 검색해서 활용하는 것은 별도의 과정이라는 점이다.

Part 1에서는

이미지 → Document → Vector Store
PDF → Document → Chunk → Vector Store

처럼 데이터를 적재하는 과정을 다뤘다면,

Part 2에서는

질문
 ↓
SearchRequest
 ↓
Vector Search
 ↓
관련 Document 검색
 ↓
RAG에서 활용

하는 과정을 다룬다.

특히 SearchRequest를 이용해

.topK(3)
.similarityThreshold(0.5)

와 같이 검색 범위를 조절할 수 있다는 점이 중요했다.

느낀 점

이번 프로젝트를 통해 RAG는 단순히 AI에게 질문을 전달하는 방식이 아니라, 질문과 관련된 데이터를 먼저 검색하고 그 결과를 AI가 활용하도록 만드는 구조라는 것을 코드로 이해할 수 있었다.

특히 이미지 RAG에서는 검색된 Document에서 caption과 publicUrl을 활용하고, PDF RAG에서는 검색된 문서를 질문에 활용한다는 차이를 확인하면서 같은 Vector Search를 서로 다른 형태의 데이터에 적용할 수 있다는 점을 배웠다.

또한 topK와 similarityThreshold를 직접 설정하면서 RAG에서 무엇을 검색할 것인지뿐만 아니라 검색 결과를 어디까지 허용할 것인지도 중요하다는 것을 알게 되었다.

이번 프로젝트에서는 이미지뿐만 아니라 PDF 파일을 RAG의 검색 대상 문서로 적재하는 과정을 구현했다.

PDF는 이미지처럼 그대로 Vector Store에 넣는 것이 아니라,

PDF 파일 → 페이지별 Document → Chunk → Vector Store 저장

과정을 거쳐야 한다.

이번 프로젝트에서 핵심적으로 사용한 기술은 다음과 같다.

• MultipartFile을 이용한 PDF 업로드
• PagePdfDocumentReader
• PdfDocumentReaderConfig
• TokenTextSplitter
• Document
• VectorStore
• PDF 원본 파일명 metadata 저장
• vectorStore.add()를 통한 벡터 저장

PDF를 바로 Vector Store에 넣지 않는 이유

PDF 파일 자체는 RAG가 바로 검색할 수 있는 형태가 아니다.

따라서 업로드된 PDF를 먼저 Document 객체로 변환하고, 다시 검색하기 적절한 크기의 조각으로 나누어야 한다.

전체적인 흐름은 다음과 같다.

PDF 업로드
   ↓
MultipartFile
   ↓
InputStreamResource
   ↓
PagePdfDocumentReader
   ↓
페이지별 Document
   ↓
TokenTextSplitter
   ↓
여러 개의 Chunk
   ↓
metadata 추가
   ↓
VectorStore.add()
   ↓
벡터 DB 저장

이 과정에서 중요한 것은 PDF를 읽는 것과 PDF를 검색 가능한 단위로 만드는 것은 별개의 작업이라는 점이다.

PDF 업로드 받기

PDF 파일은 MultipartFile로 전달받는다.

실제 프로젝트에서는 PDF 업로드를 처리하는 서비스에서 다음과 같은 형태로 파일을 받는다.

public int uploadPDF(MultipartFile file) {
    validate(file);

    ...
}

여기서 MultipartFile은 사용자가 업로드한 파일을 Spring에서 표현하는 객체다.

따라서 서비스 입장에서는 다음과 같은 정보를 가지고 PDF를 처리할 수 있다.

MultipartFile
 ├─ 파일 이름
 ├─ Content-Type
 ├─ InputStream
 └─ 파일 데이터

특히 PDF 내용을 읽기 위해서는 다음처럼 getInputStream()을 사용한다.

Resource resource =
        new InputStreamResource(
                file.getInputStream()
        );

즉,

MultipartFile
      ↓
getInputStream()
      ↓
InputStreamResource
      ↓
PDF Reader

라는 형태로 PDF Reader가 읽을 수 있는 Resource로 변환한다.

PagePdfDocumentReader로 PDF 읽기

PDF를 읽는 핵심 코드가 다음 부분이다.

PagePdfDocumentReader reader =
        new PagePdfDocumentReader(
                resource,
                PdfDocumentReaderConfig.builder().build()
        );

여기서 중요한 클래스가 PagePdfDocumentReader다.

이 Reader는 PDF를 읽어서 Spring AI의 Document 형태로 변환하는 역할을 한다.

그리고 실제로 PDF를 읽는 부분은 다음과 같다.

List<Document> pages = reader.read();

결과적으로 PDF 하나가 여러 개의 Document로 변환된다.

예를 들어 PDF가 5페이지라면 개념적으로 다음과 같은 형태가 된다.

PDF
 ├─ 1페이지 → Document
 ├─ 2페이지 → Document
 ├─ 3페이지 → Document
 ├─ 4페이지 → Document
 └─ 5페이지 → Document

즉, 이 단계에서는 PDF를 페이지 단위의 Document로 변환한다.

PDF를 페이지 단위로 읽은 다음 다시 Chunk로 나누기

페이지 단위로 만들어졌다고 해서 바로 Vector Store에 저장하는 것은 아니다.

프로젝트에서는 다음 코드를 사용한다.

TokenTextSplitter splitter =
        TokenTextSplitter.builder().build();

List<Document> chunks =
        splitter.apply(pages);

여기서 TokenTextSplitter가 하는 역할은 Document를 더 작은 텍스트 조각으로 나누는 것이다.

전체 과정을 보면:

PDF
 ↓
PagePdfDocumentReader
 ↓
pages
 ↓
TokenTextSplitter
 ↓
chunks

이다.

왜 다시 나눌까?

페이지 하나가 항상 검색하기 좋은 크기의 텍스트라는 보장이 없기 때문이다.

예를 들어 한 페이지에 매우 많은 내용이 있다면 하나의 Document로 저장했을 때 검색 단위가 너무 커질 수 있다.

그래서

페이지 단위 Document
        ↓
TokenTextSplitter
        ↓
작은 Chunk 여러 개

형태로 변환한다.

이렇게 만들어진 chunks가 실제 RAG 검색의 기본 단위가 된다.

Chunk에 PDF 파일명 metadata 추가하기

이번 프로젝트에서 특히 눈여겨볼 부분이 이 코드다.

chunks.forEach(
        chunk -> chunk.getMetadata()
                .put(
                        "filename",
                        file.getOriginalFilename()
                )
);

Chunk의 본문만 저장하는 것이 아니라 어떤 PDF에서 나온 내용인지 metadata로 저장한다.

예를 들어 사용자가

spring-ai-guide.pdf

를 업로드했다면 각각의 Chunk에 다음과 같은 metadata가 들어갈 수 있다.

Document
 ├─ text
 │   └─ PDF에서 추출된 내용
 │
 └─ metadata
     └─ filename = "spring-ai-guide.pdf"

이렇게 하면 나중에 검색 결과에서 해당 내용이 어떤 파일에서 나온 것인지 확인할 수 있는 기반을 만들 수 있다.

VectorStore에 Chunk 저장

마지막으로 만들어진 Chunk들을 Vector Store에 저장한다.

vectorStore.add(chunks);

여기서 중요한 것은 chunks가 단순한 문자열 목록이 아니라는 점이다.

List<Document> chunks

형태로 만들어져 있다.

그리고 이 Document 목록을 VectorStore에 전달한다.

전체 PDF 적재 코드는 다음과 같은 구조다.

public int uploadPDF(MultipartFile file) {
    validate(file);

    try {
        Resource resource =
                new InputStreamResource(
                        file.getInputStream()
                );

        PagePdfDocumentReader reader =
                new PagePdfDocumentReader(
                        resource,
                        PdfDocumentReaderConfig.builder().build()
                );

        List<Document> pages = reader.read();

        TokenTextSplitter splitter =
                TokenTextSplitter.builder().build();

        List<Document> chunks =
                splitter.apply(pages);

        chunks.forEach(
                chunk -> chunk.getMetadata()
                        .put(
                                "filename",
                                file.getOriginalFilename()
                        )
        );

        vectorStore.add(chunks);

        return chunks.size();

    } catch (Exception e) {
        throw new IllegalArgumentException(e);
    }
}

이 코드 하나에 PDF RAG의 적재 과정 전체가 들어있다.

코드의 역할을 단계별로 정리

PDF RAG에서 중요한 것은 "파일 → Chunk" 변환

이번 구현을 공부하면서 PDF RAG를 단순히

PDF → Vector DB

라고 생각하면 안 된다.

실제로는 다음과 같은 여러 단계가 존재한다.

                    PDF
                     │
                     ▼
            PagePdfDocumentReader
                     │
                     ▼
             List<Document>
              페이지 단위
                     │
                     ▼
             TokenTextSplitter
                     │
                     ▼
              List<Document>
               Chunk 단위
                     │
                     ▼
              metadata 추가
                     │
                     ▼
             VectorStore.add()
                     │
                     ▼
               Vector Store

즉 RAG의 검색 품질을 결정하는 중요한 부분 중 하나가 문서를 어떻게 쪼개서 저장하느냐라는 것을 알 수 있다.

Controller에서는 PDF 적재를 서비스에 위임

PDF 업로드 요청을 받는 Controller에서는 PDF 처리 자체를 직접 하지 않고 서비스의 uploadPDF()를 호출한다.

실제 프로젝트의 PDF 업로드 흐름에서는 서비스에서 다음 메서드를 사용한다.

uploadPDF(MultipartFile file)

그리고 PDF를 적재한 뒤 반환되는 값은 다음과 같다.

return chunks.size();

즉, 업로드된 PDF가 몇 개의 Chunk로 분리되었는지를 반환하도록 되어 있다.

예를 들어:

PDF 업로드
   ↓
100개의 Chunk 생성
   ↓
vectorStore.add(chunks)
   ↓
100 반환

처럼 동작한다.

이 값은 단순한 숫자처럼 보이지만 PDF가 RAG 저장 단위로 몇 개의 Document로 분리되었는지 확인할 수 있는 값이다.

이번 Part 1-2에서 가장 중요하게 이해한 것은 PDF를 RAG에 사용하기 위해서는 문서 변환 과정이 필요하다는 것이다.

특히 다음 세 가지를 구분해서 이해해야 한다.

① Reader

PagePdfDocumentReader

PDF를 읽어서 Document로 만든다.

② Splitter

TokenTextSplitter

Document를 작은 Chunk로 나눈다.

③ VectorStore

vectorStore.add(chunks);

나누어진 Chunk를 벡터 저장소에 적재한다.

따라서 이번 프로젝트의 PDF 적재 과정은

Reader → Splitter → VectorStore

라는 구조로 이해하면 된다.

느낀 점

이번에는 PDF를 단순히 파일로 저장하는 것이 아니라 AI가 검색할 수 있는 Document 단위로 변환하는 과정이 필요하다는 것을 배웠다.

특히 PagePdfDocumentReader로 PDF를 읽은 뒤 TokenTextSplitter를 통해 다시 Chunk로 나누는 과정을 직접 코드로 확인하면서, RAG에서 문서 적재가 단순한 파일 업로드와 다르다는 것을 이해할 수 있었다.

또한 Chunk마다 filename metadata를 추가함으로써 본문뿐만 아니라 문서의 출처 정보도 함께 관리할 수 있다는 점도 알게 되었다.

결국 PDF RAG에서는

PDF 파일을 받는 것

에서 끝나는 것이 아니라,

PDF
 → Document
 → Chunk
 → Metadata
 → VectorStore

까지 변환해야 실제 검색에 활용할 수 있다는 것이 이번 Part 1-2의 핵심이었다.

                                          Huh?

프로그래머스 데브코스 AI 활용 백엔드 과정 7기의 두번째 프로젝트인 백엔드 팀 프로젝트가 시작되었다. 다른 백엔드 개발자와의 협업 경험이 전무하여 이번이 처음으로 하는 백엔드 팀 프로젝트였다. 지금 쓰는 프로젝트 회고도 처음 쓰는 프로젝트 회고이다...

프로젝트의 주제는 재능 및 프리랜서 매칭 플랫폼이었다.

Keep

• 사용자의 입장에서 서비스를 어떤 목적으로 어떻게 사용할 지 생각하며, 사용될 기능이나 기술을 새롭게 배우고 고민하며 추가해나가는 부분이 알찼다.
• 개발 중에 일어난 문제에 대하여 트러블 슈팅을 진행했고 이를 공식 문서화하며 기록한 점은 이어나가면 좋을 것 같다.

Problem

1. 프로젝트 첫 날, 프로젝트를 계획하며 단방향 거래 방식에서 양방향 거래 방식으로 변경하면서 기능의 흐름에 대한 팀원별로 이해가 어긋남을 발견하였다. 핵심 기능과 객체 관계등을 서로 다르게 이해하였고 이로 인해 개발 진행 과정에서 혼선이 발생하였다. 이를 유저워크플로우를 따라가며 핵심 기능과 객체 관계등을 보다 더 정확하게 정의, 분기를 나눠서 세밀한 부분까지 유저의 입장에서 사용성을 예상하며 정리해나갔다. 앞으로 있을 프로젝트 진행에서는 프로젝트 기획 단계에서 적극적으로 서로 질문해가며 한 단계, 한 산출물마다 꼼꼼히 설계를 해야 한다는 것을 느꼈다.

2. 계속해서 개발 중 프로젝트를 하던 중 강사님께서 프로젝트 기획 점검을 진행하셨고, 많은 부분에서 부족한 부분이 있음을 발견하였다. 프로젝트 문서와 컨벤션을 정립하지 않았고 팀원간에 프로젝트 현재 진행도와 의사결정이 서로 공유가 잘 되지 않았다. 또 개발 계획이나 구현 계획에 정확한 가이드나 지침도 없어서 예상치 못한 상황 발생 시 대응에 어려움이 예상됐다. 그래서 피드백 후에 현재 진행도에 맞춰 구두가 아닌 문서화에 우선순위를 두어 팀 내 문서를 재정립하고 다시 작업을 진행해나갔다. 아직 문서화가 덜 진행된 부분이 있었지만 그래도 현 상황 진행도가 어떠한 지, 이어서 어떻게 진행을 해야 할 지 맞추어나가는 시간을 가지니 앞으로 해야할 것이 뚜렷이 보였다.

Try

• 이번 프로젝트는 처음 진행하는 백엔드 협업 프로젝트기도 해서 빠듯한 개발 일정에 기능 구현과 개발만 쫓기듯이 진행한 것 같다. 다음 프로젝트는 개발과 함께 이슈 추적/관리를 하며 중간중간 회고도 진행하고 코드/커밋/PR 컨벤션, 전체적인 WBS를 정하고 개발을 시작하는 게 좋을 것 같다.

소감

이번 프로젝트에서 가장 한 것이 없는 것 같다..ㅜㅜ 수업시간에 배웠던 기능을 왜 적용해야 하고 어떻게 적용해야하는지 철저하게 복습하지 않은 탓인 것 같다. 때문에 반복적인 CRUD 코드 구현과 좀 더 클린한 코드 작성에만 신경이 더 쓰인 것 같다.

더욱더 개발에 AI를 적극적으로 활용은 하되 그러한 코드나 기능이 어떻게 동작하는지 왜 그것이어야만 하는지 꼭 꼼꼼히 따져보며 개발을 해나가야겠다.

이번 프로젝트에서는 이미지를 AI가 검색할 수 있는 데이터로 만드는 과정에 집중하였다. 특히 업로드된 이미지를 Supabase Storage에 저장하고, 이미지 크기를 조정한 뒤 AI에게 이미지 설명을 생성하게 하고, 그 설명과 이미지 URL을 Document의 metadata에 저장하여 VectorStore에 넣는 과정을 실습하였다. 또한 이후 검색 결과를 화면에 전달하기 위해 ImageRagSearchResult DTO를 사용하는 구조도 학습하였다.

이미지 RAG에서 이미지 자체를 그대로 저장하지 않는 이유

이번 프로젝트에서 가장 중요한 흐름은 다음과 같다.

사용자가 이미지 업로드
        ↓
MultipartFile
        ↓
Supabase Storage에 실제 이미지 저장
        ↓
이미지 크기 조정
        ↓
AI가 이미지 설명 생성
        ↓
Document 생성
        ↓
caption + publicUrl을 metadata에 저장
        ↓
imageVectorStore.add()

즉, 이번 프로젝트에서는 단순히 이미지를 저장하는 것이 아니라 이미지를 검색할 수 있는 형태의 정보로 변환하는 과정을 구현하였다. ImageService에서는 실제 이미지 저장과 이미지 설명 생성, Document 생성, VectorStore 저장까지 하나의 흐름으로 연결되어 있다.

ImageService의 구성

먼저 이번 프로젝트의 핵심 서비스인 ImageService를 살펴보았다.

@Service
@RequiredArgsConstructor
public class ImageService {

    @Qualifier("googleGenAiChatModel")
    private final ChatModel chatModel;

    @Qualifier("imageVectorStore")
    private final VectorStore imageVectorStore;

    // Supabase Storage
    private final S3Template s3Template;
}

여기에서 중요한 것은 세 가지 의존성이다.

특히 VectorStore에 @Qualifier("imageVectorStore")를 사용한 것이 중요하다.

이번 프로젝트에서는 이미지 검색을 위한 별도의 VectorStore Bean인 imageVectorStore를 사용하고 있기 때문에 해당 이름을 지정하여 주입받는다. ImageRagConfig에서는 이 Bean을 PgVectorStore 기반으로 생성하고, 테이블 이름을 image_vector_store로 지정하였다.

이미지 업로드 Controller

이미지 업로드 요청은 ImageController에서 받는다.

@PostMapping
public String uploadImage(@RequestParam MultipartFile file,
                          RedirectAttributes redirectAttributes) {

    System.out.println("file = " + file);
    System.out.println(file.getContentType());
    System.out.println(file.getOriginalFilename());

    redirectAttributes.addFlashAttribute("msg", "파일 업로드 완료");

    String answer = imageService.explain(file);

    redirectAttributes.addFlashAttribute("answer", answer);

    return "redirect:/image";
}

사용자가 이미지 파일을 업로드하면

@RequestParam MultipartFile file

을 통해 파일을 전달받는다.

그리고 Controller에서는 직접 파일을 저장하거나 AI 분석을 수행하지 않고

String answer = imageService.explain(file);

을 호출한다.

즉 역할은 다음과 같이 나뉜다.

Controller에서 모든 작업을 처리하지 않고 Service에 실제 작업을 위임하는 구조를 확인할 수 있었다.

UUID로 이미지 파일명 생성

이미지 저장 과정에서 다음 코드가 사용된다.

String uuid = java.util.UUID.randomUUID().toString();

String extension =
        StringUtils.getFilenameExtension(
                file.getOriginalFilename());

String newFilename =
        uuid + "." + extension;

사용자가 업로드한 파일 이름이

cat.jpg

라고 하더라도 그대로 저장하지 않는다.

먼저

UUID.randomUUID().toString()

으로 UUID를 생성한다.

그리고

StringUtils.getFilenameExtension(
    file.getOriginalFilename()
)

으로 원본 파일의 확장자를 가져온다.

결과적으로

UUID + "." + jpg

형태의 새로운 파일명이 만들어진다.

예를 들어 개념적으로

cat.jpg
        ↓
UUID 생성
        ↓
550e8400-....jpg

와 같은 형태가 된다.

이렇게 하면 서로 다른 사용자가 같은 이름의 파일을 업로드하더라도 저장 파일명이 겹칠 가능성을 줄일 수 있다.

Supabase Storage에 이미지 저장

파일명까지 만들었으면 실제 저장을 수행한다.

S3Resource result =
        s3Template.upload(
                "rag",
                newFilename,
                file.getInputStream()
        );

여기서 새롭게 학습한 부분은 S3Template이다.

프로젝트에서는 Supabase Storage를 S3 방식으로 다루고 있다.

S3Template
   ↓
Supabase Storage
   ↓
rag 버킷
   ↓
newFilename

"rag"는 업로드할 Storage 영역이고,

newFilename은 실제 저장할 파일 이름이다.

file.getInputStream()은 업로드된 파일의 내용을 읽어 Storage로 전달한다.

따라서 이 코드 한 줄을 통해

사용자가 업로드한 MultipartFile → Supabase Storage

로 실제 파일이 이동한다.

S3Resource를 이용한 저장 결과 확인

업로드 결과는

S3Resource result

로 받는다.

그리고

System.out.println("result = " + result.getURL());

을 통해 업로드된 파일의 URL을 확인한다.

즉 S3Template이 단순히 저장만 하는 것이 아니라 저장 결과를 S3Resource로 반환하기 때문에 저장된 리소스의 URL을 가져올 수 있다는 점을 학습하였다.

Public URL 생성

그런데 코드에서는 result.getURL()을 그대로 사용하는 것이 아니라 URL을 변경한다.

String publicUrl = result.getURL().toString()
        .replace(
                "storage.supabase.co/storage/v1/s3",
                "supabase.co/storage/v1/object/public"
        );

프로젝트 코드에는 실제 URL 형태가 주석으로 작성되어 있다.

https://...storage.supabase.co/storage/v1/s3/rag/movie.jpg

를

https://...supabase.co/storage/v1/object/public/rag/movie.jpg

형태로 변환한다.

즉,

S3 방식의 URL
       ↓
public URL 형태로 변환

하는 것이다.

이렇게 만들어진 publicUrl은 나중에 Document의 metadata에 저장된다.

이미지 크기 조정

이미지를 AI에게 전달하기 전에 다음 코드를 실행한다.

byte[] resized = resize(
        file.getInputStream(),
        file.getContentType().split("/")[1],
        512,
        512
);

여기에서 새롭게 사용한 것이 Thumbnailator이다.

public byte[] resize(
        InputStream inputStream,
        String format,
        int width,
        int height
) {

    ByteArrayOutputStream outputStream =
            new ByteArrayOutputStream();

    try {
        Thumbnails.of(inputStream)
                .size(width, height)
                .outputFormat(format)
                .toOutputStream(outputStream);

    } catch (Exception e) {
        throw new IllegalArgumentException(e);
    }

    return outputStream.toByteArray();
}

처리 흐름은 다음과 같다.

InputStream
    ↓
Thumbnailator
    ↓
512 × 512
    ↓
ByteArrayOutputStream
    ↓
byte[]

Thumbnails.of(inputStream)으로 원본 이미지 스트림을 받고,

.size(width, height)

를 통해 크기를 설정한다.

이번 코드에서는 실제 호출할 때

512 × 512

를 전달한다.

마지막에는

outputStream.toByteArray()

를 이용하여 처리된 이미지를 byte[]로 반환한다.

Media 객체로 이미지 전달

크기가 조정된 이미지는 AI가 처리할 수 있도록 Media로 만든다.

Media media = new Media(
        MimeTypeUtils.parseMimeType(
                file.getContentType()
        ),
        new ByteArrayResource(resized)
);

여기서 중요한 것은 이미지 데이터가

byte[]

에서

ByteArrayResource

를 거쳐

Media

가 된다는 것이다.

즉,

MultipartFile
      ↓
InputStream
      ↓
resize()
      ↓
byte[]
      ↓
ByteArrayResource
      ↓
Media

의 흐름으로 이미지가 AI에게 전달할 수 있는 형태로 변환된다.

AI에게 이미지 설명 생성

이번 프로젝트의 핵심 부분이다.

String caption = chatClient.prompt()
        .user(u -> u
                .text("첨부한 이미지를 해석해주세요")
                .media(media))
        .call()
        .content();

여기서 중요한 것은 단순히 문자열을 AI에게 전달하는 것이 아니라

.media(media)

를 통해 실제 이미지 데이터를 함께 전달한다는 것이다.

결과는

String caption

으로 받는다.

즉

이미지
  ↓
AI
  ↓
이미지 설명
  ↓
caption

이라는 과정이 만들어진다.

그리고 이 caption이 이후 이미지 검색의 핵심 데이터가 된다.

Document에 이미지 설명과 URL 저장

AI가 만들어낸 caption과 Storage의 publicUrl을 Document에 저장한다.

Document document = Document.builder()
        .text(caption)
        .metadata("caption", caption)
        .metadata("publicUrl", publicUrl)
        .build();

text

이미지 설명

을 Document의 본문으로 사용한다.

metadata

추가적인 정보를 저장한다.

이번 프로젝트에서는

caption
publicUrl

을 metadata로 저장하였다.

결과적으로 하나의 Document는 개념적으로

Document

├── text
│    └── 이미지 설명
│
└── metadata
     ├── caption
     └── publicUrl

구조를 가지게 된다.

VectorStore에 Document 저장

Document를 만들었으면

imageVectorStore.add(
        List.of(document)
);

를 실행한다.

이 부분을 통해 이미지가 단순한 파일 저장으로 끝나는 것이 아니라 검색 가능한 데이터로 등록된다.

전체적으로 보면

이미지 업로드
      ↓
Storage 저장
      ↓
이미지 설명 생성
      ↓
Document 생성
      ↓
VectorStore 저장

이다.

이것이 이번 프로젝트에서 구현한 이미지 RAG 데이터 적재 과정이다.

ImageRagSearchResult DTO

검색 결과를 화면에서 사용하기 위해 별도의 DTO를 사용한다.

public record ImageRagSearchResult(
        String caption,
        String publicUrl
) {
}

이 DTO는 검색 결과에서 필요한

이미지 설명

+

이미지 URL

만 전달하기 위한 객체이다.

즉 VectorStore 내부의 Document를 그대로 Controller나 View에 전달하는 것이 아니라, 화면에서 필요한 데이터만 DTO로 변환한다.

이미지 검색 과정

이미지를 저장했다면 다음으로 저장된 이미지 중에서 질문과 관련된 이미지를 검색할 수 있다.

프로젝트에서는 다음 코드를 사용하였다.

SearchRequest request = SearchRequest.builder()
        .query(query)
        .topK(3)
        .similarityThreshold(0.5)
        .build();

List<Document> results =
        imageVectorStore.similaritySearch(request);

이번 Part에서는 검색 원리 자체보다는 저장한 Document를 어떻게 검색 요청으로 연결하는지에 초점을 맞추었다.

여기서

.query(query)

는 사용자가 입력한 검색어이고,

.topK(3)

은 최대 3개의 결과를 가져오도록 설정한다.

.similarityThreshold(0.5)

는 유사도가 0.5 이상인 결과를 대상으로 한다.

검색 결과는

List<Document> results

로 반환된다.

Document의 metadata를 검색 결과 DTO로 변환

검색된 Document에서 metadata를 가져온다.

return results.stream().map(
        d -> {
            Object caption =
                    d.getMetadata().get("caption");

            Object publicUrl =
                    d.getMetadata().get("publicUrl");

            return new ImageRagSearchResult(
                    caption.toString(),
                    publicUrl.toString()
            );
        }
).toList();

검색 결과인 Document에는 우리가 앞에서 저장했던

caption
publicUrl

이 들어 있다.

그래서

d.getMetadata().get("caption")

으로 이미지 설명을 가져오고,

d.getMetadata().get("publicUrl")

로 실제 이미지 URL을 가져온다.

그리고 이를

new ImageRagSearchResult(...)

로 변환한다.

최종적으로 화면에는

검색된 이미지의 설명

+

실제 이미지 URL

만 전달된다.

이미지 RAG 전체 흐름

이번 Part에서 가장 중요하게 기억해야 할 흐름이다.

[이미지 업로드]

MultipartFile
      ↓
UUID 파일명 생성
      ↓
S3Template
      ↓
Supabase Storage
      ↓
publicUrl 생성
      ↓
이미지 resize
      ↓
Media 생성
      ↓
AI 이미지 분석
      ↓
caption 생성
      ↓
Document 생성
      ↓
caption + publicUrl metadata 저장
      ↓
imageVectorStore.add()
      ↓
VectorStore

그리고 검색할 때는

사용자 query
      ↓
SearchRequest
      ↓
imageVectorStore.similaritySearch()
      ↓
Document 검색
      ↓
metadata에서 caption / publicUrl 추출
      ↓
ImageRagSearchResult
      ↓
화면 출력

으로 이어진다.

새롭게 배운 내용

핵심 코드

이번 프로젝트에서 가장 중요한 코드는 다음 흐름으로 기억하면 된다.

① 이미지 저장

String uuid = java.util.UUID.randomUUID().toString();

String extension =
        StringUtils.getFilenameExtension(
                file.getOriginalFilename());

String newFilename = uuid + "." + extension;

S3Resource result =
        s3Template.upload(
                "rag",
                newFilename,
                file.getInputStream());

↓

② Public URL 생성

String publicUrl = result.getURL().toString()
        .replace(
                "storage.supabase.co/storage/v1/s3",
                "supabase.co/storage/v1/object/public");

↓

③ 이미지 전처리

byte[] resized = resize(
        file.getInputStream(),
        file.getContentType().split("/")[1],
        512,
        512);

↓

④ AI 이미지 설명 생성

String caption = chatClient.prompt()
        .user(u -> u
                .text("첨부한 이미지를 해석해주세요")
                .media(media))
        .call()
        .content();

↓

⑤ RAG Document 생성

Document document = Document.builder()
        .text(caption)
        .metadata("caption", caption)
        .metadata("publicUrl", publicUrl)
        .build();

↓

⑥ VectorStore 저장

imageVectorStore.add(List.of(document));

이 6단계를 이해하면 이번 프로젝트에서 이미지가 어떻게 RAG 데이터로 변환되는지를 이해한 것이다.

Part 1-1 핵심 정리

이번 프로젝트에서 새롭게 배운 가장 중요한 부분은 이미지를 단순히 저장하는 것과 AI가 검색할 수 있는 데이터로 만드는 것은 다르다는 것이었다.

이미지는 먼저 S3Template을 통해 Supabase Storage에 저장하고, Thumbnailator를 이용해 AI에 전달할 이미지를 처리한다. 이후 Media를 통해 AI에게 이미지를 전달하여 caption을 생성하고, 이 설명과 publicUrl을 Document의 metadata에 저장한다. 마지막으로 imageVectorStore.add()를 통해 Document를 VectorStore에 저장함으로써 이후 검색할 수 있는 이미지 RAG 데이터가 만들어진다.

즉 이번 Part의 핵심은

이미지 → 저장 → 전처리 → AI 설명 → Document + Metadata → VectorStore

라는 하나의 파이프라인을 이해하는 것이다.

이번 프로젝트에서는 조회 성능을 향상시키기 위한 JPA 조회 전략과 Repository 설계 방식을 학습하였다. 특히 FetchType.LAZY, @EntityGraph를 이용하여 N+1 문제를 해결하는 방법을 익혔으며, Repository를 인터페이스로 추상화하여 Service 계층이 구현체에 의존하지 않도록 설계하였다.

또한 Controller부터 View까지의 전체 요청 흐름을 정리하면서 Spring MVC와 JPA가 어떻게 함께 동작하는지 이해할 수 있었다.

FetchType.LAZY

MovieEntity와 MovieImageEntity는 연관관계를 가지고 있지만, 영화를 조회할 때마다 항상 이미지가 필요한 것은 아니다.

@OneToMany(
        mappedBy = "movie",
        fetch = FetchType.LAZY
)
private List<MovieImageEntity> images;

FetchType.LAZY는 연관된 데이터를 실제로 사용할 때 조회하는 방식이다.

예를 들어

MovieEntity movie =
        movieRepository.findById(id).get();

를 실행하면 처음에는

Movie

↓

title

price

까지만 조회된다.

이미지는 아직 조회되지 않는다.

이미지가 필요한 순간

movie.getImages();

을 호출하면 그때 SQL이 실행되어 이미지를 조회한다.

즉

Movie 조회

↓

MovieEntity 생성

↓

movie.getImages()

↓

Image 조회

순서로 동작한다.

LAZY를 사용하는 이유

만약 영화를 100개 조회한다고 가정해 보자.

모든 영화의 이미지를 항상 함께 가져온다면

Movie 100개

↓

Image 500개

까지 한 번에 메모리에 올라오게 된다.

하지만 목록 화면에서는 영화 제목만 필요한 경우도 있다.

그래서 필요하지 않은 데이터를 미리 조회하지 않기 위해 LAZY를 사용한다.

이를 통해 불필요한 메모리 사용을 줄이고 조회 성능을 향상시킬 수 있다.

N+1 문제

LAZY를 사용하면 새로운 문제가 발생한다.

예를 들어

List<MovieEntity> movies =
        movieRepository.findAll();

을 실행한다.

첫 번째 SQL은

SELECT *
FROM movie;

이다.

하지만

movie.getImages();

를 호출할 때마다

SELECT *
FROM movie_image
WHERE movie_id = ?;

가 반복 실행된다.

Movie가 100개라면

Movie 조회

1번

+

Image 조회

100번

=

101번 SQL 실행

이 된다.

이 현상을

N+1 문제라고 한다.

EntityGraph를 이용한 해결

이번 프로젝트에서는 N+1 문제를 해결하기 위해

@EntityGraph를 사용하였다.

@EntityGraph(attributePaths = "images")
List<MovieEntity> findAll();

@EntityGraph를 사용하면

Movie를 조회하는 순간 Image도 함께 조회한다.

즉

Movie 조회

+

Image 조회

↓

한 번의 SQL 실행

이 된다.

SQL은 내부적으로

SELECT *

FROM movie

LEFT JOIN movie_image

와 유사한 방식으로 실행된다.

즉

Movie와 Image를 한 번에 가져오기 때문에 N+1 문제가 발생하지 않는다.

Repository 추상화

이번 프로젝트에서는 Service가 JpaRepository를 직접 사용하지 않았다.

public interface MovieRepository {

    MovieEntity save(MovieEntity movie);

    List<MovieEntity> findAll();

}

실제로 데이터를 저장하는 구현체는

MovieRepository

↓

MovieRepositoryImpl

↓

JpaRepository

이다.

Service는

private final MovieRepository movieRepository;

만 알고 있다.

즉 인터페이스에만 의존한다.

Repository를 추상화한 이유

현재는 JPA를 사용하지만 나중에

JPA

↓

MyBatis

로 변경할 수도 있다.

Service는

movieRepository.findAll();

만 사용하고 있으므로 구현체만 교체하면 된다.

즉 변경에 유연한 구조를 만들기 위해 Repository를 추상화하였다.

학습한 내용

느낀 점

이번 프로젝트를 통해 단순히 파일을 업로드하는 기능을 구현하는 것보다, 객체지향적인 설계와 JPA의 동작 원리를 이해하는 것이 훨씬 중요하다는 점을 느꼈다. MultipartFile을 UploadFile과 MovieImageEntity로 분리하여 관리하고, FileStore 인터페이스를 이용해 Local과 S3 저장 방식을 자유롭게 교체할 수 있도록 설계하면서 다형성과 의존성 역전 원칙(DIP) 이 실제 프로젝트에서 어떻게 활용되는지 경험할 수 있었다.

또한 OneToMany, ManyToOne, Cascade, orphanRemoval, Dirty Checking, FetchType.LAZY, EntityGraph를 함께 학습하면서 JPA가 단순히 SQL을 대신 실행하는 기술이 아니라 객체의 생명주기와 연관관계를 관리하고 조회 성능까지 고려하는 ORM 프레임워크라는 점을 이해하게 되었다. 앞으로도 기능 구현에만 집중하기보다 확장성과 유지보수성을 고려한 설계와 성능 최적화 방법을 함께 고민하며 개발해야겠다고 느꼈다.

이번 프로젝트에서는 MovieEntity와 MovieImageEntity 사이의 연관관계를 설계하고, JPA가 객체를 어떻게 관리하는지에 대해 학습하였다.

특히 OneToMany와 ManyToOne 관계, Cascade, orphanRemoval, BaseEntity를 이용한 Auditing, 영속성 컨텍스트(Persistence Context) 와 Dirty Checking을 이해하면서 JPA가 단순한 ORM이 아니라 객체의 생명주기를 관리하는 프레임워크라는 점을 알게 되었다.

MovieEntity와 MovieImageEntity를 분리한 이유

영화 하나에는 여러 장의 이미지가 존재한다.

예를 들어

인사이드 아웃2

↓

포스터

↓

스틸컷1

↓

스틸컷2

처럼 하나의 영화가 여러 이미지를 가진다.

그래서 하나의 Entity에

private String image;

를 두는 것이 아니라

MovieEntity와 MovieImageEntity를 분리하였다.

MovieEntity

@OneToMany(
        mappedBy = "movie",
        cascade = CascadeType.ALL,
        orphanRemoval = true
)
private List<MovieImageEntity> images = new ArrayList<>();

@OneToMany

Movie 하나가

Image 여러 개를 가진다는 의미이다.

mappedBy

mappedBy = "movie"

는 MovieImageEntity에 있는

private MovieEntity movie;

필드를 기준으로 관계를 관리하겠다는 의미이다.

Movie가 외래키(FK)를 직접 관리하지 않는다.

DB에서는 MovieImage가

movie_id

를 가지고 있다.

List< MovieImageEntity >

MovieEntity는

이미지 한 개가 아니라

여러 개를 관리한다.

그래서 List< MovieImageEntity >

를 사용한다.

MovieImageEntity

@ManyToOne(fetch = FetchType.LAZY)

@JoinColumn(name = "movie_id")

private MovieEntity movie;

MovieImage 입장에서 보면

이미지 하나는 반드시 하나의 영화에 속한다.

즉

MovieImage

↓

Movie

관계이다.

그래서

@ManyToOne

을 사용한다.

@JoinColumn

@JoinColumn(name = "movie_id")

는

DB의

movie_id

컬럼과 연결된다.

예를 들어

Movie 테이블

MovieImage 테이블

처럼 저장된다.

연관관계 편의 메서드

프로젝트에는

public void addImage(MovieImageEntity image){

    images.add(image);

    image.setMovie(this);

}

메서드가 존재한다.

많은 사람들이

images.add(image);

만 하면 된다고 생각한다.

하지만 MovieImage도 자신이 어느 Movie에 속하는지 알아야 한다.

그래서

Movie

↓

Image 추가

────────────

Image

↓

Movie 지정

두 작업을 동시에 수행해야 한다.

이를 연관관계 편의 메서드라고 한다.

Cascade

cascade = CascadeType.ALL

Cascade는

부모(Entity)의 작업을

자식(Entity)에게 전파하는 기능이다.

예를 들어

movieRepository.save(movie);

를 호출하면

실제로는

Movie 저장

↓

Image1 저장

↓

Image2 저장

↓

Image3 저장

가 자동으로 수행된다.

즉 Movie만 저장해도 Image까지 함께 저장된다.

orphanRemoval

orphanRemoval = true

Movie는 그대로 두고

Image 하나만 삭제한다고 가정하자.

movie.getImages().remove(image);

그러면

Collection에서는 제거되지만

DB에서는 삭제되지 않을 수도 있다.

하지만

orphanRemoval = true

를 사용하면

List.remove()

↓

JPA 감지

↓

DELETE 실행

이 된다.

즉 부모와 관계가 끊어진 자식 Entity를 자동으로 삭제한다.

BaseEntity

모든 Entity에는

생성일

수정일

이 필요하다.

그래서

공통 기능을

BaseEntity에서 관리하였다.

@MappedSuperclass

@EntityListeners(AuditingEntityListener.class)

public abstract class BaseEntity {

    @CreatedDate

    private LocalDateTime createdAt;

    @LastModifiedDate

    private LocalDateTime updatedAt;

}

MovieEntity는

extends BaseEntity

만 하면

createdAt

updatedAt

를 자동으로 상속받는다.

중복 코드를 줄일 수 있는 구조이다.

JPA Auditing

Auditing은 생성일과 수정일을 자동으로 관리하는 기능이다.

Movie 저장

↓

createdAt 자동 저장

Movie 수정

↓

updatedAt 자동 수정

개발자가 직접 시간을 넣지 않아도 된다.

영속성 컨텍스트(Persistence Context)

영속성 컨텍스트는

JPA가 Entity를 관리하는 공간이다.

객체를 조회하면

Database

↓

MovieEntity 생성

↓

Persistence Context 저장

↓

Service 반환

이 된다.

즉 조회한 Entity는 JPA가 계속 관리하고 있다.

Dirty Checking

예를 들어

MovieEntity movie =
        repository.findById(id).get();

movie.changeTitle("새 제목");

save()를 호출하지 않았다.

그런데도 DB가 수정된다.

왜일까?

Movie 조회

↓

Persistence Context 저장

↓

title 변경

↓

Transaction 종료

↓

기존 값과 비교

↓

UPDATE 실행

이 과정을 Dirty Checking이라고 한다.

즉 JPA는 Entity가 변경되었는지를 자동으로 감지한다.

@Transactional의 역할

Dirty Checking은 Transaction 안에서만 동작한다.

그래서 Service에는

@Transactional

이 존재한다.

Transaction이 끝나는 순간 JPA가 변경 여부를 확인하고 UPDATE를 실행한다.

학습한 내용

이번 프로젝트에서는 사용자가 입력한 영화 정보와 이미지 파일을 하나의 요청으로 받아 데이터베이스에 저장하는 기능을 구현하였다. 이전 프로젝트에서는 문자열과 숫자만 저장하였다면, 이번에는 MultipartFile을 이용한 파일 업로드, DTO를 Entity로 변환, MovieEntity와 MovieImageEntity의 연관관계 생성까지 함께 처리하였다.

특히 Service 계층에서 파일 저장과 비즈니스 로직을 담당하도록 구현하여 Controller는 요청 처리만 수행하고 Service는 실제 기능을 수행하는 계층 분리 구조를 학습할 수 있었다.

Controller의 역할

Controller는 사용자의 요청을 받아 Service에게 전달하는 역할만 수행한다.

@PostMapping("/new")
public String createMovie(

        @Valid MovieDTO request,

        BindingResult bindingResult

) {

    if (bindingResult.hasErrors()) {

        return "movies/new";

    }

    movieService.insert(request);

    return "redirect:/movies";

}

@Valid MovieDTO

사용자가 입력한 제목, 이미지를 MovieDTO로 전달받는다.

브라우저

↓

MovieDTO 생성

↓

Validation

순서로 진행된다.

BindingResult

Validation이 실패하면 MovieService는 실행되지 않는다.

예를 들어

제목 없음

↓

Validation 실패

↓

등록 화면 유지

가 된다.

즉 사용자 입력 오류는 Exception이 아니라 BindingResult가 처리한다.

movieService.insert()

Controller는 파일 저장도 하지 않고 Entity도 만들지 않는다.

MovieDTO

↓

MovieService

에게 전달한다.

이것이 Controller의 역할이다.

MovieEntity 생성

MovieEntity movie =

        MovieEntity.builder()

                .title(dto.title())

                .price(dto.price())

                .build();

MovieDTO는

사용자가 입력한 데이터이다.

DB에는 Entity를 저장해야 한다.

그래서

MovieDTO

↓

MovieEntity

로 변환한다.

MovieEntity는 아직 DB에 저장되지 않은 상태이다.

MultipartFile 반복 처리

사용자는 이미지를 여러 장 업로드할 수 있다.

따라서

for (MultipartFile image : dto.images()) {

    ...

}

를 사용한다.

예를 들어

포스터

스틸컷1

스틸컷2

를 선택했다면

반복문은

1번째 파일

↓

2번째 파일

↓

3번째 파일

순으로 처리한다.

MovieImageEntity 생성

파일을 저장한 후에는 이미지 정보를 Entity로 만든다.

MovieImageEntity imageEntity =

        MovieImageEntity.builder()

                .originalName(upload.originalName())

                .storedName(upload.storedName())

                .build();

MovieImageEntity는 파일 자체를 저장하는 것이 아니라 파일 정보를 저장한다.

즉 DB에는

movie.jpg

82ab73.jpg

만 저장된다.

실제 파일은 Local 또는 S3에 존재한다.

Movie와 Image 연결

이미지를 Movie와 연결해야 한다.

movie.addImage(imageEntity);

이 메서드는 단순히

images.add(imageEntity);

만 하지 않는다.

내부에서는

images.add(imageEntity);

imageEntity.setMovie(this);

도 함께 수행한다.

즉

Movie

↓

Image 추가

────────────

Image

↓

Movie 지정

를 동시에 처리한다.

이를 연관관계 편의 메서드 라고 한다.

Repository 저장

이미지 연결이 끝나면 Movie를 저장한다.

movieRepository.save(movie);

Movie만 저장하지만 Cascade가 설정되어 있으므로

Movie 저장

↓

Image1 저장

↓

Image2 저장

↓

Image3 저장

가 자동으로 수행된다.

개발자는 Movie만 저장하면 된다.

Controller와 Service 역할 비교

Controller는

"무엇을 할지"

결정하고

Service는

"어떻게 할지"

구현한다.

DTO → Entity 변환 과정

이번 프로젝트에서는

다음과 같은 흐름으로 객체가 변경된다.

사용자 입력

↓

MovieDTO

↓

MovieEntity

↓

Database

이미지는

MultipartFile

↓

UploadFile

↓

MovieImageEntity

↓

Database

라는 별도의 흐름을 가진다.

즉 영화 정보와 이미지 정보는 각각 Entity로 변환된 뒤 연관관계를 맺어 저장된다.

Validation과 Service의 관계

Service는 Validation을 직접 수행하지 않는다.

Validation은 Controller에서 끝난다.

Validation 성공

↓

MovieService 실행

즉 Service는 항상 정상적인 데이터가 들어온다고 가정하고 비즈니스 로직만 수행한다.

학습한 내용

이번 프로젝트에서는 기존 영화 CRUD 프로젝트를 확장하여 이미지 파일 업로드 기능을 구현하였다. 단순히 영화 제목과 가격 같은 텍스트 데이터만 처리하는 것이 아니라, 사용자가 여러 장의 이미지를 선택하여 업로드하고 이를 서버(Local) 또는 S3와 같은 외부 저장소에 저장하는 구조를 학습하였다.

특히 MultipartFile을 이용한 파일 처리, UploadFile을 활용한 파일 정보 관리, FileStore 인터페이스를 이용한 저장소 추상화, StorageProperty를 통한 설정 관리 등을 구현하면서 객체지향적인 파일 저장 구조를 이해할 수 있었다.

MultipartFile이란?

기존 프로젝트에서는 사용자가 입력한 값이 모두 문자열이나 숫자였다.

제목

가격

하지만 이번 프로젝트에서는 사용자가 파일도 함께 업로드한다.

제목

이미지1

이미지2

이미지3

Spring에서는 업로드된 파일을 MultipartFile 객체로 변환하여 전달한다.

즉,

브라우저

↓

파일 선택

↓

HTTP Multipart Request

↓

MultipartFile 객체 생성

↓

Controller

과정으로 동작한다.

MovieDTO를 이용한 입력 데이터 관리

사용자가 입력한 데이터는 MovieDTO에서 관리하였다.

public record MovieDTO(

        @NotBlank String title,

        @NotEmpty List<MultipartFile> images

) {
}

@NotBlank String title

영화 제목은 반드시 입력되어야 한다.

• null 불가
• 빈 문자열 불가
• 공백만 입력 불가

Validation을 통해 잘못된 입력을 사전에 방지한다.

List<MultipartFile> images

파일 하나가 아니라

포스터

스틸컷1

스틸컷2

처럼 여러 장을 업로드할 수 있으므로

MultipartFile image;

가 아니라

List<MultipartFile> images;

를 사용하였다.

MultipartFile 안에는 무엇이 들어 있을까?

MultipartFile은 단순히 파일만 저장하는 객체가 아니다.

다음과 같은 정보를 포함한다.

UploadFile DTO

파일을 저장한 뒤에는 MultipartFile 자체를 계속 사용할 필요가 없다.

public record UploadFile(

        String originalName,

        String storedName

) {

    public String url() {

        return "/upload/%s".formatted(storedName);

    }

}

파일을 저장하면 두 가지 이름이 존재한다.

예를 들어 사용자가

cat.jpg

를 업로드하였다.

실제로 서버에는

2fa39fd8-8ab2.jpg

처럼 저장된다.

따라서

를 모두 저장해야 한다.

originalName을 저장하는 이유

사용자는

cat.jpg

를 보고 싶다.

다운로드 화면에서도

cat.jpg

라고 표시되어야 한다.

storedName을 저장하는 이유

서버에서는 파일명이 중복되면 안 된다.

예를 들어

두 사용자가 모두

cat.jpg

를 업로드하면 기존 파일이 덮어써질 수 있다.

그래서 UUID를 이용하여

cat.jpg

↓

7fd81e2d.jpg

처럼 저장한다.

이를 통해 파일명 충돌을 방지할 수 있다.

URL 생성 메서드

UploadFile에는

public String url() {
    return "/upload/%s".formatted(storedName);
}

도 존재한다.

이 메서드는 저장된 파일명을 이용하여 브라우저에서 접근 가능한 URL을 생성한다.

예를 들어 storedName이

abc123.jpg

이면

/upload/abc123.jpg

를 반환한다.

화면에서는 이 URL을 <img> 태그의 src 속성으로 사용하여 이미지를 출력한다.

FileStore 인터페이스

public interface FileStore {

    UploadFile storeFile(MultipartFile image);

}

MovieService는 파일을 어떻게 저장하는지 알 필요가 없다.

UploadFile upload = fileStore.storeFile(image);

만 호출한다.

실제로 저장하는 방법은

FileStore

↓

LocalFileStore 또는 S3FileStore가 담당한다.

즉, MovieService는 인터페이스에만 의존한다.

LocalFileStore 구현

LocalFileStore는 프로젝트 내부 폴더에 파일을 저장한다.

@Component
public class LocalFileStore implements FileStore {

    private final Path uploadPath =
            Path.of("src/main/resources/static/upload");

}

업로드된 파일은

src

↓

main

↓

resources

↓

static

↓

upload

폴더에 저장된다.

브라우저는

/upload/파일명

으로 접근할 수 있다.

파일 저장 과정

LocalFileStore 내부에서는

다음 순서로 동작한다.

MultipartFile

↓

비어있는지 검사

↓

확장자 검사

↓

UUID 생성

↓

파일 저장

↓

UploadFile 반환

즉, MovieService는 파일이 어디에 저장되는지 전혀 알지 못한다.

StorageProperty를 이용한 설정 관리

S3 정보를 관리하기 위해 StorageProperty를 사용하였다.

@ConfigurationProperties(prefix = "app.storage")

@Validated

public record StorageProperty(

        String bucket,

        String endpoint,

        String region,

        String access_key,

        String secret_key

) {
}

기존에는

@Value(...)

를 여러 번 사용해야 했다.

하지만 ConfigurationProperties를 사용하면

application.yml

↓

app.storage

↓

StorageProperty

로 자동 매핑된다.

따라서 S3 관련 설정을 하나의 객체로 관리할 수 있다.

FileStore를 인터페이스로 만든 이유

현재는

LocalFileStore

를 사용할 수도 있고

S3FileStore

를 사용할 수도 있다.

MovieService는

private final FileStore fileStore;

만 알고 있다.

따라서

나중에

AWS S3

↓

Azure Blob

↓

Google Cloud Storage

등으로 변경하더라도 MovieService는 전혀 수정하지 않아도 된다.

이것이 다형성과 DIP(의존성 역전 원칙) 의 대표적인 예시이다.

학습한 내용

이번 프로젝트에서는 Spring Data JPA를 활용한 영화 CRUD 기능 구현과 Spring MVC의 예외 처리 구조를 함께 학습하였다. JpaRepository와 Service 계층을 이용하여 조회, 등록, 수정, 삭제 기능을 계층적으로 구현하고, BaseEntity와 JPA Auditing을 통해 생성일과 수정일을 자동으로 관리하는 방법을 익혔다. 또한 Optional.orElseThrow()를 활용한 안전한 데이터 조회와 Custom Exception, @ExceptionHandler, @ControllerAdvice, @ResponseStatus를 이용한 예외 처리 구조를 구현하여, 상황에 맞는 404, 409, 500, 5xx 오류 페이지를 사용자에게 제공하는 방법도 학습하였다. 이를 통해 계층형 아키텍처를 활용한 유지보수성 높은 구조와 사용자 친화적인 예외 처리 방식을 이해할 수 있었다.

Spring Data JPA와 JpaRepository

이번 프로젝트에서는 영화 정보를 관리하기 위해 JpaRepository를 사용하였다.

public interface MovieJpaRepository
        extends JpaRepository<MovieEntity, Long> {
}

(프로젝트 Repository 구조)

JpaRepository는 Spring Data JPA가 제공하는 인터페이스로, 기본적인 CRUD 기능을 미리 구현해 놓은 저장소이다.

즉, 개발자가 직접 SQL을 작성하지 않아도 다음과 같은 기능을 바로 사용할 수 있다.

예를 들어

movieJpaRepository.findAll();

을 호출하면 내부적으로는 다음과 같은 SQL과 유사한 쿼리가 자동으로 실행된다.

SELECT *
FROM movie;

즉, 개발자는 SQL을 직접 작성하지 않고도 객체를 이용하여 데이터를 조회할 수 있다는 점을 학습하였다.

Repository 추상화

이번 프로젝트에서는 Repository를 단순히 JpaRepository만 사용하는 것이 아니라

MovieRepository

↓

MovieRepositoryImpl

↓

MovieJpaRepository

와 같이 여러 계층으로 분리하였다.

Controller는

private final MovieRepository movieRepository;

만 알고 있다.

실제로 데이터베이스에 접근하는 코드는

MovieRepositoryImpl

이 담당한다.

즉,

Controller

↓

MovieRepository (인터페이스)

↓

MovieRepositoryImpl

↓

JpaRepository

↓

Database

순서로 동작한다.

Repository를 분리하는 이유

예를 들어 현재는 JPA를 사용하지만

나중에 JPA에서 MyBatis로 변경해야 하는 상황이 발생할 수도 있다.

이 경우

Controller는

movieRepository.findAll();

만 사용하고 있기 때문에

구현체만 변경하면 된다.

즉,

구현보다 인터페이스에 의존하도록 설계하는 객체지향 원칙(DIP) 을 적용한 구조라는 점을 이해하였다.

Service 계층의 역할

이번 프로젝트에서는 Controller가 Repository를 직접 호출하지 않고 Service를 거쳐 데이터를 처리하였다.

전체 구조는 다음과 같다.

사용자 요청

↓

Controller

↓

MovieService

↓

Repository

↓

Database

Service를 사용하는 이유

Controller의 역할은

• 요청 받기
• 화면 반환

이다.

반면

Service는

• 비즈니스 로직 수행
• 데이터 가공
• 여러 Repository 호출

등을 담당한다.

예를 들어 영화 등록 기능은

사용자 입력

↓

Validation 성공

↓

MovieFormDTO

↓

Entity 변환

↓

Service

↓

Repository

↓

Database 저장

순서로 동작한다.

이처럼 Controller와 Service의 역할을 분리하면 각 계층이 하나의 책임만 가지게 되어 코드의 가독성과 유지보수성이 향상된다는 점을 학습하였다.

Optional.orElseThrow()

영화를 조회할 때는

findById(id)

.orElseThrow(...)

방식을 사용하였다.

findById()는

결과가 없을 수도 있기 때문에

Optional<MovieEntity>를 반환한다.

예를 들어

ID = 1

↓

데이터 존재

↓

MovieEntity 반환

하지만

ID = 999

↓

데이터 없음

↓

Optional.empty()

가 된다.

이때

.orElseThrow(...)

를 사용하면

Optional.empty()

↓

NoMovieException 발생

하도록 구현할 수 있다.

이를 통해 null을 직접 비교하지 않고도 안전하게 예외를 처리하는 방법을 학습하였다.

Custom Exception(NoMovieException)

이번 프로젝트에서는 영화가 존재하지 않을 경우를 처리하기 위해 Custom Exception을 생성하였다.

@ResponseStatus(HttpStatus.NOT_FOUND)
public class NoMovieException extends RuntimeException {

    public NoMovieException(Long movieId) {
        super("해당 영화를 찾을 수 없습니다. id=" + movieId);
    }

}

일반적으로 영화를 조회할 때

ID = 1

이라면

정상적으로 데이터를 반환한다.

하지만

ID = 999

처럼 존재하지 않는 ID를 요청하면

MovieEntity가 존재하지 않는다.

이때

.orElseThrow(
    () -> new NoMovieException(id)
);

를 호출하면

동작 과정은 다음과 같다.

사용자 요청

↓

findById()

↓

Optional.empty()

↓

NoMovieException 발생

↓

Spring Exception 처리

이처럼 비즈니스 상황에 맞는 예외를 직접 정의하여 사용할 수 있다는 점을 학습하였다.

@ResponseStatus

Custom Exception에는

@ResponseStatus(HttpStatus.NOT_FOUND)

을 지정하였다.

@ResponseStatus는 예외가 발생했을 때 어떤 HTTP 상태 코드를 반환할지 지정하는 Annotation이다.

예를 들어

NoMovieException

이 발생하면

Spring은 자동으로

HTTP 404

를 반환한다.

예외 발생

↓

@ResponseStatus 확인

↓

404 상태 코드 설정

↓

Error Page 이동

이를 통해 예외와 HTTP 상태 코드를 자연스럽게 연결하는 방법을 이해하였다.

@ExceptionHandler를 이용한 예외 처리

이번 프로젝트에서는 특정 Controller 내부에서 발생한 예외를 처리하기 위해 @ExceptionHandler를 사용할 수 있다는 점도 학습하였다.

예를 들어

@ExceptionHandler(NoMovieException.class)
public String handleMovieException() {

    return "errors/404";

}

과 같은 형태로 사용할 수 있다.

Controller 실행

↓

NoMovieException 발생

↓

@ExceptionHandler 탐색

↓

404 화면 반환

즉, Controller 내부에서 발생한 특정 예외를 원하는 화면으로 연결할 수 있다.

@ControllerAdvice를 이용한 공통 예외 처리

프로젝트에서는 예외 처리를 하나의 Controller마다 작성하는 것이 아니라 공통으로 관리하는 구조도 함께 학습하였다.

동작 과정은 다음과 같다.

MovieController

↓

MemberController

↓

OrderController

↓

ControllerAdvice

↓

공통 Exception 처리

예를 들어

모든 Controller에서

NoMovieException

이 발생할 수 있다.

각 Controller마다

@ExceptionHandler(...)

를 작성하면

같은 코드가 계속 반복된다.

그래서

@ControllerAdvice를 사용하면

모든 Controller

↓

예외 발생

↓

ControllerAdvice

↓

공통 처리

구조가 된다.

이를 통해 예외 처리 코드도 중복 없이 관리할 수 있다는 점을 학습하였다.

Error Page 구성

이번 프로젝트에서는 다양한 HTTP 상태 코드에 맞는 Error Page도 구현하였다.

프로젝트에는

• 404.html

• 409.html

• 500.html

• 5xx.html

등이 존재하였다.

404 Error

404는

존재하지 않는 데이터

또는

잘못된 URL

을 의미한다.

예를 들어

/movies/999

를 요청하면

Movie 없음

↓

404

이 발생한다.

409 Error

409는

Conflict

상태이다.

예를 들어

중복된 영화 등록처럼

비즈니스 규칙이 충돌하는 상황에서 사용할 수 있다.

500 Error

500은

예상하지 못한 서버 오류를 의미한다.

예를 들어

NullPointerException

SQLException

등이 발생하면

500 오류가 반환된다.

5xx Error

5xx는

500번대 오류를 공통으로 처리하는 페이지이다.

특정 상태 코드에 해당하는 페이지가 없으면

5xx.html이 대신 출력된다.

이를 통해 사용자에게 시스템 오류가 발생했다는 사실을 친절하게 안내할 수 있다는 점을 이해하였다.

DispatcherServlet 이후 Exception 처리 흐름

이번 프로젝트에서는 예외가 발생했을 때 Spring MVC 내부에서 어떤 순서로 처리되는지도 학습하였다.

전체 흐름은 다음과 같다.

브라우저 요청

↓

DispatcherServlet

↓

Controller

↓

Service

↓

Repository

↓

예외 발생

↓

ExceptionResolver

↓

@ControllerAdvice

↓

Error Controller

↓

Error Page

↓

브라우저

즉,

예외가 발생하더라도 바로 프로그램이 종료되는 것이 아니라

Spring MVC가 예외를 가로채어 적절한 화면을 반환한다는 점을 이해하였다.

SSR(Server Side Rendering)에서의 예외 처리

이번 프로젝트는 Thymeleaf를 사용하는 SSR(Server Side Rendering) 방식이다.

따라서

예외가 발생하면

JSON이 아니라

HTML을 반환한다.

예를 들어

영화 조회

↓

NoMovieException

↓

404.html 생성

↓

브라우저 출력

처럼 동작한다.

REST API였다면

{
  "status":404,
  "message":"Movie Not Found"
}

를 반환했겠지만

SSR에서는 사용자에게 보여 줄 HTML 페이지를 반환한다는 차이를 이해하였다.

BindingResult와 Exception의 차이

이번 프로젝트를 진행하면서 Validation과 Exception의 차이도 명확하게 이해할 수 있었다.

예를 들어

사용자가

가격 = -1000

을 입력하면

Validation 실패이므로

BindingResult가 처리한다.

반면

없는 영화 조회

는

Validation 문제가 아니라

비즈니스 예외이므로

NoMovieException이 발생한다.

즉,

Validation과 Exception은 서로 다른 목적을 가진다는 점을 이해하였다.

직면한 문제와 해결 과정

느낀 점

이번 프로젝트를 통해 기능 구현뿐만 아니라 유지보수성과 사용자 경험을 고려한 설계가 매우 중요하다는 점을 배울 수 있었다. Thymeleaf Fragment를 활용하여 공통 화면을 재사용하여 코드의 중복을 줄이는 방법을 익혔다.

특히 예외 처리 부분에서는 Optional.orElseThrow()를 이용한 안전한 조회, Custom Exception과 @ControllerAdvice를 활용한 공통 예외 처리, 그리고 @ResponseStatus와 오류 페이지를 이용한 사용자 친화적인 오류 응답을 구현하면서 정상적인 기능 구현뿐 아니라 예외 상황까지 고려하는 것이 완성도 높은 애플리케이션을 만드는 중요한 요소라는 점을 배울 수 있었다. 이번 프로젝트를 통해 Spring MVC의 요청 처리부터 예외 처리까지 전체 흐름을 하나의 구조로 이해할 수 있었고, 앞으로도 재사용성과 확장성을 고려한 설계와 사용자 중심의 예외 처리를 지속적으로 적용해야겠다는 점을 느꼈다.

이번 프로젝트에서는 기존의 Spring MVC 프로젝트를 확장하여 Thymeleaf Fragment를 활용한 화면 재사용, 공통 Layout 구성, DTO를 활용한 화면과 도메인 객체의 분리, 그리고 영화(Movie) CRUD 화면 구성을 학습하였다.

이전에는 HTML 페이지마다 <head>, <nav>, 오류 출력 영역 등을 각각 작성하였다면, 이번 프로젝트에서는 이러한 공통 요소를 Fragment로 분리하여 필요한 화면에서 재사용하는 구조를 구현하였다.

또한 사용자가 입력하는 데이터를 처리하기 위한 MovieFormDTO와 화면에 출력하기 위한 MovieViewDTO를 분리하여 사용하면서 DTO를 목적에 따라 구분하는 방법도 학습하였다.

이를 통해 화면 구성의 중복을 줄이고, 유지보수성을 높이며, Controller와 View가 역할에 맞게 동작하는 구조를 이해할 수 있었다.

Fragment(프래그먼트)의 개념

이번 프로젝트에서 가장 먼저 새롭게 학습한 내용은 Fragment이다.

Fragment란 여러 HTML 화면에서 반복적으로 사용되는 부분을 하나의 파일로 분리하여 재사용하는 기능이다.

예를 들어 모든 페이지에는 다음과 같은 요소가 반복된다.

• <head>
• Navigation Bar
• Footer
• Validation Error
• 공통 CSS
• 공통 JavaScript

기존 방식이라면

list.html

↓

head 작성

↓

nav 작성

↓

body 작성

──────────────

detail.html

↓

head 작성

↓

nav 작성

↓

body 작성

처럼 모든 HTML에 같은 내용을 복사해야 한다.

이 방식은 Navigation 메뉴 하나를 수정하더라도 모든 HTML을 수정해야 한다.

이번 프로젝트에서는 이러한 문제를 해결하기 위해 Fragment를 사용하였다.

fragments

↓

head.html

↓

nav.html

↓

errorMsg.html

↓

각 화면에서 참조

즉, 공통 화면을 한 곳에서 관리하고 필요한 화면에서 불러오는 구조를 학습하였다.

th:fragment를 이용한 화면 조각 정의

Fragment는 th:fragment를 이용하여 정의하였다.

예를 들어 Navigation을 하나의 Fragment로 정의하면

<nav th:fragment="mainNav">

    <a th:href="@{/movies}">
        영화 목록
    </a>

</nav>

(프로젝트 구조와 동일한 형태)

th:fragment="mainNav"은

현재 HTML의 <nav> 태그를

mainNav라는 이름의 재사용 가능한 조각으로 등록한다.

Spring Boot 실행

↓

fragments/nav.html

↓

mainNav 등록

↓

다른 HTML에서 참조 가능

이렇게 등록된 Fragment는

목록 화면

↓

상세 화면

↓

등록 화면

↓

수정 화면

모두 동일하게 사용할 수 있다.

즉, Navigation을 한 번만 작성하면 프로젝트 전체에서 재사용할 수 있다는 점을 학습하였다.

th:replace와 th:insert의 차이

Fragment를 사용하는 방법에는 여러 가지가 있지만 이번 프로젝트에서는 th:replace와 th:insert의 차이를 함께 학습하였다.

예를 들어

<div
th:replace="~{fragments/nav :: mainNav}">
</div>

과

<div
th:insert="~{fragments/nav :: mainNav}">
</div>

은 결과가 서로 다르다.

th:replace

div 태그

↓

삭제

↓

Fragment로 교체

즉,

원래 <div>는 사라지고

Fragment 자체가 그 위치를 대신한다.

예를 들면

<div
th:replace="...">
</div>

↓

렌더링 후

<nav>

...

</nav>

가 된다.

th:insert

반대로

div 태그

↓

유지

↓

안쪽에 Fragment 삽입

된다.

렌더링 후에는

<div>

<nav>

...

</nav>

</div>

구조가 된다.

프로젝트에서는 불필요한 태그를 남기지 않기 위해 대부분 th:replace를 사용하는 것이 적합하다는 점을 이해하였다.

공통 Head Fragment 구성

모든 화면에는

• title
• charset
• css
• javascript

등이 반복된다.

이번 프로젝트에서는 이를 하나의 head.html Fragment로 분리하였다.

기존에는 head 태그 부분이 모든 html에 반복되었다.

이 head 태그 부분을 분리하여 다른 html이 분리된 Fragment를 쓰는 구조로 변경하였다.

이렇게 하면

CSS를 하나 추가할 때

모든 HTML을 수정하는 것이 아니라

head.html 하나만 수정하면 된다.

이를 통해 중복 코드를 줄이는 가장 좋은 방법은 공통 부분을 분리하는 것이라는 점을 배웠다.

Navigation Fragment 구성

프로젝트의 Navigation 역시 Fragment로 관리하였다.

Navigation에는

• 영화 목록

• 영화 등록

등 공통 메뉴가 존재하였다.

동작 구조는

사용자 요청

↓

HTML

↓

th:replace

↓

nav Fragment

↓

최종 HTML 생성

이다.

따라서 메뉴를 수정하더라도

Navigation Fragment 하나만 수정하면

모든 화면에 자동으로 반영된다.

이는 유지보수성과 확장성을 크게 높여 주는 구조라는 점을 이해하였다.

Validation 오류 출력 Fragment(errorMsg)

이번 프로젝트에서는 Validation 오류도 Fragment로 분리하였다.

기존에는

모든 Form마다 오류 출력 블록을 계속 작성하였다.

이번 프로젝트에서는 errorMsg Fragment를 등록 화면과 수정 화면에 재사용하는 구조를 사용하였다.

이렇게 하면 Validation을 사용하는 Form이 늘어나더라도

동일한 Fragment를 가져다 사용할 수 있다.

즉, 오류 출력 방식이 변경되더라도 Fragment 하나만 수정하면 된다는 점을 학습하였다.

Layout을 이용한 화면 구성

이번 프로젝트에서는 화면을

• Header

• Navigation

• Main

• Footer

처럼 여러 부분으로 나누어 구성하였다.

전체 구조는 다음과 같다.

Head Fragment

↓

Navigation Fragment

↓

Body

↓

Footer

각 화면은 필요한 Body만 작성하고

공통 부분은 Fragment에서 가져온다.

예를 들어

Movie List

↓

Head

↓

Nav

↓

Movie Table

────────────

Movie Detail

↓

Head

↓

Nav

↓

Movie Info

처럼 Body만 달라지고

나머지는 모두 동일하게 유지된다.

이를 통해 레이아웃과 실제 화면을 분리하는 구조를 학습하였다.

Validation과 Fragment의 연결

등록 화면에서는

Validation이 실패하면

MovieFormDTO

↓

BindingResult

↓

Error Fragment

↓

오류 출력

순서로 동작한다.

즉

Controller는

오류를 생성하기만 하고

실제 화면 출력은 Fragment가 담당한다.

이를 통해 Controller와 View의 역할을 명확하게 분리하는 구조를 이해하였다.

이번 프로젝트에서는 단순히 데이터를 저장하고 조회하는 기능을 구현하는 것을 넘어, 프로젝트에서 반복적으로 사용되는 공통 기능을 효율적으로 관리하는 방법을 학습하였다.

특히 Spring Boot의 @ConfigurationProperties를 활용하여 설정 파일의 값을 객체로 관리하는 방법과, JPA Auditing을 이용하여 엔티티의 생성 시간과 수정 시간을 자동으로 관리하는 기능을 구현하였다.

또한 Repository를 인터페이스와 구현체로 분리하는 구조와 @Transactional을 이용한 트랜잭션 관리까지 학습하면서, 프로젝트의 유지보수성과 확장성을 고려한 설계 방법을 이해할 수 있었다.

@ConfigurationProperties를 이용한 설정 객체 관리

Spring Boot에서는 데이터베이스 정보, API Key, 프로젝트 이름 등 다양한 설정을 application.yml에 작성한다.

이러한 설정을 하나의 객체로 관리하기 위해 @ConfigurationProperties를 사용하였다.

@ConfigurationProperties(prefix = "app")
@Validated
public record AppProperties(
        @NotBlank String name,
        @NotBlank String version
) {
}

prefix = "app"은 설정 파일에서 app으로 시작하는 값을 하나의 객체에 자동으로 연결(Binding)한다.

예를 들어 설정 파일에 다음과 같이 작성되어 있다고 가정하자.

app:
  name: Library
  version: 1.0

애플리케이션이 실행되면 Spring Boot는

application.yml

↓

app.name

↓

AppProperties.name

────────────

app.version

↓

AppProperties.version

순서로 값을 읽어 객체를 생성한다.

따라서 Controller나 Service에서는

appProperties.name()

처럼 메서드를 호출하여 설정 값을 사용할 수 있다.

객체로 관리하는 이유

설정이 하나만 있다면

@Value("${app.name}")

만으로도 충분하다.

하지만

app:
  name:
  version:
  company:
  description:
  email:

처럼 설정이 많아질 경우

각각 @Value를 사용하는 것보다 하나의 객체로 관리하는 것이 훨씬 편리하다.

@Validated를 이용한 설정 검증

이번 프로젝트에서는 설정 객체에도 Validation을 적용하였다.

@Validated

일반적으로 Validation은 사용자의 입력(Form)에만 사용하는 것으로 생각하기 쉽다.

하지만 설정 파일도 잘못 작성될 수 있다.

예를 들어

app:
  name:

처럼 프로젝트 이름이 비어 있다면

애플리케이션이 정상적으로 동작하지 않을 수도 있다.

이때

@NotBlank

를 적용하면

Spring Boot가 실행되는 순간

application.yml

↓

Validation

↓

실패

↓

Application 종료

가 된다.

즉, 잘못된 설정으로 서버가 실행되는 것을 미리 방지할 수 있다는 점을 새롭게 학습하였다.

@ConfigurationPropertiesScan의 역할

설정 객체를 자동으로 등록하기 위해

프로젝트에서는

@ConfigurationPropertiesScan

을 사용하였다.

Spring Boot가 시작되면

@SpringBootApplication

↓

@ConfigurationPropertiesScan

↓

@ConfigurationProperties 검색

↓

Bean 등록

↓

DI 가능

순서로 동작한다.

만약 이 Annotation이 없다면

AppProperties가 Bean으로 등록되지 않아

@RequiredArgsConstructor

에서 주입받을 수 없다.

따라서 설정 객체를 자동으로 검색하여 Spring Container에 등록하는 역할을 수행한다는 점을 이해하였다.

BaseEntity를 이용한 공통 필드 관리

프로젝트에는 모든 Entity가 공통으로 사용하는 정보를 관리하기 위한 BaseEntity가 존재하였다.

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

    @CreatedDate
    private LocalDateTime createdAt;

    @LastModifiedDate
    private LocalDateTime updatedAt;

}

대부분의 데이터는

• 생성일
• 수정일

정보를 가지고 있다.

예를 들어

처럼 관리된다.

만약 모든 Entity에

private LocalDateTime createdAt;
private LocalDateTime updatedAt;

를 직접 작성한다면

중복 코드가 계속 발생한다.

그래서 공통 기능을 BaseEntity에 작성하고

public class BookEntity
        extends BaseEntity

처럼 상속하여 사용하였다.

JPA Auditing

이번 프로젝트에서 새롭게 학습한 기능 중 하나는 JPA Auditing이었다.

Auditing은 Entity가 생성되거나 수정되는 시간을 자동으로 기록하는 기능이다.

프로젝트에서는

@EnableJpaAuditing

을 활성화하였다.

사용자가

새 책 등록

을 수행하면

내부적으로

Book 저장

↓

Persist

↓

@CreatedDate

↓

현재 시간 저장

이 자동으로 수행된다.

예를 들어

2026-08-06 10:30

에 저장했다면

createdAt도

2026-08-06 10:30

으로 자동 저장된다.

개발자가

entity.setCreatedAt(...)

를 직접 호출하지 않아도 된다.

@LastModifiedDate

책 정보를 수정하면

가격 변경

↓

UPDATE

↓

@LastModifiedDate

↓

현재 시간 저장

이 자동으로 수행된다.

예를 들어

기존 데이터가

이었다면

가격 수정 후에는

처럼 수정일만 변경된다.

이를 통해 변경 이력을 자동으로 관리할 수 있다는 점을 학습하였다.

Repository 추상화

이번 프로젝트에서는 Repository를 인터페이스와 구현체로 분리하였다.

BookRepository

↓

BookRepositoryImpl

↓

JpaRepository

Controller는

BookRepository

만 알고 있다.

실제 구현은

BookRepositoryImpl

이 담당한다.

이 구조를 사용하면

나중에

JPA

↓

MyBatis

로 변경하더라도

Controller와 Service는 수정하지 않아도 된다.

즉,

구현보다 인터페이스에 의존하는 구조를 만들 수 있다는 점을 이해하였다.

@Transactional의 역할

Service에서는

@Transactional

과

@Transactional(readOnly = true)

를 함께 사용하였다.

일반 Transaction

@Transactional

은

• INSERT
• UPDATE
• DELETE

처럼 데이터를 변경하는 작업에서 사용한다.

동작 과정은

Transaction 시작

↓

DB 작업

↓

성공

↓

Commit

────────────

실패

↓

Rollback

이다.

즉, 여러 작업 중 하나라도 실패하면 이전 상태로 되돌려 데이터의 일관성을 유지한다.

readOnly = true

조회 기능에서는

@Transactional(readOnly = true)

를 사용하였다.

조회는 데이터를 변경하지 않기 때문에 JPA는 변경 사항을 추적할 필요가 없다.

따라서 Dirty Checking과 같은 작업을 생략하여 불필요한 비용을 줄일 수 있다.

예를 들어

도서 목록 조회

↓

SELECT

↓

readOnly Transaction

↓

조회만 수행

처럼 동작하며, 읽기 전용 작업에 적합하다.

학습한 내용

느낀 점

이번 프로젝트를 통해 애플리케이션은 단순히 기능을 구현하는 것뿐만 아니라, 반복되는 기능을 공통화하고 설정을 체계적으로 관리하는 설계가 중요하다는 점을 배울 수 있었다. 특히 BaseEntity와 JPA Auditing을 활용하여 생성일과 수정일을 자동으로 관리하는 기능을 구현하면서 중복 코드를 줄이는 방법을 익혔고, @ConfigurationProperties를 통해 설정을 객체로 관리함으로써 유지보수성과 안정성을 높일 수 있다는 점을 이해하였다. 또한 Repository를 인터페이스와 구현체로 분리하는 구조와 @Transactional을 통한 트랜잭션 관리 방식을 학습하면서 객체지향적인 설계와 데이터의 일관성을 유지하는 방법을 함께 배울 수 있었다.

이번 프로젝트에서는 사용자가 입력한 데이터를 데이터베이스에 저장하기 전에 올바른 값인지 검증(Validation) 하는 방법을 학습하였다. 단순히 Controller에서 데이터를 받아 저장하는 것이 아니라, Bean Validation을 이용하여 입력값의 형식을 검사하고, 검증에 실패했을 경우 사용자에게 오류 메시지를 보여 주면서 다시 입력할 수 있도록 구현하였다.

또한 @Valid, @Validated, BindingResult, Validation Group, Thymeleaf의 오류 출력 기능을 함께 사용하면서 사용자가 잘못된 데이터를 입력했을 때 서버와 화면이 어떻게 동작하는지를 이해할 수 있었다.

실제 웹 서비스에서는 회원가입, 로그인, 상품 등록, 게시글 작성과 같이 거의 모든 입력 화면에서 Validation이 사용되므로 이번 프로젝트를 통해 Spring Validation의 전체 흐름을 익힐 수 있었다.

Validation(데이터 검증)이 필요한 이유

웹 애플리케이션에서는 사용자가 항상 올바른 값만 입력한다고 보장할 수 없다.

예를 들어 책 등록 화면이 있다고 가정해 보자.

사용자가 다음과 같이 입력할 수도 있다.

또는

이러한 값이 그대로 저장된다면

• 데이터의 신뢰성이 떨어지고
• 화면에서 오류가 발생하거나
• 비즈니스 로직이 정상적으로 동작하지 않을 수 있다.

그래서 데이터를 저장하기 전에 반드시 검증을 수행해야 한다.

전체 흐름은 다음과 같다.

사용자 입력

↓

Controller

↓

Validation

↓

성공

↓

DB 저장

──────────────

실패

↓

오류 메시지 출력

↓

입력 화면 유지

이번 프로젝트에서는 이러한 과정을 Spring Validation이 자동으로 처리하도록 구현하였다.

Bean Validation Annotation 이해

데이터 검증은 DTO에서 Annotation을 이용하여 정의하였다.

@NotBlank
@Size(min = 1, max = 50, message = "{Size.bookForm.title2}")
private String title;

@NotNull
@PositiveOrZero
@Max(value = 1_000_000)
private Integer price;

Spring Validation은 DTO에 선언된 Annotation을 읽어서 자동으로 검증을 수행한다.

예를 들어

@NotBlank
private String title;

은

제목이

""

또는

"     "

처럼 공백이면

검증에 실패한다.

@NotBlank

문자열이

• null
• ""
• 공백

모두 허용하지 않는다.

예를 들어

회원가입의

• 이름
• 아이디
• 제목

등에 자주 사용된다.

@NotEmpty

@NotEmpty
private String author;

@NotEmpty는

빈 문자열은 허용하지 않지만

공백은 허용한다.

예를 들어

따라서 일반적인 사용자 이름에는 @NotBlank가 더 적합한 경우가 많다.

@NotNull

@NotNull
private Integer price;

null 값만 허용하지 않는다.

예를 들어

즉

숫자 자체는 허용하지만

값이 존재해야 한다.

@PositiveOrZero

@PositiveOrZero

0 이상만 허용한다.

예를 들어

책 가격이 음수가 되는 상황을 방지할 수 있다.

@Max

@Max(1_000_000)

100만원 이하만 허용한다.

예를 들어

비즈니스 규칙을 Annotation 하나로 표현할 수 있다는 점을 학습하였다.

@Valid를 이용한 자동 검증

Controller에서는

@PostMapping("/new")
public String createBook(

@Valid
@ModelAttribute("bookForm")
BookFormDTO bookFormDTO,

BindingResult bindingResult
)

사용자가 등록 버튼을 누르면

Spring은 먼저

Form 데이터

↓

BookFormDTO 생성

↓

@Valid

↓

Validation 수행

을 실행한다.

예를 들어

사용자가

제목

↓

(공백)

을 입력하면

@NotBlank가 실패한다.

그러면

@NotBlank 실패

↓

BindingResult 저장

↓

Controller 실행

이 된다.

즉

Controller가 직접

if(title == null)

처럼 검사하지 않아도

Spring Validation이 자동으로 검증을 수행한다.

BindingResult의 역할

Validation이 끝난 후

검증 결과는

BindingResult에 저장된다.

if(bindingResult.hasErrors()){

return "form";

}

BindingResult는

Validation 과정에서 발생한 오류들을 저장하는 객체이다.

예를 들어

사용자가

제목

↓

공백

을 입력하면

BindingResult 안에는

가 저장된다.

Controller에서는

bindingResult.hasErrors()

만 호출하면

오류가 있는지 쉽게 확인할 수 있다.

왜 BindingResult가 바로 뒤에 와야 하는가?

@Valid BookFormDTO dto,

BindingResult bindingResult

처럼

바로 뒤에 작성해야 한다.

만약

@Valid BookFormDTO dto,

Model model,

BindingResult bindingResult

처럼 작성하면

Spring은 Validation 결과를 BindingResult에 저장하지 못한다.

그래서 Validation 예외가 발생하여

400 오류가 발생할 수도 있다.

따라서 BindingResult는 검증 대상 객체 바로 다음에 위치해야 한다는 점을 이해하였다.

Thymeleaf와 Validation 연동

Validation 오류는

Thymeleaf에서 바로 출력할 수 있었다.

<input th:field="*{title}">

<p
th:if="${#fields.hasErrors('title')}"
th:errors="*{title}">
</p>

사용자가

제목

↓

공백

을 입력하면

Spring은 BindingResult에 오류를 저장한다.

Thymeleaf는

BindingResult

↓

#fields

↓

title Error

↓

th:errors

↓

화면 출력

순서로 오류를 출력한다.

예를 들어

화면에는

제목은 반드시 입력해야 합니다.

가 자동으로 출력된다.

즉

Controller가

model.addAttribute("error", ...)

를 작성하지 않아도

BindingResult와 Thymeleaf가 자동으로 연결되어 오류를 보여준다.

전역 오류(Global Error)

필드 하나가 아니라

객체 전체를 검사해야 하는 경우도 있다.

이번 프로젝트에서는

bindingResult.reject(

"author.noKimjava",

"김자바는 등록할 수 없습니다"

);

를 사용하였다.

예를 들어

제목

↓

김자바

또는

저자

↓

김자바

인 경우

필드 하나의 문제가 아니라

비즈니스 규칙 자체를 위반한 것이다.

그래서

BookFormDTO

↓

전체 검사

↓

Global Error

를 생성하였다.

Thymeleaf에서는

<div th:if="${#fields.hasGlobalErrors()}">

<p
th:each="err : ${#fields.globalErrors()}"

th:text="${err}">
</p>

</div>

를 통해

전역 오류를 화면 상단에 출력하였다.

Validation Group을 이용한 상황별 검증

프로젝트를 진행하면서 새롭게 학습한 기능 중 하나는 Validation Group이었다.

회원가입이나 상품 등록처럼 등록(Create) 과 수정(Update) 은 입력받아야 하는 값이 서로 다른 경우가 많다.

예를 들어 책 등록 화면에서는 판매 여부(isAvailable)를 입력받지 않아도 되지만, 수정 화면에서는 판매 여부를 변경할 수 있어야 한다.

이처럼 같은 DTO를 사용하면서도 상황에 따라 다른 검증 규칙을 적용하기 위해 Validation Group을 사용하였다.

public interface Update {
}

DTO에서는 Group을 지정하여 검증을 수행하였다.

@NotNull(groups = Update.class)
private Boolean isAvailable;

Validation Group은 검증을 여러 개의 그룹으로 나누는 기능이다.

예를 들어

등록 화면에서는

이지만

수정 화면에서는

가 될 수 있다.

이 경우 Validation Group이 없다면

등록 화면에서도 판매 여부를 입력해야 하는 문제가 발생한다.

Validation Group을 적용하면

등록 요청

↓

기본 Validation만 수행

──────────────

수정 요청

↓

Update Group Validation 수행

처럼 상황에 따라 필요한 검증만 실행된다.

이를 통해 하나의 DTO를 재사용하면서도 기능에 맞는 검증을 수행할 수 있다는 점을 학습하였다.

RedirectAttributes와 PRG(Post-Redirect-Get) 패턴

책을 등록한 후에는 바로 목록 화면으로 이동하였다.

이때 RedirectAttributes를 이용하여 메시지를 전달하였다.

redirectAttributes.addFlashAttribute(
        "msg",
        "책이 등록되었습니다."
);

return "redirect:/books";

사용자가 등록 버튼을 누르면

POST /books/new

요청이 발생한다.

만약 등록이 끝난 뒤

return "index";

를 반환한다면

브라우저는 여전히 POST 요청 상태를 유지한다.

이 상태에서 사용자가 새로고침(F5)을 누르면

POST

↓

새로고침

↓

POST 재실행

↓

데이터 중복 저장

문제가 발생한다.

이러한 문제를 해결하기 위해 PRG(Post-Redirect-Get) 패턴을 사용한다.

동작 과정은 다음과 같다.

사용자 등록

↓

POST /books/new

↓

DB 저장

↓

redirect:/books

↓

GET /books

↓

목록 화면

이렇게 하면 새로고침을 하더라도 GET 요청만 다시 실행되므로 중복 등록이 발생하지 않는다.

Flash Attribute의 역할

Redirect를 수행하면 일반적인 Model 데이터는 전달되지 않는다.

따라서

redirectAttributes.addFlashAttribute(
        "msg",
        "등록 완료"
);

를 사용한다.

Flash Attribute는

Redirect 이전

↓

Flash Map 저장

↓

Redirect

↓

한 번만 사용

↓

자동 삭제

순서로 동작한다.

목록 화면에서는

<section th:if="${msg != null}">
    <p th:text="${msg}"></p>
</section>

을 통해 메시지를 출력하였다.

즉, "등록되었습니다."와 같은 알림을 한 번만 보여주고 자동으로 사라지는 기능을 구현할 수 있었다.

Query Method를 이용한 검색 기능

이번 프로젝트에서는 Spring Data JPA의 Query Method를 활용하여 검색 기능도 구현하였다.

Repository에는 다음과 같은 메서드가 정의되어 있었다.

findAllByTitleContaining(String keyword)

Spring Data JPA는 메서드 이름을 분석하여 SQL을 자동으로 생성한다.

예를 들어

findAllByTitleContaining("Java")

를 호출하면 내부적으로 다음과 같은 SQL과 유사한 쿼리가 실행된다.

SELECT *
FROM book
WHERE title LIKE '%Java%';

개발자가 직접 SQL을 작성하지 않아도 메서드 이름만으로 검색 기능을 구현할 수 있다는 점을 학습하였다.

실제 동작 과정

목록 화면에서는 검색창을 제공하였다.

<form>
    <label>
        키워드 :
        <input name="keyword">
    </label>

    <button>검색</button>
</form>

사용자가

Java

를 입력하면

브라우저

↓

GET /books?keyword=Java

↓

Controller

↓

Repository

↓

findAllByTitleContaining()

↓

DB 조회

↓

검색 결과 출력

순서로 동작한다.

이를 통해 검색 기능도 Spring MVC와 Repository가 자연스럽게 연결되어 동작한다는 점을 이해하였다.

등록 화면과 수정 화면 재사용

이번 프로젝트에서는 등록과 수정 화면을 각각 만들지 않고 하나의 form.html을 재사용하였다.

th:action="@{${bookId == null ? '/books/new' : '/books/' + bookId}}"

또한 버튼의 글자도 변경하였다.

<button
th:text="${bookId == null ? '등록' : '수정'}">
</button>

등록 화면에서는

bookId = null

이므로

POST /books/new

으로 전송된다.

반대로 수정 화면에서는

bookId = 3

이라면

POST /books/3

으로 전송된다.

버튼 역시

등록

↓

bookId 없음

──────────────

수정

↓

bookId 존재

처럼 자동으로 변경된다.

하나의 HTML을 재사용함으로써 중복 코드를 줄이고 유지보수를 쉽게 하는 방법을 학습하였다.

Validation 메시지(properties) 관리

이번 프로젝트에서는 Validation 오류 메시지를 코드에 직접 작성하지 않고 messages.properties 파일에서 관리하였다.

NotBlank.bookForm.title=책 제목을 꼭 입력해주세요
Size.bookForm.title=책 제목은 {2} 이상 {1} 이하로 입력해야합니다
Max.bookForm.price={0} 미만의 책 가격이어야 합니다

예를 들어 DTO에서

@NotBlank
private String title;

검증이 실패하면 Spring은

NotBlank.bookForm.title

이라는 키를 찾는다.

그리고

책 제목을 꼭 입력해주세요

를 읽어 사용자에게 출력한다.

또한

Size.bookForm.title2=책 제목은 {min} 이상 {max} 이하로 입력해야합니다

처럼 {min}, {max}와 같은 플레이스홀더를 사용할 수 있다.

예를 들어

@Size(min = 2, max = 30)

이라면 화면에는

책 제목은 2 이상 30 이하로 입력해야 합니다.

처럼 실제 값이 자동으로 치환되어 출력된다.

이러한 방식은 메시지를 한 곳에서 관리할 수 있기 때문에 유지보수가 쉽고, 국제화(i18n)와도 자연스럽게 연동할 수 있다는 장점이 있다.

학습한 내용

느낀 점

이번 프로젝트를 통해 Validation은 단순히 입력값을 검사하는 기능이 아니라, 사용자가 올바른 데이터를 입력하도록 돕고 애플리케이션의 데이터 무결성을 보장하는 중요한 기능이라는 점을 이해할 수 있었다. 특히 @Valid와 BindingResult를 이용한 자동 검증, Validation Group을 통한 상황별 검증, RedirectAttributes와 PRG 패턴을 활용한 중복 요청 방지, 그리고 messages.properties를 이용한 검증 메시지 관리까지 구현하면서 실제 웹 애플리케이션에서 사용자 경험과 데이터의 신뢰성을 함께 고려하는 방법을 배울 수 있었다. 또한 하나의 form.html을 등록과 수정 화면에서 함께 사용하는 구조를 구현하며 중복 코드를 줄이고 유지보수성을 높이는 설계 방식도 함께 익힐 수 있었다.

이번 프로젝트에서는 화면을 구성하는 것뿐만 아니라 Spring Boot 애플리케이션의 환경을 효율적으로 관리하는 방법을 학습하였다. 하나의 설정 파일에 모든 정보를 작성하는 것이 아니라 설정을 역할별로 분리하고, @ConfigurationProperties를 이용하여 여러 설정 값을 객체로 관리하는 방법을 익혔다.

또한 개발 환경과 운영 환경을 구분하기 위한 Profile, 동일한 타입의 Bean이 여러 개 존재할 때 사용할 Bean을 선택하는 @Primary와 @Qualifier, 그리고 사용자의 언어에 따라 다른 화면을 제공하는 국제화(i18n) 기능까지 실습하였다.

이번 프로젝트를 통해 단순히 기능을 구현하는 것을 넘어 프로젝트를 체계적으로 관리하고 확장 가능한 구조를 만드는 방법을 이해할 수 있었다.

application.yml을 이용한 설정 관리

Spring Boot에서는 데이터베이스 정보, 서버 포트, API Key와 같은 다양한 설정을 application.yml(또는 application.properties)에 작성한다.

하지만 프로젝트가 커질수록 하나의 파일에 모든 설정을 작성하면 관리가 어려워진다.

이번 프로젝트에서는 설정 파일을 목적에 따라 분리하여 관리하였다.

예를 들어

application.yml

↓

application-db.yml

↓

application-app.yml

처럼 역할에 따라 설정을 나누어 관리하였다.

이러한 방식은 프로젝트 규모가 커질수록 설정 파일을 찾기 쉽고, 환경별 설정을 관리하기에도 편리하다는 점을 학습하였다.

@ConfigurationProperties를 이용한 설정 객체 생성

설정 파일의 값을 Java 코드에서 사용할 때는 @ConfigurationProperties를 활용하였다.

@ConfigurationProperties(prefix = "app")
public record AppProperties(
        String message
) {
}

prefix = "app"은 설정 파일에서 app으로 시작하는 항목을 하나의 객체로 묶어 준다.

예를 들어 설정 파일에 다음과 같은 내용이 있다.

app:
  message: Hello Spring Boot

Spring Boot는 애플리케이션이 실행될 때

application.yml

↓

app.message

↓

AppProperties.message

순서로 값을 자동으로 바인딩한다.

따라서 Controller에서는 문자열을 직접 읽어오는 것이 아니라 객체를 통해 사용할 수 있다.

appProperties.message();

이처럼 설정 값을 하나의 객체로 관리하면 여러 설정을 체계적으로 관리할 수 있으며, 타입이 지정되기 때문에 오타나 형변환 오류도 줄일 수 있다는 점을 배웠다.

@Value를 이용한 설정값 주입

이번 프로젝트에서는 @Value도 함께 사용하였다.

@Value("${app.message}")
private String msg;

@Value는 특정 설정 값을 하나만 가져올 때 사용하는 어노테이션이다.

예를 들어

app:
  message: Hello

가 있다면

@Value("${app.message}")

를 통해 "Hello"가 주입된다.

실행 과정은 다음과 같다.

Spring 실행

↓

application.yml 읽기

↓

app.message 검색

↓

msg 변수에 저장

@Value와 @ConfigurationProperties를 함께 학습하며 이해한 점

두 방법 모두 설정 값을 읽어오는 기능을 수행하지만 사용하는 목적이 조금 다르다.

예를 들어

app:
  name: Pizza
  version: 1.0
  author: Hong
  company: SSAFY

처럼 여러 개의 설정이 존재한다면

AppProperties

하나의 객체로 관리하는 것이 훨씬 효율적이라는 점을 이해하였다.

Bean 등록과 Spring Container

Spring에서는 필요한 객체를 직접 생성하지 않고 Spring Container가 생성하고 관리한다.

이번 프로젝트에서는 @Configuration과 @Bean을 이용하여 객체를 등록하였다.

@Configuration
public class AppConfig {

    @Bean
    public HelloService helloService() {
        return new HelloService();
    }

}

(프로젝트 구조 기반)

애플리케이션이 실행되면

Spring Boot 실행

↓

@Configuration 탐색

↓

@Bean 메서드 실행

↓

객체 생성

↓

Spring Container 저장

순서로 Bean이 등록된다.

이후 Controller나 Service에서는

@RequiredArgsConstructor

또는

@Autowired

를 이용하여 필요한 Bean을 주입받는다.

이를 통해 객체 생성과 관리를 Spring이 대신 수행하는 IoC(Inversion of Control) 구조를 이해할 수 있었다.

@Primary와 @Qualifier를 이용한 Bean 선택

동일한 타입의 Bean이 여러 개 존재하면 Spring은 어떤 Bean을 주입해야 할지 결정하지 못한다.

이를 해결하기 위해 @Primary와 @Qualifier를 사용하였다.

예를 들어

PizzaService

CheesePizzaService

BulgogiPizzaService

세 개가 모두 같은 인터페이스를 구현했다고 가정하자.

이 경우

private final PizzaService pizzaService;

만 작성하면 Spring은 어떤 객체를 주입해야 하는지 알 수 없다.

@Primary

CheesePizzaService

↓

@Primary

를 지정하면

기본적으로 CheesePizzaService가 주입된다.

@Qualifier

특정 Bean을 사용하고 싶다면

@Qualifier("bulgogiPizzaService")

를 사용하여 원하는 Bean을 직접 선택할 수 있다.

Spring Profile을 이용한 환경 분리

애플리케이션은 실행 환경에 따라 서로 다른 설정이 필요하다.

예를 들어

이번 프로젝트에서는 Profile을 이용하여 이러한 환경을 구분하는 방법을 학습하였다.

Profile을 사용하면

개발 환경

↓

Dev Bean

운영 환경에서는

운영 환경

↓

Prod Bean

이 자동으로 선택된다.

덕분에 개발 환경에서는 테스트용 객체를 사용하고, 운영 환경에서는 실제 서비스를 사용하는 등 환경에 맞는 Bean을 쉽게 적용할 수 있다는 점을 이해하였다.

국제화(i18n)

이번 프로젝트에서 가장 흥미롭게 학습한 기능은 국제화(i18n) 였다.

프로젝트에는

messages.properties

messages_ko.properties

messages_en.properties

파일이 존재하였다.

Thymeleaf에서는

<h1 th:text="#{page.headline}"></h1>

처럼 작성하였다.

사용자의 브라우저 언어가

한국어라면

message_ko.properties

↓

피자 주문 시스템

영어라면

message_en.properties

↓

Pizza Order System

이 출력된다.

즉,

같은 HTML을 사용하더라도

브라우저의 Locale에 따라 자동으로 다른 언어가 출력되는 구조라는 점을 이해하였다.

MessageSource의 동작 과정

국제화 기능은 내부적으로 다음과 같은 과정으로 동작한다.

브라우저 요청

↓

Accept-Language

↓

Spring LocaleResolver

↓

MessageSource

↓

message_ko.properties

또는

message_en.properties

↓

Thymeleaf

↓

HTML 출력

예를 들어

한국 사용자가 접속하면

안녕하세요

영어 사용자라면

Hello

가 같은 HTML에서 출력된다.

이 기능을 활용하면 하나의 프로젝트로 여러 국가의 사용자를 지원할 수 있다는 점을 학습하였다.

학습한 내용

느낀 점

이번 프로젝트를 통해 애플리케이션을 개발할 때 기능 구현뿐 아니라 환경 설정과 유지보수성을 고려한 설계가 중요하다는 점을 배울 수 있었다. @ConfigurationProperties를 이용하여 설정을 객체로 관리하고, @Value를 통해 필요한 설정만 간단하게 주입하는 방법을 익히면서 프로젝트 규모에 따라 적절한 설정 관리 방법을 선택할 수 있다는 점을 이해하였다. 또한 @Primary, @Qualifier, Profile을 활용하여 실행 환경과 Bean 선택을 유연하게 제어하는 방법을 학습하였고, 국제화(i18n)를 통해 하나의 애플리케이션으로 여러 언어를 지원하는 구조를 경험하면서 실제 서비스에서 사용자의 환경에 맞춰 애플리케이션을 제공하는 방법을 이해할 수 있었다.

Thymeleaf 템플릿 엔진을 활용하여 Spring Boot에서 동적인 웹 페이지를 구성하는 방법을 학습하였다. 기존의 HTML은 화면에 고정된 내용만 출력할 수 있었지만, Thymeleaf를 이용하면 Controller에서 전달한 데이터를 화면에 출력하거나, 반복문과 조건문을 이용하여 상황에 따라 다른 화면을 생성할 수 있다.

또한 Spring MVC의 Model 객체를 이용하여 Controller와 View가 데이터를 주고받는 과정, DTO를 활용한 데이터 전달 방식, 반복문과 조건문을 활용한 동적 화면 구성, 그리고 HTML Escape를 통한 XSS 방지 기능까지 실습하면서 웹 애플리케이션의 화면이 내부적으로 어떻게 생성되는지 이해할 수 있었다.

Thymeleaf 템플릿 엔진의 역할

Thymeleaf는 Spring Boot에서 가장 많이 사용하는 서버 사이드(Server Side) 템플릿 엔진이다.

브라우저가 서버에 요청을 보내면 Controller가 필요한 데이터를 조회하고, Thymeleaf는 그 데이터를 HTML에 삽입하여 완성된 페이지를 브라우저로 전달한다.

전체 동작 과정은 다음과 같다.

브라우저 요청

↓

DispatcherServlet

↓

Controller

↓

Service

↓

Repository

↓

DB 조회

↓

Controller(Model 저장)

↓

Thymeleaf

↓

HTML 생성

↓

브라우저 출력

사용자가 최종적으로 보는 HTML은 처음부터 존재했던 것이 아니라 Controller가 전달한 데이터와 Thymeleaf가 합쳐져 새롭게 생성된 결과물이라는 점을 이해하였다.

Controller와 Model을 이용한 데이터 전달

Controller는 사용자의 요청을 처리하고, 화면에 필요한 데이터를 조회하여 View에 전달하는 역할을 수행한다.

@GetMapping
public String index(Model model) {

    model.addAttribute("msg", appProperties.message());

    model.addAttribute(
            "pizzas",
            pizzaRepository.findAll()
                    .stream()
                    .map(PizzaDTO::fromEntity)
                    .toList()
    );

    return "index";
}

사용자가

http://localhost:8080/

으로 접속하면 Spring은 가장 먼저 Controller의 index() 메서드를 실행한다.

이때 Controller는 데이터베이스에서 피자 목록을 조회하고, Model 객체에 데이터를 저장한다.

model.addAttribute("msg", "환영합니다.");
model.addAttribute("count", 5);

를 실행하면 Model 내부에는 다음과 같이 저장된다.

이후 Thymeleaf는 이 데이터를 읽어 HTML을 생성한다.

예를 들어 HTML에서

<p th:text="${msg}"></p>

<p th:text="${count}"></p>

를 작성하면 최종 HTML은

<p>환영합니다.</p>

<p>5</p>

가 된다.

즉, Model은 Controller와 View 사이에서 데이터를 전달하는 저장소 역할을 수행한다.

Model을 사용하는 이유

Model이 없다면 Controller에서 조회한 데이터를 View가 사용할 수 없다.

예를 들어

List<Pizza> pizzas = pizzaRepository.findAll();

만 실행한다면 피자 목록은 Java 메모리에만 존재한다.

HTML은 Java 변수에 직접 접근할 수 없기 때문에 화면에는 아무것도 출력되지 않는다.

그래서

model.addAttribute("pizzas", pizzas);

를 이용하여

Controller

↓

Model

↓

View

순서로 데이터를 전달한다.

Thymeleaf 표현식(Expression)

Thymeleaf는 다양한 표현식을 제공한다.

<h1 th:text="#{page.headline}"></h1>

<p th:text="${msg}"></p>

<p>[[${msg2}]]</p>

${} 표현식

${}는 Model에 저장된 데이터를 가져오는 표현식이다.

예를 들어

model.addAttribute("name", "홍길동");

를 저장하면

<p th:text="${name}"></p>

은

<p>홍길동</p>

으로 출력된다.

#{} 표현식

#{}는 국제화(MessageSource) 파일의 내용을 가져온다.

예를 들어

message.properties

page.headline=피자 주문 시스템

이 있다면

<h1 th:text="#{page.headline}"></h1>

은

피자 주문 시스템

으로 출력된다.

브라우저 언어가 영어라면

message_en.properties의 값을 출력한다.

즉, 같은 HTML이라도 사용자의 언어에 따라 다른 내용을 출력할 수 있다.

[[ ]] 표현식

[[ ]]는 Thymeleaf의 인라인 표현식이다.

기능은 ${}와 비슷하지만 HTML 태그 밖에서도 자연스럽게 사용할 수 있다.

예를 들어

<p>안녕하세요 [[${name}]] 님</p>

이라면

브라우저에는

안녕하세요 홍길동 님

으로 출력된다.

DTO를 이용한 화면 데이터 관리

프로젝트에서는 Entity를 그대로 View에 전달하지 않고 DTO를 사용하였다.

public record PizzaDTO(
        String name,
        int price
) {

    Pizza toEntity() {
        return Pizza.builder()
                .name(name)
                .price(price)
                .build();
    }

    static PizzaDTO fromEntity(Pizza pizza) {
        return new PizzaDTO(
                pizza.getName(),
                pizza.getPrice()
        );
    }
}

DTO(Data Transfer Object)는 데이터를 전달하기 위한 객체이다.

예를 들어 데이터베이스에는

가 저장되어 있다고 가정하자.

화면에서는

불고기

22000원

만 필요하다.

그렇다면

DTO는

name

price

만 가지고 있으면 된다.

즉,

Entity

↓

DTO

↓

View

순서로 데이터를 전달한다.

이를 통해 화면에는 필요한 데이터만 전달할 수 있고, Entity가 직접 노출되지 않아 보안과 유지보수 측면에서도 유리하다는 점을 이해하였다.

th:each를 이용한 반복 출력

조회한 피자 목록은 th:each를 이용하여 반복 출력하였다.

<div th:each="pizza, status : ${pizzas}">

    <code th:text="${pizza.name}"></code>

    <code th:text="${pizza.price}"></code>

</div>

Controller가

model.addAttribute(
    "pizzas",
    List.of(
        new PizzaDTO("불고기",22000),
        new PizzaDTO("치즈",18000),
        new PizzaDTO("페퍼로니",25000)
    )
);

를 전달했다고 가정하면

Thymeleaf는 내부적으로 다음과 같이 반복한다.

첫 번째 반복

pizza

↓

불고기

22000

두 번째 반복

pizza

↓

치즈

18000

세 번째 반복

pizza

↓

페퍼로니

25000

즉, HTML 요소 하나를 Collection의 크기만큼 복제하여 출력한다.

최종 브라우저에는

불고기   22000

치즈     18000

페퍼로니 25000

가 출력된다.

th:each와 status 객체를 이용한 반복 상태 관리

Thymeleaf의 th:each는 단순히 데이터를 반복해서 출력하는 기능만 제공하는 것이 아니라, 반복문의 현재 상태를 나타내는 status 객체도 함께 제공한다.

<div th:each="pizza, status : ${pizzas}">

    <span th:text="${status.count}"></span>

    <span th:text="${status.index}"></span>

    <span th:text="${status.first}"></span>

    <span th:text="${status.last}"></span>

</div>

예를 들어 Controller에서 다음과 같은 데이터를 전달했다고 가정하자.

List<PizzaDTO> pizzas = List.of(
    new PizzaDTO("불고기",22000),
    new PizzaDTO("치즈",18000),
    new PizzaDTO("페퍼로니",25000)
);

첫 번째 반복에서는

두 번째 반복에서는

세 번째 반복에서는

이처럼 status 객체는 반복문의 진행 상황을 알려주는 다양한 정보를 제공한다.

status 객체를 사용하는 이유

반복문의 현재 위치를 알 수 있기 때문에 화면을 더욱 다양하게 구성할 수 있다.

예를 들어

• 첫 번째 상품에는 "BEST" 표시
• 마지막 상품에는 "NEW" 표시
• 홀수 번째 행은 회색 배경
• 짝수 번째 행은 흰색 배경

과 같은 화면을 쉽게 구현할 수 있다.

쇼핑몰을 예로 들면

1. 아이폰 ⭐BEST

2. 갤럭시

3. 맥북

4. 아이패드 ⭐NEW

처럼 특정 순서에 따라 화면을 다르게 표현할 수 있다.

th:if와 th:unless를 이용한 조건부 출력

웹 화면에서는 모든 데이터를 항상 출력하는 것이 아니라 특정 조건에서만 보여 주어야 하는 경우가 많다.

이를 위해 Thymeleaf에서는 th:if와 th:unless를 제공한다.

<mark th:if="${status.first}">
    첫 번째 메뉴입니다.
</mark>

<mark th:unless="${status.first}">
    첫 번째 메뉴가 아닙니다.
</mark>

th:if는 조건이 참(true) 일 때만 HTML 요소를 생성한다.

예를 들어

boolean admin = true;

라면

<p th:if="${admin}">
    관리자 메뉴
</p>

은 브라우저에서

<p>관리자 메뉴</p>

로 출력된다.

반대로

boolean admin = false;

라면

브라우저에는 해당 <p> 태그 자체가 생성되지 않는다.

즉, CSS로 숨기는 것이 아니라 HTML 자체를 만들지 않는 것이다.

th:unless

th:unless는 th:if와 반대로 조건이 거짓일 때 출력된다.

예를 들어

boolean login = false;

라면

<p th:unless="${login}">
    로그인 해주세요.
</p>

는

<p>로그인 해주세요.</p>

가 출력된다.

th:switch와 th:case를 이용한 여러 조건 처리

조건이 여러 개인 경우에는 th:switch를 사용할 수 있다.

<section th:switch="${status.count}">

    <p th:case="1">첫 번째 메뉴</p>

    <p th:case="2">두 번째 메뉴</p>

    <p th:case="*">기타 메뉴</p>

</section>

Java의 switch 문과 동일한 방식으로 동작한다.

예를 들어

int level = 2;

라면

<div th:switch="${level}">

<p th:case="1">초급</p>

<p th:case="2">중급</p>

<p th:case="3">고급</p>

<p th:case="*">알 수 없음</p>

</div>

의 결과는

중급

이 된다.

*는 Java의 default와 같은 역할을 수행한다.

언제 사용하는가?

예를 들어 회원 등급이 있다면

처럼 하나의 값에 따라 여러 화면을 표현할 수 있다.

HTML Escape와 XSS 방지

이번 프로젝트에서 가장 중요하게 학습한 내용 중 하나는 HTML Escape였다.

Controller에서는 다음과 같은 문자열을 View로 전달하였다.

String data = """
<script>alert('XSS!')</script>
""";

그리고 View에서는

<p th:text="${data}"></p>

<p>[[${data}]]</p>

만약 HTML Escape가 존재하지 않는다면

브라우저는

<script>alert("XSS!")</script>

를 실행하게 된다.

그러면

사용자의 브라우저에서

⚠ alert 창 실행

이 발생한다.

이러한 공격을 XSS(Cross Site Scripting) 라고 한다.

HTML Escape가 적용되면

Thymeleaf는

<script>

를

<script>

처럼 변환하여 출력한다.

브라우저는 이것을 HTML 코드가 아닌 단순한 문자열로 인식한다.

즉,

브라우저 화면에는

<script>alert("XSS!")</script>

가 그대로 보일 뿐

실행되지는 않는다.

HTML Escape가 중요한 이유

웹 서비스에서는 사용자가 자유롭게 글을 작성하는 경우가 많다.

예를 들어

• 게시판
• 댓글
• 리뷰
• 문의 게시판

등에서 악성 사용자가

<script>
location.href='악성사이트'
</script>

를 입력한다면

Escape가 없을 경우

다른 사용자의 브라우저에서도 해당 스크립트가 실행될 수 있다.

따라서 Thymeleaf는 기본적으로 HTML Escape를 적용하여 이러한 보안 문제를 예방한다.

학습한 내용

느낀 점

Thymeleaf는 단순히 데이터를 화면에 출력하는 템플릿 엔진이 아니라, 반복문과 조건문을 활용하여 다양한 화면을 동적으로 구성하고, HTML Escape를 통해 웹 보안까지 고려한 서버 사이드 렌더링 기술이라는 점을 이해할 수 있었다. 특히 th:each와 status 객체를 활용하여 반복 상태를 제어하고, th:if와 th:switch를 이용해 조건에 따라 화면을 다르게 구성하는 방법을 실습하면서, 실제 웹 서비스에서 자주 사용되는 UI 구성 방식을 익힐 수 있었다. 또한 XSS 공격 사례를 통해 HTML Escape의 필요성을 이해하면서, 사용자 입력을 안전하게 처리하는 것이 기능 구현만큼 중요한 요소라는 점을 배울 수 있었다.

이번에는 RAG의 개념을 이해하는 것에서 나아가 Spring Boot와 Spring AI를 활용하여 실제 RAG 시스템을 구현하는 과정을 학습하였다. 단순히 AI에게 질문을 전달하는 것이 아니라 문서를 Vector Database에 저장하고, 문서를 검색하고, 검색된 결과를 AI에게 전달하여 답변을 생성하는 전체 파이프라인을 구현하였다.

특히 이번 프로젝트에서는 문서를 저장하는 과정(Ingest Pipeline) 과 질문에 대해 관련 문서를 검색하는 과정(Retrieval Pipeline) 을 직접 구현하면서 RAG 시스템이 내부적으로 어떤 단계로 동작하는지 이해할 수 있었다.

Document 객체 생성과 VectorStore 저장

RAG 시스템에서 가장 먼저 수행되는 작업은 문서를 Vector Database에 저장하는 것이다.

이를 위해 Spring AI에서는 Document 객체를 사용하였다.

public void save(String content, String category) {

    Document doc = new Document(
            content,
            Map.of(
                    "category", category,
                    "source", "manual")
    );

    vectorStore.add(List.of(doc));
}

Document는 단순한 문자열을 저장하는 객체가 아니라 텍스트와 메타데이터(Metadata)를 함께 관리하는 객체이다.

이번 프로젝트에서는 Document 생성 시 두 가지 정보를 저장하였다.

• 실제 문서 내용(content)
• 메타데이터(category, source)

예를 들어

내용

Spring Boot는...

--------------------

Metadata

category = spring

source = manual

처럼 하나의 Document 안에 저장된다.

이후

vectorStore.add(...)

를 호출하면 Spring AI가 내부적으로 다음 과정을 자동으로 수행한다.

Document

↓

Embedding Model 호출

↓

Vector 생성

↓

Vector Database 저장

즉, 개발자가 Embedding API를 직접 호출하지 않아도 VectorStore.add()만 호출하면 문서 임베딩과 저장이 자동으로 수행된다는 점을 새롭게 학습하였다.

Metadata를 함께 저장하는 이유

이번 프로젝트에서는 Document에 Metadata를 저장하였다.

Map.of(

"category", category,

"source", "manual"

)

Metadata는 문서의 부가 정보를 저장하는 영역이다.

예를 들어

Spring Boot 문서

↓

category = spring

AI 문서

↓

category = ai

처럼 카테고리를 저장할 수 있다.

나중에 검색할 때

AI 관련 문서만 검색

처럼 조건을 줄 수 있기 때문에 단순히 내용을 저장하는 것보다 훨씬 효율적인 검색이 가능하다.

실무에서는

• 작성자
• 생성일
• 문서 종류
• 권한

등도 Metadata에 저장하여 검색 조건으로 활용한다는 점도 함께 이해하였다.

Similarity Search 구현

문서를 저장한 뒤에는 질문과 가장 유사한 문서를 검색해야 한다.

public List<Document> search(String query) {

    return vectorStore.similaritySearch(

            SearchRequest.builder()

                    .query(query)

                    .topK(4)

                    .similarityThreshold(0.3)

                    .build()

    );

}

similaritySearch()는 입력한 질문을 먼저 Embedding한 뒤 저장된 모든 문서와 유사도를 계산한다.

동작 과정은 다음과 같다.

질문

↓

Embedding

↓

Vector 생성

↓

Vector DB 검색

↓

유사도 계산

↓

Top-K 반환

여기서 중요한 점은 문자열을 비교하는 것이 아니라 벡터 간의 거리(유사도) 를 비교한다는 것이다.

예를 들어

질문

Spring Boot란?

↓

검색 결과

Spring Boot 설명

92%

↓

Spring Framework 설명

88%

↓

Java 문법

35%

처럼 의미가 비슷한 문서를 찾는다.

SearchRequest의 역할

이번 프로젝트에서는 검색 조건을 객체로 관리하였다.

SearchRequest.builder()

.query(query)

.topK(4)

.similarityThreshold(0.3)

SearchRequest에는 검색 조건이 모두 포함된다.

query

검색할 질문

topK

가장 유사한 문서를 몇 개 가져올 것인지 결정한다.

예를 들어

topK = 4

이면

가장 유사한 문서 4개만 AI에게 전달된다.

similarityThreshold

최소 유사도를 의미한다.

예를 들어

0.91

0.85

0.73

0.42

0.21

이라면

Threshold가

0.3

이므로

0.21인 문서는 제외된다.

이러한 설정을 통해 AI에게 너무 관련성이 낮은 문서를 전달하지 않도록 제어할 수 있다는 점을 학습하였다.

문서 적재(Ingest Pipeline)

이번 프로젝트에서 가장 중요하게 학습한 내용 중 하나는 문서를 Vector Database에 적재하는 과정이었다.

List<Document> docs = new TextReader(resource).get();

TokenTextSplitter splitter =
        TokenTextSplitter.builder()
                .withChunkSize(chunkSize)
                .build();

List<Document> chunks =
        splitter.apply(docs);

문서를 그대로 저장하지 않고 여러 개의 Chunk로 분리하였다.

전체 과정은

TXT 파일

↓

TextReader

↓

Document 생성

↓

Chunk 분할

↓

Embedding

↓

Vector DB 저장

순서로 진행된다.

TextReader

new TextReader(resource)

는

TXT 파일을 읽어서 Document 객체를 생성한다.

TokenTextSplitter

문서를 일정한 크기로 분리하는 역할을 수행한다.

예를 들어

1000자의 문서라면

Chunk1

Chunk2

Chunk3

Chunk4

처럼 여러 개로 나눈다.

Chunk를 나누는 이유

LLM은 한 번에 처리할 수 있는 토큰 수가 제한되어 있다.

또한

문서를 너무 크게 저장하면

질문과 관계없는 내용까지 같이 검색된다.

반대로

너무 작게 나누면

문맥(Context)이 끊어질 수 있다.

따라서 적절한 Chunk Size를 설정하는 것이 검색 품질을 높이는 중요한 요소라는 점을 이해하였다.

UUID를 이용한 Document 관리

Chunk를 생성한 후

UUID를 이용하여 Document의 ID를 생성하였다.

.id(

UUID.nameUUIDFromBytes(

("sample.txt:" + c.getText())

.getBytes(StandardCharsets.UTF_8)

).toString()

)

UUID를 랜덤하게 생성하지 않고

문서 내용을 기반으로 생성하였다.

그 이유는

같은 문서를 여러 번 적재하더라도

같은 UUID가 생성되기 때문이다.

즉

같은 문서

↓

같은 UUID

↓

기존 문서 덮어쓰기

가 가능해진다.

이를 통해 중복 데이터 저장을 방지하는 방법을 학습하였다.

QuestionAnswerAdvisor를 이용한 RAG 응답 생성

RAG에서 가장 핵심이 되는 기능은

QuestionAnswerAdvisor였다.

ChatResponse response =
        chatClient.prompt()

.advisors(

a -> a.param(

QuestionAnswerAdvisor.FILTER_EXPRESSION,

"category == '%s'".formatted(category)

)

)

Advisor는 질문을 AI에게 보내기 전에

자동으로 관련 문서를 검색한다.

이번 프로젝트에서는

category == spring

처럼 Metadata를 이용하여

특정 카테고리의 문서만 검색하도록 구현하였다.

즉

사용자 질문

↓

Metadata Filter

↓

Vector Search

↓

관련 문서

↓

LLM

↓

답변 생성

과정이 자동으로 수행된다.

MainController의 전체 요청 흐름

Controller에서는 사용자의 요청을 받아

각 기능을 Service로 전달하였다.

@PostMapping("/chat")

public String chat(

@RequestParam String question,

@RequestParam String category,

RedirectAttributes redirectAttributes
)

사용자가 질문을 입력하면

JSP

↓

MainController

↓

DocumentService

↓

QuestionAnswerAdvisor

↓

VectorStore 검색

↓

LLM

↓

답변 생성

↓

JSP 출력

순서로 처리된다.

Controller는 검색이나 AI 호출을 직접 수행하지 않고

요청을 Service에 전달하는 역할만 담당하였다.

이를 통해 MVC 구조를 유지하면서도 RAG 기능을 자연스럽게 통합하는 방법을 학습하였다.

학습한 내용

느낀 점

이번 프로젝트를 통해 RAG는 단순히 AI 모델의 성능을 높이는 기술이 아니라, 검색 시스템(Vector Database)과 생성형 AI를 하나의 파이프라인으로 연결하는 구조라는 점을 깊이 이해할 수 있었다. 특히 문서를 Document 객체로 생성하고, VectorStore가 자동으로 임베딩을 수행하여 저장하는 과정, Similarity Search를 통해 의미적으로 가장 유사한 문서를 검색하는 과정, QuestionAnswerAdvisor가 검색된 문서를 프롬프트에 자동으로 포함시키는 과정을 직접 구현하면서 RAG 시스템의 내부 동작 원리를 체계적으로 학습할 수 있었다. 또한 Chunk Size, Metadata, Top-K, Similarity Threshold와 같은 요소들이 검색 정확도와 AI 답변의 품질에 큰 영향을 미친다는 점을 실습을 통해 확인하면서, 실무에서 RAG를 구축할 때 검색 성능과 문서 관리 전략이 매우 중요하다는 사실을 배울 수 있었다.

이번에는 기존의 생성형 AI(ChatGPT, Gemini 등)가 가지고 있는 한계를 해결하기 위한 RAG(Retrieval-Augmented Generation) 기술을 학습하였다. 이전 프로젝트에서는 LLM에게 사용자의 질문만 전달하여 답변을 생성하는 방식이었다면, 이번 프로젝트에서는 외부 문서를 Vector Database에 저장한 후 질문과 가장 유사한 문서를 검색하여 함께 전달하는 방식을 구현하였다.

이를 통해 LLM이 학습하지 않은 최신 정보나 회사 내부 문서와 같은 데이터를 활용하여 보다 정확한 답변을 생성할 수 있는 구조를 이해하였다. 또한 Spring AI에서 제공하는 VectorStore, EmbeddingModel, QuestionAnswerAdvisor, ChatClient를 활용하여 RAG 시스템을 구성하는 방법을 익혔다.

RAG(Retrieval-Augmented Generation)의 개념

이번 프로젝트에서 가장 먼저 학습한 내용은 RAG의 전체 동작 원리였다.

기존 LLM은 학습된 데이터만을 기반으로 답변을 생성하기 때문에 최신 정보나 학습되지 않은 내용을 질문하면 잘못된 정보를 생성하는 Hallucination(환각) 문제가 발생할 수 있다.

RAG는 이러한 문제를 해결하기 위해 질문과 관련된 문서를 먼저 검색한 후, 검색된 문서를 함께 LLM에 전달하여 답변을 생성하는 방식이다.

RAG의 전체 흐름은 다음과 같다.

사용자 질문

↓

질문 임베딩(Embedding)

↓

Vector Database 검색

↓

유사한 문서 추출

↓

질문 + 검색된 문서

↓

LLM

↓

최종 답변

기존에는 AI가 자신의 학습 데이터만을 이용해 답변을 생성했다면, RAG는 외부 문서를 근거(Context)로 함께 제공하기 때문에 더욱 신뢰성 있는 답변을 생성할 수 있다는 점을 이해하였다.

Embedding의 개념 이해

RAG를 구현하기 위해서는 텍스트를 숫자로 변환하는 과정이 필요하다.

이를 Embedding이라고 한다.

Embedding은 사람이 읽는 문자열을 AI가 계산할 수 있는 고차원의 벡터(Vector)로 변환하는 기술이다.

예를 들어

"사과"

↓

[0.21, -0.43, 0.81, ...]

처럼 하나의 문장이 수백 또는 수천 개의 실수값으로 변환된다.

이 벡터는 단순한 숫자가 아니라 문장의 의미를 포함하고 있기 때문에 의미가 비슷한 문장끼리는 벡터의 위치도 가까워진다.

이번 프로젝트에서는 Google의 Embedding Model을 이용하여 이러한 벡터를 생성하였다.

EmbeddingService 구현

@Service
@RequiredArgsConstructor
public class EmbeddingService {

    @Qualifier("googleGenAiTextEmbedding")
    private final EmbeddingModel embeddingModel;

    public float[] embed(String text) {
        return embeddingModel.embed(text);
    }
}

EmbeddingModel은 텍스트를 벡터로 변환하는 역할을 수행한다.

프로젝트에서는 googleGenAiTextEmbedding Bean을 주입받아 사용하였다.

embeddingModel.embed(text);

메서드를 호출하면 입력한 문자열이 AI 모델을 통해 임베딩되고, 결과는 float[] 형태의 벡터로 반환된다.

이 과정에서 개발자는 벡터 계산 과정을 직접 구현하지 않아도 되며, Spring AI가 내부적으로 Google Embedding API와 통신하여 결과를 받아온다.

Vector Database의 역할

이번 프로젝트에서는 생성된 벡터를 저장하기 위해 Vector Database(VectorStore) 를 사용하였다.

일반적인 데이터베이스는

이름 = 홍길동
나이 = 25

처럼 값을 비교한다.

반면 Vector Database는

질문 벡터

↓

문서 벡터

↓

유사도 계산

을 수행한다.

즉, 문장의 의미를 기준으로 가장 비슷한 문서를 찾는 데이터베이스라는 점을 이해하였다.

Spring AI의 VectorStore

Spring AI에서는 Vector Database를 추상화한 VectorStore 인터페이스를 제공한다.

private final VectorStore vectorStore;

VectorStore는 개발자가 사용하는 추상 인터페이스이며, 내부적으로는 pgvector와 같은 실제 Vector Database와 연결된다.

덕분에 개발자는 특정 Vector DB 구현체에 의존하지 않고 동일한 코드로 다양한 Vector Database를 사용할 수 있다.

ChatClient와 QuestionAnswerAdvisor

@Bean
public ChatClient ragChatClient(
        ChatClient.Builder builder,
        VectorStore vectorStore
) {

이번 프로젝트에서는 ChatClient를 생성하면서 VectorStore를 함께 주입하였다.

이를 통해 ChatClient는 질문을 받을 때마다 VectorStore에서 관련 문서를 검색할 수 있는 구조가 된다.

QuestionAnswerAdvisor

.defaultAdvisors(
    QuestionAnswerAdvisor.builder(vectorStore)

QuestionAnswerAdvisor는 RAG의 핵심 기능을 담당한다.

사용자가 질문하면 내부적으로 다음과 같은 과정을 자동으로 수행한다.

사용자 질문

↓

질문 임베딩

↓

VectorStore 검색

↓

관련 문서 조회

↓

Prompt 생성

↓

LLM 호출

즉, 개발자가 직접

• 문서를 검색하고
• Prompt를 조합하는 코드를 작성하지 않아도

Advisor가 자동으로 처리해 준다.

SearchRequest를 이용한 검색 조건 설정

QuestionAnswerAdvisor에서는 검색 방식을 설정할 수 있다.

.searchRequest(
    SearchRequest
        .builder()
        .topK(4)
        .similarityThreshold(0.5)
        .build()
)

여기서 새롭게 학습한 개념은 Top-K와 Similarity Threshold이다.

Top-K

.topK(4)

질문과 가장 유사한 문서를 최대 4개까지 검색한다.

예를 들어

검색 결과가

문서1 98%

문서2 94%

문서3 91%

문서4 87%

문서5 82%

라면

Top-K가 4이므로 문서1~문서4까지만 AI에게 전달된다.

Similarity Threshold

.similarityThreshold(0.5)

는 최소 유사도를 의미한다.

예를 들어

문서1 0.91

문서2 0.74

문서3 0.52

문서4 0.31

이라면

Threshold가 0.5이므로

문서4는 제외된다.

이를 통해 검색 품질을 높이고 관련성이 낮은 문서가 AI에게 전달되는 것을 방지할 수 있다는 점을 학습하였다.

System Prompt를 이용한 RAG 응답 제어

.defaultSystem("""
주어진 컨텍스트를 기반으로 할 것.
컨텍스트에 없는 내용은 지어내지 말고
'찾을 수 없다'라고 답할 것.
답변은 마크다운으로 작성
""")

RAG에서는 검색된 문서를 AI에게 전달하는 것만큼 중요한 것이 System Prompt이다.

이번 프로젝트에서는 AI에게 다음과 같은 규칙을 부여하였다.

• 검색된 문서를 기준으로 답변할 것
• 문서에 없는 내용은 추측하지 말 것
• 찾을 수 없으면 없다고 답변할 것
• 마크다운 형식으로 응답할 것

이를 통해 Hallucination을 줄이고 신뢰성 있는 답변을 생성하는 방법을 학습하였다.

학습한 내용

느낀 점

이번 프로젝트를 통해 RAG는 단순히 AI에게 질문을 전달하는 기술이 아니라, 검색 시스템과 생성형 AI를 결합하여 답변의 정확성과 신뢰성을 높이는 구조라는 점을 이해할 수 있었다. 특히 Embedding을 통해 문장을 의미 기반의 벡터로 변환하고, Vector Database에서 가장 유사한 문서를 검색한 뒤 QuestionAnswerAdvisor가 이를 자동으로 프롬프트에 포함시키는 과정을 학습하면서 Spring AI가 RAG 파이프라인을 얼마나 효율적으로 추상화하고 있는지 체감할 수 있었다. 또한 Top-K와 Similarity Threshold를 조정하여 검색 결과의 품질을 제어하고, System Prompt를 통해 AI가 문서에 없는 내용을 추측하지 않도록 설정하는 방법을 익히면서 실제 서비스에서 신뢰성 있는 AI 응답을 제공하기 위한 핵심 요소들을 배울 수 있었다.

Spring Data JPA를 활용하여 AI Chat Memory를 데이터베이스에 저장하고 관리하는 기능을 구현하였다. 이전에는 MyBatis를 사용하여 SQL을 직접 작성하고 Mapper를 통해 데이터베이스를 제어하였다면, 이번에는 객체(Entity)를 중심으로 데이터를 관리하는 ORM(Object Relational Mapping) 방식을 적용하였다.

JPA를 활용하면서 SQL을 직접 작성하지 않고도 Repository를 통해 데이터를 조회·저장·삭제할 수 있었으며, 엔티티(Entity)를 영속성 컨텍스트(Persistence Context)가 관리하는 과정을 직접 실습하였다. 또한 Spring Data JPA가 제공하는 기본 CRUD 기능과 JPQL, 트랜잭션 관리, 영속성 컨텍스트의 Dirty Checking 등 JPA의 핵심 개념을 학습하였다.

이를 통해 데이터베이스의 테이블을 직접 다루는 것이 아니라 객체를 중심으로 비즈니스 로직을 구현하는 개발 방식을 이해할 수 있었다.

JPA와 ORM(Object Relational Mapping)의 이해

이번 프로젝트를 진행하면서 가장 먼저 학습한 내용은 ORM(Object Relational Mapping)의 개념이었다.

기존의 JDBC나 MyBatis는 SQL을 직접 작성하여 데이터베이스의 테이블을 조작하는 방식이었다. 개발자가 SELECT, INSERT, UPDATE, DELETE 문을 작성하고, 조회된 결과를 다시 Java 객체로 변환하는 과정을 직접 구현해야 했다.

반면 JPA는 데이터베이스의 테이블을 하나의 객체(Entity)로 매핑하여 관리한다.

예를 들어 Chat Message 테이블은 다음과 같은 Entity로 표현하였다.

@Entity
@Table(name = "chat_message")
public class ChatMessageJPA {

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

    private String conversationId;

    private String messageType;

    private String content;

    private int seq;

}

@Entity는 해당 클래스가 데이터베이스 테이블과 매핑되는 객체임을 의미한다.

@Table은 어떤 테이블과 연결되는지를 지정하며, @Id는 기본 키(Primary Key)를 나타낸다.

@GeneratedValue를 사용하여 기본 키 값을 데이터베이스가 자동으로 생성하도록 설정하였다.

이를 통해 SQL을 직접 작성하지 않고도 객체를 저장하거나 조회할 수 있는 JPA의 기본 구조를 이해할 수 있었다.

Spring Data JPA Repository 활용

이번 프로젝트에서는 Spring Data JPA가 제공하는 JpaRepository를 상속받아 Repository를 구현하였다.

public interface ChatMemoryJpaRepository
        extends JpaRepository<ChatMessageJPA, Long> {

    List<ChatMessageJPA> findAllByConversationId(
            String conversationId);

    @Query(
        "SELECT DISTINCT cm.conversationId FROM ChatMessageJPA cm"
    )
    List<String> findConversationIds();

    void deleteAllByConversationId(
            String conversationId);

}

JpaRepository는 CRUD 기능을 기본적으로 제공한다.

따라서 별도의 SQL을 작성하지 않아도

• save()
• saveAll()
• findById()
• findAll()
• delete()

등을 사용할 수 있다.

또한 메서드 이름만으로 SQL이 생성되는 Query Method 기능을 활용하였다.

예를 들어

findAllByConversationId(...)

메서드는 별도의 SQL을 작성하지 않아도

SELECT *
FROM chat_message
WHERE conversation_id = ?

와 동일한 기능을 수행한다.

이를 통해 SQL 작성량을 크게 줄일 수 있다는 점을 학습하였다.

JPQL을 이용한 객체 중심 조회

기본 CRUD 외에도 직접 조회 조건이 필요한 경우에는 JPQL을 사용하였다.

@Query(
"SELECT DISTINCT cm.conversationId
FROM ChatMessageJPA cm"
)

JPQL은 SQL과 비슷하지만 테이블이 아닌 Entity 객체를 대상으로 조회한다.

SQL이라면

SELECT DISTINCT conversation_id
FROM chat_message

가 되지만,

JPQL에서는

SELECT cm.conversationId
FROM ChatMessageJPA cm

처럼 Entity 이름과 객체의 필드를 사용한다.

이를 통해 JPA는 객체 중심으로 동작한다는 점을 이해하였다.

ChatMemoryRepository 구현

Spring AI와 JPA를 연결하기 위해 ChatMemoryRepository를 구현하였다.

@Repository
@RequiredArgsConstructor
public class JpaChatMemoryRepository
        implements ChatMemoryRepository

Spring AI는 Chat Memory를 저장하는 방식에 대해 인터페이스만 제공한다.

이번 프로젝트에서는 JPA Repository를 이용하여

• 대화 저장
• 대화 조회
• 대화 삭제

기능을 구현하였다.

이를 통해 Spring AI와 Spring Data JPA를 연결하는 구조를 이해할 수 있었다.

Entity와 Message 객체의 변환

Spring AI는 Message 객체를 사용하지만 JPA는 Entity를 저장한다.

따라서 두 객체를 서로 변환하는 과정이 필요하였다.

public static ChatMessageJPA fromMessage(
        Message message,
        String conversationId,
        int seq)

반대로

public Message toMessage()

를 통해 Entity를 Message 객체로 변환하였다.

Entity는 데이터베이스에 저장하기 위한 객체이고,

Message는 Spring AI가 사용하는 객체이다.

따라서

Message

↓

Entity 저장

↓

DB

↓

Entity 조회

↓

Message

과 같은 변환 과정을 직접 구현하였다.

이를 통해 서로 다른 계층에서 사용하는 객체를 변환하는 방법을 학습하였다.

saveAll()을 이용한 데이터 저장

Chat Memory는 saveAll()을 이용하여 저장하였다.

repository.deleteAllByConversationId(
        conversationId);

...

repository.saveAll(chatMessages);

새로운 대화가 저장될 때

먼저 기존 대화를 삭제하고,

현재 메모리에 존재하는 대화를 모두 저장하였다.

Spring Data JPA에서는

repository.saveAll(...)

만 호출하면

Entity 개수만큼 INSERT SQL을 자동으로 생성하여 실행한다.

이를 통해 SQL을 직접 작성하지 않고도 여러 데이터를 저장하는 방법을 학습하였다.

트랜잭션(Transaction) 관리

이번 프로젝트에서는 저장과 삭제를 하나의 작업으로 처리하기 위해 @Transactional을 사용하였다.

@Transactional
public void saveAll(...)

Chat Memory 저장 과정에서는

1. 기존 데이터 삭제
2. 새로운 데이터 저장

두 작업이 하나의 작업 단위로 처리되어야 한다.

만약 삭제는 성공하고 저장에서 오류가 발생하면 대화 기록이 모두 사라지는 문제가 발생한다.

@Transactional을 적용하면 두 작업을 하나의 트랜잭션으로 처리하여 오류 발생 시 전체 작업을 Rollback한다.

이를 통해 데이터의 일관성을 유지하는 트랜잭션의 중요성을 이해할 수 있었다.

Spring Data JPA가 제공하는 생산성

이번 프로젝트를 진행하면서 가장 크게 느낀 점은 개발 생산성이었다.

MyBatis에서는

• SQL 작성
• Mapper 작성
• XML 작성

과정을 거쳐야 했다.

반면 JPA에서는

• Entity 작성
• Repository 생성

만으로 대부분의 CRUD 기능을 구현할 수 있었다.

또한 Query Method를 활용하면 메서드 이름만으로 SQL이 자동 생성되기 때문에 반복적인 SQL 작성이 크게 줄어드는 것을 경험하였다.

이를 통해 Spring Data JPA가 제공하는 높은 생산성과 유지보수성을 체감할 수 있었다.

영속성 컨텍스트(Persistence Context)의 이해

이번 프로젝트에서 새롭게 이해한 개념 중 하나는 영속성 컨텍스트(Persistence Context)였다.

JPA에서 조회한 Entity는 단순한 Java 객체가 아니라 영속성 컨텍스트에 의해 관리되는 객체가 된다.

즉, Entity를 조회하면 JPA는 해당 객체를 메모리에서 관리하고 있으며, 트랜잭션이 종료되는 시점까지 객체의 상태 변화를 계속 추적한다.

이러한 기능 덕분에 개발자는 SQL의 UPDATE 문을 직접 작성하지 않고도 객체의 값을 변경하는 것만으로 데이터베이스의 값이 자동으로 수정된다.

비록 이번 Chat Memory 프로젝트에서는 대부분 저장(saveAll)과 삭제(deleteAll)를 중심으로 구현하였지만, 이전 JPA 프로젝트에서 학습한 Dirty Checking 개념과 연결하여 JPA는 객체의 상태를 관리하는 ORM 프레임워크라는 점을 더욱 명확하게 이해할 수 있었다.

새롭게 학습한 내용

느낀 점

JPA는 단순히 SQL을 자동으로 생성해 주는 기술이 아니라 객체 중심으로 데이터를 관리하는 ORM 프레임워크라는 점을 깊이 이해할 수 있었다. Spring Data JPA의 JpaRepository를 활용하면서 반복적인 CRUD SQL을 작성하지 않아도 대부분의 기능을 구현할 수 있었고, Query Method와 JPQL을 통해 필요한 조회 기능을 객체 중심으로 구현하는 방법도 익힐 수 있었다. 또한 Entity를 영속성 컨텍스트가 관리한다는 개념과 트랜잭션을 통한 데이터 일관성 유지 과정을 학습하면서, JPA가 데이터베이스와 객체 사이의 매핑을 넘어 애플리케이션의 유지보수성과 생산성을 높여 주는 핵심 기술이라는 점을 체감할 수 있었다.

Spring AI의 Chat Memory 기능을 MyBatis와 연동하여 AI와 사용자의 대화 내용을 데이터베이스에 저장하고, 이전 대화 내용을 다시 불러와 대화를 이어갈 수 있는 기능을 구현하였다.

기존에는 AI와의 대화가 한 번의 요청과 응답으로 끝나는 구조였다면, 이번에는 사용자의 대화 기록을 데이터베이스에 영속적으로 저장(Persistence) 하여 이전 대화를 기억하는 AI 서비스를 구현하는 방법을 학습하였다.

이를 위해 MyBatis를 이용하여 SQL을 직접 작성하고, Mapper 인터페이스를 통해 데이터베이스와 통신하는 구조를 설계하였다. 또한 Spring AI에서 제공하는 ChatMemoryRepository 인터페이스를 직접 구현하여 Spring AI와 MyBatis를 연결하는 방법도 익힐 수 있었다.

Chat Memory의 개념 이해

가장 먼저 이해해야 했던 개념은 Chat Memory였다.

일반적으로 생성형 AI는 사용자가 질문을 보내면 그 질문에 대해서만 답변을 생성한다.

예를 들어

사용자 : 나는 백엔드 개발자야.

AI : 반갑습니다.

-------------------------

사용자 : 내가 방금 무슨 직업이라고 했지?

AI : 알 수 없습니다.

이처럼 이전 대화를 기억하지 못한다.

하지만 Chat Memory를 사용하면 이전 대화를 저장해 두었다가 다음 요청 시 함께 AI에게 전달한다.

사용자 : 나는 백엔드 개발자야.

AI : 반갑습니다.

-------------------------

사용자 : 내가 방금 무슨 직업이라고 했지?

AI : 백엔드 개발자라고 말씀하셨습니다.

즉, Chat Memory는 AI가 기억력이 생긴 것처럼 보이도록 이전 대화를 함께 전달하는 기능이라는 점을 이해하였다.

Spring AI의 ChatMemoryRepository 구현

Spring AI에서 제공하는 ChatMemoryRepository를 직접 구현하였다.

@Repository
@RequiredArgsConstructor
public class MyBatisChatMemoryRepository
        implements ChatMemoryRepository

Spring AI는 Chat Memory를 어디에 저장할지 정해져 있지 않다.

대신

• InMemory
• Redis
• MySQL
• PostgreSQL

등 다양한 저장소를 사용할 수 있도록 ChatMemoryRepository 인터페이스를 제공한다.

이번 프로젝트에서는 MyBatis를 이용하여 MySQL에 저장하기 위해 직접 구현체를 작성하였다.

이를 통해 Spring AI의 인터페이스를 구현하여 원하는 저장 방식을 자유롭게 만들 수 있다는 점을 학습하였다.

Mapper를 이용한 데이터 접근

MyBatis는 Repository가 SQL을 직접 실행하지 않는다.

반드시 Mapper를 통해 SQL을 실행한다.

@Mapper
public interface ChatMessageMapper {

    List<String> findConversationIds();

    List<ChatMessageMyBatis> findByConversationId(String conversationId);

    void insertAll(List<ChatMessageMyBatis> messages);

    void deleteByConversationId(String conversationId);

}

Mapper 인터페이스는 SQL과 Java를 연결해 주는 역할을 한다.

이번 프로젝트에서는

• 저장된 대화 목록 조회
• 특정 대화 조회
• 여러 메시지 저장
• 특정 대화 삭제

기능을 Mapper에 정의하였다.

실제 SQL은 XML Mapper에서 작성되고, Java에서는 메서드만 호출하면 SQL이 실행되는 구조라는 점을 이해하였다.

이를 통해 SQL과 Java 코드를 분리하는 MyBatis의 구조를 학습하였다.

Conversation ID를 이용한 대화 구분

이번 프로젝트에서는 여러 사용자의 대화를 구분하기 위해 Conversation ID를 사용하였다.

public record ChatDTO(
        String message,
        String conversationId
)

Controller에서는

dto.withID(session.getId())

를 이용하여 현재 세션 ID를 Conversation ID로 사용하였다.

사용자가 여러 명일 경우 모든 대화를 하나의 테이블에 저장하면 어떤 메시지가 누구의 것인지 구분할 수 없다.

따라서 세션 ID를 Conversation ID로 사용하여

conversation_id

AAA111

AAA111

AAA111

BBB222

BBB222

CCC333

처럼 사용자별 대화를 구분하였다.

이를 통해 AI 서비스에서도 사용자 식별이 매우 중요하다는 점을 학습하였다.

Message 객체와 Entity 변환

Spring AI는 Message 객체를 사용하지만

MyBatis는 Entity를 저장한다.

따라서 두 객체를 서로 변환하는 과정이 필요하였다.

public static ChatMessageMyBatis fromMessage(
        Message message,
        String conversationId,
        int seq
)

그리고

public Message toMessage()

AI는 Message 객체를 사용한다.

하지만 데이터베이스에는 객체를 그대로 저장할 수 없기 때문에

conversation_id

message_type

content

seq

형태로 저장하였다.

필요할 때 다시 Message 객체로 변환하여 Spring AI가 사용할 수 있도록 구현하였다.

이를 통해 객체와 데이터베이스 간의 변환 과정을 직접 구현하는 방법을 학습하였다.

saveAll() 동작 원리

가장 중요한 로직은 saveAll()이었다.

chatMessageMapper.deleteByConversationId(conversationId);

...

chatMessageMapper.insertAll(chatMessages);

새로운 메시지가 저장될 때

기존 데이터를 UPDATE 하는 것이 아니라

1.

기존 대화를 모두 삭제

↓

2.

현재 메모리에 있는 대화를 모두 INSERT

하는 방식을 사용하였다.

예를 들어

USER

안녕

ASSISTANT

안녕하세요.

가 저장되어 있다가

새로운 질문

오늘 날씨 어때?

가 들어오면

기존 데이터를 삭제한 뒤

안녕

안녕하세요

오늘 날씨 어때?

맑습니다.

전체를 다시 저장한다.

이 방식은 코드가 단순하며 MessageWindowChatMemory와 잘 동작하도록 설계되어 있다는 점을 이해하였다.

MessageWindowChatMemory

이번 프로젝트에서는 모든 대화를 저장하지 않고 최근 메시지만 기억하도록 설정하였다.

MessageWindowChatMemory.builder()

.chatMemoryRepository(chatMemoryRepository)

.maxMessages(3)

maxMessages(3)은

최근 3개의 메시지만 AI에게 전달한다.

예를 들어

1

안녕

2

반가워

3

점심 추천해줘

4

김치찌개 추천

5

오늘 날씨는?

라면

AI는

점심 추천해줘

김치찌개 추천

오늘 날씨는?

만 전달받는다.

이를 통해 너무 많은 대화를 보내지 않아

• 응답 속도 향상
• 토큰 절약
• API 비용 감소

효과를 얻을 수 있다는 점을 학습하였다.

ChatClient와 Chat Memory 연결

MyBatis로 구현한 Chat Memory는 ChatClient에 연결하여 사용하였다.

@Bean

public ChatClient mybatisChatClient(

ChatModel chatModel,

@Qualifier("mybatisChatMemory")
ChatMemory memory
)

그리고

.advisors(
a -> a.param(
ChatMemory.CONVERSATION_ID,
dto.conversationId()
))

를 이용하여 현재 대화 ID를 전달하였다.

Conversation ID를 Advisor에 전달하면

Spring AI는

1.

Conversation ID로 이전 대화를 조회하고

↓

2.

Prompt 앞에 이전 대화를 붙인 뒤

↓

3.

AI에게 함께 전송한다.

즉, 개발자가 직접 이전 대화를 Prompt에 이어붙이지 않아도 Spring AI가 자동으로 Chat Memory를 활용한다는 점을 학습하였다.

새롭게 학습한 내용