Demo Application

본 리포지토리는 엔터프라이즈 환경을 고려하여 기능성(도메인형 구조)과 유지보수성을 극대화 하도록 설계된 Spring Boot 3 기반의 백엔드 데모 프로젝트입니다.

🏗️ Architecture & Project Structure

기존의 계층형(Layered) 디렉터리 분산 구조를 탈피하고, 기능/도메인 별로 응집력을 높인 Package-by-Feature (도메인형 구조) 아키텍처를 채택했습니다.

src/main/java/com/example/demo
├── common             // 전역적으로 쓰이는 DTO, Exception, Util 등
├── config             // Swagger, WebMvc, Security 등 전역 설정
├── interceptor        // 로깅, 인증 관련 시스템 빈
└── domain             // 🌟 도메인(업무/기능) 기준 패키지
    ├── health         // 헬스 체크 도메인
    │   ├── controller
    │   └── mapper
    └── home           // 홈 도메인
        └── controller

핵심 개편 아키텍처

1. 커스텀 비즈니스 에러 코드 구조 도입:
   • HTTP Status 코드와 비즈니스 논리 응답(BaseResponseCode.java - "9101", "0000")을 철저히 분리하여 프론트엔드와 유연하게 연동 가능하도록 GlobalExceptionHandler를 다형성 인터페이스(ResponseCode) 기반으로 설계했습니다.
2. 비동기 롤링 로그 (Async + Rolling Logback):
   • 애플리케이션 로그, 에러 전용 로그, 비즈니스 추적(Trace) 로그가 용량(100MB/3GB) 기반으로 철저히 분산 및 압축 저장되며 I/O 병목을 유발하지 않도록 설정되었습니다. (logback-spring.xml 내 AsyncAppender 적용)
3. 가독성 높은 SQL 로깅 (log4jdbc):
   • ? 처리된 PreparedStatement 파라미터가 자동으로 바인딩된 온전한 SQL 문자열이 커스텀 콘솔 출력 [SQL] 말머리와 함께 출력되어 개발 디버깅 능률을 높입니다.

🛠️ Technology Stack

• Languages: Java 17
• Framework: Spring Boot 3.0.x
• Database: PostgreSQL
• ORM / Data Access: MyBatis (Spring Boot Starter 3.x)
• Log Management: SLF4J + Logback + Log4jdbc
• Template Engine: Thymeleaf
• API Documentation: Springdoc OpenAPI (Swagger v3)

💡 코드 컨벤션 및 규칙: 프로젝트의 자세한 코딩 가이드라인은 RULES.md를 참고해 주세요.

🚀 Getting Started

Prerequisites

• JDK 17 이상
• PostgreSQL (로컬 5432 포트에 구동되어 있어야 합니다.)
  • Database: demo
  • Username: postgres
  • Password: postgres

🛠️ 로컬 DB(Docker) 구동 방법: 프로젝트 루트에 포함된 docker-compose.yml을 활용하여 로컬 개발용 데이터베이스를 손쉽게 띄울 수 있습니다.

docker-compose up -d

(위 커맨드 실행 후 docker ps로 postgres 컨테이너가 정상 구동 중인지 확인해 주세요.)

DB 접속 환경은 src/main/resources/application-local.yml 에서 수정할 수 있습니다.

Build & Run

프로젝트 루트 경로에서 아래의 Gradle 명령어를 통해 빌드 및 실행할 수 있습니다.

# 1. Clean & Build
./gradlew clean build

# 2. Run the application (Local Profile)
./gradlew bootRun

또는 내장된 스크립트를 사용하여 백그라운드 구동이 가능합니다.

./run.sh    # 데몬 서버 스타트
./stop.sh   # 데몬 종료

📖 API Documentation

애플리케이션이 구동된 상태에서 아래 경로로 접속하시면 현재 등록된 컨트롤러 API 명세를 Swagger UI를 통해 실시간으로 확인하고 테스트할 수 있습니다.

• Swagger UI: http://localhost:8080/swagger-ui.html
• OpenAPI JSON: http://localhost:8080/api-docs