전체 메뉴

테마

Chapter 13

Thymeleaf 화면과 폼 처리

Spring MVC와 Thymeleaf로 목록·상세·폼 화면을 만들고 이스케이프, 검증 오류, PRG, Flash 메시지와 화면 테스트를 구현합니다.

난이도
중급
예상 학습
150분
Spring Boot 기준
Spring Boot 4.1.1
JDK 기준
JDK 21
최종 검토

전체 24개 Chapter 중 Chapter 13입니다. 예제 코드는 공개 저장소 spring-boot-curriculum의 examples/ch19-thymeleaf 폴더에서 확인할 수 있습니다.

Learning goals

오늘 배울 내용

  • Controller가 Model과 뷰 이름을 전달하는 흐름 설명하기
  • Thymeleaf 표현식과 반복·조건·링크 문법 사용하기
  • 출력 이스케이프와 비이스케이프의 보안 차이 구분하기
  • 폼 객체 검증 오류를 입력 화면에 다시 표시하기
  • PRG와 Flash 속성으로 중복 제출 방지하기
  1. Model 전달
  2. 템플릿 렌더링
  3. 폼 바인딩
  4. 검증 오류 표시
  5. PRG 적용
이 Chapter의 진행 흐름

지금까지 만든 것은 JSON을 돌려주는 API였습니다. 사람이 직접 쓰는 화면은 브라우저가 읽을 HTML이어야 합니다. 서버가 HTML을 직접 만들어 보내는 가장 전통적인 방법이 템플릿 엔진이고, Spring Boot와 가장 자연스럽게 어울리는 것이 Thymeleaf입니다.

이 Chapter에서는 사용자 목록과 상세 화면을 만들고(예제 ch19-thymeleaf), 이어서 값을 입력받아 등록·수정·삭제하는 폼 화면(예제 ch20-thymeleaf-crud)까지 만듭니다. 입력은 잘못 들어올 수 있고, 저장 뒤 새로고침을 누르면 무슨 일이 생기는지도 정해야 합니다. 이 두 질문이 Chapter 후반의 중심입니다.

이 Chapter에서 만드는 것

만드는 것 설명
/users 목록·상세 화면 @Controller가 Model과 뷰 이름을 넘기고 템플릿이 렌더링
공통 조각 fragments/layout.html의 head와 nav를 th:replace로 재사용
404 오류 페이지 templates/error/404.html
등록·수정 폼 UserForm, th:field, 검증 오류 표시
PRG와 Flash 메시지 저장 뒤 redirect, 안내 문구 한 번만 표시
테스트 ch19: 10건, ch20: 14건

JSON API와 달라지는 점

비교 이전 Chapter(JSON API) 이 Chapter(Thymeleaf)
컨트롤러 @RestController @Controller
반환값 객체 → JSON 뷰 이름(문자열)
오류 오류 JSON 오류 HTML 페이지, 폼 재표시
중복 제출 방지 해당 없음 PRG 패턴

준비물과 예제 저장소

사전 지식

  • Chapter 04의 컨트롤러, Chapter 06의 Bean Validation.
  • 코드는 examples/ch19-thymeleaf, examples/ch20-thymeleaf-crud입니다.

확인 환경

Docker 컨테이너(JDK 21.0.11)에서 실행한 값이고 Thymeleaf 3.1.5.RELEASE입니다. 브라우저에서 화면을 직접 열어 보지는 않았고 응답 HTML을 받아 확인했습니다. Windows는 확인하지 못했습니다.

컨트롤러는 뷰 이름과 Model만 넘긴다

@RestController는 반환값을 응답 본문(JSON)으로 쓰지만, @Controller는 반환한 문자열을 뷰 이름으로 해석합니다. 화면용 컨트롤러가 하는 일은 단순합니다. Model에 값을 담고 어떤 템플릿을 쓸지 이름을 돌려주는 것입니다.

컨트롤러

@GetMapping("/users")
public String list(@RequestParam(defaultValue = "false") boolean activeOnly, Model model) {
    List<User> users = repository.findAll().stream()
            .filter(user -> !activeOnly || user.active())
            .toList();
    model.addAttribute("users", users);
    model.addAttribute("activeOnly", activeOnly);
    return "users/list";
}

주요 코드 설명

  • 반환 타입이 String입니다. @Controller에서는 이 문자열이 응답 본문이 아니라 뷰 이름입니다.
  • Model model: 컨트롤러와 템플릿 사이의 값 상자입니다. addAttribute("users", users)로 넣은 이름(users)을 템플릿이 ${users}로 꺼냅니다.
  • "users/list" → src/main/resources/templates/users/list.html. 앞의 templates/와 뒤의 .html은 자동으로 붙습니다. spring-boot-starter-thymeleaf 의존성만 있으면 별도 설정이 필요 없습니다.
  • @RequestParam(defaultValue = "false") boolean activeOnly는 Chapter 04에서 배운 쿼리 파라미터 받기와 같습니다.
비교 @RestController @Controller
반환값의 의미 응답 본문(JSON 등) 뷰 이름
결과 데이터 렌더링된 HTML
이 과정에서 쓴 곳 Chapter 04~12 이 Chapter

테스트는 뷰 이름과 모델을 바로 확인한다

mvc.perform(get("/users"))
        .andExpect(view().name("users/list"))
        .andExpect(model().attribute("users", hasSize(4)));

view().name(...)은 컨트롤러가 돌려준 뷰 이름, model().attribute(...)는 Model에 담긴 값을 검사합니다. HTML을 파싱하지 않고도 컨트롤러의 책임(무엇을 넘기는가)을 확인할 수 있습니다. Chapter 01의 MockMvc와 같은 도구입니다.

OS 실행 이 Chapter만 테스트
Linux / macOS ./gradlew :examples:ch19-thymeleaf:bootRun ./gradlew :examples:ch19-thymeleaf:test
Windows gradlew.bat :examples:ch19-thymeleaf:bootRun gradlew.bat :examples:ch19-thymeleaf:test

실행한 뒤 브라우저에서 http://localhost:8080/users를 엽니다. 테스트 10건이 모두 통과했습니다.

따라 하기

./gradlew :examples:ch19-thymeleaf:bootRun
curl -i http://localhost:8080/users

Content-Type: text/html;charset=UTF-8로 HTML이 나오면 성공입니다. JSON이 아니라 HTML이 나온다는 점이 @RestController와의 차이입니다.

직접 해 보기

  1. @Controller를 @RestController로 바꾸면 /users 응답이 어떻게 달라질지 예측하고 확인하세요.
  2. model.addAttribute("users", users)의 이름을 "userList"로 바꾸고 어디서 어떤 오류가 날지 예측하세요(아래 “4. 모델 이름이 다르다” 절).
  3. 뷰 이름과 파일 경로가 대응하는 규칙을 자신의 말로 적어 보세요.

템플릿은 올바른 HTML 파일이다

