0. 시작하며
IT 회사가 있는 조직이라면 보통 개발 프로세스에 컨벤션이 존재해서, 일부 문서들은 작성하는 것이 필수로 정해져있다.
예를 들어 백엔드 / 프론트엔드가 나뉘어 있는 조직이라면 직군 간 소통을 위해 API 문서를 필수로 작성하게 된다.
하지만 규모가 작은 조직에서는 이런 부분이 미흡할 수 있다.
스타트업 초기에는 빠른 성장이 우선이다 보니, 문서화나 컨벤션 정립은 후순위로 밀릴 수 있다.
따라서 이 문제도 성장을 위한 일종의 부채라고 볼 수 있다.
이번에 새로운 프로젝트를 진행하면서, 새롭게 구현하는 API들부터 컨벤션을 적용해보자고 마음 먹게 되었다.
1. 요구 사항
당시의 요구 사항은 아래와 같았다.
1. 프론트 / 백엔드로 역할을 구분해서 구현
2. 각 에러를 구분하여, 이해하기 쉬운 에러 메시지를 보여줘야 함2.1. API 문서
프론트 / 백엔드로 역할을 구분해서 구현
당시 조직은 풀스택 개발자들 위주로 구성되어 있었지만, 프론트엔드 / 백엔드 중에서 지향하는 스택은 서로 다른 상태였다.
새로운 프로젝트를 하는 김에 피쳐 단위로 태스크를 나누기 보다는, 각자 원하는 스택으로 역할을 나눠서 구현하기로 했다.
이렇게 역할을 나누기 위해서는 API 문서가 필수였다.
API 스펙을 정의한 API 문서가 각 직군 사이의 소통 단위가 되어서, 추가적인 소통 없이 문서 공유 만으로 처리가 가능하길 원했다.
swagger 등의 문서화 도구를 사용하는 것도 좋은 선택이겠지만, 당장 어떤 도구를 도입하기 위해서는 팀 내 논의를 먼저 거쳐야만 했다.
빠르게 시험적으로 도입해보기 위해, 일단은 노션에 API 문서를 작성하기로 결정했다.
먼저 노션의 데이터베이스 기능을 이용해서 한 눈에 API 문서들을 볼 수 있게 테이블을 만들었다.
url, http method, 간단한 설명, 타입(태그)를 간단하게 확인할 수 있게 구성했다.
'Name' 칼럼에 있는 각 페이지를 클릭하면 각 API의 문서를 확인할 수 있다.
API 문서의 상단에는 테이블에 입력한 값들이 확인된다.
내부 내용으로 해당 API의 상세 설명과 request body 또는 query parameter에 삽입될 값이 입력된다.
그 밑에는 각 http 응답에 대한 response body의 형식을 작성해두었다.
정상 응답과 에러 응답의 예시를 넣어서 해당 API를 통해 받을 수 있는 응답이 모두 담겨있도록 했다.
2.2. 에러 코드 정리 문서
각 에러를 구분하여, 이해하기 쉬운 에러 메시지를 보여줘야 함
해당 프로젝트에서는 사용자가 유효하지 않은 주소를 입력하는 등의 상황에서, 각 에러 상황을 구분해서 친절한 에러 메시지를 보여주어야 했다.
기존에는 에러 응답에 직접 에러 메시지를 담아서 보내거나, 10, 11, 12... 와 같은 숫자를 에러 코드로 응답하는 방식을 사용했다.
하지만 이렇게 할 경우 서버 단에서 UI에서 보여줄 에러 메시지를 제한해버리거나, 에러 코드 만으로는 도메인을 식별할 수 없어서 어디에서 에러가 발생했는지 디버깅을 하는데 어려움을 겪었다.
직군 간 원할한 소통과 서버 단의 로깅/디버깅의 편의성을 위해서는, 적절히 에러 코드를 정의하고 각 에러 종류를 한 눈에 파악할 수 있는 문서가 필요했다.
우선 에러 코드의 경우 각 도메인을 구분할 수 있는 약어를 접두사로 붙였다.
그리고 각 에러를 대분류/소분류로 나누어서 뒤에 숫자 코드를 붙였다.
각 에러 코드에 대한 정리 문서는 노션에 작성했다.
API 문서 작성과 마찬가지로 노션의 데이터베이스 기능을 이용해서 작성했다.
각 에러 코드와 이름, 간단한 설명을 한눈에 확인할 수 있다.
태그를 이용해서 각 에러를 구분하고, 비고에는 어떤 요청에서 해당 에러가 발생하는지를 작성한다.
해당 문서만 있어도 프론트엔드 단에서는 에러 코드에 대한 식별이 가능했고, 프론트 단에서 적절한 에러메시지와 코드를 상수로 매핑해두어서 UI로 보여주었다.
