gRPC的重要概念翻译

本篇是对于https://grpc.io/docs/quickstart/java.html文档的翻译。

This document introduces some key gRPC concepts with an overview of gRPC’s architecture and RPC life cycle.

这边文档从gprc的架构和生命周期介绍了一些关键的grpc的概念

It assumes that you’ve read What is gRPC?. For language-specific details, see the Quick Start, tutorial, and reference documentation for your chosen language(s), where available (complete reference docs are coming soon).

它假设你已经读了什么是gRPC这个文档，对于一些你选择的特定的语言的详细信息，请查看快速上手指南和参考文档

Overview（概要）

Service definition（服务定义）

Like 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. By default, gRPC uses protocol buffers as the Interface Definition Language (IDL) for describing both the service interface and the structure of the payload messages. It is possible to use other alternatives if desired.

像许多的RPC框架一样，gRPC是基于定义一个服务，指定能够携带参数和返回值进行远程调用的想法。gRPC默认使用ptotocol buffers来作为服务接口以及消息负载的IDL。

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

message HelloRequest {
  string greeting = 1;
}

message HelloResponse {
  string reply = 1;
}

gRPC lets you define four kinds of service method:

gRPC让你有有四种方式定义服务的方法：

• Unary RPCs where the client sends a single request to the server and gets a single response back, just like a normal function call.
• 单一RPC（客户端发送一个简单的请求给服务端，然后得到一个简单的响应，就像是普通的函数调用一样）
  

rpc SayHello(HelloRequest) returns (HelloResponse){
}

• Server streaming RPCs where the client sends a request to the server and gets a stream to read a sequence of messages back. The client reads from the returned stream until there are no more messages.
• 服务端流式RPC（客户端发送一个请求给服务端，然后获得一个流，从这个流中读取返回的消息序列，直到这个流中没有更多的消息为止）
  

rpc LotsOfReplies(HelloRequest) returns (stream HelloResponse){
}

• Client streaming RPCs where the client writes a sequence of messages and sends them to the server, again using a provided stream. Once the client has finished writing the messages, it waits for the server to read them and return its response.
• 客户端流式RPC(客户端写入一个消息的序列到一个流中，然后将他们发送到服务端，一旦客户端结束了对消息的写入，它就等待服务读取消息，并返回它的响应)
  

rpc LotsOfGreetings(stream HelloRequest) returns (HelloResponse) {
}

• Bidirectional streaming RPCs where both sides send a sequence of messages using a read-write stream. The two streams operate independently, so clients and servers can read and write in whatever order they like: for example, the server could wait to receive all the client messages before writing its responses, or it could alternately read a message then write a message, or some other combination of reads and writes. The order of messages in each stream is preserved.
• 双向流RPC(两边用一个读写流发送消息序列，这两个流式独立操作的，所以客户端和服务器能够在他们想要的时候读取和写入数据，例如，服务器在写入它的响应之前，能够等待接受所有的客户端消息。或者它能够交替的读取消息和写入消息，又或者同时进行读写。每个流中 的消息的顺序的呗保存的，用于保证消息不会紊乱)
  

rpc BidiHello(stream HelloRequest) returns (stream HelloResponse){
}

We’ll look at the different types of RPC in more detail in the RPC life cycle section below.

下面，我们来看一下每种RPC在生命周期中更加详细的信息

Using the API surface（使用API）

Starting from a service definition in a .proto file, gRPC provides protocol buffer compiler plugins that generate client- and server-side code. gRPC users typically call these APIs on the client side and implement the corresponding API on the server side.

从一个.proto文件中进行服务定义开始，gRPC提供了protocol buffer编译器插件来生成客户端和服务端的代码。gRPC的用户通常会在客户端调用这些API,在服务端实现跟客户端一致的API.

• On the server side, the server implements the methods declared by the service and runs a gRPC server to handle client calls. The gRPC infrastructure decodes incoming requests, executes service methods, and encodes service responses.
• 在服务器端，服务器实现了在service中声明的方法，然后运行一个gRPC的服务来处理客户端的调用。gRPC的基础设施会解码进来的请求，执行服务的方法，编码服务的响应
  