Thymeleaf 템플릿은 th: 속성이 붙은 그냥 HTML입니다. 서버를 거치지 않고 브라우저로 열어도 깨지지 않고, 안에 적어 둔 기본 문구(이름, 0)가 그대로 보입니다. 서버가 렌더링할 때 그 문구가 실제 값으로 바뀝니다. 디자이너와 개발자가 같은 파일을 볼 수 있다는 점이 장점입니다.

목록 행 만들기

<tr th:each="user, stat : ${users}" th:classappend="${user.active} ? '' : 'inactive'">
  <td th:text="${stat.count}">1</td>
  <td><a th:href="@{/users/{id}(id=${user.id})}" th:text="${user.name}">이름</a></td>
  <td th:text="${user.email}">email</td>
  <td th:text="${user.active} ? '활성' : '비활성'">상태</td>
</tr>

주요 코드 설명

  • th:each="user, stat : ${users}": users를 하나씩 user에 담아 이 <tr>을 반복합니다. 두 번째 변수 stat은 반복 상태로 stat.count(1부터 순번)를 얻습니다.
  • ${...}: 모델의 값을 꺼내는 표현식입니다. ${user.name}은 user.getName()(record라면 name())을 호출합니다.
  • th:text: 태그 안의 내용을 값으로 교체합니다. 안에 적어 둔 1, 이름은 서버를 거치지 않고 열었을 때 보이는 기본 문구입니다.
  • th:classappend: 조건이 거짓일 때 inactive 클래스를 붙입니다. 삼항식 조건 ? 값1 : 값2을 씁니다.
  • @{/users/{id}(id=${user.id})}: 링크 표현식입니다. {id} 자리에 id 값을 채워 /users/3 같은 주소를 만듭니다. 주소를 문자열로 이어 붙이는 것보다 안전합니다. 컨텍스트 경로가 있을 때 자동으로 붙는지는 이 Chapter에서 확인하지 않았습니다.

JAR로 띄워서 받은 실제 응답의 일부입니다.

<tr class="inactive">
  <td>3</td>
  <td><a href="/users/3">park</a></td>
  <td>park@example.com</td>
  <td>41</td>
  <td>비활성</td>
</tr>

조건에 따라 요소를 넣고 뺀다

th:if와 th:unless는 조건에 따라 요소 전체를 넣거나 뺍니다. 목록이 비면 표 대신 안내 문구를 보여 주고, activeOnly가 켜졌을 때만 “활성 사용자만 보는 중입니다.“를 보여 줍니다. /users?activeOnly=true의 응답에는 3명이 나오고 park은 빠집니다.

속성 하는 일
th:text 내용을 값으로 교체(이스케이프함)
th:each 요소를 반복
th:if / th:unless 조건에 따라 요소를 넣거나 뺌
th:href 링크 주소를 표현식으로 생성
th:classappend 조건부로 클래스 추가

/ 요청은 302로 /users로 보냈습니다.

따라 하기

curl -s http://localhost:8080/users | sed -n '/<tbody>/,/<\/tbody>/p' | head -20
curl -s 'http://localhost:8080/users?activeOnly=true' | grep -c '<tr'

첫 명령은 표 본문의 HTML을, 두 번째는 activeOnly=true일 때의 행 수를 보여 줍니다(비활성 사용자가 빠져 행 수가 줄어듭니다).

직접 해 보기

  1. th:each의 stat.count를 stat.index로 바꿔 0부터 시작하는지 확인하세요.
  2. 서버를 켜지 않고 list.html을 브라우저로 열어 기본 문구가 어떻게 보이는지 보세요(자신의 환경에서).
  3. ?activeOnly=true일 때만 보이는 안내 문구의 th:if 조건을 찾아 읽어 보세요.

th:text와 th:utext, 이스케이프

템플릿으로 화면을 만들 때 가장 중요한 보안 습관 하나를 고르라면 사용자가 입력한 값은 이스케이프해서 출력한다입니다. Thymeleaf는 기본(th:text)이 안전하고, th:utext는 일부러 이스케이프를 끄는 속성입니다.

실험: 이름이 HTML인 사용자

예제에는 이름이 <b>choi</b>인 사용자를 하나 넣어 두었습니다. 같은 값을 th:text와 th:utext로 각각 출력한 상세 화면의 응답입니다.

<dt>이름</dt><dd>&lt;b&gt;choi&lt;/b&gt;</dd>
<dt>이름(이스케이프 안 함)</dt><dd><b>choi</b></dd>
속성 <b>choi</b> 출력 브라우저에서
th:text &lt;b&gt;choi&lt;/b&gt; <b>choi</b> 글자 그대로 보임
th:utext <b>choi</b> 진짜 굵은 글씨 choi로 해석됨

(브라우저 화면은 응답 HTML로부터의 설명이며 직접 열어 보지는 않았습니다.)

th:text는 <, >를 &lt;, &gt;로 바꿔 글자 그대로 보여 줍니다. th:utext는 값을 HTML로 그대로 넣습니다.

왜 위험한가

이름에 <script>...</script>가 들어 있었다면 th:utext에서는 그 스크립트가 실행됩니다. 공격자가 저장한 값이 다른 사용자의 브라우저에서 실행되는 이런 공격을 XSS(크로스 사이트 스크립팅)라고 부릅니다.

기준

  • 사용자가 입력한 값, 외부에서 온 값: 항상 th:text.
  • th:utext: 서버가 직접 만든 신뢰할 수 있는 HTML 조각에만. 사용자 입력이 섞일 가능성이 있으면 쓰지 않습니다.

목록 화면의 이름 칸도 th:text여서 &lt;b&gt;choi&lt;/b&gt;로 나옵니다. 테스트 두 건이 이 차이를 고정합니다. 폼에서도 th:field가 값을 이스케이프해서 넣기 때문에, 이름 칸에 "><script>alert(1)</script>를 넣어도 &quot;&gt;&lt;script&gt;로 나온다는 것은 아래 “실행 결과” 절에서 확인합니다.

따라 하기

curl -s http://localhost:8080/users/4 | grep -n '이름'

&lt;b&gt;choi&lt;/b&gt;와 <b>choi</b> 두 줄이 보이면 같은 값이 출력 방식에 따라 다르게 나온다는 것을 확인한 것입니다(상세 화면의 사용자 번호는 예제 데이터 기준이며, 번호가 다르면 목록에서 choi를 찾으세요).

직접 해 보기

  1. 상세 화면의 th:text를 th:utext로 바꾸고 <b>choi</b>가 어떻게 달라지는지 응답을 비교한 뒤 되돌리세요.
  2. 자신의 프로젝트에서 th:utext나 [(...)] 표기를 쓰는 곳을 검색해 보세요.
  3. JSON API(@RestController)에서는 이스케이프 문제가 어떻게 달라지는지 생각해 보세요.

공통 조각과 오류 페이지

