zs-file 模块技术文档

1. 模块概述

zs-file 是系统的文件管理模块，提供了文件上传、存储和管理功能。该模块采用策略模式设计，支持多种存储方式，包括本地文件系统、阿里云OSS、腾讯云COS和华为云OBS，用户可以根据需要灵活切换。

2. 目录结构

zs-file/
├── zs-file-api/             # API定义模块
├── zs-file-service/         # 服务实现模块
│   ├── src/main/java/com/zs/file/
│   │   ├── controller/      # 控制器
│   │   ├── domain/          # 数据模型
│   │   │   ├── dto/         # 请求DTO
│   │   │   ├── entity/      # 实体类
│   │   │   └── vo/          # 响应VO
│   │   ├── factory/         # 工厂类
│   │   ├── manager/         # 客户端管理器
│   │   ├── mapper/          # Mapper接口
│   │   ├── service/         # 服务层
│   │   └── strategy/        # 上传策略
│   └── pom.xml
└── pom.xml                  # 父级POM

3. 核心组件说明

3.1 控制器

文件路径: com.zs.file.controller.SysFileController

提供文件上传相关的REST API：

POST /system/file/upload：单文件上传
POST /system/file/uploads：多文件上传

3.2 数据模型

实体类: com.zs.file.domain.entity.SysFileEntity

字段名	类型	描述
id	Long	文件ID
fileName	String	文件名
fileType	String	文件类型
fileSize	Long	文件大小
filePath	String	文件路径
fileUrl	String	文件访问URL
uploadType	String	上传类型
createTime	Date	创建时间
updateTime	Date	更新时间

3.3 工厂类

文件路径: com.zs.file.factory.FileFactory

采用工厂模式，根据配置的上传类型动态创建对应的上传策略实例。

核心方法:

build()：根据配置创建上传策略实例
initialize()：初始化文件上传配置

3.4 客户端管理器

文件路径: com.zs.file.manager

提供云存储客户端的管理功能：

OSSClientManager：阿里云OSS客户端管理器
COSClientManager：腾讯云COS客户端管理器
ObsClientManager：华为云OBS客户端管理器

3.5 上传策略

文件路径: com.zs.file.strategy

采用策略模式，支持多种上传方式：

策略类	上传方式
LocalFileStrategy	本地文件系统
AliyunCloudStrategy	阿里云OSS
TencentCloudStrategy	腾讯云COS
HuaweiCloudStrategy	华为云OBS

策略接口: UploadStrategy

java

public interface UploadStrategy {
    SysFileEntity upload(MultipartFile file);
    List<SysFileEntity> uploads(MultipartFile[] files);
}

4. 核心功能详解

4.1 文件上传流程

客户端调用文件上传API
SysFileController 接收上传请求
通过 FileFactory 获取配置的上传策略
调用对应策略的 upload 或 uploads 方法
上传成功后返回文件信息
将文件信息保存到数据库

4.2 策略选择机制

java

public static UploadStrategy build() {
    // 从Redis获取上传配置
    Object object = redisUtil.get(RedisConstants.SYS_DICT_CONFIG_KEY + Constants.FILE_UPLOAD);
    SysConfigFileVO sysConfigFileVO = JSONUtil.toBean(JSONUtil.toJsonStr(object), SysConfigFileVO.class);
    UploadTypeEnum uploadTypeEnum = UploadTypeEnum.getEnum(sysConfigFileVO.getType());
    if (uploadTypeEnum == null) {
        return new LocalFileStrategy(sysConfigFileVO);
    }

    return switch (uploadTypeEnum) {
        case LOCAL -> new LocalFileStrategy(sysConfigFileVO);
        case TENCENT -> new TencentCloudStrategy(sysConfigFileVO);
        case ALIYUN -> new AliyunCloudStrategy(sysConfigFileVO);
        case HUAWEI -> new HuaweiCloudStrategy(sysConfigFileVO);
    };
}

4.3 多文件上传支持

系统支持多文件同时上传，通过调用 uploads 方法实现，内部会遍历文件数组并逐个上传。

