백엔드(BE) 코드 스타일 및 시스템 컨벤션

본 문서는 폴더 구조 외에 코드를 작성할 때 지켜야 할 문법적 스타일, 의존성 관리, 어노테이션 규칙 및 테스트 환경 설정에 대해 정의합니다.

1. 기본 명명 규칙 (Naming Conventions)

Java와 Spring Boot의 표준 스타일을 따르며, 누구나 코드를 보고 역할을 유추할 수 있도록 아래의 네이밍 룰을 지킵니다.

• 클래스(Class) 및 인터페이스(Interface): 파스칼 케이스 (PascalCase)
  • 첫 글자는 무조건 대문자로 시작합니다.
  • ✅ MemberController, SubscriptionService, PaymentRepository
• 메서드(Method) 및 변수(Variable): 카멜 케이스 (camelCase)
  • 첫 글자는 소문자로 시작하되, 이어지는 단어의 첫 글자는 대문자로 씁니다.
  • ✅ getMemberInfo(), totalPrice, isDeleted
• 상수(Constant) 및 ENUM 상수: 대문자 스네이크 케이스 (UPPER_SNAKE_CASE)
  • 모든 글자를 대문자로 쓰고 단어 사이를 언더바(_)로 구분합니다.
  • ✅ MAX_RETRY_COUNT, MOBILE_PLAN, ACTIVE
• 패키지(Package): 올 소문자 (All lowercase)
  • 대문자나 특수문자를 절대 사용하지 않습니다.
  • ✅ site.holliverse.customer.application.usecase
• 의미 없는 축약어 금지
  • 타이핑이 조금 길어지더라도 누구나 알아볼 수 있는 명확한 단어를 사용합니다.
  • ❌ int pCnt;, String usrNm;
  • ✅ int productCount;, String userName;

2. 서버 런타임 및 프로파일 제어

서버 실행 시 환경 변수(SPRING_PROFILES_ACTIVE)에 따라 활성화되는 API가 다릅니다.

• Customer API 개발 시: 컨트롤러에 @Profile("customer") 적용
• Admin API 개발 시: 컨트롤러에 @Profile("admin") 적용
• 포트 및 환경변수(.env): 루트 디렉토리에 .env 파일을 생성하고, DB 접속 정보와 허용 호스트(CORS)를 팀 컨벤션에 맞게 세팅합니다.

3. DTO 설계 규칙: 기본은 record

모든 요청(Request) 및 응답(Response) DTO는 불변성을 보장하는 Java record 사용을 원칙으로 합니다. (ArchUnit에서 검사함)

단, 아래의 예외적인 상황에서만 class 사용을 허용합니다:

• 선택 필드가 너무 많아 점진적 확장이 필요할 때
• 복잡한 객체 조립을 위해 @Builder가 필수적일 때
• 회원가입처럼 필드 검증 로직이 무겁게 들어가야 할 때
• 상속이나 다형성이 필요한 경우 (거의 없음)

4. 빈(Bean) 등록 및 의존성 주입

• 생성자 주입: 빈 주입 시 필드 주입(@Autowired)은 금지하며, Lombok의 @RequiredArgsConstructor를 이용한 생성자 주입만 허용합니다.
• Infra 계층 빈 등록 주의: infra 계층의 구현체 클래스에는 @Component를 직접 붙이지 않습니다. 대신 공유 설정(shared.config.runtime)의 @Configuration 클래스 내부에서 @Bean으로 수동 등록하고, RuntimeModule ENUM을 통해 제어합니다.

5. DB 권한 및 트랜잭션 규칙

• 트랜잭션 위치: @Transactional은 오직 usecase 패키지 내의 메서드에만 붙일 수 있습니다. (Web, Persistence, Infra 계층에는 금지)
• 조회 최적화: 데이터를 읽기만 하는 UseCase 메서드에는 반드시 @Transactional(readOnly = true)를 우선 적용합니다.
• DB Role 통제: 초기화 시 3가지 Role(migrator, customer, admin)로 구분하여 권한을 제어합니다. (자세한 스키마 및 Role 부여 쿼리는 로컬 Docker-compose 세팅 가이드 참고)

6. 테스트 검증 (JaCoCo & ArchUnit)

우리 팀은 PR을 올리기 전 로컬에서 테스트 커버리지와 아키텍처 룰을 반드시 통과해야 합니다. CI에서 실패하면 재실행 시간이 오래 걸리므로 로컬 검증을 습관화합니다.

📊 JaCoCo 테스트 커버리지 기준

• 목표 기준: 라인 커버리지 70% 이상, 브랜치 커버리지 50% 이상 (미달 시 빌드 실패)
• 제외 대상: DTO, Exception, Config, Mapper, Enum, Q-class 등 단순 데이터/설정 객체
• 실행 명령어: ./gradlew clean test jacocoTestReport

🏗️ ArchUnit 아키텍처 검사

코드가 팀의 폴더 구조 및 의존성 규칙을 어기지 않았는지 코드로 검증합니다.

• 주요 검사 항목: customer와 admin 간의 상호 참조 금지
  • Controller의 Repository 직접 호출 금지
  • @Transactional 위치 강제
  • DTO의 record 타입 강제
• 실행 명령어: ./gradlew test --tests "site.holliverse.arch.ArchitectureRulesTest"

💡 트러블슈팅 팁: DB 연결 실패(Connection refused) 에러 발생 시, 로컬 환경의 PostgreSQL 컨테이너(holliverse-test-db)가 실행 중(docker ps)인지 먼저 확인하세요.