필드 이름은 변경되지 않았지만 의미가 변경되었으며 다운스트림에서 조용히 오류가 발생했습니다. 추출 결과에 버전 번호를 추가합니다.

이 문서는 문서 추출 인터페이스를 유지 관리하는 개발자 및 다운스트림 데이터 팀을 위해 작성되었습니다. 추출 결과가 업그레이드된 후에는 필드 이름이 변경되지 않을 수 있지만 의미는 달라집니다. 예를 들어, amount가 "fen"에서 "yuan"으로 변경된 경우 유형 검사는 통과하지만 비즈니스 번호는 2배 정도 다를 수 있습니다.

다음은 이러한 유형의 문제를 처리하기 위해 버전 번호, 명확한 마이그레이션 기능 및 마이그레이션 기록을 사용하는 방법을 설명합니다. 이 내용을 읽고 나면 어떤 업그레이드에 버전 전환이 필요한지, 마이그레이션 중에 어떤 정보를 유지해야 하는지 결정할 수 있습니다.

이 기사의 예제는 합성 샘플을 사용하며 격리된 환경에서 예제를 통해 코드를 확인했습니다. 이는 모든 실제 파일이나 제품 효과를 보장하는 것은 아닙니다. 중요한 서류를 처리하기 전, 원본을 보관하시고, 본문에 기재된 경계 및 허용 항목에 따라 검토하시기 바랍니다.

필드 이름은 변경되지 않았지만 의미가 변경되었습니다. 그것을 처리하는 방법? 한 문장 결론

각 출력에 schema_version 레이블을 지정하고 명시적 마이그레이션 기능을 사용하여 새 버전에 레이블을 지정하는 대신 다양한 버전의 데이터를 변환합니다.

버전 번호는 의미와 일치해야 합니다.

필드를 추가하는 것은 단위를 변경하는 것과 다릅니다. 각 출력에 schema_version를 제공하고 버전별로 유효성 검사기와 마이그레이션 기능을 선택할 수 있습니다.

버전 번호 자체는 시스템을 보호하지 않습니다. 모든 버전이 동일한 미분화된 구문 분석 논리를 따른다면 그것은 단지 장식적인 분야일 뿐입니다.

버전 분석의 핵심

• 버전별 구문 분석 규칙 선택: 버전마다 자체 유효성 검사기를 사용합니다.
• 이주는 명시적인 데이터 변환입니다: 이전 데이터에 새 버전으로 직접 레이블을 지정하지 않습니다.
• 의미적 변경은 추적 가능해야 합니다: 단위 및 정밀도와 같은 규칙을 검토할 수 있어야 합니다.

다음 예에서는 정수 포인트 수를 소수 문자열로 변환하는 방법을 보여줍니다.

감사 가능한 마이그레이션 기능

from decimal import Decimal

def migrate(record):
    if record.get("schema_version") != "v1":
        raise ValueError("unexpected input version")
    cents = record.get("amount_cents")
    if type(cents) is not int:
        raise ValueError("integer cents required")
    return {"schema_version": "v2",
            "amount": format(Decimal(cents) / Decimal(100), ".2f"),
            "currency": record["currency"]}

old = {"schema_version": "v1", "amount_cents": 12345, "currency": "USD"}
new = migrate(old)
assert new["amount"] == "123.45"
assert old["amount_cents"] == 12345
assert migrate({**old, "amount_cents": -25})["amount"] == "-0.25"
try:
    migrate({**old, "amount_cents": True})
except ValueError:
    pass
else:
    raise AssertionError("bool is not a monetary integer here")

이 예에서는 입력 통화가 백분율 단위 관계를 사용하고 출력에 소수점 이하 두 자리가 있다고 가정합니다. 모든 통화 단위를 포괄하는 범용 변환기는 아닙니다.

type(cents) is int는 True를 페니로 받아들이지 않도록 부울 값을 Python의 정수 하위 클래스로 의도적으로 제외합니다.

📊 핵심 비교: 버전 번호만 및 버전별 마이그레이션

이관기록에는 어떤 내용을 남겨야 하나요?

역추적 및 오프로드 처리를 용이하게 하려면 마이그레이션 중에 다음 정보를 기록하는 것이 좋습니다.

역사적 오류와 무한히 호환되지 마십시오.

이전 레코드의 단위 자체가 불확실한 경우 마이그레이션 기능은 추측해서는 안 됩니다. 보다 적절한 접근 방식은 명시적인 실패를 반환하고 이전 데이터를 유지하며 추가 증거를 요청하는 것입니다.

이미 기존 인터페이스를 사용하고 있는 다운스트림 사용자의 경우 값 의미가 변경되었음을 자동으로 발견하기보다는 버전 전환도 준비해야 합니다.

참고: JSON 스키마 공통 키워드

번역 후 검증에도 버전 인식이 필요합니다

추출된 필드를 사용하여 OmniDoc(제품 포털) 변환을 확인할 때 필드가 생성된 프로토콜을 표시해야 합니다. 소스 파일, 추출 규칙 또는 대상 언어의 변경 사항은 비교 방법에 영향을 미칠 수 있습니다.

버전 정보를 보존하면 단순히 모델 불안정성 때문이 아니라 "이번이 지난번과 다른 이유"를 해결 가능한 문제로 만들 수 있습니다.

🎯 어떤 방법이 당신에게 적합합니까?

새 필드만 추가하는 경우

새 필드를 직접 추가하고 출력에 schema_version를 기록합니다.

필드의 단위나 의미를 수정하고 싶은 경우

새 버전에 대한 독립적인 유효성 검사기와 마이그레이션 기능을 작성하고 이전 구문 분석 논리를 재사용하지 마십시오.

과거 데이터 단위가 명확하지 않은 경우

마이그레이션이 실패했음을 명확히 하고 원본 데이터를 유지하며 처리하기 전에 증거를 추가하세요.

❓ 자주 묻는 질문(FAQ)

1. 출력에 버전 번호를 추가하는 것만으로도 충분합니까?

충분하지 않습니다. 버전 번호는 단지 레이블일 뿐이며 모든 버전이 여전히 동일한 구문 분석 논리를 사용하는 경우 비즈니스 의미를 보호할 수 없습니다.

2. 마이그레이션 기능에서 부울 값을 제외하는 이유는 무엇입니까?

Python의 부울 값은 정수의 하위 클래스이며 type(cents) is int는 True가 페니로 허용되는 것을 방지합니다.

3. 이전 녹음 단위가 확실하지 않은 경우 어떻게 해야 합니까?

마이그레이션 기능을 추측해서는 안 됩니다. 명시적인 실패가 반환되고 이전 데이터가 유지되며 추가 증거가 요청됩니다.

4. 이주기록에 어떤 정보를 저장해야 하나요?

최소한 입력 및 출력 버전, 마이그레이션 프로그램 버전, 원본 레코드 ID 및 실패 이유를 포함하십시오.

📝 요약

필드 이름이 변경되지 않은 상태로 유지된다고 해서 의미가 변경되지 않은 상태로 유지되는 것은 아닙니다. 명시적인 마이그레이션 기능과 마이그레이션 기록을 사용하여 출력 버전을 관리하고 의미론적 변경을 처리하면 다운스트림에서 자동 오류가 발생할 위험을 크게 줄일 수 있습니다.

지금 사용해 보세요: 원본 레이아웃을 유지하면서 번역을 시작하려면 문서를 업로드하세요.