[BE] 코드 컨벤션 - woowacourse-teams/2026-gachi-gacha GitHub Wiki

1. 코드 스타일

IntelliJ IDEA의 Code Style - Java - Schema에서 팀 공용 코드 스타일인 WootecoStyle을 적용합니다.

• 기본 들여쓰기: 공백 4칸
• 연속 들여쓰기: 공백 8칸
• 탭 사용: 사용하지 않음
• 우측 여백 기준: 120자
• if, for, while, do-while 중괄호 항상 사용
• 와일드카드 import 사용하지 않음
• import 순서: static import -> 일반 import

2. 프로젝트 패키지 구조

패키지 구조는 계층형 아키텍처(Layered Architecture)를 기반으로 하며, 도메인 단위 패키지 안에서 계층별로 하위 패키지를 구성합니다. 역할 기반으로 명확히 구분해 애매한 위치의 클래스가 생기는 것을 방지하고, 패키지 선택의 혼동을 줄여 협업 시 일관성과 유지보수성을 높이기 위함입니다.

{domain}/
├── presentation    // Controller 등 API 요청 처리
│   ├── converter   // DTO ↔ 도메인 객체 변환
│   └── dto
├── application     // Service 등 비즈니스 로직
├── domain          // Entity, VO, 도메인 예외, 리포지토리 인터페이스
│   ├── {subdomain}
│   ├── exception
│   └── repository
└── infra           // 외부 연동, 설정 (config, 외부 API 클라이언트, 보안 등)

ex - auth 도메인은 presentation(OauthController, AuthConfig, AuthArgumentResolver), application(OauthService), domain(OauthId, OauthMember, OauthServerType 등), infra(config, jwt, kakao, security)로 구성됩니다.

계층 간 의존 방향

• presentation → application → domain 순으로 의존하며, 역방향 의존은 지양합니다.
• domain은 다른 계층에 의존하지 않는 것을 원칙으로 합니다 (순수 도메인 로직 유지).
• infra는 domain에 정의된 인터페이스(리포지토리 등)를 구현하는 방식으로 연결합니다.

3. 공통 스타일 가이드

네이밍 스타일

• 변수는 CamelCase를 기본으로 한다. — userEmail
• 패키지명은 단어가 달라지더라도 무조건 소문자를 사용한다. — frontend, useremail
• URL, 파일명은 kebab-case를 사용한다. — /user-email-page
• ENUM이나 상수는 대문자를 사용한다. — NORMAL_STATUS
• 함수명은 소문자로 시작하고 동사로 네이밍한다. — getUserId(), isNormal()
• 클래스명은 명사로 네이밍하고 UpperCamelCase를 사용한다. — UserEmail
• 객체 이름을 함수 이름에 중복해서 넣지 않는다. — line.getLength() (O) / line.getLineLength() (X)
• 컬렉션은 복수형을 사용하고, 컬렉션명을 넣지 않는다. — List ids
• 의도가 드러난다면 되도록 짧은 이름을 선택한다. — retrieveUser() (X) / getUser() (O)
• 함수는 하나의 역할을 수행한다. 단, 부수효과가 있는 함수라면 메서드명으로 나타낸다. — 말을 움직여서 죽일 때 move() (X) / moveAndKill() (O)

메서드 네이밍 가이드

객체를 조회하는 함수는 일관성을 위해 JPA Repository의 네이밍 방식(findXXX)을, Service 단에서는 되도록 getXXX를 사용합니다. 리소스를 읽는 경우에는 readXXX를 사용합니다.

구분	의미	상황	예시	특징
get	존재한다고 확신하는 데이터를 가져올 때	필드 접근, 존재 보장되는 참조	getUserId(), getName()	예외 없음 또는 NPE 가능
find	존재할 수도 있고 없을 수도 있는 대상을 탐색	Repository, 조건 검색	findUserById(), findOrdersByDate()	Optional 또는 null 반환
read	외부 리소스/IO 또는 상태를 읽을 때	파일, HTTP, DB 레코드	readFile(), readFromDB()	부작용 없음 (side-effect free)

