GH GambleHub

스키마 레지스트리 및 데이터 진화

왜 스키마 레지스트리가 필요합니까?

Schema Registry는 다음을 제공하는 데이터 계약 (API, 이벤트, 스레드, 메시지, 상점) 에 대한 중앙 집중식 진실 소스입니다

예측 가능한 진화: 호환성 규칙 및 자동 차단 점검.
반복성과 투명성: 버전의 이력, 누가/언제/왜 변경되었습니까?
표준화: 균일 한 이름, 오류 형식, 추적 필드, PII 레이블.
CI/CD와의 통합: 생산 전에 깨는 변화를 차단합니다.

레지스트리는 프로토콜 우선 및 계약 호환성을 연결하여 변경 사항을 빠르고 안전하

형식 및 응용 프로그램

JSON 스키마: REST/TH 페이로드, 문서, 구성.
Avro: 이벤트 버스 (Kafka/Pulsar), 필드 ID를 통한 소형/진화.
원형: gRPC/RPC, 이진 효율적이고 엄격한 태그.
GraphQL SDL: 유형 및 지침 스키마, '@ under' 를 통한 진화.
아티팩트로서 SQL DDL: 합의 된보기 (예: 외부 상점) 를 조심스럽게 수정합니다.

💡 단일 레지스트리는 여러 유형의 아티팩트를 한 번에 저장할 수 있지만 별도의 호환성 정책을 사용할 수

호환성 모드

BACKWARD: 새로운 스키마는 오래된 데이터/메시지를 읽습니다. 페이로드를 추가로 확장하는 생산자에게 적합합니다.

