Files

sohot8653 4fac74b6a5 [회원 목록 조회 기능 개선] 회원 목록 조회 API에 페이지네이션 기능을 추가하고, 검색 조건을 위한 DTO 및 관련 메서드를 구현하여 효율적인 데이터 조회를 지원. README.md에 DTO 네이밍 규칙을 추가하여 코드 일관성을 강화.

2025-09-03 10:19:08 +09:00

12 KiB

Raw Blame History

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/                    # 도메인별 패키지
│   └── base/                 # 기본 도메인
│       └── member/           # 회원 도메인
│           ├── controller/    # API 엔드포인트
│           ├── service/       # 비즈니스 로직
│           ├── repository/    # 데이터 접근
│           ├── entity/        # JPA 엔티티
│           ├── dto/          # 데이터 전송 객체
│           ├── mapper/       # MapStruct 매퍼
│           └── enums/        # 도메인 열거형
├── global/                    # 공통 설정
│   ├── config/               # 설정 클래스
│   ├── security/             # 보안 설정
│   ├── exception/            # 예외 처리
│   ├── aop/                  # AOP 로깅
│   ├── filter/               # HTTP 로깅 필터
│   ├── utils/                # 유틸리티
│   ├── constants/            # 상수 정의
│   ├── dto/                  # 공통 DTO
│   ├── entity/               # 공통 엔티티
│   └── annotation/           # 커스텀 어노테이션
├── BioBackendApplication.java
└── ServletInitializer.java

2. API 응답 표준화 (ApiResponseDto)

응답 구조

모든 API 응답은 ApiResponseDto<T> 형태로 표준화되어 있습니다.

public class ApiResponseDto<T> {
    private boolean success;    // 성공/실패 여부 (true/false)
    private int code;           // HTTP 상태 코드
    private String message;     // 응답 메시지 (ApiResponseCode enum 값)
    private String description; // 응답 설명
    private T data;            // 실제 데이터 (제네릭 타입)
}

응답 예시

성공 응답 (201 Created)

{
  "success": true,
  "code": 201,
  "message": "COMMON_SUCCESS_CREATED",
  "description": "Created successfully",
  "data": {
    "seq": 1,
    "userId": "user123",
    "name": "홍길동"
  }
}

실패 응답 (409 Conflict)

{
  "success": false,
  "code": 409,
  "message": "USER_ID_DUPLICATE",
  "description": "User ID already exists"
}

사용 방법

Controller에서 응답 생성

@PostMapping("/members")
public ResponseEntity<ApiResponseDto<CreateMemberResponseDto>> createMember(@RequestBody CreateMemberRequestDto requestDto) {
    // ... 비즈니스 로직 ...

    // 성공 응답
    ApiResponseDto<CreateMemberResponseDto> apiResponse =
        ApiResponseDto.success(ApiResponseCode.COMMON_SUCCESS_CREATED, responseDto);

    return ResponseEntity.status(HttpStatus.CREATED).body(apiResponse);
}

공용 응답 코드 사용

// ApiResponseCode.java
public enum ApiResponseCode {
    // 공용 성공 코드
    COMMON_SUCCESS(HttpStatus.OK.value(), "요청 성공"),
    COMMON_SUCCESS_CREATED(HttpStatus.CREATED.value(), "성공적으로 생성되었습니다"),
    COMMON_SUCCESS_UPDATED(HttpStatus.OK.value(), "성공적으로 수정되었습니다"),
    COMMON_SUCCESS_DELETED(HttpStatus.OK.value(), "성공적으로 삭제되었습니다"),
    COMMON_SUCCESS_RETRIEVED(HttpStatus.OK.value(), "성공적으로 조회되었습니다"),

    // 공용 오류 코드
    COMMON_BAD_REQUEST(HttpStatus.BAD_REQUEST.value(), "필수 요청 본문이 누락되었거나 오류가 발생했습니다"),
    COMMON_UNAUTHORIZED(HttpStatus.UNAUTHORIZED.value(), "인증에 실패했습니다"),
    COMMON_FORBIDDEN(HttpStatus.FORBIDDEN.value(), "접근이 거부되었습니다"),
    COMMON_NOT_FOUND(HttpStatus.NOT_FOUND.value(), "리소스를 찾을 수 없습니다"),
    COMMON_CONFLICT(HttpStatus.CONFLICT.value(), "충돌이 발생했습니다"),
    COMMON_INTERNAL_SERVER_ERROR(HttpStatus.INTERNAL_SERVER_ERROR.value(), "서버에서 오류가 발생했습니다"),

