파일 이름은 그대로인데 안이 바뀌었다

한 줄 요약

남이 주는 파일의 스키마는 통보 없이 바뀐다. 그래서 받는 쪽이 지문을 굳혀 두고, 무엇이 깨지고 무엇이 안 깨지는지를 코드로 못박아 자동으로 판정해야 한다.

왜 이게 필요했나

월요일마다 같은 이름의 파일이 온다. 12주 동안 아무 문제가 없었다. 13주차에 대시보드의 매출이 0 이 된다. 파일을 열어 보니 칼럼 이름 하나가 amount_krw 에서 amount 로 바뀌어 있다. 보낸 쪽에서는 "필드 이름을 정리했다" 고 한다. 알려 주지 않은 이유는 간단하다 — 그쪽에서는 그게 우리 파이프라인을 멈추는 일인 줄 몰랐다.

이 일이 반복되는 구조적인 이유가 있다. 보내는 쪽은 자기 시스템의 스키마를 바꾼 것이고, 받는 쪽은 그것을 계약으로 쓰고 있었다. 두 사실 사이에 문서가 없으면 변경은 늘 조용히 온다. 게다가 우리는 바꾸는 쪽을 통제할 수 없다. 운영 DB 라면 구·신 스키마를 공존시키며 옮겨 갈 수 있지만, 남의 파일에는 그런 여지가 없다.

그래서 할 수 있는 일은 하나뿐이다. 바뀌었다는 사실을 파이프라인이 먼저 알아채게 만드는 것.

어떻게 동작하나

받은 파일에서 스키마를 뽑아 지문으로 굳힌다. 지문에 담을 것은 칼럼 이름과 순서, 칼럼마다 추론한 타입, 그리고 값 표본이다. 이름과 타입만 이어 붙여 해시를 내면 짧은 지문 하나가 나오고, 그 지문이 지난주와 다르면 무언가 바뀐 것이다.

타입 추론은 잣대를 먼저 정해야 한다. 빈 값을 빼고 남은 값이 전부 정수 모양이면 int, 소수까지 포함하면 float, 전부 YYYY-MM-DD 면 date, 그 밖은 str 로 본다. 이것은 추론이지 선언이 아니다 — 그래서 어떤 잣대를 썼는지 코드에 적혀 있어야 나중에 틀렸을 때 고칠 자리를 안다.

그다음 지난주 지문과 대조해 달라진 것을 다섯 가지로 나눈다.

| 종류 | 무엇이 보이나 | 어떻게 알아내나 |
| --- | --- | --- |
| 추가 | 없던 칼럼이 생겼다 | 이름 집합의 차 |
| 삭제 | 있던 칼럼이 없어졌다 | 이름 집합의 차 |
| 이름 변경 | 하나가 사라지고 하나가 생겼다 | 사라진 칼럼과 생긴 칼럼의 값 표본이 크게 겹치는가 |
| 타입 변경 | 같은 이름의 타입이 달라졌다 | 추론한 타입 비교 |
| 의미 변경 | 아무것도 안 보인다 | 스키마로는 못 잡는다. 값 분포로만 보인다 |

이름 변경을 값으로 알아내는 것이 핵심이다. 이름만 보면 사라진 것과 생긴 것 두 건이지만, 값 표본이 거의 같으면 같은 칼럼이 이름만 바꾼 것이다. 이 판정이 있어야 파이프라인이 "매핑을 하나 추가하면 된다" 로 답할 수 있다.

마지막 줄이 이 실습에서 제일 중요하다. 의미 변경은 스키마 검사로 절대 안 잡힌다. 금액 단위가 원에서 천원으로 바뀌어도 칼럼 이름도 타입도 그대로다. 검사는 전부 통과하고, 매출만 1000분의 1이 된다.

현장에서 만나는 모습

첫째, 모르는 칼럼에 놀라서 멈춘다. 보내는 쪽이 자기 필요로 칼럼을 하나 더 붙이는 일은 흔하고, 그것 때문에 우리 적재가 멈출 이유는 없다. 그래서 규칙의 기본은 모르는 칼럼은 통과다. 반대로 없어진 필수 칼럼은 중단이다. 이 두 줄이 호환 규칙의 뼈대이고, 나머지는 그 사이 어딘가에 놓인다.

둘째, 필수와 선택을 구별하지 않는다. 구별이 없으면 모든 삭제가 같은 무게로 취급되어, 아무도 경고를 읽지 않게 된다. 필수 칼럼 목록은 업무가 정하는 것이지 데이터가 정하는 것이 아니다.

셋째, 타입이 넓어진 것과 망가진 것을 같이 다룬다. int 가 float 이 된 것은 대개 소수 표기로 바뀐 것이라 계산은 그대로 된다. int 가 str 이 된 것은 합계가 문자열 이어붙이기가 되거나 예외가 난다. 둘을 같은 등급으로 두면 경고가 쓸모없어진다.

넷째, 분포를 안 본다. 의미 변경을 잡을 유일한 방법은 값의 분포를 지난주와 견주는 것이다. 중앙값이 세 배 이상 뛰거나 3분의 1 아래로 떨어졌다면 사람이 봐야 한다. 이것은 증거가 아니라 단서다 — 실제로 그 주에 대형 거래가 몰렸을 수도 있다. 단서를 사람에게 넘기는 것까지가 기계의 몫이다.

실무에서 진짜 중요한 것

• 지문을 파일과 함께 보관한다. "지난주와 다르다" 를 말하려면 지난주가 어딘가에 적혀 있어야 한다.
• 호환 규칙을 문서가 아니라 코드로 못박는다. 문서에만 있으면 아무도 안 읽고, 읽어도 판정이 사람마다 다르다.
• 필수 칼럼 목록은 업무에게 받는다. 엔지니어가 혼자 정하면 나중에 바꿀 근거가 없다.
• 분포 감시는 단서 생산이다. 멈추지 말고 알리고, 판단은 사람이 한다.

다음 실습에서 할 것

같은 주문 30건을 일곱 주에 걸쳐 스키마만 바꿔 가며 내보내는 재현기를 돌려 수신함을 만든 뒤, 스키마 도구 schema.py 를 한 단계씩 키운다. 지문을 굳히고, 추가와 삭제를 분류하고, 값 표본으로 이름 변경을 찾아내고, 타입 변경을 가르고, 호환 규칙을 contract.json 으로 선언해 pass 와 warn 과 stop 을 자동으로 판정한다. 마지막에는 이름도 타입도 그대로인 채 단위만 바뀐 칼럼을 값 분포로 잡아, 스키마 검사가 무엇을 못 보는지를 숫자로 보인다.