#7 - Spring Boot 4 실습: 환경 준비부터 서버 실행까지
중년개발자
@loxo
17일 전
Spring Boot 4 실습: 환경 준비부터 서버 실행까지
이 실습의 목적은 강의를 따라 실제로 서버를 실행해보는 것이다.
단순히 코드를 읽는 것이 아니라,
"내 로컬에서, 내가 이해한 구조로, 서버가 뜬다"
라는 경험을 만드는 것이 목표다.
눈으로만 코딩은 아무 도움이 되지 않습니다. 오직 손으로 직접 코딩만이 당신의 실력을 키워 줍니다. AI가 코딩해도 이해 기반 손코딩은 여전히 필요합니다.
단순히 아래 글을 눈으로 지나치지 마시고, 중간 가이드 문서도 꼼꼼히 보셔야 따라 올 수 있습니다.
0. 사전 준비: 왜 VS Code + Antigravity 인가
0.1 IntelliJ에서 Antigravity로 갈아탄 이유
IntelliJ는 여전히 훌륭한 IDE다.
하지만 이 강의에서는 VS Code + Antigravity를 기준으로 한다.
이유는 단 하나다.
AI 개발 경험
- AI 없이는 이제 코딩하기 힘들다.
- 노가다 코딩을 줄여주기 때문에 이전으로 못 돌아간다.
- 때로는 공부도 된다.
- 이제는 이해를 기반으로 한 프롬프트 전문가가 되어야 한다.
이 생태계는 현재 VS Code가 가장 빠르고 자유롭다.
0.2 그럼 Java 개발이 불편하지 않나?
결론부터 말하면:
요즘은 전혀 아니다.
- Spring Boot
- Gradle / Maven
- 멀티 모듈
- 디버깅 / 테스트
모두 VS Code에서 충분히 가능하다.
특히 구조를 이해하고 설계하는 강의에서는,
오히려 IDE의 과도한 자동화가 사고를 방해한다.
0.3 Antigravity 설치
https://antigravity.google/download
Antigravity는 VS Code 기반 AI 개발 환경을 강화하기 위한 설정/확장 조합이다.
- AI Agent 중심 개발
- 프롬프트 파일(@AGENTS.md, @GEMINI.md) 기반 작업
- 코드 생성과 구조 검증을 분리
이 강의에서는 AI를 쓰는 법이 아니라
AI와 함께 설계하는 법을 연습한다.
설계한 결과물을 가지고 각자가 맞게 고쳐 가면 진행한다.
그러면서 원리와 이해 기반으로 구성해 가고자 한다.
1. 필수 VS Code 확장 구성
프로젝트를 열자마자 동일한 개발 환경을 갖추기 위해
.vscode/extensions.json을 사용한다.
- 개인적으로 사용하는 Next.js, Spring Boot, Java 관련 extensions 모음이다.
2. 프로젝트 시작: Template에서 출발하기
2.1 Starter 소개
- Spring Boot 4 기반 모던 백엔드 아키텍처
- 멀티 모듈 구조
- PostgreSQL 중심 설계
📘 가이드 글
📦 GitHub Template
2.2 시작 방법
- GitHub에서 Use this template 클릭
- 본인 저장소로 생성
- 로컬에 clone
git clone <your-repo-url>
cd postgresql-co-kr-starter
code .3. 데이터베이스 설치 및 샘플 데이터
이 강의는 로컬 DB를 직접 다루는 것을 전제로 한다.
3.1 환경
- WSL2
- PostgreSQL 17
- Redis
📘 참고 강의
3.2 핵심 포인트
- DB 생성
- 사용자 분리 (owner / app)
- schema 분리
- 샘플 게시판 데이터
- 반드시 위의 과정을 거친 다음 다음 강의를 들으세요!
- 한번 귀찮음을 극복하는 것은 절반의 성공입니다.
DB는 인프라가 아니라 코드의 일부다.
4. API 서버 먼저 실행해보기 (Datasource 설정 전)
이 단계에서는 아무 설정도 건드리지 않고 API 서버가 정상적으로 실행되는지부터 확인한다.
Datasource, 트랜잭션, 구조는 그 다음 단계에서 다룬다.
4.1 Spring Boot Dashboard
VS Code의 Spring Boot Dashboard에서 api 모듈을 선택한다.
- Run
- Debug
- Profile 선택 가능
4.2 실행 확인
curl http://localhost:8080
response:
{"message":"여기까지 오시느라 수많은 에러와 싸우며 삽질(?) 좀 하셨죠? 대단합니다! 👏👏 그 끈기에 박수를 보내며, 당신의 멋진 개발 여정을 응원합니다. https://postgresql.co.kr"}% 정상 응답이 오면 성공이다.
이 단계의 목적은 단 하나다.
"이 프로젝트는 지금 이 상태에서도 서버가 뜬다"
5. Spring Boot 4 멀티 Datasource 실습
이 단계가 이번 실습의 핵심이다.
5.1 목표 요약
- PostgreSQL Master / Slave 구조
- 트랜잭션 기반 자동 라우팅
- Annotation 기반 명시적 선택
- Profile 기반 HikariCP 설정
5.2 핵심 규칙
-
@Transactional(readOnly = true)- MASTER / SLAVE 랜덤 접근
-
@Transactional(readOnly = false)- MASTER 전용
-
트랜잭션 없음
- MASTER 기본
-
@UseDataSource- 트랜잭션보다 우선
5.3 AI Prompt로 멀티 데이터소스 생성
- AI 시대에 프롬프트 한 줄이면 소스가 만들어진다.
- Spring Boot 4 멀티 데이터 소스 생성 Prompt
- 아래 prompt 를 복사하여 입력 후 생성된 데이터 소스를 확인하고 서버 기동 오류가 없는지 확인 한다.
- 서버가 시작될 때까지 디버깅(프롬프트) 하면서 서버가 기동되기를 바랍니다.
@AGENTS.md 및 @README.md에 정의된 프로젝트 구조와 컨벤션을 반드시 준수하여,
Spring Boot 4.x 기준의 DB Connection Java Config를 구현하라.
[목표]
PostgreSQL Master/Slave(Read Replica) 구조를 사용하는 멀티 Datasource 환경을 구성하고,
트랜잭션 속성 및 커스텀 Annotation을 기반으로 Datasource를 자동 또는 명시적으로 선택할 수 있도록 한다.
[기술 스택]
- Spring Boot 4.x
- Spring Framework 6.x (Jakarta 패키지 사용)
- PostgreSQL
- HikariCP
- Java Config 기반 설정
[DB 공통 정보 - 환경변수화]
- host: localhost
- username: lecture_app
- password: lecture_app_pwd
- driver-class-name: org.postgresql.Driver
[Datasource 구성]
1. MASTER
- INSERT/UPDATE/DELETE 전용
2. SLAVE
- SELECT(Read Only) 전용
[트랜잭션 기반 라우팅 규칙]
1. @Transactional(readOnly = true)
- MASTER, SLAVE 모두 접근 가능, Thread Random 사용
2. @Transactional(readOnly = false) 또는 기본 트랜잭션
- MASTER만 접근 가능
3. 트랜잭션 미존재 시
- 기본 Datasource는 MASTER
위 규칙은 AbstractRoutingDataSource를 사용하여 구현한다.
[Annotation 기반 Datasource 선택]
자동 라우팅과 별도로 개발자가 명시적으로 Datasource를 선택할 수 있어야 한다.
- 커스텀 Annotation 정의
@Target({METHOD, TYPE})
@Retention(RUNTIME)
public @interface UseDataSource {
DataSourceType value();
}
- DataSourceType enum
MASTER, SLAVE
- AOP를 이용하여 Annotation이 존재할 경우
트랜잭션 속성보다 Annotation을 우선 적용한다.
[Profile 별 HikariCP 설정]
Spring Profile에 따라 maximumPoolSize를 다르게 설정한다.
- local: 2
- dev: 10
- prod: 20
application.yml에서 Profile을 분리하고 환경변수를 설정한다.
@ConfigurationProperties 기반으로 바인딩한다.
[필수 생성 파일]
1. DataSourceType enum
2. Datasource Context Holder (ThreadLocal)
3. Routing DataSource (AbstractRoutingDataSource)
4. Master Datasource Config
5. Slave Datasource Config
6. TransactionManager 설정
7. UseDataSource Annotation
8. Annotation 처리 AOP
9. Profile 기반 HikariCP 설정
10. 전체 Datasource 구성을 통합하는 최종 Configuration
11. 환경 변수 env 파일
[설계 및 품질 기준]
- Spring Boot 4 Best Practice 준수
- 테스트 및 확장성을 고려한 구조
- 멀티 모듈 환경에서 재사용 가능하도록 설계
- 역할 기준 패키지 분리
- 코드에 의도 중심의 주석 포함
[결과물]
- Java Config 전체 코드
- 필요한 application.yml 예시6. 이 실습의 진짜 목적
이 강의는
- 설정을 외우게 하지 않는다
- 코드를 베끼게 하지 않는다
대신,
"왜 이런 구조가 되었는가"
를 몸으로 이해하게 만든다.
서버가 뜨는 순간,
여러분은 이미 Spring Boot 4의 절반을 이해한 것이다.
다음 단계에서는
- 이전 강의 실제 요청이 도착하기까지의 전체 경로와 Filter / Interceptor / AOP 차이점
를 다룬다.