README

Amphp RPC

PHP (8.1) 基于 Amp 的异步 RPC

安装

此包可以作为 Composer 依赖项安装。

composer require makaronnik/amphp-rpc

要求

• PHP 8.1+

描述

这是一个基于 Amp 的异步、非阻塞模式的 RPC（远程过程调用）包。
基于 amphp/rpc 实现的想法，但增强了微服务架构中用于通信和负载均衡的高级功能。
在 Amphp 微服务框架 中用作服务间通信的主要方法之一。它还作为 Amphp 请求代理包的基础。

主要特性

• 客户端在远程服务器（服务）上调用过程（方法），并获得结果的可能性。
• 在服务器执行过程中发生的异常被捕获并传输到客户端，客户端可以捕获和处理这些异常。
• 服务器根据不同情况提供不同的响应选项（重定向到另一个主机/ip、n秒后重试等）和相应的客户端反应。您可以使用拦截器机制实现自己的响应选项及其处理。
• 用于存储和重用重定向目标的缓存，以减少可能的中间请求数量

创建远程对象

远程对象实际上是在 RPC 服务器端从 RPC 客户端收到 RPC 请求时生成的类的实例。这些类必须在服务器端，并实现它们的接口。这些接口的公共方法必须返回 Amp\Promise 对象，否则将抛出异常。这些方法称为远程过程。它们将在服务器端作为客户端代理对象上调用类似方法的结果执行。为了实现这一点，必须注册远程对象接口与其实现之间的映射。这是通过将 RpcRegistry 对象的 registerRemoteObject 方法传递给 RpcServer 构造函数来完成的。远程对象的相同接口必须在服务器和客户端上。客户端上的相同接口需要通过在 RpcProxyObjectFactory 上调用 createProxy 方法来创建远程对象的适当代理。

远程对象接口示例

use Amp\Promise;

interface SimpleCalcInterface
{
    public function add(int $a, int $b): Promise; // remote procedure add() API
}

远程对象实现示例

use Amp\Promise;
use function Amp\call;

class SimpleCalc implements SimpleCalcInterface
{
    public function add(int $a, int $b): Promise // remote procedure add() implementation
    {
        return call(fn (): int => $a + $b); // returns Promise<int>
    }
}

(服务器) 注册远程对象接口与其实现的映射

$registry = new RpcRegistry();
$registry->registerRemoteObject(SimpleCalcInterface::class, SimpleCalc::class);
$requestHandler = new RpcRequestHandler(new NativeSerializer(), $registry);
$rpcServer = (new RpcServerFactory(8181, $registry, $requestHandler))->getRpcServer();
yield $rpcServer->start();

(客户端) 创建远程对象代理并调用其远程方法

$rpcClient = (new RpcClientBuilder('localhost', 8181))->build();
$proxyCalc = yield $proxyObjectsFactory->createProxy($rpcClient, SimpleCalcInterface::class);
$addResult = yield $proxyCalc->add(5, 7); // int: 12

完整示例

您可以在 examples 和 test 目录中找到完整示例。

主要包类

服务器端

• RpcServer - 启动一个处理 RPC 请求的服务器。最好通过 RpcServerFactory 进行配置。

• RpcRequestHandler - 处理RPC请求。具有用于注册在主请求处理逻辑之前执行的请求拦截器的 registerInterceptor 方法。请求被处理后，它返回适当的RPC响应。

• RpcRegistry - 存储远程对象接口及其实现之间的链接。如果您没有注册远程接口映射及其实现，则服务器将不知道如何处理RPС请求。传递给服务器和处理器的构造函数。

客户端

• RpcClient - 向服务器发出RPC请求。最好通过 RpcClientBuilder 进行配置。不直接使用，传递给远程对象代理的创建方法。

• RpcResponseHandler - 处理来自RPC服务器的响应并返回RPC请求的结果或抛出适当的异常。

• RpcProxyObjectFactory - 为远程对象创建代理。它有一个公共方法 createProxy，该方法接受一个RpcClient对象和目标远程对象的完全限定接口名称作为参数。如果之前生成的代理无法找到，则使用生成器。

• RpcProxyObjectGenerator - 为远程对象生成代理类文件。它传递给工厂构造函数，在那里使用它。

• RpcProxyClassFileLocator - 配置一个目录路径以存储远程对象的生成代理类。它传递给工厂构造函数，在那里使用它。

响应工厂

• SuccessRpcResponseFactory - 创建包含序列化RPC请求结果的RPC响应。

• ThrowableRpcResponseFactory - 创建包含在处理RPC请求期间在服务器上发生的异常数据的RPC响应。

• RetryRpcResponseFactory - 创建一个RPC响应，告知RPC客户端（处理器）在一段时间后重试请求。

• RedirectRpcResponseFactory - 创建一个RPC响应，告知RPC客户端（处理器）重新提交请求，但提交到不同的主机、端口或路径。

异常

• UnprocessedCallException - 如果RPC请求在RPC服务器上未完成，并且可以安全地重试，则抛出。

• PossiblyProcessedCallException - 如果RPC请求在RPC服务器上部分完成，并且重试可能不安全，则抛出。

• ProcessedCallException - 如果请求在服务器上成功，但在获取或返回结果时出现问题时，重试此请求可能不安全，则抛出。

• RetriesCountExceededException - 如果超过允许的重试次数，则抛出。此异常继承自UnprocessedCallException，因此可以安全地重试请求。

• RedirectCountExceededException - 当允许的重定向次数超出时抛出。此异常继承自UnprocessedCallException，因此可以安全地重试请求。

版本控制

makaronnik/amphp-rpc 遵循 semver 语义化版本规范。

许可证

MIT许可证（MIT）。有关更多信息，请参阅 LICENSE。