[Spring boot] Node Gradle을 이용하여 Spring 프로젝트와 Node 프로젝트 붙이기

Spring boot를 이용하여 웹 페이지를 개발할 때는 REST API 서버로 백엔드를 구현하고, 페이지는 서버 사이드 렌더링(SSR)을 이용하여 구현합니다. 이 때 사용하는 기술은 아래의 2가지 기술을 사용합니다.

 

• JSP (Java Server Page)
• Thymeleaf

JSP와 Thymeleaf는 Spring을 이용하여 화면을 구현할 때 사용하는 뷰 템플릿 엔진으로 과거에는 JSP를 이용하여 화면을 구현했지만 최근에는 Thymeleaf를 많이 사용합니다. 이렇게 HTML 코드를 직접 템플릿으로 다뤄 Controller의 데이터를 이용해 동적으로 화면을 만들어주는 것을 서버 사이들 렌더링이라 합니다.

 

하지만 최근에는 클라이언트 사이드 렌더링(CSR) 기법을 이용한 React.js, Vue.js를 이용하여 페이지를 개발하고, 멀티 페이지보다는 싱글 페이지 애플리케이션 개발이 주류가 되어 HTML과 같은 마크업 언어 페이지 개발보다는 Javascript, Typescript 등의 프로그래밍 언어를 주로 사용합니다.

 

이렇게 개발하면 하나의 서비스에서 페이지와 서버가 분리되어 개발이 되는 이른 바 Decoupled Architecture를 채택하면서 Back-end와 Front-end로 분리하게 되는데, 이는 확장성과 자원 최적화 등의 이점을 가지게 됩니다. 하지만 부득이하게 이러한 커플링을 가져야 한다면(인력 리소스 문제 등) 이들 프로젝트를 모놀리식 아키텍처로 개발하려면 어떻게 해야할까요?

 

 

Node Gradle

가장 간단한 방법은 하나의 언어를 사용하는 것이겠지만 백엔드를 Spring으로 하는 걸 원한다면 두 가지 언어를 사용해야 합니다. Spring은 Java와 Kotlin 등의 JVM 언어를 사용하고, Front-end는 Javascript/Typescript를 사용해야 하므로 컴파일 하는 데도 두 가지 컴파일러를 사용해야 합니다.

 

Javascript/Typescript 코드를 빌드하는 데는 NPM 이라는 빌드 도구가 필요하고, Spring 애플리케이션을 빌드하려면 Maven 혹은 Gradle이 필요한데, Gradle에는 3rd Party 플러그인을 제공하여 외부 프로그램을 실행시킬 수 있습니다. 즉 Gradle 환경에서 NPM 빌드 도구를 실행하는 것이 바로 Node Gradle 플러그인 입니다.

 

Node Gradle 플러그인은 Gradle 환경에서 Node.js 환경을 제공해주는 플러그인입니다. NPMTask, NPXTask 등 Node 환경에서 사용할 수 있는 여러 명령어들을 지원하므로 해당 Task를 코드로 작성하여 Javascript/Typescript로 코딩한 페이지들을 빌드할 수 있습니다.

 

https://github.com/node-gradle/gradle-node-plugin

GitHub - node-gradle/gradle-node-plugin: Gradle plugin for integrating NodeJS in your build. :rocket:

Gradle 환경에서 먼저 Node 환경을 구성합니다. Node 환경이 구성되지 않았다면 Gradle에서 자동으로 gradle 스크립트에 정의한 Node 버전을 설치하게 되며 Node 환경이 구성된 경우 FE 소스 코드에서 소스를 빌드한 후 빌드한 결과를 Spring App에 담고난 뒤 Spring App을 빌드하는 과정으로 진행합니다.

 

이러한 환경을 구성하기 위해서는 Spring 프로젝트를 멀티 모듈 프로젝트로 구성해야 합니다.

 

 

 

Multi-Module Project