Controller / Service 메서드 네이밍 규칙

요청	Controller	Service
목록 조회	readXXX	getXXXs, findXXX
단건 상세 조회	readXXX	getXXX, findXXX
등록	createXXX	addXXX
수정	updateXXX	modifyXXX
삭제	deleteXXX	removeXXX

정적 팩토리 메서드명

• from: 파라미터 개수가 1개일 경우
• of: 파라미터 개수가 2개 이상일 경우

메서드 작성 순서

주로 사용되는 조회 쿼리를 상단에 표시하고, 데이터 조작 명령은 RCUD(read → create → update → delete) 순으로 정렬합니다.

public class ExampleService {
    // public → 바로 아래 관련 private 메서드 위치
    public void doSomething() {
        helperMethod();
    }
 
    // private 메서드가 여러 public에서 사용되면
    // 마지막 public 메서드 뒤로 위치시킴
    private void helperMethod() {
        // ...
    }
}

접근제어자 순서

• static → public → private 순으로 작성한다.
• public 메서드 아래에 관련 private 메서드를 바로 위치시킨다.
• private 메서드가 여러 곳에서 사용되면 가장 마지막 public 뒤에 정리한다.

어노테이션

길이가 짧은 순서대로 위에서부터 배치합니다 (피라미드 형태).

@Test
@DisplayName
void testMethod() {
}

4. Controller

ResponseEntity를 다음과 같은 이유로 사용합니다.

• 반환하는 상태코드를 메서드 안에서 쉽게 알기 위해
• 통일성을 위해

5. Domain

equals & hashCode - 필요 시 사용한다.

• domain 및 entity에서 모두 재정의한다.
• equals 시 id만 비교한다.
• equals 재정의 시 instanceof로 구현한다.
• id는 null 의미를 추가하기 위해 Long 타입을 사용한다.
• domain 생성자에서 null 검사와 규칙 검사를 실시한다.

6. DTO

• DTO는 Controller → Service까지 전달되며, 변환은 Service에서 처리한다. (예: MemberCreateRequestDto → Member 변환은 Service 내에서 처리)
• DTO 관련 정적 팩토리 메서드를 DTO 내부에서 활용한다 (from, of 활용).
• Request DTO 유효성 검사는 다음 항목을 시행한다.
  • null 검사를 한다.
  • 도메인 규칙은 검사하지 않는다 — 도메인 안에서 검사한다.

7. Lombok 사용

항목	규칙
금지 어노테이션	@Setter, @Data

값의 변경을 예측하기 어려우므로 무분별한 사용을 제한하고, 행위 메서드로 의도를 표현합니다.

8. 테스트

Controller

• 실제 요청을 인수 테스트함으로써 신뢰도를 보장한다.
• RestAssured 테스트만 작성한다.
• 해피케이스 테스트를 모두 작성한다 (API 당 테스트).
• 각 상태코드마다 대표 케이스를 1개 이상 테스트한다 (예: 401, 403, 404 각각 하나씩). Service
• Service - H2 DB는 통합 테스트한다.
• Mocking 시 테스트가 실제 운영 코드에 의존하게 되어 리팩터링 내성이 약해지므로 fake DB를 사용한다. Repository
• 쿼리(@Query)를 직접 작성할 시 테스트한다.
• 테스트 비용을 줄이고자 JpaRepository의 기본 제공 메서드나 쿼리 메서드는 테스트하지 않는다. 테스트 네이밍
• 테스트 이름은 DisplayName으로 작성한다.
• 테스트 메서드명은 영어로 간단하게 작성한다.
• 테스트하려는 메서드명 + 상황을 간단히 설명한다.
• 주먹구구식(무지성) 작성을 금지한다.
• BDD 스타일(given / when / then)로 작성한다.

9. API 문서화

개발 단계에서 변동이 잦은 API를 반영하기 위해 Swagger를 사용합니다.

10. 오류 및 예외 처리

Custom 예외를 상태 코드와 title을 지정하여 사용합니다.

{
  "type": "/요청/uri",
  "title": "에러 제목",
  "status": 400,
  "detail": "에러 상세 메시지"
}