Hyperf 中的 gRPC 服务端与客户端实战:从 .proto 定义到双向流调用
Hyperf 中的 gRPC 服务端与客户端实战:从 .proto 定义到双向流调用
gRPC 是微服务架构中广泛使用的高性能 RPC 框架,但官方 PHP quickstart 教程往往只停留在“跑通一个 Demo”,距离可落地的整套 RPC 服务还有不小差距。本文以 Hyperf 协程框架对 gRPC 的封装为基础,按照 hyperf-skeleton 项目的完整步骤,讲解从 .proto 文件定义、protoc 代码生成,到 gRPC Server 与 gRPC Client 的配置、路由、控制器实现,再到 Streaming 流式调用与底层编解码原理的完整链路。读完本文,你将能够在 Hyperf 中独立搭建一套可复用的 gRPC 服务,并理解其底层处理机制。
为什么选择 Hyperf 搭建 gRPC 服务
gRPC 官方文档中的 quickstart - php 很容易给 PHPer 产生误导:按照官网文档,即便只是把 gRPC 服务“运行起来”就非常麻烦,更不用说搭建整套 RPC 服务。而 Hyperf 对 gRPC 支持做了更进一步的封装,借助协程与 Swoole HTTP2 的能力,让 PHPer 可以用接近普通 HTTP 服务的开发体验来编写 gRPC 接口。
在 Hyperf 中接入 gRPC 主要包含三个环节,本文后续将逐一展开:
.proto文件定义以及相关配置实例- gRPC Server 示例(服务端接收并处理请求)
- gRPC Client 示例(客户端发起调用,含 Streaming 模式)
定义 .proto 文件并生成 PHP 代码
编写 grpc.proto
首先在项目中定义好 proto 文件 grpc.proto,这里定义一个最简单的 Hi 服务,包含一个一元方法 SayHello,以及两个消息类型 HiUser 与 HiReply:
syntax = "proto3";
package grpc;
service Hi {
rpc SayHello (HiUser) returns (HiReply) {
}
}
message HiUser {
string name = 1;
int32 sex = 2;
}
message HiReply {
string message = 1;
HiUser user = 2;
}
需要注意的是 package grpc; 这一行——它决定了后续 gRPC 路由路径与生成代码命名空间的基础(详见下文“路由与 .proto 的对应关系”)。
使用 protoc 生成示例代码
生成 PHP 代码需要安装 protoc。可以使用 Linux 包管理工具安装,下面以 alpine 为例(也可以参考 hyperf-skeleton 项目下的 Dockerfile 安装方式):
# 使用 linux 包管理工具安装 protoc,下面以 alpine 为例
apk add protobuf
# 使用 protoc 自动生成代码
protoc --php_out=grpc/ grpc.proto
执行完成后,grpc/ 目录下会生成如下结构:
grpc
├── GPBMetadata
│ └── Grpc.php
└── Grpc
├── HiReply.php
└── HiUser.php
其中 Grpc/HiUser.php、Grpc/HiReply.php 即根据消息定义生成的数据类,二者都继承自 Google\Protobuf\Internal\Message(这是后续服务端参数注入与编解码判断的关键,见下文源码分析)。
配置 composer.json 自动加载
为了让 grpc/ 目录下的生成代码可以被自动加载,需要在 composer.json 中增加 psr-4 配置。如果 proto 文件中使用了不同的 package 设置,或者将代码生成到了不同目录,做相应调整即可:
"autoload": {
"psr-4": {
"App\\": "app/",
"GPBMetadata\\": "grpc/GPBMetadata",
"Grpc\\": "grpc/Grpc"
},
"files": [
]
},
配置完成并保存后,执行 composer dump-autoload 使自动加载生效。
gRPC Server:安装、配置、路由与控制器
安装组件
composer require hyperf/grpc-server
从本仓库源码看,hyperf/grpc-server 的 Server 类继承自 Hyperf\HttpServer\Server(见 Server.php),并在 initCoreMiddleware() 中注入专门的 CoreMiddleware 与默认的 GrpcExceptionHandler 异常处理器(见 Server.php),因此 gRPC 服务本质上是在 HTTP Server 之上做协议层适配。
server.php 服务配置
gRPC 服务与普通 HTTP 服务可以共存于同一进程,通过多端口配置区分。在 server.php 中(参考 配置)新增一个 grpc 服务端口:
'servers' => [
....
[
'name' => 'grpc',
'type' => Server::SERVER_HTTP,
'host' => '0.0.0.0',
'port' => 9503,
'sock_type' => SWOOLE_SOCK_TCP,
'callbacks' => [
Event::ON_REQUEST => [\Hyperf\GrpcServer\Server::class, 'onRequest'],
],
],
],
关键点说明:
type使用Server::SERVER_HTTP:gRPC 基于 HTTP/2,Hyperf 通过 HTTP 服务端口承载 gRPC 请求;callbacks中的onRequest必须指向\Hyperf\GrpcServer\Server::class,而不是默认的 HTTP Server,这是请求进入 gRPC 处理链路的前提;- 端口(如
9503)可自定义,客户端连接地址需与之对应。
routes.php 路由配置
gRPC 路由需要绑定到指定服务器。在 routes.php 中(参考 路由)使用 Router::addServer('grpc', ...) 声明属于 grpc 服务器的路由组:
Router::addServer('grpc', function () {
Router::addGroup('/grpc.Hi', function () {
Router::post('/SayHello', 'App\Controller\HiController@sayHello');
});
});
控制器实现
HiController.php 中的 sayHello 方法直接接收 proto 生成的消息对象 HiUser,返回 HiReply 消息对象即可:
public function sayHello(HiUser $user)
{
$message = new HiReply();
$message->setMessage("Hello World");
$message->setUser($user);
return $message;
}
路由与 .proto 的对应关系
.proto 文件中的定义和 gRPC server 路由的对应关系是:/{package}.{service}/{rpc}。
以上述配置为例:package 为 grpc、service 为 Hi、rpc 方法为 SayHello,因此完整路径为 /grpc.Hi/SayHello,路由组的 /grpc.Hi 与 post('/SayHello') 恰好拼出该路径。
这一点在源码中也有印证:src/grpc/src/PathGenerator.php 的 generate() 方法(见 PathGenerator.php)通过将服务类名末段的 Service 后缀去掉,拼出 /grpc.{service}/{method} 形式的路由路径。
服务端原理:gRPC 请求如何被解析与响应
如果想要更深入一层,可以阅读 gRPC server 是如何处理 gRPC 请求的。核心实现位于 vendor/hyperf/grpc-server/src/CoreMiddleware.php(本仓库对应 CoreMiddleware.php)。
请求分发:process()
\Hyperf\GrpcServer\CoreMiddleware::process()(见 CoreMiddleware.php)的执行流程如下:
- 从请求中取出路由分发结果
Dispatched; - 根据分发状态处理:
FOUND时解析控制器与方法的参数并调用;路由不存在时返回NOT_FOUND状态的 gRPC 响应; - 若返回结果不是
Message实例(即不是 proto 生成的消息对象),则返回INTERNAL错误,提示The result is not a valid message.。
参数注入与反序列化
在 parseMethodParameters()(见 CoreMiddleware.php)中,Hyperf 通过 MethodDefinitionCollector 反射方法签名:如果参数类型继承自 ProtobufMessage,则从请求体读取流数据,并调用封装好的 gRPC 编解码类 \Hyperf\Grpc\Parser::deserializeMessage 将二进制数据还原为对应的 proto 消息对象——这就是控制器方法中可以直接拿到 HiUser $user 的原因。
Parser 的编解码实现位于 Parser.php,其中:
pack()按 gRPC wire 协议在消息体前加上 1 字节压缩标志 + 4 字节长度(见 Parser.php);unpack()反向去掉这 5 字节头取出原始数据(见 Parser.php);serializeMessage()/deserializeMessage()完成消息对象与二进制流的互转(见 Parser.php)。
响应组装
关于 gRPC server 如何进行 gRPC 响应,可以从 CoreMiddleware 的 handleResponse() 与 transferToResponse()(见 CoreMiddleware.php)中发现规律:响应头会设置 Content-Type: application/grpc,并声明 trailer 字段 grpc-status, grpc-message,最后通过 withTrailer() 写入 gRPC 状态码与错误消息——这正是 gRPC 协议要求通过 HTTP/2 trailer 传递最终状态的标准做法。也就是说,gRPC 响应 = 标准 HTTP 响应体(序列化后的 proto 消息)+ trailer 中携带的状态信息。
gRPC Client:一元调用(Unary)
安装组件
composer require hyperf/grpc-client
基于 BaseClient 扩展客户端类
Hyperf 已经封装好了 \Hyperf\GrpcClient\BaseClient,只要根据 .proto 文件中的定义,按需扩展即可。例如为 Hi 服务编写 HiClient:
class HiClient extends BaseClient
{
public function sayHello(HiUser $argument)
{
return $this->_simpleRequest(
'/grpc.Hi/SayHello',
$argument,
[HiReply::class, 'decode']
);
}
}
这里的关键是 _simpleRequest 的三个参数:
- 第一个参数是 gRPC 方法路径
/{package}.{service}/{rpc},必须与服务端路由、.proto定义严格一致; - 第二个参数是请求消息对象
HiUser; - 第三个参数
[HiReply::class, 'decode']是响应消息的反序列化描述,用于将返回的二进制解析为HiReply对象。
从源码看,_simpleRequest() 定义于 BaseClient.php,它内部通过 retry() 发送请求并返回一个 UnaryCall 对象;而 UnaryCall::wait() 负责等待响应,通过 Parser 解析出 <a href="https://link.gitcode.com/i/7f7bad2b786e5451c7c418b75d1f93c1" target="_blank">$message, $status] 二元组(见 [UnaryCall.php)。
在控制器中调用
示例代码可以在 GrpcController 中找到。完整的调用流程如下:
public function hello()
{
// 这个 client 是协程安全的,可以复用
$client = new \App\Grpc\HiClient('127.0.0.1:9503', [
'credentials' => null,
]);
$request = new \Grpc\HiUser();
$request->setName('hyperf');
$request->setSex(1);
/**
* @var \Grpc\HiReply $reply
*/
list($reply, $status) = $client->sayHello($request);
$message = $reply->getMessage();
$user = $reply->getUser();
var_dump(memory_get_usage(true));
return $message;
}
要点说明:
'127.0.0.1:9503'对应服务端server.php中grpc服务的host与port;'credentials' => null表示不启用 TLS 加密(如需 TLS 可传入相应凭据配置);- 调用返回
list($reply, $status),$reply为HiReply消息对象,$status为调用状态对象,可通过$reply->getMessage()、$reply->getUser()获取响应字段; - 客户端是协程安全的,可以在协程环境中复用同一个实例。
客户端连接池与重试机制
从 BaseClient.php 可以看到,BaseClient 构造时支持 options 中的 client_count 参数(默认 1,最小为 1),即内部可以维护多个 GrpcClient 连接实例并在协程上下文中按需选取,这从源码结构上保证了多协程并发调用时的连接复用与安全。
同时 _simpleRequest 内部的重试逻辑(见 BaseClient.php)支持两个可选参数:
retry_attempts:发送失败时的最大重试次数,默认 3;retry_interval:重试间隔(毫秒),默认 100。
Streaming 模式:双向流调用
gRPC 客户端还支持 gRPC 的 Streaming 模式(客户端流、服务端流与双向流)。以双向流为例:
public function hello()
{
$client = new RouteGuideClient('127.0.0.1:50051');
$note = new RouteNote();
$call = $client->routeChat();
$call->push($note);
$call->push($note);
/** @var RouteNote $note */
[$note,] = $call->recv();
[$note,] = $call->recv();
}
与一元调用的 _simpleRequest 相对应,BaseClient 中还封装了其余三种流式调用的入口(见 BaseClient.php):
_clientStreamRequest():客户端流(Client Streaming),对应ClientStreamingCall;_serverStreamRequest():服务端流(Server Streaming),对应ServerStreamingCall;_bidiRequest():双向流(Bidirectional Streaming),对应BidiStreamingCall(见 BidiStreamingCall.php,它继承自StreamingCall)。
在双向流场景下,通过 $call->push($note) 向服务端持续推送消息,通过 $call->recv() 接收服务端返回的消息。
请注意:在 streaming 模式下,必须手动捕获连接断开的异常(
Hyperf\GrpcClient\Exception\GrpcClientException),并根据业务需要决定是否重试。流式调用是长连接交互,断线是常态,不能依赖框架自动处理。
gRPC 状态码与错误处理
gRPC 使用标准的错误码体系描述调用结果。Hyperf 在 StatusCode.php 中完整定义了 0–16 号状态码常量,包括 OK(0)、CANCELLED(1)、INVALID_ARGUMENT(3)、DEADLINE_EXCEEDED(4)、NOT_FOUND(5)、PERMISSION_DENIED(7)、UNIMPLEMENTED(12)、INTERNAL(13)、UNAVAILABLE(14) 等(见 StatusCode.php)。
同时,该类还提供了一份 gRPC 状态码到 HTTP 状态码的映射表 HTTP_CODE_MAPPING(见 StatusCode.php),例如 NOT_FOUND 对应 HTTP 404、DEADLINE_EXCEEDED 对应 504、UNAVAILABLE 对应 503、PERMISSION_DENIED 对应 403。这份映射关系用于在 HTTP/2 传输层将 gRPC 错误语义映射为可观测的 HTTP 状态,便于网关、监控与排查。
客户端侧,UnaryCall::parse()(见 UnaryCall.php)会依次检查:无响应(GRPC_ERROR_NO_RESPONSE,值为 -1)、HTTP 状态异常、grpc-status 非 0,最后才反序列化正常消息体;而 Parser::parseMetadata()(见 Parser.php)负责剥离 gRPC 预留头与 HTTP/2 伪头,并对 -bin 结尾的 metadata 做 base64 解码,对普通 metadata 做 URL 解码——客户端可以通过 $status->metadata 获取这些附加信息。
写在后面
如果你是 gRPC 的重度使用者,可以关注 Hyperf 后续的开发者工具——社区规划中支持根据 .proto 文件自动生成全套 gRPC 代码(服务端类、客户端类与消息类),进一步降低接入成本。
延伸阅读
- 本文 gRPC 服务端端口、路由等配置的更多细节,参见 配置 与 路由;
- gRPC 编解码与状态码实现,可深入阅读 Parser.php 与 StatusCode.php;
- 服务端请求处理链路,可深入阅读 CoreMiddleware.php 与 Server.php;
- 客户端连接管理、重试与流式调用,可深入阅读 BaseClient.php、UnaryCall.php 与
StreamingCall系列类。