페이지마다 <head>와 메뉴를 복사하면 고칠 때 모든 파일을 열어야 합니다. 공통 부분은 조각(fragment)으로 한 곳에 두고 가져다 씁니다. 또 존재하지 않는 사용자를 요청했을 때 보여 줄 오류 페이지도 만듭니다.

조각 정의와 사용

<!-- fragments/layout.html -->
<head th:fragment="head(title)"> ... <title th:text="${title} + ' - ch19'">제목</title> ... </head>

<!-- list.html -->
<head th:replace="~{fragments/layout :: head('사용자 목록')}"></head>
<nav th:replace="~{fragments/layout :: nav}"></nav>

주요 코드 설명

  • th:fragment="head(title)": 이 <head>를 head라는 이름의 조각으로 정의하고, 매개변수 title을 받습니다.
  • th:replace="~{fragments/layout :: head('사용자 목록')}": 이 요소를 fragments/layout 템플릿의 head 조각으로 통째로 교체합니다. :: 앞이 파일, 뒤가 조각 이름입니다.
  • 매개변수 덕분에 응답에는 <title>사용자 목록 - ch19</title>처럼 페이지마다 다른 제목이 들어갑니다.
  • 목록과 상세가 같은 메뉴를 쓰고, 메뉴를 고치면 파일 하나만 바꾸면 됩니다.

없는 사용자는 404 페이지로

/users/999는 UserNotFoundException을 던지고, 이 예외에 붙인 @ResponseStatus(NOT_FOUND)가 404 상태를 만듭니다. templates/error/404.html을 두면 Boot가 상태 코드에 맞는 오류 페이지로 사용합니다. 예외와 상태 코드의 관계는 Chapter 06에서 JSON 응답으로 다룬 것의 HTML 버전입니다.

MockMvc는 오류 페이지까지 가지 않는다

MockMvc 테스트는 상태 코드가 404인지만 확인합니다. MockMvc는 서블릿 컨테이너가 오류 페이지로 요청을 다시 넘기는 단계(오류 디스패치)를 수행하지 않는 것으로 알려져 있습니다. 그 원인은 문서 설명에 의존했고 직접 파고들어 확인하지는 않았습니다. 그래서 테스트 이름도 처음 쓴 “오류 페이지와 함께”에서 unknownUserIs404로 바꿨습니다. 오류 템플릿이 실제로 쓰이는지는 JAR를 띄워 따로 확인했습니다.

HTTP/1.1 404
<title>찾을 수 없음 - ch19</title>
<h1>찾을 수 없습니다</h1>

테스트가 통과했다고 해서 화면까지 확인된 것은 아닙니다. 테스트 도구가 거치지 않는 경로는 실행 결과로 직접 확인해야 합니다. 이 원칙은 Chapter 19 단위·슬라이스 테스트에서도 계속 나옵니다.

따라 하기

curl -i -H 'Accept: text/html' http://localhost:8080/users/999

HTTP/1.1 404, Content-Type: text/html과 함께 <h1>찾을 수 없습니다</h1>가 나오면 templates/error/404.html이 쓰인 것입니다. Accept 헤더 없이 curl만 쓰면 Boot가 JSON 오류 본문({"timestamp":...,"status":404,...})을 돌려줍니다(직접 확인). 브라우저는 Accept: text/html을 보내므로 HTML 페이지를 받습니다. MockMvc 테스트는 상태 코드만 확인하므로, 이 화면은 실행 결과로 확인해야 합니다.

확인 문제

  1. th:replace와 th:fragment는 각각 어디에 붙나요?
  2. MockMvc가 404 오류 페이지의 내용을 확인하지 못하는 이유는 무엇인가요?

답: 1) th:fragment는 조각을 정의하는 쪽, th:replace는 가져다 쓰는 쪽에 붙습니다. 2) 서블릿 컨테이너가 오류 페이지로 요청을 다시 넘기는 단계를 MockMvc가 거치지 않기 때문입니다.

직접 해 보기

  1. nav 조각에 메뉴 항목 하나를 추가하고 목록·상세 양쪽에 반영되는지 확인하세요.
  2. head('제목') 매개변수를 바꿔 <title>이 달라지는 것을 보세요.
  3. error/404.html을 지우면 /users/999 응답이 어떻게 달라질지 예측해 보세요.

화면 렌더링 오류 읽기

Thymeleaf 오류는 서버가 뜬 뒤 그 화면을 요청할 때 나옵니다. 메시지가 길어도 읽을 곳은 두세 줄입니다. 아래는 이 예제를 한 군데씩 망가뜨려 테스트를 돌려 얻은 결과입니다(각각 10건 중 해당 화면을 거치는 6건이 실패). 바꾼 코드는 되돌렸고 저장소에는 올리지 않았습니다.

1. EL1008E: Property or field cannot be found

${user.email}을 ${user.emial}로 틀렸습니다.

TemplateInputException: An error happened during template parsing (template: "class path resource [templates/users/list.html]")
Exception evaluating SpringEL expression: "user.emial" (template: "users/list" - line 18, col 11)
EL1008E: Property or field 'emial' cannot be found on object of type 'com.jqdom.curriculum.ch19.User' - maybe not public or not valid?

맨 위 An error happened during template parsing은 모든 템플릿 오류가 똑같이 시작합니다. 읽을 곳은 Exception evaluating SpringEL expression 줄의 표현식과 줄 번호(line 18, col 11), 그리고 EL1008E의 속성 이름입니다.

2. Error resolving fragment

fragments/layout :: nav를 :: navv로 오타를 냈습니다.

Error resolving fragment: "~{'fragments/layout' :: navv}": template or fragment could not be resolved (template: "users/list" - line 5, col 6)

:: 앞이 파일, 뒤가 조각입니다. 파일 이름이 틀렸는지, 파일은 맞고 조각 이름(th:fragment)이 틀렸는지 구분합니다.

3. Error resolving template [users/lst]

컨트롤러가 돌려주는 뷰 이름을 users/lst로 틀렸습니다.

TemplateInputException: Error resolving template [users/lst], template might not exist or might not be accessible by any of the configured Template Resolvers

templates/users/lst.html이 없다는 뜻입니다. 컨트롤러의 반환 문자열과 templates 아래 경로(확장자 제외)가 같은지 봅니다. 앞의 두 오류와 달리 템플릿 안이 아니라 컨트롤러가 원인입니다.

4. 모델 이름이 다르다

컨트롤러에서 model.addAttribute("users", users)의 이름을 "user"로 바꿨습니다. 템플릿은 여전히 users를 찾습니다.

Exception evaluating SpringEL expression: "#lists.size(users)" (template: "users/list" - line 24, col 12)

화면 아래쪽의 총 ...명 줄에서 실패했습니다. 원인은 모델에 users가 없는 것인데 오류는 그 값을 쓰는 표현식에서 납니다. 컨트롤러가 addAttribute로 넣은 이름과 템플릿의 ${...} 이름이 같은지 비교합니다.

