README

允许Lumen处理Lumen的JSON-RPC 2.0请求并返回JSON-RPC 2.0响应。

此包提供了一个请求管理器，它将请求传递给RpcRequests或默认RoutesRequests调度器。

版本兼容性

安装

通过Composer

$ composer require boomdraw/rpc-core

在引导文件中更改Application类为Boomdraw\RpcCore\Application，或者提供自己的带有Boomdraw\RpcCore\Concerns\RequestManager特性的Application类。

// bootstrap/app.php

$app = new Boomdraw\RpcCore\Application(
    dirname(__DIR__)
);

更改异常处理程序

// bootstrap/app.php

$app->singleton(
    Illuminate\Contracts\Debug\ExceptionHandler::class,
    Boomdraw\RpcCore\Handler::class
);

您的Lumen应用程序已准备好处理JSON-RPC请求！

用法

RPC端点

RPC关注点仅处理针对特定端点的POST请求。

默认情况下，它使用当前应用程序版本config('app.version', '1.0')作为路由路径（POST /v1.0）。

您可以在应用程序配置文件中设置自定义RPC路径。

// config/app.php

return [
    ...
    'rpc' => 'my-custom-uri',
    ...
];

禁用JSON-RPC请求

您可以在config/app.php配置文件中禁用RPC调度器。

// config/app.php

return [
    ...
    'rpc' => false,
    ...
];

禁用路由请求

如果您只想将应用程序用作RPC，可以在config/app.php配置文件中禁用默认路由调度器。

// config/app.php

return [
    ...
    'routes' => false,
    ...
];

JSON-RPC处理器

幕后，JSON-RPC处理器的逻辑与控制器相同。它与全局和路由中间件一起工作。您可以像为Controller一样为处理器或其特定方法提供中间件。

处理器应扩展Boomdraw\RpcCore\Handler类，以拥有与控制器相同的功能。

处理器命名空间和命名

默认情况下，JSON-RPC请求关注点将在App\Rpc\Handlers命名空间中寻找后缀为Handler的处理器。您可以在配置文件中更改处理器的默认命名空间和/或后缀。

创建包含以下内容的config/rpc.php文件

<?php

return [
    /*
    | Handlers default namespace and suffix.
    */
    'handler' => [
        'path' => 'App\Rpc\Handlers',
        'suffix' => 'Handler',
    ],
    /*
     | List of custom handlers with its paths.
     | Handler key must be in a studly caps case
     | Example:
     | 'CustomHelper' => App\Handlers\CustomRpcHandler::class
     */
    'handlers' => [
        //
    ],
];

或从供应商目录复制

cp vendor/boomdraw/rpc-core/config/rpc.php config/rpc.php

在引导中注册配置文件

// bootstrap/app.php

$app->configure('rpc');

根据需要更改配置文件中的path和suffix值。

自定义处理器

您可以提供具有自定义名称和命名空间的处理器。

按上一步骤注册rpc配置文件。

在config/rpc.php文件的handlers数组的键中使用名称作为键和其类作为值添加到处理器。此处理器将不应用后缀。

您太棒了！

示例

处理器示例

// app/Rpc/Handlers/ExampleHandler.php

<?php

namespace App\Rpc\Handlers;

use Boomdraw\RpcCore\Handler;
use Illuminate\Http\Request;

class ExampleHandler extends Handler
{
    public function __invoke(Request $request)
    {
        return ['data' => ['hello' => $request->hello]];
    }

    public function message(Request $request): string
    {
        return $request->message;
    }

    public function throwException(): void 
    {
        abort(500, 'Yeah!');
    }
}

JSON-RPC请求和响应示例

POST /v1.0

{
  "jsonrpc": "2.0",
  "method": "Example",
  "params": {"args": {"hello": "world"}, "context": {"userId":  11}},
  "id": 19
}

此请求将在ExampleHandler中调用方法__invoke。RPC响应不会包裹返回的结果，因为它已经手动包裹。

{
  "jsonrpc": "2.0",
  "result": {
    "data": {"hello": "world"}
  },
  "id": 19
}

POST /v1.0

{
  "jsonrpc": "2.0",
  "method": "Example.message",
  "params": {"message": "Hello world!"},
  "id": 19
}

此请求将在ExampleHandler中调用方法message。RPC响应将返回结果作为具有data键的数组。将params对象传递给Request而不是args，因为未提供args和context对象。

{
  "jsonrpc": "2.0",
  "result": {
    "data": "Hello world!"
  },
  "id": 19
}

POST /v1.0

{
  "jsonrpc": "2.0",
  "method": "Example.throwException",
  "id": 19
}

此请求将在ExampleHandler中调用方法throwException。RPC错误响应将被返回。

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Yeah!"
  },
  "id": 19
}

您可以在官方规范中了解更多关于JSON-RPC请求和响应的信息。

上下文

传递给params对象中的context对象的数据将被存储在请求对象中。您可以使用context辅助函数获取这些数据。

// function context(string $key, $default = null)

context('userId', 'default')

此上下文调用的结果将是context对象中的userId或如果没有userId字段或在context中不是JSON-RPC请求时，将返回字符串default。

JSON-RPC请求id始终传递到上下文中。

调用先前示例中的context('requestId')的结果将是19。

响应

当处理程序返回原始数据时，如果需要，它将被包裹成带有data键的数组，然后传递给Boomdraw\RpcCore\Responses\RpcResponse进行响应结构构建。

如果处理程序返回Illuminate\Http\Response或Symfony\Component\HttpFoundation\Response，它将被转换为带有数据包裹和HTTP状态码200的Boomdraw\RpcCore\Responses\RpcResponse。

如果处理程序不返回任何数据，将返回不带有效负载和HTTP状态码204的Boomdraw\RpcCore\Responses\RpcEmptyResponse。

对于非JSON-RPC请求，应用程序将默认方式处理响应。

错误响应

RPC-core包提供了一个异常处理器，将异常转换为符合JSON-RPC规范的格式。

所有错误响应都将返回HTTP状态码200。

对于服务器错误（代码>=500），将返回内部代码为-32000的错误响应。

对于代码在400到499之间的异常，将返回带有相同代码但前面带有负号的错误响应。例如：对于405错误代码，将返回内部代码为-405的响应。

验证异常将被转换为Boomdraw\RpcCore\Exceptions\InvalidParamsRpcException并返回代码-32602。

测试

测试辅助类

该包提供了一个类，使JSON-RPC处理程序的测试变得容易。

将Boomdraw\RpcCore\Tests\RpcTrait特性添加到您的TestCase.php中。

现在您可以使用以下方法：

send

public function send(string $method, array $args = [], array $context = [])

将提供的参数转换为JSON-RPC请求，并将其传递给调度器。

getRpcData

public function getRpcData(string $key = '')

从RPC响应的data对象中提取提供的键字段，如果键为空，则返回data作为数组。

responseAsArray

public function responseAsArray(): array

使用json_decode将响应作为数组返回。

seeJsonRpc

public function seeJsonRpc(array $data = []): self

断言响应包含提供的数据。

seeJsonRpcError

public function seeJsonRpcError(array $data = []): self

断言错误响应包含提供的数据。

包测试

您可以使用以下命令运行测试：

composer test

变更日志

请参阅变更日志以获取有关最近更改的更多信息。

贡献

请参阅贡献以获取详细信息及待办事项列表。

安全性

如果您发现任何与安全相关的漏洞，请通过pkgsecurity@boomdraw.com发送电子邮件，而不是使用问题跟踪器。

许可证

MIT