PaymentFailedException 的字段设计应聚焦业务语义与决策支持：必须包含 paymentId、orderNo、channelCode 等业务标识；failureCode 和 failureCategory 实现结构化错误分类；isRetryable、suggestedAction、retryAfterMs 支持重试与降级；rawResponse 用于排查但不参与逻辑；避免日志ID、敏感信息等冗余字段。
在 Java 中定义 PaymentFailedException 时，业务字段不是为了“记录错误”，而是为了**让调用方能准确识别失败原因、区分处理逻辑、支持下游重试或降级决策**。关键在于字段设计要贴近支付域的真实上下文，而非堆砌技术细节。
包含核心支付业务标识字段
必须携带能唯一关联本次支付动作的业务主键，便于对账、排查和补偿：
-
paymentId：商户侧生成的支付单号（如
pay_20241125_88923</strong>），非第三方流水号</li> <li><strong>orderNo</strong>：对应业务订单号（如 <code>ORD-7721094
），用于快速定位用户与商品上下文 -
channelCode：支付渠道编码（如
alipay_app、wechat_jsapi），方便按渠道聚合分析失败率
封装可结构化解析的失败原因
避免只存模糊消息（如 "支付失败，请稍后重试"），应提供标准化、可枚举的失败分类：
Alibabacloud Sdk Client Initialization For Java
下载
在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。
-
failureCode：字符串或枚举类型（如
PAY_AMOUNT_INVALID、CHANNEL_UNAVAILABLE、USER_CANCELLED），用于 switch-case 分支处理 -
failureCategory：更高层归类（如
VALIDATION_ERROR、NETWORK_TIMEOUT、USER_ACTION_REQUIRED），支撑监控告警策略 - rawResponse：保留原始渠道返回的响应体（JSON 字符串或 Map），供人工排查或合规审计，不参与程序逻辑判断
支持幂等与重试决策的上下文字段
为下游是否重试、如何重试提供依据：
立即学习“Java免费学习笔记（深入）”；
- isRetryable：布尔值，明确标识该失败是否适合自动重试（例如网络超时可重试，余额不足则不可）
-
suggestedAction：建议操作（如
RETRY_WITH_NEW_NONCE、REDIRECT_TO_USER_CONFIRM、MANUAL_CHECK_REQUIRED），驱动前端交互或调度策略 - retryAfterMs：推荐重试间隔毫秒数（如 1000 表示 1 秒后），避免雪崩式重试
保持异常轻量，避免冗余信息
不放入日志 ID、trace ID、时间戳等由统一日志框架/链路追踪系统自动注入的内容；也不放用户敏感信息（如完整卡号、身份证号）。这些应由外围日志组件统一附加，而非污染异常结构。
