refactor: 에러 코드와 메시지 표기 체계 통일(#118) - #119
Merged
Merged
Conversation
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LMAsC5aH8Te4dGjAH2kZYr
정수 코드를 {도메인 접두사}-{순번} 문자열로 바꾸고 메시지 어투를 -요체로
통일했다. 코드 값만 보고 어느 도메인의 오류인지 알 수 있게 해 프론트엔드와의
대조 비용을 없앤다.
접두사는 GLB, AUTH, MEM, CRS, CART, REG, ADM이고 순번은 그룹별 001부터
재부여했다. 장바구니와 수강신청 양쪽에서 던지던 시간표 충돌과 과목 유형 제한은
과목 검증이므로 CRS로 옮겼다.
ErrorResponse.code가 int에서 String이 되는 응답 계약 변경이라 프론트엔드 배포와
순서를 맞춰야 한다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LMAsC5aH8Te4dGjAH2kZYr
파라미터 3개가 한 줄에 몰려 있던 AsyncExceptionHandler를 컨벤션대로 줄바꿈했다. main 전체를 훑어 이 형식을 어긴 곳은 여기 하나였다. 코드를 그대로 옮겨 적은 설명 주석을 지웠다. ExceptionCode와 enum 상수의 카테고리 구획 주석은 common.md가 명시적 예외로 둔 종류라 남겼다. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LMAsC5aH8Te4dGjAH2kZYr
conc, perf 프로파일의 주석 48줄을 17줄로 줄였다. 지우면 기동 실패, 401, 결함 재현 실패, 지표 0으로 이어지는 것만 남기고 나머지 이유 설명은 뺐다. 설정값은 한 줄도 바뀌지 않았다. fix-concurrency의 conc 템플릿도 같은 기준으로 맞췄다. Phase 2가 파일이 없을 때 이 템플릿으로 생성하므로, 맞추지 않으면 지운 주석이 되살아난다. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LMAsC5aH8Te4dGjAH2kZYr
Test Results301 tests 301 ✅ 4s ⏱️ Results for commit aa2e113. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PR Summary
ExceptionCode의 정수 코드를{도메인 접두사}-{순번}문자열로 바꾸고, 갈려 있던 응답 메시지 어투를 "-요"체로 통일했습니다.ErrorResponse.code가int에서String이 되는 응답 계약 변경이라, 프론트엔드 배포와 순서를 맞춰야 합니다.Problem
문제 1 - 코드 값이 어느 도메인의 오류인지 말해주지 않음
기존 코드는 9999, 1010, 3001 같은 정수였습니다. 값만 봐서는 도메인을 알 수 없어 프론트엔드와 백엔드가 숫자와 의미를 별도 표로 대조해야 했고, 응답 본문만 보이는 상황에서는 그 대조가 매번 선행 작업이 됐습니다.
번호 배치도 규칙을 잃은 상태였습니다. 회원 그룹은 1010, 1012, 1015, 1016으로 세 자리가 비어 있고 전역 그룹만 9999, 8888, 7777이라는 다른 규칙을 썼습니다. 새 코드를 어느 자리에 넣을지가 추가할 때마다 판단 거리였습니다.
문제 2 - 요청 본문 검증 실패에만 HTTP 상태값이 코드로 내려감
@Valid검증이 실패하는 경로만code자리에 리터럴400을 넣고 있었습니다. 다른 응답은 전부ExceptionCode에 정의된 값을 쓰는데 이 경로만 HTTP 상태값을 섞어, 프론트엔드가code로 분기하면 어떤ExceptionCode에도 없는 값을 만나게 됩니다.문제 3 - 응답 메시지 어투가 한 화면에서 섞임
34개 메시지 중 관리자, 표시 학기, 강의 동기화의 9개만 "-요"체였고 나머지 25개는 "-습니다"체였습니다. 같은 화면에서 두 어투가 함께 노출됐습니다.
Solution
해결 1 - 도메인 접두사와 그룹별 순번
접두사는 도메인 패키지 단위로 두되 3-4자로 줄였습니다. 첫 글자 한 자만 따는 안을 먼저 검토했지만, 과목과 장바구니가
C, 액세스 토큰과 관리자가A, 표시 학기와 동기화가S로 아홉 그룹 중 세 쌍이 곧바로 충돌합니다. 충돌을 임의 배정으로 피하는 순간 "코드만 보고 도메인을 안다"는 이 변경의 유일한 이점이 사라지므로 택하지 않았습니다.GLBAUTHMEMCRSCARTREGADM관리자는 계정 인증과 표시 학기, 강의 동기화가 기존에 5000, 5100, 5200으로 나뉘어 있었지만
admin패키지 하나이므로ADM으로 합치고 순번으로만 구분했습니다. 접두사를 패키지가 아니라 기능 단위로 쪼개기 시작하면 어디까지 쪼갤지에 다시 기준이 필요해집니다.순번은 그룹별로
001부터 다시 매겼습니다. 어차피 응답 계약이 깨지는 변경이라 이번에 결번을 물려받지 않는 편이 이득이 큽니다.이 접두사 규칙에서 공유 코드의 자리가 문제가 됩니다. 시간표 충돌과 과목 유형 제한은 장바구니와 수강신청 양쪽에서 던지는데, 기존 그룹핑(3002, 3003)을 그대로 옮기면 수강신청 API가
CART-코드를 내려주게 됩니다. 둘 다 과목 자체에 대한 검증이므로CRS로 옮겨, 응답의 접두사와 호출한 API의 도메인이 어긋나지 않게 했습니다.해결 2 - 검증 실패 응답도 정의된 코드를 사용
code가 문자열이 되면서 리터럴400은 컴파일되지 않습니다. 이 경로의 의미가 정확히 "유효하지 않은 입력 파라미터"이므로 별도 코드를 새로 만들지 않고INVALID_REQUEST_PARAMETER(GLB-003)를 쓰고, 어느 필드가 왜 거절됐는지는 기존대로 메시지에 담았습니다. 코드를 나눠도 프론트엔드가 같은 처리를 하게 되므로 나누지 않았습니다.해결 3 - 메시지 어투를 "-요"체로 통일
이미 그 어투를 쓰고 있던 관리자 쪽에 나머지 25개를 맞췄습니다. 문구가 바뀐 만큼 Swagger의 에러 예시 48개도 함께 고쳤고, 예시의 코드와 메시지가
ExceptionCode의 정의와 한 건도 어긋나지 않는지 대조해 확인했습니다.앞으로 추가되는 코드가 다시 갈리지 않도록 접두사 규칙과 어투, 공유 코드의 배치 기준을 코드 컨벤션과 API 문서 컨벤션에 함께 남겼습니다.
Related Issue