Spring Boot Boilerplate 설계 가이드

이 문서는 보일러플레이트의 핵심 설계 원칙과 패턴을 정리한 가이드입니다.

📐 아키텍처 원칙

Layer Architecture

Controller → Service → Repository
계층 역할 규칙
Controller 요청/응답 처리 Repository 직접 사용 ❌, Entity 사용 ❌
Service 비즈니스 로직 Entity ↔ DTO 변환 담당
Repository 데이터 접근 QueryDSL에서 DTO 직접 반환 가능

API 설계 규칙

📁 파일 업로드

설계 원칙

환경별 저장 전략 (Strategy Pattern)

// 로컬 환경: LocalFileStorage (컴퓨터 경로에 저장)
// 운영 환경: SupabaseFileStorage (클라우드에 저장)

| 환경 | 저장소 | 설정 | |——|——–|——| | 개발 | 로컬 파일시스템 | supabase.enabled: false | | 운영 | Supabase Storage | supabase.enabled: true |

yml;에 따라 운영, 로컬에서 수파베이스용, 로컬용 파일 처리 빈이 주입

🗄️ JPA 설계

연관관계 원칙

Entity vs DTO

변환메소드는 DTO측에서
 DTO → Entity
Entity entity = dto.toEntity();
 Entity → DTO  
DTO dto = DTO.from(entity);

Entity - DB 매핑, 비즈니스 편의 메소드 (상태 변경)
편의메소드에서 exception 발생시켜도 공통처리 됨. DTO - 변환 메소드, API 요청/응답 기본적으로 공통DTO 쓰다가 새로운 DTO가 필요하면 그때그때 만들기.

Repository 규칙

Paging Contrroller 바인딩

📤 응답 표준화

성공 응답

ResponseEntity<ApiResponse<T>>

// 사용 예시
return ResponseEntity.ok(ApiResponse.success("조회 성공", data));

페이징 응답

PageResponse<T>  // Page<>의 필요한 필드만 추출 Page<>는 안 쓰는 필드 너무 많음

에러 응답

ErrorResponse //모든 에러 상황에서 일관된 JSON 구조로 응답

HTTP 상태 코드

| 코드 | 사용 | |——|——| | 400 | 비즈니스 규칙 위반 | | 401 | 인증 필요 | | 403 | 권한 없음 | | 404 | 리소스 없음 | | 409 | 중복 리소스 |

이게 예외세분화인거고,, 글로벌처리에 대한 내용이없군

🔐 Security

로그인 정보 사용

@AuthenticationPrincipal CustomUserAccount userAccount

JWT 구조

🔧 환경 분리

환경 파일 특징
개발 application.yml ddl-auto: create, SQL 초기화
운영 application-prod.yml ddl-auto: update, SQL 초기화 비활성화

📝 로그

✅ 보일러플레이트 구현 현황

기능 상태 파일/패키지
Layer Architecture ✅ Controller/Service/Repository 분리
API 표준 응답 ✅ ApiResponse, PageResponse
예외 처리 ✅ GlobalExceptionHandler
JWT 인증 ✅ jwt/ 패키지
OAuth2 로그인 ✅ 카카오, 구글
파일 업로드 ✅ file/ 패키지, Strategy Pattern
게시판 ✅ community/ 패키지
댓글 ✅ community/comment/
로그 설정 ✅ logback-spring.xml
환경 분리 ✅ application.yml / application-prod.yml
Docker ✅ Dockerfile
Swagger ✅ /swagger-ui.html
Actuator ✅ /actuator/health

🚀 추가 고려사항 (선택)

현재 미적용 (필요시 추가)

| 기능 | 설명 | 언제 필요? | |——|——|———–| | Redis | 세션/캐시/토큰 블랙리스트 | 서버 다중화, 로그아웃 즉시 무효화 | | 이메일 발송 | 비밀번호 찾기, 알림 | 사용자 알림 필요 시 | | 스케줄러 | 배치 작업 (@Scheduled) | 고아 파일 정리, 통계 집계 | | 캐싱 | @Cacheable | 자주 조회되는 데이터 | | Rate Limiting | API 호출 제한 | 악용 방지 | | AOP 로깅 | 메소드 실행 시간 측정 | 성능 모니터링 | | 웹소켓 | 실시간 양방향 통신 (채팅, 알림) | CSR + JWT 완성 후 (STOMP + SockJS + JWT 인증, SSR 단계에서는 하지 말 것) |

프론트엔드 분리 시

현재 Thymeleaf 템플릿이 포함되어 있음. 완전한 REST API 서버로 사용하려면:

📚 참고 문서