파일 구조

gRPC API는 .proto 파일에서 proto3 IDL을 통해 정의되어야 합니다.

파일 구조에서는 더욱 중요한 상위 수준의 정의가 비교적 중요하지 않은 하위 수준의 항목 앞에 위치해야 합니다. 각 proto 파일에서 적용 가능한 섹션은 다음과 같은 순서를 따라야 합니다.

필요한 경우 저작권 및 라이선스 고지
Proto syntax, package, import, option 문(순서대로)
개발자가 파일의 나머지를 준비할 수 있는 API 개요 문서
API proto service 정의(중요도에 따른 내림차순으로)
RPC 요청 및 응답 message 정의(해당 메서드의 동일한 순서). 각 요청 메시지는 해당하는 응답 메시지(있는 경우)보다 선행해야 합니다.
리소스 message 정의. 상위 리소스는 하위 리소스보다 먼저 정의되어야 합니다.

proto 파일 하나에 API 표면 전체가 포함되어 있는 경우에는 다음과 같이 API를 따라 파일 이름을 지정해야 합니다.

API	Proto
`Library`	`library.proto`
`Calendar`	`calendar.proto`

.proto 파일이 대용량이면 여러 파일로 분할할 수 있습니다. 서비스와 리소스 메시지, 그리고 요청/응답 메시지는 필요에 따라 개별 파일로 옮겨야 합니다.

해당하는 요청 및 응답은 서비스마다 파일 1개에 포함시키는 것이 좋습니다. 이 파일의 이름을 <enclosed service name>.proto으로 지정해 보세요. proto 파일에 리소스만 포함된 경우에는 이 파일의 이름을 단순히 resources.proto로 지정해도 좋습니다.

Proto 파일 이름

proto 파일 이름에서는 lower_case_underscore_separated_names를 사용해야 하며 동시에 확장자로 .proto를 사용해야 합니다. 예를 들면 service_controller.proto입니다.

Proto 옵션

API 개발자가 여러 API에 클라이언트 라이브러리를 일관되게 생성하려면 .proto 파일에서 일관된 proto 옵션을 사용해야 합니다. 이러한 가이드를 준수하는 API 정의는 다음과 같은 파일 수준의 proto 옵션을 사용해야 합니다.

syntax = "proto3";

// The package name should start with the company name and end with
// the major version.
package google.abc.xyz.v1;

// This option specifies the namespace to be used in C# code. This defaults
// to the PascalCased version of the proto package, which is fine if the
// package name consists of single-word segments.
// For example, a package name of "google.shopping.pets.v1" would use a C#
// namespace of "Google.Shopping.Pets.V1".
// However, if any segment of a package name consists of multiple words,
// this option needs to be specified to avoid only the first word being
// capitalized. For example, a Google Pet Store API might have a package name of
// "google.shopping.petstore.v1", which would mean a C# namespace of
// "Google.Shopping.Petstore.V1". Instead, the option should be used to
// capitalize it properly as "Google.Shopping.PetStore.V1".
//
// For more detail on C#/.NET capitalization rules, see the [Framework Design
// Guidelines](https://msdn.microsoft.com/en-us/library/ms229043).
//
// One corner-case of capitalization: while acronyms are generally
// PascalCased (e.g. Http), two-letter acronyms are normally all in capitals,
// e.g. `IOStream` and `OSVersion`, not `IoStream` and `OsVersion`. However,
// in APIs this should be used carefully, as protoc doesn't know which words
// are abbreviations and which aren't: it would introduce inconsistency to have
// a namespace of (say) `OSLogin` but then a class called `OsDetails` generated
// from a message of the same name. Unless you can be certain that the acronym
// won't crop up in a message or field name, it's safest to stick to regular
// PascalCase.
//
// For pre-releases, the Alpha/Beta should also be capitalized, so "V1Beta1"
// rather than "V1beta1" for example.
option csharp_namespace = "Google.Abc.Xyz.V1";

// This option lets the proto compiler generate Java code inside the package
// name (see below) instead of inside an outer class. It creates a simpler
// developer experience by reducing one-level of name nesting and be
// consistent with most programming languages that don't support outer classes.
option java_multiple_files = true;

// The Java outer classname should be the filename in UpperCamelCase. This
// class is only used to hold proto descriptor, so developers don't need to
// work with it directly.
option java_outer_classname = "XyzProto";

// The Java package name must be proto package name with proper prefix.
option java_package = "com.google.abc.xyz.v1";

// A reasonable prefix for the Objective-C symbols generated from the package.
// It should at a minimum be 3 characters long, all uppercase, and convention
// is to use an abbreviation of the package name. Something short, but
// hopefully unique enough to not conflict with things that may come along in
// the future. 'GPB' is reserved for the protocol buffer implementation itself.
option objc_class_prefix = "GABCX";

// This option specifies the namespace to be used in PHP code. This defaults
// to the PascalCased version of the proto package, which is fine if the
// package name consists of single-word segments.
// For example, a package name of "google.shopping.pets.v1" would use a PHP
// namespace of "Google\\Shopping\\Pets\\V1".
// However, if any segment of a package name consists of multiple words,
// this option needs to be specified to avoid only the first word being
// capitalized. For example, a Google Pet Store API might have a package name of
// "google.shopping.petstore.v1", which would mean a PHP namespace of
// "Google\\Shopping\\Petstore\\V1". Instead, the option should be used to
// capitalize it properly as "Google\\Shopping\\PetStore\\V1".
//
// For pre-releases, the Alpha/Beta should not be capitalized, so "V1beta1"
// rather than "V1Beta1" for example. Note that this is different from the
// capitalization used in the csharp_namespace option for pre-releases.
option php_namespace = "Google\\Abc\\Xyz\\V1";

디렉터리 구조

용어