Spring Boot(Kotlin) — 12편. 완성된 프로젝트 템플릿 공유

📚 Spring Boot(Kotlin) 기본 셋팅 — 전체 시리즈

1. 왜 멀티 모듈 구조인가? (아키텍처 철학 & 전체 설계 편)
2. API Response 포맷 설계
3. 글로벌 예외 처리(GlobalExceptionHandler)
4. Swagger(OpenAPI) 설정
5. Security(JWT) 기본 골격
6. JWT TokenProvider
7. Redis 설정
8. Validation 설정
9. Logging + MDC(traceId) 설정
10. application.yml 프로필 분리 (local/dev/prod)
11. 멀티모듈 + JPA 기본 구조 정리 
12. 완성된 프로젝트 템플릿 Git 공유← 지금 글

---

 

이 글은 “Spring Boot(Kotlin) 기본 셋팅 — 12편 시리즈”의 마지막 글입니다.
앞선 글들을 통해 멀티 모듈 구조 → API 설계 → 예외 처리 → 보안 → 로깅 → JPA까지 실제 운영 수준의 골격을 단계별로 완성했습니다.

이제 그 모든 내용을 하나의 프로젝트로  Git을 통해 공유합니다.

 

🎁 1. 템플릿 다운로드

GitHub에 올린 템플릿을 다운로드해서 자유롭게 수정하여 사용하시면 됩니다.
https://github.com/jaemoi/springboot-kotlin-initial-template

GitHub - jaemoi/springboot-kotlin-initial-template

 

 

🔧 2. 템플릿에서 미리 적용된 내용

springboot_initial_setup/
 ├── api/
 ├── application/
 ├── batch/ (선택)
 ├── build.gradle.kts
 ├── settings.gradle.kts
 └── ...

 

 

✔ 멀티모듈(api / application / batch)

• controller / service / repository 계층 분리
• module 간 의존성 명확하게 설정
• DTO → ServiceModel → Entity 구조 설계

✔ API Response 포맷 통일

• ApiResponse<T> 기본 구조 포함
• 성공/실패 포맷 일관화
• 성공/실패 포맷 일관화

✔ 글로벌 예외 처리

• @RestControllerAdvice 기반 통합 핸들러 구성
• 비즈니스/Validation/서버 내부 예외 처리

✔ JWT Security 기본 골격

• TokenProvider
• JwtAuthenticationFilter
• Custom AccessDeniedHandler / EntryPoint

✔ Swagger(OpenAPI) 기본 페이지 적용

✔ Redis 기본 설정

 

✔ Validation + 글로벌 처리

✔ MDC(traceId / eventId / userId / clientIp) 기반 로깅 필터

• 모든 요청에 unique trace-id 자동 삽입
• 운영환경 디버깅/로그 분석에 강력한 형태

✔ application.yml 프로필 분리

• local / dev / prod 분리
• 환경별 설정 독립

 

🏗 3. 템플릿에서 수정해야 하는 부분

✔ 1) 패키지 경로 변경

템플릿은 com.example 로 되어 있으므로, 회사/프로젝트 도메인에 맞게 변경하세요.

✔ 2) DB 설정 변경

공유 목적 때문에 기존 환경 변수(LOCAL_DB_URL 등)를 삭제하고 임시로 H2 DB를 사용하도록 세팅했습니다.

spring:
  datasource:
    url: jdbc:mysql://~
    username: xxx
    password: xxx

실제 개발 시에는 위와 같이 DB 설정을 다시 연결해주세요.

✔ 3) JWT secret key 교체

샘플 값이 포함되어 있으니 반드시 새로 생성해서 교체하세요.

✔ 4) Swagger 문구/프로젝트명

info.title, description 등은 브랜드에 맞게 수정할 수 있습니다.

✔ 5) Redis 사용 여부

프로젝트 성격에 따라 사용하지 않는다면 의존성 제거 가능.

 

🧪 4. 실행 방법

Local 환경 실행

프로젝트는 application-local.yml로 실행되게 설정되어있습니다.

 

IntelliJ의 Run 버튼으로도 실행되지만,
multi-module 구조에서는 IDE가 run 구성을 제대로 못 잡을 가능성이 있으므로
공식 실행 방법은 Gradle의 bootRun 명령을 기준으로 안내합니다.

$ ./gradlew :api:bootRun

환경 변수 필요 없이 바로 실행되도록, 내장 H2 + 내장 Tomcat + 간단한 JWT 구조로 설정되어 있습니다.

 

💡 5. 이 템플릿을 만든 이유

처음 스프링을 시작할 때 가장 어려운 부분 중 하나는
“도대체 무엇부터 설정해야 하지?” 하는 고민입니다.

예제 코드는 많지만, 실서비스 기반 구조를 갖춘 템플릿을 찾기가 어려웠습니다.

그래서:

• 처음부터 확장성이 있도록
• 팀 단위 협업에서도 빠르게 이해할 수 있도록
• 운영환경(log, security, 예외처리 등)까지 고려할 수 있도록

위 모든 내용을 바로 쓸 수 있는 형태로 정리했습니다.

 

아직은 많이 부족한 개발자여서 공유하는 템플릿의 퀄리티가 부족할 수 있습니다. 개선 사항을 댓글에

자유롭게 말씀해주시면 고민해보고 반영하도록 하겠습니다. 함께 더 나은 프로그래밍을 위해 같이 고민하고

소통하면 좋겠습니다.

 

🙌 6. 시리즈를 만들면서 ..

 

저는 컴퓨터 프로그래밍을 전공하지 않아서 개발자의 길을 걷기 시작하기까지 남들보다

더 많은 고생을 해야했습니다. 그래서 저와 같이 프로그래밍 개발을 이제 막 시작하는 분들에게

조금이나마 도움을 주고자 본 시리즈를 제작하게 되었습니다.

 

오늘도 즐거운 코딩하세요. 감사합니다.