증상 가장 먼저 볼 것
EL1008E ... cannot be found on object 표현식의 속성 이름, 줄 번호
Error resolving fragment :: 앞 파일 이름, 뒤 조각 이름
Error resolving template [...] 컨트롤러의 반환 문자열과 파일 경로
표현식 평가 실패인데 속성은 맞음 모델에 넣은 이름

읽는 순서

로그의 줄·열 번호(line 18, col 11)는 템플릿 파일 안의 위치입니다. 번호가 가리키는 줄을 열어 해당 표현식을 바로 확인하세요.

지금의 한계

브라우저에서 오류 페이지가 어떻게 보이는지는 확인하지 않았습니다. 다국어 메시지, CSS 파일 분리, 레이아웃 확장 방식은 다루지 않았습니다. 예제의 CSS는 조각 안에 직접 넣었고, spring.thymeleaf.cache: false는 학습 중 템플릿을 바로 확인하려고 끈 것이라 운영에서는 켜 두어야 합니다.

직접 해 보기

  1. 위 네 가지 중 두 개를 복사본에서 재현하고 줄 번호가 실제로 그 줄을 가리키는지 확인하세요.
  2. Caused by를 아래부터 읽는 습관(Chapter 01)을 템플릿 오류에도 적용해 보세요.
  3. 모델에 없는 이름을 쓰면 오류가 나는 대신 빈 값이 나오는 경우가 있는지 조사해 보세요(이 Chapter에서는 확인하지 않았습니다).

폼 객체와 th:field

보여 주기만 하던 화면에 값을 입력받는 폼을 더합니다. 입력은 잘못 들어올 수 있으니, 폼의 칸과 서버의 객체를 이어 주고 검증 결과를 화면에 되돌리는 구조가 필요합니다. 이 절은 그 첫 단계인 폼 객체와 th:field입니다.

폼 객체

public class UserForm {
    @NotBlank(message = "이름은 필수입니다")
    @Size(min = 2, max = 20, message = "이름은 2자 이상 20자 이하여야 합니다")
    private String name;
    // email도 비슷한 제약
    @NotNull(message = "나이는 필수입니다")
    private Integer age;
    // getter / setter
}

주요 코드 설명

  • 폼과 바인딩되는 객체는 일반 클래스입니다. th:field가 getter로 값을 읽고 폼 전송 시 setter로 값을 쓰기 때문입니다. record는 setter가 없어 이 방식과 맞지 않습니다.
  • 검증 규칙은 Chapter 06과 같은 애노테이션이고, message는 화면에 그대로 보입니다.
  • 나이를 int가 아니라 Integer로 둔 이유: 비어 있는 입력이 null로 들어와야 “필수” 오류를 보여 줄 수 있습니다. int면 빈 입력이 변환 오류가 됩니다(Chapter 05의 int vs Integer와 같은 이야기).

템플릿

<form th:action="@{${action}}" th:object="${userForm}" method="post">
  <input type="text" th:field="*{name}">
  <span th:if="${#fields.hasErrors('name')}" th:errors="*{name}" class="error">오류</span>
  ...
</form>
  • th:object="${userForm}": 이 폼이 다루는 객체를 지정합니다. 모델에 userForm이라는 이름으로 있어야 합니다.
  • *{name}: th:object로 지정한 객체의 name 속성입니다(${userForm.name}의 줄임).
  • th:field="*{name}" 하나가 id, name, value를 함께 만들어 줍니다. 값이 이미 있으면 value에 채워 주므로 수정 화면에 기존 값이 보입니다.
  • ${#fields.hasErrors('name')}와 th:errors: 해당 필드에 오류가 있을 때만 메시지를 보여 줍니다(아래 “검증 오류와 변환 오류 표시” 절).
  • 등록과 수정이 같은 템플릿을 쓰도록 폼의 전송 주소(action)는 컨트롤러가 모델로 넘깁니다.

따라 하기

./gradlew :examples:ch20-thymeleaf-crud:bootRun
curl -s http://localhost:8080/users/new | grep -n 'form \|input'
22:<form action="/users" method="post">
26:    <input type="text" id="name" name="name" value="">
31:    <input type="text" id="email" name="email" value="">
36:    <input type="text" id="age" name="age" value="">

th:field 하나가 id, name, value를 함께 만든 것을 볼 수 있습니다. 등록 화면이라 value가 비어 있습니다.

직접 해 보기

  1. th:field="*{name}"가 만들어 낸 <input>의 id, name, value를 응답 HTML에서 확인하세요.
  2. UserForm.age를 int로 바꾸면 빈 입력이 어떻게 달라질지 예측하세요.
  3. 등록 폼과 수정 폼에서 action만 다르게 넘기는 컨트롤러 코드를 찾아 읽어 보세요.

검증 오류와 변환 오류 표시

폼 검증에 실패하면 저장하지 않고 같은 폼을 오류 메시지와 함께 다시 보여 줘야 합니다. 이때 사용자가 입력한 값은 지우면 안 됩니다. 이 절은 BindingResult로 오류를 받는 컨트롤러와, 형식 오류·업무 규칙 오류·변환 오류 세 종류를 한 화면에 보여 주는 방법을 다룹니다.

컨트롤러

컨트롤러 메서드는 @Valid 폼 객체 바로 뒤에 BindingResult를 받습니다.

@PostMapping("/users")
public String create(@Valid @ModelAttribute("userForm") UserForm form, BindingResult result,
        Model model, RedirectAttributes redirect) {
    if (!result.hasErrors()) {
        try {
            User created = service.create(form);
            redirect.addFlashAttribute("message", "등록했습니다: " + created.name());
            return "redirect:/users";
        } catch (DuplicateEmailException e) {
            result.rejectValue("email", "duplicate", e.getMessage());
        }
    }
    model.addAttribute("action", "/users");
    return "users/form";
}

주요 코드 설명

  • @Valid @ModelAttribute("userForm"): 폼 값을 UserForm에 바인딩하고 검증합니다. 모델 이름 userForm은 템플릿의 th:object="${userForm}"와 같아야 합니다.
  • BindingResult result: 검증과 변환 오류가 여기 담깁니다. @Valid 인자 바로 뒤에 있어야 하며, 위치가 틀리면 400이 됩니다(아래 “3. BindingResult 위치가 틀리면 검증 화면이 사라진다” 절).
  • 오류가 없을 때만 저장하고 redirect:로 응답합니다(아래 “저장 뒤 redirect: PRG와 Flash” 절).
  • 오류가 있으면 저장하지 않고 같은 users/form을 그대로 렌더링합니다. 폼 객체가 모델에 남아 있으므로 입력값도 유지됩니다.
  • result.rejectValue("email", ...): 서비스가 던진 업무 규칙 예외(중복 이메일)를 필드 오류로 바꿔 형식 오류와 같은 자리(이메일 칸 옆)에 보여 줍니다.

실행 결과

이름, 이메일, 나이를 모두 잘못 넣어 보낸 요청(name=k&email=bad&age=abc)에 JAR가 돌려준 폼입니다.

<input type="text" id="name" name="name" value="k">
<span class="error">이름은 2자 이상 20자 이하여야 합니다</span>
...
<input type="text" id="email" name="email" value="bad">
<span class="error">이메일 형식이 올바르지 않습니다</span>

상태는 200이고, 사용자가 입력한 값이 value에 그대로 남아 있습니다. 오류가 있다고 입력을 지워 버리면 사용자는 처음부터 다시 써야 합니다. 이 값은 th:field가 이스케이프해서 넣기 때문에 이름 칸에 "><script>alert(1)</script>를 넣어도 &quot;&gt;&lt;script&gt;로 나온다는 것을 테스트로 확인했습니다(아래 “테스트 14건” 절의 입력값 이스케이프).

중복 이메일은 이렇게 보입니다.

POST /users name=kim2&email=kim@example.com&age=1
-> 200  <span class="error">이미 사용 중인 이메일입니다: kim@example.com</span>

수정할 때는 자기 자신의 이메일을 그대로 두는 것은 허용하고 다른 사람의 이메일은 막습니다. 테스트 두 건이 이 경계를 고정합니다.

변환 오류는 검증 오류와 다른 곳에서 난다

나이 칸에 abc를 넣으면 검증 규칙까지 가지 못하고 그 앞의 문자열 → 정수 변환에서 실패합니다. 빈 칸은 null이 되어 “나이는 필수입니다”가 나오지만 abc는 다른 경로입니다. 처음 만들었을 때 이 칸의 메시지는 이랬습니다.

<span class="error">Failed to convert property value of type java.lang.String to required type java.lang.Integer for property age; For input string: &quot;abc&quot;</span>

Java 내부 문구가 사용자 화면에 그대로 나옵니다. 메시지 파일에 키를 추가해서 바꿨습니다.

# src/main/resources/messages.properties
typeMismatch.userForm.age=나이는 숫자로 입력해 주세요

키 형식은 typeMismatch.{폼 객체 이름}.{필드}이고, Boot가 messages.properties를 자동으로 읽습니다. 고친 뒤에는 같은 요청에서 <span class="error">나이는 숫자로 입력해 주세요</span>가 나오고, 테스트가 Failed to convert가 화면에 없다는 것까지 확인합니다.

오류 종류 발생 위치 메시지 출처
형식(빈 값, 길이, 이메일) Bean Validation 애노테이션의 message
변환(숫자 칸에 문자) 데이터 바인딩 messages.properties의 typeMismatch...
업무 규칙(중복 이메일) 서비스 예외 → rejectValue 예외 메시지

따라 하기

curl -s -i -X POST http://localhost:8080/users -d 'name=k&email=bad&age=abc' | grep -n 'HTTP/\|class="error"'
1:HTTP/1.1 200
29:  <p class="error">입력값을 확인해 주세요.</p>
33:    <span class="error">이름은 2자 이상 20자 이하여야 합니다</span>
38:    <span class="error">이메일 형식이 올바르지 않습니다</span>
43:    <span class="error">나이는 숫자로 입력해 주세요</span>

검증이 실패해도 상태가 200이고, 세 칸의 오류가 한 번에 나옵니다. 정상 값은 302와 Location: http://localhost:8080/users가 나옵니다.

확인 문제

  1. 검증에 실패했는데 응답 상태가 200인 이유는 무엇인가요?
  2. 나이 칸에 abc를 넣었을 때 @Min 검증까지 가지 못하는 이유는 무엇인가요?

답: 1) 오류를 담은 폼을 정상 화면으로 다시 렌더링하기 때문입니다. 2) 검증 전에 문자열을 정수로 바꾸는 변환 단계에서 먼저 실패하기 때문입니다.

