Data Pipeline 文件上传API设计文档

概述

本文档描述了Data Pipeline文件上传功能的详细设计，包括API接口设计、文件管理机制、安全控制和使用示例。

功能特性

1. 支持的文件类型

.ddl - DDL文件
.md - Markdown文档
.txt - 文本文件
.json - JSON文件
.sql - SQL文件
.csv - CSV文件

2. 文件大小限制

最大文件大小：10MB
空文件检查：不允许上传空文件

3. 重名处理模式

backup（默认）：备份原文件，命名规则为 原文件名_bak1, 原文件名_bak2 等
replace：直接覆盖原文件
skip：跳过上传，保留原文件

4. 安全控制

文件名安全检查：防止路径遍历攻击
文件类型验证：仅允许指定的文件扩展名
目录权限控制：文件只能上传到指定任务目录内

API接口设计

POST /api/v0/data_pipeline/tasks/{task_id}/files

上传文件到指定任务目录。

请求参数

路径参数：

task_id (string, required): 任务ID

表单参数（multipart/form-data）：

file (file, required): 要上传的文件
overwrite_mode (string, optional): 重名处理模式，可选值：backup（默认）、replace、skip

响应格式

成功响应（200）：

{
    "success": true,
    "code": 200,
    "message": "文件上传成功",
    "data": {
        "task_id": "task_20250701_123456",
        "uploaded_file": {
            "filename": "test.ddl",
            "size": 1024,
            "size_formatted": "1.0 KB",
            "uploaded_at": "2025-07-01T12:34:56",
            "overwrite_mode": "backup"
        },
        "backup_info": {  // 仅当overwrite_mode为backup且文件已存在时返回
            "had_existing_file": true,
            "backup_filename": "test.ddl_bak1",
            "backup_version": 1,
            "backup_created_at": "2025-07-01T12:34:56"
        }
    }
}

跳过上传响应（200）：

{
    "success": true,
    "code": 200,
    "message": "文件已存在，跳过上传",
    "data": {
        "task_id": "task_20250701_123456",
        "skipped": true,
        "uploaded_file": {
            "filename": "test.ddl",
            "existed": true,
            "action": "skipped"
        }
    }
}

错误响应：

400 Bad Request: 参数错误、文件验证失败
404 Not Found: 任务不存在
500 Internal Server Error: 服务器内部错误

错误示例

文件类型不支持（400）：

{
    "success": false,
    "code": 400,
    "message": "不支持的文件类型: .exe，允许的类型: .ddl, .md, .txt, .json, .sql, .csv"
}

文件大小超限（400）：

{
    "success": false,
    "code": 400,
    "message": "文件大小超出限制: 11.0 MB，最大允许: 10.0 MB"
}

任务不存在（404）：

{
    "success": false,
    "code": 404,
    "message": "任务不存在: task_invalid_id"
}

技术实现

1. 文件管理器架构

class SimpleFileManager:
    # 支持的文件类型
    ALLOWED_EXTENSIONS = {'.ddl', '.md', '.txt', '.json', '.sql', '.csv'}
    MAX_FILE_SIZE = 10 * 1024 * 1024  # 10MB
    
    def upload_file_to_task(self, task_id, file_stream, filename, overwrite_mode="backup"):
        """上传文件到任务目录"""
        
    def validate_file_upload(self, filename, file_stream):
        """验证文件合法性"""
        
    def create_backup_file(self, original_path):
        """创建备份文件"""
        
    def find_next_backup_version(self, file_path):
        """查找下一个可用的备份版本号"""

2. 备份文件命名规则

当选择backup模式且目标文件已存在时，系统会自动创建备份文件：

原文件：test.ddl
第1次备份：test.ddl_bak1
第2次备份：test.ddl_bak2
以此类推...

3. 文件安全验证

文件名安全检查

禁止路径遍历字符：..
禁止Windows危险字符：<>:"|?*
禁止控制字符：\x00-\x1f
禁止Windows保留文件名：CON, PRN, AUX, NUL, COM1-9, LPT1-9
文件名长度限制：255字符

文件类型验证

基于文件扩展名进行验证
仅允许预定义的安全文件类型
大小写不敏感

文件大小验证

最大10MB限制
禁止空文件上传
流式读取避免内存溢出

