13 Coding Convention

프로젝트 개발 가이드 v0.1

본 문서는 팀 내에서 일관된 코드 스타일과 협업 방식을 유지하기 위한 코딩 컨벤션 & 네이밍 컨벤션, 프로젝트 구조를 정리한 자료입니다. 필요 시 팀원들과 협의 후 업데이트해 주세요.

---

1. 프로젝트 구조

• Domain 기준 패키지 생성
  • 각 도메인별로 최상위 패키지를 생성한 후, 하위에 세부 도메인 및 역할별 패키지를 구성합니다.
  • 예시 구조:

    {domain}
      └── {subdomain}
            ├── controller
            ├── service
            ├── dto
            ├── entity
            └── repository
    

---

2. 코딩 컨벤션 & 네이밍 컨벤션

2.1 Class, Variables, Functions, Constants

• Class:
  • 명명 규칙: PascalCase
    • 예: UserController, UserService
• Variables & Functions:
  • 명명 규칙: camelCase
    • 예: userName, getOrderItems()
• Constants:
  • 명명 규칙: 영대문자 + snake_case
    • 예: MAX_COUNT, DEFAULT_USER_ROLE

2.2 Controller

• Controller는 Request, Response 전용 객체를 사용하여 클라이언트와의 데이터 교환을 담당합니다.
• 예외 케이스는 반드시 처리하고, 관련 API 스펙은 @ApiResponse 등의 애너테이션으로 문서화합니다.
• DTO 분리:
  • Controller에서 사용하는 Request/Response 객체는 보통 record로 작성하며, 네이밍 규칙은 {Domain}{MethodName}Request 또는 {Domain}{MethodName}Response 형태로 합니다.
  • Controller 내에 별도의 Dto 서브패키지를 두어 Service에서 사용하는 DTO와 구분합니다.

2.3 Service

• 트랜잭션 관리:
  • 서비스 계층에서 @Transactional을 사용하여 트랜잭션을 관리합니다.
• DTO 변환:
  • 객체와 DTO 간 변환 로직은 Service 계층에서 수행합니다.
  • 변환 메서드는 보통 static으로 구현하며, 아래와 같은 네이밍 규칙을 따릅니다.
    • of: 여러 파라미터를 받아 DTO로 조합할 때
    • from: Entity 객체 하나를 DTO로 변환할 때
    • toEntity: DTO를 Entity로 변환할 때

2.4 Entity

• JPA 변경 감지:
  • 엔티티 내 필드의 변경은 변경 감지(Dirty Checking)를 활용합니다.
  • 이를 위해 엔티티 내에 별도의 필드 변경 메서드를 작성하며, Setter 사용은 지양합니다.
• 객체 생성:
  • 객체 생성 시 new 대신 **@Builder**를 적극 사용하여 가독성과 불변성을 높입니다.

2.5 DTO (Data Transfer Object)

• DTO 사용:

  • Controller와 Service에 사용하는 DTO는 용도가 다르므로 분리하여 관리합니다.
  • Controller에서는 클라이언트와의 요청/응답을 위한 Request/Response 객체를 주로 record로 작성하며,
    Service에서 공통적으로 사용하는 데이터 구조는 별도의 DTO 레이어에 생성합니다.

• 네이밍 가이드라인:

  • Controller용: {동사}{명사}Request / {동사}{명사}Response
    • 예: UserJoinRequest, UserUpdateResponse
  • Service용: {적절한이름}Dto

• DTO 변환 메서드:

  • DTO 내에 변환 메서드를 작성하여 Entity와의 변환을 명확하게 합니다.
  • 일반적으로 많이 사용하는 메서드 이름은 of, from, toEntity입니다.

• Java Record:

  • 간결함과 불변성을 위해 Controller의 Request/Response 객체는 record를 사용하는 것을 권장합니다.

2.6 코드 자동 포맷팅

• 코드 포맷팅 툴 사용:
  • 코드 스타일 통일성을 위해 자동 포맷팅 도구(예: IntelliJ의 코드 정리 기능 등)를 활용할 수 있습니다.
  • 참고 자료: 코드 자동 포맷팅 관련 블로그

2.7 기타

• 변수/함수명:
  • 모든 변수와 함수명은 camelCase로 작성합니다.
• Docker & 환경 변수 관리:
  • 프로젝트 배포 및 실행 환경은 Docker를 활용하는 것을 고려합니다.
  • 환경 변수 관리는 .env 파일을 사용하며, Doppler와 같은 툴로 관리할 수 있습니다.

2.8 Testing

• Service 단위 테스트: 필수 작성
• Controller 통합 테스트: 필요 시 작성 (선택적)

---