秒传功能核心是验指纹而非传文件：前端发送文件哈希（如SparkMD5计算的fileMd5），后端通过verify接口查库判断是否存在，存在则返回fileId等信息跳过上传；不存在才调用upload/chunk接口分片上传。
秒传功能的后端接口对接，核心不是“传文件”，而是“验指纹”。前端把文件哈希（如 MD5 或 SparkMD5 计算出的摘要）发给后端，后端查库——存在就返回成功标识，不存在才走分片上传流程。整个过程对前端来说就是一次轻量 HTTP 请求，不走文件体传输，所以快。
后端需提供两个关键接口
前端交互依赖两个明确职责的接口，不能混在一起：
- 文件存在性校验接口（verify）：接收文件唯一标识（如 fileMd5），返回 { exists: true, fileId: "xxx" } 或 { exists: false }。这是秒传判定的唯一依据，必须幂等、低延迟、支持高并发查询。
- 分片上传接口（upload/chunk）：仅当 verify 返回 false 时调用。接收分片序号（chunkIndex）、总片数（totalChunks）、当前分片数据（Blob 或 base64）、以及 fileMd5（用于关联归属）。后端按 md5 + chunkIndex 存储临时分片，最后合并。
fileMd5 是前后端协同的唯一纽带
这个值必须前后端完全一致，否则秒传和分片都会失效。注意三点：
- 前端必须用 SparkMD5（非原生 crypto.subtle.digest）计算完整文件哈希，因为它支持流式分块计算，避免大文件读入内存卡死；Vue 3 中推荐在 Web Worker 里执行，防阻塞 UI。
- 后端计算逻辑要严格对齐：比如是否对空文件、特殊字符、换行符做统一预处理；Node.js 常用
spark-md5或md5-file库，Java 用org.apache.commons.codec.digest.DigestUtils.md5Hex，务必保证字节级一致。 - fileMd5 要作为所有后续请求（verify、分片上传、合并、删除）的主键字段传入，数据库建表时设为唯一索引，便于快速检索与去重。
verify 接口的响应要带业务上下文
不能只返回布尔值。建议结构化响应，方便前端直接决策：
接口对接到交付·数据管线
下载
用户要对接第三方接口、整理 ERP 字段、管理多环境配置或导出结构化报表时使用。本技能是「API/数据接入管线闭环」的总控，编排：接口文档解析(字段提取) → 字段对齐(归一规范 key) → 配置合并(三层优先级+冲突自修) → 单位换算(规格归一) → 表格导出(Excel/CSV 带样式)。触发词：对接接口、解析 API 文档、字段对不上、多环境配置、导出 Excel、ERP 字段整理、规格换算。
立即学习“前端免费学习笔记（深入）”；
- 若
exists: true，应附带fileId（数据库主键或业务 ID）、fileName、fileSize、url（可直接访问的 CDN 地址），前端可立即更新 UI 并跳过上传流程。 - 若
exists: false，可返回uploadUrl（分片上传地址）、chunkSize（建议分片大小，如 5MB）、maxConcurrency（最大并发数），让前端动态适配后端策略。 - 状态码建议：200 OK（校验完成），不要用 404 表示不存在——那是资源未找到语义，而这里是业务逻辑判断。
后端存储设计要支撑秒传本质
秒传不是魔法，它依赖一个“已上传文件指纹库”。这个库至少包含三列：
- file_md5（主键/唯一索引）
- file_id（对应真实文件存储路径或对象存储 key）
- created_at（用于冷热分离或自动清理）
当 verify 查询命中时，后端不再操作文件系统，只是新建一条业务记录（如用户-文件关系表），把 fileId 关联过去。真正的文件本体只存一份，多个用户秒传同一安装包，磁盘占用不会叠加。
