Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

9.4 KiB

Raw Permalink Blame History

title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed

title

source_type

url

archive_url

status

confidence

Protocol Buffers proto3 schema evolution rules

Layer: raw/official-docs/ — Protobuf 공식 proto3 guide 의 "Updating A Message Type" 섹션 verbatim 발췌. ca-tmpl 의 unknown field strict inbound / tolerant outbound 결정과의 비교 + JSON 환경에서 흉내내야 할 안전성 식별.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-schema-serialization-contract	G-F 대안 2 (Protobuf strict typing + reserved field) 의 1차 근거 — Protobuf 의 wire-format 강제와 ca-tmpl JSON 의 OpenAPI drift 검증을 비교
raw/branch-notes/feature-api-compatibility-deprecation-contract	Protobuf 의 "removed field 재사용 차단" + "field rename = JSON encoding 위험" 두 사실이 ca-tmpl 의 deprecation catalog / rename = breaking 결정의 외부 근거

컨텍스트

ca-tmpl 은 JSON over HTTP 기준이지만, schema evolution 을 typed schema (Protobuf/Avro) 와 비교해야 trade-off 가 보임. Protobuf 는 wire-format 안전성을 field number 와 reserved 로 강제. ca-tmpl 결정 (request fail-fast, response strict schema) 이 이에 비해 무엇을 잃고 얻는지 평가.

출처 / Source

원본 URL: https://protobuf.dev/programming-guides/proto3/
아카이브 URL: (미수집)
저자 / 조직: Google / Protocol Buffers project
발행일: continuously updated
마지막 확인일: 2026-05-27

핵심 인용 / Key quotes (verbatim)

[§Updating A Message Type — Adding] "Adding new fields is safe. If you add new fields, any messages serialized by code using your 'old' message format can still be parsed by your new generated code."

[§Updating A Message Type — Removing] "Removing fields is safe. The same field number must not used again in your updated message type. You may want to rename the field instead, perhaps adding the prefix 'OBSOLETE_', or make the field number reserved."

[§Reserved fields] "you must reserve the deleted field number. If you do not reserve the field number, it is possible for a developer to reuse that number in the future."

[§Reserved fields — Risks of reuse] "Reusing a field number makes decoding wire-format messages ambiguous." Identified risks include "Developer time lost to debugging", "A parse/merge error (best case scenario)", "Leaked PII/SPII", "Data corruption".

[§Reserved fields — name reuse] "Reusing an old field name later is generally safe, except when using TextProto or JSON encodings where the field name is serialized."

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
SPVJ-C1	proto3 에서 새 field 추가는 안전 — 이전 message format 으로 직렬화된 메시지를 새 코드가 그대로 파싱 가능 (forward compatibility 보장)	[§Updating A Message Type] "Adding new fields is safe. If you add new fields, any messages serialized by code using your 'old' message format can still be parsed by your new generated code."	`official-standard`	proto3 wire-format 의 forward compatibility	추가된 field 가 모든 코드 경로에서 자동으로 채워진다는 뜻 아님 — default 값 / unset 구분은 별도 시맨틱
SPVJ-C2	field 제거는 안전하나 동일 field number 를 재사용해서는 안 됨 — rename ("OBSOLETE_" prefix) 또는 reserved 처리 권장	[§Updating A Message Type] "Removing fields is safe. The same field number must not used again in your updated message type. You may want to rename the field instead, perhaps adding the prefix 'OBSOLETE_', or make the field number reserved."	`official-standard`	proto3 schema 변경 시 field number 정책	OpenAPI / JSON 환경에서 동일 강제가 표준으로 존재한다는 뜻 아님 — JSON 환경에는 등가 메커니즘 부재
SPVJ-C3	삭제된 field number 는 반드시 reserved 처리 필요 — 안 하면 미래 개발자가 그 번호를 재사용 가능 (컴파일러 차단 없음)	[§Reserved fields] "you must reserve the deleted field number. If you do not reserve the field number, it is possible for a developer to reuse that number in the future."	`official-standard`	proto3 schema 변경 / Protobuf 컴파일러 동작	reserved 처리가 자동으로 일어난다는 뜻 아님 — 개발자가 명시적으로 `.proto` 에 작성해야 함
SPVJ-C4	field number 재사용은 wire-format 디코딩을 ambiguous 하게 만들며, 결과로 (a) 디버깅 시간 손실, (b) parse/merge 에러 (best case), (c) PII/SPII 누출, (d) 데이터 손상 가능	[§Reserved fields — Risks] "Reusing a field number makes decoding wire-format messages ambiguous." + risk list quoted	`official-standard`	proto3 wire-format 의 호환성 위험	위 4가지 위험이 반드시 모두 발생한다는 뜻 아님 — 시나리오별 발생 (best case = parse error)
SPVJ-C5	field name 재사용은 일반적으로 안전하나 TextProto 또는 JSON encoding 사용 시는 위험 — 그 인코딩에서는 field name 이 직렬화됨	[§Reserved fields] "Reusing an old field name later is generally safe, except when using TextProto or JSON encodings where the field name is serialized."	`official-standard`	proto3 + JSON / TextProto encoding 시 field name 정책	binary wire-format 환경에서 field name 이 완전 무의미하다는 뜻 아님 — 디버깅 / 로깅에서 사용됨

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- SPVJ-C1 ~ C5: proto3 schema evolution 의 5가지 핵심 규칙 (add 안전, remove + reserved 의무, 재사용 위험, name 재사용 시 JSON 환경 위험)
이 자료가 증명하지 않는 것:
- OpenAPI / JSON Schema 에 등가 reserved 키워드가 존재한다 (별도 page protobuf-reserved-vs-json-openapi-extension.md 에서 부재 확인)
- Protobuf JSON Mapping 사용 시 자동으로 field name 재사용을 컴파일러가 차단한다는 사실 (proto3 컴파일러는 reserved 키워드 기준으로만 차단)
- Protobuf 의 enum 추가가 모든 클라이언트에서 안전하다는 사실 — 본 page 추출 범위 밖
- "int32 ↔ int64" 등 wire-호환 type 변경의 정확한 안전 조건 — 별도 섹션
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-tmpl 이 JSON 환경에서 Protobuf reserved 시맨틱을 OpenAPI x- extension 으로 흉내낼 때의 lint tool 선택 (raw/official-docs/protobuf-reserved-vs-json-openapi-extension 후속 결정)
- Protobuf 채택 시 외부 client 의 디코더 의존성 / 디버깅 비용
- REST → Protobuf 전환 시 OpenAPI 도구 체인 (Swagger UI, Postman) 의 호환성

