[Spring] Server response normalization

필자는 비즈니스 서비스 운영 시, 유지보수에서 제일 중요한건 "정형화" 라고 생각한다.

 

가끔 오래된 프로젝트나 앱들을 살펴보면, 난잡한 API Endpoint들과 뒤죽박죽인 response가 보인다.

 

어떤 요청의 response는 ok: true,

또 다른 요청은 success: true,

status: "OK" 등등이 섞여있는 경우가 있었다.

 

응답의 정형화는 시스템의 맨 바닥 기반이다.

 

응답이 정형화되지 않은 서비스는 그 크기가 늘어날수록 유지보수에 어려움을 겪게 될 것이다.

 

필자의 경우, 응답의 정형화를 아래와 같이 구성했다.

 

- code (required)

- message (required)

- data (optional)

 

HTTP status가 있는데, 어째서 code를 별도로 전송하게 되었는가?

 

물론 HTTP는 status 자체에 의미를 내포하고 있다.

 

400 Bad request,

401 Unauthorized,

403 Forbidden

과 같이 말이다.

 

근데 만일, 회원가입시 닉네임 중복 또는 휴대폰 번호 중복의 경우를 생각해보자.

 

400 Bad request와 함께 body에 message를 담아 보내면, 클라이언트에서는 물론 효과적으로 처리가 가능하다.

 

근데 로깅, 디버깅 차원에서는 다른 얘기다.

 

로그에 HTTP status와 error message만을 저장하는 경우, 해당 로그는 효과적으로 검색되지 않는다.

 

code를 ERR_DUPLIATED_EMAIL 과 같이, 함께 저장하는 경우엔 필터링과 집계가 훨씬 쉬워진다.

 

HTTP Status만으로는 표현할 수 있는 정보의 디테일이 부족하기 때문이다.

 

응답을 정형화 했을 시의 장점은 한가지 더 있다.

공통된 형식의 response가 돌아오므로, interceptor에서 에러 로깅과 시각화 등의 action을 통합해서 사용 가능하다.

 

 

여담으로, 클라이언트 측에서 오류 메시지를 시각화하는 것은 최소화 해야 한다고 생각한다.

 

서버와의 통신이 불가한 경우만 오류 메시지를 클라이언트 단에서 표현해야 한다.