직접 해 보기

  1. age=abc를 보내 보고 messages.properties의 키를 지웠을 때 화면 문구가 어떻게 되는지 확인하세요(복원 필수).
  2. 키를 typeMismatch.form.age로 틀리게 적으면 어떤 메시지가 나오는지 예측하세요(결과는 아래 “4. 메시지 키가 틀리면 영어 변환 메시지가 노출된다” 절).
  3. 이메일 중복 오류가 형식 오류와 같은 자리에 보이는 이유를 rejectValue로 설명해 보세요.

저장 뒤 redirect: PRG와 Flash

폼 제출(POST)의 응답으로 바로 목록 화면을 그리면, 사용자가 새로고침할 때 브라우저가 같은 POST를 다시 보냅니다. 사용자가 두 번 등록되는 사고입니다. 해결책은 저장 뒤 redirect하는 것이고, 이름이 PRG(Post-Redirect-Get)입니다. redirect하면 “등록했습니다” 같은 안내를 다음 화면에 넘길 방법이 필요한데, Flash 속성이 그 일을 합니다.

POST, Redirect, GET

POST /users name=kim&email=kim@example.com&age=28
-> 302  Location: http://x/users

저장 직후 응답은 목록을 그리는 것이 아니라 “목록으로 가라”(302)입니다. 새로고침은 마지막 요청인 GET만 다시 보내므로 사용자가 추가로 생기지 않습니다. 목록을 여러 번 새로고침해도 사용자가 늘지 않는다는 것을 테스트(refreshingTheListAfterCreateDoesNotCreateAgain)로 확인했습니다. 실제 브라우저에서 새로고침했을 때의 동작은 확인하지 않았고, 서버의 302 응답과 GET이 데이터를 바꾸지 않는 것만 확인했습니다.

Flash 속성: redirect 뒤 한 번만

redirect하면 요청이 새로 시작되어 모델 값이 사라집니다. Flash 속성은 값을 세션에 잠깐 저장했다가 redirect 직후의 요청 한 번에만 모델로 넘기고 지웁니다.

redirect.addFlashAttribute("message", "등록했습니다: " + created.name());
<p th:if="${message}" th:text="${message}" class="message">안내</p>

첫 번째 GET에는 안내가 보이고, 두 번째 GET(새로고침)에는 사라져야 합니다. 일반 addAttribute와 달리 주소에 값이 붙지 않습니다.

세션 ID가 주소에 붙는다

Flash 속성은 세션에 저장됩니다. 쿠키 없이 첫 POST를 보내자 redirect 주소에 세션 ID가 붙어 나왔습니다.

Location: http://x/users;jsessionid=981CBD908B51B5F6B277EA4EC3658C95

세션 ID가 주소에 들어가면 주소 공유나 로그를 통해 노출될 수 있습니다. 쿠키만 쓰도록 설정해서 막았고, 같은 요청이 Location: http://x/users로 바뀐 것을 확인했습니다.

server:
  servlet:
    session:
      tracking-modes: cookie

쿠키가 없는 첫 요청의 URL 재작성이 원인이라는 설명은 일반적인 서블릿 동작에 의존했고, 설정 변경 전후의 응답 차이만 확인했습니다.

