企业官网建设流程全解析

• 金融科技
• 后端

本篇指南围绕 yansongda/pay（基于 yansongda/artful 构建的多渠道支付 SDK）梳理「任何一次 API 调用最终会返回什么」这一核心问题。通过阅读本文，你将掌握三种返回类型（MessageInterface、Collection、Rocket）各自的出现场景、底层来源与框架适配方式，并学会用_return_rocket参数进入调试模式、用toArray()获取纯数组数据，从而在 Laravel、ThinkPHP、Hyperf 等框架中精准消费返回值。

一、总览：一次调用的三种返回类型

yansongda/pay 通过Pay::config($config)完成初始化后，所有 provider 方法（如Pay::alipay()->app()、Pay::wechat()->refund()）本质上都会被转发到Yansongda\Artful\Artful的插件管道中执行。这一点可以从 src/Pay.php 的静态代理实现看出：

public static function __callStatic(string $service, array $config = []) { if (!empty($config)) { self::config(...$config); } return Artful::get($service); }

Pay是Artful的门面，因此「返回格式与 yansongda/artful 完全一致」并非巧合，而是架构使然——composer.json 中明确声明依赖yansongda/artful: ~1.2.0与yansongda/supports: ~4.1.0，后者提供了Collection实现。

最终返回的类型只有以下三种（具体是哪种，视调用方法而定，下文逐一展开）：

:::tip 最终到底返回哪一种类型，取决于你调用的具体方法（app()、web()、query()、refund()等），而非由全局配置决定。 :::

二、MessageInterface：直接面向框架的响应对象

\Psr\Http\Message\MessageInterface是 PSR-7 规范中的消息接口，在支付 SDK 语境下，最终实例/接口为\GuzzleHttp\Psr7\Response——一个携带状态码、响应头和响应体的 HTTP 响应对象。

2.1 哪些方法返回 Response

• 支付宝（Alipay）：
  • app()：APP 支付，返回的是携带唤起支付宝客户端所需参数串的响应体；
  • web()：电脑网站支付；
  • h5()：手机网站支付；
  • success()：异步回调处理完毕后的应答响应。
• 微信（Wechat）：
  • success()：回调应答响应。

这些方法的返回值签名可以在 src/Provider/Alipay.php 与 src/Provider/Wechat.php 的@method注解中直接看到，例如：

/** * @method ResponseInterface|Rocket app(array<string, mixed> $order) APP 支付 * @method ResponseInterface|Rocket h5(array<string, mixed> $order) 手机网站支付 * @method ResponseInterface|Rocket web(array<string, mixed> $order) 电脑支付 * @method Collection|Rocket pos(array<string, mixed> $order) 刷卡支付（付款码，被扫码） * @method Collection|Rocket mini(array<string, mixed> $order) 小程序支付 */

可见「支付」类场景多返回ResponseInterface，而「交易管理」类场景（pos/scan/transfer/mini 等）返回Collection。

2.2 Response 是怎么构造出来的

以支付宝 APP 支付为例，一次调用经由AppShortcut编排的插件链完成，见 src/Shortcut/Alipay/AppShortcut.php：

return [ StartPlugin::class, PayPlugin::class, FormatPayloadBizContentPlugin::class, AddPayloadSignaturePlugin::class, ResponseInvokeStringPlugin::class, ParserPlugin::class, ];

其中ResponseInvokeStringPlugin负责把已经完成签名封装的 payload 组装成 PSR-7 响应，见 src/Plugin/Alipay/V2/ResponseInvokeStringPlugin.php：

$response = new Response(200, [], Arr::query($rocket->getPayload()->all())); $rocket->setDestination($response);

也就是说，app()/web()/h5()返回的Response并不是支付宝服务端下发的数据，而是本地构造的、用于让商户端「直接向客户端输出」的响应——这正是它能被当作 HTTP 响应返回给调用方的原因。

2.3 框架适配：Laravel 与 ThinkPHP

由于返回的是 PSR-7 规范的Response，在支持 PSR7 的框架中可以直接把它作为请求响应返回。但主流框架的原生响应并非 PSR-7 对象，因此需要桥接：

• Laravel 框架：自行安装symfony/psr-http-message-bridge即可把 PSR-7 响应转换为 Laravel 响应对象并正常返回。该依赖在仓库的 composer.json 的require-dev中亦被引用（symfony/psr-http-message-bridge: ^6.4），说明这是官方认可的桥接方案。
• ThinkPHP 框架：仅在 PSR7 规范支持合入框架主干之后（对应 top-think/framework 的 2614 号 PR）才原生支持 PSR7。因此，旧版本 ThinkPHP 需要参考该 PR 自行解包处理返回数据——即手动读取Response的状态码与响应体内容再包装成 ThinkPHP 响应，无法直接整体返回。

:::warning 如果你的 ThinkPHP 版本较老，切勿直接return该Response对象，否则会得到异常输出；应解包$response->getStatusCode()、$response->getBody()->getContents()等数据后自行组装。 :::

2.4 回调应答的成功写法

