Hyperf 3.0 的 RPC 服务契约必须是两端完全一致的 PHP 接口文件（含命名空间、方法签名、参数与返回类型），应置于共享 Composer 包中；混用 jsonrpc-http 与 jsonrpc-tcp 会导致 Transporter 和 Packer 不兼容，引发连接拒绝或解析失败。
Hyperf 3.0 的 RPC 不是“加个包就能用”的黑盒，而是需要明确协议选型、服务契约对齐、注册发现联动的协作系统。跳过契约定义或混用 jsonrpc-http 与 jsonrpc-tcp 客户端配置，90% 的调用失败都源于此。
如何定义和复用服务接口契约？
契约不是文档，是 PHP 接口文件，必须在提供者和消费者两端完全一致（包括命名空间、方法签名、参数类型）。
- 接口文件应放在共享包（如
commonComposer 包）中，而非仅存于服务提供者项目内 - 方法返回类型不能省略，
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 端口。协议头、连接管理、超时机制均不兼容。
- 服务端配置了
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，只会在线上流量高峰时突然爆发。
