전체 메뉴

테마

Chapter 14

React 프런트엔드 연동

Vite와 React로 목록·상세·폼 화면을 만들고 Spring Boot REST API, 필드 오류, 로딩 상태, CORS를 테스트하며 연동합니다.

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

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

Learning goals

오늘 배울 내용

  • Vite와 React 프로젝트의 실행·빌드·테스트 명령 구분하기
  • 컴포넌트, props, state로 목록과 상세 화면 구성하기
  • React Router로 URL과 화면 연결하기
  • fetch 호출과 서버 필드 오류·로딩 상태를 한곳에서 처리하기
  • CORS의 출처 기준을 이해하고 서버 허용 목록 설정하기
  1. Vite 프로젝트 구성
  2. 컴포넌트와 상태
  3. 라우팅과 테스트
  4. REST API 연동
  5. CORS 검증
이 Chapter의 진행 흐름

Chapter 13에서는 서버가 HTML을 완성해서 보냈습니다. 이번에는 브라우저가 화면을 그립니다. 서버는 데이터(JSON)만 주고, 화면은 React가 만듭니다. 같은 사용자 관리 기능을 다른 방식으로 나눠 보면 각 방식이 무엇을 책임지는지 선명해집니다.

이 Chapter는 두 단계입니다. 먼저 서버 없이 고정 데이터로 React의 구조(컴포넌트, 상태, 라우팅, 테스트)를 익히고(ch21), 이어서 Spring이 만든 REST API와 연결합니다(ch22). 연결하는 순간 포트가 달라서 CORS라는 벽을 만나고, 로딩·오류·빈 목록을 화면이 직접 구분해야 합니다.

이 Chapter에서 만드는 것

만드는 것 설명
Vite + React 프로젝트 Gradle이 아니라 npm으로 도는 examples/ch21-react-basics
사용자 목록·상세 화면 컴포넌트, props, 상태(useState), 라우터
usersApi.js fetch를 한곳에 모은 API 호출 모듈
등록·수정·삭제 화면 서버의 검증 오류를 입력 칸 옆에 표시
CorsConfig 개발 서버의 출처만 허용하는 서버 설정
테스트 ch21: 12건, ch22 화면: 18건, ch22 백엔드: 15건

전체 흐름

  1. 서버 없이 고정 데이터로 React의 구조(컴포넌트, 상태, 라우팅, 테스트)를 익힙니다(ch21).
  2. API 호출 모듈을 만들고 서버의 검증 오류와 로딩 상태를 화면에서 처리합니다(ch22).
  3. CORS를 설정하고, Thymeleaf 방식과 비교한 뒤 연동 오류를 정리합니다.

두 번째 단계부터는 Chapter 13에서 만든 같은 기능을 다른 방식으로 나누는 것이므로 서버 렌더링 방식과 계속 비교합니다.

직접 실행해 확인한 결과

확인 결과
ch21 npm ci → npm test 테스트 12건 통과
ch21 npm run build dist/assets/index-HBGMLdZC.js 260.37 kB
ch22 화면 npm test 테스트 18건 통과(2개 파일)
ch22 백엔드 CORS 응답 허용 출처 200, 비허용 출처 403, Origin 없음 200

사전 지식과 준비물

항목 내용
사전 지식 JavaScript의 변수, 함수, 배열 메서드, 모듈. Chapter 05의 REST API
Node 22.12 이상 필요, 예제는 Node 24에서 확인
코드 examples/ch21-react-basics, examples/ch22-react-rest

확인 환경

Node 24.21.0(Docker node:24-bookworm-slim), React 19.3.1, Vite 8.3.4, react-router 8.4.0, Vitest 5.0.5입니다. 브라우저에서 npm run dev 화면을 직접 열어 보지는 않았고 jsdom 테스트, 빌드, 서버 응답으로 확인했습니다. Node의 fetch는 CORS를 강제하지 않아서 CORS는 서버가 보내는 헤더만 확인했습니다. Windows는 확인하지 못했습니다.

예제 코드

대상 링크
React 기초 ch21-react-basics/
React + REST ch22-react-rest/
package.json package.json
한 행 컴포넌트 components/
목록 화면 UserListPage.jsx
라우팅 App.jsx
테스트 App.test.jsx
API 모듈 api/
화면 코드 pages/
CORS 설정 CorsConfig.java
가짜 fetch test/
백엔드 src/

프로젝트는 Gradle이 아니라 npm으로 돕니다

examples/ch21-react-basics는 Gradle 모듈이 아닙니다. 자바 프로젝트와 달리 의존성은 package.json에 적고 package-lock.json으로 고정하며, 명령도 ./gradlew가 아니라 npm입니다. 이 절에서는 npm 프로젝트의 기본 명령과 버전 고정 방식을 익힙니다.

기본 명령

cd examples/ch21-react-basics
npm ci          # 잠금 파일 그대로 설치
npm run dev     # 개발 서버 http://localhost:5173
npm test
npm run build   # dist/ 에 배포용 파일 생성
명령 하는 일 Gradle에서 비슷한 것
npm ci package-lock.json에 적힌 버전 그대로 설치 의존성 내려받기
npm run dev 개발 서버 실행(Vite) bootRun
npm test 테스트 실행(Vitest) test
npm run build 배포용 파일 생성 build(bootJar)

npm install은 잠금 파일을 갱신할 수 있지만 npm ci는 잠금 파일에 적힌 버전 그대로 설치합니다. 학습 자료는 같은 결과를 내야 해서 package.json의 버전도 ^나 ~ 없이 정확한 값으로 적었습니다(React 19.3.1, Vite 8.3.4, react-router 8.4.0). 이는 Chapter 01에서 Gradle 버전과 Wrapper를 고정하던 이유와 같습니다.

Vite는 무엇인가

Vite는 React 같은 프론트엔드 프로젝트의 개발 서버와 빌드 도구입니다. 코드를 고치면 브라우저에 바로 반영하고(개발), 배포할 때는 파일을 묶고 줄여 dist/에 만듭니다(빌드). Node 22.12 이상이 필요하고 예제는 Node 24에서 확인했습니다.

프로덕션 빌드는 이렇게 끝났습니다.

dist/index.html                   0.40 kB │ gzip:  0.28 kB
dist/assets/index-CchdFZdn.css    0.21 kB │ gzip:  0.17 kB
dist/assets/index-HBGMLdZC.js   260.37 kB │ gzip: 82.74 kB
built in 602ms

따라 하기: 깨끗한 환경에서 확인

Node 22.12 이상이 필요합니다. Node가 없어도 Docker로 같은 결과를 볼 수 있습니다.

cd examples/ch21-react-basics
npm ci
npx vitest run
npm run build

Tests 12 passed (12)와, 빌드 마지막 줄 built in ...ms가 보이면 성공입니다. 재검증에서 node:24-bookworm-slim 컨테이너에서 같은 순서로 실행해 12건 통과와 index-HBGMLdZC.js 260.37 kB를 확인했습니다.

직접 해 보기

  1. 저장소를 받아 npm ci와 npm test를 실행해 12건이 통과하는지 확인하세요.
  2. package.json의 버전 표기에 ^가 없는 것을 확인하세요.
  3. npm run build의 출력 크기를 적어 두고, 컴포넌트를 추가하면 어떻게 달라지는지 비교해 보세요.

컴포넌트는 props를 받아 화면을 돌려주는 함수입니다

