gRPC简介

Introduction to gRPC

gRPC简介

An introduction to gRPC and protocol buffers.

gRPC和协议缓冲区简介。

This page introduces you to gRPC and protocol buffers. gRPC can use protocol buffers as both its Interface Definition Language (IDL) and as its underlying message interchange format. If you’re new to gRPC and/or protocol buffers, read this! If you just want to dive in and see gRPC in action first, select a language and try its Quick start.

​本页介绍gRPC和协议缓冲区。gRPC可以使用协议缓冲区作为其接口定义语言（IDL）和底层消息交换格式。如果是gRPC和/或协议缓冲区的新手，请阅读本文！如果只想深入了解gRPC的实际操作，请选择一种语言并尝试其快速入门。

Overview

概述

In gRPC, a client application can directly call a method on a server application on a different machine as if it were a local object, making it easier for you to create distributed applications and services. As in many RPC systems, gRPC is based around the idea of defining a service, specifying the methods that can be called remotely with their parameters and return types. On the server side, the server implements this interface and runs a gRPC server to handle client calls. On the client side, the client has a stub (referred to as just a client in some languages) that provides the same methods as the server.

在gRPC中， 客户端应用程序可以直接调用另一台计算机上服务器应用程序上的方法，就好像它是本地对象一样，这样可以更容易地创建分布式应用程序和服务。与许多RPC系统一样，gRPC基于定义服务的思想，指定可以通过其参数和返回类型远程调用的方法。在服务器端，服务器实现了这个接口，并运行一个gRPC服务器来处理客户端调用。在客户端，客户端有一个存根（在某些语言中称为客户端），它提供与服务器相同的方法。

 

gRPC clients and servers can run and talk to each other in a variety of environments - from servers inside Google to your own desktop - and can be written in any of gRPC’s supported languages. So, for example, you can easily create a gRPC server in Java with clients in Go, Python, or Ruby. In addition, the latest Google APIs will have gRPC versions of their interfaces, letting you easily build Google functionality into your applications.

gRPC客户端和服务器可以在各种环境中运行并相互通信，从谷歌内部的服务器到自己的桌面，并且可以用gRPC支持的任何语言编写。因此，例如，可以使用Go、Python或Ruby中的客户端轻松地用Java创建gRPC服务器。此外，最新的谷歌API将有gRPC版本的接口，可以轻松地将谷歌功能构建到应用程序中。

Working with Protocol Buffers

使用协议缓冲区

By default, gRPC uses Protocol Buffers, Google’s mature open source mechanism for serializing structured data (although it can be used with other data formats such as JSON). Here’s a quick intro to how it works. If you’re already familiar with protocol buffers, feel free to skip ahead to the next section.

​默认情况下，gRPC使用Protocol Buffers，这是谷歌成熟的开源机制，用于序列化结构化数据（尽管它可以与JSON等其他数据格式一起使用）。下面简单介绍一下它的工作原理。如果您已经熟悉协议缓冲区，请随时跳到下一节。

The first step when working with protocol buffers is to define the structure for the data you want to serialize in a proto file: this is an ordinary text file with a .proto extension. Protocol buffer data is structured as messages, where each message is a small logical record of information containing a series of name-value pairs called fields. Here’s a simple example:

使用协议缓冲区时的第一步是定义要在proto文件中序列化的数据的结构：这是一个扩展名为.proto的普通文本文件。协议缓冲区数据的结构是消息，其中每个消息都是包含一系列名值对（称为字段）的信息的小逻辑记录。下面是一个简单的例子：

message Person {
  string name = 1;
  int32 id = 2;
  bool has_ponycopter = 3;
}

Then, once you’ve specified your data structures, you use the protocol buffer compiler protoc to generate data access classes in your preferred language(s) from your proto definition. These provide simple accessors for each field, like name() and set_name(), as well as methods to serialize/parse the whole structure to/from raw bytes. So, for instance, if your chosen language is C++, running the compiler on the example above will generate a class called Person. You can then use this class in your application to populate, serialize, and retrieve Person protocol buffer messages.

然后，一旦指定了数据结构，就可以使用协议缓冲区编译器proto根据proto定义以首选语言生成数据访问类。它们为每个字段提供了简单的访问器，如name（）和set_name（），以及将整个结构序列化到原始字节/从原始字节解析整个结构的方法。因此，例如，如果选择的语言是C++，那么在上面的示例中运行编译器将生成一个名为Person的类。然后，可以在应用程序中使用此类来填充、序列化和检索Person协议缓冲区消息。

You define gRPC services in ordinary proto files, with RPC method parameters and return types specified as protocol buffer messages:

可以在普通的proto文件中定义gRPC服务，RPC方法参数和返回类型被指定为协议缓冲区消息：

// The greeter service definition.
service Greeter {
  // Sends a greeting
  rpc SayHello (HelloRequest) returns (HelloReply) {}
}

// The request message containing the user's name.
message HelloRequest {
  string name = 1;
}

// The response message containing the greetings
message HelloReply {
  string message = 1;
}

gRPC uses protoc with a special gRPC plugin to generate code from your proto file: you get generated gRPC client and server code, as well as the regular protocol buffer code for populating, serializing, and retrieving your message types. To learn more about protocol buffers, including how to install protoc with the gRPC plugin in your chosen language, see the protocol buffers documentation.

​gRPC使用protoc和一个特殊的gRPC插件从proto文件生成代码：可以获得生成的gRPC客户端和服务器代码，以及用于填充、序列化和检索消息类型的常规协议缓冲区代码。要了解有关协议缓冲区的更多信息，包括如何用选择的语言使用gRPC插件安装protoc，请参阅协议缓冲区文档。

Protocol buffer versions

协议缓冲区版本

While protocol buffers have been available to open source users for some time, most examples from this site use protocol buffers version 3 (proto3), which has a slightly simplified syntax, some useful new features, and supports more languages. Proto3 is currently available in Java, C++, Dart, Python, Objective-C, C#, a lite-runtime (Android Java), Ruby, and JavaScript from the protocol buffers GitHub repo, as well as a Go language generator from the golang/protobuf official package, with more languages in development. You can find out more in the proto3 language guide and the reference documentation available for each language. The reference documentation also includes a formal specification for the .proto file format.

​虽然协议缓冲区已经为开源用户提供了一段时间，但该网站的大多数示例都使用协议缓冲区版本3（proto3），该版本具有略微简化的语法、一些有用的新功能，并支持更多的语言。Proto3目前有Java、C++、Dart、Python、Objective-C、C#、lite运行时（Android Java）、Ruby和协议缓冲区GitHub repo中的JavaScript，以及golang/protobuf官方包中的Go语言生成器，还有更多语言正在开发中。可以在proto3语言指南和每种语言的参考文档中找到更多信息。参考文档还包括.proto文件格式的正式规范。

In general, while you can use proto2 (the current default protocol buffers version), we recommend that you use proto3 with gRPC as it lets you use the full range of gRPC-supported languages, as well as avoiding compatibility issues with proto2 clients talking to proto3 servers and vice versa.

一般来说，虽然可以使用proto2（当前默认的协议缓冲区版本），但我们建议您将proto3与gRPC一起使用，因为它可以使用所有受gRPC支持的语言，并避免proto2客户端与proto3服务器通信的兼容性问题，反之亦然。

Last modified February 16, 2023: Update Protocol Buffers documentation URL (#1092) (852a744)