金融科技后端【免费下载链接】pay可能是我用过的最优雅的 Alipay/WeChat/Douyin/Unipay/江苏银行 的支付 SDK 扩展包了项目地址https://gitcode.com/gh_mirrors/pa/pay点击查看免费下载本篇指南聚焦yansongda/pay抖音支付通用交易系统 trade_basic的订单查询能力一次Pay::douyin()-query($order)调用通过_action参数即可分发到订单查询、CPS 信息查询与退款单查询三类官方接口。读完本文你将掌握三类查询的完整调用方式、必填参数规则、返回值形态以及查询背后的插件管线与源码级实现原理可直接用于对账、风控与售后等真实业务场景。1. 方法总览一个 query 方法三类查询能力抖音通用交易系统的查询统一由query方法完成方法签名如下方法名参数返回值queryarray $orderCollection查询目标通过$order参数中的_action键分发不传时默认查询订单对应关系如下_action说明对应官方 API 端点order默认查询订单/api/trade_basic/v1/developer/order_query/cps查询 CPS/api/trade_basic/v1/developer/query_cps/refund查询退款单/api/trade_basic/v1/developer/refund_query/从源码看分发逻辑实现在 QueryShortcut.php 中getPlugins()通过match表达式按_action值匹配_action缺省时取DouyinAction::QUERY_DEFAULT即default与order等价非法_action会抛出InvalidParamsException错误码为PARAMS_SHORTCUT_ACTION_INVALID。全部合法取值定义在 DouyinAction.phpQUERY_DEFAULT default、QUERY_ORDER order、QUERY_CPS cps、QUERY_REFUND refund。2. 查询支付订单order默认不传_action或显式传_action order均查询订单Pay::config($config); $order [ out_order_no 202408040747147327, // _action order, // 查询订单默认 ]; $result Pay::douyin()-query($order);2.1 订单配置参数order_id抖音侧订单号与out_order_no商户侧订单号二选一必填其余参数与官方接口无任何差别兼容所有功能字段。全部参数请参考官方「查询订单」接口的「请求参数」一栏对应端点order_query。需要强调的是SDK 对业务字段采取全量透传策略查询插件只负责设置请求方法与请求地址不注入、不篡改任何业务字段。这一点在 QueryPlugin.php 中体现得十分明确——assembly()仅向 payload 合并_method与_url两个键测试 QueryPluginTest.php 也断言了传入order_id后 payload 中仅新增_method/_url不会出现app_id等多余字段保证与官方请求参数一一对应。3. 查询 CPS 信息cpsPay::config($config); $order [ out_order_no 202408040747147327, _action cps, ]; $result Pay::douyin()-query($order);3.1 订单配置参数与订单查询一致order_id与out_order_no二选一必填其余参数参照官方「查询 CPS」接口的「请求参数」一栏端点query_cps。实现上由 QueryCpsPlugin.php 完成行为与QueryPlugin完全相同仅设置POST方法与/api/trade_basic/v1/developer/query_cps/地址业务字段透传。4. 查询退款订单refundPay::config($config); $order [ out_refund_no 202408040747147327R, _action refund, ]; $result Pay::douyin()-query($order);4.1 订单配置参数退款查询的必填参数为三选一refund_id抖音侧退款单号out_refund_no商户侧退款单号order_id抖音侧订单号按订单查询上限 50 条。其余参数参照官方「查询退款」接口的「请求参数」一栏端点refund_query。与订单/CPS 查询不同的是退款查询插件 Refund/QueryPlugin.php 增加了参数非空校验若 payload 经filter_params过滤后为空会直接抛出InvalidParamsException错误码PARAMS_NECESSARY_PARAMS_MISSING提示缺少必要的业务参数避免向官方发送无意义的空请求。5. 底层实现查询管线与源码剖析5.1 插件管线query方法在 Provider/Douyin.php 中先派发MethodCalled事件再经__call(query, ...)动态加载QueryShortcut并组装插件管线。三类查询对应的管线均由 QueryShortcut.php 返回以订单查询为例StartPlugin → ObtainClientTokenPlugin → QueryPlugin → AddPayloadBodyPlugin → AddRadarPlugin → ResponsePlugin → ParserPluginCPS 与退款查询仅将中间的QueryPlugin替换为QueryCpsPlugin/Refund\QueryPlugin其余环节完全一致。这一结构在 QueryShortcutTest.php 中被逐条断言五个用例分别验证了默认、order、cps、refund 的插件链以及非法_action抛异常。各环节职责如下StartPlugin初始化 Rocket 与运行环境ObtainClientTokenPlugin注入client_token优先使用params[_access_token]外部注入否则自动获取并进程内缓存对应 all.md 中的基础插件说明业务插件QueryPlugin / QueryCpsPlugin / Refund\QueryPlugin设置端点与请求方法AddPayloadBodyPlugin组装请求体AddRadarPlugin构建请求注入access-token请求头并序列化 JSON body_body优先ResponsePlugin校验响应要求 HTTP 2xx 且顶层err_no 0异常消息取err_msg ?? err_tipsParserPlugin将响应解析为Collection返回。5.2 client_token 的获取与缓存查询类接口需要携带access-token请求头完成鉴权token 的获取逻辑位于 DouyinTrait.php 的getDouyinClientToken()端点POST /oauth/client_token/请求体包含grant_typeclient_credential、client_key、client_secret子调用管线为[StartPlugin, GetClientTokenPlugin, AddRadarPlugin, ParserPlugin]仅传最小参数集仅_config避免业务字段混入 token 请求体结果按app_id缓存在静态数组$clientTokens中expires_in默认 7200 秒提前 60 秒过期若业务方自建了共享缓存可通过params[_access_token]外部注入 token优先级高于自动获取。5.3 请求地址与沙盒注意事项业务端点统一为POST /api/trade_basic/v1/developer/name/形式注意尾斜杠域名由mode决定定义在 Provider/Douyin.php 的URL常量中normal与service指向https://open.douyin.comsandbox指向https://open-sandbox.douyin.com。重要限制trade_basic业务接口没有沙盒环境。MODE_SANDBOX会把包括查询在内的全部请求指向open-sandbox.douyin.com该域名并未部署trade_basic服务仅适合验证client_token获取。真实查询请使用MODE_NORMAL详见 快速入门。6. 配置要求纯查询用户的最小配置抖音查询所需的配置项定义在 DouyinConfig.php与通用交易系统保持一致douyin: { default: { app_id: ttxxxxxx, // 必填client_key即小程序 appid app_secret: xxx, // 必填获取 client_token app_private_key: -----BEGIN ..., // 应用私钥下单加签用纯查询无需配置 douyin_public_key: -----BEGIN ..., // 平台公钥回调验签用纯查询无需配置 notify_url: https://xx/notify, // 选填支付/退款回调默认地址 mode: 0 } }必填校验仅包含app_idapp_secret缺失时抛CONFIG_DOUYIN_INVALID错误码 9405两把 RSA 密钥在使用点校验因此只做查询、不做下单与回调的业务方无需配置私钥与平台公钥这是查询链路相对下单/回调更轻量的关键设计。7. 返回值与事件查询成功返回Collection类型即官方响应的解析结果含err_no/err_msg/log_id及业务数据data可直接链式取用例如$result Pay::douyin()-query($order); $outOrderNo $result-get(data.out_order_no); // 按实际响应结构取字段同时Provider\Douyin::query()在每次调用时会派发MethodCalled事件对应 MethodCalled.php可用于链路日志与埋点观测若需更深层的请求/响应追踪还可借助 HttpStart.php 与 HttpEnd.php 事件。关于抖音回调、退款等周边能力可进一步阅读 douyin-trade-system.md通用交易系统完整设计说明与 all.md全部可用插件清单。8. 常见问题速查三个接口请求参数记不住怎么办记住口诀订单/CPS 查询order_id与out_order_no二选一退款查询refund_id、out_refund_no、order_id三选一按订单查上限 50 条。传了非法_action会怎样抛出InvalidParamsExceptionPARAMS_SHORTCUT_ACTION_INVALID提示不支持的 _action。查询报PARAMS_NECESSARY_PARAMS_MISSING常见于_actionrefund且三选一参数全部缺失补充任一退款/订单号即可。沙盒模式查不到数据属预期行为trade_basic无沙盒部署请切回正式环境mode: 0。高并发下 token 被频控进程内缓存按app_id提前 60 秒过期官方频控约为 5 分钟 500 次可通过_access_token外部注入接入 Redis 等共享缓存。至此抖音通用交易系统的三类查询已全部打通一个入口方法、一个_action参数、一组清晰的必填规则配合源码级的插件管线理解足以应对订单对账、CPS 结算核对与退款状态轮询等绝大多数生产场景。赞分享金融科技后端【免费下载链接】pay可能是我用过的最优雅的 Alipay/WeChat/Douyin/Unipay/江苏银行 的支付 SDK 扩展包了项目地址https://gitcode.com/gh_mirrors/pa/pay点击查看免费下载相关推荐yansongda/pay 江苏银行 e融支付订单查询实战query() 查询交易支付订单与退款订单yansongda/pay 江苏银行 e融支付订单查询实战query 查询交易支付订单与退款订单 本篇技术指南围绕 yansongda/pay 扩展包中江苏银金融科技后端yansongda/pay 抖音小程序支付实战通用交易系统trade_basicJSAPI 下单签名指南yansongda/pay 抖音小程序支付实战通用交易系统trade_basicJSAPI 下单签名指南 本篇技术指南聚焦 yansongda/pay 中金融科技后端yansongda/pay 抖音快速入门通用交易系统小程序支付集成实战yansongda/pay 抖音快速入门通用交易系统小程序支付集成实战 本篇技术指南围绕 yansongda/pay v3.8 起的抖音「通用交易系统」tr金融科技后端上一篇OpiumOCaml开发者必备的轻量级Web框架入门指南下一篇掌握Ollama模型可复现性确保AI实验一致性的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
