README

此包提供了一种简单的方法来实现具有完整规范支持的json-rpc服务器。包支持在一个请求中执行多个过程调用，如规范所述。

JSON-RPC 规范与 CQRS 架构完全兼容

安装

composer require mops1k/json-rpc-bundle

在路由中导入路由声明

#config/routes/json-rpc.yaml
app_file:
    # loads routes from the given routing file stored in some bundle
    resource: '@JsonRpcBundle/Resources/config/routing/json-rpc-bundle.yaml'

或者通过模板添加自己的路径

json_rpc_entrypoint:
    path: '/path/to/rpc'
    methods: 'POST'
    controller: 'JsonRpcBundle\Controller\JsonRpcController'

json_rpc_namespace_entrypoint:
    path: '/path/to/rpc/{namespace}'
    methods: 'POST'
    controller: 'JsonRpcBundle\Controller\JsonRpcController'

用法

要创建方法，您必须创建具有属性 \JsonRpcBundle\Attribute\AsRpcMethod 的可调用类，其中 methodName 构造函数参数必须包含方法名。示例

<?php

use JsonRpcBundle\Attribute\AsRpcMethod;
use Symfony\Component\Validator\Constraints\Collection;
use Symfony\Component\Validator\Constraints\GreaterThanOrEqual;

#[AsRpcMethod('methodWithoutContract')]
class MethodWithoutContract
{
    public function __invoke(int $id): int
    {
        return $id;
    }
}

合同请求 DTO

包提供向您的 DTO 类提供参数的可能性。为此功能，您必须添加属性 \JsonRpcBundle\Attribute\RpcMethodContract。传递的 DTO 支持通过 symfony/validator 进行验证。示例

<?php

use JsonRpcBundle\Attribute\AsRpcMethod;
use JsonRpcBundle\Attribute\RpcMethodContract;
use JsonRpcBundle\Tests\Stubs\Contract\Contract;
use Symfony\Component\Validator\Constraints as Assert;

readonly class Contract
{
    public function __construct(
        #[Assert\GreaterThanOrEqual(0)]
        public int $id,
        #[Assert\NotBlank(allowNull: false)]
        public ?string $text = null,
    ) {
    }
}

#[AsRpcMethod('methodWithContract')]
#[RpcMethodContract(Contract::class)]
class MethodWithContract
{
    public function __invoke(Contract $contract): array
    {
        return [
            'id' => $contract->id,
            'text' => $contract->text,
        ];
    }
}

无合同的方法参数验证

如果您不想使用 DTO，您仍然可以验证方法参数并设置其组。在这种情况下，您需要从 \JsonRpcBundle\MethodResolver\ValidateMethodParametersInterface 实现您的类方法。示例

<?php

use JsonRpcBundle\Attribute\AsRpcMethod;
use JsonRpcBundle\MethodResolver\ValidateMethodParametersInterface;
use Symfony\Component\Validator\Constraints\Collection;
use Symfony\Component\Validator\Constraints\GreaterThanOrEqual;
use Symfony\Component\Validator\Constraints\GroupSequence;

#[AsRpcMethod('methodWithoutContract')]
class MethodWithoutContract implements ValidateMethodParametersInterface
{
    public function __invoke(int $id): int
    {
        return $id;
    }

    public function configureValidation(): Collection
    {
        return new Collection([
            'id' => [
                new GreaterThanOrEqual(0),
            ],
        ], groups: ['rpc']);
    }

    public function validationGroups(): array|string|GroupSequence|null
    {
        return ['rpc'];
    }
}

通知

Json rpc 支持通知请求，不返回任何响应。要将方法作为通知，只需在 __invoke 返回类型提示中添加 void。示例

use JsonRpcBundle\Attribute\AsRpcMethod;

#[AsRpcMethod('updateUser')]
class UpdateUser
{
    public function __invoke(int $id): void
    {
        // some logic
    }
}

命名空间

包支持方法命名空间。要设置方法命名空间，请使用 \JsonRpcBundle\Attribute\AsRpcMethod::$namespace 属性参数。示例

use JsonRpcBundle\Attribute\AsRpcMethod;

#[AsRpcMethod(methodName: 'update', namespace: 'user')]
class UpdateUser
{
    public function __invoke(int $id): void
    {
        // some logic
    }
}

要获取命名空间方法，您可以通过方法名（namespace.methodName）调用它，或者调用到路径 /rpc/{namespace} 并使用常规方法名。示例

1. 调用 /rpc

   {
     "jsonrpc": "2.0",
     "method": "user.update",
     "params": null,
     "id": 32
   }

2. 调用 /rpc/user

   {
     "jsonrpc": "2.0",
     "method": "update",
     "params": null,
     "id": 32
   }

此功能也支持批量请求。

API 文档

包支持通过 nelmio/api-doc-bundle 生成半自动文档。默认情况下，文档从方法参数和方法规范生成参数。如果您需要更具体的参数文档，请使用 OA\Property 属性。如果您需要特定的响应结果，请使用 \JsonRpcBundle\ApiDoc\Attribute\Result 属性（在 $properties 参数中设置数组 OA\Property）。对象响应通过其描述自动生成到文档中。