hyperf 3.0 的 rpc 服务契约必须是两端完全一致的 php 接口文件（含命名空间、方法签名、参数与返回类型），应置于共享 composer 包中；混用 jsonrpc-http 与 jsonrpc-tcp 会导致 transporter 和 packer 不兼容，引发连接拒绝或解析失败。

Hyperf 3.0 的 RPC 不是“加个包就能用”的黑盒，而是需要明确协议选型、服务契约对齐、注册发现联动的协作系统。跳过契约定义或混用 jsonrpc-http 与 jsonrpc-tcp 客户端配置，90% 的调用失败都源于此。

如何定义和复用服务接口契约？

契约不是文档，是 PHP 接口文件，必须在提供者和消费者两端完全一致（包括命名空间、方法签名、参数类型）。

• 接口文件应放在共享包（如 common Composer 包）中，而非仅存于服务提供者项目内
• 方法返回类型不能省略，int 和 int|null 在 Normalizer 层处理逻辑不同，会导致反序列化失败
• 若使用 gRPC，需额外维护 .proto 文件，并通过 protoc 生成 PHP 类；此时接口类由工具生成，不可手写覆盖
• 常见错误：Call to undefined method App\JsonRpc\CalculatorServiceInterface::add() —— 实际是消费者加载的接口类没被自动加载器识别，检查 composer.json 的 autoload 配置是否包含该路径

为什么 jsonrpc-http 和 jsonrpc-tcp 不能混用？

它们底层 Transporter 和 Packer 完全不同：jsonrpc-http 依赖 Hyperf\HttpClient 发起 HTTP 请求，jsonrpc-tcp 使用 Swoole\Coroutine\Client 直连 TCP 端口。协议头、连接管理、超时机制均不兼容。

Hyperframes Creative

HyperFrames视频非动画创意指导，包括设计规范（frame.md/design.md）处理、配色、字体设计、旁白及节奏规划等。

下载

• 服务端配置了 jsonrpc-tcp（监听 9503），但客户端配置 'protocol' => 'jsonrpc-http' → 连接被拒绝或返回 HTML 错误页
• 反之，HTTP 服务端无法解析 TCP 流中的 EOF 分隔帧，会卡住或抛出 Invalid response
• 查看实际通信协议，最简单方式是抓包：tcpdump -i lo port 9503 -A（TCP） 或 curl -v http://127.0.0.1:9503（HTTP）
• Hyperf 3.0 默认推荐 jsonrpc-http，因调试友好、能复用 Nginx/HTTPS、兼容性更广；高吞吐内部调用可切 jsonrpc-tcp

服务注册后，客户端为何仍报 “No service found”？

这不是网络不通，而是服务治理层未匹配到可用节点。Hyperf 的服务发现是运行时行为，依赖 governance 组件主动拉取元数据。

• 确认已安装并启用治理组件，例如 hyperf/service-governance-nacos 或 hyperf/consul，且 config/autoload/services.php 中 providers 配置了正确 publishTo 值（如 'nacos'）
• 检查服务提供者启动日志，搜索 RegisterServiceListener 是否成功输出 Registered service xxx；失败常因 Consul/Nacos 地址不可达或 ACL token 权限不足
• 客户端必须配置 'load_balancer' => 'random'（或其他策略），且 consumers 中 'name' 必须与提供者注册的 service name 完全一致（大小写敏感）
• 开发环境临时绕过治理：直接在 consumers 中写死 'nodes'，但上线前必须移除，否则失去负载均衡和故障转移能力

调用延迟高，是协议问题还是中间件阻塞？

先排除中间件，再看协议。Hyperf 的中间件链默认开启超时控制、链路追踪、日志记录，任一环节慢都会拖累整体。

• 关闭所有中间件测试基准性能：config/autoload/middlewares.php 中清空 Hyperf\RpcClient\Middleware\* 数组
• 对比 jsonrpc-http 和 gRPC 同样接口：若 gRPC 快 3 倍以上，说明 HTTP 序列化/解析开销是瓶颈；此时应检查是否启用了 gzip 压缩（服务端需配 response_compression）
• gRPC 延迟高？确认客户端和服务端 Protobuf 版本一致（Hyperf 3.0 要求 google/protobuf ≥ v4.25.0），旧版本存在序列化性能 regressions
• 真实瓶颈常在业务逻辑：用 Hyperf\Tracer\Aspect\TraceAspect 打点，看耗时是否集中在某个方法内，而非 RPC 框架层

RPC 调用看似一行代码，背后是契约、协议、治理三层对齐。最容易被忽略的是：服务提供者改了接口方法但没同步更新消费者端的契约文件，而 PHP 不报错，只在运行时返回 null 或类型异常 —— 这类问题不会出现在 CI，只会在线上流量高峰时突然爆发。