<aside> ❗ 본 문서는 전반적인 개발 프로세스 및 코드 컨벤션에 대한 가이드를 제공합니다.

</aside>

가이드라인

시작하기

본 문서는 프로젝트 개발 과정에서 일관성과 효율성을 높이기 위해 따라야 할 개발 프로세스와 코드 컨벤션을 안내합니다. 백엔드 프로젝트에 적용되는 규칙을 상세히 설명하며, 브랜치 전략, 네이밍 규칙, 커밋 메시지 작성법, 그리고 이슈 및 PR 관리에 대한 지침을 포함하고 있습니다.

<aside> ❗ 해당 문서는 항상 최신 상태를 유지해야 합니다. 가이드에 변경이 있는 경우 해당 문서를 업데이트해 주세요.

</aside>

컨밴션

Branch 전략

<aside> ❗ 현재는 main 브랜치만 사용하여 모든 개발과 배포를 진행합니다. 하지만, 애플리케이션 출시 이후에는 테스트를 위한 develop 브랜치를 추가로 도입할 계획입니다.

</aside>

GitHub Flow 는 간단한 분기 기반 워크플로우 입니다. 본 프로젝트는 Github Flow 기반의 브랜치 전략을 활용하고 있습니다.

본 프로젝트에서 사용 가능한 브랜치 종류는 다음과 같습니다:

브렌치 유형 설명
main 항상 배포 가능한 상태를 유지하는 브랜치입니다. 모든 기능과 버그 수정은 이 브랜치에 최종적으로 병합됩니다.
feature/* 새로운 기능을 개발하기 위한 브랜치입니다. 기능별로 브랜치를 생성하며, 작업이 완료되면 main 브랜치로 병합됩니다.
fix /* 버그를 수정하기 위한 브랜치입니다. 각 버그 수정 작업은 개별 브랜치에서 진행되며, 완료되면 main 브랜치로 병합됩니다.
refactor/* 코드 리팩터링을 위한 브랜치입니다. 기능의 동작은 그대로 유지하면서 코드의 구조를 개선할 때 사용하며, 완료되면 main 브랜치로 병합됩니다.

main 브랜치는 CI/CD 파이프라인을 통해 자동화된 배포가 이루어지는 주요 브랜치입니다. 이 브랜치에 병합된 코드는 자동으로 빌드되고, 테스트를 거쳐 최종적으로 배포됩니다

Branch Naming 컨벤션

Branch Naming 컨벤션은 작업 흐름을 명확히 추적할 수 있도록 도와줍니다. 또한, JIRA 티켓을 사용하여 이슈와 작업을 관리하기 때문에, 브랜치명에 이슈 번호를 포함하여 작업과 이슈를 쉽게 연동할 수 있습니다.

네이밍 구성은 다음과 같습니다:

{Branch 유형}/{Jira 이슈 ID}-{브랜치 설명}

Branch Naming 예시

Commit Message 컨벤션

<aside> ❗

커밋 메시지 규칙을 강제하기 위해 Husky와 Commitlint를 사용합니다. 커밋 메시지가 규칙에 맞지 않으면, Husky가 자동으로 커밋을 거부할 수 있으니, 커밋 메시지를 작성할 때는 이하 규칙을 준수하세요.

</aside>

이 컨벤션은 커밋 메시지를 구조화하여 코드 변경의 목적과 내용을 간결하고 명확하게 전달하도록 합니다.

  1. 커밋 메시지 형식

커밋 메시지는 다음과 같은 형식을 따라야 합니다:

<타입>: <제목>
feat: 
[선택적 본문]
[선택적 바닥글]
  1. 커밋 메시지 타입

다음은 사용 가능한 커밋 메시지 타입과 그 의미입니다:

타입 설명
feat 새로운 기능 추가
fix 버그 수정
docs 문서 수정
style 코드 포맷팅 변경 (코드 동작 변경 없음)
refactor 코드 리팩토링
test 테스트 코드 추가/수정
chore 빌드 작업, 패키지 매니저 수정 등
  1. 커밋 메시지 규칙

Java 코딩 컨벤션

<aside> ❗ Java 코딩 컨벤션을 준수하기 위해 **Checkstyle**과 **EditorConfig**를 사용하고 있습니다. 또한, **Husky**를 통해 코드 컨벤션 준수 여부를 자동으로 검토합니다. 관련 설정과 구체적인 내용은 초기 개발환경 설정 문서에서 확인하실 수 있습니다.

</aside>

본 프로젝트의 모든 컨벤션은 아래의 “네이버 캠퍼스 핵데이 Java 코딩 컨밴션” 을 기준으로 합니다.

캠퍼스 핵데이 Java 코딩 컨벤션

추가적인 코딩 컨벤션은 다음과 같습니다:

스프링 코딩 컨벤션

테스트 코드 컨벤션

디렉터리 구조

디렉토리 1차 항목 설명
api - Swagger 설정 파일 및 API 스펙과 문서화 관련 파일이 위치합니다.
presentation controller HTTP 요청을 처리하고 비즈니스 로직을 호출하는 컨트롤러 클래스들이 위치합니다.
dto API 요청과 응답에서 사용하는 데이터 전송 객체들이 위치합니다.
domain service 비즈니스 로직을 수행하는 서비스 클래스들이 위치합니다.
usecase 애플리케이션의 특정 유스케이스를 처리하는 클래스들이 위치합니다.
persistence repository 데이터베이스와의 상호작용을 담당하는 레포지토리 클래스들이 위치합니다.
entity 데이터베이스 테이블과 매핑되는 엔티티 클래스들이 위치합니다.
vo entity에 사용되는 불변 객체들이 위치합니다.
common util, mapper, converter… 레이어에 포함되지 않는 기타 협력 클래스들이 위치합니다.
exception - 사용자 정의 예외 클래스와 예외 처리 관련 핸들러 및 유틸리티들이 위치합니다.

아키텍쳐 품질 검증

시작하기

<aside> ❗ 아키텍처 규칙 준수 여부를 자동으로 검증하기 위해 ArchUnit을 사용하고 있습니다. ArchUnit 테스트는 Junit5와 통합되어 있어, CI 테스트 과정에서 함께 수행됩니다.

</aside>

본 프로젝트는 ArchUnit을 활용하여 코드베이스의 아키텍처 규칙을 자동으로 검증합니다. 이를 통해 프로젝트의 구조적 일관성을 유지하고, 의도하지 않은 의존성을 방지합니다. 주요 아키텍처 검증 규칙: 레이어 의존성, 레이어 별 컨벤션, 패키지 구조, 네이밍 컨벤션, 코딩 컨벤션 등

개발자는 테스트를 실행하여 커밋 전 아키텍처 규칙 준수 여부를 확인할 수 있습니다. 새로운 아키텍처 규칙 추가나 기존 규칙 수정은 팀 논의를 거쳐 결정됩니다.

<aside> 💡

</aside>

아키텍쳐 테스트는 다음을 보장합니다:

개발 프로세스

개발 Flow

  1. Jira에서 작업 할 이슈를 스프린트에 추가합니다.

변경 이력:

| --- | --- | --- | --- |