React 화면은 컴포넌트라는 함수로 만듭니다. 컴포넌트는 입력(props)을 받아 화면(JSX)을 돌려줍니다. 한 행을 그리는 작은 컴포넌트부터 목록을 그리는 컴포넌트까지, 그리고 Thymeleaf에서 확인했던 이스케이프가 React에서는 어떻게 되는지 봅니다.

한 행을 그리는 컴포넌트

export default function UserRow({ user }) {
  return (
    <tr className={user.active ? undefined : 'inactive'}>
      <td>{user.id}</td>
      <td><Link to={`/users/${user.id}`}>{user.name}</Link></td>
      <td>{user.email}</td>
      <td>{user.active ? '활성' : '비활성'}</td>
    </tr>
  )
}

주요 코드 설명

  • UserRow({ user }): 함수의 인자가 props입니다. { user }는 구조 분해로, 부모가 <UserRow user={...} />로 넘긴 값을 받습니다.
  • JSX의 { ... } 안은 자바스크립트 표현식입니다. {user.name}은 값을 출력하고, className={조건 ? undefined : 'inactive'}는 조건부 클래스입니다. Thymeleaf의 th:text, th:classappend에 해당합니다(Chapter 13).
  • <Link to=...>는 라우터의 링크입니다(아래 “라우트 정의” 절).
  • 컴포넌트는 props만 보고 화면을 정합니다. 같은 props면 같은 화면입니다.

목록과 key

목록을 그리는 쪽은 users.map으로 행을 만들고 항목마다 key를 줍니다.

{users.map((user) => <UserRow key={user.id} user={user} />)}

key는 React가 어느 항목이 바뀌었는지 알아보는 표식입니다. 배열의 순번보다 user.id처럼 항목 고유의 값이 맞습니다. key를 빼면 화면은 그대로인데 경고만 납니다(아래 “1. key 경고: 테스트는 통과한다” 절).

이스케이프는 기본으로 적용된다

Chapter 13의 th:text처럼, {user.name}은 값을 글자로 출력합니다. 이름이 <b>choi</b>인 사용자를 같은 데이터로 넣었는데 태그가 아니라 글자로 나옵니다. 테스트가 이를 확인합니다.

expect(screen.getByText('<b>choi</b>')).toBeInTheDocument()
expect(container.querySelector('b')).toBeNull()

Thymeleaf에서는 th:utext를 일부러 쓰지 않는 한 안전하고, React에서는 dangerouslySetInnerHTML을 일부러 쓰지 않는 한 안전하다고 알려져 있습니다. 후자는 이 Chapter에서 다루지 않았습니다.

데이터가 흐르는 방향

부모 컴포넌트는 users 배열을 map으로 돌며 항목마다 key={user.id}와 user props를 넘겨 UserRow를 만들고, 각 UserRow는 받은 props로 JSX를 만들어 화면의 한 행을 그립니다.

props는 부모에서 자식으로 한 방향으로만 흐릅니다. 자식이 props를 직접 바꾸지 않습니다.

직접 해 보기

  1. UserRow의 key를 지우고 테스트 출력(stderr)의 경고를 찾으세요(복원).
  2. 이름을 <script>가 들어간 값으로 바꿔 글자로 나오는지 확인하세요.
  3. UserRow에 “이메일 마스킹” 같은 가공을 추가한다면 어디에 둘지 생각해 보세요.

상태가 바뀌면 화면이 다시 그려집니다

Thymeleaf에서는 요청마다 서버가 화면을 새로 만들었습니다. React에서는 브라우저 안에서 사용자가 체크박스를 누르거나 글자를 입력하면 화면이 곧바로 바뀝니다. 이를 가능하게 하는 것이 상태(state)입니다. 상태가 바뀌면 컴포넌트가 다시 그려집니다.

상태 둘, 파생 값 하나

목록 화면에는 상태가 둘 있습니다. “활성만 보기” 체크 여부와 이름 검색어입니다.

const [activeOnly, setActiveOnly] = useState(false)
const [keyword, setKeyword] = useState('')
const visibleUsers = useMemo(
  () => users.filter((user) =>
    (!activeOnly || user.active) &&
    user.name.toLowerCase().includes(keyword.trim().toLowerCase())),
  [activeOnly, keyword],
)

주요 코드 설명

  • useState(false): 초기값이 false인 상태를 만들고 [현재 값, 바꾸는 함수]를 돌려줍니다. setActiveOnly(true)처럼 호출하면 값이 바뀌고 컴포넌트가 다시 그려집니다.
  • visibleUsers는 상태로 따로 저장하지 않고 두 상태에서 계산합니다. 상태가 늘수록 서로 어긋날 가능성이 커지므로, 계산할 수 있는 값은 계산하는 쪽이 안전합니다.
  • useMemo(계산, [의존 값들]): 의존하는 값이 바뀔 때만 다시 계산합니다. 이 예제는 데이터가 5건이라 없어도 되지만 의존 배열을 읽는 연습을 위해 두었습니다.
  • 조건식 (!activeOnly || user.active): 체크가 꺼져 있으면 모두 통과, 켜져 있으면 활성 사용자만 통과합니다. 이 식을 뒤집으면 아래 “4. 필터 조건을 뒤집으면” 절의 오류가 납니다.

useEffect: 화면 밖의 것 맞추기

useEffect는 화면에 반영한 뒤 화면 밖의 것을 맞출 때 씁니다. 예제에서는 문서 제목입니다.

useEffect(() => {
  document.title = '사용자 목록 - ch21'
}, [])

의존 배열이 비어 있어 처음 한 번만 실행됩니다. 테스트는 렌더링 뒤 document.title이 바뀌었는지 확인합니다. 서버에서 데이터를 가져오는 것도 보통 useEffect에서 시작하며, 아래 “로딩, 오류, 빈 목록”과 “cancelled 표시” 절에서 다룹니다.

상태가 바뀔 때 일어나는 일을 순서대로 적으면 다음과 같습니다.

  1. 사용자가 체크박스나 입력 칸을 조작합니다.
  2. set... 함수 호출로 상태가 바뀝니다.
  3. 컴포넌트 함수가 다시 실행됩니다.
  4. 파생 값을 다시 계산하고 새 화면을 그립니다.
  5. 화면에 반영된 뒤, 의존 배열 조건에 맞으면 useEffect가 실행됩니다.

확인 문제

  1. visibleUsers를 상태가 아니라 계산으로 두는 이유는 무엇인가요?
  2. useEffect(..., [])는 언제 실행되나요?

답: 1) 상태가 늘수록 서로 어긋날 위험이 커지므로, 다른 상태에서 구할 수 있는 값은 매번 계산하는 편이 안전합니다. 2) 화면에 처음 반영된 뒤 한 번만 실행됩니다.

직접 해 보기

  1. 검색어 칸에 “ki”를 입력해 목록이 줄어드는 것을 개발 서버에서 확인하세요(브라우저가 있다면).
  2. visibleUsers를 상태로 저장하는 방식으로 바꾸면 어떤 어긋남이 생길 수 있는지 적어 보세요.
  3. useEffect의 의존 배열을 [activeOnly]로 바꾸면 언제 실행될지 예측해 보세요.

라우터가 주소와 화면을 연결합니다

React는 보통 HTML 파일 하나(index.html)를 로드한 뒤 자바스크립트로 화면을 바꿉니다. 주소(/users, /users/3)에 따라 어떤 컴포넌트를 보여 줄지 정해 주는 것이 라우터입니다. Spring MVC에서 @GetMapping이 주소와 메서드를 연결하던 역할을 브라우저 안에서 합니다.

