React로 단일 페이지 애플리케이션(SPA)을 개발하고 Spring Boot를 통해 배포하는 과정에서, 사용자들이 특정 페이지로 이동한 후 새로고침을 하면 404 오류가 발생하는 경우가 있습니다. 이는 React와 Spring Boot가 라우팅을 처리하는 방식의 차이에서 비롯된 문제로, 많은 개발자가 마주하는 흔한 이슈입니다.
이번 포스팅에서는 문제의 원인을 분석하고, 이를 효과적으로 해결하는 방법을 상세히 설명하겠습니다.
문제 상황: 새로고침 시 404 오류 발생
React 애플리케이션에서 BrowserRouter를 사용하여 클라이언트 사이드 라우팅(Client-Side Routing)을 처리할 때, 새로고침 시 다음과 같은 404 오류가 발생할 수 있습니다.
GET https://example.com/purchased-product 404 (Not Found)
이 상황은 브라우저가 /purchased-product 경로에 대한 요청을 서버로 보냈지만, Spring Boot 서버가 해당 경로를 처리하는 방법을 알지 못해 404 Not Found를 반환했기 때문에 발생합니다.
React는 클라이언트에서 모든 라우팅을 처리하도록 설계되었으나, 브라우저는 새로고침하거나 직접 URL을 입력했을 때 서버에 요청을 보내는 기본 동작을 따릅니다. 따라서 Spring Boot 서버가 이러한 요청을 적절히 처리하지 않으면 위와 같은 문제가 발생합니다.
문제 원인: React와 Spring Boot 라우팅 처리 방식의 차이
[React의 클라이언트 사이드 라우팅]
React에서 BrowserRouter는 브라우저의 주소(URL)를 변경하지만 실제로 서버에 요청을 보내지 않습니다. 대신, 클라이언트 측에서 라우팅이 이루어지며, 경로에 매핑된 React 컴포넌트를 렌더링합니다.
- URL 변경은 브라우저 주소창에서만 이루어집니다.
- React 내부에서 지정된 컴포넌트가 로드됩니다.
[브라우저의 기본 동작]
반면, 브라우저에서 새로고침하거나 URL을 직접 입력하면 해당 경로에 대한 요청을 서버로 보냅니다.
- 서버는 경로에 대해 정의된 처리가 없는 경우, 404 Not Found를 반환합니다.
- 이는 서버가 클라이언트 사이드 라우팅 경로에 대해 무지한 상태이기 때문입니다.
| 상황 | React의 동작 | 서버의 동작 |
| React 내에서 경로 이동 | React가 경로를 파싱하고, 해당 컴포넌트 렌더링 | 서버는 관여하지 않음 |
| 새로고침 또는 URL 직접 접근 | React는 관여하지 않음. 브라우저가 서버에 경로를 요청 | 서버는 요청 경로를 인식하지 못하고 404 반환 |
React와 브라우저의 동작 차이를 이해했으니, 이제 이를 해결하기 위한 Spring Boot 설정 방법을 살펴보겠습니다.
해결 방법: Spring Boot에서 React 경로 처리하기
Spring Boot 서버가 React 애플리케이션의 모든 경로를 처리하도록 설정하면, 브라우저가 서버로 보내는 모든 요청에 대해 React의 index.html 파일을 반환할 수 있습니다. 이렇게 하면 브라우저는 React 애플리케이션을 다시 로드하고, 클라이언트 측에서 올바른 경로를 렌더링할 수 있습니다.
[구현 방법]
Spring Boot에서 React 라우팅을 처리하기 위한 WebController를 다음과 같이 작성할 수 있습니다.
import org.springframework.boot.web.servlet.error.ErrorController;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
@Controller
public class WebController implements ErrorController {
@GetMapping({
"/purchased-product"
})
public String index() {
// Spring Boot가 React의 index.html 파일을 반환하도록 설정
// index.html은 /resources/static 또는 /resources/public에 위치
return "index.html";
}
}
위 코드는 React 애플리케이션의 경로를 명시적으로 나열하고, 해당 경로에 대한 요청이 들어오면 index.html을 반환하도록 설정합니다. 이렇게 하면 React의 라우터가 클라이언트 측에서 경로를 처리할 수 있는 환경을 제공하게 됩니다.
결론 및 추가 팁
Spring Boot와 React를 통합할 때, 클라이언트 사이드 라우팅으로 인해 발생하는 새로고침 404 오류는 React와 브라우저의 기본 동작 차이에서 발생합니다. 서버에서 React의 모든 경로를 처리하도록 설정함으로써 문제를 쉽게 해결할 수 있습니다.
추가적으로, 새로운 경로가 생길 때마다 이를 반영하는 작업이 번거로울 수 있으므로, 모든 경로를 자동으로 처리하도록 설정하는 방법도 고려할 수 있습니다. 예를 들어, @RequestMapping에 정규식을 사용하여 모든 경로를 한 번에 처리하는 방법이 있습니다.
import org.springframework.boot.web.servlet.error.ErrorController;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
@Controller
public class WebController implements ErrorController {
@GetMapping({
"/admin/**"
})
public String index() {
return "index.html";
}
}이 코드는 모든 경로를 React의 index.html로 처리하므로, 경로가 추가될 때마다 코드를 수정할 필요가 없어 관리가 더 편리해질 수 있습니다. 물론, React용 API가 아닌 친구들은 제외해야 합니다.
