Skip to content

CONVENTIONS.md

Latest commit

 

History

History
131 lines (92 loc) · 5.07 KB

CONVENTIONS.md

File metadata and controls

131 lines (92 loc) · 5.07 KB
Raw

Java 프로젝트 컨벤션 (Spring Boot/Gradle)

이 문서는 팀 개발 효율/품질/일관성을 위해 자바 프로젝트에서 지킬 규칙을 정리합니다.
이 저장소는 Spring Boot 4 + Gradle + Java 21 + JUnit5 구성을 전제로 합니다.

0) 참고(근거) 문서

  • Google Java Style Guide: https://google.github.io/styleguide/javaguide.html
  • Conventional Commits v1.0.0: https://www.conventionalcommits.org/en/v1.0.0/
  • Semantic Versioning 2.0.0: https://semver.org/

1) 기본 원칙

  • 일관성이 최우선: 개인 취향보다 팀 합의/자동 포맷/리뷰 룰을 우선합니다.
  • 명확성 우선: 축약/트릭보다 읽기 쉬운 코드(이름/구조/테스트)를 선택합니다.
  • 실패는 빠르게: 입력 검증/예외/테스트로 문제를 조기에 드러냅니다.

2) 코드 스타일(포맷팅)

  • 기본 가이드: Google Java Style Guide를 따릅니다.
  • 들여쓰기: 스페이스 사용(탭 금지). (IDE 포맷터로 자동 적용)
  • 한 줄 길이: 기본 100자 권장(문자열/URL 등 불가피한 경우 예외).
  • import: 와일드카드 import 금지. 사용하지 않는 import 제거.
  • 중괄호: 단일 라인 if/for라도 중괄호 사용을 원칙으로 합니다.

IDE 설정(권장)

  • IntelliJ 기준: Save Actions / Reformat code / Optimize imports를 저장 시 수행하도록 설정합니다.

3) 네이밍

  • 패키지명: 전부 소문자. 예) com.example.demo
  • 클래스/인터페이스: PascalCase (명사/명사구). 예) OrderService
  • 메서드/변수: camelCase (동사로 시작 권장). 예) calculateTotal()
  • 상수: UPPER_SNAKE_CASE. 예) MAX_RETRY_COUNT
  • boolean: is/has/can 접두어 권장. 예) isActive, hasPermission

4) 패키지 구조(권장)

기본 베이스 패키지: com.example.demo (현재 프로젝트 기준)

4.1 레이어 구조(단순/기본)

  • .../web (또는 controller): MVC Controller, ViewModel/Request/Response DTO
  • .../service: 유스케이스/비즈니스 로직
  • .../domain: 도메인 모델(엔티티/값 객체/도메인 서비스)
  • .../repository: DB 접근(Repository/DAO)
  • .../config: 설정(Bean, Security, WebMvc, Jackson 등)
  • .../common: 공통 유틸/예외/응답 래퍼/상수

4.2 의존성 방향

  • web → service → domain/repository 단방향을 원칙으로 합니다.
  • service가 web을 의존하면 안 됩니다(역참조 금지).
  • DTO는 web 또는 api 레이어에 두고, domain에 섞지 않습니다.

5) Lombok 사용 규칙(사용 중인 경우)

  • 무분별한 @Data 지양: (특히 엔티티/도메인) 필요 어노테이션을 명시적으로 선택합니다.
  • 불변 우선: DTO는 가능하면 record(Java 21) 또는 불변 객체를 사용합니다.
  • Builder: 생성 인자가 많은 경우에만 사용하고, 의미 있는 기본값/필수값을 분명히 합니다.

6) 예외 처리/응답 규칙

  • 예외는 의미 있게: IllegalArgumentException 남발 대신 도메인/유스케이스에 맞는 예외를 정의합니다.
  • 메시지: 로그/디버깅에 유용한 메시지(식별자/상태)를 포함하되 민감정보는 금지합니다.
  • 로깅: System.out 금지, SLF4J(log.info/warn/error) 사용.

7) 테스트 컨벤션(JUnit 5)

  • 기본 원칙: 새 기능/버그 수정은 테스트와 함께 제출합니다.
  • 테스트 네이밍
    • 단위 테스트: *Test
    • 통합 테스트: *IT (예: DB/외부 시스템 연동)
  • 구조: Given-When-Then(또는 Arrange-Act-Assert)로 작성합니다.
  • 검증 범위
    • service 로직: 단위 테스트 우선
    • web 계층: @WebMvcTest 등으로 컨트롤러 검증
    • 전체 플로우: 필요한 경우에만 @SpringBootTest

8) Git 브랜치/커밋 컨벤션

8.1 브랜치 네이밍

  • main: 배포 가능한 안정 브랜치
  • feature/<topic>: 기능 개발
  • fix/<topic>: 버그 수정
  • refactor/<topic>: 리팩터링
  • docs/<topic>: 문서
  • chore/<topic>: 빌드/설정/잡무

8.2 커밋 메시지(Conventional Commits)

형식:

<type>(<scope>): <subject>

<body>
  • type: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
  • scope: 선택(예: web, service, build, auth)
  • subject: 현재형/명령형으로 간결하게(“add …”, “fix …”)

예:

feat(web): add signup page
fix(service): prevent duplicate order creation
refactor(domain): extract Money value object

9) PR(머지) 규칙

  • 작게 자주: PR은 작을수록 리뷰/회귀가 쉽습니다.
  • 설명 필수: 무엇/왜/어떻게 검증했는지 포함합니다.
  • 체크리스트(권장)
    • 테스트 추가/수정 여부
    • 스크린샷(뷰 변경 시)
    • Breaking change 여부 및 마이그레이션 가이드
    • 성능/보안 영향

10) 버전/릴리즈

  • 버전은 SemVer(MAJOR.MINOR.PATCH)를 따릅니다.
    • MAJOR: 호환성 깨짐
    • MINOR: 기능 추가(호환 유지)
    • PATCH: 버그 수정