라우트 정의

<Routes>
  <Route path="/" element={<UserListPage />} />
  <Route path="/users" element={<UserListPage />} />
  <Route path="/users/:id" element={<UserDetailPage />} />
  <Route path="*" element={<NotFoundPage />} />
</Routes>

주요 코드 설명

  • path="/users/:id": :id는 경로 변수입니다. Spring의 @PathVariable(Chapter 04)과 같은 개념입니다.
  • path="*": 위에서 매칭되지 않은 모든 주소입니다. 정의되지 않은 경로(/nope)와 없는 사용자는 같은 “찾을 수 없습니다” 화면을 보여 줍니다.
  • 상세 화면은 useParams()로 :id를 읽습니다. 경로에서 온 값은 항상 문자열이라서 숫자 id와 비교하려면 String(candidate.id) === id처럼 타입을 맞춰야 합니다.

서버로 가지 않는 이동

링크를 누르면 서버에 요청하지 않고 브라우저 안에서 화면만 바뀌는 것으로 알려져 있습니다. 주소 표시줄은 바뀌지만 페이지는 다시 로드되지 않습니다. 이 설명은 라우터 문서에 의존했고, jsdom 테스트는 화면 전환만 확인했습니다.

그래서 실제 서버에 배포할 때는 /users/1을 직접 열어도 index.html을 돌려주도록 서버를 설정해야 합니다. 이 설정은 이 Chapter에서 다루지 않았습니다.

따라 하기

테스트에서 주소를 바꿔 확인합니다.

cd examples/ch21-react-basics
npx vitest run

테스트 12건 안에 /users/999 같은 없는 주소와 링크 이동이 포함되어 있습니다. 개발 서버를 직접 띄워(npm run dev) 브라우저 주소창에서 /users/999를 입력해 “찾을 수 없습니다”를 확인해 보세요(이 화면은 직접 열어 보지 않았습니다).

직접 해 보기

  1. 주소를 /users/999로 바꿔 “찾을 수 없습니다”가 나오는지 확인하세요.
  2. useParams()로 받은 id의 타입을 console.log(typeof id)로 확인하세요.
  3. Spring MVC의 @GetMapping과 라우터의 Route를 비교해 같은 점과 다른 점을 적어 보세요.

테스트는 사용자가 보는 것을 확인합니다

React 화면 테스트의 원칙은 구현이 아니라 사용자가 보는 것을 확인하는 것입니다. 상태 변수나 함수 이름이 아니라, 화면에 어떤 글자가 보이는지, 버튼을 누르면 무엇이 사라지는지를 검사합니다. Vitest와 Testing Library로 이를 구현합니다.

테스트 예

it('활성만 보기를 켜면 비활성 사용자가 사라진다', async () => {
  const user = userEvent.setup()
  renderAt('/users')
  await user.click(screen.getByLabelText('활성만 보기'))
  expect(screen.queryByText('park@example.com')).not.toBeInTheDocument()
  expect(screen.getByTestId('count')).toHaveTextContent('3')
})

주요 코드 설명

  • renderAt('/users'): 지정한 주소에서 앱을 그리는 도우미입니다.
  • screen.getByLabelText('활성만 보기'): 화면의 “활성만 보기”라는 라벨이 붙은 입력을 찾습니다. 사용자가 보는 방식으로 요소를 찾는 것이 Testing Library의 철학입니다.
  • user.click(...): 실제 사용자처럼 클릭 이벤트를 일으킵니다.
  • queryByText(...)는 없으면 null을 돌려주어 not.toBeInTheDocument()로 “없음”을 검사할 수 있습니다. getBy...는 없으면 오류를 던집니다.
  • 브라우저가 아니라 Node에서 도는 가짜 DOM(jsdom)이고, 라우터는 실제 주소 대신 MemoryRouter로 구동합니다.

12건이 모두 통과했습니다.

 src/App.test.jsx (12 tests)
 Test Files  1 passed (1)
      Tests  12 passed (12)

테스트가 정말 잡는지도 확인한다

필터 조건 (!activeOnly || user.active)를 일부러 true로 바꿔 보았습니다.

FAIL  src/App.test.jsx > 목록 화면 > 활성만 보기를 켜면 비활성 사용자가 사라진다
expected document not to contain element, found <td>
Tests  1 failed | 11 passed (12)

필터를 깨뜨리면 그 한 건만 실패합니다. 확인한 뒤 원래 코드로 되돌렸습니다. 이는 Chapter 13에서 본 “구현을 망가뜨려 테스트가 잡는지 확인”과 같은 습관입니다. 자바 쪽 테스트 전략은 Chapter 19에서 이어집니다.

테스트 쿼리 고르는 순서

  1. 사용자가 읽는 글자나 라벨이 있으면 getByLabelText, getByText, getByRole로 찾습니다.
  2. 그런 글자나 라벨이 없을 때만 최후의 수단으로 getByTestId를 씁니다.
  3. 요소가 없다는 것까지 검사해야 하면 queryBy...와 not.toBeInTheDocument()를 씁니다.

따라 하기

cd examples/ch21-react-basics && npx vitest run
 Test Files  1 passed (1)
      Tests  12 passed (12)

직접 해 보기

  1. npm test를 실행하고 테스트 이름 12개를 읽어 보세요.
  2. 필터 조건을 직접 뒤집어 어떤 테스트가 실패하는지 보고 복원하세요.
  3. getByLabelText와 getByTestId의 차이를 생각해 보세요(사용자가 보는 것 vs 개발자용 표식).

React 오류 네 가지

React 오류는 콘솔 경고로 오는 것과 화면이 틀리게 나오는 것으로 나뉩니다. 아래는 이 예제의 코드를 한 군데씩 바꿔 테스트(vitest)를 돌린 결과입니다. 기준 상태에서는 12건이 모두 통과합니다. 스크래치 복사본에서 실행했고 원본 저장소는 바꾸지 않았습니다.

1. key 경고: 테스트는 통과한다

UserTable에서 <UserRow key={user.id} .../>의 key를 지웠습니다. 테스트 12건이 모두 통과했지만 콘솔(stderr)에 경고가 남았습니다.

stderr | src/App.test.jsx > 목록 화면 > 모든 사용자를 행으로 그린다
Each child in a list should have a unique "key" prop.
Check the render method of `UserTable`. See https://react.dev/link/warning-keys for more information.

화면은 그대로인데 경고만 나오는 오류라서 가장 놓치기 쉽습니다. 메시지가 어느 컴포넌트(UserTable)를 가리키는지 알려 주므로, 목록을 그리는 map 안의 최상위 요소에 안정적인 key를 줍니다. 경고가 있어도 통과하는 테스트만 믿지 말고 테스트 출력의 stderr도 살펴봅니다.

2. 상세 화면이 “찾을 수 없음”이 된다: 문자열과 숫자

String(candidate.id) === id를 candidate.id === id로 바꿨습니다. 경로의 :id는 문자열인데 데이터의 id는 숫자라서 항상 다릅니다.

링크를 누르면 상세 화면으로 이동한다
TestingLibraryElementError: Unable to find an accessible element with the role "heading" and name "사용자 상세"

