EasySwoole

发起 RPC 调用

用固定节点验证

按服务端示例启动服务后,在同一个项目根目录创建 rpc-client.php。这个 CLI 进程独立初始化 MyRpc,并为 User 服务指定本机节点。

<?php

use App\Rpc\MyRpc;
use EasySwoole\Rpc\Config\RpcConfig;
use EasySwoole\Rpc\Config\SecurityConfig;
use EasySwoole\Rpc\Server\ServiceNode;

require __DIR__ . '/vendor/autoload.php';

MyRpc::getInstance(new RpcConfig(
    security: new SecurityConfig(apiKey: 'local-demo-key'),
));

MyRpc::getInstance()->getNodeManager()->online(new ServiceNode(
    serviceName: 'User',
    nodeId: 'user-rpc-1',
    nodeName: 'user-rpc-1',
    nodeWeight: 10,
    host: '127.0.0.1',
    port: 9601,
));

\Swoole\Coroutine\run(static function (): void {
    $batch = MyRpc::getInstance()->client()->buildRequest();
    $batch->addCall('User.Profile.detail')->setArg(['id' => 1001]);
    $response = $batch->exec(timeout: 1.0)['User.Profile.detail'];

    if (!$response->isSuccess()) {
        throw new RuntimeException(sprintf(
            '%s: %s',
            $response->getStatus()->name,
            $response->getMsg(),
        ));
    }

    echo $response->toJson(), PHP_EOL;
});

运行 php rpc-client.php。响应的 status 为 0,result 包含 id、name 和 requestUUID。业务只需要 Action 返回值时,使用 $response->getResult()。

在 HTTP Worker 中使用

在启用了协程的控制器或业务服务中,从 MyRpc::getInstance()->client()->buildRequest() 开始创建每次请求自己的批次,直接执行上面的调用代码。节点应已由应用配置或服务发现提供。

同一批次可用 addCall() 加入多个不同路径,exec() 并发执行,按完整路径返回 Response。每个路径在同一批次中只能加入一次。timeout 是单个调用的总预算,单位为秒,连接、收发和重试共用该预算。

响应状态 排查方向
NOT_AVAILABLE_NODE 检查服务名、节点登记和节点有效期
NODE_LOOKUP_FAILED 检查注册中心或自定义节点管理器
TRANSPORT_ERROR 检查通告的 TCP 地址、端口和网络连通性
RESPONSE_DECODE_ERROR 检查 API key、时钟、响应内容和请求 UUID

单次调用的回调

在协程内为每个调用分别设置回调。下面的查询是只读操作,允许在节点故障策略许可且还有时间预算时重试一次。

use App\Rpc\MyRpc;
use EasySwoole\Rpc\Protocol\Response;

$batch = MyRpc::getInstance()->client()->buildRequest();
$batch->addCall('User.Profile.detail')
    ->setArg(['id' => 1001])
    ->setClientArg(['traceId' => 'trace-001'])
    ->enableRetry(1)
    ->setOnSuccess(static function (Response $response): void {
        // 这里可以记录成功指标,结果仍可从 exec() 读取。
        error_log('[RPC OK] ' . $response->getRequestUUID());
    })
    ->setOnFail(static function (Response $response): void {
        error_log('[RPC failed] ' . $response->getStatus()->name);
    });

$responses = $batch->exec(timeout: 3.0);
$response = $responses['User.Profile.detail'] ?? null;

setArg() 传业务参数,setClientArg() 传链路 ID 等附加信息,服务端通过 Request::getClientArg() 读取。成功和失败回调接收最终的 Response。想在框架选节点之外指定目标时,可以对调用设置 setServiceNode($node),节点所属服务须与路径第一段一致。

每个批次只执行一次,后续调用重新执行 buildRequest()。默认关闭重试。默认故障策略根据节点健康标记与连续失败次数决定是否保留、换节点尝试或下线。网络超时后 Action 可能已执行,写操作需有业务幂等保障才能重试。

客户端全局异常回调

在调用方初始化 MyRpc 后注册一次:

use App\Rpc\MyRpc;

MyRpc::getInstance()->client()->setOnException(static function (\Throwable $error): void {
    error_log('[RPC client exception] ' . $error->getMessage());
});

常见网络失败和无可用节点通过失败 Response 返回。未预期的节点查询、选择策略或调用回调异常进入客户端全局回调。未配置回调时,异常会从调用协程抛出。配置回调接管异常后,若异常发生在取得响应之前,exec() 的结果会缺少对应路径。若已取得响应,调用回调抛出的异常仍会上报,但响应会保留。批次创建、非法路径和调用环境等同步错误应在对应调用处捕获 RpcException。