README

描述

JsonRpc 客户端 - JsonRpc 服务器客户端实现。遵循 JsonRpc 2.0 规范。经过测试，可与 Tochka 的原始 JsonRpc 服务器兼容。

安装

Laravel

1. composer require tochka-developers/jsonrpc-client
2. 发布配置

php artisan vendor:publish --provider="Tochka\JsonRpcClient\JsonRpcClientServiceProvider"

Lumen

1. composer require tochka-developers/jsonrpc-client
2. 将包中的配置（vendor/tochka-developers/jsonrpc/config/jsonrpc-client.php）复制到项目（config/jsonrpc-client.php）中
3. 在 bootstrap/app.php 中连接配置

$app->configure('jsonrpc-client');

1. 在 bootstrap/app.php 中启用支持门面

$app->withFacades();

1. 如果您打算使用自动代理客户端生成 - 在 bootstrap/app.php 中注册服务提供者 Tochka\JsonRpcClient\JsonRpcClientServiceProvider

$app->register(Tochka\JsonRpcClient\JsonRpcClientServiceProvider::class);

使用

配置

配置文件位于 app/jsonrpc-client.php。在此文件中指定所有 JsonRpc 连接的设置。

• clientName - 客户端名称。该名称将作为所有请求 ID 的前缀。有助于识别服务。
• default - 默认连接。应包含连接名称。
• connections - 连接数组。每个连接都必须具有唯一的键（连接名称）。

连接设置

• url - 连接到 JsonRpc 服务器的 URL 地址（或 IP）。必须包含到入口点的完整路径（例如：https://api.jsonrpc.com/v1/jsonrpc）。
• clientClass - 作为代理类使用的类。需要指定完整名称（带命名空间）。用于自动生成代理类。
• extendedStubs - 生成扩展 API 描述，以类辅助器形式表示输入和输出参数
• options - 连接选项数组（见 https://docs.guzzlephp.org/en/stable/request-options.html）
• middleware - 准备请求发送之前使用的中间件类列表。可能以数组形式列出中间件类，或者如果需要传递到类中额外的参数，则将中间件类作为数组的键，将包含参数的数组作为值。

包中提供了两个中间件

• AuthTokenMiddleware - 标头中按令牌进行身份验证的类。参数：name - 标头名称，value - 令牌值
• AuthBasicMiddleware - Basic 身份验证类。参数：scheme - 身份验证类型（basic、digest、ntlm），username 和 password - 身份验证数据
• AdditionalHeadersMiddleware - 用于添加自定义标头的类。参数：headers - 包含标头的关联数组，其中键是标头名称，值是标头值。

代理类生成

代理类是包含有关所有可用 JsonRpc 服务器方法的信息的 JsonRpcClient 门面，同时将传递给方法的参数映射为关联数组。如果服务器能够返回 SMD 方案，则可以自动生成此类。

要生成类，请使用以下命令

php artisan jsonrpc:generateClient connection

为了成功生成，必须满足以下条件

1. JsonRpc 服务器必须支持返回 SMD 方案（通过传递 GET 参数 ?smd）
2. 建议使用 tochka-developers/jsonrpc 作为服务器。该包能够返回用于更精确代理类生成的扩展信息
3. 必须指定 JsonRpc 服务器的 URL 地址
4. 必须指定完整的代理类名。类文件的路径将根据命名空间和 composer 设置自动生成。
5. 存放代理类的文件夹必须具有写入权限。

如果满足所有条件，则将在指定的连接上创建代理类。如果要更新代理类（例如，在服务器方法更新时） - 请重新执行指定的命令。如果要为所有指定的连接生成类，请不指定连接执行该命令

php artisan jsonrpc:generateClient

方法调用

调用 JsonRpc 方法

//....
$result = Api::fooBar('Some text');

客户端支持通过一个请求调用多个远程方法

$api = Api::batch();
$api->foo('params');
$api->bar(123);
$api->someMethod(1, true);
[$resultFoo, $resultBar, $resultSome] = $api->execute();

客户端支持使用 cache 方法进行结果缓存

$result = Api::cache(10)->fooBar('Some text');

在这种情况下，结果将被缓存 10 分钟，并且在后续调用此方法具有相同参数时，不会向服务器发送请求，结果将从缓存中直接获取。当然，只有成功的调用结果才会被缓存。

同样，多个调用也支持缓存

$api = Api::batch();
$resultFoo = $api->cache(10)->foo('params');
$resultBar = $api->bar(123);
$resultSome = $api->cache(60)->someMethod(1, true);
[$resultFoo, $resultBar, $resultSome] = $api->execute();

请注意，只有调用 cache 方法之前的方法才会被缓存。

中间件

中间件类允许修改出站请求，例如添加额外的标题、启用授权或修改请求体。

您可以通过在配置中指定类名来使用自己的类。有两种类型的中间件。第一种针对每个具体的 JsonRpc-请求进行交互，即使它们在批处理模式下运行。第二种类型在整个传输请求中运行一次。

第一种类型的中间件会在请求中的每个方法调用时运行。也就是说，如果执行了包含 3 个方法调用的批处理请求 - 每个中间件将针对每个调用的方法运行一次。

第二种类型的中间件将在整个请求中只运行一次，并将整个调用栈传递给它。第二种类型适用于处理添加头、授权和其他传输请求修改的中间件。

中间件类必须实现一个方法 - handle。前两个参数是必需的。处理请求中每个调用的示例中间件（第一种类型）

class SomeMiddleware
{
    public function handle(\Tochka\JsonRpcClient\Request $request, \Closure $next): void
    {
        // ...
        return $next($request);
    }
}

处理整个请求的示例中间件

class SomeMiddleware implements \Tochka\JsonRpcClient\Contracts\OnceExecutedMiddleware
{
    /**
     * @param \Tochka\JsonRpcClient\Standard\JsonRpcRequest[] $requests
     * @param \Closure         $next
     */
    public function handle(array $requests, \Closure $next): void
    {
        // ...
        return $next($requests);
    }
}

要继续执行中间件链，必须在方法中调用方法 $next，并将当前版本的 $request 传递给它。此外，您可以在 handle 方法的参数中使用

• 配置中传递的额外参数

// config
'middleware'  => [
    \Tochka\JsonRpcClient\Middleware\AuthTokenMiddleware::class => [
        'name'  => 'X-Access-Key',
        'value' => 'TokenValue',
    ],
]

// middleware
use Tochka\JsonRpcClient\Request;

class AuthTokenMiddleware implements \Tochka\JsonRpcClient\Contracts\OnceExecutedMiddleware
{
    public function handle(array $request, \Closure $next, $value, $name = 'X-Access-Key') 
    {
        // ...

        return $next($request);
    }
}

参数的顺序不重要，配置中指定的值将按参数名称传递给中间件。

• 上下文类 Tochka\JsonRpcClient\Contracts\TransportClient 和 Tochka\JsonRpcClient\ClientConfig。如果参数指定了这些类型之一，则在调用时将传递负责构建传输请求的当前实例的类（例如，配置的 Tochka\JsonRpcClient\Client\HttpClient 类实例）或具有当前连接配置的类。
• DI Laravel 中注册的任何其他类/合同/外观

[]: https://docs.guzzlephp.org/en/stable/request-options.html(描述)