paymentfailedexception 的字段设计应聚焦业务语义与决策支持：必须包含 paymentid、orderno、channelcode 等业务标识；failurecode 和 failurecategory 实现结构化错误分类；isretryable、suggestedaction、retryafterms 支持重试与降级；rawresponse 用于排查但不参与逻辑；避免日志id、敏感信息等冗余字段。
在 Java 中定义 PaymentFailedException 时，业务字段不是为了“记录错误”，而是为了**让调用方能准确识别失败原因、区分处理逻辑、支持下游重试或降级决策**。关键在于字段设计要贴近支付域的真实上下文，而非堆砌技术细节。
包含核心支付业务标识字段
必须携带能唯一关联本次支付动作的业务主键，便于对账、排查和补偿：
-
paymentId：商户侧生成的支付单号（如
pay_20241125_88923），非第三方流水号
-
orderNo：对应业务订单号（如
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），供人工排查或合规审计，不参与程序逻辑判断
支持幂等与重试决策的上下文字段
为下游是否重试、如何重试提供依据：
- isRetryable：布尔值，明确标识该失败是否适合自动重试（例如网络超时可重试，余额不足则不可）
-
suggestedAction：建议操作（如
RETRY_WITH_NEW_NONCE、REDIRECT_TO_USER_CONFIRM、MANUAL_CHECK_REQUIRED），驱动前端交互或调度策略 - retryAfterMs：推荐重试间隔毫秒数（如 1000 表示 1 秒后），避免雪崩式重试
保持异常轻量，避免冗余信息
不放入日志 ID、trace ID、时间戳等由统一日志框架/链路追踪系统自动注入的内容；也不放用户敏感信息（如完整卡号、身份证号）。这些应由外围日志组件统一附加，而非污染异常结构。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
