Skip to content

백엔드 컨벤션

Jump to bottom
나경호(Na Gyeongho) edited this page May 27, 2025 · 1 revision

사용 툴

백엔드

Java 17 + Spring Boot 3.4.2

데이터베이스

MySQL

문서화

Swagger UI

  • 규칙
    • 요청/응답 데이터는 @Schema로 정의
    • 컨트롤러단은 공통 클래스로 처리

일정 관리

Notion 칸반보드

PR AI

https://www.coderabbit.ai/

코드 컨벤션

네이밍 및 스타일

패키지 및 전체 코드

  • 패키지 구조는 도메인 기준으로 한다.
  • 클래스와 선언부 필드 사이는 개행한다.
  • @Valid를 통한 입력값 검증을 진행한다.
  • Enum의 값을 정의할 때, 후행 쉼표를 사용한다.
  • Lombok 라이브러리를 사용하되, 그 범위를 제한한다.
  • @Getter, @NoArgsConstructor, @RequiredArgsConstructor
  • 어노테이션이 여럿 있는 경우, 중요한 것을 가장 상단에 배치한다.
    • Lombok의 어노테이션을 가장 아래에 배치한다.

변수 및 메서드

  • 메서드의 순서는 public을 위에 두되, private의 경우 사용하는 메서드 아래에 둔다.
  • 필드 변수는 static final → final → instance variable 순서로 정의한다. (상수와 변수 사이 공백)
  • 웬만한 상황에서의 static factory method는 지양한다.
  • 메서드 파라미터에는 final을 사용하지 않는다.

컨트롤러

  • @RestController에서 @RequestMapping을 최상단에 사용하지 않는다.

서비스

  • @Transactional 어노테이션을 클래스 최상단에 작성하지 않는다.
    • 메서드 레벨에 필요한 경우 작성

엔티티

  • @Table과 @Column 으로 테이블명, 컬럼명을 명시한다.
  • 예약어인 경우 복수형 또는 동의어를 찾아 작성한다 (예: order → orders)
  • @Column 어노테이션의 nullable 여부를 명시한다.
  • @Embeddable 내부에는 @Embedded을 사용하지 않는다.

테스트

  • 메서드명은 한글로 작성한다. @DisplayName는 사용하지 않는다.
  • 데이터는 메서드 내부에서 설정한다.
    • O: given절이 길어지지 않음
    • X: Entity 검증을 거치지 않음, 문맥이 드러남
  • 테스트 메서드에 given, when, then을 주석으로 표기한다.
    • 두가지 이상이 될 경우 컴마(,)로 연결한다.
  • 테스트 범위
    • 비즈니스 로직 단위 (도메인 위주, 리소스 투자는 추후 결정)

로깅

  • 로그 레벨은 아래와 같이 관리한다. 추가로 필요하다면 자유롭게 로깅한다.
    • info: 외부 API 응답 / 요청은 남긴다.
    • < 이 아래는 슬랙 봇 메시지로 알림 받아야 함 >
    • warn: 내일 아침에 데일리에서 확인해도 무방한 사항
    • error: 자다가도 일어나서 확인해야 하는 사항 → 외부 API 타임아웃, DB 저장 실패 등

예외 처리

  • 커스텀 예외를 사용한다. 각각 추상화된 카테고리를 Advice에서 핸들링한다.

  • 추상 예외 (BadRequestException 등)을 각각의 도메인/서비스 레이어에서 구현한다.

  • 모든 Custom의 superclass로 잡으면 Advice에서 상태 코드를 알지 못한다. 즉 하위 레이어에서 응답 상태와 관련한 내용을 알게 된다.

  • Global 의존은 피해야하지만, Exception에 대해서는 어쩔 수 없이 글로벌 패키지를 받아오기로 한다. 추상화 예외의 변경 가능성이 적기 때문이다.

  • 에러 메시지는 각각의 예외에 작성한다.

  • 추후 디벨롭 예정

    val error: String,
val status: Int,
val message: String,
val timestamp: String

image

깃 컨벤션

이슈 관리

  • 노션 칸반보드로 대체
<!--- 
❗️ 이슈 제목은 아래의 형식을 맞춰주세요 
- `[Feat]`  :  기능 추가 구현
- `[Fix]`  : 코드 수정, 버그/오류 해결
- `[Performance]` : 개선할 성능 이슈
- `[Docs]` : README 등의 문서 수정                      
- `[Deploy]` : 배포 관련                         
- `[Refactor]` : 코드 리팩토링(기능 변경 없이 코드만 수정할 때)     
- `[Test]`: 테스트 추가/수정          
- `[Hotfix]` : 급한 핫픽스        
-->

