必须定义标准PHP接口作为RPC服务契约，存放于app/JsonRpc/或app/Grpc/目录，命名与文件名一致，声明完整类型提示和PHPDoc，通过dependencies.php绑定实现类，并按JSON-RPC/gRPC协议规范调整签名，最后执行autoload扫描与客户端代理验证。
如果您在 Hyperf 项目中需要对外提供远程过程调用能力，但尚未定义服务契约，则无法启动 RPC 服务或被客户端识别。以下是定义 RPC 服务接口的具体方法：
一、创建标准 PHP 接口文件
RPC 服务接口本质是一个纯 PHP 接口（Interface），用于声明可被远程调用的方法签名，是服务提供方与消费方必须共用的契约。该接口不包含实现逻辑，仅描述“能做什么”，确保类型安全与跨端一致性。
1、在项目目录下创建接口存放路径，推荐使用 app/JsonRpc/ 或 app/Grpc/ 子目录；
2、新建 PHP 文件，例如 CalculatorServiceInterface.php；
3、定义命名空间为 App\JsonRpc（若使用 JSON-RPC）或 App\Grpc（若使用 gRPC）；
4、声明接口并显式标注参数与返回值类型，例如：
public function add(int $a, int $b): int;；
5、为每个方法添加 PHPDoc 注释，说明用途与参数含义，便于生成文档与 IDE 提示。
二、遵循接口设计规范
接口需满足 Hyperf RPC 框架对契约的强制要求，否则会导致服务注册失败、客户端代理生成异常或类型解析错误。规范约束直接影响序列化、协议适配与服务中心元数据生成。
1、接口必须使用 interface 关键字声明，不可为 abstract class 或 trait；
2、所有方法必须声明完整的标量或数组类型提示，禁止使用 mixed、void（除构造方法外）或无类型声明；
3、返回类型若为对象，须对应具体类名且该类已通过自动加载可访问，或使用 array 表示结构化响应；
4、接口内不得包含属性、常量或静态方法；
5、文件命名须与接口名严格一致，且首字母大写，例如 UserServiceInterface 对应 UserServiceInterface.php。
三、配置依赖注入映射
Hyperf 需通过容器明确知道哪个具体类实现了该接口，才能在服务端实例化、在客户端生成代理。该映射关系是运行时解析契约与实现绑定的关键依据。
1、打开 config/autoload/dependencies.php 文件；
2、在返回数组中添加一项，键为接口全限定名，值为其实现类全限定名；
3、格式示例：
App\JsonRpc\CalculatorServiceInterface::class => App\JsonRpc\CalculatorService::class；
4、确保实现类已存在且正确 implements 该接口；
5、若使用 Consul 等服务中心，此映射仍为必需，否则服务注册时无法获取有效实例。
四、适配不同协议的接口约定
JSON-RPC 与 gRPC 对接口语义存在差异化约束，定义时需按协议特性调整方法签名与注释结构，否则将引发协议层序列化失败或服务端拒绝注册。
1、JSON-RPC 接口方法名必须为合法 PHP 方法标识符，不支持重载，参数建议扁平化（避免嵌套对象传参）；
2、gRPC 接口需配合 .proto 文件生成，PHP 接口方法名须与 rpc 定义名称一致，参数类型必须映射至 Protobuf 支持的基础类型；
3、若接口同时供 JSON-RPC 与 gRPC 使用，方法签名应取交集：仅使用 int、string、bool、float、array 等通用类型；
4、gRPC 接口需额外定义 ServiceStatus 类等辅助类型，并确保其可序列化；
5、JSON-RPC 接口方法返回值建议统一为 array，以兼容 HTTP 响应体结构。
五、验证接口定义有效性
定义完成后需确认接口可被框架正确识别与加载，避免因命名空间、自动加载或语法错误导致后续服务注册静默失败。
1、执行 composer dump-autoload 更新自动加载映射；
2、运行 php bin/hyperf.php di:scan 扫描依赖注入配置；
3、检查控制台是否输出 "Found interface App\JsonRpc\XXXInterface" 类似日志；
4、启动服务后访问 /server/info（如启用 HttpServer）查看已注册接口列表；
5、尝试调用 php bin/hyperf.php rpc:client --interface=App\JsonRpc\XXXInterface 生成客户端代理，观察是否报错。