따라 하기

curl -s -i -X POST http://localhost:8080/users -d 'name=kim&email=kim9@example.com&age=28' | grep -i 'HTTP/\|location'
HTTP/1.1 302
Location: http://localhost:8080/users

저장 직후 응답은 화면이 아니라 302와 이동할 주소입니다. 쿠키를 보내지 않았는데도 Location에 ;jsessionid가 붙지 않는 것은 tracking-modes: cookie 설정 덕분입니다.

확인 문제

  1. PRG는 무엇의 약자이고 왜 쓰나요?
  2. Flash 속성은 어디에 저장되나요?

답: 1) Post-Redirect-Get이며, 새로고침이 POST를 다시 보내 중복 제출되는 것을 막습니다. 2) 세션에 잠깐 저장했다가 redirect 직후의 요청 한 번에만 전달합니다.

직접 해 보기

  1. 저장 성공 시 redirect:/users 대신 return "users/list"로 바꾸면 새로고침에서 무슨 일이 생길지 예측하세요.
  2. addFlashAttribute를 addAttribute로 바꾸면 주소가 어떻게 달라지는지 확인해 보세요(복원).
  3. 세션 설정이 Chapter 21 Spring Security의 로그인 세션과 어떻게 이어질지 생각해 보세요.

수정·삭제와 순환 검증 피하기

HTML 폼은 GET과 POST만 보낼 수 있습니다. 그래서 이 예제의 수정과 삭제도 POST로 받습니다. 이 절에서는 그 구조와 함께, Flash 메시지 테스트를 처음에 잘못 만들어 컨트롤러가 틀려도 통과하는 테스트가 되었던 경험을 정리합니다.

수정과 삭제는 POST

삭제를 DELETE로 보내는 방법도 있지만, 이 예제는 POST /users/{id}/delete와 POST /users/{id}(수정)를 사용합니다. 목록 화면의 삭제 버튼은 작은 폼입니다. 없는 사용자를 수정하거나 삭제하면 404입니다. REST API에서는 Chapter 05처럼 PUT/DELETE를 쓰던 것과 대비됩니다.

동작 화면 요청 REST API(Chapter 05)
등록 POST /users POST /users
수정 POST /users/{id} PUT /users/{id}
삭제 POST /users/{id}/delete DELETE /users/{id}

순환 검증이 될 뻔한 테스트

Flash 메시지를 테스트로 고정하려고 처음에는 flashAttr("message", ...)로 값을 직접 넣어 목록 화면에 보이는지 확인했습니다. 이 테스트는 컨트롤러가 Flash 속성을 넣지 않아도 통과합니다. 테스트가 컨트롤러의 일을 대신해 버렸기 때문입니다. 이런 테스트를 순환 검증이라고 부릅니다.

그래서 POST의 결과에서 세션을 꺼내 같은 세션으로 GET을 두 번 하는 방식으로 바꿨습니다. 첫 번째 GET에는 안내가 보이고 두 번째에는 사라져야 합니다. 그리고 컨트롤러에서 addFlashAttribute 줄을 지워 이 테스트가 실패하는지 확인했습니다.

UserPageTests > createRedirectsAndShowsFlashMessageOnce() FAILED
    java.lang.AssertionError: Flash attribute 'message' expected:<등록했습니다: kim> but was:<null>

확인한 뒤 줄을 되돌렸습니다. 테스트가 정말 구현을 검증하는지는 구현을 일부러 망가뜨려 실패하는지로 확인할 수 있습니다. 이 습관은 Chapter 19의 테스트 설계에서 다시 만납니다.

테스트 14건

확인하는 것
등록 성공: 302, 목록 반영
검증 실패: 200, 입력값 유지, 오류 문구
변환 오류: 나이는 숫자로 입력해 주세요, Failed to convert가 없음
중복 이메일: 필드 오류, 수정 시 자기 이메일은 허용
Flash 메시지가 한 번만 보임
새로고침이 사용자를 추가하지 않음
없는 사용자 수정·삭제는 404
입력값 이스케이프
OS 실행 이 Chapter만 테스트
Linux / macOS ./gradlew :examples:ch20-thymeleaf-crud:bootRun ./gradlew :examples:ch20-thymeleaf-crud:test
Windows gradlew.bat :examples:ch20-thymeleaf-crud:bootRun gradlew.bat :examples:ch20-thymeleaf-crud:test

14건이 모두 통과했습니다. 동시 요청에서의 중복 이메일 방어는 테스트하지 않았습니다.

따라 하기

./gradlew :examples:ch20-thymeleaf-crud:test

