Hyperf gRPC 服务实战指南:从 .proto 定义到服务端与客户端完整落地

原创2026-10-08 11:56:511,866 阅读
文章标签:后端微服务RPC框架Web框架

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() 方法中,完整链路清晰可见:

  1. 从请求属性中取出 Dispatched 路由分发结果,若 Dispatcher::FOUND 则解析控制器/闭包参数;
  2. parseMethodParameters() 通过 MethodDefinitionCollector 反射方法签名,若参数类型继承自 Google\Protobuf\Internal\Message(即 protobuf 消息类),则从请求体 RequestContext::get()->getBody() 读取原始字节流,调用 Parser::deserializeMessage([$class->getName(), null], (string) $stream) 反序列化为消息对象——这就是 sayHello(HiUser $user) 中 $user 的来源;
  3. 控制器返回后校验结果必须是 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 调用链与错误处理策略。

登录后查看全文
hyperf