기존 Spring Boot JSP 프로젝트에서 Vue.js로 프론트엔드 교체하기

기존 JSP 기반으로 구성된 Spring Boot 프로젝트를 Vue.js를 이용한 클라이언트 사이드 렌더링(CSR) 방식으로 전환하여, 모던한 사용자 경험(UX)을 제공하고자 하시는 분들을 위해 이번 포스팅에서는 기존 프로젝트를 유지하면서 JSP를 제거하고, Vue.js를 프론트엔드로 교체하는 전체적인 흐름과 구현 방법을 단계별로 정리합니다.

---

✅ 전환 전제 및 기본 구조

현재 상황은 다음과 같습니다:

• 백엔드(Spring Boot):
  • Java로 구현되어 있으며, @RestController 방식으로 API를 제공
  • 기존 JSP가 화면 구성을 담당하였으나, 이제 API를 통해 데이터만 제공
• 프론트엔드:
  • 기존에는 JSP 템플릿을 사용했으나, 앞으로는 Vue.js 기반의 SPA(Single Page Application)로 변경
  • API 호출을 통해 데이터를 받아와 화면을 구성

아래의 다이어그램은 전체적인 아키텍처를 시각적으로 표현한 것입니다.

• Vue.js Frontend(A): 사용자의 브라우저에서 Vue.js로 구성된 프론트엔드가 실행됩니다.
• Spring Boot API(B): Vue.js는 기존에 구현된 RESTful API를 호출하여 데이터를 주고받습니다.
• Vue.js 빌드 결과물(C): npm run build를 통해 생성된 정적 파일을 Spring Boot의 static 디렉토리에 복사하여 서빙합니다.
• Spring Security(D): 기존 세션 인증 방식 대신, JWT 기반 인증 방식을 적용하여 보안을 강화할 수 있습니다.

---

1. Vue.js 프로젝트 생성

먼저, 새 Vue.js 프로젝트를 생성합니다. Vue CLI 또는 Vite 등을 사용하면 편리합니다.

npm init vue@latest
cd my-vue-app
npm install
npm run dev

참고: 프로젝트 생성 시 Vue Router, 상태관리 라이브러리(Pinia) 등을 선택하면 추후 개발에 유리합니다.

---

2. API 호출 구조 적용 (Axios)

Spring Boot에서 제공하는 API를 호출하기 위해 axios 라이브러리를 사용합니다.

npm install axios

예시 코드 (API 모듈):

 

js

// src/api/user.js
import axios from 'axios'

const API_BASE = '/api'

export const fetchUsers = () => axios.get(`${API_BASE}/users`)
export const fetchUser = (id) => axios.get(`${API_BASE}/users/${id}`)
export const createUser = (data) => axios.post(`${API_BASE}/users`, data)

컴포넌트 예시:

vue

<template>
  <div>
    <h2>사용자 목록</h2>
    <ul>
      <li v-for="user in users" :key="user.id">{{ user.name }}</li>
    </ul>
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue';
import { fetchUsers } from '@/api/user';

const users = ref([]);

onMounted(async () => {
  const res = await fetchUsers();
  users.value = res.data;
});
</script>

---

3️⃣ Spring Boot에서 CORS 허용

프론트엔드(Vue)와 백엔드(Spring Boot)가 별도의 도메인(또는 포트)에서 개발될 경우, CORS(Cross-Origin Resource Sharing) 설정이 필요합니다.

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")
                .allowedOrigins("http://localhost:5173")  // Vue 개발 서버 주소
                .allowedMethods("GET", "POST", "PUT", "DELETE")
                .allowCredentials(true);
    }
}

이렇게 하면 Vue 개발 서버와의 API 통신에서 발생할 수 있는 CORS 오류를 방지할 수 있습니다.

---

4️⃣ JSP 제거 및 정적 자원 처리

Vue.js로 전환한 후에는 기존의 JSP 파일은 필요 없어집니다.

📁 JSP 제거 위치

• /src/main/webapp/WEB-INF/views/ 디렉토리에 있는 JSP 파일
• application.properties에서 spring.mvc.view.prefix/suffix 설정 제거 ( JSP 관련 뷰 리졸버 설정)

📁 정적 자원 배포

Vue 앱을 빌드한 후 생성된 정적 파일을 Spring Boot의 static 폴더에 복사하여 정적 자원으로 서빙합니다. 

npm run build
cp -r dist/* ../backend/src/main/resources/static

이렇게 하면 사용자가 브라우저에서 /로 접근할 때 Vue.js 앱이 렌더링되고, /api/** 경로는 백엔드 API가 처리하게 됩니다.

 

---

5️⃣ 인증 처리 (JWT 적용 권장)

• 기존 세션 기반 인증에서 JWT 기반 인증으로 전환하면 프론트엔드와 백엔드의 분리가 더욱 원활해집니다.
  • Spring Security에서 JWT 설정: 사용자가 로그인 시 JWT를 발급하고, 이후 API 호출 시 JWT를 검증합니다.
  • Vue.js에서 인증 처리: 로그인 후 받은 JWT 토큰을 localStorage나 sessionStorage에 저장하고, Axios 인터셉터를 이용해 모든 API 요청 시 헤더에 첨부합니다.

js

axios.defaults.headers.common['Authorization'] = `Bearer ${token}`

JWT 설정방법에 대한 포스팅은 따로 정리하였습니다.

---

✅ 요약

단계	설명
Vue 세팅	npm init vue@latest로 프로젝트 생성
API 연동	Axios로 기존 REST API 호출
CORS 설정	Spring Boot에서 Vue 개발 서버 허용
JSP 제거	JSP, 관련 설정 삭제
정적 빌드	Vue 앱 빌드 → static/으로 복사
인증 방식	세션 기반 → JWT 방식으로 전환 권장

---

✨ 참고: 프로젝트 구조 예시

📁 backend (Spring Boot)
├─ src/main/java
├─ src/main/resources
│  ├─ static ← 여기 Vue 앱 빌드 결과물 위치
│  └─ application.yml
└─ build.gradle

📁 frontend (Vue.js)
├─ src
│  ├─ api
│  └─ views
├─ public
└─ vite.config.js

 

---

🔚 결론

기존 JSP 기반 프로젝트를 Vue.js 기반으로 전환하면 유지보수성과 사용자 경험 측면에서 훨씬 유리해집니다. 전환을 어렵게 느낄 수 있지만, 이미 API 기반으로 분리된 구조라면 부담 없이 시작하실 수 있습니다.

참고자료

• Vue.js 공식 문서
• Axios 공식 GitHub
• Spring Boot 공식 문서