Add doc

2024-11-29 18:27:44 +08:00 · 2020-08-10 02:12:16 +08:00 · 2020-08-10 02:12:16 +08:00 · b1cc1d6bb9
commit b1cc1d6bb9
parent ca0f8b361b
7 changed files with 379 additions and 0 deletions
--- a/docs/en/jet.md
+++ b/docs/en/jet.md
@ -0,0 +1,125 @@
+# Jet, by Hyperf
+
+Jet is a unification model RPC Client, built-in JSONRPC protocol, available to running in ALL PHP environments, including PHP-FPM and Swoole/Hyperf environments. 
+
+> Also will built-in gRPC and Tars protocols in future.
+
+# Installation
+
+```bash
+composer require hyperf/jet
+```
+
+# Quickstart
+
+## Register protocol
+
+> Register the protocol is not necessary, but you could manage the protocols more easily by using ProtocolManager.
+
+You cloud register any protocol by `Hyperf\Jet\ProtocolManager`, per protocol basically including Transporter, Packer, DataFormatter and PathGenerator, you could register a JSONRPC protocol like below: 
+
+```php
+<?php
+
+use Hyperf\Jet\DataFormatter\DataFormatter;
+use Hyperf\Jet\Packer\JsonEofPacker;
+use Hyperf\Jet\PathGenerator\PathGenerator;
+use Hyperf\Jet\ProtocolManager;
+use Hyperf\Jet\Transporter\StreamSocketTransporter;
+
+ProtocolManager::register($protocol = 'jsonrpc', [
+    ProtocolManager::TRANSPORTER => new StreamSocketTransporter(),
+    ProtocolManager::PACKER => new JsonEofPacker(),
+    ProtocolManager::PATH_GENERATOR => new PathGenerator(),
+    ProtocolManager::DATA_FORMATTER => new DataFormatter(),
+]);
+```
+
+## Register service
+
+> > Register the service is not necessary, but you could manage the services more easily by using ServiceManager.
+
+After you registered a protocol to `Hyperf\Jet\ProtocolManager`, you could bind the protocol with any services by `Hyperf\Jet\ServiceManager`, like below:
+
+```php
+<?php
+use Hyperf\Jet\ServiceManager;
+
+// Bind CalculatorService with jsonrpc protocol, and set the static nodes info.
+ServiceManager::register($service = 'CalculatorService', $protocol = 'jsonrpc', [
+    ServiceManager::NODES => [
+        [$host = '127.0.0.1', $port = 9503],
+    ],
+]);
+```
+
+## Call RPC method
+
+### Call by ClientFactory
+
+After you registered the protocol and service, you could get your service client via `Hyperf/Jet/ClientFactory`, like below:
+
+```php
+<?php
+use Hyperf\Jet\ClientFactory;
+
+$clientFactory = new ClientFactory();
+$client = $clientFactory->create($service = 'CalculatorService', $protocol = 'jsonrpc');
+```
+
+When you have the client object, you could call any remote methods via the object, like below: 
+
+```php
+// Call the remote method `add` with arguments `1` and `2`.
+// The $result is the result of the remote method.
+$result = $client->add(1, 2);
+```
+
+If you call a not exist remote method, the client will throw an `Hyperf\Jet\Exception\ServerException` exception.
+
+### Call by custom client
+
+You could also create a custom client class which extends `Hyperf\Jet\AbstractClient`, to call the remote methods via the client object.   
+For example, you want to define a RPC client for `CalculatorService` with `jsonrpc` protocol, you could create a `CalculatorService` class firstly, like below:
+
+```php
+<?php
+
+use Hyperf\Jet\AbstractClient;
+use Hyperf\Jet\Packer\JsonEofPacker;
+use Hyperf\Jet\Transporter\StreamSocketTransporter;
+use Hyperf\Rpc\Contract\DataFormatterInterface;
+use Hyperf\Rpc\Contract\PackerInterface;
+use Hyperf\Rpc\Contract\PathGeneratorInterface;
+use Hyperf\Rpc\Contract\TransporterInterface;
+
+/**
+ * @method int add(int $a, int $b);
+ */
+class CalculatorService extends AbstractClient
+{
+    // Define `CalculatorService` as the default value of $service.
+    public function __construct(
+        string $service = 'CalculatorService',
+        TransporterInterface $transporter = null,
+        PackerInterface $packer = null,
+        ?DataFormatterInterface $dataFormatter = null,
+        ?PathGeneratorInterface $pathGenerator = null
+    ) {
+        // Specific the transporter here, you could also retrieve the transporter from ProtocolManager or passing by constructor.
+        $transporter = new StreamSocketTransporter('127.0.0.1', 9503);
+        // Specific the packer here, you could also retrieve the packer from ProtocolManager or passing by constructor.
+        $packer = new JsonEofPacker();
+        parent::__construct($service, $transporter, $packer, $dataFormatter, $pathGenerator);
+    }
+}
+```
+
+Now, you could use this class to call the remote method directly, like below:
+
+```php
+// Call the remote method `add` with arguments `1` and `2`.
+// The $result is the result of the remote method.
+$client = new CalculatorService();
+$result = $client->add(1, 2);
+```
--- a/docs/en/summary.md
+++ b/docs/en/summary.md
@ -73,6 +73,7 @@
  * [Metric](en/metric.md)
  * [Retry](en/retry.md)
  * [Nacos](en/nacos.md)
