Hyperf 3.0 JSON-RPC服务需三处精准配置：1. RpcService注解必须严格绑定接口契约（name、protocol="jsonrpc-http"、server名一致）；2. server.php中HTTP服务器须显式挂载Hyperf\JsonRpc\HttpServer::onRequest回调；3. 服务端口需未被占用且与消费者nodes中host:port完全匹配。
Hyperf 3.0 的 JSON-RPC 服务不是「配好就能用」，关键在三处：注解必须精准绑定接口契约、server.php 中的 HTTP 服务器配置要匹配协议栈、服务端口不能被其他进程占用且需与消费者节点一致。
注解定义必须严格对应接口契约
Hyperf 不靠函数签名推断服务，而是靠 RpcService 注解和接口类（Interface）的双向绑定。一旦不一致，消费者注入时会报 ClassNotFoundException 或 ContainerException。
-
RpcService的name参数必须与消费者配置中consumers[].name完全一致（区分大小写） -
service属性在注解里不填，但接口类必须被消费者项目真实引入并声明为依赖类型——即消费者代码里use App\Rpc\CalculatorServiceInterface且注入类型是该接口 - 接口方法参数类型必须显式声明（如
int $a），否则 JSON-RPC 解析时可能因类型擦除失败而返回Invalid params - 注解中的
protocol="jsonrpc-http"是硬编码值，不能写成jsonrpc或http，否则客户端无法识别协议处理器
server.php 中的 HTTP 服务器必须启用 jsonrpc-http 回调
Hyperf 3.0 默认的 SERVER_HTTP 类型服务器不会自动支持 JSON-RPC；必须手动挂载 Hyperf\JsonRpc\HttpServer::onRequest 回调，否则请求进来直接 404 或返回 HTML 欢迎页。
- 检查
config/autoload/server.php的servers数组，确保存在名为jsonrpc-http的 server 条目（名字必须和注解中server字段一致） -
callbacks[SwooleEvent::ON_REQUEST]必须指向[Hyperf\JsonRpc\HttpServer::class, 'onRequest']，而不是默认的[Hyperf\HttpServer\Server::class, 'onRequest'] - 端口（如
port => 9802）需避开宿主机或 Docker 冲突端口；若用 Docker，确认-p 9802:9802映射正确，且容器内未被supervisord或其他 PHP 进程占用 - 不要复用已有 HTTP 服务（如
httpserver）来承载 JSON-RPC，协议解析逻辑不同，混用会导致Parse error: not an object类错误
消费者 nodes 配置必须精确到 host:port，且协议栈兼容
消费者发起调用时，nodes 列表不是“备用地址”，而是唯一寻址依据。填错 IP、端口或协议，会卡在连接超时或抛出 Connection refused。
-
nodes中的host值填0.0.0.0在容器内无效——应填服务提供者容器名（Docker 网络）或宿主机 IP（桥接模式），例如"host" => "hyperf-server"或"host" => "172.18.0.3" -
port必须和服务端server.php中定义的port一致，且该端口在容器内真实监听（可用netstat -tlnp | grep :9802验证） - Hyperf 3.0 默认使用
jsonrpc-http协议走 HTTP/1.1，不支持 HTTP/2；若 Nginx 做了代理，需关闭http2或明确透传Content-Type: application/json - 若启用 Consul 服务发现，
publishTo="consul"注解字段必须存在，且config/autoload/consul.php中的uri可连通（如"http://consul:8500"），否则消费者查不到节点
最容易被忽略的是：Hyperf 3.0 的 JSON-RPC 客户端在构造请求时默认不带 Content-Length，某些严格模式的反向代理（如 Caddy v2.7+）会直接拒绝请求；遇到 400 错误时，先抓包确认请求头是否完整，再排查是否漏了 jsonrpc-http 回调绑定。
