去年我们团队定技术方案时遇到一个很现实的问题后端有一半服务是PHP写的但新启动的用户服务被明确要求必须开放gRPC接口给其他团队调用。第一反应是PHP做gRPC客户端去调别人没问题但自己要常驻内存跑一个gRPC服务端去扛流量传统PHP-FPM那种“请求来了起一个进程、跑完就销毁”的模型根本撑不住。后来把整套方案落到Hyperf上开发过程比预想顺利不少。前后从环境搭建、proto协议编写、服务端实现到客户端联调压测踩了一堆文档里没写明白的坑。这篇不聊概念纯粹记录我用Hyperf落地gRPC服务的完整流程代码之外的坑都会点出来给准备走上这条路的人省点时间。1. 为什么PHP的gRPC服务要交给Hyperf来做1.1 gRPC对PHP传统架构不友好gRPC的底层本质是基于HTTP/2协议、用Protocol Buffers做数据序列化的RPC框架。HTTP/2和HTTP/1.1最大的区别之一就是长连接和多路复用同一个TCP连接上可以同时跑多个请求流连接要长时间保持还要处理心跳、streaming、deadline这些机制。这意味着服务端必须常驻内存进程生命周期和PHP-FPM完全反着来。PHP-FPM是“一个请求进来worker从进程池里拿一个进程处理响应结束进程释放”这模型天生不适合做gRPC服务端。就算你强行用PHP的grpc扩展在FPM下写一个服务端脚本每次请求结束进程就销毁客户端连上来心跳直接断流式调用更是无从谈起。所以想在PHP生态里做gRPC服务端第一步就是跳出FPM这套运行模型落到常驻内存框架上。1.2 Hyperf的协程模型正好补齐这块短板Hyperf基于Swoole常驻内存跑Swoole的worker进程本身就是长生命周期HTTP/2连接可以在这上面稳定维持。配合Swoole的协程调度单个worker可以支撑大量并发连接这在PHP世界里算是补齐了gRPC服务端的基础设施短板。选Hyperf而不是RoadRunner或者原生Swoole直接写还有几个实际层面的原因第一Hyperf把gRPC的协议解析、请求路由、异常处理这些脏活都封装好了。你用Swoole裸写HTTP/2的gRPC帧解析工作量是很大的。Hyperf的grpc-server组件把这些全部包掉你需要做的只是写proto、生成PHP代码、实现业务逻辑、注册路由。第二Hyperf的容器和生态组件都是为协程优化的。gRPC请求进来后你在一个协程里查数据库、读写Redis、调下游HTTP接口跟写普通Web接口没什么两样。连接池、协程上下文这套东西已经成熟了团队里的同事接手成本很低。第三对比RoadRunner它作为Go写的应用服务器确实稳定但PHP侧依然是同步阻塞模型要用协程还得靠额外的工具配合整个链路多了一个Go进程要维护部署复杂度更高PHP侧的协程生态也没Swoole成熟。总结就是Hyperf不是唯一能做gRPC服务端的PHP方案但它是“协程 gRPC协议支持 组件生态 PHP侧维护成本”这几个维度综合起来落地阻力最小的一个。2. 环境搭建Windows本机调试与Linux一把过2.1 PHP扩展三件套swoole、grpc、protobuf做Hyperf gRPC服务端PHP环境至少需要这三个扩展扩展作用缺失时的表现swoole提供HTTP/2服务器能力和协程调度框架起不来grpc_server无法监听端口grpc提供gRPC协议的C语言底层解析包括HPACK头部压缩、HTTP/2帧处理生成代码可以写但运行时报找不到gRPC核心库的方法protobuf对PB Message做二进制序列化和反序列化走纯PHP实现的protobuf性能掉一个量级强烈不建议很多人只装了grpc扩展没装protobuf。这种配置下代码也能跑因为gRPC扩展会带一个纯PHP的protobuf实现兜底但序列化性能和C扩展版本完全不是一回事。在线上的高并发场景这个差距会被放大得非常明显。注意安装之前先确认PHP版本和扩展版本的对应关系。比如Hyperf 2.2建议PHP 7.4/8.0Swoole 4.5。版本不匹配会出现swoole扩展加载失败、protobuf生成代码不兼容这些问题后面排查起来很费时间。2.2 用composer创建Hyperf项目骨架初始化项目我直接用官方骨架composer create-project hyperf/hyperf-skeleton hyperf-grpc-demo进入项目目录后安装gRPC相关组件composer require hyperf/grpc-server hyperf/grpc-client这里有个容易忽略的点骨架项目自带了JSON-RPC的配置和示例代码它们不会和gRPC冲突但如果你后续要用php bin/hyperf.php start同时启动HTTP服务和gRPC服务配置命名要分清。接着新建gRPC服务配置文件名是config/autoload/grpc_server.php?php use Hyperf\GrpcServer\Server; return [ handler Server::class, servers [ [ name grpc, host 0.0.0.0, port 9503, callbacks [ receive Server::class, ], settings [ open_http2_protocol true, ], ], ], ];name这个值很关键后面配置路由和中间件都要用到它。我在这一卡了很久一开始不知道要单独建grpc_server.php直接改了默认的server.php配置结果gRPC服务怎么都监听不到9503端口。完成配置后启动服务php bin/hyperf.php start看到控制台输出swoole监听0.0.0.0:9503说明grpc服务的基础环境已经通了。2.3 Windows下grpc扩展安装与验证Windows本地开发环境和Linux的生产环境安装方式不太一样这里单独说。Swoole在Windows没有官方生产支持但本地开发调试可以用。grpc和protobuf这两个扩展在Windows上可以通过pecl install安装pecl install grpc pecl install protobuf安装完成后在php.ini里加上extensiongrpc extensionprotobuf然后检查扩展是否加载成功php -m | grep grpc php -m | grep protobuf php --ri grpcphp --ri grpc能看到gRPC扩展的版本信息这一步一定要做确认扩展版本和protoc生成的代码兼容性。如果你用的是WSL2或Docker开发环境那就不存在Windows扩展这些幺蛾子。直接在Linux容器里pecl install grpc protobuf docker-php-ext-enable grpc protobuf我的建议是Windows本机只要能满足日常语法调试就行实际跑gRPC服务还是放在WSL2或Docker里面一是Swoole在Windows下的功能有限二是gRPC这种涉及网络协议栈的东西越贴近Linux生产环境越不容易出幺蛾子。3. proto协议就是服务契约先把这个定义明白3.1 一版够用的用户服务协议写gRPC服务第一步永远不是写PHP代码而是定义proto文件。proto是服务端和客户端之间的接口契约字段编号、类型、包名全都在这份文件里定死。我建了一个用户服务协议放在项目根目录的proto/目录下syntax proto3; package grpc.user; service UserService { rpc GetUserInfo (UserInfoRequest) returns (UserInfoResponse); } message UserInfoRequest { int64 user_id 1; } message UserInfoResponse { int64 user_id 1; string nickname 2; string email 3; int32 level 4; }这里有两个关键设计要解释第一package grpc.user;决定了生成的PHP命名空间和服务路径。后面注册路由时完整路径是grpc.user.UserService/getUserInfo前半段就是这里定义的package。第二字段序号不是随便填的。proto3里字段编号一旦发布出去就是线上兼容协议的一部分。老客户端可能只认编号1、2如果上线后你为了加一个新字段把已有的字段编号改了老客户端解析出来的数据就是错的。字段序号设计时就应该留出扩展空间新版本只追加编号不修改已有编号。3.2 用protoc生成PHP代码生成PHP代码需要两个工具protoc编译器和grpc_php_plugin插件。protoc负责把proto文件编译成各语言代码grpc_php_plugin生成gRPC服务相关代码。安装protoc之后执行生成命令protoc --php_out./ \ --grpc_out./ \ --pluginprotoc-gen-grpc/path/to/grpc_php_plugin \ proto/user.proto--php_out生成的是Message的PHP类--grpc_out生成的是gRPC服务和客户端代码。grpc_php_plugin一般在你编译安装grpc扩展时生成如果是用pecl装的插件位置通常在PHP扩展目录里找不到就用find / -name grpc_php_plugin搜一下。3.3 生成目录和PSR-4自动加载的坑生成出来的代码会按proto里的定义落到几个目录很多人第一次看到会懵这里拆开讲生成目录内容作用App/GPBMetadataUser.php描述proto文件的元数据信息App/GrpcUserServiceInterface.php, UserServiceClient.phpgRPC服务接口和客户端stubApp/GPB/UserUserInfoRequest.php, UserInfoResponse.php请求和响应的Message类GPB是Google Protocol Buffers的缩写Hyperf官方生成的代码默认就把Message类放在App/GPB下面。GPBMetadata下的类会在运行时被自动加载用来注册Message的描述信息。这里有一个非常容易踩的坑生成出来的目录首字母是大小写混合的App/Grpc、App/GPB但Hyperf默认的PSR-4自动加载只映射了App\到app/目录。结果就是运行时报Class not found日志里又看不出明显原因。解决办法是手动把生成出来的目录移动到项目的app/下然后确保composer.json里配置正确{ autoload: { psr-4: { App\\: app/ } } }移动完文件后执行composer dump-autoload再检查一下自动加载是否生效php -r var_dump(class_exists(App\\Grpc\\UserServiceInterface));输出bool(true)就说明类和文件路径对上了。这一步不做后面所有工作都白搭先把自动加载捋顺了再往下写。4. 服务端业务实现从“能调通”到“能上线”4.1 实现控制器并注册gRPC路由生成好的UserServiceInterface是个接口里面定义了getUserInfo方法签名。服务端要创建一个控制器类去实现这个接口。我在app/Grpc/Controller/下新建UserServiceController.php?php namespace App\Grpc\Controller; use App\Grpc\UserServiceInterface; use App\GPB\User\UserInfoRequest; use App\GPB\User\UserInfoResponse; use Hyperf\GrpcServer\BaseController; use Psr\Container\ContainerInterface; class UserServiceController extends BaseController implements UserServiceInterface { public function __construct(protected ContainerInterface $container) { } public function getUserInfo(UserInfoRequest $request): UserInfoResponse { $response new UserInfoResponse(); $userId $request-getUserId(); // 实际业务里这里会通过Service层查数据库 $user [ id $userId, nickname demo_user_ . $userId, email user . $userId . example.com, level 3, ]; $response-setUserId($user[id]); $response-setNickname($user[nickname]); $response-setEmail($user[email]); $response-setLevel($user[level]); return $response; } }这里继承了BaseController。为什么需要继承它因为Hyperf的gRPC控制器需要处理请求上下文、响应对象这些公共逻辑BaseController把这些封装好了。你只管把业务逻辑填进去返回一个符合Message定义的对象就行。接下来注册路由在config/routes.php里?php use Hyperf\HttpServer\Router\Router; Router::addRoute([POST, GET], /grpc.user.UserService/getUserInfo, [ \App\Grpc\Controller\UserServiceController::class, getUserInfo, ]);Hyperf的gRPC路由规则是固定的/package名.Service名/方法名。所以这里路径是grpc.user.UserService/getUserInfo。POST是必须的GET也注册上是因为有些工具会发GET请求做探测全配了省得后面排查的时候多一个变量。如果服务里方法多路由会显得繁琐但gRPC本身就是显式接口每个方法一条路由反而是清晰的。4.2 协程下的超时控制与连接池设防业务代码能跑通之后要考虑的是协程模型下的稳定性问题。这一点和传统PHP开发非常不一样值得单独拿出来说。Hyperf的gRPC请求进来后是在一个独立的协程里执行你的控制器代码。这个协程里如果遇到阻塞操作比如一个慢SQL、一个响应很慢的下游HTTP请求它会挂起把CPU让给别的协程。但这里有个隐患如果你没有给这些操作设置超时时间它可能一直挂起不回来这个协程就一直占着位置积累多了worker进程的资源就被吃光了。Swoole本身没有全局的超时拦截机制超时需要你自己设。比如在控制器里调一个可能很慢的服务use Swoole\Coroutine\Channel; $channel new Channel(1); go(function () use ($channel, $userId) { $channel-push($this-userService-findById($userId)); }); $result $channel-pop(2.0); if ($result false) { // 2秒内没拿到结果按超时处理 }这种模式在协调多个下游依赖时尤其重要。实际项目里我见过线上服务卡死排查半天发现是某个下游接口偶尔响应30秒协程一直被占着后续请求排队整个服务雪崩。给每个下游调用都加上超时是协程服务的基本功。数据库连接池这块也要配合调整。config/autoload/databases.php里连接池的min_connections和max_connections需要根据gRPC接口的QPS来设。假设服务有4个worker进程每个worker默认的连接池是1到10个连接。如果单接口每次查询占用1个连接并发100请求时每个worker要分25个请求连接池如果只开到10就会等待连接释放表现为接口RT升高。我的经验是先按“单次请求最多同时占用2个连接”来估算比如并发1004个worker每个worker的max_connections至少给到50。压测的时候观察连接池的wait时间再针对性调整别拍脑袋定。4.3 中间件做鉴权和访问日志gRPC服务上线后鉴权和访问日志是逃不掉的。这两个功能如果散落在各个业务方法里代码会变得很难维护正确做法是写在中间件里。Hyperf的gRPC和HTTP可以共用PSR-15中间件配置在config/autoload/middlewares.php?php return [ grpc [ \App\Middleware\GrpcAuthMiddleware::class, \App\Middleware\GrpcLogMiddleware::class, ], ];注意这里的key是grpc对应grpc_server.php里配置的server name。如果写错成http中间件不会生效。鉴权中间件的实现核心是读取gRPC请求的metadata。客户端会把token放在metadata里传过来服务端取出来校验public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface { $metadata $request-getGrpcContext()-getMetadata(); $token $metadata[authorization] ?? ; if (!$this-authService-check($token)) { throw new UnauthenticatedException(invalid token); } return $handler-handle($request); }gRPC的metadata对应HTTP/2里的header所以传递时键名用小写也没关系。这里抛出异常后Hyperf的GrpcExceptionHandler会把它转换成gRPC协议的错误状态码返回给客户端客户端那边能拿到明确的grpc-status。访问日志中间件也建议提前加上。gRPC本身没有访问日志的概念但线上排查问题的时候没有日志等于瞎找。在中间件里记录serviceMethod、耗时、状态码这些关键信息后续出问题能快速定位。5. 客户端验证grpcurl与Hyperf协程Client双管齐下5.1 用grpcurl做黑盒接口验证服务端写完第一个要用的测试工具不是代码而是grpcurl。它是类似curl的gRPC命令行工具支持Windows。去GitHub的fullstorydev/grpcurl仓库下载对应平台的可执行文件Windows下直接下载grpcurl_windows_x64.zip解压就能用。用它调接口grpcurl -plaintext \ -import-path ./proto \ -proto user.proto \ -d {user_id: 1} \ 127.0.0.1:9503 grpc.user.UserService/getUserInfo参数说明-plaintext指定不启用TLS本地调试必须加-import-pathproto文件所在目录-proto指定要加载的proto文件-d请求参数的JSON格式最后是完整的方法路径包名.服务名/方法名如果一切正常返回结果类似{ userId: 1, nickname: demo_user_1, email: user1example.com, level: 3 }grpcurl最大的价值是可以做异常输入验证。比如传个不存在的字段名或者传一个非法的字段类型看服务端到底报什么错误。这比写客户端代码去测试高效得多尤其是联调阶段客户端还没写好grpcurl就能把接口的协议正确性验证掉一大半。一个注意点grpcurl不支持gRPC服务反射的情况下必须手动指定proto文件。Hyperf的grpc-server目前没有内置反射服务所以每次都要带-proto参数。如果proto文件有更新记得先重新生成代码再用grpcurl验证新的接口。5.2 用Hyperf协程client写并发压测脚本grpcurl适合验证功能但压测还得靠代码。我用Hyperf的grpc-client组件写了个简单的并发测试脚本?php use App\Grpc\UserServiceClient; use App\GPB\User\UserInfoRequest; use Hyperf\Coroutine\Parallel; use Hyperf\GrpcClient\GrpcClient; require vendor/autoload.php; $parallel new Parallel(200); $start microtime(true); foreach (range(1, 1000) as $i) { $parallel-add(function () use ($i) { $grpcClient new GrpcClient(127.0.0.1:9503); $grpcClient-setTimeout(2); $client new UserServiceClient($grpcClient); $request new UserInfoRequest(); $request-setUserId($i); return $client-getUserInfo($request); }); } $results $parallel-wait(); $cost microtime(true) - $start; echo requests: . count($results) . PHP_EOL; echo cost: . round($cost, 3) . s . PHP_EOL; echo qps: . round(count($results) / $cost, 2) . PHP_EOL;这里的UserServiceClient就是protoc生成的那个客户端stub它继承了Hyperf的BaseClient运行时会复用同一个Hermes连接。压测结果里有两个指标要盯着QPS和P99延迟。QPS看整体吞吐能力P99延迟看最差情况下的体验。如果P99一直在涨说明服务端资源有瓶颈要去查worker进程的CPU占用、数据库连接池是否打满。有个性能优化点说一下上面的脚本每个请求都新建了GrpcClient实例这意味着每个请求都要重新建立HTTP/2连接。真实交付时应该复用连接因为gRPC的多路复用特性允许一个连接上同时跑多个请求。把GrpcClient实例缓存起来复用压测的QPS会有明显提升。我这里给的只是功能验证脚本真实的压测还应该配合监控工具看worker进程的CPU、内存、文件描述符这些指标。线上压测时服务端用top看PHP进程的CPU占用用swoole的统计接口看连接数做到心里有数。6. 部署上线的配置要点与踩坑复盘6.1 Docker镜像与生产参数线上部署我直接用的Docker。基础镜像选择phpswoole/swoole官方镜像比在Alpine Linux上手动装swoole省事得多FROM phpswoole/swoole:4.8-php8.1-alpine RUN pecl install grpc protobuf \ docker-php-ext-enable grpc protobuf WORKDIR /var/www COPY . . RUN composer install --no-dev --optimize-autoloader EXPOSE 9503 CMD [php, bin/hyperf.php, start]这个镜像里的swoole已经编译好了openssl支持如果你想在生产开启gRPC的TLS这是个必要前提。生产环境还有一个大坑不要把Nginx直接放在gRPC前面。Nginx需要配置grpc_pass才能转发gRPC流量而HTTP/2的gRPC对代理配置要求很严格稍微配置不对就报错。更稳妥的做法是直接暴露9503端口用云平台的负载均衡做TLS终止和流量分发。生产环境的worker进程数也要单独调。Swoole默认的worker_num是1这个配置对gRPC服务来说偏小了。一般按CPU核心数来设置比如4核机器设worker_num为4。但要注意worker数开太多每个worker自己的连接池、内存都会有开销要根据压测结果来平衡。6.2 几个让我折腾许久的真实问题最后分享一下这次开发中遇到的最有价值的几个问题每个都是真实踩过坑的经验文档里一般不写。问题一proto生成类的命名空间大小写问题proto里的package grpc.user;生成出来的PHP命名空间是Grpc\User而GPB生成的Message类在GPB\User下。移动目录后如果文件系统大小写不敏感本地能跑部署到Linux上就Class not found。因为composer的PSR-4自动加载在Linux下严格区分大小写。解决办法是proto文件里直接用package grpc.user;生成后手动把目录首字母统一改成和命名空间一致移动完务必执行composer dump-autoload。问题二grpc扩展版本和protoc版本不匹配生成的代码在运行时会调用GPBMetadata里的方法如果grpc扩展版本过低会报undefined method。这个坑的麻烦之处在于报错信息不会直接说是版本问题而是在某个不起眼的地方挂掉。解决思路是保持protoc和grpc扩展版本尽量一致升级grpc扩展后重启服务再次验证。问题三gRPC metadata传大token导致HTTP/2 header超限有一次把集合了多个权限点的token塞进metadata里结果请求直接报HTTP/2相关的header错误。原因是HTTP/2对header大小有限制。如果业务确实要传比较大的metadata值需要在Swoole的server配置里调整对应的buffer参数。但更合理的方案是gRPC metadata里只传token的key真实的认证信息放Redis或者配置中心服务端拿key去查。问题四中间件没有生效排查了很久最后发现是middlewares.php里配置的server name写成了http而grpc_server.php里的server name是grpc。Hyperf是按server name来匹配中间件作用范围的名字对不上中间件就静默不加载。这个问题比较隐蔽因为它不报错只有请求日志里看到鉴权没执行才会怀疑到配置上。这一路做完能明显感觉到用Hyperf做gRPC服务在PHP技术栈里是可行的甚至可以说比想象中顺畅。关键是要把proto协议设计、协程超时控制、自动加载这些基础功夫做扎实别一上来就急着写业务。把上面这些坑都趟平之后后续的每个gRPC接口开发就是纯粹的CRUD填表了。 
长河君 · 2026/9/8 8:05:46 · 阅读 1.2k Hyperf落地gRPC服务：从环境搭建到生产部署的完整实践
去年我们团队定技术方案时遇到一个很现实的问题后端有一半服务是PHP写的但新启动的用户服务被明确要求必须开放gRPC接口给其他团队调用。第一反应是PHP做gRPC客户端去调别人没问题但自己要常驻内存跑一个gRPC服务端去扛流量传统PHP-FPM那种“请求来了起一个进程、跑完就销毁”的模型根本撑不住。后来把整套方案落到Hyperf上开发过程比预想顺利不少。前后从环境搭建、proto协议编写、服务端实现到客户端联调压测踩了一堆文档里没写明白的坑。这篇不聊概念纯粹记录我用Hyperf落地gRPC服务的完整流程代码之外的坑都会点出来给准备走上这条路的人省点时间。1. 为什么PHP的gRPC服务要交给Hyperf来做1.1 gRPC对PHP传统架构不友好gRPC的底层本质是基于HTTP/2协议、用Protocol Buffers做数据序列化的RPC框架。HTTP/2和HTTP/1.1最大的区别之一就是长连接和多路复用同一个TCP连接上可以同时跑多个请求流连接要长时间保持还要处理心跳、streaming、deadline这些机制。这意味着服务端必须常驻内存进程生命周期和PHP-FPM完全反着来。PHP-FPM是“一个请求进来worker从进程池里拿一个进程处理响应结束进程释放”这模型天生不适合做gRPC服务端。就算你强行用PHP的grpc扩展在FPM下写一个服务端脚本每次请求结束进程就销毁客户端连上来心跳直接断流式调用更是无从谈起。所以想在PHP生态里做gRPC服务端第一步就是跳出FPM这套运行模型落到常驻内存框架上。1.2 Hyperf的协程模型正好补齐这块短板Hyperf基于Swoole常驻内存跑Swoole的worker进程本身就是长生命周期HTTP/2连接可以在这上面稳定维持。配合Swoole的协程调度单个worker可以支撑大量并发连接这在PHP世界里算是补齐了gRPC服务端的基础设施短板。选Hyperf而不是RoadRunner或者原生Swoole直接写还有几个实际层面的原因第一Hyperf把gRPC的协议解析、请求路由、异常处理这些脏活都封装好了。你用Swoole裸写HTTP/2的gRPC帧解析工作量是很大的。Hyperf的grpc-server组件把这些全部包掉你需要做的只是写proto、生成PHP代码、实现业务逻辑、注册路由。第二Hyperf的容器和生态组件都是为协程优化的。gRPC请求进来后你在一个协程里查数据库、读写Redis、调下游HTTP接口跟写普通Web接口没什么两样。连接池、协程上下文这套东西已经成熟了团队里的同事接手成本很低。第三对比RoadRunner它作为Go写的应用服务器确实稳定但PHP侧依然是同步阻塞模型要用协程还得靠额外的工具配合整个链路多了一个Go进程要维护部署复杂度更高PHP侧的协程生态也没Swoole成熟。总结就是Hyperf不是唯一能做gRPC服务端的PHP方案但它是“协程 gRPC协议支持 组件生态 PHP侧维护成本”这几个维度综合起来落地阻力最小的一个。2. 环境搭建Windows本机调试与Linux一把过2.1 PHP扩展三件套swoole、grpc、protobuf做Hyperf gRPC服务端PHP环境至少需要这三个扩展扩展作用缺失时的表现swoole提供HTTP/2服务器能力和协程调度框架起不来grpc_server无法监听端口grpc提供gRPC协议的C语言底层解析包括HPACK头部压缩、HTTP/2帧处理生成代码可以写但运行时报找不到gRPC核心库的方法protobuf对PB Message做二进制序列化和反序列化走纯PHP实现的protobuf性能掉一个量级强烈不建议很多人只装了grpc扩展没装protobuf。这种配置下代码也能跑因为gRPC扩展会带一个纯PHP的protobuf实现兜底但序列化性能和C扩展版本完全不是一回事。在线上的高并发场景这个差距会被放大得非常明显。注意安装之前先确认PHP版本和扩展版本的对应关系。比如Hyperf 2.2建议PHP 7.4/8.0Swoole 4.5。版本不匹配会出现swoole扩展加载失败、protobuf生成代码不兼容这些问题后面排查起来很费时间。2.2 用composer创建Hyperf项目骨架初始化项目我直接用官方骨架composer create-project hyperf/hyperf-skeleton hyperf-grpc-demo进入项目目录后安装gRPC相关组件composer require hyperf/grpc-server hyperf/grpc-client这里有个容易忽略的点骨架项目自带了JSON-RPC的配置和示例代码它们不会和gRPC冲突但如果你后续要用php bin/hyperf.php start同时启动HTTP服务和gRPC服务配置命名要分清。接着新建gRPC服务配置文件名是config/autoload/grpc_server.php?php use Hyperf\GrpcServer\Server; return [ handler Server::class, servers [ [ name grpc, host 0.0.0.0, port 9503, callbacks [ receive Server::class, ], settings [ open_http2_protocol true, ], ], ], ];name这个值很关键后面配置路由和中间件都要用到它。我在这一卡了很久一开始不知道要单独建grpc_server.php直接改了默认的server.php配置结果gRPC服务怎么都监听不到9503端口。完成配置后启动服务php bin/hyperf.php start看到控制台输出swoole监听0.0.0.0:9503说明grpc服务的基础环境已经通了。2.3 Windows下grpc扩展安装与验证Windows本地开发环境和Linux的生产环境安装方式不太一样这里单独说。Swoole在Windows没有官方生产支持但本地开发调试可以用。grpc和protobuf这两个扩展在Windows上可以通过pecl install安装pecl install grpc pecl install protobuf安装完成后在php.ini里加上extensiongrpc extensionprotobuf然后检查扩展是否加载成功php -m | grep grpc php -m | grep protobuf php --ri grpcphp --ri grpc能看到gRPC扩展的版本信息这一步一定要做确认扩展版本和protoc生成的代码兼容性。如果你用的是WSL2或Docker开发环境那就不存在Windows扩展这些幺蛾子。直接在Linux容器里pecl install grpc protobuf docker-php-ext-enable grpc protobuf我的建议是Windows本机只要能满足日常语法调试就行实际跑gRPC服务还是放在WSL2或Docker里面一是Swoole在Windows下的功能有限二是gRPC这种涉及网络协议栈的东西越贴近Linux生产环境越不容易出幺蛾子。3. proto协议就是服务契约先把这个定义明白3.1 一版够用的用户服务协议写gRPC服务第一步永远不是写PHP代码而是定义proto文件。proto是服务端和客户端之间的接口契约字段编号、类型、包名全都在这份文件里定死。我建了一个用户服务协议放在项目根目录的proto/目录下syntax proto3; package grpc.user; service UserService { rpc GetUserInfo (UserInfoRequest) returns (UserInfoResponse); } message UserInfoRequest { int64 user_id 1; } message UserInfoResponse { int64 user_id 1; string nickname 2; string email 3; int32 level 4; }这里有两个关键设计要解释第一package grpc.user;决定了生成的PHP命名空间和服务路径。后面注册路由时完整路径是grpc.user.UserService/getUserInfo前半段就是这里定义的package。第二字段序号不是随便填的。proto3里字段编号一旦发布出去就是线上兼容协议的一部分。老客户端可能只认编号1、2如果上线后你为了加一个新字段把已有的字段编号改了老客户端解析出来的数据就是错的。字段序号设计时就应该留出扩展空间新版本只追加编号不修改已有编号。3.2 用protoc生成PHP代码生成PHP代码需要两个工具protoc编译器和grpc_php_plugin插件。protoc负责把proto文件编译成各语言代码grpc_php_plugin生成gRPC服务相关代码。安装protoc之后执行生成命令protoc --php_out./ \ --grpc_out./ \ --pluginprotoc-gen-grpc/path/to/grpc_php_plugin \ proto/user.proto--php_out生成的是Message的PHP类--grpc_out生成的是gRPC服务和客户端代码。grpc_php_plugin一般在你编译安装grpc扩展时生成如果是用pecl装的插件位置通常在PHP扩展目录里找不到就用find / -name grpc_php_plugin搜一下。3.3 生成目录和PSR-4自动加载的坑生成出来的代码会按proto里的定义落到几个目录很多人第一次看到会懵这里拆开讲生成目录内容作用App/GPBMetadataUser.php描述proto文件的元数据信息App/GrpcUserServiceInterface.php, UserServiceClient.phpgRPC服务接口和客户端stubApp/GPB/UserUserInfoRequest.php, UserInfoResponse.php请求和响应的Message类GPB是Google Protocol Buffers的缩写Hyperf官方生成的代码默认就把Message类放在App/GPB下面。GPBMetadata下的类会在运行时被自动加载用来注册Message的描述信息。这里有一个非常容易踩的坑生成出来的目录首字母是大小写混合的App/Grpc、App/GPB但Hyperf默认的PSR-4自动加载只映射了App\到app/目录。结果就是运行时报Class not found日志里又看不出明显原因。解决办法是手动把生成出来的目录移动到项目的app/下然后确保composer.json里配置正确{ autoload: { psr-4: { App\\: app/ } } }移动完文件后执行composer dump-autoload再检查一下自动加载是否生效php -r var_dump(class_exists(App\\Grpc\\UserServiceInterface));输出bool(true)就说明类和文件路径对上了。这一步不做后面所有工作都白搭先把自动加载捋顺了再往下写。4. 服务端业务实现从“能调通”到“能上线”4.1 实现控制器并注册gRPC路由生成好的UserServiceInterface是个接口里面定义了getUserInfo方法签名。服务端要创建一个控制器类去实现这个接口。我在app/Grpc/Controller/下新建UserServiceController.php?php namespace App\Grpc\Controller; use App\Grpc\UserServiceInterface; use App\GPB\User\UserInfoRequest; use App\GPB\User\UserInfoResponse; use Hyperf\GrpcServer\BaseController; use Psr\Container\ContainerInterface; class UserServiceController extends BaseController implements UserServiceInterface { public function __construct(protected ContainerInterface $container) { } public function getUserInfo(UserInfoRequest $request): UserInfoResponse { $response new UserInfoResponse(); $userId $request-getUserId(); // 实际业务里这里会通过Service层查数据库 $user [ id $userId, nickname demo_user_ . $userId, email user . $userId . example.com, level 3, ]; $response-setUserId($user[id]); $response-setNickname($user[nickname]); $response-setEmail($user[email]); $response-setLevel($user[level]); return $response; } }这里继承了BaseController。为什么需要继承它因为Hyperf的gRPC控制器需要处理请求上下文、响应对象这些公共逻辑BaseController把这些封装好了。你只管把业务逻辑填进去返回一个符合Message定义的对象就行。接下来注册路由在config/routes.php里?php use Hyperf\HttpServer\Router\Router; Router::addRoute([POST, GET], /grpc.user.UserService/getUserInfo, [ \App\Grpc\Controller\UserServiceController::class, getUserInfo, ]);Hyperf的gRPC路由规则是固定的/package名.Service名/方法名。所以这里路径是grpc.user.UserService/getUserInfo。POST是必须的GET也注册上是因为有些工具会发GET请求做探测全配了省得后面排查的时候多一个变量。如果服务里方法多路由会显得繁琐但gRPC本身就是显式接口每个方法一条路由反而是清晰的。4.2 协程下的超时控制与连接池设防业务代码能跑通之后要考虑的是协程模型下的稳定性问题。这一点和传统PHP开发非常不一样值得单独拿出来说。Hyperf的gRPC请求进来后是在一个独立的协程里执行你的控制器代码。这个协程里如果遇到阻塞操作比如一个慢SQL、一个响应很慢的下游HTTP请求它会挂起把CPU让给别的协程。但这里有个隐患如果你没有给这些操作设置超时时间它可能一直挂起不回来这个协程就一直占着位置积累多了worker进程的资源就被吃光了。Swoole本身没有全局的超时拦截机制超时需要你自己设。比如在控制器里调一个可能很慢的服务use Swoole\Coroutine\Channel; $channel new Channel(1); go(function () use ($channel, $userId) { $channel-push($this-userService-findById($userId)); }); $result $channel-pop(2.0); if ($result false) { // 2秒内没拿到结果按超时处理 }这种模式在协调多个下游依赖时尤其重要。实际项目里我见过线上服务卡死排查半天发现是某个下游接口偶尔响应30秒协程一直被占着后续请求排队整个服务雪崩。给每个下游调用都加上超时是协程服务的基本功。数据库连接池这块也要配合调整。config/autoload/databases.php里连接池的min_connections和max_connections需要根据gRPC接口的QPS来设。假设服务有4个worker进程每个worker默认的连接池是1到10个连接。如果单接口每次查询占用1个连接并发100请求时每个worker要分25个请求连接池如果只开到10就会等待连接释放表现为接口RT升高。我的经验是先按“单次请求最多同时占用2个连接”来估算比如并发1004个worker每个worker的max_connections至少给到50。压测的时候观察连接池的wait时间再针对性调整别拍脑袋定。4.3 中间件做鉴权和访问日志gRPC服务上线后鉴权和访问日志是逃不掉的。这两个功能如果散落在各个业务方法里代码会变得很难维护正确做法是写在中间件里。Hyperf的gRPC和HTTP可以共用PSR-15中间件配置在config/autoload/middlewares.php?php return [ grpc [ \App\Middleware\GrpcAuthMiddleware::class, \App\Middleware\GrpcLogMiddleware::class, ], ];注意这里的key是grpc对应grpc_server.php里配置的server name。如果写错成http中间件不会生效。鉴权中间件的实现核心是读取gRPC请求的metadata。客户端会把token放在metadata里传过来服务端取出来校验public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface { $metadata $request-getGrpcContext()-getMetadata(); $token $metadata[authorization] ?? ; if (!$this-authService-check($token)) { throw new UnauthenticatedException(invalid token); } return $handler-handle($request); }gRPC的metadata对应HTTP/2里的header所以传递时键名用小写也没关系。这里抛出异常后Hyperf的GrpcExceptionHandler会把它转换成gRPC协议的错误状态码返回给客户端客户端那边能拿到明确的grpc-status。访问日志中间件也建议提前加上。gRPC本身没有访问日志的概念但线上排查问题的时候没有日志等于瞎找。在中间件里记录serviceMethod、耗时、状态码这些关键信息后续出问题能快速定位。5. 客户端验证grpcurl与Hyperf协程Client双管齐下5.1 用grpcurl做黑盒接口验证服务端写完第一个要用的测试工具不是代码而是grpcurl。它是类似curl的gRPC命令行工具支持Windows。去GitHub的fullstorydev/grpcurl仓库下载对应平台的可执行文件Windows下直接下载grpcurl_windows_x64.zip解压就能用。用它调接口grpcurl -plaintext \ -import-path ./proto \ -proto user.proto \ -d {user_id: 1} \ 127.0.0.1:9503 grpc.user.UserService/getUserInfo参数说明-plaintext指定不启用TLS本地调试必须加-import-pathproto文件所在目录-proto指定要加载的proto文件-d请求参数的JSON格式最后是完整的方法路径包名.服务名/方法名如果一切正常返回结果类似{ userId: 1, nickname: demo_user_1, email: user1example.com, level: 3 }grpcurl最大的价值是可以做异常输入验证。比如传个不存在的字段名或者传一个非法的字段类型看服务端到底报什么错误。这比写客户端代码去测试高效得多尤其是联调阶段客户端还没写好grpcurl就能把接口的协议正确性验证掉一大半。一个注意点grpcurl不支持gRPC服务反射的情况下必须手动指定proto文件。Hyperf的grpc-server目前没有内置反射服务所以每次都要带-proto参数。如果proto文件有更新记得先重新生成代码再用grpcurl验证新的接口。5.2 用Hyperf协程client写并发压测脚本grpcurl适合验证功能但压测还得靠代码。我用Hyperf的grpc-client组件写了个简单的并发测试脚本?php use App\Grpc\UserServiceClient; use App\GPB\User\UserInfoRequest; use Hyperf\Coroutine\Parallel; use Hyperf\GrpcClient\GrpcClient; require vendor/autoload.php; $parallel new Parallel(200); $start microtime(true); foreach (range(1, 1000) as $i) { $parallel-add(function () use ($i) { $grpcClient new GrpcClient(127.0.0.1:9503); $grpcClient-setTimeout(2); $client new UserServiceClient($grpcClient); $request new UserInfoRequest(); $request-setUserId($i); return $client-getUserInfo($request); }); } $results $parallel-wait(); $cost microtime(true) - $start; echo requests: . count($results) . PHP_EOL; echo cost: . round($cost, 3) . s . PHP_EOL; echo qps: . round(count($results) / $cost, 2) . PHP_EOL;这里的UserServiceClient就是protoc生成的那个客户端stub它继承了Hyperf的BaseClient运行时会复用同一个Hermes连接。压测结果里有两个指标要盯着QPS和P99延迟。QPS看整体吞吐能力P99延迟看最差情况下的体验。如果P99一直在涨说明服务端资源有瓶颈要去查worker进程的CPU占用、数据库连接池是否打满。有个性能优化点说一下上面的脚本每个请求都新建了GrpcClient实例这意味着每个请求都要重新建立HTTP/2连接。真实交付时应该复用连接因为gRPC的多路复用特性允许一个连接上同时跑多个请求。把GrpcClient实例缓存起来复用压测的QPS会有明显提升。我这里给的只是功能验证脚本真实的压测还应该配合监控工具看worker进程的CPU、内存、文件描述符这些指标。线上压测时服务端用top看PHP进程的CPU占用用swoole的统计接口看连接数做到心里有数。6. 部署上线的配置要点与踩坑复盘6.1 Docker镜像与生产参数线上部署我直接用的Docker。基础镜像选择phpswoole/swoole官方镜像比在Alpine Linux上手动装swoole省事得多FROM phpswoole/swoole:4.8-php8.1-alpine RUN pecl install grpc protobuf \ docker-php-ext-enable grpc protobuf WORKDIR /var/www COPY . . RUN composer install --no-dev --optimize-autoloader EXPOSE 9503 CMD [php, bin/hyperf.php, start]这个镜像里的swoole已经编译好了openssl支持如果你想在生产开启gRPC的TLS这是个必要前提。生产环境还有一个大坑不要把Nginx直接放在gRPC前面。Nginx需要配置grpc_pass才能转发gRPC流量而HTTP/2的gRPC对代理配置要求很严格稍微配置不对就报错。更稳妥的做法是直接暴露9503端口用云平台的负载均衡做TLS终止和流量分发。生产环境的worker进程数也要单独调。Swoole默认的worker_num是1这个配置对gRPC服务来说偏小了。一般按CPU核心数来设置比如4核机器设worker_num为4。但要注意worker数开太多每个worker自己的连接池、内存都会有开销要根据压测结果来平衡。6.2 几个让我折腾许久的真实问题最后分享一下这次开发中遇到的最有价值的几个问题每个都是真实踩过坑的经验文档里一般不写。问题一proto生成类的命名空间大小写问题proto里的package grpc.user;生成出来的PHP命名空间是Grpc\User而GPB生成的Message类在GPB\User下。移动目录后如果文件系统大小写不敏感本地能跑部署到Linux上就Class not found。因为composer的PSR-4自动加载在Linux下严格区分大小写。解决办法是proto文件里直接用package grpc.user;生成后手动把目录首字母统一改成和命名空间一致移动完务必执行composer dump-autoload。问题二grpc扩展版本和protoc版本不匹配生成的代码在运行时会调用GPBMetadata里的方法如果grpc扩展版本过低会报undefined method。这个坑的麻烦之处在于报错信息不会直接说是版本问题而是在某个不起眼的地方挂掉。解决思路是保持protoc和grpc扩展版本尽量一致升级grpc扩展后重启服务再次验证。问题三gRPC metadata传大token导致HTTP/2 header超限有一次把集合了多个权限点的token塞进metadata里结果请求直接报HTTP/2相关的header错误。原因是HTTP/2对header大小有限制。如果业务确实要传比较大的metadata值需要在Swoole的server配置里调整对应的buffer参数。但更合理的方案是gRPC metadata里只传token的key真实的认证信息放Redis或者配置中心服务端拿key去查。问题四中间件没有生效排查了很久最后发现是middlewares.php里配置的server name写成了http而grpc_server.php里的server name是grpc。Hyperf是按server name来匹配中间件作用范围的名字对不上中间件就静默不加载。这个问题比较隐蔽因为它不报错只有请求日志里看到鉴权没执行才会怀疑到配置上。这一路做完能明显感觉到用Hyperf做gRPC服务在PHP技术栈里是可行的甚至可以说比想象中顺畅。关键是要把proto协议设计、协程超时控制、自动加载这些基础功夫做扎实别一上来就急着写业务。把上面这些坑都趟平之后后续的每个gRPC接口开发就是纯粹的CRUD填表了。