FORWARD: 오래된 소비자는 새 데이터를 올바르게 읽습니다 (허용 가능한 독자가 필

전체: 두 가지를 결합합니다 (더 엄격하고 공공 계약에 더 편리 함).
아니오: 수표 없음-샌드 박스 만 해당됩니다.

권장 사항:
  • 이벤트: 더 자주 BACKWARD (프로듀서는 페이로드 옵션을 확장합니다).
  • 공개 API: 고객에 대한 전체 또는 BACKWARD + 엄격한 내성 판독기.
  • 내부 프로토 타입: 일시적으로 NONE이지만 트렁크에는 없습니다.

안전한 (첨가제) 대 위험한 변경

첨가제 (OK):
  • 선택한 필드/타입을 추가합니다.
  • 새로운 가치를 가진 Enum 확장 (내약성 독자 포함).
  • 대체 프로젝션/이벤트 ('.enriched') 를 추가하십시오.
  • 제약 조건 완화 ('minLength', 'maximum' tilled, 인터넷 없음).
위험한 (휴식):
  • 필드를 삭제/이름을 바꾸거나 유형/필수를 변경하십시
  • 스레드에서 상태/코덱의 의미를 변경합니다.
  • 원형 태그의 재사용.
  • 이벤트에서 파티션 키를 변경합니다.

등록 조직

명명 및 주소 지정

그룹/공간: '결제', 'kyc', '감사'.
이름: '결제. 승인 된. v1 '(이벤트)', 지불. v1. CaptureRequest '(gRPC),' 주문. v1. 주문 '(JSON 스키마).
메타 데이터/스키마 버전의 미성년자 이름.

메타 데이터

'소유자' (명령), '도메인', '슬래스' (SLO/SLA), '보안. 계층 '(PII/PCI),' 보존 ',' 호환성 _ 모드 ',' 일몰 ',' 변경 '.

라이프 사이클 관리

초안 → 검토 → 승인 → 방출 → 더 많은 → 일몰.
자동 유효성 검사기/린터, 수동 설계 검토 (API 길드), 메모 해제.

CI/CD에 통합

1. 사전 커밋: 로컬 라인터 (Spectral/Buf/Avro tools).
2. PR 파이프 라인: 스키마-디프 → 호환성 모드 검사; 차단.
3. 아티팩트 게시: 일관된 스키마를 레지스트리 + 생성 SDK/모델로 푸시하십시오.
4. 런타임 가드 (옵션): 게이트웨이/프로듀서는 현재 체계에 대한 페이로드를 검증합니다.

PR 단계의 예:
  • 'openapi-diff-실패-돌파'
  • '
    에 대한 파괴-'
  • 'avro-compat-mode BACKWARD'
  • 황금 샘플을 생성하고 CDC 테스트를 실행합니다

계획의 진화: 관행

첨가제 우선: но봉합- '선택적/무효화' (JSON), '선택적' (proto3), 기본적인 참조 아브로.
리버스 피라미드 모델: 코어는 안정적이며 농축은 근처에 있으며 선택 사항입니다.
메이저에 대한 이중 방출/이중 쓰기: 'v1' 과 'v2' 를 병렬로 게시합니다.
일몰 계획: 날짜, 사용, 경고, 어댑터.

무관 한 독자: 클라이언트는 알 수없는 필드를 무시하고 새 enum을 올바르게 처리합니다

체계 및 수표의 예

JSON 스키마 (조각, 추가 필드)

json
{
"$id": "orders.v1.Order",
"type": "object",
"required": ["id", "status"],
"properties": {
"id": { "type": "string", "format": "uuid" },
"status": { "type": "string", "enum": ["created", "paid", "shipped"] },
"risk_score": { "type": "number", "minimum": 0, "maximum": 1 }
},
"additionalProperties": true
}
💡 선택적 → BACKWARD로 'risk _ score' 가 추가되었습니다.

Avro (호환성 기본)

json
{
"type": "record",
"name": "PaymentAuthorized",
"namespace": "payment.v1",
"fields": [
{ "name": "payment_id", "type": "string" },
{ "name": "amount", "type": "long" },
{ "name": "currency", "type": "string" },
{ "name": "risk_score", "type": ["null", "double"], "default": null }
]
}

프로토 (태그를 재사용하지 마십시오)

proto syntax = "proto3";
package payments.v1;

message CaptureRequest {
string payment_id = 1;
int64 amount = 2;
string currency = 3;
optional double risk_score = 4; // additive
}
// tag=4 зарезервирован под risk_score, его нельзя менять/удалять без v2

이벤트 등록 및 분할

명명 이벤트: '도메인. 행동. v {major} '(' 지불. 캡처. v1 ').
파티셔닝 키는 계약의 일부입니다 ('payment _ id', 'user _ id').
코어 vs 농축: '.v1' (코어) 및 '.enriched. v1 '(세부 사항).
레지스트리 호환성: 테마/유형 수준의 모드; CI는 호환되지 않는 변경을 거부합니다.

마이그레이션 관리

→ Migrate → 계약 확대 (REST/gRPC):

1. 필드/테이블 2 추가) 새 필드를 작성/읽기 시작합니다. 3) 일몰 후 오래된 것을 삭제하십시오.

  • 이중 방출 (이벤트): 'v1 '/' v2' 와 병렬, 소비자/프로젝션 마이그레이션, 'v1' 제거.
  • 재생: 로그에서 새 다이어그램으로 투영을 재 조립합니다 (호환성 및 철새 만 해당).
  • 어댑터: 복잡한 클라이언트에 대해 'v1 ² v2' 를 변환하는 게이트웨이/프록시.

안전 및 준수

다이어그램의 PII/PCI 레이블: 'x-pii: 참', 'x- 감도: 높음'.
액세스 정책: 누가 체계 (RBAC) 를 게시/수정하고 릴리스에 서명 할 수 있습니까?
암호화: 스키마 버전의 서명, 불변의 감사 로그 (WORM).
잊을 권리: 암호화/암호화 소거가 필요한 필드를 지정하십시오. 레지스트리의 지침.

관찰 및 감사

대시 보드: 변경 사항 수, 유형 (마이너/메이저), 거부 된 PR 공유, 버전 사용량.
감사 흔적: 계획을 변경 한 사람, PR/ADR 링크, 관련 릴리스.
런타임 메트릭: 검증에 실패한 메시지의 백분율; 호환성 사고.

