分布式文件上传失败需按业务语义分类处理：客户端问题前置拦截，网络故障自动重试，服务端资源问题降级告警，一致性风险依赖状态机与事务日志驱动补偿；通过幂等设计、全链路追踪和双通道兜底保障可靠性。
分布式文件存储上传失败时，Java异常处理不能只靠try-catch吞掉错误，必须结合业务语义设计可回退、可重试、可追踪的补偿机制。核心是把“上传失败”视为一个可观察、可干预、可修复的业务事件，而非单纯的技术异常。
识别上传失败的真实原因并分类响应
上传失败不是单一异常，需根据错误码或异常类型区分处理路径：
-
客户端侧问题（如
ERROR_CODE_1001文件超限、ERROR_CODE_1002类型不支持）：属于前置校验缺失，应在上传前拦截，不进入分布式流程；若已触发，直接返回用户友好提示，无需补偿 -
网络或临时性故障（如
ERROR_CODE_1003网络中断、HTTP 504/503）：适合自动重试+指数退避，配合唯一请求ID防重放 -
服务端资源问题（如
ERROR_CODE_1004存储空间不足、目标集群不可用）：需触发告警并降级到备用存储节点，同时记录失败元数据供人工介入 - 一致性风险场景（如文件已写入存储但元数据未入库、或反之）：这是补偿的重点——必须通过事务日志或状态表标记“中间态”，驱动后续修复
用状态机+事务日志驱动补偿动作
避免在上传方法里硬编码补偿逻辑。推荐引入轻量状态机与持久化任务表：
- 上传开始时，向数据库插入一条
upload_task记录，状态为PENDING，包含文件ID、目标存储路径、原始请求参数、超时时间 - 上传成功则更新状态为
COMPLETED；失败则设为FAILED，并记录错误码和堆栈 - 部署独立的补偿调度器（如Quartz或XXL-JOB），定时扫描
status = 'FAILED'且retry_count < 3的任务，按策略重试或调用清理接口（如删除已上传但未注册的碎片文件） - 对关键操作（如“文件存了但DB没写”），补偿任务应先查目标存储是否存在该文件，再决定是补元数据还是删残留
异步上传 + 消息队列兜底双链路
对于高可靠要求场景（如合同、凭证类文件），采用主备双通道设计：
立即学习“Java免费学习笔记（深入）”；
- 主线：走MQ（如RocketMQ）异步触发上传，消息带
traceId和fileHash，消费者执行上传并更新任务状态 - 备线：同步写入本地任务表后，立即启动一个延迟消息（如30s后投递），若主线未在时限内将任务置为
COMPLETED，备线消费者自动接管并重试 - 两条链路共享同一份
upload_task记录，靠数据库乐观锁（version字段）保证并发安全，避免重复上传
确保所有补偿操作幂等且可观测
补偿本身可能失败或重复触发，必须从设计上杜绝雪球效应：
- 每个补偿动作（重试上传、清理碎片、补写元数据）都基于文件唯一标识（如MD5+业务ID）做幂等判断，例如先
SELECT COUNT(*) FROM file_meta WHERE file_hash = ?再决定是否INSERT - 所有上传和补偿操作统一打点：记录
file_id、storage_type、status、cost_ms、error_code，接入ELK或Prometheus，设置失败率突增告警 - 提供运营后台页面，支持按文件ID查询全链路轨迹（MQ发送→消费→DB更新→补偿触发→最终状态），缩短故障定位时间