12건 중 1건만 실패했습니다. 에러가 아니라 “없음 화면”이 뜨기 때문에 코드는 정상으로 도는 것처럼 보입니다. 단서는 데이터는 분명히 있는데 없다고 나온다는 점입니다. 경로에서 온 값은 항상 문자열이라는 사실(앞의 “라우트 정의” 절)을 떠올리고 비교하는 두 값의 타입을 확인합니다.

3. Router 없이 렌더링하면

테스트에서 MemoryRouter로 감싸지 않고 <App />을 그리면 12건이 모두 실패합니다.

TypeError: Cannot destructure property 'basename' of 'React$1.useContext(...)' as it is null.

메시지가 라우터라는 말을 하지 않아 원인을 짐작하기 어렵습니다. Link나 Routes가 라우터 컨텍스트 없이(useContext가 null) 렌더링된 것입니다. 앱에서는 main.jsx가 라우터로 감싸고, 테스트에서는 MemoryRouter로 감싸야 합니다.

4. 필터 조건을 뒤집으면

(!activeOnly || user.active)를 (activeOnly || user.active)로 바꿨습니다. 기본 상태에서도 5명이 아니라 4명만 보입니다.

AssertionError: expected [ …(4) ] to have a length of 5 but got 4
Unable to find an element with the text: park@example.com
expected document not to contain element, found <td>

12건 중 3건이 실패했습니다. 이 예제의 테스트가 화면에 보이는 행의 수와 내용을 직접 검사하기 때문에 잡힌 것입니다. 파생 값의 조건식은 true/false 조합을 모두 눌러 보는 테스트가 있어야 안전합니다.

증상 가장 먼저 볼 것
콘솔에 unique "key" prop 목록을 그리는 map의 key
데이터가 있는데 없음 화면 경로 값(문자열)과 데이터(숫자)의 타입
Cannot destructure property 'basename' 라우터(MemoryRouter)로 감쌌는지
필터 결과 개수가 틀림 파생 값의 조건식, 상태의 초기값

지금의 한계

npm run dev 개발 서버를 브라우저에서 열어 보지 않았고, 링크 클릭이 서버 요청 없이 화면만 바꾼다는 설명은 라우터 문서에 의존했습니다. 배포 서버의 index.html 폴백 설정은 다루지 않았습니다.

직접 해 보기

  1. 위 네 가지 중 두 가지를 복사본에서 재현해 보세요.
  2. 1번에서 npx vitest run의 stderr 위치를 찾아보세요.
  3. 오류 표를 자신의 말로 다시 정리해 보세요.

API 호출은 한곳에 모읍니다

여기부터는 이 화면을 서버와 연결합니다(ch22).

이제 고정 데이터 대신 Spring이 만든 REST API에서 데이터를 받습니다. 컴포넌트마다 fetch를 직접 부르면 오류 처리가 흩어지므로, API 호출은 usersApi.js 한 파일에 모았습니다. 이 절에서는 fetch의 가장 큰 함정(HTTP 오류에서 예외를 던지지 않는다)과 그 대응을 봅니다.

공통 요청 함수

async function request(path, options = {}) {
  const response = await fetch(`${BASE}${path}`, {
    ...options,
    headers: options.body ? { 'Content-Type': 'application/json' } : undefined,
  })
  const text = await response.text()
  const body = text ? JSON.parse(text) : null
  if (!response.ok) {
    throw new ApiError(response.status, body)
  }
  return body
}

주요 코드 설명

  • fetch는 404나 500 같은 HTTP 오류에서도 예외를 던지지 않고 성공한 것처럼 Response를 돌려줍니다. 예외가 나는 경우는 네트워크가 끊겼을 때뿐입니다. 그래서 response.ok를 직접 확인해 ApiError로 던집니다.
  • new ApiError(response.status, body): 상태 코드와 서버가 보낸 오류 본문을 함께 담습니다. 화면이 error.body.issues를 읽을 수 있게 하려는 것입니다.
  • 삭제는 204로 본문이 없어서 response.text()가 빈 문자열입니다. text ? JSON.parse(text) : null로 본문이 비었는지 먼저 확인합니다.
  • headers는 본문이 있을 때만 Content-Type: application/json을 붙입니다.
  • BASE: API 주소는 환경 설정(.env.development)에서 읽습니다. 이 파일이 저장소에서 빠졌을 때의 문제는 아래 “2. 깨끗한 클론에서만 API 주소를 모른다” 절에서 봅니다.

테스트 6건이 고정하는 것

확인
본문이 없으면 Content-Type을 붙이지 않는다
204가 null로 돌아온다
HTTP 오류가 ApiError가 된다
네트워크 오류는 fetch가 던진 예외 그대로 전달된다

이 구조는 서버(Chapter 06의 공통 응답과 예외 처리)와 짝입니다. 서버가 오류를 일정한 모양으로 돌려주기 때문에 화면이 일정하게 처리할 수 있습니다.

서버의 오류 응답 모양

{"code":"VALIDATION_FAILED","message":"요청 값이 올바르지 않습니다",
 "issues":[{"field":"email","reason":"이메일 형식이 올바르지 않습니다"},
           {"field":"age","reason":"나이는 필수입니다"},
           {"field":"name","reason":"이름은 2자 이상 20자 이하여야 합니다"}]}

Chapter 12의 ErrorBody와 같은 형식입니다. 이것이 서버와 화면 사이의 계약이고, code로 분기하고 issues로 필드 오류를 보여 줍니다. 위 응답은 실제 백엔드 JAR에 usersApi.create({ name: 'r', email: 'bad', age: null })를 호출해서 받은 것입니다.

검증 오류가 화면까지 오는 순서는 이렇습니다. 컴포넌트가 create(form)을 부르면 usersApi.js의 request가 fetch로 POST /api/users를 보냅니다. Spring API가 400과 오류 본문을 돌려주면 request가 ApiError(400, body)를 던지고, 컴포넌트는 error.body.issues를 입력 칸 옆에 표시합니다.

따라 하기(화면 테스트 실행)

cd examples/ch22-react-rest/frontend
npm ci
npx vitest run

재검증에서 확인한 결과는 Test Files 2 passed, Tests 18 passed입니다(API 모듈 테스트 6건 포함).

확인 문제

  1. fetch가 예외를 던지는 경우는 언제인가요?
  2. 서버와 화면 사이의 “계약”은 무엇을 가리키나요?

답: 1) 서버에 연결하지 못하는 네트워크 오류 같은 경우입니다. HTTP 404/500은 예외가 아닙니다. 2) 서버가 돌려주는 오류 본문의 모양(code, message, issues)입니다.

직접 해 보기

  1. response.ok 확인을 지우면 404 응답이 어떻게 처리될지 예측해 보세요.
  2. 서버를 끄고 호출하면 ApiError가 아니라 어떤 예외가 나는지 확인해 보세요(브라우저가 있다면).
  3. 204 응답에서 response.json()을 쓰면 어떤 문제가 생길지 생각해 보세요.

서버 오류는 입력 칸 옆에, 로딩과 빈 목록은 따로 보여 줍니다

Thymeleaf에서는 서버가 끝낼 때까지 브라우저가 기다렸고, 검증 오류는 서버가 같은 폼을 다시 그려 주었습니다(Chapter 13). React에서는 응답이 오기 전의 화면과 오류를 받은 뒤의 화면을 직접 정해야 합니다. 이 절은 필드 오류 표시와 로딩·오류·빈 목록 세 가지 상태 구분을 다룹니다.

필드 오류 연결

function toFieldErrors(error) {
  const result = {}
  for (const issue of error.body?.issues ?? []) {
    result[issue.field] = issue.reason
  }
  return result
}