• On the client side, the client has a local object known as stub (for some languages, the preferred term is client) that implements the same methods as the service. The client can then just call those methods on the local object, wrapping the parameters for the call in the appropriate protocol buffer message type - gRPC looks after sending the request(s) to the server and returning the server’s protocol buffer response(s).
• 在客户端上，客户端有一个本地的对象叫做stub,这个stub在服务器上有对其中的方法的实现。客户端能够在本地stub上调用这些方法，并为这次调用使用合适的protocol buffer消息类型包装参数，在发送请求到服务器之后，返回服务器响应的ptotocol buffer响应
  

Synchronous vs. asynchronous（同步 vs 异步）

Synchronous RPC calls that block until a response arrives from the server are the closest approximation to the abstraction of a procedure call that RPC aspires to. On the other hand, networks are inherently asynchronous and in many scenarios it’s useful to be able to start RPCs without blocking the current thread.

同步RPC调用会造成阻塞，直到一个响应从服务器到达。这个近似于一个过程调用。在另一方面，网络是天生异步的，这个对于不适用阻塞当成线程的情况下启动RPC是非常有用的。

The gRPC programming surface in most languages comes in both synchronous and asynchronous flavors. You can find out more in each language’s tutorial and reference documentation (complete reference docs are coming soon).

大多数语言的gRPC编程在表面上都具有同步和异步两种特点，你能够在每种语言的导航和参考文档中找到。

RPC life cycle（PRC生命周期）

Now let’s take a closer look at what happens when a gRPC client calls a gRPC server method. We won’t look at implementation details, you can find out more about these in our language-specific pages.

现在让我们以一种更近的眼光去看一个gRPC客户端段调用一个gRPC服务端方法都发生了什么样的事情，我们不去看实现的细节，你可以在我们的特定的语言页中找到有关于这些的信息

Unary RPC（单一RPC）

First let’s look at the simplest type of RPC, where the client sends a single request and gets back a single response.

首先让我们看一下这个最简单的RPC类型，客户端发送一个简单的请求，然后得到一个简单的响应。

• Once the client calls the method on the stub/client object, the server is notified that the RPC has been invoked with the client’s metadata for this call, the method name, and the specified deadline if applicable.
• 一旦客户端调用了在stub对象的方法的时候，服务端就会收到RPC调用的通知，这个通知里包含的这次调用的元数据，方法名称，以及制定的deadline。
  
• The server can then either send back its own initial metadata (which must be sent before any response) straight away, or wait for the client’s request message - which happens first is application-specific.
• 然后服务器要么立刻发送他自己的原数据，要么等待客户端的消息（这个发生在特定的应用程序中）
  
• Once the server has the client’s request message, it does whatever work is necessary to create and populate its response. The response is then returned (if successful) to the client together with status details (status code and optional status message) and optional trailing metadata.
• 一旦服务器收到了客户端的请求消息，它就会做一些必要的工作来创建和构成它的响应。这个响应会带着状态信息和可选的元数据信息一起返回给客户端
  
• If the status is OK, the client then gets the response, which completes the call on the client side.
• 如果这个状态是ok的话，客户端会得到响应，在客户端完成此次调用。
  

Server streaming RPC（服务端流RPC）

A server-streaming RPC is similar to our simple example, except the server sends back a stream of responses after getting the client’s request message. After sending back all its responses, the server’s status details (status code and optional status message) and optional trailing metadata are sent back to complete on the server side. The client completes once it has all the server’s responses.

服务端流式RPC跟我们那个简单的例子很相近，除了服务器在得到客户端的请求消息之后发送回响应的流不同以外。在返回所有的它的响应之后，服务器的状态详情和其他元数据也会被服务端发送回去，客户端一旦全部接受了服务端的响应之后，这个调用就完成了。

Client streaming RPC（客户端流式RPC）

A client-streaming RPC is also similar to our simple example, except the client sends a stream of requests to the server instead of a single request. The server sends back a single response, typically but not necessarily after it has received all the client’s requests, along with its status details and optional trailing metadata.

客户端流式RPC同样也很之前的简单范例一样，除了客户端发送一个请求的流到服务端，而不是一个简单的请求。在服务器接受完客户端所有的请求消息之后，服务端通常会发送回一个简单的响应，而且也会把他的状态详情和元数据信息一并带上。

Bidirectional streaming RPC（双向流式RPC）

