Protocol Buffers (Protobuf) 가이드
Protobuf는 Google이 만든 언어 중립·플랫폼 중립 직렬화 포맷입니다. JSON보다 작고 빠르며, 스키마를 .proto 파일로 명시한 후 protoc 컴파일러로 각 언어의 코드를 자동 생성해 사용합니다. gRPC의 IDL로 사실상 표준이며, 카프카·Pub/Sub·CDN 로그 등에서도 폭넓게 쓰입니다.
proto3 핵심 문법
syntax = "proto3";: 항상 첫 줄에 명시.package myapp.v1;: 네임스페이스.go_package·java_package옵션으로 언어별 패키지를 추가 지정.message Person { string name = 1; int32 id = 2; }: 각 필드는 고유한 양의 정수 태그 번호를 가집니다. 1~15는 1바이트로 인코딩되므로 자주 쓰이는 필드에 우선 배정.repeated: 같은 타입의 리스트.optional: proto3에서 필드 존재 여부를 구분해야 할 때 사용.map<string, int32> counts = 5;: 키-값 맵.enum: 첫 번째 값은 반드시 0이어야 합니다(기본값).service Greeter { rpc Hello(HelloRequest) returns (HelloResponse); }: gRPC 서비스 정의. 스트리밍은stream키워드 사용.
필드 번호 규칙
한번 배포된 필드 번호는 절대 재사용하지 마세요. 필드를 삭제했다면 reserved 3, 5 또는 reserved "old_name"로 예약해 호환성을 보호합니다. 번호는 1~536,870,911 범위이고, 19000~19999는 Protobuf 내부 예약 번호입니다.
컴파일 명령
- Go:
protoc --go_out=. --go-grpc_out=. myapp.proto - Python:
protoc --python_out=. --grpc_python_out=. myapp.proto - TypeScript:
protoc --ts_out=. myapp.proto(ts-proto 플러그인)
자주 묻는 질문 (FAQ)
Q. proto2와 proto3 중 무엇을 쓰나요?
A. 신규 프로젝트는 proto3가 표준입니다. 필수 필드(required)가 사라지고 모든 필드는 옵셔널이 됩니다. 호환성을 위해 옛 시스템과 인터페이스해야 하면 proto2를 유지합니다.
Q. 필드 번호를 1부터 시작해야 하나요?
A. 0은 사용할 수 없습니다. 1부터 시작하며, 자주 사용하는 필드를 1~15에 배치해 와이어 크기를 줄이는 것이 좋습니다.
Q. gRPC가 아니어도 사용 가능?
A. 네. 단순 직렬화 포맷으로 Kafka 페이로드·파일 저장·HTTP 바디 등에서도 자유롭게 활용할 수 있습니다. 본 빌더의 service 섹션은 비워 둬도 됩니다.