    // 사용자 관련 코드
    USER_ID_DUPLICATE(HttpStatus.CONFLICT.value(), "이미 존재하는 사용자 ID입니다"),
    USER_NOT_FOUND(HttpStatus.UNAUTHORIZED.value(), "사용자를 찾을 수 없습니다. 인증에 실패했습니다"),
    USER_PASSWORD_INVALID(HttpStatus.UNAUTHORIZED.value(), "비밀번호가 올바르지 않습니다")
}

핵심 규칙

모든 API 응답: ApiResponseDto<T>로 감싸서 반환
공용 응답 코드: COMMON_ 접두사로 시작하는 범용 코드 사용
일관된 구조: success, code, message, description, data 필드로 표준화
성공/실패 구분: success 필드로 명확한 성공/실패 여부 전달
제네릭 활용: <T>를 통해 다양한 데이터 타입 지원

3. JWT 인증 시스템

토큰 구성

Access Token: 15분 (900,000ms) - API 요청 시 사용
Refresh Token: 7일 (604,800,000ms) - 쿠키에 저장, 자동 갱신

자동 토큰 갱신

모든 API 요청마다 자동으로 처리됩니다:

Access Token 유효: 정상 요청 처리
Access Token 만료: Refresh Token으로 자동 갱신
새 Access Token 발급: 응답 헤더에 자동 설정
Refresh Token 갱신: 보안을 위해 매번 새로운 토큰 발급

주요 컴포넌트

JwtTokenIssuanceFilter: 로그인 시 토큰 발급
JwtTokenValidationFilter: 요청마다 토큰 검증 및 갱신
JwtUtils: 토큰 생성, 검증, 갱신 유틸리티

4. API 문서화 (Swagger)

Swagger UI 접속

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

5. 시스템 모니터링 (Actuator)

Health 체크

기본 Health: http://localhost:8080/service/actuator/health
Readiness Probe: http://localhost:8080/service/actuator/health/readiness
Liveness Probe: http://localhost:8080/service/actuator/health/liveness

시스템 정보

애플리케이션 정보: http://localhost:8080/service/actuator/info
환경 설정: http://localhost:8080/service/actuator/env
설정 속성: http://localhost:8080/service/actuator/configprops
메트릭: http://localhost:8080/service/actuator/metrics

주요 어노테이션

@Tag(name = "Member", description = "회원 관리 API")
@Operation(summary = "회원 가입", description = "새로운 회원을 등록합니다.")
@ApiResponses(value = {
    @ApiResponse(responseCode = "201", description = "회원 가입 성공"),
    @ApiResponse(responseCode = "400", description = "잘못된 요청 데이터",
                content = @Content(schema = @Schema(implementation = ApiResponseDto.class))),
    @ApiResponse(responseCode = "409", description = "중복된 사용자 정보",
                content = @Content(schema = @Schema(implementation = ApiResponseDto.class)))
})

설정 파일

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

6. 트랜잭션 관리

기본 설정

@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 (성능 최적화)

7. 오류 등록 및 사용

오류 코드 등록

// ApiResponseCode.java
public enum ApiResponseCode {
    USER_ID_DUPLICATE(HttpStatus.CONFLICT.value(), "User ID already exists"),
}

오류 사용 방법

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

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

핵심 규칙

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

8. 로깅 시스템

@LogExecution 어노테이션 사용법

메서드 실행 로깅을 위한 필수 어노테이션입니다.

기본 사용법

@LogExecution("회원 등록")
@PostMapping("/register")
public ResponseEntity<ApiResponseDto<CreateMemberResponseDto>> createMember(@RequestBody CreateMemberRequestDto requestDto) {
    // 메서드 실행 시 자동으로 로그 출력
}

로그 출력 예시

메서드 시작 시:

[START] 회원 등록 | 호출경로: MemberController.createMember | 사용자: 고명빈(kmbin92)

메서드 성공 시:

[SUCCESS] 회원 등록 | 호출경로: MemberController.createMember | 사용자: 고명빈(kmbin92) | 시간: 200ms

