7.1 KiB
7.1 KiB
文件管理 API 文档
概述
文件管理模块提供对 yz_files 表的完整 CRUD 操作，支持文件信息的管理、搜索和统计功能。
数据库表结构
CREATE TABLE yz_files (
id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '文件ID',
tenant_id VARCHAR(64) NOT NULL COMMENT '租户ID',
-- 文件基础信息
file_name VARCHAR(255) NOT NULL COMMENT '文件名称',
original_name VARCHAR(255) NOT NULL COMMENT '原始文件名',
file_path VARCHAR(500) NOT NULL COMMENT '文件存储路径',
file_url VARCHAR(500) COMMENT '文件访问URL',
file_size BIGINT NOT NULL DEFAULT 0 COMMENT '文件大小(字节)',
file_type VARCHAR(50) NOT NULL COMMENT '文件类型',
file_ext VARCHAR(20) NOT NULL COMMENT '文件扩展名',
-- 分类信息
category VARCHAR(100) NOT NULL COMMENT '文件分类',
sub_category VARCHAR(100) COMMENT '子分类',
-- 状态信息
status TINYINT DEFAULT 1 COMMENT '状态(1:正常, 0:删除)',
is_public TINYINT DEFAULT 0 COMMENT '是否公开(1:是, 0:否)',
-- 上传信息
upload_by VARCHAR(100) NOT NULL COMMENT '上传人',
upload_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '上传时间',
-- 索引
INDEX idx_tenant (tenant_id),
INDEX idx_category (category),
INDEX idx_upload_time (upload_time),
INDEX idx_status (status)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='文件表';
API 接口列表
1. 获取所有文件信息
GET /api/files
认证方式: JWT认证
参数: 无
响应:
{
"success": true,
"message": "获取成功",
"data": [
{
"id": 1,
"tenant_id": "default",
"user_id": 1,
"file_name": "example.pdf",
"original_name": "example.pdf",
"file_path": "/uploads/2024/01/01/example.pdf",
"file_url": "http://example.com/uploads/2024/01/01/example.pdf",
"file_size": 1024,
"file_type": "application/pdf",
"file_ext": "pdf",
"category": "文档",
"sub_category": "PDF",
"status": 1,
"is_public": 0,
"upload_by": "admin",
"upload_time": "2024-01-01T10:00:00Z"
}
]
}
2. 获取当前用户的文件列表
GET /api/files/my
认证方式: JWT认证
参数: 无
说明: 通过JWT token自动获取当前登录用户的文件列表
响应:
{
"success": true,
"message": "获取成功",
"data": [
{
"id": 1,
"tenant_id": "default",
"user_id": 1,
"file_name": "example.pdf",
"original_name": "example.pdf",
"file_path": "/uploads/2024/01/01/example.pdf",
"file_url": "http://example.com/uploads/2024/01/01/example.pdf",
"file_size": 1024,
"file_type": "application/pdf",
"file_ext": "pdf",
"category": "文档",
"sub_category": "PDF",
"status": 1,
"is_public": 0,
"upload_by": "admin",
"upload_time": "2024-01-01T10:00:00Z"
}
]
}
2. 根据ID获取文件信息
GET /api/files/:id
参数:
id(路径参数): 文件ID
响应: 同获取所有文件接口
3. 创建文件信息
POST /api/files
请求体:
{
"tenant_id": "tenant-001",
"file_name": "new-file.txt",
"original_name": "原始文件.txt",
"file_path": "/uploads/tenant-001/new-file.txt",
"file_url": "http://localhost:8080/uploads/tenant-001/new-file.txt",
"file_size": 1024,
"file_type": "text/plain",
"file_ext": "txt",
"category": "文本",
"sub_category": "TXT",
"status": 1,
"is_public": 0,
"upload_by": "admin"
}
响应:
{
"success": true,
"message": "创建文件成功",
"data": {
"id": 2,
... // 创建的文件信息
}
}
4. 更新文件信息
PUT /api/files/:id
参数:
id(路径参数): 文件ID
请求体: 同创建文件接口
响应: 同创建文件接口
5. 删除文件（软删除）
DELETE /api/files/:id
参数:
id(路径参数): 文件ID
响应:
{
"success": true,
"message": "删除文件成功"
}
6. 硬删除文件
DELETE /api/files/:id/hard
参数:
id(路径参数): 文件ID
响应: 同软删除接口
7. 根据租户ID获取文件
GET /api/files/tenant?tenant_id=tenant-001
参数:
tenant_id(查询参数): 租户ID
响应: 同获取所有文件接口
8. 根据分类获取文件
GET /api/files/category?category=文档
参数:
category(查询参数): 文件分类
响应: 同获取所有文件接口
9. 根据状态获取文件
GET /api/files/status?status=1
参数:
status(查询参数): 文件状态 (1:正常, 0:删除)
响应: 同获取所有文件接口
10. 获取文件统计信息
GET /api/files/statistics?tenant_id=tenant-001
参数:
tenant_id(查询参数): 租户ID
响应:
{
"success": true,
"message": "获取统计信息成功",
"data": {
"total_count": 10,
"total_size": 10485760,
"category_stats": [
{
"category": "文档",
"count": 5,
"size": 5242880
},
{
"category": "图片",
"count": 3,
"size": 3145728
}
]
}
}
11. 搜索文件
GET /api/files/search?keyword=文档&tenant_id=tenant-001
参数:
keyword(查询参数): 搜索关键词tenant_id(查询参数): 租户ID
响应: 同获取所有文件接口
12. 公开接口（无需认证）
GET /api/files/public
参数: 无
响应: 同获取所有文件接口
错误响应
所有接口在发生错误时返回统一的错误格式：
{
"success": false,
"message": "错误描述",
"error": "详细错误信息"
}
状态码说明
200: 请求成功400: 参数错误404: 资源不存在500: 服务器内部错误
使用示例
前端调用示例（JavaScript）
// 获取所有文件
const response = await fetch('/api/files');
const result = await response.json();
// 创建文件
const newFile = {
tenant_id: "tenant-001",
file_name: "example.txt",
original_name: "示例文件.txt",
file_path: "/uploads/example.txt",
file_type: "text/plain",
file_ext: "txt",
category: "文档",
upload_by: "user123"
};
const createResponse = await fetch('/api/files', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(newFile)
});
注意事项
- 所有需要认证的接口都需要在请求头中包含有效的 JWT Token
- 文件上传功能需要配合文件存储服务实现
- 软删除只是标记文件状态为删除，实际数据仍然保留
- 硬删除会永久删除文件记录，请谨慎使用