5. 技术架构

5.1 设计模式

策略模式：用于处理不同的文件上传方式
工厂模式：用于创建上传策略实例

5.2 技术栈

Spring Boot 3.x
MyBatis Plus
Redis
阿里云OSS SDK
腾讯云COS SDK
华为云OBS SDK
Hutool工具库

6. 使用方法

6.1 单文件上传

请求URL：POST /system/file/upload

请求参数：

file：要上传的文件（multipart/form-data）

响应示例：

json

{
  "code": 200,
  "message": "上传成功",
  "data": {
    "id": 1,
    "fileName": "test.jpg",
    "fileType": "image/jpeg",
    "fileSize": 102400,
    "fileUrl": "http://localhost:8080/files/test.jpg",
    "uploadType": "LOCAL",
    "createTime": "2025-12-22 10:00:00"
  }
}

6.2 多文件上传

请求URL：POST /system/file/uploads

请求参数：

file：要上传的文件数组（multipart/form-data）

响应示例：

json

{
  "code": 200,
  "message": "上传成功",
  "data": [
    {
      "id": 1,
      "fileName": "test1.jpg",
      "fileType": "image/jpeg",
      "fileSize": 102400,
      "fileUrl": "http://localhost:8080/files/test1.jpg",
      "uploadType": "LOCAL",
      "createTime": "2025-12-22 10:00:00"
    },
    {
      "id": 2,
      "fileName": "test2.jpg",
      "fileType": "image/jpeg",
      "fileSize": 204800,
      "fileUrl": "http://localhost:8080/files/test2.jpg",
      "uploadType": "LOCAL",
      "createTime": "2025-12-22 10:00:00"
    }
  ]
}

7. 配置说明

提示

文件上传使用动态配置，通过 file.upload.type 配置上传方式，并添加对应的配置项。

文件上传配置项

json

{
    "type": 1,
    "local": {  // 本地文件系统
        "domain": "https://demo.zsadmin.top/api",  
        "prefix": "file",
        "path": "/var/www/uploads"
    },
    "aliyun": {  // 阿里云OSS
        "domain": "zs-admin.oss-cn-beijing.aliyuncs.com",
        "endpoint": "oss-cn-beijing.aliyuncs.com",
        "accessKeyId": "121212",
        "accessKeySecret": "1212",
        "bucketName": "zs-admin"
    },
    "tencent": {  // 腾讯云COS
        "domain": "https://zs-admin-1253642143.cos.ap-beijing.myqcloud.com",
        "region": "ap-beijing",
        "secretId": "121212",
        "secretKey": "121212",
        "bucketName": "zs-admin-1253642143"
    },
    "huawei": {  // 华为云OBS
        "domain": "https://zs-admin.obs.cn-north-4.myhuaweicloud.com",
        "endPoint": "obs.cn-north-4.myhuaweicloud.com",
        "accessKey": "1212",
        "secretAccessKey": "1212",
        "bucketName": "zs-admin"
    }
}

zs-file 模块技术文档 ​

1. 模块概述 ​

2. 目录结构 ​

3. 核心组件说明 ​

3.1 控制器 ​

3.2 数据模型 ​

3.3 工厂类 ​

3.4 客户端管理器 ​

3.5 上传策略 ​

4. 核心功能详解 ​

4.1 文件上传流程 ​

4.2 策略选择机制 ​

4.3 多文件上传支持 ​

5. 技术架构 ​

5.1 设计模式 ​

5.2 技术栈 ​

6. 使用方法 ​

6.1 单文件上传 ​

6.2 多文件上传 ​

7. 配置说明 ​

zs-file 模块技术文档

1. 模块概述

2. 目录结构

3. 核心组件说明

3.1 控制器

3.2 数据模型

3.3 工厂类

3.4 客户端管理器

3.5 上传策略

4. 核心功能详解

4.1 文件上传流程

4.2 策略选择机制

4.3 多文件上传支持

5. 技术架构

5.1 设计模式

5.2 技术栈

6. 使用方法

6.1 单文件上传

6.2 多文件上传

7. 配置说明