우리는 보편적으로 Spring 프로젝트를 시작하면 Single Module 프로젝트로 시작합니다. 하나의 최상위 gradle 스크립트로 빌드 환경을 구성하는 것을 싱글 모듈 프로젝트라 합니다.

├── app
│   ├── .gradle
│   ├── .idea
│   ├── gradle
│   ├── src
│   ├── build.gradle.kts
│   ├── gradle.properties
│   ├── gradlew
│   ├── gradlew.bat
│   └── settings.gradle.kts

위와 같이 하나의 build.gradle.kts 파일과 그 외의 하위에는 하나의 src로 구성된 것을 싱글 모듈 프로젝트라 합니다. 이렇게 하면 개발에 필요한 디펜던시, 테스트 코드, 플러그인 등이 하나로만 구성되어 동작합니다. 따라서 FE 소스 코드와 같이 다른 속성의 코드를 한 번에 돌리는 데 적합하지 않습니다. 

 

├── app
│   ├── .gradle
│   ├── .idea
│   ├── build
│   ├── gradle
│   ├── project-api
│   │    ├── build
│   │    ├── src
│   │    └── build.gradle.kts
│   ├── project-fe
│   │    ├── node_modules
│   │    ├── public
│   │    ├── src
│   │    ├── babel.config.js
│   │    ├── build.gradle.kts
│   │    ├── jsconfig.json
│   │    ├── package.json
│   │    ├── README.md
│   │    ├── vue.config.js
│   │    └── yarn.lock
│   ├── build.gradle.kts
│   ├── gradle.properties
│   └── settings.gradle.kts

멀티 모듈 프로젝트를 구성하면 최상위 Gradle 스크립트에서 하위 모듈에 작성된 Gradle 스크립트를 독립적으로 보고 각기 작성된 빌드 스크립트를 읽어 빌드합니다. project-fe에는 FE만을 위한 소스 코드가 들어있으므로 Node Gradle 플러그인을 이용한 빌드 스크립트를 작성하고, project-api에는 Spring 애플리케이션 소스 코드를 넣었으므로 Spring 디펜던시와 플러그인 등의 빌드 스크립트를 작성하면 모놀리스 형태로 Spring 애플리케이션으로 프로젝트를 빌드 할 수 있습니다.

 

IntelliJ에서 멀티 모듈 프로젝트를 구성할 때는 먼저 새 프로젝트를 생성하고, 하위 모듈을 만들면서 진행할 수 있습니다. 진행을 위해 먼저 새 프로젝트를 Gradle로 만들어줍니다.

 

프로젝트 최상위 폴더를 오른쪽 클릭한 다음 새로운 모듈을 생성합니다. 새로운 모듈에는 api라는 이름으로 생성해줍니다.

$ vue create cms-fe

이 포스트에서는 FE 소스 코드로 Vue.js를 사용해보겠습니다. 각자 원하는 프레임워크 혹은 라이브러리를 선택하여 만든 프로젝트에 프론트엔드로 구현할 모듈을 만들어줍니다.

 

모듈이 만들어진 뒤에는 위와 같이 fe 모듈에도 build.gradle.kts 파일을 하나 추가해줍니다. 

 

 

 

 

이제 최상위 settings.gradle.kts에서 두 모듈을 include 해줍니다. 빌드할 때 이제는 두 모듈의 스크립트를 포함하여 빌드하게 됩니다.

 

 

 

먼저 cms-fe의 build.gradle.kts 파일에 Node 환경을 구성합니다. 사용할 노드 버전은 18.17.1 버전이고, 항상 Node 환경을 셋업하도록 활성화 합니다. 그리고, Vue 빌드를 위한 빌드 Task를 한 개 작성합니다. 작업에는 항상 npm install을 수행하도록 하며 빌드 명령어를 구성합니다. 그리고, BUILD_OUT_DIR이라는 환경 변수를 통해 빌드 결과물을 Spring 프로젝트로 보내어 Spring 애플리케이션 실행시 동작하도록 구성합니다.

 

 

 

