フィールド名が変わり、合計だけが静かに狂った

목표

파트너 주문 API 의 1.3 과 1.4 를 나란히 놓고 무엇이 우리를 깨뜨리는지 필드 단위로 가린 뒤, 우리가 읽는 것만 적은 소비자 계약과 그 계약을 매번 확인하는 계약 시험을 만든다. 구판과 신판을 동시에 받아들이는 읽기 계층까지 붙인다.

왜 중요한가

연결이 끊기는 사고는 경보가 울린다. 필드가 이름을 바꾸는 사고는 울리지 않는다. rec.get("region") 은 예외 대신 None 을 돌려주고, 늘어난 열거값은 우리 분기 어디에도 안 들어가고, 정수가 십진 문자열이 되면 합계가 조용히 달라진다. 그래서 통합의 안전장치는 "문서를 잘 읽는 것" 이 아니라 기계가 매번 대조하는 계약이다. 계약에는 파트너의 전체 스키마가 아니라 우리가 실제로 읽는 필드만 적는다. 전부 적으면 우리가 안 쓰는 필드의 변경에도 빨간불이 켜지고, 소음이 늘면 사람은 시험을 끈다. 판올림은 한 번에 끝나지도 않는다. 구판과 신판이 몇 달 함께 도는 동안 읽는 쪽이 둘 다 받아들여야 하므로, 이름이 바뀐 자리는 별칭 표로 타입이 바뀐 자리는 정규화 함수로 한곳에 모은다. 채점기는 여러분의 문장을 믿지 않는다. 여러분이 만든 파트너 서버를 채점기가 고른 포트에 직접 띄워 응답을 받아 보고, 여러분의 판정기와 대조기를 채점기가 만든 입력으로 다시 실행해 답을 맞춰 본다.

단계

1. /root/contract/partner.py 를 만들어 포트 8011 에 띄우고, 두 판의 응답을 /root/contract/v13.json 과 /root/contract/v14.json 에 저장하세요.
2. 두 응답의 필드 차이를 /root/contract/diff.json 에 added·removed·type_changed·enum_added 네 칸으로 적으세요.
3. /root/contract/breaking.py 를 만들어 변경 한 건을 받아 우리를 깨뜨리는지 판정하게 하세요.
4. 우리가 읽는 필드만 적은 소비자 계약을 /root/contract/order.contract.json 에 쓰세요.
5. /root/contract/validate.py 를 만들어 계약과 레코드를 대조하고 위반을 missing·type·enum 으로 갈라 적게 하세요.
6. /root/contract/read_order.py 를 만들어 1.3 과 1.4 응답을 모두 같은 내부 모양으로 옮기세요.
7. /root/contract/contract_test.sh 를 만들어 파트너의 지금 응답을 계약과 대조하고, 어긋나면 0 이 아닌 코드로 끝나게 하세요.
8. /root/contract/contract_report.md 에 네 절로 보고하세요.

참고