+  * [Jet](en/jet.md)
  
 * Message Queue

--- a/docs/zh-cn/summary.md
+++ b/docs/zh-cn/summary.md
@ -74,6 +74,7 @@
  * [服务监控](zh-cn/metric.md)
  * [服务重试](zh-cn/retry.md)
  * [Nacos](zh-cn/nacos.md)
+  * [Jet](zh-cn/jet.md)
  
 * 消息队列

--- a/docs/zh-hk/jet.md
+++ b/docs/zh-hk/jet.md
@ -0,0 +1,124 @@
+# Jet
+
+Jet 是一個統一模型的 RPC 客户端，內置 JSONRPC 協議的適配，該組件可適用於所有的 PHP 環境，包括 PHP-FPM 和 Swoole 或 Hyperf。（在 Hyperf 環境下，目前仍建議直接使用 `hyperf/json-rpc` 組件來作為客户端使用）
+
+> 未來還會內置 gRPC 和 Tars 協議。
+
+# 安裝
+
+```bash
+composer require hyperf/jet
+```
+
+# 快速開始
+
+## 註冊協議
+
+> 註冊協議不是必須的一個步驟，但您可以通過 ProtocolManager 管理所有的協議。
+
+您可以通過 `Hyperf\Jet\ProtocolManager` 類來註冊管理任意的協議，每個協議會包含 Transporter, Packer, DataFormatter and PathGenerator 幾個基本的組件，您可以註冊一個 JSONRPC 協議，如下：
+
+```php
+<?php
+
+use Hyperf\Jet\DataFormatter\DataFormatter;
+use Hyperf\Jet\Packer\JsonEofPacker;
+use Hyperf\Jet\PathGenerator\PathGenerator;
+use Hyperf\Jet\ProtocolManager;
+use Hyperf\Jet\Transporter\StreamSocketTransporter;
+
+ProtocolManager::register($protocol = 'jsonrpc', [
+    ProtocolManager::TRANSPORTER => new StreamSocketTransporter(),
+    ProtocolManager::PACKER => new JsonEofPacker(),
+    ProtocolManager::PATH_GENERATOR => new PathGenerator(),
+    ProtocolManager::DATA_FORMATTER => new DataFormatter(),
+]);
+```
+
+## 註冊服務
+
+> 註冊服務不是必須的一個步驟，但您可以通過 ServiceManager 管理所有的服務。
+
+在您往 `Hyperf\Jet\ProtocolManager` 註冊了一個協議之後，您可以通過 `Hyperf\Jet\ServiceManager` 將協議綁定到任意的服務上，如下：
+
+```php
+<?php
+use Hyperf\Jet\ServiceManager;
+
+// 綁定 CalculatorService 與 jsonrpc 協議，同時設定靜態的節點信息
+ServiceManager::register($service = 'CalculatorService', $protocol = 'jsonrpc', [
+    ServiceManager::NODES => [
+        [$host = '127.0.0.1', $port = 9503],
+    ],
+]);
+```
+
+## 調用 RPC 方法
+
+### 通過 ClientFactory 調用
+
+在您註冊完協議與服務之後，您可以通過 `Hyperf/Jet/ClientFactory` 來獲得您的服務的客户端，如下所示：
+
+```php
+<?php
+use Hyperf\Jet\ClientFactory;
+
+$clientFactory = new ClientFactory();
+$client = $clientFactory->create($service = 'CalculatorService', $protocol = 'jsonrpc');
+```
+
+當您擁有 client 對象後，您可以通過該對象調用任意的遠程方法，如下：
+
+```php
+// 調用遠程方法 `add` 並帶上參數 `1` 和 `2`
+// $result 即為遠程方法的返回值
+$result = $client->add(1, 2);
+```
+
+當您調用一個不存在的遠程方法時，客户端會拋出一個 `Hyperf\Jet\Exception\ServerException` 異常。
+
+### 通過自定義客户端調用
+
+您可以創建一個 `Hyperf\Jet\AbstractClient` 的子類作為自定義的客户端類，來完成遠程方法的調用，比如，您希望定義一個 `CalculatorService` 服務的 `jsonrpc` 協議的客户端類，您可以先定義一個 `CalculatorService` 類，如下所示：
+
+```php
+<?php
+
+use Hyperf\Jet\AbstractClient;
+use Hyperf\Jet\Packer\JsonEofPacker;
+use Hyperf\Jet\Transporter\StreamSocketTransporter;
+use Hyperf\Rpc\Contract\DataFormatterInterface;
+use Hyperf\Rpc\Contract\PackerInterface;
+use Hyperf\Rpc\Contract\PathGeneratorInterface;
+use Hyperf\Rpc\Contract\TransporterInterface;
+
+/**
+ * @method int add(int $a, int $b);
+ */
+class CalculatorService extends AbstractClient
+{
+    // 定義 `CalculatorService` 作為 $service 參數的默認值
+    public function __construct(
+        string $service = 'CalculatorService',
+        TransporterInterface $transporter = null,
+        PackerInterface $packer = null,
+        ?DataFormatterInterface $dataFormatter = null,
+        ?PathGeneratorInterface $pathGenerator = null
+    ) {
+        // 這裏指定 transporter，您仍然可以通過 ProtocolManager 來獲得 transporter 或從構造函數傳遞
+        $transporter = new StreamSocketTransporter('127.0.0.1', 9503);
+        // 這裏指定 packer，您仍然可以通過 ProtocolManager 來獲得 packer 或從構造函數傳遞
+        $packer = new JsonEofPacker();
+        parent::__construct($service, $transporter, $packer, $dataFormatter, $pathGenerator);
+    }
+}
+```
+
+現在，您可以通過該類來直接調用遠程方法了，如下所示：
+
+```php
+// 調用遠程方法 `add` 並帶上參數 `1` 和 `2`
+// $result 即為遠程方法的返回值
+$client = new CalculatorService();
+$result = $client->add(1, 2);
+```
--- a/docs/zh-hk/summary.md
+++ b/docs/zh-hk/summary.md
@ -74,6 +74,7 @@
  * [服務監控](zh-hk/metric.md)
  * [服務重試](zh-hk/retry.md)
  * [Nacos](zh-hk/nacos.md)