실행해 14건이 모두 통과하는지 확인합니다. 결과는 build/reports/tests/test/index.html 또는 build/test-results/test/*.xml에서 볼 수 있습니다.

직접 해 보기

  1. Flash 테스트에서 addFlashAttribute 줄을 지우고 실패를 확인한 뒤 복원하세요.
  2. 순환 검증이 될 수 있는 자신의 테스트를 하나 떠올려 보세요.
  3. 삭제를 GET 링크로 만들면 어떤 위험이 있는지 생각해 보세요(검색 엔진이 링크를 따라가는 경우 등).

폼 오류 읽기

폼 오류는 화면이 안 나오는 경우와 화면은 나오는데 검증이 동작하지 않는 경우로 나뉩니다. 후자가 더 찾기 어렵습니다. 아래는 이 예제를 한 군데씩 망가뜨려 얻은 결과입니다. 바꾼 코드는 되돌렸고 저장소에는 올리지 않았습니다.

1. Invalid property ‘emial’ of bean class

th:field="*{email}"을 *{emial}로 틀리면 폼 화면 자체가 열리지 않습니다. 14건 중 8건이 실패했습니다.

Invalid property 'emial' of bean class [com.jqdom.curriculum.ch20.UserForm]: Bean property 'emial' is not readable or has an invalid getter method: Does the return type of the getter match the return type of the setter?

th:field는 폼 객체의 getter로 읽으므로 getter가 있는 이름이어야 합니다.

2. Neither BindingResult nor plain target object for bean name ‘userForm’

컨트롤러가 폼 객체를 userForm이 아닌 form이라는 이름으로 모델에 넣으면 템플릿의 th:object="${userForm}"가 대상을 찾지 못합니다. 1건이 실패했습니다.

Exception evaluating SpringEL expression: "#fields.hasErrors('*')" (template: "users/form" - line 9, col 6)
Neither BindingResult nor plain target object for bean name 'userForm' available as request attribute

처음 터지는 곳은 th:field가 아니라 폼 맨 위의 #fields.hasErrors('*')입니다. 메시지의 'userForm'이 템플릿이 기대한 이름입니다.

3. BindingResult 위치가 틀리면 검증 화면이 사라진다

@Valid 폼 객체 바로 뒤에 BindingResult가 와야 하는데 중간에 Model을 끼웠습니다. 14건 중 4건이 실패했고 증상은 오류 메시지가 아니라 응답 상태가 달라진 것이었습니다.

nonNumericAgeIsConversionError()
AssertionError: Status expected:<200> but was:<400>
No ModelAndView found

BindingResult가 @Valid 인자 바로 뒤에 없으면 Spring이 검증 오류를 컨트롤러에 넘기지 않고 예외로 처리해 400이 됩니다. 폼이 다시 그려지지 않고 오류 화면 대신 400이 나온다면 파라미터 순서를 확인합니다. 400이 되는 내부 원인은 일반적인 Spring MVC 동작에 의존한 설명이고, 이 Chapter에서는 상태 코드와 No ModelAndView found까지만 확인했습니다. 이런 순서 규칙은 알아야 찾을 수 있다는 점이 함정입니다.

4. 메시지 키가 틀리면 영어 변환 메시지가 노출된다

typeMismatch.userForm.age를 typeMismatch.form.age로 틀리게 적었습니다. 1건이 실패했습니다. 키의 폼 객체 이름이 userForm과 달라 메시지를 찾지 못하고 기본 영어 변환 메시지가 그대로 화면에 노출됩니다.

증상 가장 먼저 볼 것
폼 화면이 열리지 않고 Invalid property th:field 이름과 getter
Neither BindingResult nor plain target object 모델에 넣은 폼 객체 이름과 th:object
검증 실패인데 400 BindingResult가 @Valid 인자 바로 뒤인지
변환 오류 문구가 영어 typeMismatch.{폼 객체 이름}.{필드} 키

지금의 한계

브라우저에서 새로고침했을 때 POST가 다시 전송되지 않는 동작, 동시 요청에서의 중복 이메일 방어는 확인하지 않았습니다. 다국어 메시지, CSRF 토큰은 다루지 않았습니다. CSRF 같은 보안 설정은 Chapter 21에서 다룹니다.

직접 해 보기

  1. 위 네 가지 중 두 가지를 복사본에서 재현하세요.
  2. BindingResult 위치 실수에서 왜 오류가 400으로 나타나는지 Caused by를 따라가 보세요.
  3. 오류 표를 자신의 말로 다시 정리해 보세요.

자주 하는 실수와 점검 순서

Chapter 전체에서 만날 수 있는 실수를 증상이 드러나는 시점 순서로 모았습니다. 화면을 열 때 문제가 나면 “화면 요청” 행부터, 폼을 보낸 뒤 이상하면 “폼 제출” 행부터 봅니다. 오류 메시지 원문은 앞의 “화면 렌더링 오류 읽기”와 “폼 오류 읽기” 절에 있습니다.

시점 증상 원인 해결
화면 요청 템플릿을 찾지 못한다는 오류 @Controller에서 반환 문자열을 데이터로 오해 뷰 이름과 파일 경로 일치 확인
화면 요청 화면 대신 users/list라는 글자가 응답 @RestController를 붙임 화면용 컨트롤러는 @Controller
화면 요청 렌더링 오류(앞의 “4. 모델 이름이 다르다” 절) Model에 넣은 이름과 템플릿의 ${...} 이름 불일치 이름을 일치
화면 요청 화면에 ${user.name} 글자가 나옴 th:text를 쓰지 않고 ${...}를 본문에 그대로 적음 th:text 사용(또는 인라인 표기)
화면 요청 컨텍스트 경로, 인코딩 문제 링크를 문자열 이어 붙이기로 작성 @{...} 표현식
화면 요청 EL1008E 등 렌더링 오류 th:each 변수 이름과 ${} 안 이름 불일치 반복 변수 이름 확인
화면 요청 화면에 &amp;lt;가 보임 이스케이프를 서버에서 한 번 더 함 출력 시점에 한 번만
화면 요청 Error resolving fragment 조각 이름 오타(nav → navv) th:fragment와 :: 뒤 이름 일치
화면 요청 조각 호출 오류 조각 안의 매개변수 개수 불일치 정의와 호출의 인자 맞추기
화면 요청 기본 오류 페이지가 나옴 error/404.html 위치 오류 templates/error/404.html 경로 확인
화면 요청 curl로 404 페이지를 확인했는데 JSON이 나옴 요청에 Accept: text/html 헤더가 없음 -H 'Accept: text/html' 추가
화면 요청 Invalid property th:field에 getter 없는 이름을 씀 폼 객체 필드와 getter 확인
폼 제출 폼 전송 값 바인딩 실패 폼 객체를 record로 만듦 getter/setter가 있는 일반 클래스
폼 제출 빈 입력의 오류 처리가 달라짐 나이를 int로 선언 Integer 사용
폼 제출 검증 실패 시 400 BindingResult를 @Valid 인자와 떨어뜨림 @Valid 인자 바로 뒤에 선언
폼 제출 입력값과 오류가 사라짐 검증 실패 시 redirect 사용 같은 뷰를 그대로 반환
폼 제출 영어 문구 노출 변환 오류 메시지 키를 typeMismatch.form.age로 씀 모델 이름 userForm과 일치시킴
폼 제출 새로고침 시 같은 POST 재전송 저장 성공 후 return "users/list" redirect:로 응답
폼 제출 주소에 문구가 붙음 addAttribute로 안내 문구 전달 addFlashAttribute
폼 제출 새로고침한 뒤에도 안내 문구가 계속 남음 목록 템플릿에서 안내 문구의 조건 처리 누락 Flash는 한 번만 전달되는지 테스트
테스트 실제 화면이 다름 테스트가 통과해서 화면도 정상이라 판단 실행해서 응답 확인
테스트 구현이 틀려도 항상 통과(순환 검증) 테스트에서 flashAttr로 값을 직접 넣음 POST 결과의 세션으로 GET을 두 번
테스트 일부러 망가뜨려도 통과할 수 있음 테스트 통과만으로 완료라고 판단 구현을 망가뜨려 실패하는지 확인
설계·보안 입력된 HTML이 그대로 실행됨 줄바꿈을 보여 주려고 th:utext 사용 th:text와 CSS(white-space) 사용
설계·보안 th:utext와 같은 효과 [(${...})] 인라인 표기 사용 사용자 값에는 [[${...}]]
설계·보안 링크를 따라가는 도구가 삭제를 실행 삭제를 GET 링크로 구현 POST 폼 사용

용어와 참고 자료

이 절은 이 Chapter에 나온 용어와 참고한 사이트를 모았습니다. 검증 관련 용어는 Chapter 06의 용어 정리를 참고하세요.

참고한 자료

템플릿과 화면

용어 설명
템플릿 엔진 데이터를 끼워 넣어 HTML 문서를 만들어 주는 도구입니다.
Thymeleaf th: 속성이 붙은 올바른 HTML 템플릿을 쓰는 Spring과 잘 맞는 템플릿 엔진입니다.
뷰 이름 컨트롤러가 돌려주는 화면의 이름입니다. templates/ 아래 .html 파일로 이어집니다.
Model 컨트롤러가 템플릿에 넘길 값을 담는 객체입니다.
th:each 요소를 반복합니다. 두 번째 변수로 순번 등 반복 상태를 얻습니다.
th:if / th:unless 조건에 따라 요소를 넣거나 뺍니다.
@{...} 링크 표현식입니다. 경로 변수를 채워 주소를 만듭니다.
이스케이프 <, > 같은 문자를 HTML이 아닌 글자로 바꾸는 처리입니다.
th:text / th:utext 값을 이스케이프해서/하지 않고 출력합니다.
XSS 공격자가 넣은 스크립트가 다른 사용자의 브라우저에서 실행되는 공격입니다.
조각(fragment) 여러 템플릿이 재사용하는 HTML 일부입니다. th:fragment로 정의, th:replace로 사용합니다.
오류 디스패치 오류 상태에서 서블릿 컨테이너가 오류 페이지로 요청을 다시 넘기는 단계입니다.
EL1008E Spring 표현식에서 속성을 찾지 못했을 때의 오류 번호입니다.

폼

용어 설명
폼 객체 폼의 입력 칸과 바인딩되는 객체입니다. getter/setter가 있는 일반 클래스입니다.
th:object / *{} 폼이 다루는 객체를 지정하고, 그 객체의 속성을 가리킵니다.
th:field id, name, value를 함께 만들어 입력 칸과 속성을 묶습니다.
BindingResult 데이터 바인딩과 검증 오류를 담는 객체입니다. @Valid 인자 바로 뒤에 둡니다.
typeMismatch 변환 오류 메시지를 정하는 메시지 키 접두사입니다.
PRG Post-Redirect-Get. 저장 뒤 redirect해 새로고침의 중복 제출을 막는 패턴입니다.
Flash 속성 redirect 직후의 요청 한 번에만 전달되는 값입니다. 세션에 잠깐 저장됩니다.
순환 검증 테스트가 구현의 일을 대신해서 구현이 틀려도 통과하는 상태입니다.

이 Chapter의 코드

대상 링크
목록·상세 ch19-thymeleaf/
등록·수정·삭제 폼 ch20-thymeleaf-crud/

예제 코드 파일

본문에서 다룬 파일은 예제 저장소의 다음 위치에 있습니다.

대상 링크
컨트롤러 UserPageController.java
테스트 UserPageTests.java
목록 템플릿 list.html
상세 템플릿 detail.html
공통 조각 layout.html
404 템플릿 404.html
폼 객체 UserForm.java
폼 템플릿 form.html
컨트롤러 UserPageController.java
메시지 파일 messages.properties
세션 설정 application.yml
테스트 UserPageTests.java
서비스 UserService.java

직접 해보기

  1. ./gradlew :examples:ch19-thymeleaf:bootRun 뒤 curl -i http://localhost:8080/users로 Content-Type: text/html;charset=UTF-8을 확인하고, @Controller를 @RestController로 바꾸면 응답이 어떻게 달라지는지 확인한 뒤 되돌리세요.
  2. curl -s http://localhost:8080/users/4 | grep -n '이름'으로 같은 값이 th:text와 th:utext에서 어떻게 다르게 나오는지 확인하세요.
  3. curl -i -H 'Accept: text/html' http://localhost:8080/users/999와 Accept 헤더 없는 요청을 비교해 HTML 404 페이지와 JSON 오류 본문이 갈리는지 보세요.
  4. ./gradlew :examples:ch20-thymeleaf-crud:bootRun 뒤 curl -s -i -X POST http://localhost:8080/users -d 'name=k&email=bad&age=abc'로 상태 200과 세 칸의 오류를 확인하고, 정상 값으로 보내 302와 Location을 확인하세요.
  5. 컨트롤러에서 addFlashAttribute 줄을 지우고 ./gradlew :examples:ch20-thymeleaf-crud:test를 실행해 createRedirectsAndShowsFlashMessageOnce가 실패하는지 확인한 뒤 되돌리세요.

이번 장의 정리

이 Chapter에서는 JSON 대신 HTML을 서버에서 만들어, 사용자 목록·상세 화면과 등록·수정·삭제 폼까지 완성했습니다.

  • @Controller는 Model에 값을 담고 뷰 이름을 돌려주며, 뷰 이름은 templates/ 아래 .html 파일로 이어집니다. MockMvc로 뷰 이름과 모델 값을 검증합니다.
  • 템플릿은 th: 속성이 붙은 올바른 HTML입니다. th:each, th:text, th:if, @{...}로 반복, 출력, 조건, 링크를 만듭니다.
  • 사용자 입력은 항상 이스케이프하는 th:text로 출력합니다. th:utext는 신뢰할 수 있는 HTML에만 씁니다.
  • 공통 HTML은 th:fragment와 th:replace로 재사용하고, templates/error/404.html이 404 화면이 됩니다. MockMvc는 오류 페이지까지 가지 않으므로 화면은 실행해서 확인합니다.
  • 폼은 th:object, *{}, th:field로 객체와 이어지고, @Valid 바로 뒤의 BindingResult로 오류를 받아 같은 폼을 입력값과 함께 다시 보여 줍니다. 변환 오류 문구는 typeMismatch 메시지 키로 바꿉니다.
  • 저장 뒤에는 PRG로 redirect하고 안내는 Flash 속성으로 한 번만 보여 줍니다. 테스트는 구현을 일부러 망가뜨려 실패하는지 확인해 순환 검증을 피합니다.
  • 렌더링 오류는 표현식과 줄 번호, 조각 이름, 뷰 이름, 모델 이름 순서로 의심하고, 폼 오류는 th:field 이름, 폼 객체 이름, BindingResult 위치, 메시지 키를 확인합니다.

다음 Chapter 14 React 프런트엔드 연동에서는 서버 렌더링 대신 React가 브라우저에서 화면을 그립니다.

FAQ

자주 묻는 질문

Controller와 RestController의 차이는 무엇인가요?

Controller의 문자열 반환값은 보통 뷰 이름으로 해석되고 RestController의 반환값은 응답 본문으로 직렬화됩니다.

th:text와 th:utext 중 무엇을 써야 하나요?

기본은 HTML을 이스케이프하는 th:text입니다. 신뢰할 수 없는 입력을 th:utext로 출력하면 스크립트가 실행될 수 있습니다.

저장 뒤 redirect하는 이유는 무엇인가요?

새로고침 때 POST가 다시 전송되는 것을 막기 위해서입니다. PRG는 POST 처리 후 GET으로 이동합니다.

검증 실패 때도 redirect하나요?

예제는 같은 요청에서 폼 뷰를 다시 렌더링해 BindingResult와 입력값을 유지합니다. 성공했을 때 redirect합니다.

작성·편집 ToolPado

콘텐츠 유형 Spring Boot 학습 가이드

기술 기준 Spring Boot 4.1.1 · JDK 21

마지막 검토