tus-js-client 中实现上传完成回调的最佳实践

在基于浏览器的文件上传场景中，tus-js-client 作为实现 TUS 断点续传协议的核心库，其异步上传特性常常需要开发者处理上传完成后的回调逻辑。本文将深入探讨如何优雅地封装上传过程，实现上传完成后的响应处理。

核心问题分析

原生 tus.Upload 实例采用事件驱动模式，通过 onSuccess 和 onError 回调处理上传结果。这种模式在现代前端开发中（特别是 React/Vue 等框架）往往需要转换为更符合开发者习惯的 Promise 模式，以便于在 async/await 语法中使用。

解决方案实现

通过 Promise 封装是最符合工程实践的解决方案：

const tusUpload = (file: File) => {
  return new Promise((resolve, reject) => {
    const upload = new tus.Upload(file, {
      endpoint: 'YOUR_TUS_ENDPOINT',
      retryDelays: null,
      onError: (error) => {
        reject(error);
      },
      onSuccess: () => {
        try {
          const response = JSON.parse(upload.lastResponse.getBody());
          resolve(response);
        } catch (e) {
          reject(new Error('Failed to parse response'));
        }
      }
    });

    upload.start();
  });
};

关键实现要点

1. 错误处理强化：除了网络错误，还应该处理响应解析错误
2. 响应解析：TUS 协议响应通常是 JSON 格式，需要显式解析
3. 类型安全：在 TypeScript 中建议定义明确的返回类型
4. 取消支持：可扩展实现上传取消功能

实际应用示例

在 React 组件中的典型用法：

const handleUpload = async (file) => {
  try {
    setUploadStatus('uploading');
    const result = await tusUpload(file);
    await createProject({ video_id: result.id });
    setUploadStatus('success');
  } catch (error) {
    setUploadStatus('error');
    showErrorToast(error.message);
  }
};

进阶优化建议

1. 进度监控：可结合 onProgress 回调实现上传进度显示
2. 并发控制：对于批量上传场景需要实现队列管理
3. 重试策略：根据业务需求定制 retryDelays 参数
4. 内存管理：大文件上传时注意内存释放

总结

通过 Promise 封装 tus-js-client 的上传过程，不仅使代码更符合现代前端开发范式，还能更好地与状态管理、错误处理等系统集成。这种模式特别适合需要在上传完成后执行后续业务逻辑的场景，如创建关联记录、更新UI状态等。开发者可以根据实际需求扩展基础实现，构建更健壮的上传解决方案。