Skip to content

Home

Jump to bottom
sem_in_github edited this page Aug 12, 2025 · 10 revisions

BE:OUR wiki HOME

안녕하세요, BE:OUR의 백엔드 위키입니다! 🤗
이 문서는 BE:OUR 프로젝트의 구조와 개발 가이드를 문서화한 공간입니다.

목차

  1. 🛠 기술 스택
  2. 📂 폴더 구조
  3. 📘 기능 명세
  4. 🛢 ERD
  5. 🔐 JWT 인증 흐름
  6. ❗ 에러 처리 정책
  7. 📘 API 명세서
  8. 🚀 배포 전략
  9. 📂 브랜치 전략
  10. 📝 커밋 컨벤션
  11. 🛠 코드 컨벤션
  12. 📄 기타 문서(추가 예정)

🛠 기술 스택

분류 기술
Language Java 17
Framework Spring Boot 3.4.5, Spring Security, Spring Data JPA
DB MySQL
Auth JWT (Access/Refresh), Cookie 기반 인증
Build Tool Gradle
Infra AWS EC2(Docker container: Spring Boot, MySQL), Nginx, AWS S3, CloudFront, Route53
CI/CD GitHub Actions, Docker, Discord webhooks
Version Control Git / GitHub


📂 폴더 구조

📦src
 ┣ 📂main
 ┃ ┣ 📂java
 ┃ ┃ ┗ 📂com.beour
 ┃ ┃   ┣ 📂banner          # 배너 도메인
 ┃ ┃   ┣ 📂global          # 전역 설정 및 공통 유틸
 ┃ ┃   ┃ ┣ 📂config        # CORS, Swagger 설정 등 환경 설정
 ┃ ┃   ┃ ┣ 📂entity        # 공통 엔티티
 ┃ ┃   ┃ ┣ 📂exception     # 전역 예외 처리 및 커스텀 예외
 ┃ ┃   ┃ ┣ 📂file          # 파일 업로드
 ┃ ┃   ┃ ┣ 📂jwt           # JWT 인증 관련 필터, 유틸, 쿠키 관리
 ┃ ┃   ┃ ┣ 📂response      # 공통 API 응답 포맷
 ┃ ┃   ┃ ┣ 📂security      # Spring Security 설정
 ┃ ┃   ┃ ┗ 📂validator     # 커스텀 유효성 검증
 ┃ ┃   ┃
 ┃ ┃   ┣ 📂reservation     # 예약 도메인
 ┃ ┃   ┣ 📂review          # 리뷰 도메인
 ┃ ┃   ┣ 📂space           # 공간 도메인
 ┃ ┃   ┣ 📂token           # 토큰 도메인
 ┃ ┃   ┣ 📂user            # 사용자 도메인
 ┃ ┃   ┗ 📂wishlist        # 전역 에러 처리, JWT 설정 등
 ┃ ┃   
 ┃ ┣ 📂resources
 ┃ ┃ ┗ 📜application.yml   # 환경 설정
 ┣ 📂test
 ┃ ┣ 📂...                 # 각 도메인 테스트 코드


📘 기능 명세

기능 분류 기능 설명
회원 기능 회원가입, 로그인, 로그아웃, 내 정보 조회/수정, 비밀번호 변경, 탈퇴
인증/인가 JWT 기반 로그인 및 Access/Refresh Token 발급/재발급
공간 기능 공간 등록, 공간 검색 (필터, 키워드, 거리), 예약 가능 시간 조회
예약 기능 예약 신청/조회/수락/거절, 게스트/호스트 예약 내역
리뷰 기능 리뷰 등록, 수정, 삭제, 리뷰 가능 여부 확인
댓글 기능 리뷰 댓글 등록, 수정, 삭제, 리뷰 댓글 가능 여부 확인
좋아요 기능 공간 찜하기 등록/해제
CORS 처리 쿠키 + SameSite=None, 프론트 도메인 설정, HTTPS 적용
기타 Swagger 문서, 에러 메시지 포맷 통일 등


🛢 ERD



🔐 JWT 인증 흐름

  • 로그인 시 AccessToken (헤더), RefreshToken (쿠키) 발급
  • AccessToken 만료 시 /api/token/reissue 로 재발급 요청
  • RefreshToken 은 DB에 저장되고, 쿠키에 다음과 같이 설정됨:
    • HttpOnly, Secure, SameSite=None
  • 인증이 필요 없는 API 요청은 JWT 필터에서 예외 없이 통과
  • 인증 필터와 로그인 필터는 분리되어 구성


❗ 에러 처리 정책

  • @ControllerAdvice 를 이용한 전역 예외 처리 적용
  • 커스텀 예외 및 에러 코드 Enum 사용 (예: UserErrorCode, AuthErrorCode)
  • 일관된 JSON 에러 응답 포맷:
{
    "status": 400,
    "errorCode": "USER_NOT_FOUND",
    "message": "존재하지 않는 사용자입니다."
}


📘 API 명세서



🚀 배포 전략

beour 프로젝트는 백엔드와 프론트엔드가 별도의 레포지토리 및 배포 환경을 가지고 있으며, 각기 최적화된 인프라와 자동화 파이프라인을 통해 효율적이고 안정적인 서비스 배포를 구현하고 있습니다.

beour drawio

  1. 백엔드 배포 전략

    • 인프라: AWS EC2 인스턴스에 Docker 컨테이너로 Spring Boot 애플리케이션과 MySQL 데이터베이스를 배포하여, 환경 일관성과 관리 편의성을 확보했습니다.
    • 웹서버: Nginx를 리버스 프록시로 설정하여 트래픽을 백엔드 애플리케이션에 전달하며, 보안 및 성능 최적화를 도모했습니다.
    • CI/CD: GitHub Actions 워크플로우를 통해 Main으로 PUSH 시 자동으로 빌드, 테스트, Docker 이미지 생성 및 EC2에 배포까지 이어지는 완전 자동화 파이프라인을 구축했습니다.
    • 협업 알림: Discord 웹훅을 활용해 Pull Request, Discussions 등 주요 GitHub 이벤트를 팀원에게 실시간으로 공유함으로써 신속한 피드백과 소통을 지원했습니다.

  2. 프론트엔드 배포 전략

    • 인프라: AWS S3를 정적 웹 호스팅용 스토리지로 사용하고, CloudFront CDN을 통해 전 세계에 빠른 콘텐츠 전송을 지원했습니다.
    • 도메인 관리: Route53을 통해 도메인 네임 시스템(DNS)을 관리하며, 사용자 접근성을 높였습니다.
    • CI/CD: GitHub Actions를 사용하여 프론트엔드 코드가 main 브랜치에 병합될 때마다 자동으로 빌드 및 S3 배포가 진행되도록 설정해 배포 효율성을 극대화했습니다.
    • 협업 알림: Discord 웹훅을 활용해 Pull Request 등 주요 GitHub 이벤트를 팀원에게 실시간으로 공유함으로써 신속한 피드백과 소통을 지원했습니다.


📂 브랜치 전략



📝 커밋 컨벤션



🛠 코드 컨벤션

  • 기본적으로 Google Java Style Guide를 따릅니다.
  • 단, 탭 사이즈는 2에서 4로 변경하여 사용합니다.


📄 기타 문서 (추가 예정)

  • CORS, 쿠키 설정 등 트러블슈팅 문서 추가 예정

Clone this wiki locally