메모 / Notes (내 프로젝트 해석)

본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.

Protobuf vs JSON (ca-tmpl) 차이:

측면	Protobuf	JSON (ca-tmpl)
식별자	field number (wire 영구)	field name (string)
unknown field	디코더가 자동 보존 (by default)	request fail-fast / response forbidden (ca-tmpl)
제거 후 재사용	reserved 로 차단 강제	OpenAPI 에 명시 안 하면 차단 안 됨
타입 변경	일부 wire-호환 변경 허용 (int32 ↔ int64 등)	breaking (ca-tmpl catalog)
enum 추가	안전	response 는 broken client 가능

ca-tmpl 이 JSON 에서 Protobuf 의 안전성을 흉내 내려면:
- 재사용 차단: removed field 이름을 OpenAPI 에서 x-reserved 같은 확장 또는 별도 catalog 로 강제. CI 에서 같은 이름 재사용을 막아야 함.
- enum 보존: ca-tmpl 이 채택한 "request unknown enum -> validation failure" 는 Protobuf 의 default 와 반대. 정합성을 위해 compatibility adapter 가 필수 (현재 결정 사항).
- field renaming: Protobuf 는 JSON 인코딩 사용 시 위험. ca-tmpl 결정 (rename 은 breaking, deprecate first) 과 일치.
Trade-off:
- Protobuf 채택: wire format 강제, IDL 기반 codegen, 자동 호환성. 단 디버깅·로그 가독성 ↓, 외부 노출 API 에는 부담.
- JSON 유지: 가독성·디버깅·외부 통합 용이. 단 ca-tmpl 처럼 OpenAPI diff + breaking change catalog + strict 정책을 모두 갖춰야 동급 안전성에 근접.
결론: ca-tmpl 이 JSON 기반이라면 Protobuf 의 reserved 개념 (이름·필드 재사용 차단) 을 OpenAPI 에 도입하는 것이 가장 큰 보강 포인트.

같은 주제 다른 official-doc:
- raw/official-docs/protobuf-reserved-vs-json-openapi-extension (Protobuf reserved 의 JSON 환경 흉내 보강)
- raw/official-docs/schema-avro-evolution-rules (Avro 측 동일 주제)
- raw/official-docs/schema-jackson-unknown-field-handling (Jackson 측 unknown field)
인용하는 branch:
- raw/branch-notes/feature-schema-serialization-contract (G-F 대안 2)
- raw/branch-notes/feature-api-compatibility-deprecation-contract
인용하는 wiki: (미작성)

9.4 KiB Raw Permalink Blame History