Vue와 Spring Boot 연동 구조: 개발 프록시부터 서빙 전략까지

Vue(뷰)와 Spring Boot(스프링 부트)를 연동한다는 것은 화면 렌더링을 담당하는 Vue 싱글 페이지 애플리케이션(Single Page Application)과 비즈니스 로직을 담당하는 Spring Boot API 서버를 분리해 구성하고, 둘 사이를 HTTP와 JSON 통신으로만 잇는 구조를 만드는 일이다. 개발 환경에서는 Vite(비트) 개발 서버의 프록시(proxy)와 CORS(Cross-Origin Resource Sharing) 처리가, 배포 환경에서는 빌드 산출물의 서빙 위치 결정이 연동의 핵심이 된다. 이 문서는 설치 절차가 아니라 이러한 구조와 원리를 중심으로 설명한다.

분리 아키텍처의 기본 구조

서버 템플릿 기반 구조에서는 화면 전환마다 서버가 새 HTML을 렌더링하지만, 분리 구조에서는 Spring Boot가 HTML을 전혀 만들지 않는다. 최초에 정적 파일 한 벌이 브라우저에 전달된 뒤에는 Vue Router(뷰 라우터)가 화면 전환을 담당하고, 데이터가 필요할 때만 API를 호출해 JSON을 받는다. 두 애플리케이션의 접점이 API 명세 하나로 좁혀지므로 프론트엔드와 백엔드를 서로 다른 언어, 저장소, 배포 주기로 운영할 수 있고, 같은 API를 모바일 클라이언트가 재사용할 수도 있다.

개발 환경: Vite 개발 서버와 프록시

개발 중에는 Vite 개발 서버(기본 5173 포트)와 Spring Boot(기본 8080 포트)가 동시에 실행된다. 브라우저의 동일 출처 정책(same-origin policy) 때문에 5173에서 로드된 페이지가 8080의 API를 직접 호출하면 응답이 차단된다. 가장 간편한 우회는 Vite의 프록시 기능이다.

// vite.config.js
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
  plugins: [vue()],
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,
      },
    },
  },
});

이렇게 설정하면 프론트엔드 코드는 /api로 시작하는 상대 경로로만 호출하고, 개발 서버가 그 요청을 백엔드로 대신 전달한다. 브라우저 입장에서는 같은 출처와 통신하는 것이므로 CORS가 아예 발생하지 않는다. 참고로 Vite에서는 VITE_ 접두사가 붙은 환경 변수만 클라이언트 코드에 노출되며, 노출된 값은 누구나 볼 수 있으므로 비밀 값을 담으면 안 된다.

CORS를 백엔드에서 허용하는 방법

프록시 없이 브라우저가 다른 출처의 API를 직접 호출하게 하려면, Spring Boot가 응답 헤더로 허용할 출처와 메서드를 알려 주어야 한다.

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")
                .allowedOrigins("https://app.example.com")
                .allowedMethods("GET", "POST", "PUT", "PATCH", "DELETE")
                .allowedHeaders("*");
    }
}

단순 요청의 조건을 벗어나는 요청, 예를 들어 JSON 본문을 담은 PUT 요청 전에는 브라우저가 OPTIONS 메서드의 프리플라이트(preflight) 요청을 먼저 보내 허용 여부를 확인한다. Spring Security를 함께 쓴다면 시큐리티 필터 체인에도 CORS 설정을 등록해야 프리플라이트가 인증 필터에 가로막히지 않는다.