Custom Error Code, 에러 코드 문서화

Custom Error Code

Custom Error Code : 단순히 HTTP Status 코드만으로는 서비스에서 발생하는 에러의 구체적인 원인을 식별하기 어렵기 때문에, 서비스 상황에 맞춰 별도의 식별 코드를 부여한 것을 의미한다.

 

프로젝트 회의에서 에러 처리 방식을 논의하던 중, 기존 처럼 HTTP Status만 사용하는 방식도 동작에는 문제가 없지만 프론트엔드 입장에서는 어떤 에러인지 명확히 알기 어렵다는 이야기가 나왔다. 이를 계기로 커스텀 에러 코드를 도입하게 된 과정을 정리해본다.

 

에러 처리 과정에서, 프론트에게 400 Bad Request 하나만 떨어지면 "사용자가 잘못 요청했구나" 정도만 알 수 있다. 이게 이메일 중복인지, 비밀번호 형식 오류인지, 혹은 다른 입력값 문제인지는 알 수 없다.

 

그동안은 간단한 수준의 에러 처리만 했지만, 서비스 런칭을 목표로 개발을 진행하다 보니 복잡한 비즈니스 로직과 세부적인 에러 처리가 필요하다고 판단하여 회의 안건으로 올리게 되었다.

 

팀 내 현직자 분께서 도메인 단위 Prefix + 커스텀 코드를 붙이는 방식(Ex. USR1001, USR2001 등)을 제안해주셨다. 이렇게 하면 “아, 이건 사용자(로그인 또는 회원가입) 로직에서 발생한 에러구나” 하고 바로 인식할 수 있다.  

 

아래는 현재 프로젝트에서 사용중인 Custom Error Code 일부분이다.

 

에러 코드 문서화

도입 후 가장 먼저 한 일은 에러 코드를 정리해 문서화하는 것이었다. 빠르게 공유하기 위해 기존에 프로젝트 일정과 회의록을 관리하던 노션(Notion)에 정리했다.  

 

문서에는 다음과 같은 내용을 포함했다.  

- 도메인별 Prefix 지정

-  HTTP Status / 에러 코드 / 메시지

프론트 측에서 해당 문서만 보면 되어서 협업이 훨씬 수월해졌다. 조금 불편했던 점은 노션은 백엔드 코드와 동기화되지 않는다는 점? 코드가 추가될 때 문서를 따로 수정해야 해서 실수로 누락되는 경우도 있었다.

 

Rest Docs로 전환

다음 단계로 Spring Rest Docs를 도입할 계획이다. 테스트 코드 기반으로 자동 문서화가 가능하므로, 에러 코드도 API 문서와 함께 자동으로 최신화할 수 있는 장점이 있다. 

 

Rest Docs를 위해서는  Custom .snippet 파일과 응답값 형식에 맞는 Descriptor 구현, 그리고 Custom .snippet 파일과 Descriptor들을 지정할 Custom Response 클래스 등이 필요하다. 또한, 이렇게 만들어진 문서화 기능이 제대로 동작하는지 검증하기 위해 Test 코드까지 작성해야 한다. 이 과정을 거치면 에러 코드와 API 문서가 항상 최신 상태로 유지될 수 있다.