4. 目录结构

data_pipeline/
└── training_data/
    └── {task_id}/
        ├── test.ddl
        ├── test.ddl_bak1
        ├── test.md
        ├── config.json
        └── ...

使用示例

1. 基本文件上传

curl -X POST \
  http://localhost:8084/api/v0/data_pipeline/tasks/task_20250701_123456/files \
  -F "file=@test.ddl" \
  -F "overwrite_mode=backup"

2. Python客户端示例

import requests

def upload_file(task_id, file_path, overwrite_mode="backup"):
    url = f"http://localhost:8084/api/v0/data_pipeline/tasks/{task_id}/files"
    
    with open(file_path, 'rb') as f:
        files = {'file': (file_path.name, f)}
        data = {'overwrite_mode': overwrite_mode}
        
        response = requests.post(url, files=files, data=data)
        
    return response.json()

# 使用示例
result = upload_file("task_20250701_123456", "test.ddl", "backup")
print(result)

3. JavaScript客户端示例

async function uploadFile(taskId, file, overwriteMode = 'backup') {
    const formData = new FormData();
    formData.append('file', file);
    formData.append('overwrite_mode', overwriteMode);
    
    const response = await fetch(
        `/api/v0/data_pipeline/tasks/${taskId}/files`,
        {
            method: 'POST',
            body: formData
        }
    );
    
    return await response.json();
}

// 使用示例
const fileInput = document.getElementById('fileInput');
const file = fileInput.files[0];
const result = await uploadFile('task_20250701_123456', file, 'backup');
console.log(result);

配置说明

1. 文件类型配置

可以通过修改 SimpleFileManager.ALLOWED_EXTENSIONS 来调整支持的文件类型：

ALLOWED_EXTENSIONS = {'.ddl', '.md', '.txt', '.json', '.sql', '.csv', '.py'}

2. 文件大小限制配置

可以通过修改 SimpleFileManager.MAX_FILE_SIZE 来调整文件大小限制：

MAX_FILE_SIZE = 20 * 1024 * 1024  # 20MB

错误处理

1. 常见错误类型

错误类型	HTTP状态码	说明
参数缺失	400	缺少必需的file参数
文件类型不支持	400	文件扩展名不在允许列表中
文件大小超限	400	文件大小超过10MB限制
文件为空	400	上传的文件内容为空
文件名不安全	400	文件名包含危险字符
任务不存在	404	指定的task_id不存在
服务器错误	500	文件保存失败等内部错误

2. 错误处理最佳实践

客户端应检查响应状态码
根据错误类型给用户提供友好的错误提示
对于5xx错误，建议实现重试机制
记录详细的错误日志用于调试

性能考虑

1. 文件上传性能

使用流式处理避免大文件占用过多内存
支持并发上传（不同任务间）
文件大小限制防止滥用

2. 存储空间管理

定期清理过期的备份文件
监控磁盘空间使用情况
考虑实现文件压缩存储

安全考虑

1. 文件安全

严格的文件类型白名单
文件名安全验证
防止路径遍历攻击

2. 访问控制

任务级别的文件隔离
文件只能上传到对应任务目录
未来可扩展用户权限控制

3. 资源限制

文件大小限制
上传频率限制（可扩展）
存储空间配额（可扩展）

测试验证

1. 功能测试

正常文件上传测试
重名处理模式测试
文件类型验证测试
文件大小限制测试

2. 安全测试

恶意文件名测试
路径遍历攻击测试
大文件攻击测试

3. 性能测试

并发上传测试
大文件上传测试
存储空间压力测试

未来扩展

1. 功能扩展

支持更多文件类型
批量文件上传
文件版本管理
文件内容预览

2. 安全扩展

用户权限控制
文件访问日志
病毒扫描集成

3. 性能扩展

分布式文件存储
CDN集成
文件压缩和去重

总结

Data Pipeline文件上传API提供了一个安全、可靠的文件管理解决方案，支持多种文件类型和灵活的重名处理策略。通过严格的安全控制和完善的错误处理，确保了系统的稳定性和安全性。

该API设计遵循RESTful原则，提供了清晰的接口定义和详细的文档说明，便于开发者集成和使用。

data_pipeline_file_upload_api_design.md 8.7 KB History Raw