API 스키마 변경은 값의 의미와 직렬화 형태를 함께 확인해야 합니다. 필드 이름, 존재 여부, 문자열·숫자·불리언 자료형, 시간과 수량 단위, null 가능성, enum 추가, 배열 순서와 시행 시각을 점검합니다. 구·신 응답을 저장해 계약 테스트를 돌리고, 모르는 필드는 허용하되 필수 필드의 누락과 알 수 없는 enum은 조용히 기본값으로 바꾸지 않아야 합니다.
스키마 변화는 여섯 종류로 나눕니다
공지의 changed라는 말만 기록하지 않고 추가, 삭제, 이름 변경, 자료형 변경, 단위 변경, 허용값 변경으로 나눕니다. 가격이 "1.25" 문자열에서 1.25 숫자로 바뀌면 화면에는 같아 보여도 엄격한 파서와 정밀도 처리가 달라집니다. 밀리초 타임스탬프가 마이크로초로 바뀌면 날짜는 전혀 다른 값으로 해석될 수 있습니다.
Binance Spot REST 문서는 기본 타임스탬프가 밀리초이며 헤더로 마이크로초 응답을 요청할 수 있다고 명시합니다. 이런 선택지가 추가됐을 때 필드 이름만 확인하면 단위를 놓칩니다. 수량·가격 문자열을 부동소수점으로 즉시 바꾸는 코드도 자릿수 손실 가능성이 있어 원문과 내부 정밀 타입을 분리합니다.
API 호환성은 필드 이름보다 자료형·단위·없음의 의미를 함께 지키는 계약입니다.
JOBCOIN 해설
그림은 이 주제의 공통 개념을 단순화한 설명입니다. 아래 항목에서 이 글의 구체적인 조건과 예외를 함께 읽어보세요.
- 스키마 변화는 여섯 종류로 나눕니다
공지의 changed라는 말만 기록하지 않고 추가, 삭제, 이름 변경, 자료형 변경, 단위 변경, 허용값 변경 으로 나눕니다.
- 필드 추가와 삭제의 실패 방식을 다르게 설계합니다
응답 객체에 새 필드가 추가됐다는 이유로 역직렬화가 실패하면 거래소의 비파괴적 확장에도 서비스가 멈춥니다.
- enum 추가는 정상적인 새 상태일 수 있습니다
주문 상태나 event_type에 새 값이 추가되면 switch문의 default가 예외를 내거나, 더 위험하게는 UNKNOWN을 CANCELED로 매핑할 수 있습니다.
AI로 제작한 개념도 · 실제 가격·거래 내역·통계가 아닙니다.
필드 추가와 삭제의 실패 방식을 다르게 설계합니다
응답 객체에 새 필드가 추가됐다는 이유로 역직렬화가 실패하면 거래소의 비파괴적 확장에도 서비스가 멈춥니다. 알 수 없는 필드는 보존하거나 무시할 수 있게 설계합니다. 반면 주문 ID나 상태처럼 필수 필드가 사라졌을 때 0 또는 빈 문자열로 대체하면 잘못된 주문 대사가 이어집니다.
필수 필드 누락은 격리 큐와 경보로 보내고 원문 응답을 비밀정보 제거 후 보관합니다. 선택 필드의 null과 필드 자체 누락도 구분합니다. null이 ‘아직 계산되지 않음’을 뜻하는데 0으로 바꾸면 실제 0값과 데이터 부재가 합쳐집니다.
enum 추가는 정상적인 새 상태일 수 있습니다
주문 상태나 event_type에 새 값이 추가되면 switch문의 default가 예외를 내거나, 더 위험하게는 UNKNOWN을 CANCELED로 매핑할 수 있습니다. Coinbase International 주문 응답 문서는 NEW, TRADE, CANCELED, REPLACED, PENDING_CANCEL, REJECTED 등 여러 이벤트 값을 열거합니다. 공지는 기존 값 변경뿐 아니라 새 허용값도 확인해야 합니다.
모르는 enum은 원문 값을 보존한 unknown 상태로 처리하고 자동 주문을 안전 정지시킵니다. 이후 문서 의미를 확인해 전이를 추가합니다. 새 주문 유형이나 상태를 기존 LIMIT·CANCELED 의미로 추정하지 않습니다.
| 변경 | 조용한 실패 | 권장 검증 |
|---|---|---|
| 필드 추가 | 엄격 파서 전체 실패 | 미지 필드 허용 |
| 필드 삭제 | 빈값으로 계산 지속 | 필수 필드 경보 |
| 자료형·단위 | 숫자는 보여도 배율 오류 | 타입·범위 계약 |
| enum 추가 | 기존 상태로 오분류 | 원문 unknown 보존 |
| null 규칙 | 0과 미산출 혼동 | 누락·null·0 분리 |
시행 시각과 인터페이스를 정확히 고릅니다
REST, WebSocket, FIX와 테스트넷은 같은 날 같은 형태로 바뀐다고 가정하지 않습니다. Coinbase의 Upcoming Changes는 FIX execution report의 변경이나 cancel-replace 지원 확대처럼 인터페이스와 출시일을 구체적으로 적습니다. 자신이 쓰는 채널과 메시지 타입이 대상인지 확인합니다.
공지 게시일, 예정 출시일, 실제 배포 시각과 유예 종료를 별도 필드로 기록합니다. 날짜만 있고 UTC가 없으면 거래소가 지정한 시간대를 확인합니다. 구버전과 신버전이 공존할 때는 요청 헤더·엔드포인트·버전 선택을 로그에 남겨 어느 응답을 받았는지 재현합니다.
실제 응답을 고정한 계약 테스트를 만듭니다
변경 전 정상·빈 배열·부분 체결·거절·null 포함 응답을 fixture로 저장합니다. 신 스키마 샘플에도 같은 비즈니스 검증을 적용해 주문 ID, 가격, 수량, 상태와 시각이 내부 모델로 정확히 변환되는지 봅니다. 샘플 한 개만 통과시키지 않고 경계값을 포함합니다.
운영 전에는 shadow parser로 같은 원문을 구·신 코드에 넣고 차이를 기록합니다. 계산 결과가 같더라도 로그에 원문 타입과 단위를 남깁니다. 민감한 계정 값과 API 서명은 fixture에서 제거하고 구조를 검증하는 데 필요한 필드만 보존합니다.
- 공지의 대상 REST·WebSocket·FIX와 엔드포인트를 표시합니다.
- 필드별 존재·자료형·단위·null·enum 규칙을 표로 만듭니다.
- 전환 전후 실제 응답 fixture를 각각 확보합니다.
- 미지 필드와 미지 enum의 처리 정책을 분리합니다.
- 원문과 내부 모델의 차이를 shadow 로그로 대조합니다.
오류 없는 파싱과 올바른 의미를 구분합니다
JSON 파싱에 성공해도 숫자의 통화, 계약 단위, 시각 기준이 틀리면 결과는 잘못됩니다. 필드명을 그대로 내부 변수에 옮기는 것보다 문서의 정의와 계산 소비자를 함께 검토합니다. 특히 pricePrecision 같은 표시 정보와 실제 주문 필터를 혼동하지 않습니다.
배포 뒤에는 파서 예외 수뿐 아니라 unknown enum, null 비율, 범위 이탈, 주문 거절과 구·신 결과 불일치를 관측합니다. 전환이 끝나도 구 코드를 즉시 제거하지 않고 합의한 관찰 기간과 롤백 조건을 충족한 뒤 정리합니다.
자주 묻는 질문
새 필드가 추가되면 항상 하위 호환인가요?
클라이언트가 미지 필드를 거부하면 장애가 날 수 있습니다. 추가 필드를 허용하는지 계약 테스트로 확인해야 합니다.
숫자 문자열이 숫자로 바뀌어도 값은 같은 것 아닌가요?
정밀도, 큰 정수, null 처리와 직렬화 비교가 달라질 수 있어 자료형 변경으로 다뤄야 합니다.
알 수 없는 주문 상태는 무엇으로 저장하나요?
기존 상태로 추정하지 말고 원문 값을 포함한 unknown으로 보존해 자동 처리를 안전 정지합니다.
더 깊이 읽기
본문에서 다룬 개념과 확인 절차를 다음 글에서 이어서 살펴보세요.
