React와 Spring Boot 연동 구조: CORS, 프록시, 배포 전략

React(리액트)와 Spring Boot(스프링 부트) 연동은 화면을 담당하는 싱글 페이지 애플리케이션(Single Page Application)과 데이터를 담당하는 REST API 서버를 분리해 하나의 서비스를 구성하는 아키텍처를 뜻한다. 개발 단계에서는 두 서버가 서로 다른 포트에서 동작하므로 CORS(Cross-Origin Resource Sharing)와 프록시(proxy) 설정이 핵심 과제가 되고, 배포 단계에서는 정적 빌드 산출물을 어디서 서빙할지가 핵심 결정이 된다. 이 문서는 특정 버전의 설치 절차가 아니라 구조와 원리를 중심으로 연동 방식을 설명한다.

프론트엔드와 백엔드를 분리하는 이유

JSP나 Thymeleaf 같은 서버 사이드 템플릿 방식에서는 서버가 완성된 HTML을 만들어 내려보낸다. 반면 분리 구조에서는 React가 브라우저에서 화면을 그리고, Spring Boot는 HTML을 전혀 만들지 않은 채 JSON만 반환하는 API 서버 역할에 집중한다. 두 애플리케이션을 잇는 유일한 계약은 API 명세이므로, 프론트엔드와 백엔드 팀이 독립적으로 개발하고 배포할 수 있으며 같은 API를 모바일 앱 등 다른 클라이언트가 재사용할 수도 있다.

개발 환경: 서로 다른 포트와 CORS

개발 중에는 React 개발 서버(Vite 기준 5173 포트)와 Spring Boot(8080 포트)가 동시에 떠 있다. 브라우저는 동일 출처 정책(same-origin policy)에 따라 출처(origin)가 다른 요청의 응답 읽기를 기본적으로 차단하므로, 프론트엔드에서 API를 호출하면 CORS 오류가 발생한다. 해법은 두 가지다. 하나는 개발 서버의 프록시 기능으로 요청을 대신 전달하는 것이고, 다른 하나는 백엔드가 허용 출처를 응답 헤더로 명시하는 것이다.

// vite.config.ts
export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,
      },
    },
  },
});

프록시 방식에서는 브라우저 입장에서 요청이 같은 출처로 나가고 서버 간 전달은 CORS의 적용 대상이 아니므로 문제가 아예 발생하지 않는다. 백엔드에서 허용하는 방식은 다음과 같다.

@Configuration
public class CorsConfig implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")
                .allowedOrigins("http://localhost:5173")
                .allowedMethods("GET", "POST", "PUT", "DELETE")
                .allowCredentials(true);
    }
}

단순 요청이 아닌 경우 브라우저는 본 요청 전에 OPTIONS 메서드의 프리플라이트(preflight) 요청을 먼저 보내 허용 여부를 확인한다는 점도 알아 두어야 한다.