bio_backend/README.md

Bio Backend

기술 스택

• Framework: Spring Boot
• Database: PostgreSQL
• ORM: Spring Data JPA + QueryDSL
• Security: Spring Security + JWT
• Build Tool: Gradle
• Container: Docker + Kubernetes
• API Documentation: Swagger (SpringDoc OpenAPI)

개발 가이드

1. 프로젝트 구조

src/main/java/com/bio/bio_backend/
├── domain/                    # 도메인별 패키지
│   └── user/
│       └── member/           # 회원 도메인
│           ├── controller/    # API 엔드포인트
│           ├── service/       # 비즈니스 로직
│           ├── repository/    # 데이터 접근
│           ├── entity/        # JPA 엔티티
│           └── dto/          # 데이터 전송 객체
├── global/                    # 공통 설정
│   ├── config/               # 설정 클래스
│   ├── security/             # 보안 설정
│   ├── exception/            # 예외 처리
│   └── utils/                # 유틸리티
└── BioBackendApplication.java

2. API 문서화 (Swagger)

Swagger UI 접속

• URL: http://localhost:8080/service/swagger-ui.html
• API Docs: http://localhost:8080/service/api-docs

주요 어노테이션

@Tag(name = "Member", description = "회원 관리 API")
@Operation(summary = "회원 가입", description = "새로운 회원을 등록합니다.")
@ApiResponses(value = {
    @ApiResponse(responseCode = "201", description = "회원 가입 성공"),
    @ApiResponse(responseCode = "400", description = "잘못된 요청 데이터")
})

설정 파일

• SwaggerConfig.java: OpenAPI 기본 정보 설정
• application.properties: Swagger UI 커스터마이징

3. 트랜잭션 관리

기본 설정

@Service
@Transactional(readOnly = true)  // 클래스 레벨: 읽기 전용 기본값
public class MemberServiceImpl {

    // 읽기 전용 메서드 (별도 어노테이션 불필요)
    public MemberDto selectMember(long seq) { ... }

    // 쓰기 작업 메서드 (개별 @Transactional 적용)
    @Transactional
    public MemberDto createMember(MemberDto dto) { ... }
}

핵심 규칙

• 클래스 레벨: @Transactional(readOnly = true) 기본 설정
• 메서드별: 데이터 수정 시에만 @Transactional 개별 적용
• 설정: spring.jpa.open-in-view=false (성능 최적화)

4. 오류 등록 및 사용

오류 코드 등록

// ApiResponseCode.java
public enum ApiResponseCode {
    USER_ID_DUPLICATE("400", "이미 존재하는 사용자 ID입니다."),
}

오류 사용 방법

// Service에서 예외 발생
throw new ApiException(ApiResponseCode.USER_ID_DUPLICATE);

// Controller에서 예외 처리 (자동)
// GlobalExceptionHandler가 ApiException을 잡아서 응답 변환

핵심 규칙

• 오류 코드: ApiResponseCode enum에 모든 오류 정의
• 예외 클래스: ApiException으로 비즈니스 로직 예외 처리
• 자동 처리: GlobalExceptionHandler가 일관된 응답 형태로 변환