issues 배열을 { email: '...', age: '...' } 모양으로 바꾸면, 각 입력 칸이 자기 이름의 오류만 꺼내 옆에 보여 줄 수 있습니다. 중복 이메일은 409로 오고 issues에 email 필드가 들어 있어 같은 코드로 이메일 칸 옆에 표시됩니다.

DUP 409 {"code":"DUPLICATE_EMAIL","message":"이미 사용 중인 이메일입니다","issues":[{"field":"email",...}]}

필드와 무관한 오류(서버 오류 500 등)는 폼 위쪽에 보여 줍니다.

폼 값은 항상 문자열

폼 입력값은 항상 문자열입니다. 나이 칸은 Number(form.age)로 바꿔 보내고, 비어 있으면 null을 보냅니다. null을 보내면 서버에서 “나이는 필수입니다”라는 필드 오류가 돌아오고 나이 칸 옆에 보입니다. 빈 문자열("")을 JSON으로 보내면 서버는 400을 돌려주었지만, 응답 본문은 확인하지 않았습니다.

로딩, 오류, 빈 목록

{error ? (
  <p className="error" role="alert">목록을 불러오지 못했습니다: {error.message}
    <button onClick={() => load()}>다시 시도</button></p>
) : users === null ? (
  <p>불러오는 중...</p>
) : users.length === 0 ? (
  <p>등록된 사용자가 없습니다.</p>
) : ( /* 표 */ )}
  • users가 null이면 아직 받지 못한 것이고, 빈 배열이면 받았는데 없는 것입니다. 이 둘을 구분하지 않으면 로딩 중에 “등록된 사용자가 없습니다”가 잠깐 보입니다.
  • role="alert"는 오류 영역을 화면 낭독기와 테스트가 알아보게 합니다.
  • 테스트는 첫 요청이 실패하고 “다시 시도”를 누르면 성공하는 흐름도 확인합니다.

cancelled 표시

useEffect 안에서 응답을 받는 코드는 화면이 사라진 뒤 도착한 응답으로 상태를 바꾸지 않게 cancelled 표시를 두었습니다. 개발 모드의 StrictMode는 효과를 두 번 실행하기 때문에 첫 실행의 응답이 무시되는지 확인하기 좋습니다. 이 효과와 cancelled의 영향은 React 문서의 설명에 의존했고 테스트로 직접 확인하지는 않았습니다.

확인 문제

  1. users === null과 users.length === 0은 각각 무엇을 뜻하나요?
  2. 서버 오류를 입력 칸 옆에 보여 주려면 issues를 어떤 모양으로 바꾸나요?

답: 1) 앞은 아직 응답을 받지 못한 로딩 중, 뒤는 받았는데 데이터가 없는 상태입니다. 2) { 필드이름: 이유 } 객체로 바꿉니다.

직접 해 보기

  1. 서버를 끄고 목록 화면을 열어 오류와 “다시 시도”가 보이는지 확인하세요(브라우저가 있다면).
  2. users === null 검사를 지우고 로딩 중 화면이 어떻게 달라질지 예측하세요.
  3. 이름 칸에 한 글자를 넣고 등록해 입력 칸 옆에 서버 메시지가 나오는지 보세요.

포트가 다르면 CORS가 필요합니다

개발 서버(localhost:5173)에서 API(localhost:8080)를 부르면 브라우저에게는 다른 출처입니다. 서버가 허용하지 않으면 브라우저는 응답을 스크립트에 넘기지 않습니다. 이 규칙이 CORS이고, 서버 설정으로 풉니다. 가장 흔한 오해는 “CORS가 서버를 보호한다”는 것인데, 아래 실험으로 바로잡습니다.

출처란

출처는 프로토콜 + 호스트 + 포트입니다. http://localhost:5173과 http://localhost:8080은 포트가 달라서 다른 출처입니다. 브라우저는 다른 출처로의 요청 결과를 기본적으로 스크립트에 보여 주지 않고, 서버가 “이 출처는 허용한다”고 헤더로 알려야 합니다.

서버 설정