+  * [Jet](zh-hk/jet.md)
  
 * 消息隊列

@ -91,6 +92,7 @@
  * [Consul 協程客户端](zh-hk/consul.md)
  * [ETCD 協程客户端](zh-hk/etcd.md)
  * [WebSocket 服務](zh-hk/websocket-server.md)
+  * [TCP 服務](zh-hk/tcp-server.md)
  * [WebSocket 協程客户端](zh-hk/websocket-client.md)
  * [Socket.io 服務](zh-hk/socketio-server.md)
  * [自定義進程](zh-hk/process.md)
--- a/docs/zh-tw/jet.md
+++ b/docs/zh-tw/jet.md
@ -0,0 +1,124 @@
+# Jet
+
+Jet 是一個統一模型的 RPC 客戶端，內建 JSONRPC 協議的適配，該元件可適用於所有的 PHP 環境，包括 PHP-FPM 和 Swoole 或 Hyperf。（在 Hyperf 環境下，目前仍建議直接使用 `hyperf/json-rpc` 元件來作為客戶端使用）
+
+> 未來還會內建 gRPC 和 Tars 協議。
+
+# 安裝
+
+```bash
+composer require hyperf/jet
+```
+
+# 快速開始
+
+## 註冊協議
+
+> 註冊協議不是必須的一個步驟，但您可以通過 ProtocolManager 管理所有的協議。
+
+您可以通過 `Hyperf\Jet\ProtocolManager` 類來註冊管理任意的協議，每個協議會包含 Transporter, Packer, DataFormatter and PathGenerator 幾個基本的元件，您可以註冊一個 JSONRPC 協議，如下：
+
+```php
+<?php
+
+use Hyperf\Jet\DataFormatter\DataFormatter;
+use Hyperf\Jet\Packer\JsonEofPacker;
+use Hyperf\Jet\PathGenerator\PathGenerator;
+use Hyperf\Jet\ProtocolManager;
+use Hyperf\Jet\Transporter\StreamSocketTransporter;
+
+ProtocolManager::register($protocol = 'jsonrpc', [
+    ProtocolManager::TRANSPORTER => new StreamSocketTransporter(),
+    ProtocolManager::PACKER => new JsonEofPacker(),
+    ProtocolManager::PATH_GENERATOR => new PathGenerator(),
+    ProtocolManager::DATA_FORMATTER => new DataFormatter(),
+]);
+```
+
+## 註冊服務
+
+> 註冊服務不是必須的一個步驟，但您可以通過 ServiceManager 管理所有的服務。
+
+在您往 `Hyperf\Jet\ProtocolManager` 註冊了一個協議之後，您可以通過 `Hyperf\Jet\ServiceManager` 將協議繫結到任意的服務上，如下：
+
+```php
+<?php
+use Hyperf\Jet\ServiceManager;
+
+// 繫結 CalculatorService 與 jsonrpc 協議，同時設定靜態的節點資訊
+ServiceManager::register($service = 'CalculatorService', $protocol = 'jsonrpc', [
+    ServiceManager::NODES => [
+        [$host = '127.0.0.1', $port = 9503],
+    ],
+]);
+```
+
+## 呼叫 RPC 方法
+
+### 通過 ClientFactory 呼叫
+
+在您註冊完協議與服務之後，您可以通過 `Hyperf/Jet/ClientFactory` 來獲得您的服務的客戶端，如下所示：
+
+```php
+<?php
+use Hyperf\Jet\ClientFactory;
+
+$clientFactory = new ClientFactory();
+$client = $clientFactory->create($service = 'CalculatorService', $protocol = 'jsonrpc');
+```
+
+當您擁有 client 物件後，您可以通過該物件呼叫任意的遠端方法，如下：
+
+```php
+// 呼叫遠端方法 `add` 並帶上引數 `1` 和 `2`
+// $result 即為遠端方法的返回值
+$result = $client->add(1, 2);
+```
+
+當您呼叫一個不存在的遠端方法時，客戶端會丟擲一個 `Hyperf\Jet\Exception\ServerException` 異常。
+
+### 通過自定義客戶端呼叫
+
+您可以建立一個 `Hyperf\Jet\AbstractClient` 的子類作為自定義的客戶端類，來完成遠端方法的呼叫，比如，您希望定義一個 `CalculatorService` 服務的 `jsonrpc` 協議的客戶端類，您可以先定義一個 `CalculatorService` 類，如下所示：
+
+```php
+<?php
+
+use Hyperf\Jet\AbstractClient;
+use Hyperf\Jet\Packer\JsonEofPacker;
+use Hyperf\Jet\Transporter\StreamSocketTransporter;
+use Hyperf\Rpc\Contract\DataFormatterInterface;
+use Hyperf\Rpc\Contract\PackerInterface;
+use Hyperf\Rpc\Contract\PathGeneratorInterface;
+use Hyperf\Rpc\Contract\TransporterInterface;
+
+/**
+ * @method int add(int $a, int $b);
+ */
+class CalculatorService extends AbstractClient
+{
+    // 定義 `CalculatorService` 作為 $service 引數的預設值
+    public function __construct(
+        string $service = 'CalculatorService',
+        TransporterInterface $transporter = null,
+        PackerInterface $packer = null,
+        ?DataFormatterInterface $dataFormatter = null,
+        ?PathGeneratorInterface $pathGenerator = null
+    ) {
+        // 這裡指定 transporter，您仍然可以通過 ProtocolManager 來獲得 transporter 或從建構函式傳遞
+        $transporter = new StreamSocketTransporter('127.0.0.1', 9503);
+        // 這裡指定 packer，您仍然可以通過 ProtocolManager 來獲得 packer 或從建構函式傳遞
+        $packer = new JsonEofPacker();
+        parent::__construct($service, $transporter, $packer, $dataFormatter, $pathGenerator);
+    }
+}
+```
+
+現在，您可以通過該類來直接呼叫遠端方法了，如下所示：
+
+```php
+// 呼叫遠端方法 `add` 並帶上引數 `1` 和 `2`
+// $result 即為遠端方法的返回值
+$client = new CalculatorService();
+$result = $client->add(1, 2);
+```
--- a/docs/zh-tw/summary.md
+++ b/docs/zh-tw/summary.md
@ -74,6 +74,7 @@
  * [服務監控](zh-tw/metric.md)
  * [服務重試](zh-tw/retry.md)
  * [Nacos](zh-tw/nacos.md)
+  * [Jet](zh-tw/jet.md)
  
 * 訊息佇列

@ -91,6 +92,7 @@
  * [Consul 協程客戶端](zh-tw/consul.md)
  * [ETCD 協程客戶端](zh-tw/etcd.md)
  * [WebSocket 服務](zh-tw/websocket-server.md)
+  * [TCP 服務](zh-tw/tcp-server.md)
  * [WebSocket 協程客戶端](zh-tw/websocket-client.md)
  * [Socket.io 服務](zh-tw/socketio-server.md)
  * [自定義程序](zh-tw/process.md)