文档知识库后端前端【免费下载链接】showdocShowDoc is a tool greatly applicable for an IT team to share documents online一个非常适合IT团队的在线API文档、技术文档工具项目地址https://gitcode.com/gh_mirrors/sh/showdoc点击查看免费下载导读Guzzle Commandsguzzlehttp/command是 Guzzle HTTP 生态中面向服务客户端Service Client的底层基础库它在 Guzzle 6.x 的 HTTP 请求/响应之上抽象出更高层次的**命令Command与结果Result对象并提供一套与 HTTP 层平行的中间件Middleware**体系用于定制命令 → 请求 → 响应 → 结果的完整生命周期。读完本文你将掌握 Command/Result 的核心模型、ServiceClient 的构造与执行机制、异步与并发请求的用法以及如何通过 HandlerStack 与转换器扩展自己的 Web Service 客户端。本文所引用的源码均来自当前仓库的 vendor 目录guzzlehttp/command 包主仓库将其作为 Composer 依赖纳入server/vendor见根目录 composer.json 中vendor-dir: ./server/vendor的配置。一、核心概念Command、Result 与 Service Client官方 README 用三句话定义了该库的全部核心模型Commands键值对对象代表 Web 服务的一个操作operation包含操作名称name与一组参数parameters。Results键值对对象代表执行一次 Web 服务操作后处理完成的结果。Service Clients实现了GuzzleHttp\Command\ServiceClientInterface的 Web 服务客户端内部使用一个底层的 Guzzle HTTP 客户端GuzzleHttp\Client与远端服务通信。从源码结构看这层抽象的边界非常清晰HTTP 层关心请求怎么发、响应怎么收而 Command 层关心操作是什么、结果怎么用。ServiceClient.php 的类注释将其定位为 the foundation for creating web service clients that interact with RPC-style APIs即专门面向 RPC 风格 API 的客户端基座。1.1 Command操作的定义Command.php 是默认实现核心结构只有三样东西$name命令名操作名通过getName()获取$args参数键值对构造时直接存入数据区$handlerStack该命令实例私有的 HandlerStack用于挂载命令级中间件。CommandInterface.php 进一步揭示了 Command 的对象本质它同时实现\ArrayAccess、\IteratorAggregate、\Countable与ToArrayInterface因此命令对象可以被当作数组一样读写$command[param] value也可以直接count()或 foreach 遍历。接口额外定义了getName()、hasParam($name)和getHandlerStack()三个领域方法。1.2 Result结果的载体Result.php 与 ResultInterface.php 同样基于数组语义ResultInterface继承ArrayAccess / IteratorAggregate / Countable / ToArrayInterfaceREADME 中强调 Result objects areArrayAccess-ible and contain the data parsed from HTTP response即 Result 中承载的是从 HTTP 响应解析出的业务数据。1.3 数组语义的统一实现HasDataTraitCommand 与 Result 的数组行为全部来自同一个 HasDataTrait.php它实现了offsetExists用array_key_exists判断键是否存在区别于isset值为null时依然算存在offsetGet键不存在时返回nulloffsetSet/offsetUnset常规读写count()/getIterator()支持count()与 foreachtoArray()还原为普通 PHP 数组便于序列化或直接返回给调用方__toString()print_r输出方便调试。二、安装与版本约束官方 README 给出的安装命令为composer require guzzlehttp/command针对旧版 Guzzle 5 的环境需要锁定 0.8 系列composer require guzzlehttp/command:0.8.*注意若 Composer 未全局安装需使用php composer.pharcomposer.phar为你的 Composer 文件路径代替composer命令。当前仓库中实际锁定的是基于 Guzzle 6.x 的版本。查看包的 composer.json 可得到精确的依赖约束依赖版本约束说明php5.5.0包自身对 PHP 版本的最低要求guzzlehttp/guzzle^6.2底层 HTTP 客户端guzzlehttp/promises~1.3异步 Promise 实现guzzlehttp/psr7~1.0PSR-7 消息实现命名空间按 PSR-4 注册为GuzzleHttp\Command\ → src/。需要注意该包只要求 PHP 5.5而当前 ShowDoc 主项目要求 PHP7.4见根目录 composer.json因此在本仓库环境中可以放心使用更高版本的 PHP 特性。三、实例化 Service ClientREADME 中 Instantiating a Service Client 一节标注为TODO仅列出了三个关键词。结合 ServiceClient.php 的构造器实现可以完整还原实例化过程。3.1 构造器签名public function __construct( HttpClient $httpClient, // 底层 Guzzle HTTP 客户端 callable $commandToRequestTransformer, // Command → Request 转换器 callable $responseToResultTransformer, // Response → Result 转换器 HandlerStack $commandHandlerStack null // 命令级中间件栈可选 )四个参数的作用均来自源码注释与实现$httpClient一个配置完成的GuzzleHttp\ClientInterface负责真正发出 HTTP 请求。它是唯一必需的基础设施所有命令最终都会落到它上面执行。$commandToRequestTransformer可调用对象接收一个GuzzleHttp\Command\CommandInterface返回一个Psr\Http\Message\RequestInterface。这是把业务操作翻译成具体 HTTP 报文的环节如填充 URL、请求方法、头、查询参数与请求体。$responseToResultTransformer可调用对象接收Psr\Http\Message\ResponseInterface可选地接收RequestInterface与CommandInterface返回ResultInterface。这是把 HTTP 响应解析为业务结果的环节如 JSON 解码、字段映射。$commandHandlerStack可选命令级 HandlerStack。若未传入构造器会new HandlerStack()并用createCommandHandler()设置兜底 handlerServiceClient.php。后续中间件就是叠加在这个栈上的。3.2 完整实例化示例use GuzzleHttp\Client; use GuzzleHttp\Command\ServiceClient; use GuzzleHttp\HandlerStack; use GuzzleHttp\Psr7\Request; $httpClient new Client([base_uri https://api.example.com]); // Command → Request把命令名映射为 HTTP 请求 $commandToRequestTransformer function ($command) { return new Request(POST, / . $command-getName(), [ Content-Type application/json, ], json_encode($command-toArray())); }; // Response → Result把响应体 JSON 转为 Result $responseToResultTransformer function ($response) { return new \GuzzleHttp\Command\Result(json_decode($response-getBody(), true)); }; $client new ServiceClient( $httpClient, $commandToRequestTransformer, $responseToResultTransformer );实际项目中base_uri通常会与具体 API 的路径规则、认证头、签名逻辑一起封装在转换器内两个转换器正是协议适配的天然注入点。四、执行命令getCommand 与 execute4.1 创建命令Service Client 通过getCommand()创建命令对象README 原始示例$commandName foo; $arguments [baz bar]; $command $client-getCommand($commandName, $arguments);源码实现ServiceClient.php值得注意public function getCommand($name, array $params []) { return new Command($name, $params, clone $this-handlerStack); }这里对 handler stack 做了clone意味着每个命令实例都拥有自己的栈副本可以在执行前单独追加命令级中间件而不影响客户端共享栈Command.php 的__clone会递归克隆 handler stack。4.2 执行命令创建命令后用execute()执行$result $client-execute($command);返回的$result是GuzzleHttp\Command\ResultInterface对象可以直接像数组一样读取echo $result[fizz]; // 输出 buzz4.3 魔法方法快捷调用Service Client 还提供了魔法方法__callServiceClient.php作为快捷方式调用一个不存在的方法时方法名即命令名参数数组即命令参数省去单独创建 Command 的步骤$result $client-foo([baz bar]); // 等价于 execute(getCommand(foo, [baz bar]))__call的实现逻辑是若方法名以Async结尾substr($name, -5) Async则剥离后缀得到命令名并走executeAsync否则直接execute(getCommand(...))。4.4 命令的 http 特殊参数在 createCommandHandler() 中可以看到一个隐藏的魔法键$opts $command[http] ?: []; unset($command[http]);即命令可以携带名为http的参数其值作为该次请求的 HTTP 层选项如超时、代理、自定义 header直接透传给$this-httpClient-sendAsync($request, $opts)且会在发送前从命令中移除不会污染业务参数。五、异步命令executeAsync 与 Async 后缀README 明确列出了异步执行的两种方式并给出了原始示例// 创建并执行异步命令 $command $client-getCommand(foo, [baz bar]); $promise $client-executeAsync($command); // 使用魔法方法执行异步命令 $promise $client-fooAsync([baz bar]);5.1 executeAsync 的底层逻辑executeAsync() 的实现非常简洁public function executeAsync(CommandInterface $command) { $stack $command-getHandlerStack() ?: $this-handlerStack; $handler $stack-resolve(); return $handler($command); }它优先使用命令自身的 handler stack若存在否则回退到客户端栈resolve()后调用返回的 handler。默认 handler 即createCommandHandler()产生的闭包读取http选项 → 转换命令为请求 →sendAsync发送 → 收到响应后转换为 Result整个过程用Promise\coroutine串联ServiceClient.php。5.2 等待 Promise 完成README 原始示例展示了wait()的用法$result $promise-wait(); echo $result[fizz]; // buzzexecute()本质上就是异步的同步封装ServiceClient.phppublic function execute(CommandInterface $command) { return $this-executeAsync($command)-wait(); }异步 API 的价值在于可以在不阻塞主流程的情况下发起请求随后在合适的时机统一wait()收集结果从而支撑高吞吐的并发场景。六、并发请求executeAll 与 executeAllAsyncREADME 在 Concurrent Requests 一节列出的三个要点是executeAll()、executeAllAsync()以及选项fulfilled、rejected、concurrency接口文档 ServiceClientInterface.php 给出了完整的语义。6.1 接口约定executeAll($commands, array $options [])接收命令数组或迭代器同步并发执行返回结果数组executeAllAsync($commands, array $options [])同样接收命令数组或迭代器异步并发执行返回 Promise。三个选项的语义选项类型说明concurrencyint最大并发执行数executeAllAsync的默认值为25fulfilledcallable单个命令成功完成时回调签名function ($result, $key)rejectedcallable单个命令失败时回调签名function ($reason, $key)6.2 实现细节executeAllAsync() 的实现要点未显式指定concurrency时默认取 25用Promise\iter_for将命令集合转为迭代器再包装成生成器逐个executeAsync对命令迭代器中的每个元素强制校验instanceof CommandInterface否则抛出\InvalidArgumentException最终交给Promise\EachPromise以固定池大小并发执行返回其 promise。executeAll() 则在异步基础上做了同步化包装用包装回调把每个命令的 fulfilled/rejected 结果按 key 收集进$resultsexecuteAllAsync(...)-then(...)-wait()完成后对结果ksort()排序返回保证输出顺序与输入命令的顺序一致。6.3 用法示例$commands [ user_1 $client-getCommand(getUser, [id 1]), user_2 $client-getCommand(getUser, [id 2]), user_3 $client-getCommand(getUser, [id 3]), ]; // 同步并发执行返回按 key 排序的结果数组 $results $client-executeAll($commands, [concurrency 5]); // 异步并发执行逐条处理 $promise $client-executeAllAsync($commands, [ concurrency 5, fulfilled function ($result, $key) { echo {$key} done\n; }, rejected function ($reason, $key) { echo {$key} failed: {$reason-getMessage()}\n; }, ]); $promise-wait();七、中间件扩展 Client 行为README 指出中间件可以添加到 Service Client 或底层 HTTP 客户端上分别定制Command → Result与Request → Response两条生命周期。这是本库最有价值的扩展点HTTP 层直接使用 Guzzle 自带的HandlerStack如加日志、重试、鉴权中间件作用于请求发送/响应接收阶段命令层通过 ServiceClient 构造时传入的命令级HandlerStack或每个命令克隆出的私有栈挂载中间件作用于命令→请求转换与响应→结果转换的周边阶段。由于命令在getCommand()时会 clone 客户端栈见 4.1 节因此可以做到全局中间件 单命令中间件的叠加组合。命令级中间件的具体挂载方式与HandlerStack的通用用法一致$stack-push($middleware)其中$middleware是接收$handler并返回新$handler的闭包。八、异常体系CommandException执行命令过程中的任何异常都会被统一包装为GuzzleHttp\Command\Exception\CommandException。在 CommandException.php 的fromPrevious()工厂方法中有一套自动分级逻辑底层异常若是RequestException则提取其 Request 与 Response 存入异常对象根据响应状态码自动选择更具体的异常子类4xx400 status 500→CommandClientException客户端错误5xx500 status 600→CommandServerException服务端错误其余情况 → 通用CommandException。同时CommandException暴露了三个取值方法getCommand()失败的命令、getRequest()引发异常的请求、getResponse()关联响应便于在catch中精确诊断问题。这一设计让调用方可以只捕获一个异常类型却能区分是参数/鉴权这类客户端问题还是远端服务故障。九、总结guzzlehttp/command为构建 RPC 风格的 Web Service 客户端提供了一套小而精的抽象骨架Command封装做什么Result封装得到什么ServiceClient通过两个转换器commandToRequestTransformer、responseToResultTransformer把两者衔接在真实的 HTTP 传输之上而HandlerStack 中间件则负责在两侧生命周期上插入可复用的横切逻辑。同步execute、异步executeAsync/fooAsync、并发executeAll/executeAllAsync三种执行模式覆盖了从单请求到批量高吞吐的典型场景配合http透传选项与 4xx/5xx 自动分级的异常体系足以支撑生产级的 API 客户端封装。如需深入源码推荐按以下顺序阅读当前仓库概念定义CommandInterface.php、ResultInterface.php默认实现Command.php、Result.php、HasDataTrait.php客户端核心ServiceClient.php、ServiceClientInterface.php异常体系CommandException.php赞分享文档知识库后端前端【免费下载链接】showdocShowDoc is a tool greatly applicable for an IT team to share documents online一个非常适合IT团队的在线API文档、技术文档工具项目地址https://gitcode.com/gh_mirrors/sh/showdoc点击查看免费下载相关推荐如何快速构建基于Cohere Command R模型的RAG智能代理系统完整指南如何快速构建基于Cohere Command R模型的RAG智能代理系统完整指南 基于Cohere Command R模型的RAG智能代理系统是一种强大的人工示例工程人工智能VidBee Web 全栈实践基于 TanStack Start 的下载客户端开发、构建与部署指南VidBee Web 全栈实践基于 TanStack Start 的下载客户端开发、构建与部署指南 本篇技术指南围绕 apps/web/README.md h桌面应用音视频AI 应用语音Polar 客户端 Monorepo 完全指南基于 Turborepo 的 TypeScript 前端工作区架构与构建实践Polar 客户端 Monorepo 完全指南基于 Turborepo 的 TypeScript 前端工作区架构与构建实践 导读 本文面向希望理解 Polar后端前端金融科技创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 GuzzleHttp Command 完全指南：基于 Command/Result 抽象构建 Web Service 客户端
文档知识库后端前端【免费下载链接】showdocShowDoc is a tool greatly applicable for an IT team to share documents online一个非常适合IT团队的在线API文档、技术文档工具项目地址https://gitcode.com/gh_mirrors/sh/showdoc点击查看免费下载导读Guzzle Commandsguzzlehttp/command是 Guzzle HTTP 生态中面向服务客户端Service Client的底层基础库它在 Guzzle 6.x 的 HTTP 请求/响应之上抽象出更高层次的**命令Command与结果Result对象并提供一套与 HTTP 层平行的中间件Middleware**体系用于定制命令 → 请求 → 响应 → 结果的完整生命周期。读完本文你将掌握 Command/Result 的核心模型、ServiceClient 的构造与执行机制、异步与并发请求的用法以及如何通过 HandlerStack 与转换器扩展自己的 Web Service 客户端。本文所引用的源码均来自当前仓库的 vendor 目录guzzlehttp/command 包主仓库将其作为 Composer 依赖纳入server/vendor见根目录 composer.json 中vendor-dir: ./server/vendor的配置。一、核心概念Command、Result 与 Service Client官方 README 用三句话定义了该库的全部核心模型Commands键值对对象代表 Web 服务的一个操作operation包含操作名称name与一组参数parameters。Results键值对对象代表执行一次 Web 服务操作后处理完成的结果。Service Clients实现了GuzzleHttp\Command\ServiceClientInterface的 Web 服务客户端内部使用一个底层的 Guzzle HTTP 客户端GuzzleHttp\Client与远端服务通信。从源码结构看这层抽象的边界非常清晰HTTP 层关心请求怎么发、响应怎么收而 Command 层关心操作是什么、结果怎么用。ServiceClient.php 的类注释将其定位为 the foundation for creating web service clients that interact with RPC-style APIs即专门面向 RPC 风格 API 的客户端基座。1.1 Command操作的定义Command.php 是默认实现核心结构只有三样东西$name命令名操作名通过getName()获取$args参数键值对构造时直接存入数据区$handlerStack该命令实例私有的 HandlerStack用于挂载命令级中间件。CommandInterface.php 进一步揭示了 Command 的对象本质它同时实现\ArrayAccess、\IteratorAggregate、\Countable与ToArrayInterface因此命令对象可以被当作数组一样读写$command[param] value也可以直接count()或 foreach 遍历。接口额外定义了getName()、hasParam($name)和getHandlerStack()三个领域方法。1.2 Result结果的载体Result.php 与 ResultInterface.php 同样基于数组语义ResultInterface继承ArrayAccess / IteratorAggregate / Countable / ToArrayInterfaceREADME 中强调 Result objects areArrayAccess-ible and contain the data parsed from HTTP response即 Result 中承载的是从 HTTP 响应解析出的业务数据。1.3 数组语义的统一实现HasDataTraitCommand 与 Result 的数组行为全部来自同一个 HasDataTrait.php它实现了offsetExists用array_key_exists判断键是否存在区别于isset值为null时依然算存在offsetGet键不存在时返回nulloffsetSet/offsetUnset常规读写count()/getIterator()支持count()与 foreachtoArray()还原为普通 PHP 数组便于序列化或直接返回给调用方__toString()print_r输出方便调试。二、安装与版本约束官方 README 给出的安装命令为composer require guzzlehttp/command针对旧版 Guzzle 5 的环境需要锁定 0.8 系列composer require guzzlehttp/command:0.8.*注意若 Composer 未全局安装需使用php composer.pharcomposer.phar为你的 Composer 文件路径代替composer命令。当前仓库中实际锁定的是基于 Guzzle 6.x 的版本。查看包的 composer.json 可得到精确的依赖约束依赖版本约束说明php5.5.0包自身对 PHP 版本的最低要求guzzlehttp/guzzle^6.2底层 HTTP 客户端guzzlehttp/promises~1.3异步 Promise 实现guzzlehttp/psr7~1.0PSR-7 消息实现命名空间按 PSR-4 注册为GuzzleHttp\Command\ → src/。需要注意该包只要求 PHP 5.5而当前 ShowDoc 主项目要求 PHP7.4见根目录 composer.json因此在本仓库环境中可以放心使用更高版本的 PHP 特性。三、实例化 Service ClientREADME 中 Instantiating a Service Client 一节标注为TODO仅列出了三个关键词。结合 ServiceClient.php 的构造器实现可以完整还原实例化过程。3.1 构造器签名public function __construct( HttpClient $httpClient, // 底层 Guzzle HTTP 客户端 callable $commandToRequestTransformer, // Command → Request 转换器 callable $responseToResultTransformer, // Response → Result 转换器 HandlerStack $commandHandlerStack null // 命令级中间件栈可选 )四个参数的作用均来自源码注释与实现$httpClient一个配置完成的GuzzleHttp\ClientInterface负责真正发出 HTTP 请求。它是唯一必需的基础设施所有命令最终都会落到它上面执行。$commandToRequestTransformer可调用对象接收一个GuzzleHttp\Command\CommandInterface返回一个Psr\Http\Message\RequestInterface。这是把业务操作翻译成具体 HTTP 报文的环节如填充 URL、请求方法、头、查询参数与请求体。$responseToResultTransformer可调用对象接收Psr\Http\Message\ResponseInterface可选地接收RequestInterface与CommandInterface返回ResultInterface。这是把 HTTP 响应解析为业务结果的环节如 JSON 解码、字段映射。$commandHandlerStack可选命令级 HandlerStack。若未传入构造器会new HandlerStack()并用createCommandHandler()设置兜底 handlerServiceClient.php。后续中间件就是叠加在这个栈上的。3.2 完整实例化示例use GuzzleHttp\Client; use GuzzleHttp\Command\ServiceClient; use GuzzleHttp\HandlerStack; use GuzzleHttp\Psr7\Request; $httpClient new Client([base_uri https://api.example.com]); // Command → Request把命令名映射为 HTTP 请求 $commandToRequestTransformer function ($command) { return new Request(POST, / . $command-getName(), [ Content-Type application/json, ], json_encode($command-toArray())); }; // Response → Result把响应体 JSON 转为 Result $responseToResultTransformer function ($response) { return new \GuzzleHttp\Command\Result(json_decode($response-getBody(), true)); }; $client new ServiceClient( $httpClient, $commandToRequestTransformer, $responseToResultTransformer );实际项目中base_uri通常会与具体 API 的路径规则、认证头、签名逻辑一起封装在转换器内两个转换器正是协议适配的天然注入点。四、执行命令getCommand 与 execute4.1 创建命令Service Client 通过getCommand()创建命令对象README 原始示例$commandName foo; $arguments [baz bar]; $command $client-getCommand($commandName, $arguments);源码实现ServiceClient.php值得注意public function getCommand($name, array $params []) { return new Command($name, $params, clone $this-handlerStack); }这里对 handler stack 做了clone意味着每个命令实例都拥有自己的栈副本可以在执行前单独追加命令级中间件而不影响客户端共享栈Command.php 的__clone会递归克隆 handler stack。4.2 执行命令创建命令后用execute()执行$result $client-execute($command);返回的$result是GuzzleHttp\Command\ResultInterface对象可以直接像数组一样读取echo $result[fizz]; // 输出 buzz4.3 魔法方法快捷调用Service Client 还提供了魔法方法__callServiceClient.php作为快捷方式调用一个不存在的方法时方法名即命令名参数数组即命令参数省去单独创建 Command 的步骤$result $client-foo([baz bar]); // 等价于 execute(getCommand(foo, [baz bar]))__call的实现逻辑是若方法名以Async结尾substr($name, -5) Async则剥离后缀得到命令名并走executeAsync否则直接execute(getCommand(...))。4.4 命令的 http 特殊参数在 createCommandHandler() 中可以看到一个隐藏的魔法键$opts $command[http] ?: []; unset($command[http]);即命令可以携带名为http的参数其值作为该次请求的 HTTP 层选项如超时、代理、自定义 header直接透传给$this-httpClient-sendAsync($request, $opts)且会在发送前从命令中移除不会污染业务参数。五、异步命令executeAsync 与 Async 后缀README 明确列出了异步执行的两种方式并给出了原始示例// 创建并执行异步命令 $command $client-getCommand(foo, [baz bar]); $promise $client-executeAsync($command); // 使用魔法方法执行异步命令 $promise $client-fooAsync([baz bar]);5.1 executeAsync 的底层逻辑executeAsync() 的实现非常简洁public function executeAsync(CommandInterface $command) { $stack $command-getHandlerStack() ?: $this-handlerStack; $handler $stack-resolve(); return $handler($command); }它优先使用命令自身的 handler stack若存在否则回退到客户端栈resolve()后调用返回的 handler。默认 handler 即createCommandHandler()产生的闭包读取http选项 → 转换命令为请求 →sendAsync发送 → 收到响应后转换为 Result整个过程用Promise\coroutine串联ServiceClient.php。5.2 等待 Promise 完成README 原始示例展示了wait()的用法$result $promise-wait(); echo $result[fizz]; // buzzexecute()本质上就是异步的同步封装ServiceClient.phppublic function execute(CommandInterface $command) { return $this-executeAsync($command)-wait(); }异步 API 的价值在于可以在不阻塞主流程的情况下发起请求随后在合适的时机统一wait()收集结果从而支撑高吞吐的并发场景。六、并发请求executeAll 与 executeAllAsyncREADME 在 Concurrent Requests 一节列出的三个要点是executeAll()、executeAllAsync()以及选项fulfilled、rejected、concurrency接口文档 ServiceClientInterface.php 给出了完整的语义。6.1 接口约定executeAll($commands, array $options [])接收命令数组或迭代器同步并发执行返回结果数组executeAllAsync($commands, array $options [])同样接收命令数组或迭代器异步并发执行返回 Promise。三个选项的语义选项类型说明concurrencyint最大并发执行数executeAllAsync的默认值为25fulfilledcallable单个命令成功完成时回调签名function ($result, $key)rejectedcallable单个命令失败时回调签名function ($reason, $key)6.2 实现细节executeAllAsync() 的实现要点未显式指定concurrency时默认取 25用Promise\iter_for将命令集合转为迭代器再包装成生成器逐个executeAsync对命令迭代器中的每个元素强制校验instanceof CommandInterface否则抛出\InvalidArgumentException最终交给Promise\EachPromise以固定池大小并发执行返回其 promise。executeAll() 则在异步基础上做了同步化包装用包装回调把每个命令的 fulfilled/rejected 结果按 key 收集进$resultsexecuteAllAsync(...)-then(...)-wait()完成后对结果ksort()排序返回保证输出顺序与输入命令的顺序一致。6.3 用法示例$commands [ user_1 $client-getCommand(getUser, [id 1]), user_2 $client-getCommand(getUser, [id 2]), user_3 $client-getCommand(getUser, [id 3]), ]; // 同步并发执行返回按 key 排序的结果数组 $results $client-executeAll($commands, [concurrency 5]); // 异步并发执行逐条处理 $promise $client-executeAllAsync($commands, [ concurrency 5, fulfilled function ($result, $key) { echo {$key} done\n; }, rejected function ($reason, $key) { echo {$key} failed: {$reason-getMessage()}\n; }, ]); $promise-wait();七、中间件扩展 Client 行为README 指出中间件可以添加到 Service Client 或底层 HTTP 客户端上分别定制Command → Result与Request → Response两条生命周期。这是本库最有价值的扩展点HTTP 层直接使用 Guzzle 自带的HandlerStack如加日志、重试、鉴权中间件作用于请求发送/响应接收阶段命令层通过 ServiceClient 构造时传入的命令级HandlerStack或每个命令克隆出的私有栈挂载中间件作用于命令→请求转换与响应→结果转换的周边阶段。由于命令在getCommand()时会 clone 客户端栈见 4.1 节因此可以做到全局中间件 单命令中间件的叠加组合。命令级中间件的具体挂载方式与HandlerStack的通用用法一致$stack-push($middleware)其中$middleware是接收$handler并返回新$handler的闭包。八、异常体系CommandException执行命令过程中的任何异常都会被统一包装为GuzzleHttp\Command\Exception\CommandException。在 CommandException.php 的fromPrevious()工厂方法中有一套自动分级逻辑底层异常若是RequestException则提取其 Request 与 Response 存入异常对象根据响应状态码自动选择更具体的异常子类4xx400 status 500→CommandClientException客户端错误5xx500 status 600→CommandServerException服务端错误其余情况 → 通用CommandException。同时CommandException暴露了三个取值方法getCommand()失败的命令、getRequest()引发异常的请求、getResponse()关联响应便于在catch中精确诊断问题。这一设计让调用方可以只捕获一个异常类型却能区分是参数/鉴权这类客户端问题还是远端服务故障。九、总结guzzlehttp/command为构建 RPC 风格的 Web Service 客户端提供了一套小而精的抽象骨架Command封装做什么Result封装得到什么ServiceClient通过两个转换器commandToRequestTransformer、responseToResultTransformer把两者衔接在真实的 HTTP 传输之上而HandlerStack 中间件则负责在两侧生命周期上插入可复用的横切逻辑。同步execute、异步executeAsync/fooAsync、并发executeAll/executeAllAsync三种执行模式覆盖了从单请求到批量高吞吐的典型场景配合http透传选项与 4xx/5xx 自动分级的异常体系足以支撑生产级的 API 客户端封装。如需深入源码推荐按以下顺序阅读当前仓库概念定义CommandInterface.php、ResultInterface.php默认实现Command.php、Result.php、HasDataTrait.php客户端核心ServiceClient.php、ServiceClientInterface.php异常体系CommandException.php赞分享文档知识库后端前端【免费下载链接】showdocShowDoc is a tool greatly applicable for an IT team to share documents online一个非常适合IT团队的在线API文档、技术文档工具项目地址https://gitcode.com/gh_mirrors/sh/showdoc点击查看免费下载相关推荐如何快速构建基于Cohere Command R模型的RAG智能代理系统完整指南如何快速构建基于Cohere Command R模型的RAG智能代理系统完整指南 基于Cohere Command R模型的RAG智能代理系统是一种强大的人工示例工程人工智能VidBee Web 全栈实践基于 TanStack Start 的下载客户端开发、构建与部署指南VidBee Web 全栈实践基于 TanStack Start 的下载客户端开发、构建与部署指南 本篇技术指南围绕 apps/web/README.md h桌面应用音视频AI 应用语音Polar 客户端 Monorepo 完全指南基于 Turborepo 的 TypeScript 前端工作区架构与构建实践Polar 客户端 Monorepo 完全指南基于 Turborepo 的 TypeScript 前端工作区架构与构建实践 导读 本文面向希望理解 Polar后端前端金融科技创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考