Protobuf 문법

목차

1. Syntax
2. Field types
3. Field Rules
4. Tag
5. Reserved Field
6. service(rpc)
7. style guide

 

Syntax

syntax = "proto3"; //proto3 버전 문법 사용

'syntax'는 버전을 정하는 구문이며 'proto2'와 'proto3'가 있다.

해당 내용이 없으면 'proto2'가 default값으로 적용되며 gRPC를 활용하려면 'proto3'를 사용해야 한다.

proto2는 후술할 필드 규칙이 필수값이나 proto3은 그렇지않은 등 문법이 차이가 일부 있으며

요즘엔 대부분 proto3을 사용하는 추세이므로 이후 설명은 proto3를 기준으로 한다.

 

Field types

message Foo {
  string name = 1; //문자열 필드.
  int32 age = 2; //정수형 필드.
}

double, float : 실수

int32, int64 : 음수에 비효율적

uint32, uint64 : unsigned int 같은 느낌일까요

sint32, sint64 : 부호있는 정수

fixed32, fixed64 : 항상 4, 8바이트. 값이 2^28, 2^56보다 크면 효율적

sfixed32, sfixed64 : 항상 4, 8바이트

bool : 부울

string : UTF-8 혹은 7bit ASCII 이여야 함

bytes : 임의의 바이트 배열 사용가능

 

위 변수들의 default값은 다음과 같다.

numeric : 0

bool : false

string : 빈 문자열

byte : 빈 문자열

 

 

Field rules

message Foo {
  required string name = 1; //반드시 필요한 필드. proto3에선 deprecate 되었다. 
  optional int32 age = 2; //없어도 되는 필드. proto3에선 deprecate 되었다.
  repeated string nationality = 3; //없어도 되고 많아도 되는 필드(비추천)
}

required : 이 필드를 반드시 1개 가진다.

optional : 이 필드를 가지지 않거나 1개 가진다.

repeated : 이 필드를 0개 이상 가진다.(연산이 비효율적이기에 잘 안쓴다고 함.)

proto3에선 required와 optional이 deprecate 되었다!

optional을 베이스로 하되 해당 값이 없을 시 default값을 넣어주는 식.

 

 

Tag

message Foo {
  string identity = 0; //ERROR!! 0번은 태그로 사용할 수 없다!
  string name = 1; //1번 태그 사용. 1바이트 인코딩이어서 효율이 좋다.
  int32 age = 16; //16번 태그 사용. 15번 이후로는 2바이트 인코딩이어서 효율이 낮다.
  string gender = 19500; //ERROR!! 19000~19999는 예약된 태그여서 사용할 수 없다!
  int32 height = 536870911; //태그 최대치인 2^29. 이보다 큰 값은 사용할 수 없다.
}

각 변수 내의 숫자는 초기화의 의미가 아닌 바이너리 형식의 필드를 구분하기 위해 사용하는 태그이다.

태그 값으로는 1부터 2^29까지 쓸 수 있으며 19000~19999는 protocol buffers 구현을 위해 사용하고 있기에 유저가 사용할 수 없다.

태그 값 중 1~15까지는 1바이트로 인코딩 하며 이후 숫자들은 2바이트 이상으로 인코딩하기에 1~15 태그는 자주 쓸 필드에 사용하는게 좋다.

인코딩 과정에서 필드 번호를 사용하기 때문에 생기는 차이점이며 애초에 protobuf는 작은 단위로 사용할 것을 권장하기에 큰 숫자의 태그는 지양하도록 하자.

 

 

Reserved field

message Foo {
  reserved 3, 9, 5 to 7;
  reserved "leo", "dabin";
}

기존 사용하던 필드를 중간에 제거(혹은 주석처리), 이후 다시 해당 필드를 재사용하게 되면 일관성 및 호환성에 장애를 초래한다.

그래서 위와 같이 미리 미리 예약해둔다는건데 리서치 추가 필요

 

 

service - rpc

service HelloService {
  rpc Hello (HelloRequest) returns (HelloResponse);
}

 

외에도

1. Enum
2. use other message type
3. import proto
4. inner message
5. extension
6. oneof
7. map
8. package

정도가 있으며 이후 추가 리서치하여 추가 작성하기

Style guides

Message 명은 CamelCase 사용하며(첫 문자 대문자) 필드 명으로는 snake_case로 작성

Enum 명은 CamelCase 사용하며(첫 문자 대문자) 열거 필드 명으로는 대문자로 SNAKE_CASE 작성

Service 명과 메서드 명은 CamelCase 사용(첫 문자 대문자)

위 3개 케이스에 대해 스타일이 전부 다른 악의적인 무언가가 느껴짐