Hyperf gRPC 服务实战指南:从 .proto 定义到服务端与客户端完整落地
Hyperf gRPC 服务实战指南:从 .proto 定义到服务端与客户端完整落地
gRPC 官方 PHP quickstart 文档很容易让 PHPer 误入歧途——按照官方文档,仅仅是让 gRPC 服务"跑起来"就相当繁琐,更不用说构建一套完整的 RPC 服务体系。Hyperf 对 gRPC 做了进一步封装:以 HTTP 服务器承载 gRPC 协议、内置 protobuf 编解码与协程安全的客户端复用机制,让开发者像编写普通 Controller 一样编写 RPC 服务。本文以 grpc.proto 定义、服务端路由与控制器、客户端封装与 Streaming 四种模式为主线,结合 Hyperf 源码(src/grpc、src/grpc-server、src/grpc-client)讲透每一步的原理与配置,读完即可在你的 Hyperf 项目中独立落地一套完整的 gRPC 调用链。
.proto 文件定义与代码生成
gRPC 的一切都从 .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;
}
使用 protoc 生成 PHP 代码
使用 Linux 包管理工具安装 protoc(下面以 alpine 为例,也可参考 hyperf-skeleton 项目中的 Dockerfile 安装方式),然后执行代码生成:
# 使用 linux 包管理工具安装 protoc,下面以 alpine 为例
apk add protobuf
# 使用 protoc 自动生成代码
protoc --php_out=grpc/ grpc.proto
# tree grpc
grpc
├── GPBMetadata
│ └── Grpc.php
└── Grpc
├── HiReply.php
└── HiUser.php
生成的目录结构分为两部分:GPBMetadata/Grpc.php 用于描述 proto 文件的元数据(file descriptor),Grpc/HiReply.php、Grpc/HiUser.php 则是继承自 Google\Protobuf\Internal\Message 的消息类,提供 setName()、setSex()、setMessage()、setUser()、encode() 等读写与序列化方法。
composer.json 自动加载配置
将 grpc/ 目录下生成的代码纳入 PSR-4 自动加载。若 proto 文件中使用了不同的 package 设置,或使用了不同的输出目录,按实际命名空间与目录相应调整即可;修改后执行 composer dump-autoload 使自动加载生效:
"autoload": {
"psr-4": {
"App\\": "app/",
"GPBMetadata\\": "grpc/GPBMetadata",
"Grpc\\": "grpc/Grpc"
},
"files": [
]
},
gRPC Server 服务端示例
安装组件
composer require hyperf/grpc-server
hyperf/grpc-server 组件基于 hyperf/grpc(protobuf 编解码、路径生成、状态码)、hyperf/http-server(HTTP 承载层)等实现,从 src/grpc-server/composer.json 可以看到其依赖集合,PHP 版本要求 >=8.2。
server.php 服务器配置
gRPC 服务本质上是跑在 Swoole HTTP Server 之上的一种协议,因此在 server.php(参考 配置)中新增一个 type 为 Server::SERVER_HTTP 的 server,并将 onRequest 回调指向 Hyperf\GrpcServer\Server::onRequest:
'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'],
],
],
],
从源码看,src/grpc-server/src/Server.php 继承自 Hyperf\HttpServer\Server,在 initCoreMiddleware() 中注入 GrpcServer\CoreMiddleware,并默认将异常处理器设置为 GrpcExceptionHandler(可通过 exceptions.handler.grpc 配置覆盖)。这意味着你既可以用它对外提供标准 gRPC 服务,也可以在同一进程中按需注册多个 server、监听不同端口。
另外,组件还发布了一份 grpc_server.php 配置(对应 publish/grpc_server.php):
return [
// Whether to support services by rpc-server
// Required `hyperf/rpc` and `hyperf/rpc-server`.
'rpc' => [
// The port name
'grpc' => [
'enable' => false,
],
],
];
该开关用于启用基于 RPC Server 协议层的服务注册能力(需安装 hyperf/rpc、hyperf/rpc-server);若只是按本文方式用 HTTP 承载 gRPC,保持默认即可。
routes.php 路由配置
gRPC 的路由并不像普通 HTTP 路由那样按路径自由命名,而是与 proto 定义严格对应,格式为 /{package}.{service}/{rpc}。在 routes.php(参考 路由)中为 grpc server 单独注册路由组:
Router::addServer('grpc', function () {
Router::addGroup('/grpc.Hi', function () {
Router::post('/SayHello', 'App\Controller\HiController@sayHello');
});
});
HiController 控制器实现
控制器方法与普通 Hyperf Controller 无异,唯一区别是:入参是 protobuf 消息对象 HiUser,返回值必须是 protobuf 消息对象 HiReply:
public function sayHello(HiUser $user)
{
$message = new HiReply();
$message->setMessage("Hello World");
$message->setUser($user);
return $message;
}
深入原理:服务端请求是如何被处理的
在 src/grpc-server/src/CoreMiddleware.php 的 process() 方法中,完整链路清晰可见:
- 从请求属性中取出
Dispatched路由分发结果,若Dispatcher::FOUND则解析控制器/闭包参数; parseMethodParameters()通过MethodDefinitionCollector反射方法签名,若参数类型继承自Google\Protobuf\Internal\Message(即 protobuf 消息类),则从请求体RequestContext::get()->getBody()读取原始字节流,调用Parser::deserializeMessage([$class->getName(), null], (string) $stream)反序列化为消息对象——这就是sayHello(HiUser $user)中$user的来源;- 控制器返回后校验结果必须是
Message实例,否则返回StatusCode::INTERNAL的 gRPC 错误;随后handleResponse()将消息序列化写入响应体,并设置Content-Type: application/grpc,通过 HTTP/2 trailer 携带grpc-status、grpc-message。
服务端响应的序列化与解包逻辑位于 src/grpc/src/Parser.php:每个 gRPC 消息帧由「1 字节压缩标志 + 4 字节长度 + protobuf 二进制」组成,pack() 负责组装、unpack() 负责剥离帧头、serializeMessage() / deserializeMessage() 完成消息与字节流的互转。所有 gRPC 状态码常量(OK=0、INTERNAL=13、UNIMPLEMENTED=12 等)及与 HTTP 状态码的映射表 HTTP_CODE_MAPPING 定义在 src/grpc/src/StatusCode.php。
gRPC Client 客户端示例
安装组件
composer require hyperf/grpc-client
一元请求(Unary Call)
hyperf/grpc-client 已封装好基类 Hyperf\GrpcClient\BaseClient,你只需根据 .proto 文件中的定义继承并扩展即可。以 HiClient 为例(仓库中的测试桩可见 src/grpc-client/tests/Stub/HiClient.php):
class HiClient extends BaseClient
{
public function sayHello(HiUser $argument)
{
return $this->_simpleRequest(
'/grpc.Hi/SayHello',
$argument,
[HiReply::class, 'decode']
);
}
}
_simpleRequest() 接收三个核心参数:方法路径 /{package}.{service}/{rpc}、请求消息对象、响应反序列化方式(通常为 <a href="https://link.gitcode.com/i/695822c4f354d3435987234f40414cdf" target="_blank">消息类::class, 'decode'])。它在 [BaseClient.php 内部会先 send() 发出请求,发送失败时依据 retry_attempts(默认 3 次)与 retry_interval(默认 100ms)自动重试,再包装为 UnaryCall 返回。
在业务代码(如 GrpcController::hello())中调用:
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;
}
调用返回 [$reply, $status] 二元组:$reply 为反序列化后的响应消息对象,$status 为 gRPC 状态码(0 表示成功)。
BaseClient 的协程安全与连接复用
文档中强调"这个 client 是协程安全的,可以复用",其实现依据在 BaseClient.php 中:
- 懒初始化:
_getGrpcClient()首次调用时才执行init(),按client_count(默认 1)创建多个GrpcClient连接池成员; - 协程隔离:
start()通过Context::getOrSet()按协程上下文分配客户端索引,同一协程内复用同一连接,不同协程各取所需,天然规避了连接串用问题; - 断线自愈:每次使用前检查
isRunning(),未运行时加锁重启连接,失败抛出GrpcClientException。
构造函数还支持 credentials(TLS 凭证,本地直连可传 null)、client_count(并发连接数)、retry_attempts / retry_interval(发送重试次数与间隔)、client(指定已构造的 GrpcClient 实例)等选项。
Streaming 模式:客户端流、服务端流与双向流
gRPC 客户端支持完整的 Streaming 模式。以双向流(Bidi Streaming)为例,BaseClient 的 _bidiRequest() 会返回 BidiStreamingCall(见 src/grpc-client/src/StreamingCall.php),通过 push() 持续发送消息、recv() 持续接收响应:
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();
}
与之对应,BaseClient 还提供了 _clientStreamRequest()(客户端流,返回 ClientStreamingCall)与 _serverStreamRequest()(服务端流,返回 ServerStreamingCall)两个受保护方法,分别用于"多条消息上行、单条响应下行"与"单条请求上行、多条响应下行"的场景;仓库测试目录中的 RouteGuideClientTest.php 与 Routeguide/ 下的消息类即为完整的流式调用示例。
请注意:在 streaming 模式下,必须手动捕获连接断开的异常(
Hyperf\GrpcClient\Exception\GrpcClientException),并根据业务需要决定是否重试。这是因为流式调用生命周期长、连接随时可能被服务端关闭或网络中断,StreamingCall::push()/recv()在写失败、流不存在或超时时都会抛出该异常,绝不能像一元请求那样依赖框架隐式兜底。
写在后面
如果你是 gRPC 的重度使用者,可以继续深入仓库中的实现细节:src/grpc-client 下的 GrpcTransporter.php、GrpcPacker.php、DataFormatter.php 定义了客户端底层的数据传输与协议帧处理;src/grpc/src/PathGenerator.php 中的 generate() 展示了服务端 RPC 路径 /grpc.{service}/{method} 的自动生成规则(会剥去命名空间中的 Service 后缀);src/grpc-server 的 Listener/ 目录则负责协议与服务注册相关能力。结合这些源码,你可以在 Hyperf 上自由定制属于自己的 gRPC 调用链与错误处理策略。