## ✨ 이슈 내용

-

## ✅ 체크리스트

- [ ] Assignees / Labels 선택
- [ ] 
- [ ]

PR 관리

  • PR 템플릿으로 생성 + Assignees 설정
  • 머지 시 squash and merge → delete branch (깔끔한 브랜치 관리를 위해)

PR 생성 시 제목 형식

[Feat] 구현할 내용

PR 템플릿

<!-- - 
❗️ PR 제목은 아래의 형식을 맞춰주세요 
- `[Feat]`  :  기능 추가 구현
- `[Fix]`  : 코드 수정, 버그/오류 해결
- `[Performance]` : 개선할 성능 이슈
- `[Docs]` : README 등의 문서 수정
- `[Deploy]` : 배포 관련
- `[Refactor]` : 코드 리팩토링(기능 변경 없이 코드만 수정할 때)
- `[Test]`: 테스트 추가/수정
-->
### 관련 이슈가 있다면 적어주세요.

## 📌 개발 이유

## 💻 수정 사항

## 🧪 테스트 방법

## ⛳️ 고민한 점 || 궁굼한 점

## 🎯 리뷰 포인트

## 🙏 리뷰어에게 남기고 싶은 말
<!-- Reviewers, Assignees, Labels 지정해주세요 -->

## 📁 레퍼런스

브랜치 관리

Git Flow 전략

image

main : QA 마친 최종 운영 서버

develop : 개발하면서 코드 모을 공간 default

feature : 기능을 개발하며 각자가 사용할 브랜치

  • 브랜치명은 feat/이슈번호 형식
    • 예시: feat/1-initial-setup

PR 유의 사항

develop → main PR 시 체크 사항

  1. develop 브랜치에서 main 브랜치 pull (conflict 있을 시, 해결)
  2. PR 머지 할 땐, squash 머지 대신 일반 commit merge (커밋 내역 유지 목적)
    1. 작업 브랜치에서 develop PR merge 시에는 squash 머지

커밋 컨벤션

  • feat : 새로운 기능 구현
  • fix : 코드 수정, 버그/오류 해결
  • chore : 동작에 영향 없는 코드 or 변경 없는 변경 사항(주석 추가 등)
  • docs : README 등의 문서 수정
  • deploy: 배포 관련
  • refac : 전면 수정, 코드 리팩토링
  • test: 테스트 추가/수정

예시

feat : 내용

ex) git commit -m "fix : ProjectDetailResponseDto 수정"

ex) git commit -m "feat : 특정 프로젝트 가져오는 API"

README 트러블슈팅

  • 하단에 기록 남기기!!! ⇒ 모두에게 도움이 되는 기록들

소통 문화

소통방식

  • 궁금한거나 필요한 부분은 그때그때 전부 편하게 얘기하기 ✨
  • 최대한 빠르게 확인하고, 힘들다면 언제쯤 확인 가능할지 언급하기
    • 찬기: 18:00 ~ 02:00 (많이 유동적)
    • 경호: 19:00 ~ 01:00 (회사 10:00~19:00)
    • 채영: 15:00 ~ 03:00 (많이 유동적)

소통도구

  • 슬랙 파트채널
    • 편하게 작업 관련 부분 논의 및 소통
  • 슬랙 팀채널
    • 전체 공유가 필요하거나 작업 일정 등 정리된 내용 공유 시

공유방식

  • 깃허브 PR
    • 최대한 자세히, 친절하게
    • 최소 한명 이상 확인 하되, 기본적으로 모두가 approve 하는 방향으로 (너무 급할 때 제외)
  • 노션 칸반
    • 탬플릿 생성 시 상세하게 내용 작성

메서드명 컨벤션

Controller 레이어

  • POST (Create): add (예: addUser, addProduct)
  • GET (Read): get (예: getUser, getProduct)
  • PUT (Update): fix (예: fixUser, fixProduct)
  • DELETE (Delete): remove (예: removeUser, removeProduct)

Service 레이어

  • Create: create (예: createUser, createProduct)
  • Read: find (예: findUser, findProduct)
  • Update: update (예: updateUser, updateProduct)
  • Delete: delete (예: deleteUser, deleteProduct)

목차

Clone this wiki locally