여기서는 Vue 빌드에 vite를 이용하도록 구성하였으므로 vite.config.ts 파일에서 Vue의 결과물을 지정할 수 있습니다. 위에서 우리는 BUILD_OUT_DIR이라는 환경 변수로 빌드 결과물을 지정하였으므로 해당 변수를 이용하도록 구성합니다. 만약을 대비해 지정하지 않은 경우 기본 디렉터리로 빌드되도록 구성합니다.

 

 

 

다음은 Spring 모듈을 구성해보겠습니다. 이 글에서는 기본적인 웹 페이지만을 띄우기 위해 Spring Web 디펜던시와 Kotlin 디펜던시만을 사용했습니다. 그리고 멀티 모듈에서는 Spring 애플리케이션 빌드시 일반 jar가 아닌 bootJar 태스크로 빌드할 수 있도록 해야 합니다.

 

 

 

마지막으로 최상위 Gradle 스크립트에서 사용할 플러그인을 작성하고 일단 apply false로 둡니다. 각 프로젝트별로 사용할 플러그인이 다르기 때문에 하단의 스크립트에서 플러그인 지정할 코드를 project로 구현한 후 각 프로젝트에 맞게 사용할 플러그인을 작성합니다. 전체 프로젝트에 적용할 사항은 allProjects에 구현해둡니다.

 

 

$ ./gradlew build

이제 Gradle 명령어로 build 작업을 수행해봅니다. 그러면 위와 같이 지정된 디렉터리에 빌드된 결과물이 생성되는 것을 볼 수 있습니다. 

 

 

 

Spring WebMvc 설정 구현

하지만 이대로 Spring 애플리케이션을 실행하면 404 Not found가 나타납니다. 기본적으로 Spring은 resources/static 폴더에 있는 파일을 정적 로딩하므로 우리가 지정한 frontend 하위는 무시하기 때문입니다.

 

그러면 처음부터 static 폴더로 지정하는 게 낫지 않았을까? 물론 그래도 되지만 백엔드 프로젝트에서 프론트엔드와 별개로 정적인 파일을 제공해야 하는 경우 static 폴더의 사용이 제한될 수 있습니다. 만약 static 폴더와 FE 빌드 결과물을 동시에 잡고 싶다면 이 방법을 따라해봅시다.

 

Spring 프로젝트에 WebMvcConfig라는 이름으로 Configuration Bean을 생성합니다. WebMvcConfigurer 인터페이스를 구현하여 정적 리소스 경로에 위에서 지정한 frontend 폴더를 추가합니다. 만약 클라이언트가 요청한 리소스가 백엔드 프로젝트에 존재하거나 읽을 수 있는 포맷인 경우 해당 파일을 읽도록 하고, 그렇지 않으면 Vue 결과물에 의존하도록 합니다. 존재하지 않거나 읽을 수 없는 경우 Vue의 메인 페이지로 이동하도록 합니다.

 

이제 Spring 애플리케이션을 실행한 후 localhost:8080으로 접속하면 위와 같이 Vue 화면이 Tomcat 위에서 동작하는 것을 볼 수 있습니다.

 

 

 

마치며..

최대한 간단한 방법으로 모놀리식 아키텍처로 페이지와 서버를 구현하는 방법에 대해 알아봤습니다. 타임리프나 JSP를 사용하면 이러한 구성이 굳이 필요없지만 자신이 원하는 기술을 적절히 사용하고 싶다면 이런 방법을 고민하게 될 것입니다.

 

해당 포스트에서는 Vue를 사용하였지만 React, Svlete 등 Node.js 위에서 동작하는 다른 프로젝트들도 비슷하게 구성하면 동작하기 때문에 적절히 응용해서 프로젝트 구성에 도움이 되기를 바랍니다.