외부 연동에서 배송 처리 부분을 붙이고 있었다. 문서를 읽고 만들었는데 실행하면 오류가 계속 났다.
Table of contents
Open Table of contents
증상 — 같은 요청이 갈렸다
돌아오는 것은 이 코드였다.
INVALID_STATUSINVALID_STATUS 가 어떤 건에서는 안 나고 어떤 건에서만 났다.
거부된 건들을 모아 보니 주문 status 가 같았는데 무엇이 그 차이를 만드는지는 문서에 없었다.
원인 — 문답 자료에 있던 상태 규칙
문답 자료를 전수로 훑었다. 배송 관련만 27건이었다.
상품 준비 중 → 업로드 가능
접수 상태 → 오류
출발 상태 → 별도의 "송장 업데이트 API" 를 써야 함송장 업로드가 준비중 에서만 허용되고 출발 에서는 부를 창구 자체가 달랐다.
표준 규격 문서에는 status 규칙이 있다고만 적혀 있었다. 어느 상태에서 어느 창구를 쓰는지도 그때 파라미터가 무엇인지도 없었다.
표준 문서는 정상 경로를 설명하고 문답 자료에는 실패 사례가 쌓인다. 둘을 다 읽어야 만들 수 있다는 것이 여기서도 같았다.
조치 — 분기와 명시적 예외
switch 로 상태별로 부를 창구를 나눴다.
switch ($order->status) {
case '준비중':
return $this->uploadInvoice($order);
case '출발':
return $this->updateInvoice($order);
default:
throw new InvalidStateException(...);
}default 에서 InvalidStateException 을 던지므로 목록에 없는 상태가 조용히 지나가지 않는다.
그러지 않으면 새 상태가 생겼을 때 아무 처리도 안 되고 그것을 모른 채 지나간다. 예상 못 한 값을 만나면 멈추는 편이 나중에 조사할 시간을 크게 줄인다.
분기를 만들 때 나머지 경우를 어떻게 할지가 분기 자체만큼 중요했다.
주의 — 성공이 반영이 아니었다
문답 자료에서 다른 것도 나왔다.
API 성공 → 즉시 반영 아님API 성공 을 받아도 화면 반영에 최대 한 시간이 걸린다.
보내고 나서 바로 확인하면 아직 안 보인다. 안 됐나 싶어 다시 보내면 중복이 된다.
확인 시점을 뒤로 미루고 cron 이 몇 번 다시 보게 고쳤는데 성공과 반영 사이의 시차를 전제로 넣어야 했다.
비교 — 이름이 비슷한 필드들
분리 배송 쪽에는 비슷한 이름이 둘 있었다.
splitShipping 분리 배송 처리됨
ableSplitShipping 분리 배송 처리 가능함splitShipping 은 결과이고 ableSplitShipping 은 가능 여부라 잘못 읽기 쉽다.
실제 값을 몇 건 받아 우리 자료와 대조해 의미를 확정하고 표로 적어 뒀다. 이름만으로 판단하면 반드시 한 번은 틀린다.
분리 배송에는 부작용도 있었다.
처음 묶음 A 에 항목 1, 2, 3
1 출고 후 항목 1 이 다른 묶음으로 이동먼저 출고된 항목의 묶음 식별자가 바뀌므로 묶음 A 로 추적하면 못 찾는다.
제약 — 되돌릴 수 없는 처리와 완료 불가
가장 무거운 것은 이것이었다.
일단 splitShipping 이 참이 되면 합포장으로 못 돌아간다. 실수로 분리하면 그 건은 그 상태로 고정된다.
그래서 그런 처리 앞에는 확인 단계를 두고 대상 목록을 먼저 보게 했다.
그 유형으로 등록 → 완료 처리 불가
↓
일정 기간 후 자동으로 매출 인식특정 배송 유형으로 등록하면 배송 완료 처리가 영영 안 되는 것도 있었다.
완료가 안 되는데 매출은 잡힌다. 이것을 모르면 완료가 안 된다고 계속 시도하게 되고 그 시도는 영원히 성공하지 않는다.
구현 전에 알아 둔 것을 목록으로 적어 뒀다.
① 상태별로 API 가 다르다 → 분기 필요
② 성공이 즉시 반영이 아니다 → 확인 시점 조정
③ 식별자가 변경된다 → 추적 방식 변경
④ 비가역 처리가 있다 → 사전 확인
⑤ 특정 유형은 완료 불가 → 예외 처리다섯 다 오류를 만나 가며 알아내려면 며칠이 걸린다. 문답 자료 190건 중 배송 섹션 27건만 읽는 데는 반나절이면 됐다.
정리
- 상태에 따라 부를 창구 자체가 다를 수 있다
- 표준 문서에 없고 문답 자료에만 있는 규칙이 있다
- 표준 문서는 정상 경로이고 문답 자료는 실패 사례다
- 분기에 명시적 예외를 두어 예상 못 한 상태를 바로 안다
- 나머지 경우를 어떻게 할지가 분기 자체만큼 중요하다
- 성공이 즉시 반영을 뜻하지 않는다
- 확인 시점을 안 미루면 중복 전송이 된다
- 비슷한 이름의 필드는 실제 값으로 의미를 확정하고 기록한다
- 분리 처리에 식별자 변경 부작용이 있을 수 있다
- 되돌릴 수 없는 처리에는 확인 단계를 둔다
- 완료가 불가능한 유형을 알아야 시도를 멈춘다
- 필요한 섹션만 골라 읽으면 며칠이 반나절이 된다