Hyperf 的 RPC 是围绕契约、协议、传输和治理四环节构建的可组合能力体系。契约即 PHP 接口，需双方共用；支持 JSON-RPC（HTTP/TCP）与 gRPC 三种协议选型；服务需显式注解注册至 Consul 等中心；客户端通过工厂创建代理，像调本地方法一样调用，自动处理序列化、寻址与负载均衡。
Hyperf 的 RPC 不是“加个插件就能用”的黑盒，而是围绕契约、协议、传输和治理四个核心环节组织起来的一套可组合能力。它不强制绑定某一种通信方式，而是让开发者按需拼装：接口定义写一次，服务端用 JSON-RPC 或 gRPC 发布，客户端用对应协议调用，再叠加 Consul 注册发现或链路追踪，整个过程清晰可控。
定义统一的服务契约
契约是 RPC 调用的起点，本质是一个 PHP 接口（Interface），必须同时出现在服务提供方和服务消费方的代码中，保证方法签名一致。
- 接口文件通常放在 app/JsonRpc/ 或 app/Grpc/ 目录下，命名如 UserServiceInterface.php
- 方法需明确声明参数类型与返回类型，例如 public function getUser(int $id): array;，这是跨语言兼容和 Protobuf 生成的基础
- 不建议在接口里写业务逻辑，只描述“能做什么”，具体实现由服务类完成
选择并配置通信协议
Hyperf 支持三种主流协议，选型取决于场景需求：
- JSON-RPC over HTTP：适合调试快、前端联调方便、团队以 PHP/JS 为主；配置简单，直接复用 Swoole HTTP Server
- JSON-RPC over TCP：比 HTTP 少一层解析开销，适合内部高频调用；需单独启动 TCP Server，端口如 9502
- gRPC：强类型、高性能、支持流式传输；需编写 .proto 文件，通过 protoc 生成 PHP 类；适合混合技术栈或对延迟敏感的场景
发布服务与注册到服务中心
服务不是“跑起来就自动被发现”的，需要显式声明并注册。常用方式是注解 + 配置：
- 在服务实现类上加 @RpcService 注解，指定 name（服务唯一标识）、protocol（如 jsonrpc）、server（对应 config/autoload/server.php 中定义的 server 名）
- 若需服务发现，加上 publishTo="consul"，前提是已安装 hyperf/service-governance-consul 并发布配置
- 服务启动时，框架自动向 Consul 注册实例信息（IP、端口、健康检查路径等），消费者即可动态拉取节点列表
客户端调用就像调用本地方法
消费者无需处理网络细节，Hyperf 提供了高度封装的客户端工厂：
- 通过 ClientFactory 创建对应服务的代理对象，例如 $client = (new ClientFactory())->create('UserService', 'jsonrpc');
- 直接调用接口定义的方法，如 $user = $client->getUser(123);，底层自动完成序列化、寻址、重试、负载均衡
- 若使用 Consul，节点变动（如扩容缩容）对调用方完全透明，客户端会自动刷新可用列表
