跳到主要内容

[草稿] 文件上传完整链路示例

文件上传是最容易在前后端协作中出错的场景之一，因为 Nebula Storage 不是一次请求就结束，而是一个明确的两阶段流程。这个示例的目标，就是帮你把页面动作、后端接口和业务保存时机连成一条线。

场景描述​

假设你正在做一个业务表单，用户需要上传附件，只有在业务数据保存成功后，这个附件才算正式归档。

推荐链路​

第一步：前端选择文件​

页面层优先使用 NeFileUploader，把拖拽上传、文件列表和交互提示统一起来。

第二步：创建上传任务并上传临时文件​

前端上传逻辑按 nebula-storage 的真实流程执行：

  1. 创建上传任务
  2. 上传普通文件
  3. 完成上传任务

到这一步，文件只是进入临时存储，还不是业务正式文件。

第三步：业务数据保存成功​

只有当你的业务主数据真正保存成功，拿到了明确的业务实体标识之后，才适合继续下一步。

第四步：绑定上传任务​

前端把 sourceEntity、sourceId，以及可选的 sourceType 传给绑定接口。绑定成功后，后端才会生成正式文件记录。

这里要区分两种情况：

  • 如果这是“先保存业务数据，再上传或绑定附件”的场景，那么 sourceId 已经存在，可以在同一条前端辅助流程里直接完成绑定。
  • 如果这是“先选文件，再创建业务数据”的场景，那么更稳妥的做法仍然是先完成临时上传，等业务主数据真正保存成功后再绑定。

第五步：读取正式文件详情并展示​

保存成功后，前端再读取正式文件详情，用于页面回显、预览或下载。

为什么不要提前绑定​

如果你在业务数据还没落库时就先绑定，最常见的问题是正式文件没有明确业务归属，后续查询、删除、权限控制都会变得混乱。

这个示例最适合谁看​

  • 正在做附件上传表单的前端开发者
  • 负责设计附件模型的后端开发者
  • 需要联调上传和业务保存顺序的实施或测试同学