1. Why choose gRPC
1.1. history
长久以来，我们在前后端交互时使用WebApi + JSON方式，后端服务之间调用同样如此（或者更久远之前的WCF + XML方式）。WebApi + JSON 是优选的，很重要的一点是它们两者都是平台无关的三方标准，且足够语义化，便于程序员使用，在异构（前后端、多语言后端）交互场景下是不二选择。然而，在后端服务体系改进特别是后来微服务兴起后，我们发现，前后端交互理所当然认可的 WebApi + JSON 在后端体系内显得有点不太合适：
- The JSON character encoding method allows a large amount of data to be transmitted, but the backend generally does not need to directly operate JSON, and will convert JSON into a platform-specific type before processing it; since conversion is needed, why not choose a format with smaller data volume and more convenient conversion?
- The calling parties must agree on the data structure and calling interface in advance, and the relevant code (Model class and method signature) must be manually updated if there is any change; can the agreement be solidified into a document, the service provider maintains the document, and the calling party can easily generate the code you need based on the document, and the code can be automatically updated when the document changes?
- [Previously] the Http[1.1] protocol on which WebApi is based has been around for more than 20 years, and the interaction model it defines is already stretched today; the industry needs a more efficient protocol.
1.2. Efficient transmission-Http2.0
我们先来说第 3 个问题，其实很多大厂内部早已开始着手处理，并诞生了一些应用广泛的框架，如阿里开源的Dubbo，直接抛弃了 Http 改为基于 Tcp 实现，效率得到明显提升，不过 Dubbo 依赖 Java 环境，无法跨平台使用，不在我们考虑范围。
另一个大厂 Google，内部也在长期使用自研的Stubby框架，与 Dubbo 不同的是，Studdy 是跨平台的，但是 Google 认为 Studdy 不基于任何标准，而且与其内部基础设施紧密耦合，并不适合公开发布。
At the same time, Google is also enhancing the Http1.1 protocol. This project is a SPDY solution proposed in 2012. It optimizes the Http protocol layer and adds new functions including multiplexing of data streams, request priority and HTTP header compression. Google said that after introducing the SPDY protocol, pages loaded 64% faster in laboratory tests than before. The huge improvement allowed everyone to start looking at and solving the problems of the old version of the Http protocol positively, which also directly accelerated the birth of Http2.0. In fact, Http2.0 was discussed and standardized based on SPDY, and of course, more improvements and adjustments have been made.
With the advent and popularity of Http2.0, many of the same features as Stubby have appeared in public standards, including other features not provided by Stubby. It's clear that it's time to redo Stubby to take advantage of this standardization and extend its applicability to the last mile of distributed computing, supporting mobile devices (such as Android), the Internet of Things (IoT), and browsers connecting to backend services.
2015 年 3 月，Google 决定在公开场合构建下一版 Stubby，以便与业界分享经验，并进行相关合作，也就是本文的主角gRPC。
1.3. Efficient coding-protobuf
回头来看第 1 个问题，解决起来相对比较简单，无非是将傻瓜式字符编码转为更有效的二进制编码（比如数字 10000 JSON 编码后是 5 个字节，按整型编码就是 4 个字节），同时加上些事先约定的编码算法使得最终结果更紧凑。常见的平台无关的编码格式有MessagePack和protobuf等，我们以 protobuf 为例。
protobuf 采用 varint 和 处理负数的 ZigZag 两种编码方式使得数值字段占用空间大大减少；同时它约定了字段类型和标识，采用 TLV 方式，将字段名映射为小范围结果集中的一项（比如对于不超过 256 个字段的数据体来说，不管字段名本身的长度多少，每个字段名都只要 1 个字节就能标识），同时移除了分隔符，并且可以过滤空字段（若字段没有被赋值，那么该字段不会出现在序列化结果中）。
1.4. Efficient Programming-Code Generation Tools
第 2 个问题呢，其实需要的就是[每个平台]一套代码生成工具。生成的代码需要覆盖类的定义、对象的序列化/反序列化、服务接口的暴露和远程调用等等必要的模板代码，如此，开发人员只需要负责接口文档的维护和业务代码的实现（很自然的面向接口编程：））。此时，采用 protobuf 的gRPC自然而然的映入眼帘，因为对于目前所有主要的编程语言和平台，都有 gRPC 工具和库，包括 .NET、Java、Python、Go、C++、Node.js、Swift、Dart、Ruby 以及 PHP。可以说，这些工具和库的提供，使得 gRPC 可以跨多种语言和平台一致地工作，成为一个全面的 RPC 解决方案。
2. Use of gRPC in. NET
ASP.NET Core 3.0 开始，支持gRPC作为 .NET 平台中的“一等公民”。
2.1. server
在 VS 中新建ASP.NET Core gRPC 服务，会发现在项目文件中自动引入了Microsoft.NET.Sdk.Web类库，很明显，gRPC 服务仍然是 Web 服务，毕竟它走的是 Http 协议。同时还引入了Grpc.AspNetCore类库，该类库引用了几个子类库需要了解下：
Google.Protobuf：包含 protobuf 预定义 message 类型在 C# 中的实现；Grpc.Tools：上面讲到的代码生成工具，编译时使用，运行时不需要，因此依赖项标记为 PrivateAssets="All"；Grpc.AspNetCore.Server：服务端专用；Grpc.Net.ClientFactory：客户端专用，如果只是提供服务的话，那么该类库可以移除。
Define interface files:
syntax = "proto3";
// 指定自动生成的类所在的命名空间，如果不指定则以下面的 package 为命名空间，这主要便于本项目内部的模块划分
option csharp_namespace = "Demo.Grpc";
// 对外提供服务的命名空间
package TestDemo;
// 服务
service Greeter {
// 接口
rpc SayHello (HelloRequest) returns (HelloReply);
}
// 不太好的一点是就算只有一个基础类型字段，也要新建一个 message 进行包装
message HelloRequest {
string name = 1;
}
message HelloReply {
string message = 1;
}
Then include it in the project file:
<ItemGroup>
<Protobuf Include="Protos\greeter.proto" GrpcServices="Server" />
</ItemGroup>
After compiling it, Grpc.Tools will help us generate the GreeterBase class and two model classes:
public abstract partial class GreeterBase
{
public virtual Task<HelloReply> SayHello(HelloRequest request, ServerCallContext context)
{
throw new RpcException(new Status(StatusCode.Unimplemented, ""));
}
}
public class HelloRequest
{
public string Name { get; set; }
}
public class HelloReply
{
public string Message { get; set; }
}
The SayHello here is an empty implementation. Let's create a new implementation class and fill in the business logic, such as:
public class GreeterService : GreeterBase
{
public override Task<HelloReply> SayHello(HelloRequest request, ServerCallContext context)
{
return Task.FromResult(new HelloReply { Message = $"Hello {request.Name}" });
}
}
Finally, add the service to the routing pipeline, exposing it to the outside world:
using Demo.Grpc.Services;
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
builder.Services.AddGrpc();
var app = builder.Build();
// Configure the HTTP request pipeline.
app.MapGrpcService<GreeterService>();
app.Run();
2.1.1. protobuf-net.Grpc
如果觉得写 .proto 文件太别扭，希望可以按传统方式写接口，那么社区项目protobuf-net.Grpc值得尝试，使用它可以它通过特性批注的 .NET 类型来定义应用的 gRPC 服务和消息。
First we no longer need to reference Grpc.AspNetCore, but instead reference the protobuf-net.Grpc library. Also, instead of writing a.proto file, write the interface class directly:
using ProtoBuf.Grpc;
using System.Runtime.Serialization;
using System.ServiceModel;
using System.Threading.Tasks;
namespace Demo.Grpc;
[DataContract]
public class HelloReply
{
[DataMember(Order = 1)]
public string Message { get; set; }
}
[DataContract]
public class HelloRequest
{
[DataMember(Order = 1)]
public string Name { get; set; }
}
[ServiceContract(Name = "TestDemo.GreeterService")]
public interface IGreeterService
{
[OperationContract]
Task<HelloReply> SayHelloAsync(HelloRequest request, CallContext context = default);
}
Note the modification of the character.
After writing the implementation class, you can register it in Program.cs, and I won't go into it here.
使用 protobuf-net.Grpc，我们不需要写 .proto 文件，但是调用方特别是其他平台的调用方，需要 .proto 文件来生成相应的客户端，难道我们还要另外再写一份吗？别急，我们可以引入protobuf-net.Grpc.AspNetCore.Reflection，它引用的protobuf-net.Grpc.Reflection提供了根据 C# 接口生成 .proto 文件的方法；同时使用它还便于客户端测试，同Grpc.AspNetCore.Server.Reflection的作用一样，下文会讲到。
2.1.2. exception handling
Net provides an interceptor mechanism for gRPC. You can create a new interceptor to handle business exceptions in a unified manner, such as:
public class GrpcGlobalExceptionInterceptor : Interceptor
{
private readonly ILogger<GrpcGlobalExceptionInterceptor> _logger;
public GrpcGlobalExceptionInterceptor(ILogger<GrpcGlobalExceptionInterceptor> logger)
{
_logger = logger;
}
public override async Task<TResponse> UnaryServerHandler<TRequest, TResponse>(
TRequest request,
ServerCallContext context,
UnaryServerMethod<TRequest, TResponse> continuation)
{
try
{
return await continuation(request, context);
}
catch (Exception ex)
{
_logger.LogError(new EventId(ex.HResult), ex, ex.Message);
// do something
// then you can choose throw the exception again
throw ex;
}
}
}
上述代码在处理完异常后重新抛出，旨在让客户端接收处理该异常，然而，实际上客户端是无法接收到该异常信息的，除非服务端抛出的是RpcException；同时，为使客户端得到正确的 HttpStatusCode（默认是 200，即使客户端得到是 RpcException），需要显式给HttpContext.Response.StatusCode赋值，如下：
// ...
catch(Exception ex)
{
var httpContext = context.GetHttpContext();
httpContext.Response.StatusCode = StatusCodes.Status400BadRequest;
// 注意，RpcException 的 StatusCode 和 Http 的 StatusCode 不是一一对应的
throw new RpcException(new Status(StatusCode.XXX, "some messages"));
}
// ...
我们可以在构造 RpcException 对象时传递Metadata，用于携带额外的数据到客户端，如果需要传递复杂对象，那么要先按约定序列化成字节数组。
After the interceptor logic is completed, the following settings need to be set during service injection:
builder.Services.AddGrpc(options =>
{
options.Interceptors.Add<GrpcGlobalExceptionInterceptor>();
});
2.1.3. test
服务端完成后，如果要借助Postman或者gRPCurl测试，那么它们其实就是调用服务的客户端，要让它们事先知道服务约定信息，有两种方法：
- Provide them with a.proto file. This is easy to understand. All information about the service is defined in the.proto file;
- The server exposes an interface that can obtain service information.
如果要用方法 2，那么要先引入Grpc.AspNetCore.Server.Reflection类库，然后在 Program.cs 中注册接口：
// ...
builder.Services.AddGrpcReflection();
var app = builder.Build();
// ...
IWebHostEnvironment env = app.Environment;
if (env.IsDevelopment())
{
app.MapGrpcReflectionService();
}
2.2. client
The client does not need Grpc.AspNetCore.Server, so we directly quote Google.Protobuf, Grpc.Tools, Grpc. Net.ClientFactory.
Add the.proto file provided by the server to the project, and include in the project file:
<ItemGroup>
<Protobuf Include="Protos\greeter.proto" GrpcServices="Client" />
</ItemGroup>
Note that if you only need some of the interfaces provided by the server, then only the necessary interfaces can be retained in the.proto file to truly obtain them on demand: ).
We can also change the field name of the message in the.proto file (as long as the field type and order are not changed) without affecting the service invocation. This also directly reflects that protobuf is not encoded by field names but by predefined field identifiers.
由此，假如我们有多个 .proto 文件，使用到了相同结构的 message，无所谓字段名是否相同，我们都可以将这些 message 抽离为单独的一个 .proto 文件，然后其他的 .proto 文件使用import "Protos/xxx.proto";引入它。
Compile it and register the service client in Program. cs:
// .proto 文件中的 package
using TestDemo;
// 这里注入的服务是 Transient 模式
builder.Services.AddGrpcClient<Greeter.GreeterClient>(o =>
{
o.Address = new Uri("https://localhost:5001");
});
In this way, you can happily use clients to invoke remote services elsewhere.
Just like the server, we can configure a unified interceptor for the client. If the server returns the RpcException mentioned above, and the client receives it and throws it directly (like a local exception), we can create a new exception interceptor to handle the RpcException exception.
builder.Services
.AddGrpcClient<Greeter.GreeterClient>(o =>
{
o.Address = new Uri("https://localhost:5001");
})
.AddInterceptor<ExceptionInterceptor>(); // 默认创建一次，并在 GreeterClient 实例之间共享
//.AddInterceptor<ExceptionInterceptor>(InterceptorScope.Client); // 每个 GreeterClient 实例拥有自己的拦截器
具体的异常处理逻辑就不举例了。提一下，通过 RpcException.Trailers 可以获取异常的 metadata 数据。
另外，对于异常处理来说，如果项目是普通的 ASP.NET Core Web 服务，那么使用原先的 ActionFilterAttribute、IExceptionFilter等拦截器也是一样的，因为既然运行时出现了异常，这两者肯定也能捕获到。
2.3. advanced knowledge
本文未涉及的 .NET-gRPC 的进阶知识诸如单元测试、服务调用中止、负载均衡、健康监控等，以后有机会再与大家分享。其实这方面微软官方文档已经讲解得相当全面了，但也难以覆盖在实操过程中遇到的所有问题，所以有此文以飨读者，还望不吝指教。
3. resources
This article comes from reprint.
Author: Leibniz
Original title: Introduction and Practical Operation of gRPC (. NET Chapter)
Original link: www.cnblogs.com/newton/archive/2023/01/10/17033789.html