ID: key_26_22_05_25_사전_P3 Created date: 5월 25 2026 월요일
연관 문서
개발 일정 > 사전 준비 서버 개발 | 서버 (befw-app-server)
개요
전 API에 적용될 응답 포맷 및 에러 코드 체계를 확정한다. 확정 전에는 서버 API 개발을 시작하지 않는다.
표준 응답 구조 (안)
// 성공
{
"success": true,
"data": { ... },
"meta": {
"page": 1,
"size": 20,
"total": 150
}
}
// 실패
{
"success": false,
"error": {
"code": "ISSUE_NOT_FOUND",
"message": "요청한 이슈를 찾을 수 없습니다.",
"details": []
}
}에러 코드 체계 (안)
| 코드 접두사 | 영역 | 예시 |
|---|---|---|
AUTH_ | 인증/인가 | AUTH_TOKEN_EXPIRED |
USER_ | 사용자 | USER_NOT_FOUND |
PROJECT_ | 프로젝트 | PROJECT_PERMISSION_DENIED |
ISSUE_ | 이슈 | ISSUE_INVALID_TRANSITION |
COMMON_ | 공통 | COMMON_VALIDATION_FAILED |
Claude Code 작업 수행서
목표
공통 응답 포맷 클래스 및 에러 코드 Enum을 구현하고 전역 예외 핸들러를 설정한다.
작업 지시
CIRA 서버의 API 공통 응답 포맷 및 예외 처리 구조를 구현해줘.
[프로젝트 경로]
- C:\workspace\tsh\boilerplate\be\befw\dd\cira
[수행 작업]
1. 공통 응답 래퍼 클래스 생성
경로: src/main/java/.../common/response/
- ApiResponse<T> (제네릭 래퍼)
- PageResponse<T> (페이지네이션 메타 포함)
- befw-lib-core에 이미 존재하면 상속/재활용
2. 에러 코드 Enum 생성
경로: src/main/java/.../common/exception/ErrorCode.java
- HTTP 상태코드와 에러 코드 문자열 매핑
- 카테고리: AUTH_, USER_, PROJECT_, ISSUE_, SPRINT_, BOARD_, COMMON_
- 각 코드에 defaultMessage 포함
3. 커스텀 예외 클래스 생성
- CiraException extends RuntimeException
- 필드: ErrorCode errorCode, Object[] args
4. 전역 예외 핸들러 생성
경로: src/main/java/.../common/exception/GlobalExceptionHandler.java
- @RestControllerAdvice
- CiraException 처리
- MethodArgumentNotValidException (Bean Validation)
- Exception (미처리 예외 — 500)
5. 사용 예시 단위 테스트 1건 작성
- 존재하지 않는 리소스 조회 시 404 + ISSUE_NOT_FOUND 응답 검증
[준수 사항]
- befw-lib-core 응답 포맷이 이미 존재하면 확장(상속)하여 CIRA 전용 에러코드 추가
- 모든 에러코드는 CLAUDE.md "Error Code" 섹션에 테이블로 문서화
완료 기준
| 항목 | 기준 |
|---|---|
| ApiResponse 클래스 | 컴파일 정상 |
| ErrorCode Enum | AUTH~COMMON 카테고리 전체 정의 |
| GlobalExceptionHandler | 단위 테스트 통과 |
| CLAUDE.md 반영 | 에러코드 테이블 작성 완료 |
선행 조건
후행 작업
- 1-2_서버-Auth-API — 에러코드 활용
- 1-3_서버-이슈-CRUD-API