백엔드는 허용할 출처를 설정에서 읽어 /api/**에 적용합니다.

registry.addMapping("/api/**")
        .allowedOrigins(allowedOrigins)          // 설정: http://localhost:5173
        .allowedMethods("GET", "POST", "PUT", "DELETE")
        .allowedHeaders("Content-Type")
        .exposedHeaders("Location")
        .maxAge(3600);

주요 코드 설명

  • addMapping("/api/**"): 이 경로에만 적용합니다.
  • allowedOrigins: 설정에서 읽은 출처만 허용합니다. *로 모두 열지 않았습니다.
  • allowedMethods: PATCH는 목록에 없어 허용되지 않습니다(테스트가 확인).
  • exposedHeaders("Location"): Location은 CORS에서 기본으로 읽을 수 있는 응답 헤더가 아니라서, 등록 응답의 Location을 화면 코드가 읽으려면 노출해야 합니다. 이 예제의 화면은 Location 대신 응답 본문을 씁니다.
  • maxAge(3600): 사전 요청 결과를 브라우저가 1시간 캐시합니다.

사전 요청(preflight)

JSON 본문을 보내는 POST는 먼저 브라우저가 OPTIONS 사전 요청을 보내 허용 여부를 묻습니다. 실제 서버에서 받은 응답입니다.

OPTIONS /api/users  Origin: http://localhost:5173
                    Access-Control-Request-Method: POST
                    Access-Control-Request-Headers: content-type
-> 200
access-control-allow-origin: http://localhost:5173
access-control-allow-methods: GET,POST,PUT,DELETE
access-control-allow-headers: content-type
access-control-max-age: 3600

허용하지 않은 출처로 보내면 이렇게 됩니다.

OPTIONS /api/users  Origin: http://evil.example
-> 403  Invalid CORS request   (access-control-allow-origin 헤더 없음)

오해 풀기: CORS는 브라우저의 규칙이다

Origin 헤더를 붙이지 않는 요청은 CORS의 영향을 받지 않습니다. GET /api/users/1을 Origin 없이 보내면 200이 오고 CORS 헤더는 붙지 않습니다.

  • CORS는 브라우저가 지키는 규칙이라서 curl 같은 클라이언트는 막지 못합니다.
  • 따라서 CORS는 인증과 인가를 대신하지 않습니다. 접근을 막으려면 Spring Security가 필요합니다.
  • Spring 서버는 허용하지 않은 Origin이 붙은 요청을 사전 요청이 아니어도 403으로 거절하는데, 이는 서버 쪽의 추가 방어일 뿐입니다.

검증 중 이 오해를 한 번 했습니다. CORS 테스트 중 하나가 “허용되지 않은 Origin의 요청도 서버에 도착한다”는 이름과 주석이었지만 실제로는 Spring이 403으로 거절했습니다. 이름을 otherOriginGetIsRejectedByServerToo로 바꾸고, Origin 없는 요청이 CORS 영향을 받지 않는 테스트를 추가했으며, CorsConfig의 주석도 “CORS는 브라우저가 지키는 규칙”이라는 사실에 맞게 고쳤습니다.

브라우저에서의 CORS 차단과 허용 동작은 직접 확인하지 못했습니다. Node의 fetch는 CORS를 강제하지 않으므로, 서버가 보내는 헤더만 확인했습니다.

따라 하기

./gradlew :examples:ch22-react-rest:bootRun
curl -s -i -X OPTIONS http://localhost:8080/api/users -H 'Origin: http://localhost:5173' \
  -H 'Access-Control-Request-Method: POST' -H 'Access-Control-Request-Headers: content-type'
curl -s -i -X OPTIONS http://localhost:8080/api/users -H 'Origin: http://evil.example' \
  -H 'Access-Control-Request-Method: POST'
curl -s -i http://localhost:8080/api/users/1
요청 재검증에서 확인한 응답
허용 출처 사전 요청 200, Access-Control-Allow-Origin: http://localhost:5173, Allow-Methods: GET,POST,PUT,DELETE, Max-Age: 3600, Expose-Headers: Location
비허용 출처 사전 요청 403, 본문 Invalid CORS request, Allow-Origin 없음
Origin 없는 GET 200, CORS 헤더 없음

확인 문제

  1. http://localhost:5173과 http://localhost:8080이 다른 출처인 이유는 무엇인가요?
  2. curl로는 호출되는데 브라우저에서만 막히는 이유는 무엇인가요?

답: 1) 포트가 다르기 때문입니다(프로토콜·호스트·포트가 모두 같아야 같은 출처). 2) CORS는 브라우저가 지키는 규칙이라 브라우저가 응답 헤더를 보고 요청 결과를 차단하기 때문입니다.

직접 해 보기

  1. allowedOrigins에 다른 출처를 추가하고 사전 요청 응답을 curl -X OPTIONS -H "Origin: ..."로 확인하세요.
  2. Origin 없이 같은 API를 호출해 CORS 헤더가 없는 것을 확인하세요.
  3. “CORS가 있으니 API는 안전하다”는 문장이 왜 틀렸는지 설명해 보세요.

Thymeleaf와 React, 가짜 서버와 진짜 서버

같은 사용자 관리 기능을 Chapter 13에서는 Thymeleaf로, 이 Chapter에서는 React와 REST로 만들었습니다. 일을 나누는 위치가 다릅니다. 이 절은 두 방식을 비교하고, 화면 테스트에서 가짜 서버와 진짜 서버를 어떻게 함께 쓰는지 정리합니다.

같은 일을 다르게 나눈다

구분 Thymeleaf (Chapter 13) React + REST (이 Chapter)
화면을 만드는 곳 서버가 HTML을 완성 브라우저가 JSON으로 그림
검증 오류 BindingResult로 같은 폼을 다시 렌더링 issues를 받아 화면 코드가 연결
저장 뒤 이동 서버가 redirect(PRG), 안내는 Flash 화면이 navigate, 안내는 라우터 state
포트와 CORS 같은 출처라 필요 없음 출처가 다르면 서버가 허용
로딩과 오류 브라우저가 기다림 화면 코드가 상태로 구분

저장 뒤 안내 문구는 라우터 state로 넘겼습니다. 새로고침하면 사라지는 점이 Flash 속성(Chapter 13)과 비슷합니다. 어느 쪽이 낫다기보다 서버가 화면까지 책임지느냐, 화면을 클라이언트에 맡기느냐의 선택이고, API를 모바일 앱 같은 다른 클라이언트와 나눠 쓸 수 있는지가 큰 차이입니다. 이 선택은 Chapter 12의 계약 개념과 이어집니다. API가 곧 계약이 되기 때문입니다.

테스트는 가짜 서버로

화면 테스트(18건)는 fetch를 가짜로 바꿔 서버 응답을 흉내 냅니다.

export function installFakeFetch(handler) {
  const calls = []
  const fake = vi.fn(async (url, options = {}) => {
    calls.push({ method: options.method ?? 'GET', url, body: options.body ? JSON.parse(options.body) : undefined })
    const result = await handler(...)
    return new Response(result.body === undefined ? null : JSON.stringify(result.body), { status: result.status ?? 200 })
  })
  vi.stubGlobal('fetch', fake)
  return { calls, fake }
}
  • calls에 어떤 메서드·주소·본문으로 호출했는지 기록합니다. 화면이 올바른 요청을 보냈는지 검사할 수 있습니다.
  • vi.stubGlobal('fetch', fake)로 전역 fetch를 대체합니다.
  • 가짜 서버는 빠르고 오류 상황(400, 409, 500)을 마음대로 만들 수 있습니다.

확인은 진짜 서버로

가짜 서버는 진짜 서버와 어긋날 수 있습니다. 그래서 임시 테스트 파일을 만들어 실제 usersApi.js가 실제 백엔드 JAR를 호출하게 했습니다(확인 후 삭제).

LIST    -> 3명 (kim, lee, park)
CREATED -> {"id":4,"name":"real","email":"real@example.com","age":20}
BAD     -> 400 VALIDATION_FAILED (issues 3건)
DUP     -> 409 DUPLICATE_EMAIL
UPDATED -> {"id":4,"name":"real2",...,"age":21}
REMOVE  -> null (204)
GONE    -> 404 USER_NOT_FOUND

백엔드 쪽 테스트 15건(API 9, CORS 6)은 API, 검증, 중복, 사전 요청 허용과 거절, 허용되지 않은 메서드(PATCH) 거절을 확인합니다. 화면 테스트 18건은 usersApi.test.js 6건과 App.test.jsx 12건입니다.

테스트 장점 한계
가짜 fetch 빠르고 오류를 마음대로 만듦 진짜 응답과 어긋날 수 있음
진짜 서버 확인 계약이 맞는지 실증 느리고 환경이 필요

이 구분은 Chapter 19의 단위 테스트와 Chapter 20의 통합 테스트 전략에서 일반화됩니다.

OS 백엔드 화면
Linux / macOS ./gradlew :examples:ch22-react-rest:bootRun cd examples/ch22-react-rest/frontend && npm ci && npm run dev
Windows gradlew.bat :examples:ch22-react-rest:bootRun 같은 npm 명령

브라우저에서 http://localhost:5173을 엽니다(이 화면은 직접 열어 보지 않았습니다).

어떤 방식을 고를까

  1. 같은 API를 모바일 앱도 써야 한다면 React(또는 JSON API 중심 구조)를 고릅니다.
  2. 그렇지 않고 화면이 단순해 서버 렌더링으로 충분하다면 Thymeleaf를 고릅니다.
  3. 서버 렌더링으로 부족한 화면이라면 React를 고릅니다.

이 순서는 이 과정의 학습용 판단 기준이며, 실제 선택은 팀 상황과 요구에 따라 달라집니다.

직접 해 보기

  1. 두 방식 중 모바일 앱이 같은 API를 쓸 수 있는 쪽이 어느 쪽인지 이유와 함께 적어 보세요.
  2. 가짜 fetch의 calls로 “삭제 버튼이 DELETE /api/users/4를 보냈다”를 검증하는 테스트를 구상해 보세요.
  3. 가짜 응답과 진짜 응답이 어긋난 경험을 떠올려 보세요.

연동 오류: CORS와 .gitignore

프론트와 백엔드가 나뉘면 오류가 어느 쪽에서 났는지부터 가려야 합니다. 아래 두 가지는 이 예제를 검증하면서 실제로 만난 사례를 증상으로 찾을 수 있게 정리한 것입니다.

1. CORS는 브라우저의 규칙이다

허용하지 않은 출처가 사전 요청을 보내면 서버가 403으로 거절합니다.

OPTIONS /api/users  Origin: http://evil.example
-> 403  Invalid CORS request   (access-control-allow-origin 헤더 없음)

그런데 Origin 헤더 없이 curl로 같은 API를 부르면 200이 옵니다. 그래서 curl로는 되는데 브라우저에서만 안 되는 모양이 CORS 문제의 전형입니다. 서버 로그가 아니라 응답에 access-control-allow-origin 헤더가 있는지를 확인합니다. 이 Chapter의 개발 환경에서는 브라우저를 열어 확인하지 못했고, 위 결과는 서버 응답을 직접 확인한 것입니다.

2. 깨끗한 클론에서만 API 주소를 모른다

.env.development가 .gitignore의 .env.* 규칙에 걸려 커밋에서 빠져 있었습니다. 내 PC에서는 파일이 있어서 잘 되고, 새로 클론한 곳에서 npm run dev를 하면 API 주소를 몰랐을 것입니다.

# .gitignore의 .env.* 규칙 때문에 추적되지 않던 공개 설정 파일을
# 예외(!examples/*/frontend/.env.development)로 추적하게 고쳤다

