Home

Web Project Convention

이 문서는 웹 기반 개발 프로젝트에서 팀의 일관성과 협업 효율을 높이기 위한 개발 컨벤션을 정의합니다. 적용 범위: 프론트엔드 + 백엔드 + GitHub 협업 + 문서 관리

예시 요약

• 이슈: [feat] 로그인 기능 구현
• 브랜치: feat/login
• 커밋: feat(member): 로그인 API 엔드포인트 추가
• 풀리퀘스트: [feat] 로그인 기능 구현 (#이슈번호)

1. 프로젝트 구조 및 네이밍

디렉토리 구조

Backend (Spring)

src/
 ├── domain/         # 기능별 도메인 (user, post 등)
 │    ├── user/
 │    ├── post/
 │    └── comment/
 ├── global/         # 전역 설정, 예외, 응답 처리
 ├── config/         # 환경 설정 (Security, DB 등)
 └── Application.java

Frontend (React / Next.js)

src/
 ├── components/     # UI 컴포넌트
 ├── pages/          # 라우팅 단위
 ├── hooks/          # 커스텀 훅
 ├── context/        # 전역 상태 관리
 ├── utils/          # 유틸 함수
 ├── styles/         # 전역 스타일
 └── services/       # API 통신 모듈

네이밍 규칙

구분	컨벤션	예시
클래스 / 컴포넌트	PascalCase	UserController, PostService, UserCard
변수 / 함수	camelCase	getUserInfo, isLoggedIn
상수	UPPER_SNAKE_CASE	MAX_PAGE_SIZE, TOKEN_EXPIRE_TIME
패키지 / 폴더	소문자	user, auth, config
파일명	소문자 + 하이픈(-)	user-service.ts, post-detail.tsx

2. 코드 스타일

공통

• 들여쓰기: 2칸 (JS/TS) / 4칸 (Java)
• 한 줄 길이: 100~120자
• console.log / System.out.println 등은 PR 전 반드시 제거
• 불필요한 import 제거

---

Backend (Spring)

• 계층 구조 구분
  • @Controller, @Service, @Repository 명확히 역할 구분
• DTO 명명 규칙
  • UserRequest, UserResponse, UserDto
• 메서드 네이밍
  • 동사 + 목적어 (findUserByEmail, createPost)
• 예외
  • 커스텀 예외는 XXXException 으로 통일 (UserNotFoundException)
• Swagger 문서화 사용

@Operation(summary = "사용자 조회", description = "이메일로 사용자를 조회합니다.")
@ApiResponses({
  @ApiResponse(responseCode = "200", description = "조회 성공"),
  @ApiResponse(responseCode = "404", description = "사용자 없음")
})

Frontend (React / Next.js)

• 함수형 컴포넌트 사용
• use 접두사로 커스텀 훅 작성 (useAuth, useFetch)
• Props 타입 지정 (TypeScript interface 우선)
• TailwindCSS 또는 Styled Components 중 하나로 통일
• 컴포넌트 설계 시 Atomic Design 지향
  • atoms, molecules, organisms 폴더로 분리 가능

3. GitHub Flow

GitHub Flow는 단일 메인 브랜치를 기준으로, feature 브랜치를 만들어 작업 후 PR을 통해 병합하는 방식입니다.

브랜치 전략

브랜치	설명
main	배포용 브랜치
feature/*	기능 개발용 브랜치
fix/*	버그 수정용 브랜치

main 브랜치에서 초기 세팅 (back, front) 진행 후, 도메인 별로 front, back 개발 모두 진행

예시

feature/login
feature/user-profile
fix/post-delete

---

4. 커밋 컨벤션

기본 형식

<type>(<scope>): <subject>

예시

feat(user): add login API
fix(post): correct null pointer exception
refactor(auth): simplify token validation logic
docs(readme): update setup instructions
style(header): fix alignment
chore(deps): upgrade Spring Boot version

타입 목록

type	설명
feat	새로운 기능 추가
fix	버그 수정
refactor	코드 구조 변경 (동작 동일)
style	포맷, 세미콜론 등 비기능 변경
docs	문서 수정
test	테스트 코드 추가/수정
chore	빌드, 의존성, 환경 설정 변경

---

5. Pull Request & Issue 컨벤션

Issue

형식

[feat] 로그인 기능 구현

내용 템플릿

## 설명
- 사용자 로그인 기능 구현

## 할 일
- [ ] 로그인 API 연동
- [ ] JWT 저장/만료 처리
- [ ] 상태 관리 (Context)

---

Pull Request

제목

[feat] 로그인 기능 구현 (#이슈번호)

본문 템플릿

## 이슈

## 요약
- 로그인 API 연동 및 인증 상태 관리 추가

## 변경 사항
- AuthContext 추가
- /api/login 연동
- JWT 저장 및 만료 처리

## 테스트
- [x] 로그인 성공 시 메인 페이지 이동 확인
- [x] 잘못된 비밀번호 시 에러 메시지 확인

주의 사항

• PR 시 공통 처리 코드 부분 수정시 팀원들에게 상세하게 알릴 것
• 도메인간 영향을 주는 수정 부분 있는 경우(ex) 유저 엔티티 객체 → DTO 전환)에는

---

6. 문서화

• API 문서화는 Swagger 사용
  • /swagger-ui.html 또는 /api-docs 경로에서 확인
  • 각 API는 @Operation, @ApiResponses, @Schema 활용
  • DTO에는 명확한 설명 필수
• README.md 필수 포함 항목
  • 프로젝트 개요
  • 기술 스택
  • 실행 방법
  • GitHub Flow 전략
  • Swagger 문서 접근 방법
  • 팀원 / 역할

---

7. 협업 규칙

• 모든 PR은 리뷰 후 병합
• main 직접 커밋 금지
• 공통 코드 포맷터 적용
  • Backend: Checkstyle
  • Frontend: ESLint + Prettier
• .env 파일은 .gitignore에 포함
  • 대신 .env.example 제공
• 코드 리뷰는 논리적 단위로 진행 (한 PR에 너무 많은 변경 금지)

---

8. 기타 권장 사항

• 커밋은 작고 명확하게, 하나의 목적만 담을 것
• 변수/함수명은 의도를 드러내게 작성 (isValidToken, fetchUserData)
• Swagger 문서가 실제 동작과 어긋나지 않도록 주기적으로 점검
• 팀원 간의 코드 스타일 차이는 린터로 자동 정리

---

요약

• GitHub Flow 기반: main + feature/*
• Swagger 기반 API 문서
• 일관된 네이밍과 코드 포맷
• PR 리뷰 필수
• README와 Swagger 문서로 투명한 협업