README

JSON-RPC 是一种使用 JSON 编码的远程过程调用协议。它是一个非常简单的协议（与 XML-RPC 非常相似），仅定义了少量数据类型和命令。JSON-RPC 允许发送通知（发送到服务器但不需要响应的数据）和多个调用可以发送到服务器，这些调用可能以不同的顺序得到响应。

维基百科 | 规范

安装

Symfony >= 6.4 或 7.0

composer require timiki/rpc-server-bundle "^6.4"

Symfony >= 6.0

composer require timiki/rpc-server-bundle "^6.0"

已弃用的版本

Symfony >= 5.0 使用版本 ^5.0

composer require timiki/rpc-server-bundle "^5.0"

Symfony >= 4.3 使用版本 ^4.1

composer require timiki/rpc-server-bundle "^4.1"

Symfony < 4.3 使用版本 ^4.0

composer require timiki/rpc-server-bundle "^4.0"

配置

rpc_server:
    
    # Mapping configs

    # Default mapping
    #   mapping: '%kernel.project_dir%/src/Method' 
    #
    # Multi dir mapping
    #   mapping:
    #   - '%kernel.project_dir%/src/Method1'
    #   - '%kernel.project_dir%/src/Method2'  
    # 
    # Multi handler|dir mapping
    #   mapping:
    #    v1:
    #       - '%kernel.project_dir%/src/Method/V1'
    #    v2:
    #       - '%kernel.project_dir%/src/Method/V2'
    #   
    
    mapping: '%kernel.project_dir%/src/Method'
            
    # Cache pool name
    
    cache: null
    
    # Serializer service, must be instanced of Timiki\Bundle\RpcServerBundle\Serializer\SerializerInterface
    # By default use Timiki\Bundle\RpcServerBundle\Serializer\BaseSerializer
    
    serializer: null

    parameters:
        
        # Allow extra params in JSON request
        allow_extra_params: false

将方法目录添加到自动装配排除列表中

    App\:
        resource: '../src/*'
        exclude: '../src/{Method}'

控制器

默认

您可以使用自己的控制器来处理 JSON-RPC 请求。例如

<?php

declare(strict_types=1);

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;

class RpcController extends AbstractController
{
    public function indexAction(Request $request)
    {
        return $this->get('rpc.server.http_handler.default')->handleHttpRequest($request);
    }
}

或将默认 JSON-RPC 路由（默认 POST 到 /rpc）添加到 routing.yml 中

rpc:
    path: /rpc
    defaults: { _controller: Timiki\Bundle\RpcServerBundle\Controller\RpcController::handlerAction }
    methods: [POST]

或不同处理器（版本）的控制器

rpc:
    path: /{version}
    defaults: { _controller: Timiki\Bundle\RpcServerBundle\Controller\RpcController::handlerAction, version: v1 }
    methods: [POST]

如果网站和 JSON-RPC 服务器位于不同的域名上，请记住关于 CORS。

方法

<?php

declare(strict_types=1);

namespace App\Method;

use Timiki\Bundle\RpcServerBundle\Attribute as RPC;
use Symfony\Component\Validator\Constraints as Assert;

#[RPC\Method("name")]
#[RPC\Roles(["ROLE_NAME"])]
#[RPC\Cache(3600)]
class Method
{
    #[RPC\Param]
    #[Assert\NotBlank]
    protected $param;

    #[RPC\Execute] 
    public function execute()
    {
        $param = $this->param;
        
        ...
        
        return $result;
    }
}
    

或者您也可以使用 __invoke 声明调用方法

<?php

declare(strict_types=1);

namespace App\Method;

use Timiki\Bundle\RpcServerBundle\Attribute as RPC;
use Symfony\Component\Validator\Constraints as Assert;

#[RPC\Method("name")]
#[RPC\Roles(["ROLE_NAME"])]
#[RPC\Cache(3600)]
class Method
{
    #[RPC\Param]
    #[Assert\NotBlank]
    protected $param;

    public function __invoke()
    {
        $param = $this->param;
        
        ...
        
        return $result;
    }
}
    

注入方法执行上下文

<?php

declare(strict_types=1);

namespace App\Method;

use Timiki\Bundle\RpcServerBundle\Attribute as RPC;
use Timiki\Bundle\RpcServerBundle\Method\Context;
use Symfony\Component\Validator\Constraints as Assert;

#[RPC\Method("name")]
#[RPC\Roles(["ROLE_NAME"])]
#[RPC\Cache(3600)]
class Method
{
    #[RPC\Param]
    #[Assert\NotBlank]
    protected $param;

    public function __invoke(Context $context)
    {
        $param = $this->param;
        
        ...
        
        return $result;
    }
}
    

属性

方法

将类定义为 JSON-RPC 方法。

#[Method("name")]

角色

为访问方法设置角色。如果用户没有权限访问服务器，则返回包含消息“方法未授权”和代码“-32001”的错误。

#[Roles(["ROLE_NAME", "ROLE_OTHER"])]

缓存

如果配置中定义了缓存，则设置响应的生存时间。

#[Cache(3600)]

参数

定义 JSON-RPC 参数。使用 Symfony\Component\Validator\Constraints 验证它们。

#[Param]
protected $param;

#[Param]
protected $param = null'; // Default value for param

执行

在类中定义执行函数。

#[Execute]
public function execute()
{
    // Code
}

或使用 __invoke

public function __invoke()
{
    // Code
}

序列化

在组件中，用于将方法输出的结果转换为 JSON 的工具是序列化器。

序列化器配置

rpc:
    serializer: rpc.server.serializer.base # serialize service id

组件中包含以下序列化器

rpc.server.serializer.base - (默认) 使用 Symfony 序列化将结果转换为 JSON rpc.server.serializer.role - 使用用户角色作为 @Group (@see https://symfony.com.cn/doc/current/components/serializer.html) 控制对输出数组的访问

创建自定义序列化器

以下是一个简单序列化类的示例。

<?php

declare(strict_types=1);

namespace App\Serializer;

use Timiki\Bundle\RpcServerBundle\Serializer\SerializerInterface;

class MySerializer implements SerializerInterface
{
    public function serialize(mixed $data): string 
        // You serialize logic
    }
    
    public function toArray(mixed $data): array 
        // You serialize logic
    }
}

然后添加自定义序列化器服务 ID 到配置中

rpc:
    serializer: MySerializer # serialize service id