외부 거래소의 주문 취소 관련 API 를 공식 문서대로 구현했는데 동작이 예상과 계속 달랐다. 어긋나는 자리를 하나씩 관측해서 규칙을 다시 세웠다.
Table of contents
Open Table of contents
증상 — 상태에 따라 갈리는 목록
같은 주문이 GET /orders/open 에서는 조회되고 GET /orders/history 에서는 안 나왔다. 접수 단계에서 취소 요청한 것은 두 목록에 다 있고 부분 체결 이후에 취소 요청한 것은 한쪽에만 있었다.
문서에는 각 목록이 무엇인지만 적혀 있고 어떤 주문이 어디에 들어가는지가 없었다. 두 가지 방법이 있었다. 상대에게 문의해 답을 기다리는 것과, 두 목록을 다 조회하고 orderId 로 합치면서 중복을 제거하는 것이다. 뒤쪽을 골랐다. 이유는 문의 답이 한 주 넘게 걸리는 상대라서다. 대신 호출 수가 두 배가 되는 것을 감수했다.
조합으로만 드러나는 상태
취소 요청 중인 주문만 골라 조회하는 방법이 없어서 전부 받아 거르는 수밖에 없었다. 거르는 조건은 isCancelRequested 와 fillStatus 와 cancelSource 세 필드의 조합이었다.
각 필드는 혼자서는 아무것도 알려 주지 않는다. 실제 데이터를 여러 건 받아 상태별로 필드값을 표로 만들고 나서야 그 조합이 보였다.
원인 — 사라지는 항목
가장 곤란한 것은 취소가 완료되면 open 목록에서 항목 자체가 없어지는 동작이었다. 받아서 처리하는 중인데 다음 조회에서 안 보이면 취소 완료인지 조건 불일치인지 우리 조회가 틀린 것인지 알 수 없다.
같은 상대의 입출금 API 는 상태만 바뀌고 목록에는 남으므로 주문 쪽만 다른 설계였다. 최초 접수 때 orderId 를 저장해 두고 GET /orders/{id} 로 이력을 따로 조회하는 경로를 붙여서 사라진 이유를 확인하게 했다.
주의 — 이름이 자연스러운 함정 필드
스키마에 있는데 값이 항상 0인 fee 필드가 있었다. 이름만 보면 실제 수수료가 들어올 것 같아서 그대로 쓰면 수수료를 항상 0으로 계산하게 되는데 실제 수수료는 체결 이벤트에만 실려 온다.
quantity 도 남은 수량이 아니라 주문에 걸린 전체 수량이었다. 오류가 나지 않고 값만 틀리는 부류이고 이름이 자연스러울수록 확인 없이 쓰게 된다.
검증 — 관측이 실질적인 명세가 됐다
발견할 때마다 항목별로 docs/external-api-notes.md 에 모았더니 다섯 줄짜리 목록이 됐다. 공식 문서보다 이 목록이 구현에 더 쓸모가 있었으므로 실질적인 명세는 관측한 동작 쪽이었다.
다만 표본이 적으면 우연히 그렇게 보였을 수 있어서 다른 사람이 원문과 대조하게 했다. 대조에서 대부분 맞았고 하나는 조건이 더 좁아서 그것을 반영했다.
정리
- 외부 연동에서 진짜 명세는 관측한 동작이다
- 상태에 따라
open과history중 조회되는 목록이 다를 수 있다 - 특정 상황이 여러 필드의 조합으로만 드러날 수 있다
- 상태별 필드값을 표로 만들어야 그 조합이 보인다
- 취소되면 목록에서 사라지는 설계가 있다
- 최초
orderId를 저장하고 이력 조회를 따로 붙인다 - 항상 같은 값인
fee같은 함정 필드는 오류 없이 값만 틀리게 만든다 - 관측으로 얻은 규칙은 다른 눈으로 한 번 더 대조한다