From 70870d4a2fc5a64713c5a446a34317d3d09d8d00 Mon Sep 17 00:00:00 2001 From: Xinchen Hui Date: Sun, 30 Aug 2026 08:12:33 +0800 Subject: [PATCH 1/2] =?UTF-8?q?=E6=96=B0=E5=A2=9E=20Yar=20=E5=8D=8F?= =?UTF-8?q?=E8=AE=AE=E7=AB=A0=E8=8A=82=E5=B9=B6=E5=90=8C=E6=AD=A5=E6=9B=B4?= =?UTF-8?q?=E6=96=B0=20Yar=20=E6=89=A9=E5=B1=95=E4=B8=AD=E6=96=87=E7=BF=BB?= =?UTF-8?q?=E8=AF=91?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 跟进英文文档修订 (php/doc-en#5815, EN-Revision 60ce1c5c7c)： 新增《Yar 协议》章节、三种安装方式（PECL/PIE/源码）、 YAR_ERR_FORBIDDEN 常量，完善并发客户端与核心方法文档。 --- reference/yar/book.xml | 10 +- reference/yar/constants.xml | 15 +- reference/yar/examples.xml | 72 +++++++-- reference/yar/protocol.xml | 131 ++++++++++++++++ reference/yar/setup.xml | 148 +++++++++++------- reference/yar/yar-concurrent-client.xml | 12 +- reference/yar/yar-server.xml | 7 +- reference/yar/yar_client/call.xml | 49 +++++- reference/yar/yar_client/construct.xml | 8 +- reference/yar/yar_client/getopt.xml | 4 +- reference/yar/yar_client/setopt.xml | 8 +- .../yar/yar_client_exception/gettype.xml | 4 +- reference/yar/yar_concurrent_client/call.xml | 33 ++-- reference/yar/yar_concurrent_client/loop.xml | 36 ++++- reference/yar/yar_concurrent_client/reset.xml | 6 +- reference/yar/yar_server/construct.xml | 36 ++++- reference/yar/yar_server/handle.xml | 16 +- .../yar/yar_server_exception/gettype.xml | 4 +- 18 files changed, 467 insertions(+), 132 deletions(-) create mode 100644 reference/yar/protocol.xml diff --git a/reference/yar/book.xml b/reference/yar/book.xml index 17fdff7e7..c2eef1b51 100644 --- a/reference/yar/book.xml +++ b/reference/yar/book.xml @@ -1,6 +1,6 @@ - + Yet Another RPC Framework @@ -15,14 +15,16 @@ Yar 是一个原生 PHP 扩展，而不是用户态的库。它基于 HTTP、HTTPS 或 TCP 使用紧凑的二进制协议，并内置三种打包器（php、json，以及在使用 - 编译时的 - msgpack），因此不需要额外的依赖包或代理进程。 + 编译时可用的 + msgpack），因此无需安装额外的依赖包或代理进程。 - 该协议与语言无关：目前已存在 C、Java 和 Lua 的兼容实现。 + 该协议与语言无关，任何语言都可以轻松实现与 Yar 服务的通信， + 具体细节参见 Yar 协议。 + &reference.yar.protocol; &reference.yar.setup; &reference.yar.constants; &reference.yar.examples; diff --git a/reference/yar/constants.xml b/reference/yar/constants.xml index 88856211d..ecbbd8f56 100644 --- a/reference/yar/constants.xml +++ b/reference/yar/constants.xml @@ -1,6 +1,6 @@ - + &reftitle.constants; &extension.constants; @@ -302,6 +302,19 @@ + + + YAR_ERR_FORBIDDEN + (int) + + + + 请求被服务器端的身份验证拒绝（参见 + Yar 协议头的 + provider 和 token 字段）。 + + + diff --git a/reference/yar/examples.xml b/reference/yar/examples.xml index c268ede5b..9af0bde45 100644 --- a/reference/yar/examples.xml +++ b/reference/yar/examples.xml @@ -1,16 +1,33 @@ - + &reftitle.examples; + + 下面的示例演示了一个完整的服务：一个暴露若干算术方法的服务端、 + 一个调用它们的同步客户端、一个一次性发出多个并发调用的客户端， + 以及一个通过 TCP 与服务器通信的客户端。 + + Yar 服务端示例 + + Yar 服务就是一个由 Yar_Server + 包装的普通 PHP 类。对象的每一个公开方法都会成为一个 RPC + 端点，而受保护方法、私有方法以及方法名以下划线开头的方法， + 对客户端不可见。公开方法的文档注释会被收集起来， + 显示在服务信息页面上。 + + + RPC 请求以 HTTP POST 请求的形式到达，请求体携带 Yar 二进制协议 + 负载，因此这个脚本通常被映射为常规 Web 服务器上的一个 URI。 + handle(); 通过浏览器访问服务端（GET 请求） - 当向服务地址发起 GET 请求时，Yar 会渲染一个信息页面， + 当向服务地址发起 GET 请求时（例如直接在浏览器中打开它）， + Yar 不会执行 RPC 调用，而是渲染一个信息页面， 列出执行对象的每一个公开方法及其文档注释。 该行为由 - yar.expose_info 配置项控制。 + yar.expose_info + 配置项控制；当它关闭时，GET 请求将失败。 &example.outputs.similar; @@ -73,10 +92,22 @@ $server->handle(); Yar 客户端示例 + + Yar_Client 绑定到单一的服务地址。 + 在它上面调用任何未定义的方法，都会被透明地转换为同步 + RPC 调用，远程方法用起来和本地方法一样； + Yar_Client::call + 显式地按方法名做同样的事情。 + + + 受保护方法不会被暴露：调用它们会失败，并抛出错误码为 + YAR_ERR_REQUEST 的 + Yar_Client_Exception。 + add(1, 2)); @@ -84,7 +115,7 @@ var_dump($client->add(1, 2)); /* 通过 call() 调用 */ var_dump($client->call("add", array(3, 2))); -/* _add 无法被调用: 它不是公开方法 */ +/* _add 无法被调用：它不是公开方法 */ var_dump($client->_add(1, 2)); ?> ]]> @@ -94,17 +125,33 @@ var_dump($client->_add(1, 2)); Yar 并发客户端示例 + + Yar_Concurrent_Client + 不是逐个调用服务，而是先注册多个调用，然后通过 + Yar_Concurrent_Client::loop + 一次性发出所有调用。响应按到达的顺序传递给回调函数， + 而不是按调用注册的顺序。 + + + 在全部请求发送完毕后，回调函数会以 &null; + 参数被调用一次，以便调用方知道没有更多请求等待发送； + 下面的示例检查了这个通知。 + 除了 HTTP 之外，Yar_Client 还可以 通过 TCP 或 Unix socket 与兼容 Yar 协议的服务器通信， - 例如一个由 Yar C 框架实现的服务。 - 远程服务器必须实现相同的 Yar 二进制协议。 + 例如一个由 + Yar C 框架 + 实现的服务，它提供的二进制 Yar 协议与 PHP 服务端使用的相同。 + + + + Yar 协议 + + Yar 不依赖 schema 或 IDL 文件：网络上传输的一切都是纯字节。 + 任何能够读写字节的语言都可以与 Yar 服务通信，完全不需要安装任何框架—— + 只需构造一个固定大小的二进制请求头和一个序列化后的请求体， + 把它们发送到服务 URI，再解析响应即可。 + + + 一条消息由一个固定大小为 82 字节的头部和紧随其后的消息体组成。 + 头部的布局与下面的 C 结构体完全一致，紧凑排列、没有填充字节， + 并按声明顺序逐个字段写入网络： + + + + + + 其中 id、magic_num、reserved + 和 body_len 字段以网络字节序（大端）存储； + 其余字段是原始字节。 + + + 消息体以一个 8 字节的打包器标识符开头——PHP、JSON + 或 MSGPACK，不足部分以零填充——用于告知接收方其余内容的编码方式， + 其后是序列化内容本身。 + + + + + 请求体解码后是一个数组，包含以下键：i（事务 id）、m + （被调用的方法）和 p（参数列表）。 + + + + + 响应体解码后是一个数组，包含以下键：i（事务 id）、s + （状态，取值为 YAR_ERR_* 常量之一）、r（返回值）、 + o（服务方法产生的任何输出）以及 e + （调用失败时的错误或异常）。 + + + + + 通过 HTTP 传输时，消息作为 POST 请求的正文发送，响应作为回复的正文到达； + 通过 TCP 或 Unix socket 传输时，消息直接写入流中。 + + + 在不安装扩展的情况下调用 Yar 服务 + + 下面这个独立脚本仅使用标准 socket，就为 php + 打包器构造了一个有效的 Yar 请求，将其发送到服务 URI， + 并输出解码后的响应。用 + 示例中的 + Operator 服务运行该脚本，输出为 + int(3)。 + + + 1, "m" => "add", "p" => array(1, 2))); +$body = str_pad("PHP", 8, "\0") . $serialized; + +/* 2. the header: 82 bytes, multi-byte integers in network byte order */ +$header = pack("N", 1) /* id */ + . pack("v", 0) /* version */ + . pack("N", 0x80DFEC60) /* magic number */ + . pack("N", 0) /* reserved */ + . str_pad("", 32, "\0") /* provider */ + . str_pad("", 32, "\0") /* token */ + . pack("N", strlen($body)); /* body length */ + +/* 3. send it as the body of a POST request */ +$stream = stream_context_create(array("http" => array( + "method" => "POST", + "header" => "Content-Type: application/octet-stream\r\n", + "content" => $header . $body, +))); +$reply = file_get_contents($uri, false, $stream); + +/* 4. parse the reply: 82-byte header, then the response body */ +$response = unserialize(substr($reply, 82 + 8)); +var_dump($response["r"]); +?> +]]> + + + + 一个更完整的纯 PHP 客户端实现位于 + Yar 源码仓库的 + tools/ 目录中，它还会解码响应头，并支持并发调用。 + + + + diff --git a/reference/yar/setup.xml b/reference/yar/setup.xml index 8a48d5cc6..18e38f176 100644 --- a/reference/yar/setup.xml +++ b/reference/yar/setup.xml @@ -1,6 +1,6 @@ - + &reftitle.setup; @@ -26,6 +26,9 @@
&reftitle.install; + + Yar 有三种安装方式：通过 PECL、通过 PIE，或从源码构建。 + &pecl.moved; @@ -36,64 +39,97 @@ &pecl.windows.download.avail; - + + 用 PECL 安装 Yar + + + + + + 自 Yar 2.4.0 起，也可以使用 &link.pie;（PHP Installer for + Extensions，PHP 扩展安装器）安装本扩展。在命令行执行以下命令： + + + 用 PIE 安装 Yar + + + + + + 安装时可以同时启用 msgpack 打包器： + + + 用 PIE 安装 Yar 并启用 msgpack + + + + + 源代码托管在 - GitHub 上。从源码构建该扩展： - + GitHub 上。 + 若要自源码构建该扩展，请在命令行执行以下命令， + 并把其中的路径替换为本地 PHP 安装的实际路径： + + + 从源码构建 Yar + - - - - 可以使用以下 configure 选项： - - - - - - - - 当 cURL 不在默认的 include 路径中时， - 指定 cURL 的安装位置。 - - - - - - - - - - 启用 msgpack 打包器，并将 - msgpack 扩展作为可选依赖。当 - Yar 使用该选项编译时， - yar.packager 的默认值变为 - msgpack。 - - - - - - - - - - 使用 Linux epoll 代替 - select() 进行 I/O 多路复用，自 - Yar 2.1.2 起可用。在高并发场景下，该选项可以提升 - Yar_Concurrent_Client 的性能。 - 它仅在 Linux 上生效；在其他平台上会被静默忽略。 - - - - - + + + + 可用的 configure 选项如下： + + + + + + + + + 当 cURL 不在默认的 include 路径中时， + 指定 cURL 的安装位置。 + + + + + + + + + + 启用 msgpack 打包器，并将 + msgpack 扩展作为可选依赖。当 + Yar 使用该选项编译时， + yar.packager 的默认值变为 + msgpack。 + + + + + + + + + + 使用 Linux epoll 代替 + select() 进行 I/O 多路复用，自 + Yar 2.1.2 起可用。在高并发场景下，该选项可以提升 + Yar_Concurrent_Client 的性能。 + 它仅在 Linux 上生效；在其他平台上会被静默忽略。 + + + +
diff --git a/reference/yar/yar-concurrent-client.xml b/reference/yar/yar-concurrent-client.xml index adbb341ab..7bfb1812d 100644 --- a/reference/yar/yar-concurrent-client.xml +++ b/reference/yar/yar-concurrent-client.xml @@ -1,6 +1,6 @@ - + Yar_Concurrent_Client 类 @@ -18,9 +18,17 @@ Yar_Concurrent_Client::loop 统一并行发出。 + + 该类适用于需要多个远程调用结果的应用。只有互相独立——不依赖彼此结果——的调用才能这样批量发起； + 当一个调用依赖另一个调用的结果时，两者只能串行执行。通过 + Yar_Client + 调用会一个接一个地发送，每次都要付出完整的往返时间； + 而使用并发客户端时它们会同时发出，因此整体等待时间降为最慢单次调用的耗时。 + - 并发调用仅支持 HTTP(S) 服务。 + 并发调用仅支持 HTTP(S) 服务。这些调用通过 curl 的 multi-handle + 接口同时发出，TCP/Unix socket 传输方式没有提供该能力。 diff --git a/reference/yar/yar-server.xml b/reference/yar/yar-server.xml index a2d6c0711..90eb27823 100644 --- a/reference/yar/yar-server.xml +++ b/reference/yar/yar-server.xml @@ -1,6 +1,6 @@ - + Yar_Server 类 @@ -16,6 +16,11 @@ 通过 Yar_Server::handle 以 HTTP 方式提供服务。 + + PHP 扩展只提供 HTTP 服务器。遵循同一 Yar 协议的 TCP 和 + Unix socket 服务器由 + Yar C 框架提供。 + diff --git a/reference/yar/yar_client/call.xml b/reference/yar/yar_client/call.xml index c2c94a33d..fdd626495 100644 --- a/reference/yar/yar_client/call.xml +++ b/reference/yar/yar_client/call.xml @@ -1,6 +1,6 @@ - + Yar_Client::call @@ -16,8 +16,8 @@ 对远程方法 method 发起一次 RPC 调用。 - 这与在 Yar_Client 对象上调用一个不存在的方法时发生的事情完全相同（参见 - Yar_Client::__call）； + 这与在 Yar_Client 对象上调用一个不存在的方法时发生的事情完全相同 + （通过 PHP 的 __call 魔法方法）； Yar_Client::call 的存在只是为了让名字恰好叫 call 或 __call 的远程方法仍然可以被调用。 @@ -55,17 +55,50 @@ &reftitle.errors; - 如果服务器端不存在 call 方法，会抛出 - Yar_Server_Request_Exception 异常。 - 各种失败情况及其对应的异常类的完整列表，参见 - Yar_Client::__call。 + 当远程方法在服务器上不存在，或不是公开方法时，客户端会抛出错误码为 + YAR_ERR_REQUEST 的 + Yar_Client_Exception。 + 其他客户端侧的失败情况及其对应的异常类，参见 + Yar_Client_Exception。 + + &reftitle.examples; + + <methodname>Yar_Client::call</methodname> 示例 + +add(1, 2)); + +/* Equivalent: call the method explicitly by name */ +var_dump($client->call("add", array(1, 2))); + +/* Needed only when the remote service literally exposes a method + * named call (or __call), which the magic __call cannot reach */ +var_dump($client->call("call", array($some_argument))); +?> +]]> + + &example.outputs.similar; + + + + + + &reftitle.seealso; - Yar_Client::__call Yar_Client::setOpt diff --git a/reference/yar/yar_client/construct.xml b/reference/yar/yar_client/construct.xml index 7a9fb79df..944229df6 100644 --- a/reference/yar/yar_client/construct.xml +++ b/reference/yar/yar_client/construct.xml @@ -1,6 +1,6 @@ - + Yar_Client::__construct @@ -70,10 +70,10 @@ 1000, YAR_OPT_PACKAGER => "json", ]); @@ -86,7 +86,7 @@ $client = new Yar_Client("http://host/api/", [ &reftitle.seealso; - Yar_Client::__call + Yar_Client::call Yar_Client::setOpt diff --git a/reference/yar/yar_client/getopt.xml b/reference/yar/yar_client/getopt.xml index ef0b921c6..a70b70427 100644 --- a/reference/yar/yar_client/getopt.xml +++ b/reference/yar/yar_client/getopt.xml @@ -1,6 +1,6 @@ - + Yar_Client::getOpt @@ -50,7 +50,7 @@ setOpt(YAR_OPT_TIMEOUT, 1000); var_dump($client->getOpt(YAR_OPT_TIMEOUT)); diff --git a/reference/yar/yar_client/setopt.xml b/reference/yar/yar_client/setopt.xml index 86618f78e..b4883c2ee 100644 --- a/reference/yar/yar_client/setopt.xml +++ b/reference/yar/yar_client/setopt.xml @@ -1,6 +1,6 @@ - + @@ -86,7 +86,7 @@ 每个选项都要求特定类型的值（字符串、布尔、整型或数组）， - 具体说明见常量页。 + 具体说明见常量页面。 @@ -100,7 +100,7 @@ setOpt(YAR_OPT_TIMEOUT, 1000); @@ -126,7 +126,7 @@ $result = $client->some_method("parameter"); &reftitle.seealso; Yar_Client::getOpt - Yar_Client::__call + Yar_Client::call diff --git a/reference/yar/yar_client_exception/gettype.xml b/reference/yar/yar_client_exception/gettype.xml index 7ec4ca83f..00dcdc28b 100644 --- a/reference/yar/yar_client_exception/gettype.xml +++ b/reference/yar/yar_client_exception/gettype.xml @@ -1,6 +1,6 @@ - + Yar_Client_Exception::getType @@ -42,7 +42,7 @@ some_method("parameter"); diff --git a/reference/yar/yar_concurrent_client/call.xml b/reference/yar/yar_concurrent_client/call.xml index b5c945bb9..37b86138f 100644 --- a/reference/yar/yar_concurrent_client/call.xml +++ b/reference/yar/yar_concurrent_client/call.xml @@ -1,6 +1,6 @@ - + Yar_Concurrent_Client::call @@ -25,7 +25,8 @@ - 仅支持 HTTP 和 HTTPS URI。并发调用不支持 TCP 和 Unix socket 传输方式。 + 仅支持 HTTP 和 HTTPS URI。并发调用通过 curl 的 multi-handle 接口同时发出， + TCP/Unix socket 传输方式没有提供该能力。 @@ -63,12 +64,18 @@ 当此次调用的响应到达时调用的 callable， - 接收两个参数：响应值，以及一个包含 - sequence、uri 和 - method 三个键的 callinfo &array;。 + 接收两个参数：响应值，以及一个描述该调用的 + callinfo &array;： + + + sequence ——注册该调用时返回的序列号 + uri ——服务的地址 + method ——远程方法的名称 + + 如果省略，则使用 Yar_Concurrent_Client::loop 的 - callback。 + callback；两者都不设置时的行为参见该方法。 @@ -78,10 +85,10 @@ 当此次调用失败时调用的 callable， 接收三个参数：错误类型（YAR_ERR_* - 错误码之一）、错误消息，以及 callinfo &array;。 + 错误码之一）、错误消息，以及上述的 callinfo &array;。 如果省略，则使用 Yar_Concurrent_Client::loop 的 - error_callback。 + error_callback；两者都不设置时的行为参见该方法。 @@ -129,16 +136,16 @@ function error_callback($type, $error, $callinfo) error_log($error); } -Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"), "callback"); +Yar_Concurrent_Client::call("http://api.example.com/operator.php", "some_method", array("parameters"), "callback"); -/* 如果不指定回调, 将使用 loop() 的回调 */ -Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters")); +/* 如果不指定回调，将使用 loop() 的回调 */ +Yar_Concurrent_Client::call("http://api.example.com/operator.php", "some_method", array("parameters")); /* 该服务器接受 JSON 打包器 */ -Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"), "callback", NULL, array(YAR_OPT_PACKAGER => "json")); +Yar_Concurrent_Client::call("http://api.example.com/operator.php", "some_method", array("parameters"), "callback", NULL, array(YAR_OPT_PACKAGER => "json")); /* 自定义超时时间 */ -Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"), "callback", NULL, array(YAR_OPT_TIMEOUT => 1000)); +Yar_Concurrent_Client::call("http://api.example.com/operator.php", "some_method", array("parameters"), "callback", NULL, array(YAR_OPT_TIMEOUT => 1000)); /* 此时请求尚未发送 */ ]]> diff --git a/reference/yar/yar_concurrent_client/loop.xml b/reference/yar/yar_concurrent_client/loop.xml index 79b299ca8..9b6b6cec5 100644 --- a/reference/yar/yar_concurrent_client/loop.xml +++ b/reference/yar/yar_concurrent_client/loop.xml @@ -1,6 +1,6 @@ - + Yar_Concurrent_Client::loop @@ -21,6 +21,18 @@ 并阻塞直到每一个响应都已到达并被处理完毕。 此方法返回时，调用列表会被清空。 + + 由于这些调用是同时执行的，loop 的耗时只等于最慢单次调用的耗时， + 而不是所有调用耗时之和。但回调不会按照调用注册的顺序触发： + 哪个响应先到达，就先触发哪个回调。要确定某个响应属于哪次调用， + 可以将 callinfo 参数中的 + sequence 与 + Yar_Concurrent_Client::call + 返回的序列号进行对照。callinfo &array; + 包含该调用的 sequence、uri 和 + method；参见 + Yar_Concurrent_Client::call。 + @@ -30,9 +42,12 @@ callback - 用于处理注册时没有指定自身回调的调用的响应的 callable。 - 在全部请求发送完毕后，它还会先于任何响应到达之前， - 额外被调用一次，此时两个参数均为 &null;。 + callable，用于处理未指定自身回调的调用的响应。 + 在全部请求发送完毕后、任何响应到达之前，它还会额外被调用一次， + 此时两个参数均为 &null;。 + + + 如果省略该参数，成功调用的返回值会在其响应到达时被直接打印输出。 @@ -40,10 +55,15 @@ error_callback - 用于处理注册时没有指定自身错误回调的调用的错误的 callable。 + callable，用于处理未指定自身错误回调的调用的错误。 接收三个参数：错误类型（YAR_ERR_* 错误码之一）、错误消息，以及 callinfo &array;。 + + 如果省略该参数，失败的调用会改为触发一条 PHP 警告； + 这一点与同步的 Yar_Client 不同， + 后者会抛出异常。 + @@ -89,10 +109,10 @@ function error_callback($type, $error, $callinfo) { error_log($error); } -Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"), "callback"); +Yar_Concurrent_Client::call("http://api.example.com/operator.php", "some_method", array("parameters"), "callback"); -/* 如果不指定回调, 将使用 loop() 的回调 */ -Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters")); +/* 如果不指定回调，将使用 loop() 的回调 */ +Yar_Concurrent_Client::call("http://api.example.com/operator.php", "some_method", array("parameters")); Yar_Concurrent_Client::loop("callback", "error_callback"); ?> diff --git a/reference/yar/yar_concurrent_client/reset.xml b/reference/yar/yar_concurrent_client/reset.xml index 59421c20a..f4b3abc8d 100644 --- a/reference/yar/yar_concurrent_client/reset.xml +++ b/reference/yar/yar_concurrent_client/reset.xml @@ -1,6 +1,6 @@ - + Yar_Concurrent_Client::reset @@ -50,9 +50,9 @@ function callback($retval, $callinfo) { var_dump($retval); } -Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"), "callback"); +Yar_Concurrent_Client::call("http://api.example.com/operator.php", "some_method", array("parameters"), "callback"); -/* 从未发送: 丢弃已注册的调用 */ +/* 从未发送：丢弃已注册的调用 */ Yar_Concurrent_Client::reset(); ?> ]]> diff --git a/reference/yar/yar_server/construct.xml b/reference/yar/yar_server/construct.xml index 0ea68cfd8..ffa1162fa 100644 --- a/reference/yar/yar_server/construct.xml +++ b/reference/yar/yar_server/construct.xml @@ -1,6 +1,6 @@ - + Yar_Server::__construct @@ -29,6 +29,40 @@ 任意一个对象，其公开方法将被作为 RPC 服务对外暴露。 受保护和私有方法，以及方法名以下划线开头的方法，不会被暴露。 + + 执行对象还可以定义两个受保护的魔法方法， + 它们会被 Yar_Server::handle + 识别，且永远不会作为 RPC 端点对外暴露： + + + + + protected function __info(string $markup): + string — 自 Yar 2.3.0 起。在请求服务信息页面时被调用； + 它接收 Yar 原本要渲染的页面标记（markup）， + 如果返回一个 &string;，该字符串会被发送给客户端， + 替代默认的页面。参见 + Yar_Server::handle。 + + + + + protected function __auth(string $provider, string + $token): bool — 自 Yar 2.3.0 起。在每个请求处理的最开始被调用， + 请求头中的 provider 和 + token 字段会作为参数传入， + 这两个字段由客户端通过 + YAR_OPT_PROVIDER 和 + YAR_OPT_TOKEN 选项设置。 + 严格返回 &false; 表示拒绝该请求；任何其他返回值都会让请求继续。 + 参见 Yar_Server::handle。 + + + + + 这两个方法只有在声明为 protected 时才生效； + 同名的公开或私有方法会被忽略。 + diff --git a/reference/yar/yar_server/handle.xml b/reference/yar/yar_server/handle.xml index d8cf06493..4f685777c 100644 --- a/reference/yar/yar_server/handle.xml +++ b/reference/yar/yar_server/handle.xml @@ -1,6 +1,6 @@ - + Yar_Server::handle @@ -28,12 +28,10 @@ - 自 Yar 2.3.0 起，可以在执行对象上定义一个名为 - __info 的 protected 方法， - 以自定义服务信息页面。当 GET 请求到达时，Yar 会调用该方法， - 并将它原本要渲染的页面标记（markup）作为参数传入； - 如果该方法返回一个 &string;，这个字符串会被发送给客户端， - 替代默认的页面。 + 自 Yar 2.3.0 起，执行对象可以定义受保护的魔法方法 + __info 和 __auth， + 分别用于自定义服务信息页面和验证请求的身份； + 详情参见 Yar_Server::__construct。 @@ -160,8 +158,8 @@ class API { } /* - * 必须声明为 protected。当收到 GET 请求时调用, - * 传入 Yar 原本要渲染的页面标记(markup), + * 必须声明为 protected。当收到 GET 请求时调用， + * 传入 Yar 原本要渲染的页面标记（markup）， * 其返回的字符串会被发送给客户端以替代默认页面。 */ protected function __info($markup) { diff --git a/reference/yar/yar_server_exception/gettype.xml b/reference/yar/yar_server_exception/gettype.xml index 42e96d5ef..70bded435 100644 --- a/reference/yar/yar_server_exception/gettype.xml +++ b/reference/yar/yar_server_exception/gettype.xml @@ -1,6 +1,6 @@ - + Yar_Server_Exception::getType @@ -59,7 +59,7 @@ $service->handle(); throw_exception("client"); From 63acc80d0ce8a1f91fc528063931df9d244b9bbb Mon Sep 17 00:00:00 2001 From: Luffy Date: Sun, 30 Aug 2026 08:53:25 +0800 Subject: [PATCH 2/2] Update protocol.xml --- reference/yar/protocol.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/yar/protocol.xml b/reference/yar/protocol.xml index 13a6808d7..f4e6a2d07 100644 --- a/reference/yar/protocol.xml +++ b/reference/yar/protocol.xml @@ -1,6 +1,6 @@ - + Yar 协议