GRPC 的功能、使用方式以及配套的生态工具
目录
说明
grpc 具备多种常用的功能，比如 Authentication、Flow Control 等等。
- grpc Guides：概要介绍了这些功能的用法
- grpc examples/features： 提供相关功能的使用代码。
配套的生态工具
grpc-ecosystem 中有多个和 grpc 相关的生态项目，比如：
- grpc-gateway：生成将 restful 接口代理到 grpc 服务接口的代码
- go-grpc-middleware：一些可复用的 grpc middleware
grpc-gateway：生成对应的 restful 接口
grpc-gateway 用于生成 restful 接口到 rpc 接口的转换代码。
标记 restful 接口和 rpc 接口之间的字段映射关系
用注解标记映射关系需要更改接口定义文件。如果不能修改接口定义文件，可以:
- 方法1：生成 generate_unbound_methods，uri 为 servername/methodname
- 方法2：用单独的一个文件描述 rest 接口和 rpc 接口之间的映射关系。
具体用法见：[gRPC API Configuration][13]。
如果使用注解标记，需要将下面的文件复制到本地项目 idl 目录的 google/api 中，就可以使用其中的 option google.api.http 进行标注。
google.api.http 支持参数都列在 google/api/http.proto 中的 HttpRule 结构体中，用途分别如下：
- selector
- pattern 指定使用的 http method，指定 rpc 接口参数和 uri 路径参数的映射关系
- body 指定映射到 http request body 的 rpc 参数
- response_body 指定映射到 http response body 的 rpc 响应参数
message HttpRule {
string selector = 1;
oneof pattern {
string get = 2;
string put = 3;
string post = 4;
string delete = 5;
string patch = 6;
CustomHttpPattern custom = 8;
}
string body = 7;
string response_body = 12;
repeated HttpRule additional_bindings = 11;
}
路径参数指定方式如下（example/library/v1/library.proto），定义了两个路径参数 schelves 和 books，其中 schelves 对应请求参数中的 name。Google 的 api 使用了这种风格的路径参数：google api。
rpc DeleteBook(DeleteBookRequest) returns (google.protobuf.Empty) {
option (google.api.http) = {
delete: "/v1/{name=shelves/*/books/*}"
};
option (google.api.method_signature) = "name";
}
http 接口代码生成
代码生成需要在 protoc-gen-go 和 protoc-gen-go-grpc 之外，再安装两个 protoc 插件：
go install \
github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway@latest \
github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2@latest \
然后用 protoc 生成代码：
protoc -I ./idl --grpc-gateway_out ./ \
--grpc-gateway_opt module=NAME \
./idl/NAME/v1beta/*.proto \
./idl/NAME/v1beta/*/*.proto
之后就可以引用生成的代码提供 rest 接口。
参考
- 李佶澳的博客
- grpc Guides
- grpc Metadata
- grpc examples/features
- grpc-ecosystem
- grpc-gateway
- google/api/http.proto
- google/api/annotations.proto
- example/library/v1/library.proto
- google api
- go-grpc-middleware
[12]: https://grpc-ecosystem.github.io/grpc-gateway/docs/mapping/grpc_api_configuration/ “” [13]: https://grpc-ecosystem.github.io/grpc-gateway/docs/mapping/grpc_api_configuration/ “gRPC API Configuration”