메서드 실패 시:

[FAILED] 회원 등록 | 호출경로: MemberController.createMember | 사용자: 고명빈(kmbin92) | 시간: 23ms | 오류: 이미 존재하는 사용자 ID입니다

어노테이션 설정

@LogExecution("사용자 정보 조회")
public UserDto getUserInfo() { }

@LogExecution("주문 처리")
public OrderDto processOrder() { }

로깅 시스템 구성

MethodExecutionLoggingAspect: 메서드 실행 로깅 (AOP)
HttpLoggingFilter: HTTP 요청/응답 로깅 (필터)
logback-spring.xml: 로그 파일 관리 및 설정

중요: @LogExecution 어노테이션이 없으면 메서드 실행 로그가 출력되지 않습니다

9. MapStruct

매퍼 인터페이스

@Mapper(componentModel = "spring")
public interface MemberMapper {
    MemberDto toDto(Member member);
    Member toEntity(MemberDto dto);
}

사용 예시

// Entity → DTO
MemberDto dto = memberMapper.toDto(member);

// DTO → Entity
Member entity = memberMapper.toEntity(dto);

자동 생성: 컴파일 시 MemberMapperImpl 구현체 생성

10. BaseEntity 상속

모든 엔티티는 BaseEntity 상속을 원칙으로 합니다.

자동 생성 필드

OID: @PrePersist에서 자동 생성 (고유 식별자)
생성일시: @CreatedDate로 자동 설정
수정일시: @LastModifiedDate로 자동 갱신
생성자/수정자 OID: 사용자 추적용

사용 예시

@Entity
@Table(name = "st_members")
public class Member extends BaseEntity {
    // OID, 생성일시, 수정일시 등이 자동으로 관리됨
    private String userId;
    private String name;
}

11. DTO 네이밍 규칙

기본 원칙

API 계층: Dto 접미사 유지
Service 계층: 역할에 따라 Dto 접미사 결정

사용 예시

// API 계층 (Dto 유지)
CreateMemberRequestDto, GetMemberResponseDto

// Service 계층 - 비즈니스 핵심 (Dto 유지)
MemberDto

// Service 계층 - 내부 전달 (Dto 제거)
MemberSearchCondition

핵심 규칙

API 노출: Dto 유지
비즈니스 핵심: Dto 유지
내부 전달: Dto 제거

12. 데이터베이스 스키마

데이터베이스 테이블 구조는 ddl/schema_entity.sql에 정의되어 있습니다.

스키마 파일

위치: ddl/schema_entity.sql
내용: 모든 엔티티 테이블의 CREATE TABLE DDL 스크립트

초기화 스크립트

위치: src/main/resources/schema_initial.sql
내용: 서버 부팅 시 자동 실행되는 초기화 스크립트 (예: shedlock 테이블 등)

사용 방법

자동 생성: 애플리케이션 시작 시 schema_entity.sql로 엔티티 테이블 자동 생성
초기화: 서버 부팅 시 schema_initial.sql로 시스템 테이블 자동 생성
설정: spring.jpa.hibernate.ddl-auto=none으로 Hibernate 자동 스키마 생성 비활성화

12 KiB Raw Blame History

Bio Backend

기술 스택

개발 가이드

1. 프로젝트 구조

2. API 응답 표준화 (ApiResponseDto)

응답 구조

응답 예시

사용 방법

핵심 규칙

3. JWT 인증 시스템

토큰 구성

자동 토큰 갱신

주요 컴포넌트

4. API 문서화 (Swagger)

Swagger UI 접속

5. 시스템 모니터링 (Actuator)

Health 체크

시스템 정보

주요 어노테이션

설정 파일

6. 트랜잭션 관리

기본 설정

핵심 규칙

7. 오류 등록 및 사용

오류 코드 등록

오류 사용 방법

핵심 규칙

8. 로깅 시스템

@LogExecution 어노테이션 사용법

기본 사용법

로그 출력 예시

어노테이션 설정

로깅 시스템 구성

9. MapStruct

10. BaseEntity 상속

자동 생성 필드

사용 예시

11. DTO 네이밍 규칙

기본 원칙

사용 예시

핵심 규칙

12. 데이터베이스 스키마

스키마 파일

초기화 스크립트

사용 방법

12 KiB

Raw Blame History