支付宝与微信的success()方法返回的都是Response。以 src/Provider/Alipay.php 为例：

public function success(): ResponseInterface { return new Response(200, [], 'success'); }

在接入回调路由时，直接return Pay::alipay()->success();即可向支付平台返回合法的成功应答（响应体为success字符串）。微信侧的success()则更灵活，支持通过_action区分支付分（204 空响应）与虚拟支付（XML/JSON 应答），见 src/Provider/Wechat.php。

三、Collection：默认的 API 调用返回值

3.1 适用面最广的返回类型

默认情况下，支付宝、微信、银联所有 API 调用场景下，绝大多数方法最终都返回Collection实例，例如常用的「退款」「转账」「小程序支付」「查询」等。这与各 Provider 的方法注解一致（见上文 src/Provider/Alipay.php），例如：

• query()/cancel()/close()/refund()均返回Collection|Rocket；
• 微信的close()在调用完成后会显式返回new Collection()，见 src/Provider/Wechat.php。

Collection本质上是一个对数组的面向对象封装，既保留了数组的键值访问，又提供了链式便捷方法。

3.2 便捷取值：支持点号路径

Collection类提供了丰富的快捷方法，其具体 API 以yansongda/supports组件源码为准（该组件由本仓库声明依赖）。这里给出一个点号路径取值的实战示例——抖音客户端令牌的获取逻辑在 src/Traits/DouyinTrait.php 中正是这样做的：

$token = $result->get('data.access_token', ''); $expiresIn = $result->get('data.expires_in', 7200);

即通过get('a.b.c', $default)形式直接按层级路径读取嵌套数据，并支持默认值兜底——这对解析支付平台返回的嵌套 JSON（如alipay.trade.query.response结构）极为方便。

3.3 返回链路：从 Rocket 的 destination 到 Collection

需要说明的是，Collection并非凭空出现：在 Artful 插件管道的末端，ParserPlugin会把Rocket中携带的响应体解析后写入 destination，最终由 Provider 返回给调用方。也就是说，无论你最终拿到Response、Collection还是Rocket，底层走的都是同一条插件管道，区别只在于管道末端对结果的处理方式不同。这一点可以从Alipay::__call统一走Artful::shortcut()的实现（src/Provider/Alipay.php）得到印证。

四、Rocket：调试与自定义的「透视镜」

4.1 什么时候返回 Rocket

一般情况下，Rocket不会作为最终返回值。但如果你有自定义需求（例如需要观察一次调用的完整请求参数、签名前/后的 payload、实际发出的 HTTP 报文等），只需在入参中传递_return_rocket = true：

$params = [ '_return_rocket' => true, ]; Pay::config($config); $rocket = Pay::alipay()->app($params);

此时返回的\Yansongda\Artful\Rocket会携带整条调用链路的上下文，你可以从中取出雷达请求（getRadar()）、载荷（getPayload()）、目的地（getDestination()）等内部状态，非常适合排查签名、参数组装等问题。

4.2 源码与测试的实证

_return_rocket的影响在源码注释中被明确提及——src/Traits/DouyinTrait.php 中为避免子调用返回形态被改变，专门注释道：

_return_rocket会改变返回值形态（PayPal 曾因此修复 #1196），最小参数集从结构上同时排除两个问题。

仓库测试也大量使用该参数验证内部链路，例如 tests/Provider/AlipayTest.php 中testWeb()用例：

$result = Pay::alipay()->web([ 'out_trade_no' => 'web'.time(), 'total_amount' => '0.01', 'subject' => 'yansongda 测试 - 01', '_return_rocket' => true, ]); $radar = $result->getRadar();

随后测试直接断言$radar->getBody()、$radar->getMethod()的内容——这正是 Rocket 模式在真实项目中的典型用法：在调试阶段开启，验证请求报文与签名，排查通过后再移除该参数恢复默认返回。

五、array：一行代码拿回纯数组

在某些场景（例如直接对接旧代码、序列化存储）下，你可能不希望拿到Collection对象，而是希望得到 PHP 原生数组。

由于 API 调用场景下默认返回的是Collection实例，只需调用其toArray()方法即可：

$collection = Pay::alipay()->refund($params); // 假设返回 Collection $array = $collection->toArray();

就是这么简单——Collection与array之间可以零成本互转，无需任何额外配置。因此：

• 需要链式取值、带默认值读取 → 直接用Collection的get()；
• 需要传给既有数组风格的代码、或做json_encode序列化 → 调toArray()；
• 需要完整链路上下文 → 传_return_rocket = true拿Rocket；
• 需要直接输出给客户端 → 使用返回Response的方法并在支持 PSR7 的框架中直接return。

六、小结：按场景选择返回类型

理解这套返回体系，是顺畅使用 yansongda/pay 的基础：它保证了「业务调用拿Collection、页面输出拿Response、深度调试拿Rocket」三种形态互不干扰，且任意形态之间切换成本极低。更多调用入口与初始化方式，可继续查阅 快速开始、支付宝接入、微信接入 等文档。

• 金融科技
• 后端