In a bidirectional streaming RPC, again the call is initiated by the client calling the method and the server receiving the client metadata, method name, and deadline. Again the server can choose to send back its initial metadata or wait for the client to start sending requests.

在一个双向流式RPC中，这个调用还是客户端调用方法，服务器接收客户端的元数据，方法名称，deadline,服务端能够自由选择是发送它的元数据返回回去，还是接着等待客户端发起发送请求。

What happens next depends on the application, as the client and server can read and write in any order - the streams operate completely independently. So, for example, the server could wait until it has received all the client’s messages before writing its responses, or the server and client could “ping-pong”: the server gets a request, then sends back a response, then the client sends another request based on the response, and so on.

接下来发生什么完全取决于应用程序，客户端和服务端能够进行任意的读写，对流的操作完全独立。举个例子，服务端在写它的响应之前能够一直等待，直到他接受完这个客户端所有消息，或者服务端和客户端能够来回交互：服务端得到一个请求，然后发送回一个响应，然后客户端基于刚才的响应又发送另外一个请求，以此类推。

Deadlines/Timeouts

gRPC allows clients to specify how long they are willing to wait for an RPC to complete before the RPC is terminated with the error DEADLINE_EXCEEDED. On the server side, the server can query to see if a particular RPC has timed out, or how much time is left to complete the RPC.

gRpc允许客户端指定他们等待一个RPC完成的时间长度，在RPC调用完成之前。在服务端方面，服务端能够查询到某一个RPC调用是否已经超时了，或者还需要多少时间来完成这个rpc调用。

How the deadline or timeout is specified varies from language to language - for example, not all languages have a default deadline, some language APIs work in terms of a deadline (a fixed point in time), and some language APIs work in terms of timeouts (durations of time).

这个deadline或者是timeout对于各个语言的表达是不一样的。

RPC termination

In gRPC, both the client and server make independent and local determinations of the success of the call, and their conclusions may not match. This means that, for example, you could have an RPC that finishes successfully on the server side (“I have sent all my responses!”) but fails on the client side (“The responses arrived after my deadline!”). It’s also possible for a server to decide to complete before a client has sent all its requests.

在gRPC中，客户端和服务端对一次成功的调用完成有自己理解，他们的结论是不匹配的。举个例子，你在服务器成功的完成了一个RPC的返回（服务器返回了所有的响应），但是对于客户端来说是失败的，因为这个响应在我的deadline之后才到达的。在一个客户端已经发送了它的所有的请求之前，服务器也有可能结束了这次rpc调用。

Cancelling RPCs（取消RPC）

Either the client or the server can cancel an RPC at any time. A cancellation terminates the RPC immediately so that no further work is done. It is not an “undo”: changes made before the cancellation will not be rolled back.

不管是客户端或者是服务端都能够取消rpc调用，不管在什么时候。一个取消的信号发出后，rpc会立马停止调用，未来的工作也会停止。他不是“undo”:在取消之前发生变化不能够被回滚。

Metadata（元数据）

Metadata is information about a particular RPC call (such as authentication details) in the form of a list of key-value pairs, where the keys are strings and the values are typically strings (but can be binary data). Metadata is opaque to gRPC itself - it lets the client provide information associated with the call to the server and vice versa.

元数据是对于某一个RPC调用的相关信息，例如授权详细等，他是放置在一个存放key-value对的列表的表单，这个key-value对的key是字符串，value通常也是字符串，但是也可以是二进制数据。元数据对于gRPC自身是不透明的，他让客户端提供此次调用相关的信息给服务端，反之亦然。

Access to metadata is language-dependent.

对于元数据的访问时语言无关的。

Channels

A gRPC channel provides a connection to a gRPC server on a specified host and port and is used when creating a client stub (or just “client” in some languages). Clients can specify channel arguments to modify gRPC’s default behaviour, such as switching on and off message compression. A channel has state, including connected and idle.

一个gRPC通道提供了一个对于gRPC服务器的连接，这个服务器有特定的主机地址和端口，他在创建客户端stub的时候被创建。客户端能够指定通道的参数来修改gRPC的默认行为，比如切换消息压缩的开关。每一个通道都有状态，比如connected(已连接)和idle(闲置)

How gRPC deals with closing down channels is language-dependent. Some languages also permit querying channel state.