Struktur file

gRPC API harus ditentukan dalam file .proto menggunakan IDL proto3.

Struktur file harus menempatkan definisi tingkat yang lebih tinggi dan lebih penting sebelum item tingkat yang lebih rendah dan yang kurang penting. Di setiap file proto, bagian yang berlaku harus dalam urutan berikut:

  • Pemberitahuan hak cipta dan lisensi jika diperlukan.
  • Proto pernyataan syntax, package, import, dan option dalam urutan tersebut.
  • Dokumentasi ringkasan API yang mempersiapkan pembaca untuk sisa file.
  • Definisi service proto API, untuk mengurangi urutan nilai penting.
  • Definisi message permintaan dan respons RPC, dalam urutan metode terkait yang sama. Setiap pesan permintaan harus mendahului pesan respons yang sesuai, jika ada.
  • Definisi message resource. Resource induk harus ditentukan sebelum resource turunannya.

Jika satu file proto berisi seluruh platform API, nama tersebut harus diberi nama berdasarkan API:

API Proto
Library library.proto
Calendar calendar.proto

File .proto berukuran besar dapat dibagi menjadi beberapa file. Layanan, pesan resource, dan pesan permintaan/respons harus dipindahkan ke file terpisah sesuai kebutuhan.

Kami merekomendasikan satu file per layanan dengan permintaan dan respons yang sesuai. Sebaiknya beri nama file ini <enclosed service name>.proto. Untuk file proto dengan resource saja, sebaiknya beri nama file ini sebagai resources.proto.

Nama File Proto

Nama file proto harus menggunakan huruf kecil_case_underscore_separated_name dan harus menggunakan ekstensi .proto. Contoh: service_controller.proto.

Opsi Proto

Untuk menghasilkan library klien yang konsisten di berbagai API, developer API harus menggunakan opsi proto yang konsisten dalam file .proto. Definisi API yang sesuai dengan panduan ini harus menggunakan opsi proto level file berikut:

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";
Sebelumnya
Struktur direktori
Berikutnya
Glosarium