开发接入检查用例

更新时间:2026.11.18
||| 安装 Skill
1[
2  {
3    "id": "common_sign_verify_crypto",
4    "category": [
5      "工程质量"
6    ],
7    "title": "签名、验签、加解密抽成公共方法",
8    "text": "把签名、验签、敏感字段加解密、回调验签与解密抽成公共方法。业务接口调用这一份,不要在各接口里各写一套。默认使用官方工具类(Java [`WXPayUtility`](https://iwiki.woa.com/p/4014931831)、Go [`wxpay_utility`](https://iwiki.woa.com/p/4015119334))配合 API 列表请求示例实现(知识库内各接口请求示例即基于该工具类,且原生支持微信支付公钥),非 java、go 语言可参考示例进行实现;工程已依赖官方 SDK、或经用户明确选定 SDK 时才使用 SDK,两种方式都须满足本项单点维护要求。"
9  },
10  {
11    "id": "sign_wechat_pay_api_requests",
12    "category": [
13      "资金安全"
14    ],
15    "title": "调用微信支付接口要签名",
16    "text": "APIv3 用商户 API 证书私钥签名并写入 `Authorization`。`serial_no` 填商户 API 证书序列号,不填平台证书序列号或微信支付公钥 ID。见 [4012365342-总述-APIv3如何签名和验签](https://iwiki.woa.com/p/4012365342)。APIv2 按参数名 ASCII 序签名,空值不参与,签名写入 `sign`。见 [4011985891-安全规范](https://iwiki.woa.com/p/4011985891)。"
17  },
18  {
19    "id": "verify_response_and_callback_signatures",
20    "category": [
21      "资金安全"
22    ],
23    "title": "应答和回调都要验签",
24    "text": "应答和回调先验签,通过后再使用。**存在验签方法不等于验签生效**;须核对每个调用点确实调用,且验签失败即中止,不是只记日志继续执行。验签失败如何处理见 [4013053249-如何使用微信支付公钥验签](https://iwiki.woa.com/p/4013053249)。"
25  },
26  {
27    "id": "match_callback_and_query_with_local_order",
28    "category": [
29      "资金安全"
30    ],
31    "title": "回调与查单结果必须与本地订单核对一致",
32    "text": "验签只证明报文来自微信支付,不证明这笔钱属于这笔订单。**验签通过不等于可以直接入账**;须用通知或查单返回的商户订单号定位本地订单,核对金额、商户号、`appid` 与订单归属后才能更新状态。外部交易号须完整持久化,防止串单或被覆盖。见 [4012075420-回调通知注意事项](https://iwiki.woa.com/p/4012075420)。"
33  },
34  {
35    "id": "do_not_skip_signature_probe_verification",
36    "category": [
37      "资金安全"
38    ],
39    "title": "签名探测流量不得跳过验签或直接当成功",
40    "text": "`Wechatpay-Signature` 以 `WECHATPAY/SIGNTEST/` 开头是探测流量。仍要验签。验签失败后应答舍弃,回调返回 `4xx` 或 `5xx`。见 [4013053249-如何使用微信支付公钥验签](https://iwiki.woa.com/p/4013053249)。"
41  },
42  {
43    "id": "keep_secrets_on_server_only",
44    "category": [
45      "资金安全"
46    ],
47    "title": "密钥只留服务端,不得泄露到任何外部可获取的位置",
48    "text": "商户 API 私钥、证书、APIv3 密钥、APIv2 密钥只留在服务端,从环境变量或 KMS 加载,**不得硬编码**。禁止进入源码、仓库、日志、接口响应和可被 URL 直接访问的目录。疑似泄露立即更换;从仓库删除不能使已泄露密钥失效。**使用环境变量或 KMS 不等于密钥安全**;还须核对配置是否随仓库分发、读取权限,以及日志与异常是否回显密钥内容。见 [4012073693-密钥泄漏修复指引](https://iwiki.woa.com/p/4012073693)。"
49  },
50  {
51    "id": "encrypt_sensitive_fields_per_api_doc",
52    "category": [
53      "资金安全"
54    ],
55    "title": "敏感字段加解密按接口文档逐字段执行",
56    "text": "哪些字段需加密、用公钥还是平台证书,以该接口文档的字段说明为准(含 `Wechatpay-Serial` 请求头应传公钥 ID 还是平台证书序列号,与 `Authorization` 中的商户证书序列号不是同一个);应答中的密文用商户私钥解密。"
57  },
58  {
59    "id": "use_backend_values_for_critical_fields",
60    "category": [
61      "资金安全"
62    ],
63    "title": "资金 / 关键字段一律以后端为准,严禁相信前端传值",
64    "text": "调用微信 API 的金额、商户号、用户标识、业务类型等关键字段必须从可信后端数据源读取;前端传入仅作为引导,不能直接落库或入参。下单金额由服务端计算,不采用前端传入的金额。"
65  },
66  {
67    "id": "use_integer_cents_for_amounts",
68    "category": [
69      "资金安全"
70    ],
71    "title": "金额全程使用整数分,不经过浮点",
72    "text": "接口金额单位为分且必须是整数。从计价、优惠扣减、累加到落库与接口入参,全程使用整数或精确十进制类型;**在最后一步转为整数分不等于精度安全**——只要中间任一环节用过 `float`/`double`,误差已经产生。同时核对舍入方式、负值、零值与溢出边界。见 [4012068676-参数说明](https://iwiki.woa.com/p/4012068676)。"
73  },
74  {
75    "id": "do_not_treat_client_success_as_paid",
76    "category": [
77      "资金安全"
78    ],
79    "title": "前端返回成功不能当作支付成功",
80    "text": "用户在页面或 App 上看到的支付结果,只表示收银台流程结束,不能据此把订单改成已支付。是否支付成功,要由商户后端调用微信支付查单接口确认:`trade_state` 为 `SUCCESS`。**调用查单接口不等于确认**;须核对确实判断了 `trade_state`,且查单失败或超时时不得按成功处理。见 [4012075249-支付回调和查单实现指引](https://iwiki.woa.com/p/4012075249)。"
81  },
82  {
83    "id": "do_not_skip_server_certificate_checks",
84    "category": [
85      "资金安全"
86    ],
87    "title": "不得忽略服务端证书校验错误",
88    "text": "请求走 HTTPS,不得为图方便关闭或跳过服务端证书校验(如 trust-all)。见 [4012081709-基本规则](https://iwiki.woa.com/p/4012081709)。"
89  },
90  {
91    "id": "retry_with_original_order_and_params",
92    "category": [
93      "数据一致性"
94    ],
95    "title": "重试必须使用原单号且原参数",
96    "text": "微信支付接口支持幂等。超时或失败后重试,单据沿用第一次的单号和全部参数,不要换单号或改参数。要修改内容时,先结束原单,再换新单号。"
97  },
98  {
99    "id": "process_each_business_order_once",
100    "category": [
101      "数据一致性"
102    ],
103    "title": "同一笔业务只能处理一次",
104    "text": "1)**以业务完成状态为唯一幂等判据,判定与写入须原子完成**:重复可能来自回调重发、查单结果、重试应答等任意来源,不靠来源区分,一律以业务自身的完成状态(如订单已支付)判定;判定与写入须由条件更新或数据库唯一约束一次完成。**通知 ID 去重不等于业务幂等**(只防同一条通知重复到达);**仅「先查状态再更新」不能证明并发安全**;**独立去重标记不得替代业务状态作为判据**——标记写入不代表业务已完成,否则业务失败后重发被误判为已处理,该单永不收敛。2)**幂等命中仍须应答成功**:重复到达不再执行业务,但仍应答 200/204,**不得以抛异常表达「已处理过」**而被转成 5xx。未在 5 秒内应答微信会判失败并重发,故业务处理耗时须与应答窗口解耦(先应答再异步处理)。见 [4012075420-回调通知注意事项](https://iwiki.woa.com/p/4012075420)。"
105  },
106  {
107    "id": "prevent_duplicate_payment_orders",
108    "category": [
109      "数据一致性"
110    ],
111    "title": "防止重复下单(前端与服务端都要做)",
112    "text": "**前端**:付款按钮点击后立即置为不可点并提示处理中,本次下单有结果后再恢复。**服务端**:以业务订单为幂等粒度——同一业务订单(合并支付时为同一组业务订单)重复发起支付,须复用已有商户订单号及有效期内的 `prepay_id`,不得生成第二个商户订单号;原商户订单号确认已关闭或失效后才可换新。用户确实要再买一次时会产生新的业务订单,服务端无需猜测意图。**按请求或页面会话去重不等于按业务订单去重**;同一业务订单只要可能产生第二个商户订单号,即不通过。两者不可互相替代——只做防抖,网络延迟、多端操作或接口被直接调用时失效;只做服务端去重,用户连点时仍会感到卡顿、出现异常。见 [4012791870-JSAPI支付开发指引](https://iwiki.woa.com/p/4012791870)。"
113  },
114  {
115    "id": "set_timeouts_and_bounded_retries",
116    "category": [
117      "工程质量"
118    ],
119    "title": "对外调用必须设超时,重试必须有界",
120    "text": "每个微信支付调用都要设连接与读取超时,不得无限等待;**代码里有 try-catch 不等于有超时控制**,未显式配置的 HTTP 客户端多数默认无限等待。失败后区分结果不确定(超时、网络中断)与明确失败(参数、鉴权错误):前者走查单收敛,不直接判失败;后者不重试。**重试须有明确终止条件**:按查单收敛的重试,终止于结果明确或业务时效到期(如订单 `time_expire`、流程规则给定的时间窗);不得无条件无限重试,也不得仅以次数上限代替收敛。"
121  },
122  {
123    "id": "query_order_when_notification_missing",
124    "category": [
125      "工程质量"
126    ],
127    "title": "异步通知缺失时主动查单",
128    "text": "支付、退款、扣款、分账都要有后台主动查单,不能只等异步通知;实现方式不限(回调异常时查单、定时任务、延时队列等均可),但须由后台自己发出,**仅靠用户回到页面时前端触发不算**。**存在查单代码不等于覆盖**;扫描窗口须覆盖单据有效期,到期须有关单或终止动作,以内存队列作唯一事实来源的会永久漏单,须说明待处理单如何被完整发现。见 [4012075249-支付回调和查单实现指引](https://iwiki.woa.com/p/4012075249)。"
129  },
130  {
131    "id": "failover_and_failback_api_domains",
132    "category": [
133      "工程质量"
134    ],
135    "title": "配置主备域名,异常时自动切换并在恢复后回切",
136    "text": "主备域名双活,备域名保持少量流量。主域名异常时自动把主通道切到备域名,恢复后回切。**配置两个域名不等于具备容灾**;须有按故障判断实际切换的代码路径,由网关或基础设施实现的需提供配置证据,仅声明记「未验证」。见 [4012075113-跨城冗灾升级指引](https://iwiki.woa.com/p/4012075113)。"
137  },
138  {
139    "id": "use_field_names_from_current_api_doc",
140    "category": [
141      "接入规范"
142    ],
143    "title": "字段名与取值以该接口文档为准",
144    "text": "写请求、解析应答或回调前,先读当前接口文档里的字段名,按文档原文使用。不要凭其他接口、命名习惯或记忆去猜大小写和下划线。例如:服务端下单用 `appid`,JSAPI 调起支付用 `appId`。选填字段没有值时不要传 `null` 或 `\"\"`。见 [4012081709-基本规则](https://iwiki.woa.com/p/4012081709)。"
145  },
146  {
147    "id": "parse_responses_without_assuming_order",
148    "category": [
149      "接入规范"
150    ],
151    "title": "应答解析兼容性",
152    "text": "不假设 JSON 键值对的出现顺序;不强校验应答结构,新增字段不得导致解析失败或拒绝该笔应答。见 [4012081709-基本规则](https://iwiki.woa.com/p/4012081709)。"
153  },
154  {
155    "id": "branch_on_http_status_and_code",
156    "category": [
157      "接入规范"
158    ],
159    "title": "按 HTTP 状态码和 `code` 处理,禁止按 `message` 做逻辑判断",
160    "text": "`message` 是可变文案,同一 `code` 可对应多条 `message`,按它分支会在文案变更时失效。见 [4012081717-HTTP状态码](https://iwiki.woa.com/p/4012081717)。"
161  },
162  {
163    "id": "log_request_id_without_secrets",
164    "category": [
165      "工程质量"
166    ],
167    "title": "成功和失败都记录 Request-ID,且不记录敏感明文",
168    "text": "成功和失败都记录应答头 `Request-ID`,并关联商户订单号。见 [4012081709-基本规则](https://iwiki.woa.com/p/4012081709)。不得记录密钥和敏感明文。"
169  },
170  {
171    "id": "completion_success_not_payment_success",
172    "category": [
173      "数据一致性"
174    ],
175    "title": "支付分订单完结成功不等于扣款成功",
176    "text": "说明:完结接口调用成功只表示订单进入待支付状态,微信支付会轮询扣款;扣款失败时 collection.state 仍为 USER_PAYING,完结成功不等于已收款成功。正确应该怎么做:。① 服务完成后调用完结接口,传实际 post_payments 和 total_amount;② 保存订单号,等待支付成功回调,未收到回调时调用查询订单接口确认 collection.state;③ 待支付状态下不要重复调用完结接口;④ 用户通过其他渠道完成付款时调用同步订单状态接口;⑤ 商户不再需要通过支付分渠道收款时调用取消订单接口。典型反例:未收到扣款成功回调就反复调用完结接口;或把完结成功直接记为已收款,未继续查单和等待支付结果。**不做会怎么样**:重复完结会返回 INVALID_REQUEST 或「当前订单状态不合法」;账务已记为收款但实际仍为待支付,会造成商户短款、对账差异和用户客诉;部分场景还可能返回 USER_PAYING。见 [4012587200-微信支付分常见问题](https://iwiki.woa.com/p/4012587200)、[4012587166-微信支付分开发指引](https://iwiki.woa.com/p/4012587166)、[4012587955-完结支付分订单](https://iwiki.woa.com/p/4012587955)、[4012587902-查询支付分订单](https://iwiki.woa.com/p/4012587902)、[4012587962-同步支付分订单状态](https://iwiki.woa.com/p/4012587962)、[4012587905-取消支付分订单](https://iwiki.woa.com/p/4012587905)、[4013138598-完结支付分订单](https://iwiki.woa.com/p/4013138598)、[4012586136-支付成功回调通知](https://iwiki.woa.com/p/4012586136)、[4013138559-查询支付分订单](https://iwiki.woa.com/p/4013138559)、[4013138975-同步支付分订单状态](https://iwiki.woa.com/p/4013138975)、[4012586139-常见问题](https://iwiki.woa.com/p/4012586139)、[4012586134-微信支付分开发指引](https://iwiki.woa.com/p/4012586134)、[4012587960-支付成功回调通知](https://iwiki.woa.com/p/4012587960)。"
177  }
178]
反馈
目录
置顶