• 파트너 서버 실행 계약: python3 /root/contract/partner.py --port <포트> [--drift]. /health 는 {"ok": true, "versions": ["1.3", "1.4"]}, /v1.3/orders 와 /v1.4/orders 는 {"version": ..., "orders": [...]} 를 냅니다. 주문은 24건입니다.
• 두 판의 차이는 이렇습니다. 1.3 은 order_id amount(정수) currency status region updated_at 을, 1.4 는 order_id amount(십진 문자열) currency status market channel updated_at 을 냅니다. 1.4 의 status 에는 on_hold 가 더 있습니다.
• --drift 는 파트너가 공지 없이 또 움직인 판입니다. 7번 단계의 계약 시험이 이것을 0 이 아닌 코드로 걸러야 합니다.
• 판정기 실행 계약: python3 breaking.py --change <파일> 은 {"breaking": true|false, "reason": "..."} 를 냅니다. 변경 JSON 은 {"where": "response"|"request", "kind": "...", "field": "..."} 이고 kind 는 add_field · remove_field · rename_field · type_change · add_enum_value · field_becomes_optional · add_optional_field · add_required_field · relax_required 아홉 가지입니다. 같은 kind 이름이 응답 쪽과 요청 쪽에 모두 나올 수 있고, 그때 답은 서로 다릅니다. 표에 없는 kind 가 오면 안전한 쪽이 아니라 깨진다고 답합니다.
• 대조기 실행 계약: python3 validate.py --contract <파일> --records <파일> 은 {"records": n, "ok": n, "violations": [{"index": i, "field": f, "kind": k}]} 를 냅니다. kind 는 missing · type · enum 입니다. 타입 이름은 string · integer · decimal_string 셋입니다. ok 는 위반이 하나도 없는 레코드의 수입니다.
• 읽기 계층 실행 계약: python3 read_order.py --in <응답 파일> 은 정규화 레코드의 리스트를 냅니다. 각 레코드는 order_id amount_krw(정수) currency status market 다섯 칸입니다.
• 계약 시험 실행 계약: bash contract_test.sh <BASE_URL> 은 위반이 없으면 0, 있으면 1 로 끝납니다.
• 이 실습의 판정 규칙: 응답에서 필드가 더해지는 것만 안전하고 나머지는 깨뜨린다고 봅니다. 요청 쪽은 필수 필드가 더해지는 것만 깨뜨립니다. 이것은 소비자 관점의 규칙이며 RFC 가 정한 것이 아닙니다.
• 흔한 실수: 계약에 파트너의 모든 필드를 적기(우리가 안 쓰는 변경에도 빨간불이 켜집니다), 금액을 float 로 정규화하기(반올림이 생깁니다), 파트너 서버를 앞단에서 띄워 터미널이 막히기.
• 서버는 백그라운드로 띄우고 curl -sf http://127.0.0.1:8011/health 가 될 때까지 기다린 뒤 다음으로 갑니다. 채점기는 여러분이 띄워 둔 프로세스를 보지 않고 스크립트를 직접 다시 띄웁니다.

두 판을 함께 내주는 파트너 띄우기

/root/contract/partner.py 를 만들어 포트 8011 에 띄우고, /v1.3/orders 와 /v1.4/orders 의 응답을 각각 /root/contract/v13.json 과 /root/contract/v14.json 에 저장하세요. 주문은 두 판 모두 24건입니다.

flask 로 세 경로를 만듭니다. /health 는 준비되었음을 알리는 자리이고, 두 판의 목록 경로는 같은 주문 24건을 각자의 필드 이름과 타입으로 냅니다. --port 와 --drift 를 argparse 로 받으세요. 앞단에서 띄우면 터미널이 막히므로 백그라운드로 띄우고 /health 가 200 이 될 때까지 기다립니다.

두 판의 차이를 기계가 읽게 뽑기

/root/contract/diff.json 에 added removed type_changed enum_added 네 칸을 적으세요. added 와 removed 는 필드 이름의 정렬된 리스트, type_changed 는 {"field": ..., "from": ..., "to": ...} 의 리스트(타입 이름은 integer·string), enum_added 는 {"field": ..., "values": [...]} 의 리스트입니다. 열거로 보는 필드는 신판에서 서로 다른 값이 6개 이하인 필드로 한정합니다.

두 응답 파일의 첫 레코드만 보면 필드 이름 집합을 얻을 수 있지만 열거값은 전수로 훑어야 보입니다. 타입 이름은 integer 와 string 두 가지면 충분합니다. status 처럼 값이 몇 종류뿐인 필드는 양쪽의 값 집합을 빼 보세요.

무엇이 우리를 깨뜨리는지 가리기

/root/contract/breaking.py 를 만들어 --change <파일> 로 받은 변경 한 건을 판정해 {"breaking": true|false, "reason": "..."} 를 내게 하세요. 응답 쪽과 요청 쪽의 규칙이 다릅니다.