“내 PC에서는 되는데 다른 곳에서는 안 된다”면 git status --ignored로 무시된 파일 중 실행에 필요한 것이 있는지 봅니다. 비밀 값이 들어 있는 .env 파일을 예외로 풀면 안 되고, 공개해도 되는 주소 같은 설정만 따로 둡니다. 비밀값을 환경 변수로 다루는 방법은 Chapter 11의 Oracle 접속 정보와 같은 원칙입니다.

증상 가장 먼저 볼 것
curl은 되는데 브라우저에서만 실패 응답의 access-control-allow-origin, 허용 출처 설정
새로 받은 저장소에서만 API 주소를 모름 .gitignore가 가린 환경 파일
400 응답인데 입력 칸 옆에 안 보임 서버 issues의 field 이름과 폼 필드 이름
목록이 잠깐 “없음”으로 보임 null(로딩)과 빈 배열 구분

마지막 두 행은 실제로 만난 사례가 아니라 앞의 “필드 오류 연결”과 “로딩, 오류, 빈 목록” 절의 설계에서 도출한 점검 항목입니다.

어느 쪽 문제인지 가리는 순서

  1. curl로 호출하면 되는데 브라우저에서만 실패하면 응답의 CORS 헤더와 허용 출처 설정을 봅니다.
  2. curl로도 안 되면 서버 로그에 요청이 도착했는지 봅니다. 도착하지 않았다면 API 주소(VITE_API_BASE), 포트, 서버 기동 여부를, 도착했다면 서버 응답의 상태 코드와 오류 본문을 확인합니다.
  3. 깨끗한 클론에서만 실패하면 .gitignore가 가린 설정 파일을 봅니다.

지금의 한계

브라우저의 CORS 차단·허용 동작, npm run dev 화면, 빈 문자열 나이를 서버에 보냈을 때의 응답 본문은 확인하지 못했습니다. 인증과 CSRF는 다루지 않았습니다.

직접 해 보기

  1. 자신의 프로젝트에서 git status --ignored로 무시된 파일 목록을 확인해 보세요.
  2. 허용 출처를 일부러 틀리게 설정해 사전 요청 응답을 비교하세요.
  3. 이 Chapter 전체에서 “오류가 어느 쪽에서 났는지 가리는” 순서를 한 줄로 적어 보세요.

자주 하는 실수 점검표

증상이 보이면 같은 행의 원인부터 확인합니다.

영역 증상 원인 해결
npm 프로젝트 사람마다 다른 버전 설치 package-lock.json 없이 npm install만 반복 npm ci 사용
npm 프로젝트 설치·실행 시 엔진 경고 또는 오류 Node 버전이 낮음 Node 22.12 이상
npm 프로젝트 저장소가 커지고 충돌 node_modules를 저장소에 커밋 .gitignore에 포함
npm 프로젝트 프로젝트를 찾지 못함 Gradle 명령으로 npm 프로젝트를 실행하려 함 해당 폴더에서 npm 명령
컴포넌트 테스트는 통과, 콘솔 경고 key를 빼먹음 항목 고유 값으로 key
컴포넌트 순서가 바뀌면 상태가 엉킴 배열 순번을 key로 사용 user.id 같은 고유 값
컴포넌트 HTML 태그로 해석됨 컴포넌트 이름을 소문자로 시작 대문자로 시작
컴포넌트 의도와 다르게 동작 props를 자식에서 수정 상태는 부모에서 올려 관리
상태 화면이 안 바뀜 상태 변수를 직접 대입(activeOnly = true) setActiveOnly(true) 호출
상태 상태끼리 어긋남 파생 값을 별도 상태로 저장 계산으로 구함
상태 렌더링마다 실행 useEffect 의존 배열을 빼먹음 의도에 맞는 배열 지정
라우터 데이터가 있어도 “찾을 수 없음” 경로 변수(문자열)와 숫자 id를 ===로 비교 String(id)로 맞춤
라우터 다른 경로도 모두 NotFound path="*"를 맨 위에 둠 구체적인 경로를 먼저, *는 마지막
라우터 /users/1에서 새로고침하면 서버가 404 서버가 index.html을 돌려주지 않음 배포 서버 설정(이 Chapter 범위 밖)
화면 테스트 요소가 없으면 예외로 테스트 실패 getBy로 “없음”을 검사 queryBy + not.toBeInTheDocument
화면 테스트 Cannot destructure property 'basename' Router 없이 렌더링 MemoryRouter로 감쌈
화면 테스트 가끔 실패 비동기 화면을 await 없이 검사 findBy... 또는 await 사용
API 호출 404/500도 성공처럼 처리 response.ok를 확인하지 않음 !response.ok이면 ApiError
API 호출 본문이 없어 파싱 오류 204 응답에 response.json() 호출 text()로 받아 비었는지 확인
API 호출 화면이 필드별 오류를 못 보여 줌 오류 본문을 버리고 상태 코드만 던짐 본문을 ApiError에 담음
API 호출 환경마다 수정 필요 API 주소를 코드에 하드코딩 VITE_API_BASE 환경 설정
오류·로딩 표시 로딩 중에도 “등록된 사용자가 없습니다” users의 초기값을 []로 둠 초기값 null로 로딩 구분
오류·로딩 표시 오류가 칸 옆에 안 보임 서버 필드 이름과 폼 필드 이름이 다름 issues[].field와 입력 name 일치
오류·로딩 표시 서버 변환 오류 나이 칸 값을 문자열 그대로 전송 Number(...), 빈 값은 null
오류·로딩 표시 경고 또는 잘못된 화면 컴포넌트가 사라진 뒤 상태 변경 cancelled 표시
CORS 모든 출처가 허용됨 allowedOrigins("*")로 열어 둠 필요한 출처만 설정
CORS JSON 요청의 사전 요청 실패 allowedHeaders에 Content-Type을 빠뜨림 필요한 헤더 추가
CORS 사전 요청 거절 PATCH를 쓰는데 allowedMethods에 없음 사용하는 메서드를 허용
CORS curl 같은 비브라우저 요청이 그대로 통과함 CORS가 있으니 안전하다고 생각 인증·인가는 별도 구현
테스트 전략 진짜 서버 응답과 어긋남 가짜 fetch 테스트만으로 연동 완료라 판단 진짜 서버로 한 번 확인
테스트 전략 저장소 오염 진짜 서버 확인을 임시 파일로 하고 정리하지 않음 확인 후 삭제
테스트 전략 서버 계약과 다름 가짜 응답의 모양을 임의로 작성 실제 응답 예를 복사

