文件 API

文件 API 提供文件上传、下载、管理等功能。

上传文件

接口地址

POST /api/files/upload

请求头

Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data

请求参数

参数	类型	必填	说明
file	File	是	文件（支持 PDF、Word、Markdown）
category	string	否	文件分类（默认：uncategorized）

请求示例（FormData）

const formData = new FormData()
formData.append('file', fileInput.files[0])
formData.append('category', 'reference')

const response = await fetch('/api/files/upload', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`
  },
  body: formData
})

响应示例

{
  "code": 200,
  "msg": "上传成功",
  "data": {
    "file_id": "file_abc123",
    "original_name": "reference.pdf",
    "save_name": "uploads/20260209/file_abc123.pdf",
    "file_size": 1024000,
    "file_ext": "pdf",
    "url": "https://xdai.fun/storage/uploads/20260209/file_abc123.pdf",
    "uploaded_at": "2026-02-09T10:30:00Z"
  }
}

获取文件列表

接口地址

GET /api/files

查询参数

参数	类型	必填	说明
page	number	否	页码（默认：1）
page_size	number	否	每页数量（默认：20）
category	string	否	文件分类
file_type	string	否	文件类型：pdf、docx、md、txt

响应示例

{
  "code": 200,
  "msg": "获取成功",
  "data": {
    "total": 50,
    "page": 1,
    "page_size": 20,
    "files": [
      {
        "file_id": "file_abc123",
        "original_name": "reference.pdf",
        "save_name": "uploads/20260209/file_abc123.pdf",
        "file_size": 1024000,
        "file_ext": "pdf",
        "url": "https://xdai.fun/storage/uploads/20260209/file_abc123.pdf",
        "category": "reference",
        "uploaded_at": "2026-02-09T10:30:00Z"
      }
    ]
  }
}

获取文件详情

接口地址

GET /api/files/:file_id

响应示例

{
  "code": 200,
  "msg": "获取成功",
  "data": {
    "file_id": "file_abc123",
    "original_name": "reference.pdf",
    "save_name": "uploads/20260209/file_abc123.pdf",
    "file_size": 1024000,
    "file_ext": "pdf",
    "url": "https://xdai.fun/storage/uploads/20260209/file_abc123.pdf",
    "category": "reference",
    "extracted_content": "文件提取的文本内容...",
    "uploaded_at": "2026-02-09T10:30:00Z"
  }
}

删除文件

接口地址

DELETE /api/files/:file_id

响应示例

{
  "code": 200,
  "msg": "删除成功",
  "data": null
}

批量删除

接口地址

POST /api/files/batch-delete

请求参数

参数	类型	必填	说明
file_ids	array	是	文件 ID 数组

请求示例

{
  "file_ids": ["file_abc123", "file_def456", "file_ghi789"]
}

响应示例

{
  "code": 200,
  "msg": "删除成功",
  "data": {
    "deleted_count": 3,
    "failed_count": 0
  }
}

错误码

错误码	说明
4001	文件格式不支持
4002	文件大小超限（最大 50MB）
4003	文件不存在
4004	文件已被删除
4005	存储空间不足

最佳实践

文件上传优化

提高上传成功率：

1. 分片上传: 大文件分片上传
2. 断点续传: 支持断点续传
3. 进度显示: 显示上传进度
4. 错误重试: 失败后自动重试

文件管理

合理管理文件：

1. 分类存储: 按类型分类存储
2. 定期清理: 删除无用文件
3. 命名规范: 使用清晰的文件名
4. 版本管理: 保留文件版本

安全建议

保护文件安全：

1. 权限控制: 设置文件访问权限
2. 加密存储: 敏感文件加密存储
3. 访问日志: 记录文件访问日志
4. 定期备份: 定期备份重要文件