응답은 우리가 읽는 쪽이라 더해지는 것만 안전합니다. 요청은 우리가 보내는 쪽이라 방향이 반대입니다 — 선택 필드가 늘거나 필수가 선택으로 풀리는 것은 우리에게 아무 일도 아닙니다. (where, kind) 짝을 열쇠로 하는 표 하나면 충분하고, 모르는 짝은 안전한 쪽이 아니라 깨진다고 답하세요.

우리가 읽는 것만 적은 계약

/root/contract/order.contract.json 에 소비자 계약을 쓰세요. version 은 1.4, unknown_fields 는 ignore, fields 에는 우리가 실제로 읽는 다섯 필드(order_id·amount·currency·status·market)만 각각 type 과 required 로 적습니다. currency·status·market 에는 enum 도 답니다.

파트너가 내주는 필드를 전부 적고 싶어지지만, 우리가 안 읽는 필드(channel·updated_at)를 적으면 그쪽이 그 필드를 바꿀 때마다 우리 시험이 빨간불을 켭니다. 타입 이름은 string·integer·decimal_string 셋이고, 1.4 의 금액은 십진 문자열입니다. status 의 열거값은 1.4 응답을 전수로 훑어 얻으세요.

계약과 실제 응답을 대조하기

/root/contract/validate.py 를 만들어 --contract 와 --records 를 받아 {"records": n, "ok": n, "violations": [...]} 를 내게 하세요. 위반은 missing type enum 셋으로 가르고, 각 위반에 index 와 field 를 답니다.

레코드 하나에 위반이 둘일 수 있으니 violations 는 레코드마다 여러 줄이 될 수 있습니다. 반면 ok 는 위반이 하나도 없는 레코드의 수이므로 위반 줄 수를 빼는 방식으로는 나오지 않습니다. 필수가 아닌 필드가 없는 것은 위반이 아니고, 타입이 이미 틀린 값에 열거를 또 묻지는 마세요.

구판과 신판을 함께 받아들이기

/root/contract/read_order.py 를 만들어 --in <응답 파일> 로 1.3 과 1.4 응답을 모두 읽어 같은 내부 모양으로 옮기세요. 각 레코드는 order_id amount_krw(정수) currency status market 다섯 칸이고, 모르는 필드는 버립니다.

이름이 바뀐 자리는 별칭 표 하나로, 타입이 바뀐 자리는 정규화 함수 하나로 모읍니다. 곳곳에 if 를 흩뿌리면 구판을 끊을 때 어디를 지워야 할지 모르게 됩니다. 금액은 float 를 거치지 마세요 — "12300.00" 은 점을 기준으로 잘라 정수로 옮기면 반올림이 생기지 않습니다.

공지 없이 또 움직인 파트너 잡아내기

/root/contract/contract_test.sh 를 만들어 bash contract_test.sh <BASE_URL> 로 파트너의 지금 /v1.4/orders 를 계약과 대조하게 하세요. 위반이 없으면 0, 있으면 1 로 끝나야 하고, 위반이 있을 때는 몇 건인지 화면에 남아야 합니다.

앞에서 만든 validate.py 와 order.contract.json 을 그대로 씁니다. 새로 만들 것은 응답을 받아 오는 부분과 종료 코드뿐입니다. --drift 로 띄운 파트너에 대고 돌려 1 이 나오는지, 평소 파트너에 대고 돌려 0 이 나오는지 둘 다 확인하세요.

판올림 점검 보고서

/root/contract/contract_report.md 에 ## 무엇이 바뀌었나 ## 무엇이 우리를 깨뜨리나 ## 우리가 지킬 계약 ## 다음부터 어떻게 잡나 네 절로 적으세요. 앞 단계에서 얻은 필드 이름과 위반 건수가 본문에 들어가야 합니다.

읽는 사람은 우리 팀장이 아니라 파트너사 담당자일 수도 있습니다. '깨졌다' 가 아니라 '어느 필드가 어떻게 바뀌어 우리 쪽 무엇이 틀어졌다' 로 적으세요. 네 절의 제목은 그대로 두고 숫자는 여러분이 얻은 값으로 채웁니다.