[REFACTOR] 공통 API 오류 응답 코드 체계를 도입

[GiJungPark]

Related Issue

• refactor/[REFACTOR] 공통 API 오류 응답 코드 체계 도입 #594 -> dev
• Closes [REFACTOR] 공통 API 오류 응답 코드 체계 도입 #594

Key Changes

• DTO Bean Validation 실패와 JSON 파싱 실패를 각각 COMMON-001, COMMON-002로 분리하고 기존 검증 메시지·HTTP 상태·도메인 오류 계약을 유지했습니다. (5d278588)
• PathVariable·RequestParam 검증·누락·타입 변환, multipart·헤더 누락, 업로드 용량, 404·405·406·415, 일반 인가, DB 무결성 fallback에 COMMON-003~014를 부여했습니다. 예상하지 못한 예외는 내부 내용을 노출하지 않는 COMMON-999로 응답합니다. (7af902c3)
• 처리되지 않은 MVC 예외가 ERROR 디스패치에서 401 AUTH-001로 바뀌지 않도록 명시적인 예외 매핑과 catch-all을 추가했습니다. AccessDeniedException은 Security로 다시 전달해 기존 401/403 판단을 보존하고, 일반 403은 COMMON-012 본문을 반환합니다. (7af902c3)
• 실제 Security 필터 체인을 통과하는 요청 테스트로 400·403·404·405·406·415·500, BlockController 메서드 검증, 기존 AUTH-*와 도메인 오류 회귀를 검증했습니다. REST Docs named example도 새 공통 코드로 갱신했습니다. (7af902c3)
• 공통 오류 코드의 명명·분류·보안·문서화 기준과 기존 코드 영역 표기의 호환성 원칙을 문서화했습니다. (7c85e7ff, 8b3c1953)

To Reviewers

• 기존 BAD_REQUEST·CONFLICT 문자열을 ErrorResult.code로 사용하는 소스 경로는 제거했습니다. 클라이언트가 해당 문자열로 분기했다면 COMMON-* 전환이 필요합니다.
• HTTP 상태는 유지했습니다. 업로드 용량 초과도 기존과 동일하게 400이며 설정값은 변경하지 않았습니다.
• SecurityConfig와 /error 인가 정책은 변경하지 않았습니다. 인증 토큰 오류는 기존 AUTH-*, 도메인 인가 오류는 기존 도메인 코드를 유지합니다.
• COMMON-999는 고정 메시지만 응답하고 원본 예외·SQL·스택 트레이스는 로그에만 남깁니다.
• 변경 규모는 크지만 전역 예외 handler, 공통 enum, Security writer와 예외별 반복 테스트가 하나의 응답 계약으로 결합되어 있어 하나의 PR로 유지했습니다.
• ./gradlew build -x test, 관련 테스트, ./gradlew clean apiDocs는 성공했습니다. 전체 ./gradlew test는 761개 중 12개가 실패하며, 변경 전 사본에서도 동일하게 재현된 로컬 MySQL 시드·Redis 상태 관련 기존 환경 실패입니다.
• DB 스키마·DDL·배포 설정 영향은 없습니다.

References

• Follow-up to [FEAT] 컬렉션 생성·수정·삭제 기능 구현 #560
• Related to [TEST] API 문서 테스트 공통 기반 구축 #585

[ljy1348]

p2 현재 코드는 다음처럼 예외에서 상태와 본문만 새로 만듭니다.

HttpRequestMethodNotSupportedException에는 Spring이 지원 가능한 HTTP 메서드를 e.getHeaders()의 Allow 헤더로 담아 둡니다. 하지만 현재 errorResponse()는 이 헤더를 전달받지 않으므로 버려집니다.

405 응답은 HTTP 규격상 Allow 헤더를 반드시 포함해야 합니다. 따라서 단순 부가정보 누락이 아니라 HTTP 계약 위반입니다.

권장 수정:

return errorResponse(METHOD_NOT_SUPPORTED, e.getHeaders());
그리고 errorResponse()에 헤더를 받는 오버로드를 추가해야 합니다.

private ResponseEntity errorResponse(
ICustomError error,
HttpHeaders headers
) {
return ResponseEntity
.status(error.getStatusCode())
.headers(headers)
.contentType(APPLICATION_JSON)
.body(new ErrorResult(error.getCode(), error.getDescription()));
}