용어와 참고 자료

이 절은 Chapter 14 전체에서 나온 용어와 참고한 사이트를 모았습니다. 서버 렌더링 관련 용어는 Chapter 13 용어 정리를 참고하세요.

프로젝트와 도구

용어 설명
npm Node의 패키지 관리자이자 스크립트 실행 도구입니다.
package-lock.json 설치된 의존성의 정확한 버전을 고정한 파일입니다.
npm ci 잠금 파일 그대로 깨끗이 설치하는 명령입니다.
Vite 개발 서버와 빌드를 제공하는 프론트엔드 도구입니다.
Vitest Vite 기반의 테스트 실행기입니다.
jsdom Node에서 동작하는 가짜 브라우저 DOM입니다.
Testing Library 사용자가 보는 방식으로 화면을 찾고 조작하는 테스트 도구입니다.

React

용어 설명
컴포넌트 props를 받아 화면(JSX)을 돌려주는 함수입니다.
props 부모가 컴포넌트에 넘기는 입력 값입니다.
JSX 자바스크립트 안에 쓰는 HTML 비슷한 문법입니다.
key 목록에서 항목을 식별하는 고유 표식입니다.
상태(state) 바뀌면 컴포넌트를 다시 그리게 하는 값입니다. useState로 만듭니다.
파생 값 다른 값에서 계산할 수 있어 상태로 저장하지 않는 값입니다.
useMemo 의존 값이 바뀔 때만 다시 계산하게 하는 훅입니다.
useEffect 렌더링 뒤 화면 밖의 것을 맞추는 훅입니다.
라우터 주소와 컴포넌트를 연결합니다.
useParams 경로 변수를 읽습니다. 값은 항상 문자열입니다.
MemoryRouter 테스트용으로 주소를 메모리에서 구동하는 라우터입니다.

통신

용어 설명
fetch 브라우저의 HTTP 호출 함수입니다. HTTP 오류에서 예외를 던지지 않습니다.
ApiError 상태 코드와 서버 오류 본문을 담은 예외입니다.
출처(origin) 프로토콜 + 호스트 + 포트입니다.
CORS 다른 출처의 요청 결과를 스크립트에 보여 줄지 서버가 헤더로 허용하는 브라우저 규칙입니다.
사전 요청(preflight) 본 요청 전에 브라우저가 OPTIONS로 허용 여부를 묻는 요청입니다.
exposedHeaders 화면 코드가 읽을 수 있게 노출하는 응답 헤더 목록입니다.

참고 자료

  • React 공식 문서: 컴포넌트, props, 상태, 목록의 key 개념을 확인했습니다.
  • useEffect: 의존 배열이 비어 있을 때 한 번만 실행되는 동작을 확인했습니다.
  • React Router: Routes, Route, useParams의 사용법을 확인했습니다.
  • Vite 가이드: 개발 서버와 빌드 명령을 확인했습니다.
  • Testing Library (React): 사용자 관점의 질의(getByRole, getByLabelText) 방식을 확인했습니다.
  • CORS - MDN: 사전 요청의 조건과 기본으로 노출되는 응답 헤더를 확인했습니다.
  • Fetch 사용하기 - MDN: fetch가 HTTP 오류에서 예외를 던지지 않고 response.ok로 확인해야 한다는 점을 확인했습니다.
  • Spring Framework - CORS: addCorsMappings 설정과 허용하지 않은 출처의 처리를 확인했습니다.

직접 해보기

  1. examples/ch21-react-basics와 examples/ch22-react-rest/frontend에서 npm ci와 npx vitest run을 실행해 12건과 18건이 통과하는지 확인하세요.
  2. “React 오류 네 가지” 절의 실험 중 하나를 복사본에서 재현하고, 증상만 보고 원인까지 찾아가는 순서를 적어 보세요.
  3. 허용 출처를 바꾼 뒤 curl -X OPTIONS로 사전 요청 응답을 비교하고, Origin 없는 요청의 결과와 어떻게 다른지 설명해 보세요.

이번 장의 정리

이 Chapter에서는 같은 사용자 관리 기능을 브라우저가 그리는 화면으로 옮겼습니다.

  • React 프로젝트는 npm으로 관리하고, npm ci로 잠금 파일 그대로 설치하며, 기본 명령은 dev, test, build입니다.
  • 컴포넌트는 props를 받아 JSX를 돌려주는 함수이고, 목록은 map과 항목 고유의 key로 그리며, {값} 출력은 기본으로 이스케이프됩니다.
  • useState의 상태가 바뀌면 컴포넌트가 다시 그려지고, 계산할 수 있는 값은 상태로 두지 않으며, useEffect의 실행 시점은 의존 배열이 정합니다.
  • 라우터는 주소와 화면을 연결하고, 경로 변수는 항상 문자열이므로 비교하기 전에 타입을 맞춥니다.
  • 화면 테스트는 사용자가 보는 글자와 동작으로 검증하고, 구현을 일부러 망가뜨려 테스트가 잡는지 확인하며, key 경고처럼 테스트가 통과해도 stderr에만 남는 오류가 있습니다.
  • fetch는 HTTP 오류에서 예외를 던지지 않으므로 usersApi.js 한곳에서 response.ok를 확인해 ApiError로 바꾸고, 본문이 없는 204는 null로 처리합니다.
  • 서버의 issues를 입력 칸 옆에 연결하고, 로딩(null)과 빈 목록과 오류를 구분해 보여 줍니다.
  • CORS는 브라우저의 규칙이므로 서버는 필요한 출처만 허용하고, 인증·인가는 따로 구현하며, curl은 되고 브라우저만 실패하면 응답 헤더부터 봅니다.
  • 화면 테스트는 가짜 fetch로 빠르게 돌리고 계약 일치는 진짜 서버로 따로 확인하며, 깨끗한 클론에서만 실패하면 .gitignore가 가린 설정 파일을 의심합니다.

예제 저장소에서 코드를 직접 실행하고 조건과 실패 상황을 바꾸어 보면 각 선택이 필요한 이유를 더 분명하게 이해할 수 있습니다.

다음 Chapter 15 계층과 Port-Adapter 설계에서는 코드를 계층으로 나누고 외부 시스템을 Port/Adapter 뒤로 숨깁니다.

FAQ

자주 묻는 질문

React 프로젝트도 Gradle로 실행하나요?

이 Chapter의 프런트엔드는 npm으로 의존성을 설치하고 Vite로 실행합니다. Spring Boot 백엔드는 기존처럼 Gradle을 사용합니다.

fetch가 400 응답을 받으면 자동으로 예외가 되나요?

네트워크 실패와 달리 HTTP 400은 자동으로 throw되지 않습니다. response.ok를 확인하고 오류 본문을 읽어야 합니다.

CORS는 브라우저 밖에서도 적용되나요?

CORS는 브라우저의 출처 보안 정책입니다. 서버 설정은 응답 헤더를 만들지만 curl 같은 클라이언트가 브라우저와 똑같이 차단하는 것은 아닙니다.

Thymeleaf와 React 중 무엇을 선택해야 하나요?

화면 상호작용, 배포 구조, 팀 역량, API 재사용 요구를 함께 봅니다. 서버 렌더링이 단순한 화면에는 Thymeleaf가 더 작은 구조일 수 있습니다.

작성·편집 ToolPado

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

기술 기준 Spring Boot 4.1.1 · JDK 21

마지막 검토