도구 (샘플 스택)

OpenAPI/JSON 스키마: 스펙트럼, OpenAPI Diff, Schemathesis.
프로토 타입/gRPC: 부프, 마비, 프로토 라인터.
Avro/Events: 유창한/Redpanda Schema Registry, Avro-tools, Karapace.
GraphQL: GraphQL 검사관, GraphQL Codegen.
레지스터/카탈로그: 아티팩트 레지스트리, Git 기반 레지스트리, 백 스테이지 카탈로그, 사용자 지정 UI.
문서: Redocly/Stoplight, Swagger-UI, GraphQL.

반 패턴

스와 거 세척: 이 계획은 서비스의 현실을 반영하지 않습니다 (또는 그 반대).
비활성화 된 호환성 검사: "긴급" → 제품 중단.
원형 태그 재사용: 자동 데이터 손상.

"모든 것을위한" 단일 호환성 모드: 다른 도메인에는 다른 모드가 필요합니

공공 계획으로서의 원시 CDC: DB 모델 유출, 진화의 불가능성.

구현 점검표

  • 도메인별로 정의 된 아티팩트 형식 및 호환성 모드.
  • 라이터와 스키마 디프는 CI로 구성되고 PR은 깨질 때 차단됩니다.
  • 고객의 관용 독자를위한 활성화; 'additionalProperties = 참' (해당되는 경우).
  • 주요 변경 사항은 LF/ADR을 통해 이루어지며 일몰 계획과 이중 배출/이중 쓰기가 있습니다.
  • 회로에는 PII/PCI 및 액세스 레벨이 표시됩니다. 감사가 가능합니다.
  • 버전 사용 및 호환성 실패 대시 보드.
  • 레지스트리에서 SDK/모델을 생성하는 것은 파이프 라인의 일부입니다.
  • 문서 및 황금 샘플이 자동으로 업데이트되었

FAQ

Git에 체계를 저장할 레지스트리가 없으면 가능합니까?
예. 그러나 레지스트리에는 호환성 API, 검색, 메타 데이터, 중앙 집중식 정책 및 즉시 검증이 추가됩니다. 가장 좋은 옵션은 위에 스토리지 + UI/정책으로 Git입니다.

호환성 모드를 어떻게 선택합니까?
생산자가 페이로드를 확장하면-BACKWARD. 공개 API/SDK-전체. 빠른 프로토 타입-일시적으로 NONE (트렁크가 아님).

필요한 경우 어떻게해야합니까?
v2 준비: 이중 방출/이중 실행, 일몰 날짜, 어댑터, 원격 측정, 마이그레이션 가이드.

런타임에 페이로드를 확인해야합니까?
중요한 도메인의 경우 예: 정크 메시지를 방지하고 진단 속도를 높입니다.

결과

스키마 레지스트리는 위험한 즉흥 연주에서 데이터의 진화를 균일 한 상호 운용성 규칙, 자동화 된 검증, 이해하기 쉬운 버전 및 투명한 이력과 같은 관리 가능한 프로세스로 전환합니다. 여기에 첨가제 우선, 관용 독자, 이중 방출 및 일몰의 규율을 추가하면 고장과 야간 사고없이 계약이 빠르게 개발됩니다.

Contact

문의하기

질문이나 지원이 필요하시면 언제든지 연락하십시오.우리는 항상 도울 준비가 되어 있습니다!

통합 시작

Email — 필수. Telegram 또는 WhatsApp — 선택 사항.

이름 선택 사항
Email 선택 사항
제목 선택 사항
메시지 선택 사항
Telegram 선택 사항
@
Telegram을 입력하시면 Email과 함께 Telegram에서도 답변드립니다.
WhatsApp 선택 사항
형식: +국가 코드 + 번호 (예: +82XXXXXXXXX).

버튼을 클릭하면 데이터 처리에 동의하는 것으로 간주됩니다.