文件哈希幂等上传需用sha256基于完整文件流计算确定性标识，数据库contentsha256字段必须建唯一索引，后端返回409 conflict而非200，前端须显式处理该状态码复用已有fileid。
上传前生成并校验文件哈希令牌
核心思路不是靠时间戳或随机 GuiD，而是用文件内容本身生成确定性标识。只要文件字节完全一致，哈希值就一样，天然适配幂等场景。
常见错误是只取文件名或前端传来的 fileName 做判断——重名但内容不同、内容相同但改了后缀，都会误判。
- 推荐用
SHA256（不是MD5）计算整个文件流的哈希，SHA1已不安全，MD5易碰撞 - 前端需在上传前读取文件并计算哈希（用
FileReader+crypto.subtle.digest），连同文件流一起发给后端 - 后端收到后，先查数据库或缓存中是否存在该
sha256Hash对应的已存记录；存在则直接返回已有fileId，跳过存储 - 注意大文件：不要把整个文件 load 到内存再算哈希，要用流式计算（
SHA256.Create().ComputeHash(stream)支持）
数据库唯一约束必须落在哈希字段上
光靠代码逻辑判断不够，高并发下两个请求几乎同时完成哈希计算、同时查库没结果、又同时插入，就会重复落库。
真实出问题的点往往在这里：开发者加了业务层判断，却忘了加数据库约束。
- 在文件表中增加
contentSha256字段，类型设为char(64)（小写十六进制）或BINARY(32) - 对该字段建唯一索引：
CREATE UNIQUE INDEX IX_Files_ContentSha256 ON Files(contentSha256) - 插入时用
INSERT ... ON CONFLICT DO NOTHING（postgresql）或INSERT IGNORE（mysql）或 SQL Server 的MERGE，避免抛异常打断流程 - 如果用 EF Core，别依赖
SaveChangesAsync抛异常来捕获冲突——它不可靠，且掩盖了真正想表达的“已存在”语义
客户端需处理 409 Conflict 响应并复用已有 ID
后端识别到重复后，不该返回 200 + 新数据，而应明确返回 409 Conflict 和已有文件元信息。否则前端无法区分“这次上传成功了”和“其实只是命中缓存”。
典型翻车现场：前端看到 200 就欢天喜地更新 UI，结果列表里出现两个一模一样的文件条目。
- 后端返回示例响应体：
{"fileId": "f_abc123", "exists": true, "uploadedAt": "2024-05-20T10:30:00Z"} - 前端收到
409后，提取fileId直接用于后续操作（如关联业务单据），不再走上传流程 - 不要让前端自己做“去重”：比如上传前先 GET 一遍 /files/check?hash=xxx —— 这会多一次 RTT，且无法解决检查后、上传前的竞态窗口
- 若使用
fetch，记得显式检查response.status === 409，别只依赖ok字段（409 的ok是 false）
缓存层不能替代数据库唯一约束
有人想用 redis 缓存哈希 → 文件 ID 映射来提速，这没错，但千万别以为加了 Redis 就能删掉数据库唯一索引。
缓存永远有失效、穿透、集群同步延迟等问题。生产环境出过太多次“缓存没刷全，两个节点各自写入”的事故。
- Redis 可作为快速前置校验（
EXISTS+GET），降低数据库压力，但必须保留最终兜底的 DB 约束 - 缓存 key 建议用
file:sha256:{hash}，设置合理过期时间（比如 7 天），避免无限膨胀 - 写入成功后，异步刷新缓存（非阻塞），失败也不影响主流程；但不要在事务里同步写缓存，拖慢主链路
- 特别注意：如果文件支持分片上传，哈希必须基于完整文件计算，不能只算某一片 —— 否则同一文件不同分片策略会产生不同哈希
事情说清了就结束。最常被绕开的是数据库唯一索引，其次是前端没正确处理 409 响应码。这两处一漏，幂等就只剩心理安慰。