API 명세서를 봤다. 엔드포인트가 열몇 개고 피드백과 쿠폰과 릴 정보와 결제와 로그인과 초대와 공유가 있었다.
result_code (0: FAIL, 1: SUCCESS)
result_data응답 형식이 전부 같았다.
Table of contents
Open Table of contents
껍데기가 같았다
기능이 다 다른데 바깥이 같다.
로그인 result_code, result_data
쿠폰 result_code, result_data
릴 정보 result_code, result_data
결제 result_code, result_data내용물만 result_data 안에서 달라진다. 이것이 왜 좋은지 생각해 봤다.
클라이언트에서 API 를 부르는 코드가 응답을 받아 result_code 를 확인하고 1이면 result_data 를 처리하고 0이면 실패 처리를 한다. API 마다 다른 것이 아니라 한 형태라 공통 함수 하나로 감쌀 수 있다.
각각이 다른 모양이면 부르는 쪽에서 매번 다른 키를 확인해야 한다. json_decode 가 null 을 돌려주는 경우에 json_last_error 로 파싱 실패인지 보는 것도 그 공통부에 한 번만 넣으면 된다. 새 엔드포인트가 생겨도 그 부분을 그대로 쓰고 명세서를 읽는 사람도 result_data 안의 차이만 보면 된다.
실패 사유가 따로였다
로그인 응답에 이런 설명이 붙어 있었다.
(0: FAIL, 1: SUCCESS) 0 일 경우 result_data 에 오류 메시지 보내줌실패면 result_data 에 메시지가 들어간다. TCP 쪽 패킷 정의서에는 별도 필드가 있었다.
result_code
result_data
kick_reson 실패코드 (실패했을 경우에만 값이 있다)같은 시스템에 두 방식이 섞여 있는 셈이다. HTTP 는 실패면 result_data 자리에 메시지를 넣고 TCP 는 kick_reson 이라는 별도 필드에 코드를 넣는다.
result_data 에 넣는 방식은 필드가 안 느는 대신 그 자리의 타입이 상황에 따라 달라진다. 성공이면 유저 정보 객체이고 실패면 오류 메시지 문자열이라 파싱하는 쪽에서 성공 여부를 먼저 보고 타입을 정해야 하고 is_array 로 한 번 더 확인하게 된다.
TCP 쪽은 각 필드의 타입이 항상 같다. 다만 항상 있는 것은 아니고 실패했을 때만 kick_reson 에 값이 있다.
코드와 메시지의 차이
또 하나 다른 것이 있다. 메시지는 사람이 읽는 문자열이고 코드는 프로그램이 분기하는 값이다.
메시지를 받으면 그대로 화면에 띄우기는 쉬운 대신 분기가 어렵다. 문자열을 비교해야 하는데 문구가 바뀌면 그 분기가 조용히 안 걸린다. 코드를 받으면 분기는 쉬운데 화면에 띄울 문구는 클라이언트가 갖고 있어야 한다.
여기까지 보고 나니 왜 다른지 짐작이 갔다. HTTP 쪽은 웹 화면이라 오류가 나면 대개 보여주고 끝이다.
TCP 쪽은 게임 접속이라 실패 사유에 따라 다르게 동작해야 한다.
중복 로그인 → 재접속 안내
인증 실패 → 로그인 화면으로
서버 만원 → 잠시 후 재시도분기가 필요하니 코드가 맞다.
0과 1이었다
성공과 실패 값이 0과 1이다.
0: FAIL
1: SUCCESS참이 1이라 조건문에 그대로 쓸 수 있다. 반대로 0을 성공으로 두는 방식도 있는데 그것은 명령줄 종료 코드의 관례다.
두 관례가 정반대라는 것을 이때 알았다. 셸의 종료 코드는 0이 성공이고 HTTP 상태 코드는 200 이 성공이라 관례 자체가 두 갈래다.
한 시스템 안에서 둘이 섞이면 위험해 보인다. API 응답은 1이 성공이고 스크립트 종료는 0이 성공인데 둘 다 다루는 코드를 짜면 헷갈릴 것 같다. 이 명세서는 전부 1이 성공으로 통일돼 있었다.
층이 갈리는 것도 있다. HTTP 상태 코드가 200 인데 본문의 result_code 가 0일 수 있다. 두 값은 서로 다른 층이다.
비교 — 자리마다 다른 표현
결제 쪽에는 다른 형식이 있었다.
status completed, initiated, failed문자열이다. 숫자 코드가 아니라 뜻이 보이는 값이라 로그에 찍혔을 때 바로 읽힌다. 숫자면 1과 2와 3을 보고 표를 찾아야 한다.
정리하면 이 시스템에 값 표현이 세 가지였다.
성공 여부 0/1
실패 사유 코드 또는 메시지
처리 상태 영문 문자열한 가지로 통일돼 있지 않다. 지금은 각각 이유가 있어 보이는데 어디까지가 의도이고 어디부터가 그냥 그렇게 된 것인지는 모르겠다.
정리
- 열몇 개 API 가
result_code·result_data껍데기를 공유한다 - 읽는 쪽이 공통 처리를 한 번만 만들면 된다
json_decode가null이면json_last_error로 파싱 실패를 가른다- 실패 사유를 데이터 자리에 넣는 방식과 별도 필드를 쓰는 방식이 있다
- 데이터 자리에 넣으면 성공은 객체 실패는 문자열로 타입이 달라진다
- 별도 필드는 타입이 고정인 대신 실패했을 때만 값이 있다
- 메시지는 보여주기 쉽고 코드는 분기하기 쉽다
- 분기가 필요한 쪽은 코드 보여주고 끝인 쪽은 메시지가 맞아 보인다
- 성공이 1인 관례와 0인 관례가 정반대로 존재한다
- HTTP 상태 코드와 본문의
result_code는 서로 다른 층이다 - 상태 값을 영문 문자열로 두면 로그에서 바로 읽힌다