Cherry Markdown 多文件上传接口设计与实现

多文件上传机制解析

Cherry Markdown 编辑器在处理多文件上传时，采用的是逐个文件上传的机制。当用户在文件选择框中选择了多个文件后，编辑器会遍历文件数组，对每个文件单独发起上传请求。这种设计虽然看似效率不高，但具有更好的兼容性和错误处理能力。

上传接口返回格式规范

对于多文件上传接口，Cherry Markdown 要求返回一个包含上传结果的数组。每个文件的上传结果应包含以下信息：

1. 必填字段：

   • url: 文件上传成功后的访问地址

2. 可选字段：

   • params: 包含文件元数据的对象
     • name: 文件名
     • isHidden: 是否为隐藏文件
     • width: 图片宽度
     • height: 图片高度
     • 其他自定义元数据

实际应用示例

以下是一个完整的多文件上传实现示例，包含了成功和失败的处理逻辑：

function handleMultiFileUpload(files, callback) {
  const uploadResults = [];
  
  // 遍历所有文件进行上传
  for (const file of files) {
    try {
      // 执行实际上传操作
      const result = await uploadSingleFile(file);
      
      // 构建成功响应
      uploadResults.push({
        url: result.path,
        params: {
          name: file.name,
          type: file.type,
          size: file.size
        }
      });
    } catch (error) {
      // 处理上传失败情况
      uploadResults.push({
        error: true,
        message: `文件 ${file.name} 上传失败`,
        details: error.message
      });
    }
  }
  
  // 回调返回所有结果
  callback(uploadResults);
}

最佳实践建议

1. 批量上传优化： 虽然 Cherry Markdown 采用逐个上传机制，但开发者可以实现自己的批量上传逻辑，通过单个请求上传多个文件，然后按照要求格式返回结果。

2. 错误处理：

   • 为每个文件提供独立的状态标识
   • 保留原始文件名等信息便于问题追踪
   • 提供详细的错误信息

3. 性能考虑：

   • 对大文件进行分片上传
   • 实现上传进度显示
   • 考虑并发上传限制

4. 安全建议：

   • 验证文件类型和大小
   • 对上传文件进行安全检查
   • 实现访问权限控制

后端接口设计

后端接口应返回结构化的响应数据，示例如下：

{
  "status": "success",
  "data": {
    "successful": [
      {
        "originalName": "document.pdf",
        "storedName": "a1b2c3d4.pdf",
        "size": 102400,
        "url": "/uploads/a1b2c3d4.pdf"
      }
    ],
    "failed": [
      {
        "originalName": "virus.exe",
        "error": "File type not allowed",
        "code": "FILE_TYPE_ERROR"
      }
    ]
  }
}

通过遵循这些规范和最佳实践，开发者可以构建出稳定可靠的 Cherry Markdown 文件上传功能，为用户提供流畅的文档编辑体验。