一、概述

文件服务(kb-file)是知识库系统的核心支撑模块,提供文件存储、上传、下载、预览等功能。

本文将详细介绍如何从零开始搭建文件服务模块,实现完整的图片上传功能。

1.1 服务定位

文件服务作为系统的文件基础设施层,为其他业务模块提供:

功能模块说明使用场景
文件上传支持多种文件格式上传文档编辑器插入图片、头像上传等
文件存储分布式文件存储系统大容量、高可靠文件存储
文件下载安全的文件下载服务文档附件下载、图片访问
文件预览在线预览功能图片预览、文档预览
断点续传大文件分块上传大视频文件上传、断网恢复

1.2 技术架构

kb-file
├── 数据持久层:MyBatis Plus + MySQL
├── 缓存层:Redis(文件信息缓存)
├── 存储层:RustFS(分布式文件系统)
├── API文档:Knife4j
├── 服务注册:Nacos
└── 基础设施:Spring Boot 3.2

1.3 功能特点

  • 高性能:支持分布式存储,可水平扩展
  • 安全性:文件类型校验、大小限制、访问控制
  • 断点续传:支持大文件分块上传
  • 多端支持:提供RESTful API,支持多种客户端
  • 简单易用:统一的文件上传接口,降低集成复杂度

二、环境准备

2.1 RustFS存储系统安装

文件服务使用RustFS作为分布式文件存储系统。

RustFS是基于Rust语言开发的高性能对象存储系统,兼容AWS S3 API。

# Docker方式安装RustFS
docker run -d \
  --name rustfs \
  -p 9091:9091 \
  -e RUSTFS_LOG_LEVEL=info \
  -v /data/rustfs:/data \
  rustfs/rustfs:latest \
  --endpoint 0.0.0.0:9091 \
  --data-dir /data

如果不想自己安装,可以直接使用京东云中我搭建好的RustFS文件服务。

2.2 数据库准备

创建kb\_file数据库:

mysql -u root -p -e "CREATE DATABASE kb_file DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

三、创建模块骨架

3.1 创建Maven模块

在项目根目录下创建kb-file子模块:

mkdir -p kb-file/src/main/java/com/knowledge/base/file
mkdir -p kb-file/src/main/resources

3.2 配置pom.xml

创建 kb-file/pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>com.knowledge.base</groupId>
        <artifactId>knowledge-base-backend</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>
    <artifactId>kb-file</artifactId>
    <packaging>jar</packaging>
    <name>Knowledge Base File Service</name>
    <description>文件服务</description>
    <dependencies>
        <!-- 公共模块 -->
        <dependency>
            <groupId>com.knowledge.base</groupId>
            <artifactId>kb-common</artifactId>
        </dependency>
        <!-- Spring Boot Web -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!-- Spring Boot Validation -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
        </dependency>
        <!-- MySQL驱动 -->
        <dependency>
            <groupId>com.mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
            <scope>runtime</scope>
        </dependency>
        <!-- Druid数据源 -->
        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>druid-spring-boot-3-starter</artifactId>
        </dependency>
        <!-- MyBatis Plus -->
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-boot-starter</artifactId>
        </dependency>
        <!-- Redis -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-redis</artifactId>
        </dependency>
        <!-- Apache POI(文档处理) -->
        <dependency>
            <groupId>org.apache.poi</groupId>
            <artifactId>poi-ooxml</artifactId>
            <version>5.2.5</version>
        </dependency>
        <!-- PDFBox(PDF处理) -->
        <dependency>
            <groupId>org.apache.pdfbox</groupId>
            <artifactId>pdfbox</artifactId>
            <version>2.0.29</version>
        </dependency>
        <!-- Nacos 配置中心 -->
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
        </dependency>
        <!-- Nacos 服务注册与发现 -->
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
        </dependency>
        <!-- Hutool -->
        <dependency>
            <groupId>cn.hutool</groupId>
            <artifactId>hutool-all</artifactId>
        </dependency>
        <!-- Lombok -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <!-- Knife4j -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
        </dependency>
        <!-- AWS SDK S3 -->
        <dependency>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>s3</artifactId>
            <version>2.25.0</version>
        </dependency>
        <!-- Test -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

四、数据库设计

4.1 文件信息表设计

创建数据库表 kb_file/sql/01_init_table.sql:

-- 文件信息表
CREATE TABLE `tb_file` (
    `id` BIGINT NOT NULL COMMENT '文件ID(雪花算法)',
    `original_name` VARCHAR(255) NOT NULL COMMENT '原始文件名',
    `stored_name` VARCHAR(255) DEFAULT NULL COMMENT '存储文件名',
    `file_path` VARCHAR(500) NOT NULL COMMENT '文件路径',
    `file_size` BIGINT NOT NULL COMMENT '文件大小(字节)',
    `file_type` VARCHAR(50) NOT NULL COMMENT '文件类型:IMAGE-图片,VIDEO-视频,AUDIO-音频,DOCUMENT-文档,OTHER-其他',
    `mime_type` VARCHAR(100) DEFAULT NULL COMMENT 'MIME类型',
    `file_hash` VARCHAR(64) DEFAULT NULL COMMENT '文件哈希(SHA256)',
    `storage_type` VARCHAR(50) NOT NULL DEFAULT 'RUSTFS' COMMENT '存储类型:RUSTFS-分布式存储,LOCAL-本地存储',
    `bucket_name` VARCHAR(100) DEFAULT NULL COMMENT '存储桶名称',
    `uploader_id` BIGINT NOT NULL COMMENT '上传者ID',
    `access_level` TINYINT NOT NULL DEFAULT 0 COMMENT '访问级别:0-私有,1-团队可见,2-公开',
    `download_count` INT NOT NULL DEFAULT 0 COMMENT '下载次数',
    `status` TINYINT NOT NULL DEFAULT 1 COMMENT '状态:0-删除,1-正常',
    `deleted` TINYINT NOT NULL DEFAULT 0 COMMENT '删除标记:0-正常,1-已删除',
    `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    `create_by` BIGINT DEFAULT NULL COMMENT '创建人ID',
    `update_by` BIGINT DEFAULT NULL COMMENT '更新人ID',
    PRIMARY KEY (`id`),
    KEY `idx_file_hash` (`file_hash`),
    KEY `idx_uploader_id` (`uploader_id`),
    KEY `idx_storage_type` (`storage_type`),
    KEY `idx_created_at` (`created_at`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='文件信息表';

4.2 字段说明

字段类型说明示例
idBIGINT文件唯一标识,使用雪花算法生成315091148181999616
original\_nameVARCHAR(255)原始文件名截屏2026-05-19.png
stored\_nameVARCHAR(255)存储文件名(系统生成)a1b2c3d4e5f6.png
file\_pathVARCHAR(500)文件在存储系统中的路径2026/05/19/ab/abc123...png
file\_sizeBIGINT文件大小(字节)50214
file\_typeVARCHAR(50)文件类型分类IMAGE
mime\_typeVARCHAR(100)MIME类型image/png
file\_hashVARCHAR(64)文件SHA256哈希值,用于去重a1b2c3d4...
storage\_typeVARCHAR(50)存储类型RUSTFS
bucket\_nameVARCHAR(100)存储桶名称mall-dev

五、实体类设计

5.1 文件信息实体

创建 entity/FileInfo.java:

package com.knowledge.base.file.entity;

import com.baomidou.mybatisplus.annotation.*;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
import lombok.EqualsAndHashCode;

import java.time.LocalDateTime;

/**
 * 文件信息实体
 *
 * @author 苏三
 * @since 1.0.0
 */
@Data
@EqualsAndHashCode
@TableName("tb_file")
@Schema(description = "文件信息实体")
public class FileInfo {

    private static final long serialVersionUID = 1L;

    /**
     * 文件ID
     */
    @TableId(type = IdType.ASSIGN_ID)
    @Schema(description = "文件ID")
    private Long id;

    /**
     * 原始文件名
     */
    @Schema(description = "原始文件名")
    private String originalName;

    /**
     * 存储文件名
     */
    @Schema(description = "存储文件名")
    private String storedName;

    /**
     * 文件路径
     */
    @Schema(description = "文件路径")
    private String filePath;

    /**
     * 文件大小(字节)
     */
    @Schema(description = "文件大小")
    private Long fileSize;

    /**
     * 文件类型
     */
    @Schema(description = "文件类型")
    private String fileType;

    /**
     * MIME类型
     */
    @Schema(description = "MIME类型")
    private String mimeType;

    /**
     * 文件哈希
     */
    @Schema(description = "文件哈希")
    private String fileHash;

    /**
     * 存储类型
     */
    @Schema(description = "存储类型")
    private String storageType;

    /**
     * 存储桶名称
     */
    @Schema(description = "存储桶名称")
    private String bucketName;

    /**
     * 上传者ID
     */
    @Schema(description = "上传者ID")
    private Long uploaderId;

    /**
     * 访问级别:0-私有,1-团队可见,2-公开
     */
    @Schema(description = "访问级别")
    private Integer accessLevel;

    /**
     * 下载次数
     */
    @Schema(description = "下载次数")
    private Integer downloadCount;

    /**
     * 状态:0-删除,1-正常
     */
    @Schema(description = "状态")
    private Integer status;

    /**
     * 删除标记
     */
    @TableLogic
    @Schema(description = "删除标记")
    private Integer deleted;

    /**
     * 创建时间
     */
    @TableField("created_at")
    @Schema(description = "创建时间")
    private LocalDateTime createTime;

    /**
     * 更新时间
     */
    @Schema(description = "更新时间")
    private LocalDateTime updateTime;

    /**
     * 创建人ID
     */
    @Schema(description = "创建人ID")
    private Long createBy;

    /**
     * 更新人ID
     */
    @Schema(description = "更新人ID")
    private Long updateBy;
}

5.2 存储类型枚举

创建 storage/StorageType.java:

package com.knowledge.base.file.storage;

/**
 * 存储类型枚举
 *
 * @author knowledge-base-team
 * @since 1.0.0
 */
public enum StorageType {

    /**
     * RustFS 分布式文件存储
     */
    RUSTFS("rustfs", "rustFileStorage");

    private final String code;
    private final String beanName;

    StorageType(String code, String beanName) {
        this.code = code;
        this.beanName = beanName;
    }

    public String getCode() {
        return code;
    }

    public String getBeanName() {
        return beanName;
    }

    public static StorageType fromCode(String code) {
        for (StorageType type : values()) {
            if (type.code.equalsIgnoreCase(code)) {
                return type;
            }
        }
        return RUSTFS;
    }
}

六、数据传输对象

6.1 文件上传DTO

创建 dto/FileUploadDTO.java:

package com.knowledge.base.file.dto;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

/**
 * 文件上传DTO
 *
 * @author 苏三
 * @since 1.0.0
 */
@Data
@Schema(description = "文件上传请求")
public class FileUploadDTO {

    /**
     * 上传者ID
     */
    @Schema(description = "上传者ID")
    private Long uploaderId;

    /**
     * 访问级别:0-私有,1-团队可见,2-公开
     */
    @Schema(description = "访问级别", example = "0")
    private Integer accessLevel = 0;

    /**
     * 存储类型:rustfs-分布式存储,local-本地存储
     */
    @Schema(description = "存储类型", example = "rustfs")
    private String storageType = "rustfs";

    /**
     * 业务类型
     */
    @Schema(description = "业务类型", example = "document")
    private String businessType;

    /**
     * 业务ID
     */
    @Schema(description = "业务ID")
    private Long businessId;
}

6.2 文件查询DTO

创建 dto/FileQueryDTO.java:

package com.knowledge.base.file.dto;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

/**
 * 文件查询DTO
 *
 * @author 苏三
 * @since 1.0.0
 */
@Data
@Schema(description = "文件查询请求")
public class FileQueryDTO {

    /**
     * 文件类型
     */
    @Schema(description = "文件类型")
    private String fileType;

    /**
     * 上传者ID
     */
    @Schema(description = "上传者ID")
    private Long uploaderId;

    /**
     * 存储类型
     */
    @Schema(description = "存储类型")
    private String storageType;

    /**
     * 关键字搜索(文件名)
     */
    @Schema(description = "关键字搜索")
    private String keyword;

    /**
     * 页码
     */
    @Schema(description = "页码", example = "1")
    private Integer pageNum = 1;

    /**
     * 页面大小
     */
    @Schema(description = "页面大小", example = "10")
    private Integer pageSize = 10;
}

6.3 文件信息VO

创建 vo/FileInfoVO.java:

package com.knowledge.base.file.vo;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Builder;
import lombok.Data;

import java.time.LocalDateTime;

/**
 * 文件信息VO
 *
 * @author 苏三
 * @since 1.0.0
 */
@Data
@Builder
@Schema(description = "文件信息响应")
public class FileInfoVO {

    /**
     * 文件ID
     */
    @Schema(description = "文件ID")
    private Long id;

    /**
     * 原始文件名
     */
    @Schema(description = "原始文件名")
    private String originalName;

    /**
     * 文件大小
     */
    @Schema(description = "文件大小(字节)")
    private Long fileSize;

    /**
     * 文件大小(可读格式)
     */
    @Schema(description = "文件大小(可读格式)")
    private String fileSizeReadable;

    /**
     * 文件类型
     */
    @Schema(description = "文件类型")
    private String fileType;

    /**
     * MIME类型
     */
    @Schema(description = "MIME类型")
    private String mimeType;

    /**
     * 文件URL
     */
    @Schema(description = "文件访问URL")
    private String fileUrl;

    /**
     * 预览URL
     */
    @Schema(description = "文件预览URL")
    private String previewUrl;

    /**
     * 上传者ID
     */
    @Schema(description = "上传者ID")
    private Long uploaderId;

    /**
     * 上传者名称
     */
    @Schema(description = "上传者名称")
    private String uploaderName;

    /**
     * 访问级别
     */
    @Schema(description = "访问级别")
    private Integer accessLevel;

    /**
     * 下载次数
     */
    @Schema(description = "下载次数")
    private Integer downloadCount;

    /**
     * 存储类型
     */
    @Schema(description = "存储类型")
    private String storageType;

    /**
     * 创建时间
     */
    @Schema(description = "创建时间")
    private LocalDateTime createdAt;
}

七、数据持久层

7.1 文件Mapper接口

创建 mapper/FileMapper.java:

package com.knowledge.base.file.mapper;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.knowledge.base.file.entity.FileInfo;
import org.apache.ibatis.annotations.Mapper;

/**
 * 文件Mapper接口
 *
 * @author 苏三
 * @since 1.0.0
 */
@Mapper
public interface FileMapper extends BaseMapper<FileInfo> {
}

7.2 MyBatis配置

创建 resources/mapper/FileMapper.xml:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.knowledge.base.file.mapper.FileMapper">

    <!-- 通用查询映射结果 -->
    <resultMap id="BaseResultMap" type="com.knowledge.base.file.entity.FileInfo">
        <id column="id" property="id" />
        <result column="original_name" property="originalName" />
        <result column="stored_name" property="storedName" />
        <result column="file_path" property="filePath" />
        <result column="file_size" property="fileSize" />
        <result column="file_type" property="fileType" />
        <result column="mime_type" property="mimeType" />
        <result column="file_hash" property="fileHash" />
        <result column="storage_type" property="storageType" />
        <result column="bucket_name" property="bucketName" />
        <result column="uploader_id" property="uploaderId" />
        <result column="access_level" property="accessLevel" />
        <result column="download_count" property="downloadCount" />
        <result column="status" property="status" />
        <result column="deleted" property="deleted" />
        <result column="create_time" property="createTime" />
        <result column="update_time" property="updateTime" />
        <result column="create_by" property="createBy" />
        <result column="update_by" property="updateBy" />
    </resultMap>

    <!-- 通用查询结果列 -->
    <sql id="Base_Column_List">
        id, original_name, stored_name, file_path, file_size, file_type, mime_type, file_hash,
        storage_type, bucket_name, uploader_id, access_level, download_count, status,
        deleted, version, create_time, update_time, create_by, update_by
    </sql>

    <!-- 根据上传者ID查询文件列表 -->
    <select id="selectByUploaderId" resultMap="BaseResultMap">
        SELECT
        <include refid="Base_Column_List" />
        FROM tb_file
        WHERE uploader_id = #{uploaderId}
        AND deleted = 0
        ORDER BY create_time DESC
    </select>

    <!-- 根据文件类型查询文件列表 -->
    <select id="selectByFileType" resultMap="BaseResultMap">
        SELECT
        <include refid="Base_Column_List" />
        FROM tb_file
        WHERE file_type = #{fileType}
        AND status = 1
        AND deleted = 0
        ORDER BY create_time DESC
    </select>

    <!-- 根据文件哈希查询文件 -->
    <select id="selectByFileHash" resultMap="BaseResultMap">
        SELECT
        <include refid="Base_Column_List" />
        FROM tb_file
        WHERE file_hash = #{fileHash}
        AND deleted = 0
        LIMIT 1
    </select>

    <!-- 根据存储类型查询文件列表 -->
    <select id="selectByStorageType" resultMap="BaseResultMap">
        SELECT
        <include refid="Base_Column_List" />
        FROM tb_file
        WHERE storage_type = #{storageType}
        AND deleted = 0
        ORDER BY create_time DESC
    </select>

    <!-- 根据访问级别查询文件列表 -->
    <select id="selectByAccessLevel" resultMap="BaseResultMap">
        SELECT
        <include refid="Base_Column_List" />
        FROM tb_file
        WHERE access_level &lt;= #{accessLevel}
        AND status = 1
        AND deleted = 0
        ORDER BY create_time DESC
    </select>

    <!-- 增加下载次数 -->
    <update id="incrementDownloadCount">
        UPDATE tb_file
        SET download_count = download_count + 1
        WHERE id = #{fileId}
        AND deleted = 0
    </update>

    <!-- 更新文件状态 -->
    <update id="updateStatus">
        UPDATE tb_file
        SET status = #{status}
        WHERE id = #{fileId}
        AND deleted = 0
    </update>

    <!-- 检查文件哈希是否存在 -->
    <select id="checkFileHashExists" resultType="java.lang.Boolean">
        SELECT COUNT(*) > 0
        FROM tb_file
        WHERE file_hash = #{fileHash}
        AND deleted = 0
    </select>

    <!-- 统计用户上传的文件数量 -->
    <select id="countByUploaderId" resultType="java.lang.Long">
        SELECT COUNT(*)
        FROM tb_file
        WHERE uploader_id = #{uploaderId}
        AND deleted = 0
    </select>

    <!-- 统计用户上传的文件总大小 -->
    <select id="sumFileSizeByUploaderId" resultType="java.lang.Long">
        SELECT COALESCE(SUM(file_size), 0)
        FROM tb_file
        WHERE uploader_id = #{uploaderId}
        AND status = 1
        AND deleted = 0
    </select>

    <!-- 根据存储桶名称查询文件列表 -->
    <select id="selectByBucketName" resultMap="BaseResultMap">
        SELECT
        <include refid="Base_Column_List" />
        FROM tb_file
        WHERE bucket_name = #{bucketName}
        AND deleted = 0
        ORDER BY create_time DESC
    </select>

</mapper>

7.3 应用配置

创建 src/main/resources/application.yml:

server:
  port: 8084

spring:
  application:
    name: kb-file
  profiles:
    active: dev

  # Nacos 服务注册与发现
  cloud:
    nacos:
      config:
        namespace: knowledge
        server-addr: 117.72.88.11:8848
        file-extension: yaml
        group: KNOWLEDGE_BASE
        enabled: true
        username: nacos
        password: susan123
      discovery:
        server-addr: 117.72.88.11:8848
        namespace: KNOWLEDGE_BASE
        username: nacos
        password: susan123
    config:
      import: optional:nacos:kb-file-dev.yaml

  # 数据源配置
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/kb_file?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
    username: root
    password: 123456
    type: com.alibaba.druid.pool.DruidDataSource
    druid:
      initial-size: 5
      min-idle: 5
      max-active: 30
      max-wait: 60000
      test-while-idle: true
      test-on-borrow: false
      test-on-return: false
      validation-query: SELECT 1
      time-between-eviction-runs-millis: 60000
      min-evictable-idle-time-millis: 300000
      filters: stat,wall

  # Redis配置
  data:
    redis:
      host: localhost
      port: 6379
      password:
      database: 3
      timeout: 5000ms
      lettuce:
        pool:
          max-active: 20
          max-idle: 10
          min-idle: 5
          max-wait: 3000ms

  # 文件上传配置
  servlet:
    multipart:
      enabled: true
      max-file-size: 50MB
      max-request-size: 500MB

# MyBatis Plus配置
mybatis-plus:
  mapper-locations: classpath*:/mapper/**/*.xml
  type-aliases-package: com.knowledge.base.file.entity
  configuration:
    map-underscore-to-camel-case: true
    cache-enabled: false
    log-impl: org.apache.ibatis.logging.slf4j.Slf4jImpl
  global-config:
    db-config:
      id-type: ASSIGN_ID
      logic-delete-field: deleted
      logic-delete-value: 1
      logic-not-delete-value: 0

# 文件存储配置 - 使用 RustFS 分布式文件系统
file:
  storage:
    type: rustfs
    rustfs:
      # RustFS 服务端点地址
      endpoint: 117.72.88.11
      # 服务端口
      port: 9091
      # 访问密钥ID
      accessKey: IPL4GZeFumv8g9ANj3b7
      # 秘密访问密钥
      secretKey: IFil9yzO520VLE8f7qoXHgBNkUG4TmWvDrSc1ReQ
      # 是否使用 HTTPS
      secure: false
      # 默认存储桶名称
      bucketName: knowledge-dev
      # 连接超时时间(毫秒)
      connectTimeout: 30000
      # 读取超时时间(毫秒)
      readTimeout: 60000
      # 写入超时时间(毫秒)
      writeTimeout: 60000
      # 最大连接数
      maxConnections: 50
      # 是否启用 RustFS
      enabled: true
    upload:
      max-size: 52428800  # 50MB
      allowed-types:
        - pdf
        - doc
        - docx
        - xls
        - xlsx
        - ppt
        - pptx
        - txt
        - md
        - png
        - jpg
        - jpeg
        - gif
        - bmp
        - svg
      enable-fast-upload: true
      calculate-hash: true
      enable-resumable-upload: true
    url:
      prefix: http://localhost:8084/file
      preview-prefix: http://localhost:8084/file/preview

# Knife4j配置
knife4j:
  enable: true
  setting:
    language: zh_cn
    production: false

# 日志配置
logging:
  level:
    com.knowledge.base: debug
    org.springframework: info
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{50} - %msg%n"

八、存储层实现

8.1 文件存储接口

创建 storage/FileStorage.java:

package com.knowledge.base.file.storage;

import java.io.InputStream;
import java.io.OutputStream;

/**
 * 文件存储接口
 *
 * @author 苏三
 * @since 1.0.0
 */
public interface FileStorage {

    /**
     * 上传文件
     *
     * @param inputStream 文件输入流
     * @param relativePath 相对路径
     * @param fileSize 文件大小
     * @return 是否成功
     */
    boolean upload(InputStream inputStream, String relativePath, long fileSize);

    /**
     * 下载文件
     *
     * @param relativePath 相对路径
     * @param outputStream 输出流
     * @return 下载的字节数
     */
    long download(String relativePath, OutputStream outputStream);

    /**
     * 获取文件输入流
     *
     * @param relativePath 相对路径
     * @return 文件输入流
     */
    InputStream getInputStream(String relativePath);

    /**
     * 删除文件
     *
     * @param relativePath 相对路径
     * @return 是否成功
     */
    boolean delete(String relativePath);

    /**
     * 检查文件是否存在
     *
     * @param relativePath 相对路径
     * @return 是否存在
     */
    boolean exists(String relativePath);

    /**
     * 获取文件大小
     *
     * @param relativePath 相对路径
     * @return 文件大小
     */
    long getFileSize(String relativePath);

    /**
     * 获取存储类型
     *
     * @return 存储类型
     */
    String getStorageType();
}

8.2 RustFS存储实现

创建 storage/RustFileStorage.java:

package com.knowledge.base.file.storage;

import com.knowledge.base.file.config.FileStorageProperties;
import lombok.extern.slf4j.Slf4j;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.stereotype.Component;
import software.amazon.awssdk.core.ResponseInputStream;
import software.amazon.awssdk.core.sync.RequestBody;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.*;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.*;

/**
 * RustFS 文件存储实现
 * 使用 AWS SDK S3 客户端连接支持 S3 兼容 API 的 RustFS 分布式文件系统
 */
@Slf4j
@Component("rustFileStorage")
@ConditionalOnProperty(name = "file.storage.type", havingValue = "rustfs")
public class RustFileStorage implements FileStorage {

    private final S3Client s3Client;
    private final FileStorageProperties storageProperties;

    /**
     * 断点续传会话缓存
     */
    private final Map<String, UploadSession> uploadSessions = new HashMap<>();

    public RustFileStorage(S3Client s3Client, FileStorageProperties storageProperties) {
        this.s3Client = s3Client;
        this.storageProperties = storageProperties;
    }

    private String getBucketName() {
        return storageProperties.getRustfs().getBucketName();
    }

    @Override
    public boolean upload(InputStream inputStream, String relativePath, long fileSize) {
        try {
            String bucketName = getBucketName();
            log.debug("上传文件到RustFS: bucket={}, path={}, size={}", bucketName, relativePath, fileSize);

            s3Client.putObject(PutObjectRequest.builder()
                            .bucket(bucketName)
                            .key(relativePath)
                            .build(),
                    RequestBody.fromInputStream(inputStream, fileSize));

            log.info("文件上传成功: {}", relativePath);
            return true;
        } catch (S3Exception e) {
            log.error("文件上传失败: {}", relativePath, e);
            throw new RuntimeException("文件上传失败: " + e.getMessage(), e);
        }
    }

    @Override
    public long download(String relativePath, OutputStream outputStream) {
        try {
            String bucketName = getBucketName();
            log.debug("从RustFS下载文件: bucket={}, path={}", bucketName, relativePath);

            GetObjectRequest request = GetObjectRequest.builder()
                    .bucket(bucketName)
                    .key(relativePath)
                    .build();

            try (ResponseInputStream<GetObjectResponse> response = s3Client.getObject(request)) {
                long bytesCopied = response.transferTo(outputStream);
                log.info("文件下载成功: {}, bytes={}", relativePath, bytesCopied);
                return bytesCopied;
            }
        } catch (S3Exception e) {
            log.error("文件下载失败: {}", relativePath, e);
            throw new RuntimeException("文件下载失败: " + e.getMessage(), e);
        } catch (IOException e) {
            log.error("IO错误: {}", relativePath, e);
            throw new RuntimeException("IO错误: " + e.getMessage(), e);
        }
    }

    @Override
    public InputStream getInputStream(String relativePath) {
        try {
            String bucketName = getBucketName();
            log.debug("获取文件输入流: bucket={}, path={}", bucketName, relativePath);

            GetObjectRequest request = GetObjectRequest.builder()
                    .bucket(bucketName)
                    .key(relativePath)
                    .build();

            ResponseInputStream<GetObjectResponse> response = s3Client.getObject(request);
            log.info("获取输入流成功: {}", relativePath);
            return response;
        } catch (S3Exception e) {
            log.error("获取输入流失败: {}", relativePath, e);
            throw new RuntimeException("获取输入流失败: " + e.getMessage(), e);
        }
    }

    @Override
    public boolean delete(String relativePath) {
        try {
            String bucketName = getBucketName();
            log.debug("删除RustFS文件: bucket={}, path={}", bucketName, relativePath);

            s3Client.deleteObject(DeleteObjectRequest.builder()
                    .bucket(bucketName)
                    .key(relativePath)
                    .build());

            log.info("文件删除成功: {}", relativePath);
            return true;
        } catch (S3Exception e) {
            log.error("文件删除失败: {}", relativePath, e);
            throw new RuntimeException("文件删除失败: " + e.getMessage(), e);
        }
    }

    @Override
    public boolean exists(String relativePath) {
        try {
            String bucketName = getBucketName();
            log.debug("检查文件存在: bucket={}, path={}", bucketName, relativePath);

            HeadObjectRequest request = HeadObjectRequest.builder()
                    .bucket(bucketName)
                    .key(relativePath)
                    .build();

            s3Client.headObject(request);
            return true;
        } catch (NoSuchKeyException e) {
            log.debug("文件不存在: {}", relativePath);
            return false;
        } catch (S3Exception e) {
            log.error("检查文件存在时出错: {}", relativePath, e);
            throw new RuntimeException("检查文件存在时出错: " + e.getMessage(), e);
        }
    }

    @Override
    public long getFileSize(String relativePath) {
        try {
            String bucketName = getBucketName();
            log.debug("获取文件大小: bucket={}, path={}", bucketName, relativePath);

            HeadObjectRequest request = HeadObjectRequest.builder()
                    .bucket(bucketName)
                    .key(relativePath)
                    .build();

            HeadObjectResponse response = s3Client.headObject(request);
            long size = response.contentLength();
            log.info("获取文件大小成功: {}, size={}", relativePath, size);
            return size;
        } catch (S3Exception e) {
            log.error("获取文件大小失败: {}", relativePath, e);
            throw new RuntimeException("获取文件大小失败: " + e.getMessage(), e);
        }
    }

    @Override
    public String getStorageType() {
        return "rustfs";
    }

    // ==================== 断点续传支持 ====================

    /**
     * 初始化断点续传会话
     */
    public void initResumableUpload(String sessionId, String relativePath, long totalSize, int chunkCount) {
        log.debug("初始化断点续传: sessionId={}, path={}, size={}, chunks={}",
                sessionId, relativePath, totalSize, chunkCount);

        // 创建 S3 分片上传
        software.amazon.awssdk.services.s3.model.CreateMultipartUploadRequest createRequest =
                software.amazon.awssdk.services.s3.model.CreateMultipartUploadRequest.builder()
                        .bucket(getBucketName())
                        .key(relativePath)
                        .build();

        software.amazon.awssdk.services.s3.model.CreateMultipartUploadResponse response =
                s3Client.createMultipartUpload(createRequest);
        String uploadId = response.uploadId();

        // 存储会话信息
        UploadSession session = new UploadSession();
        session.setUploadId(uploadId);
        session.setRelativePath(relativePath);
        session.setTotalSize(totalSize);
        session.setChunkCount(chunkCount);
        session.setUploadedParts(new HashSet<>());

        uploadSessions.put(sessionId, session);
        log.info("断点续传会话初始化成功: sessionId={}, uploadId={}", sessionId, uploadId);
    }

    /**
     * 上传分块
     */
    public boolean uploadChunk(String sessionId, int chunkIndex, InputStream inputStream, long chunkSize) {
        log.debug("上传分块: sessionId={}, chunkIndex={}, size={}", sessionId, chunkIndex, chunkSize);

        UploadSession session = uploadSessions.get(sessionId);
        if (session == null) {
            throw new RuntimeException("会话不存在: " + sessionId);
        }

        try {
            // S3 分片索引从 1 开始
            int partNumber = chunkIndex + 1;

            software.amazon.awssdk.services.s3.model.UploadPartRequest request =
                    software.amazon.awssdk.services.s3.model.UploadPartRequest.builder()
                            .bucket(getBucketName())
                            .key(session.getRelativePath())
                            .uploadId(session.getUploadId())
                            .partNumber(partNumber)
                            .build();

            software.amazon.awssdk.services.s3.model.UploadPartResponse response =
                    s3Client.uploadPart(request, RequestBody.fromInputStream(inputStream, chunkSize));

            // 记录已上传的分块
            session.getUploadedParts().add(chunkIndex);

            log.info("分块上传成功: sessionId={}, chunkIndex={}, etag={}",
                    sessionId, chunkIndex, response.eTag());
            return true;
        } catch (S3Exception e) {
            log.error("分块上传失败: {}", e.getMessage(), e);
            throw new RuntimeException("分片上传失败: " + e.getMessage());
        }
    }

    /**
     * 获取已上传的分块索引
     */
    public int[] getUploadedChunks(String sessionId) {
        log.debug("获取已上传分块: sessionId={}", sessionId);

        UploadSession session = uploadSessions.get(sessionId);
        if (session == null) {
            throw new RuntimeException("会话不存在: " + sessionId);
        }

        // 尝试从 S3 获取已上传的分块信息
        try {
            software.amazon.awssdk.services.s3.model.ListPartsRequest request =
                    software.amazon.awssdk.services.s3.model.ListPartsRequest.builder()
                            .bucket(getBucketName())
                            .key(session.getRelativePath())
                            .uploadId(session.getUploadId())
                            .build();

            software.amazon.awssdk.services.s3.model.ListPartsResponse response =
                    s3Client.listParts(request);

            Set<Integer> uploadedChunks = new HashSet<>();
            for (software.amazon.awssdk.services.s3.model.Part part : response.parts()) {
                // S3 分片索引从 1 开始,转换为从 0 开始
                uploadedChunks.add(part.partNumber() - 1);
            }

            // 更新本地缓存
            session.getUploadedParts().clear();
            session.getUploadedParts().addAll(uploadedChunks);

            int[] result = uploadedChunks.stream().mapToInt(Integer::intValue).toArray();
            Arrays.sort(result);
            return result;
        } catch (S3Exception e) {
            log.error("获取已上传分块失败: {}", e.getMessage(), e);
            // 返回本地缓存的分块信息
            int[] result = session.getUploadedParts().stream().mapToInt(Integer::intValue).toArray();
            Arrays.sort(result);
            return result;
        }
    }

    /**
     * 合并分块
     */
    public boolean mergeChunks(String sessionId) {
        log.debug("合并分块: sessionId={}", sessionId);

        UploadSession session = uploadSessions.get(sessionId);
        if (session == null) {
            throw new RuntimeException("会话不存在: " + sessionId);
        }

        try {
            // 获取所有已上传的分块
            int[] uploadedChunks = getUploadedChunks(sessionId);

            // 构建已上传分块列表
            List<software.amazon.awssdk.services.s3.model.CompletedPart> completedParts = new ArrayList<>();
            for (int chunkIndex : uploadedChunks) {
                // 需要获取每个分块的 ETag
                completedParts.add(software.amazon.awssdk.services.s3.model.CompletedPart.builder()
                        .partNumber(chunkIndex + 1)  // S3 分片索引从 1 开始
                        .eTag("etag-" + chunkIndex)  // 这里简化处理,实际应该从 listParts 获取
                        .build());
            }

            // 完成分片上传
            software.amazon.awssdk.services.s3.model.CompleteMultipartUploadRequest request =
                    software.amazon.awssdk.services.s3.model.CompleteMultipartUploadRequest.builder()
                            .bucket(getBucketName())
                            .key(session.getRelativePath())
                            .uploadId(session.getUploadId())
                            .multipartUpload(software.amazon.awssdk.services.s3.model.CompletedMultipartUpload.builder()
                                    .parts(completedParts)
                                    .build())
                            .build();

            s3Client.completeMultipartUpload(request);

            // 清理会话
            uploadSessions.remove(sessionId);

            log.info("分块合并成功: sessionId={}, path={}", sessionId, session.getRelativePath());
            return true;
        } catch (S3Exception e) {
            log.error("分块合并失败: {}", e.getMessage(), e);
            throw new RuntimeException("分块合并失败: " + e.getMessage());
        }
    }

    /**
     * 分片上传会话信息
     */
    private static class UploadSession {
        private String uploadId;
        private String relativePath;
        private long totalSize;
        private int chunkCount;
        private Set<Integer> uploadedParts;

        public String getUploadId() {
            return uploadId;
        }

        public void setUploadId(String uploadId) {
            this.uploadId = uploadId;
        }

        public String getRelativePath() {
            return relativePath;
        }

        public void setRelativePath(String relativePath) {
            this.relativePath = relativePath;
        }

        public long getTotalSize() {
            return totalSize;
        }

        public void setTotalSize(long totalSize) {
            this.totalSize = totalSize;
        }

        public int getChunkCount() {
            return chunkCount;
        }

        public void setChunkCount(int chunkCount) {
            this.chunkCount = chunkCount;
        }

        public Set<Integer> getUploadedParts() {
            return uploadedParts;
        }

        public void setUploadedParts(Set<Integer> uploadedParts) {
            this.uploadedParts = uploadedParts;
        }
    }
}

8.3 存储工厂类

创建 storage/FileStorageFactory.java:

package com.knowledge.base.file.storage;

import com.knowledge.base.common.exception.BusinessException;
import com.knowledge.base.file.config.FileStorageProperties;
import jakarta.annotation.PostConstruct;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.context.ApplicationContext;
import org.springframework.stereotype.Component;

/**
 * 文件存储工厂
 *
 * <p>根据配置动态选择文件存储实现</p>
 *
 * @author 苏三
 * @since 1.0.0
 */
@Slf4j
@Component
@RequiredArgsConstructor
public class FileStorageFactory {

    private final ApplicationContext applicationContext;
    private final FileStorageProperties storageProperties;

    private FileStorage currentStorage;

    @PostConstruct
    public void init() {
        StorageType storageType = StorageType.fromCode(storageProperties.getType());
        log.info("初始化文件存储: type={}", storageType);

        try {
            currentStorage = applicationContext.getBean(storageType.getBeanName(), FileStorage.class);
            log.info("文件存储初始化成功: type={}, implementation={}",
                    storageType, currentStorage.getClass().getSimpleName());
        } catch (Exception e) {
            log.error("文件存储初始化失败: {}", e.getMessage(), e);
            throw new RuntimeException("文件存储初始化失败", e);
        }
    }

    /**
     * 获取当前存储实现
     *
     * @return 文件存储实现
     */
    public FileStorage getStorage() {
        if (currentStorage == null) {
            throw new BusinessException("文件存储服务未初始化");
        }
        return currentStorage;
    }

    /**
     * 获取当前存储类型
     *
     * @return 存储类型
     */
    public String getStorageType() {
        return storageProperties.getType();
    }
}

九、服务层实现

9.1 文件服务接口

创建 service/FileService.java:

package com.knowledge.base.file.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.knowledge.base.common.result.PageResult;
import com.knowledge.base.file.dto.FileQueryDTO;
import com.knowledge.base.file.dto.FileUploadDTO;
import com.knowledge.base.file.entity.FileInfo;
import com.knowledge.base.file.vo.FileInfoVO;
import org.springframework.web.multipart.MultipartFile;

import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;

/**
 * 文件Service接口
 *
 * @author 苏三
 * @since 1.0.0
 */
public interface FileService extends IService<FileInfo> {

    /**
     * 上传文件
     *
     * @param file 文件
     * @param dto  上传参数
     * @return 文件信息
     */
    FileInfoVO uploadFile(MultipartFile file, FileUploadDTO dto);

    /**
     * 批量上传文件
     *
     * @param files 文件列表
     * @param dto   上传参数
     * @return 文件信息列表
     */
    java.util.List<FileInfoVO> uploadFiles(MultipartFile[] files, FileUploadDTO dto);

    /**
     * 下载文件
     *
     * @param fileId     文件ID
     * @param response   HTTP响应
     */
    void downloadFile(Long fileId, HttpServletResponse response) throws IOException;

    /**
     * 删除文件
     *
     * @param fileId 文件ID
     * @return 是否成功
     */
    Boolean deleteFile(Long fileId);

    /**
     * 批量删除文件
     *
     * @param fileIds 文件ID列表
     * @return 是否成功
     */
    Boolean batchDeleteFiles(java.util.List<Long> fileIds);

    /**
     * 获取文件详情
     *
     * @param fileId 文件ID
     * @return 文件信息
     */
    FileInfoVO getFileInfo(Long fileId);

    /**
     * 分页查询文件
     *
     * @param dto 查询参数
     * @return 分页结果
     */
    PageResult<FileInfoVO> pageFiles(FileQueryDTO dto);

    /**
     * 获取文件预览URL
     *
     * @param fileId 文件ID
     * @return 预览URL
     */
    String getPreviewUrl(Long fileId);

    /**
     * 预览文件(直接返回文件内容)
     *
     * @param fileId 文件ID
     * @param response HTTP响应
     */
    void previewFile(Long fileId, HttpServletResponse response) throws IOException;
}

9.2 文件服务实现

创建 service/impl/FileServiceImpl.java:

package com.knowledge.base.file.service.impl;

import cn.hutool.core.io.FileUtil;
import cn.hutool.crypto.digest.DigestUtil;
import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
import com.knowledge.base.common.exception.BusinessException;
import com.knowledge.base.common.result.PageResult;
import com.knowledge.base.common.utils.SnowflakeIdGenerator;
import com.knowledge.base.file.config.FileStorageProperties;
import com.knowledge.base.file.dto.FileQueryDTO;
import com.knowledge.base.file.dto.FileUploadDTO;
import com.knowledge.base.file.entity.FileInfo;
import com.knowledge.base.file.mapper.FileMapper;
import com.knowledge.base.file.service.FileService;
import com.knowledge.base.file.storage.FileStorage;
import com.knowledge.base.file.storage.FileStorageFactory;
import com.knowledge.base.file.storage.RustFileStorage;
import com.knowledge.base.file.vo.FileInfoVO;
import jakarta.annotation.Resource;
import jakarta.servlet.http.HttpServletResponse;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import org.springframework.util.StringUtils;
import org.springframework.web.multipart.MultipartFile;

import java.io.*;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.*;
import java.util.stream.Collectors;

/**
 * 文件Service实现类
 *
 * <p>按照阿里巴巴Java开发规范设计,实现文件相关业务逻辑</p>
 * <p>支持多种存储后端,具备秒传、断点续传能力</p>
 *
 * @author 苏三
 * @since 1.0.0
 */
@Slf4j
@Service
@RequiredArgsConstructor
public class FileServiceImpl extends ServiceImpl<FileMapper, FileInfo> implements FileService {

    @Resource
    private FileMapper fileMapper;

    private final FileStorageFactory storageFactory;
    private final FileStorageProperties storageProperties;

    /**
     * 上传文件
     */
    @Override
    @Transactional(rollbackFor = Exception.class)
    public FileInfoVO uploadFile(MultipartFile file, FileUploadDTO dto) {
        log.info("开始上传文件:originalName={}, size={}, contentType={}",
                file.getOriginalFilename(), file.getSize(), file.getContentType());

        // 1. 验证文件
        validateFile(file);

        String fileHash;
        try {
            // 2. 计算文件哈希(用于秒传)
            fileHash = storageProperties.getUpload().isCalculateHash()
                    ? calculateFileHash(file.getInputStream())
                    : UUID.randomUUID().toString();

            // 3. 检查文件是否已存在(秒传)
            if (storageProperties.getUpload().isEnableFastUpload()) {
                FileInfo existFile = fileMapper.selectOne(
                        new LambdaQueryWrapper<FileInfo>()
                                .eq(FileInfo::getFileHash, fileHash)
                                .eq(FileInfo::getStatus, 1)
                );

                if (existFile != null) {
                    log.info("文件已存在,使用秒传:fileId={}, hash={}", existFile.getId(), fileHash);
                    return convertToVO(existFile);
                }
            }

            // 4. 生成存储路径
            String relativePath = generateRelativePath(fileHash, file.getOriginalFilename());

            // 5. 上传文件到存储后端
            FileStorage storage = storageFactory.getStorage();
            try (InputStream inputStream = file.getInputStream()) {
                boolean uploadSuccess = storage.upload(inputStream, relativePath, file.getSize());
                if (!uploadSuccess) {
                    throw new BusinessException("文件上传失败");
                }
            }

            // 6. 检测文件类型
            String fileType = detectFileType(FileUtil.extName(file.getOriginalFilename()), file.getContentType());

            // 7. 构建文件信息实体
            FileInfo fileInfo = buildFileInfo(file, fileHash, relativePath, fileType, dto);

            // 8. 保存文件信息到数据库
            int count = fileMapper.insert(fileInfo);
            if (count <= 0) {
                // 回滚:删除已上传的文件
                storage.delete(relativePath);
                throw new BusinessException("保存文件信息失败");
            }

            log.info("文件上传成功:id={}, originalName={}, path={}",
                    fileInfo.getId(), file.getOriginalFilename(), relativePath);

            return convertToVO(fileInfo);
        } catch (BusinessException e) {
            throw e;
        } catch (Exception e) {
            log.error("文件上传失败:originalName={}", file.getOriginalFilename(), e);
            throw new BusinessException("文件上传失败:" + e.getMessage());
        }
    }

    /**
     * 批量上传文件
     */
    @Override
    @Transactional(rollbackFor = Exception.class)
    public List<FileInfoVO> uploadFiles(MultipartFile[] files, FileUploadDTO dto) {
        List<FileInfoVO> results = new ArrayList<>();

        for (MultipartFile file : files) {
            try {
                FileInfoVO fileInfo = uploadFile(file, dto);
                results.add(fileInfo);
            } catch (Exception e) {
                log.error("批量上传中的单个文件上传失败: {}", file.getOriginalFilename(), e);
                // 创建错误信息
                FileInfoVO errorInfo = new FileInfoVO();
                errorInfo.setOriginalName(file.getOriginalFilename());
                errorInfo.setFileType("ERROR");
                results.add(errorInfo);
            }
        }

        return results;
    }

    /**
     * 下载文件
     */
    @Override
    public void downloadFile(Long fileId, HttpServletResponse response) throws IOException {
        log.info("下载文件: fileId={}", fileId);

        FileInfo fileInfo = getById(fileId);
        if (fileInfo == null) {
            throw new BusinessException("文件不存在");
        }

        if (fileInfo.getStatus() == 0) {
            throw new BusinessException("文件已被删除");
        }

        // 获取存储实现
        FileStorage storage = storageFactory.getStorage();

        // 检查文件是否存在
        if (!storage.exists(fileInfo.getFilePath())) {
            throw new BusinessException("文件不存在");
        }

        // 设置响应头
        response.setContentType(fileInfo.getMimeType());
        response.setHeader("Content-Length", String.valueOf(fileInfo.getFileSize()));
        response.setHeader("Content-Disposition", "attachment; filename=\"" +
                URLEncoder.encode(fileInfo.getOriginalName(), StandardCharsets.UTF_8) + "\"");

        // 流式传输文件
        try (var outputStream = response.getOutputStream()) {
            storage.download(fileInfo.getFilePath(), outputStream);
        }

        // 更新下载次数
        fileInfo.setDownloadCount(fileInfo.getDownloadCount() + 1);
        updateById(fileInfo);

        log.info("文件下载成功: fileId={}, fileName={}", fileId, fileInfo.getOriginalName());
    }

    /**
     * 删除文件
     */
    @Override
    @Transactional(rollbackFor = Exception.class)
    public Boolean deleteFile(Long fileId) {
        log.info("删除文件: fileId={}", fileId);

        FileInfo fileInfo = getById(fileId);
        if (fileInfo == null) {
            throw new BusinessException("文件不存在");
        }

        // 从存储系统删除文件
        FileStorage storage = storageFactory.getStorage();
        storage.delete(fileInfo.getFilePath());

        // 从数据库删除记录(逻辑删除)
        boolean result = removeById(fileId);

        log.info("文件删除成功: fileId={}", fileId);
        return result;
    }

    /**
     * 批量删除文件
     */
    @Override
    @Transactional(rollbackFor = Exception.class)
    public Boolean batchDeleteFiles(List<Long> fileIds) {
        log.info("批量删除文件: fileIds={}", fileIds);

        boolean allSuccess = true;
        for (Long fileId : fileIds) {
            try {
                deleteFile(fileId);
            } catch (Exception e) {
                log.error("删除文件失败: fileId={}", fileId, e);
                allSuccess = false;
            }
        }

        return allSuccess;
    }

    /**
     * 获取文件详情
     */
    @Override
    public FileInfoVO getFileInfo(Long fileId) {
        FileInfo fileInfo = getById(fileId);
        if (fileInfo == null) {
            throw new BusinessException("文件不存在");
        }
        return convertToVO(fileInfo);
    }

    /**
     * 分页查询文件
     */
    @Override
    public PageResult<FileInfoVO> pageFiles(FileQueryDTO dto) {
        LambdaQueryWrapper<FileInfo> queryWrapper = new LambdaQueryWrapper<>();

        if (StringUtils.hasText(dto.getFileType())) {
            queryWrapper.eq(FileInfo::getFileType, dto.getFileType());
        }
        if (dto.getUploaderId() != null) {
            queryWrapper.eq(FileInfo::getUploaderId, dto.getUploaderId());
        }
        if (StringUtils.hasText(dto.getStorageType())) {
            queryWrapper.eq(FileInfo::getStorageType, dto.getStorageType());
        }
        if (StringUtils.hasText(dto.getKeyword())) {
            queryWrapper.like(FileInfo::getOriginalName, dto.getKeyword());
        }

        queryWrapper.orderByDesc(FileInfo::getCreateTime);

        IPage<FileInfo> page = new Page<>(dto.getPageNum(), dto.getPageSize());
        IPage<FileInfo> result = page(page, queryWrapper);

        List<FileInfoVO> voList = result.getRecords().stream()
                .map(this::convertToVO)
                .toList();

        return PageResult.of(result.getTotal(), voList);
    }

    /**
     * 获取文件预览URL
     */
    @Override
    public String getPreviewUrl(Long fileId) {
        FileInfo fileInfo = getById(fileId);
        if (fileInfo == null) {
            throw new BusinessException("文件不存在");
        }

        return storageProperties.getUrl().getPreviewPrefix() + "/" + fileId;
    }

    /**
     * 预览文件(直接返回文件内容)
     */
    @Override
    public void previewFile(Long fileId, HttpServletResponse response) throws IOException {
        log.info("预览文件: fileId={}", fileId);

        FileInfo fileInfo = getById(fileId);
        if (fileInfo == null) {
            throw new BusinessException("文件不存在");
        }

        if (fileInfo.getStatus() == 0) {
            throw new BusinessException("文件已被删除");
        }

        // 获取存储实现
        FileStorage storage = storageFactory.getStorage();

        // 检查文件是否存在
        if (!storage.exists(fileInfo.getFilePath())) {
            throw new BusinessException("文件不存在");
        }

        // 设置响应头(用于预览,不是下载)
        response.setContentType(fileInfo.getMimeType());
        response.setHeader("Content-Length", String.valueOf(fileInfo.getFileSize()));
        response.setHeader("Cache-Control", "max-age=31536000, public"); // 缓存1年
        response.setHeader("Pragma", "public");

        // 对于图片文件,不设置Content-Disposition为attachment,而是inline
        if ("IMAGE".equals(fileInfo.getFileType())) {
            response.setHeader("Content-Disposition", "inline");
        } else {
            // 其他文件类型可能需要下载
            String encodedFileName = URLEncoder.encode(fileInfo.getOriginalName(), StandardCharsets.UTF_8)
                    .replace("+", "%20");
            response.setHeader("Content-Disposition", "inline; filename=\"" + encodedFileName + "\"");
        }

        // 流式传输文件
        try (OutputStream outputStream = response.getOutputStream()) {
            storage.download(fileInfo.getFilePath(), outputStream);
        }

        log.info("文件预览成功: fileId={}, fileName={}", fileId, fileInfo.getOriginalName());
    }

    // ==================== 私有方法 ====================

    /**
     * 校验文件
     */
    private void validateFile(MultipartFile file) {
        if (file == null || file.isEmpty()) {
            throw new BusinessException("文件不能为空");
        }

        // 检查文件大小
        long maxSize = storageProperties.getUpload().getMaxSize();
        if (file.getSize() > maxSize) {
            throw new BusinessException("文件大小超过限制: " + maxSize + " 字节");
        }

        // 检查文件类型
        String extension = getFileExtension(file.getOriginalFilename());
        List<String> allowedTypes = storageProperties.getUpload().getAllowedTypes();
        if (!allowedTypes.contains("*") && !allowedTypes.contains(extension.toLowerCase())) {
            throw new BusinessException("不支持的文件类型: " + extension);
        }
    }

    /**
     * 计算文件哈希
     */
    private String calculateFileHash(InputStream inputStream) {
        try {
            return DigestUtil.sha256Hex(inputStream);
        } catch (Exception e) {
            log.error("计算文件哈希失败:{}", e.getMessage());
            throw new BusinessException("计算文件哈希失败");
        }
    }

    /**
     * 生成相对存储路径
     */
    private String generateRelativePath(String fileHash, String originalFilename) {
        String datePath = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyy/MM/dd"));
        String hashPrefix = fileHash.substring(0, 2);
        String extension = getFileExtension(originalFilename);
        String storedName = fileHash + (StringUtils.hasText(extension) ? "." + extension : "");

        return datePath + "/" + hashPrefix + "/" + storedName;
    }

    /**
     * 构建文件信息实体
     */
    private FileInfo buildFileInfo(MultipartFile file, String fileHash, String relativePath,
                                    String fileType, FileUploadDTO dto) {
        FileInfo fileInfo = new FileInfo();
        fileInfo.setId(SnowflakeIdGenerator.getInstance().nextId());
        fileInfo.setOriginalName(file.getOriginalFilename());
        fileInfo.setStoredName(relativePath.substring(relativePath.lastIndexOf("/") + 1));
        fileInfo.setFilePath(relativePath);
        fileInfo.setFileSize(file.getSize());
        fileInfo.setFileType(fileType);
        fileInfo.setMimeType(file.getContentType());
        fileInfo.setFileHash(fileHash);
        fileInfo.setStorageType(storageFactory.getStorageType().toUpperCase());
        fileInfo.setUploaderId(dto.getUploaderId() != null ? dto.getUploaderId() : 1L);
        fileInfo.setAccessLevel(dto.getAccessLevel() != null ? dto.getAccessLevel() : 0);
        fileInfo.setDownloadCount(0);
        fileInfo.setStatus(1);
        fileInfo.setCreateTime(LocalDateTime.now());
        fileInfo.setUpdateTime(LocalDateTime.now());

        return fileInfo;
    }

    /**
     * 检测文件类型
     */
    private String detectFileType(String extension, String mimeType) {
        if (extension == null) {
            return "OTHER";
        }

        return switch (extension.toLowerCase()) {
            case "pdf", "doc", "docx", "xls", "xlsx", "ppt", "pptx", "txt", "md" -> "DOCUMENT";
            case "png", "jpg", "jpeg", "gif", "bmp", "svg" -> "IMAGE";
            case "mp4", "avi", "mov", "wmv" -> "VIDEO";
            case "mp3", "wav", "flac" -> "AUDIO";
            default -> "OTHER";
        };
    }

    /**
     * 格式化文件大小
     */
    private String formatFileSize(long fileSize) {
        if (fileSize < 1024) {
            return fileSize + " B";
        } else if (fileSize < 1024 * 1024) {
            return String.format("%.2f KB", fileSize / 1024.0);
        } else if (fileSize < 1024 * 1024 * 1024) {
            return String.format("%.2f MB", fileSize / (1024.0 * 1024));
        } else {
            return String.format("%.2f GB", fileSize / (1024.0 * 1024 * 1024));
        }
    }

    /**
     * 转换为VO
     */
    private FileInfoVO convertToVO(FileInfo fileInfo) {
        // 构建RustFS直接访问URL
        String rustfsDirectUrl = buildRustfsDirectUrl(fileInfo.getFilePath());

        return FileInfoVO.builder()
                .id(fileInfo.getId())
                .originalName(fileInfo.getOriginalName())
                .fileSize(fileInfo.getFileSize())
                .fileSizeReadable(formatFileSize(fileInfo.getFileSize()))
                .fileType(fileInfo.getFileType())
                .mimeType(fileInfo.getMimeType())
                .fileUrl(rustfsDirectUrl)
                .previewUrl(rustfsDirectUrl)
                .uploaderId(fileInfo.getUploaderId())
                .uploaderName(null) // TODO: 查询用户名称
                .accessLevel(fileInfo.getAccessLevel())
                .downloadCount(fileInfo.getDownloadCount())
                .storageType(fileInfo.getStorageType())
                .createdAt(fileInfo.getCreateTime())
                .build();
    }

    /**
     * 构建RustFS直接访问URL
     */
    private String buildRustfsDirectUrl(String filePath) {
        if (filePath == null || filePath.isEmpty()) {
            throw new IllegalArgumentException("文件路径不能为空");
        }

        // 构建RustFS直接访问URL
        String endpoint = storageProperties.getRustfs().getEndpoint();
        int port = storageProperties.getRustfs().getPort();
        String bucketName = storageProperties.getRustfs().getBucketName();
        boolean secure = storageProperties.getRustfs().isSecure();

        String protocol = secure ? "https" : "http";
        String normalizedPath = filePath.startsWith("/") ? filePath.substring(1) : filePath;

        return String.format("%s://%s:%d/%s/%s", protocol, endpoint, port, bucketName, normalizedPath);
    }
}

十、控制器层

10.1 文件控制器

创建 controller/FileController.java:

package com.knowledge.base.file.controller;

import com.knowledge.base.common.result.PageResult;
import com.knowledge.base.common.result.Result;
import com.knowledge.base.file.dto.FileQueryDTO;
import com.knowledge.base.file.dto.FileUploadDTO;
import com.knowledge.base.file.entity.FileInfo;
import com.knowledge.base.file.service.FileService;
import com.knowledge.base.file.vo.FileInfoVO;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.servlet.http.HttpServletResponse;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;

import java.io.IOException;
import java.util.List;

/**
 * 文件管理控制器
 *
 * @author 苏三
 * @since 1.0.0
 */
@Slf4j
@RestController
@RequestMapping("/files")
@Tag(name = "文件管理", description = "文件上传、下载、预览接口")
public class FileController {

    @Autowired
    private FileService fileService;

    /**
     * 上传单个文件
     */
    @PostMapping("/upload")
    @Operation(summary = "上传单个文件", description = "支持图片、文档等多种文件格式上传")
    public Result<FileInfoVO> uploadFile(
            @Parameter(description = "文件") @RequestParam("file") MultipartFile file,
            @Parameter(description = "上传者ID") @RequestParam(value = "uploaderId", defaultValue = "1") Long uploaderId,
            @Parameter(description = "访问级别") @RequestParam(value = "accessLevel", defaultValue = "0") Integer accessLevel,
            @Parameter(description = "存储类型") @RequestParam(value = "storageType", defaultValue = "rustfs") String storageType) {

        FileUploadDTO dto = new FileUploadDTO();
        dto.setUploaderId(uploaderId);
        dto.setAccessLevel(accessLevel);
        dto.setStorageType(storageType);

        FileInfoVO fileInfo = fileService.uploadFile(file, dto);
        return Result.success(fileInfo);
    }

    /**
     * 批量上传文件
     */
    @PostMapping("/batch-upload")
    @Operation(summary = "批量上传文件", description = "一次上传多个文件")
    public Result<List<FileInfoVO>> uploadFiles(
            @Parameter(description = "文件列表") @RequestParam("files") MultipartFile[] files,
            @Parameter(description = "上传者ID") @RequestParam(value = "uploaderId", defaultValue = "1") Long uploaderId) {

        FileUploadDTO dto = new FileUploadDTO();
        dto.setUploaderId(uploaderId);
        dto.setAccessLevel(0);
        dto.setStorageType("rustfs");

        List<FileInfoVO> fileInfos = fileService.uploadFiles(files, dto);
        return Result.success(fileInfos);
    }

    /**
     * 下载文件
     */
    @GetMapping("/download/{fileId}/**")
    @Operation(summary = "下载文件", description = "根据文件ID下载文件")
    public void downloadFile(
            @PathVariable String fileId,
            HttpServletResponse response) throws IOException {
        // 从fileId中提取真实的文件ID(去除扩展名)
        Long realFileId = extractFileId(fileId);
        fileService.downloadFile(realFileId, response);
    }

    /**
     * 获取文件预览URL
     */
    @GetMapping("/preview/{fileId}")
    @Operation(summary = "获取文件预览URL", description = "获取文件预览URL")
    public Result<String> getPreviewUrl(@PathVariable String fileId) {
        // 从fileId中提取真实的文件ID(去除扩展名)
        Long realFileId = extractFileId(fileId);
        String previewUrl = fileService.getPreviewUrl(realFileId);
        return Result.success(previewUrl);
    }

    /**
     * 预览文件(直接返回文件内容)
     */
    @GetMapping("/preview/{fileId}/**")
    @Operation(summary = "预览文件", description = "预览指定文件内容")
    public void previewFile(
            @PathVariable String fileId,
            HttpServletResponse response) throws IOException {
        // 从fileId中提取真实的文件ID(去除扩展名)
        Long realFileId = extractFileId(fileId);
        fileService.previewFile(realFileId, response);
    }

    /**
     * 获取文件详情
     */
    @GetMapping("/{fileId}")
    @Operation(summary = "获取文件详情", description = "根据文件ID获取文件详细信息")
    public Result<FileInfoVO> getFileInfo(@PathVariable Long fileId) {
        FileInfoVO fileInfo = fileService.getFileInfo(fileId);
        return Result.success(fileInfo);
    }

    /**
     * 分页查询文件列表
     */
    @PostMapping("/page")
    @Operation(summary = "分页查询文件列表", description = "支持按类型、上传者等条件查询")
    public Result<PageResult<FileInfoVO>> pageFiles(@RequestBody FileQueryDTO dto) {
        PageResult<FileInfoVO> result = fileService.pageFiles(dto);
        return Result.success(result);
    }

    /**
     * 删除文件
     */
    @DeleteMapping("/{fileId}")
    @Operation(summary = "删除文件", description = "根据文件ID删除文件")
    public Result<Boolean> deleteFile(@PathVariable Long fileId) {
        Boolean result = fileService.deleteFile(fileId);
        return Result.success(result);
    }

    /**
     * 批量删除文件
     */
    @DeleteMapping("/batch")
    @Operation(summary = "批量删除文件", description = "批量删除多个文件")
    public Result<Boolean> batchDeleteFiles(@RequestBody List<Long> fileIds) {
        Boolean result = fileService.batchDeleteFiles(fileIds);
        return Result.success(result);
    }

    /**
     * 从文件ID中提取真实的文件ID(去除扩展名)
     */
    private Long extractFileId(String fileId) {
        if (fileId == null || fileId.isEmpty()) {
            throw new IllegalArgumentException("文件ID不能为空");
        }

        // 查找第一个点号,提取点号之前的部分作为真实的文件ID
        int dotIndex = fileId.indexOf('.');
        String realIdStr = dotIndex > 0 ? fileId.substring(0, dotIndex) : fileId;

        try {
            return Long.parseLong(realIdStr);
        } catch (NumberFormatException e) {
            throw new IllegalArgumentException("无效的文件ID格式: " + fileId);
        }
    }
}

十一、配置类

11.1 文件存储配置类

创建 config/FileStorageConfig.java:

package com.knowledge.base.file.config;

import jakarta.annotation.PostConstruct;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Configuration;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;

/**
 * 文件存储配置类
 *
 * <p>配置本地文件存储服务</p>
 *
 * @author 苏三
 * @since 1.0.0
 */
@Slf4j
@Configuration
public class FileStorageConfig {

    @Value("${file.upload.path:/tmp/knowledge-base/uploads}")
    private String uploadPath;

    /**
     * 初始化时创建上传目录
     */
    @PostConstruct
    public void init() {
        try {
            Path path = Paths.get(uploadPath);
            if (!Files.exists(path)) {
                Files.createDirectories(path);
                log.info("创建文件上传目录: {}", path.toAbsolutePath());
            }
        } catch (IOException e) {
            log.error("创建文件上传目录失败: {}", e.getMessage(), e);
            throw new RuntimeException("无法创建文件上传目录", e);
        }
    }
}

11.2 文件存储属性配置

创建 config/FileStorageProperties.java:

package com.knowledge.base.file.config;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

import java.util.Arrays;
import java.util.List;

/**
 * 文件存储配置属性类
 *
 * @author knowledge-base-team
 * @since 1.0.0
 */
@Data
@Component
@ConfigurationProperties(prefix = "file.storage")
public class FileStorageProperties {

    /**
     * 存储类型: rustfs
     */
    private String type = "rustfs";

    /**
     * RustFS分布式存储配置
     */
    private Rustfs rustfs = new Rustfs();

    /**
     * 上传限制配置
     */
    private Upload upload = new Upload();

    /**
     * URL配置
     */
    private Url url = new Url();

    @Data
    public static class Rustfs {
        /**
         * RustFS服务端点地址
         */
        private String endpoint = "117.72.88.11";

        /**
         * 服务端口
         */
        private int port = 9091;

        /**
         * 访问密钥ID
         */
        private String accessKey = "IPL4GZeFumv8g9ANj3b7";

        /**
         * 秘密访问密钥
         */
        private String secretKey = "IFil9yzO520VLE8f7qoXHgBNkUG4TmWvDrSc1ReQ";

        /**
         * 是否使用HTTPS
         */
        private boolean secure = false;

        /**
         * 默认存储桶名称
         */
        private String bucketName = "mall-dev";

        /**
         * 连接超时时间(毫秒)
         */
        private int connectTimeout = 30000;

        /**
         * 读取超时时间(毫秒)
         */
        private int readTimeout = 60000;

        /**
         * 写入超时时间(毫秒)
         */
        private int writeTimeout = 60000;

        /**
         * 最大连接数
         */
        private int maxConnections = 50;

        /**
         * 是否启用RustFS
         */
        private boolean enabled = true;
    }

    @Data
    public static class Upload {
        /**
         * 最大文件大小(字节),默认50MB
         */
        private long maxSize = 52428800;

        /**
         * 允许的文件类型
         */
        private List<String> allowedTypes = Arrays.asList(
                "pdf", "doc", "docx", "xls", "xlsx", "ppt", "pptx",
                "txt", "md", "png", "jpg", "jpeg", "gif", "bmp", "svg"
        );

        /**
         * 是否启用秒传
         */
        private boolean enableFastUpload = true;

        /**
         * 是否计算文件哈希
         */
        private boolean calculateHash = true;

        /**
         * 是否启用断点续传
         */
        private boolean enableResumableUpload = true;
    }

    @Data
    public static class Url {
        /**
         * 文件访问URL前缀
         */
        private String prefix = "http://localhost:8084/file";

        /**
         * 预览URL前缀
         */
        private String previewPrefix = "http://localhost:8084/file/preview";
    }
}

11.2 S3客户端配置

创建 config/RustFsS3Config.java:

package com.knowledge.base.file.config;

import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.S3Configuration;

import java.net.URI;
import java.time.Duration;

/**
 * RustFS S3客户端配置
 *
 * @author knowledge-base-team
 * @since 1.0.0
 */
@Configuration
@ConditionalOnProperty(name = "file.storage.type", havingValue = "rustfs")
public class RustFsS3Config {

    /**
     * 创建S3客户端连接RustFS
     */
    @Bean
    public S3Client s3Client(FileStorageProperties properties) {
        return S3Client.builder()
                .endpointOverride(URI.create(String.format("http://%s:%d",
                        properties.getRustfs().getEndpoint(),
                        properties.getRustfs().getPort())))
                .credentialsProvider(StaticCredentialsProvider.create(
                        AwsBasicCredentials.create(
                                properties.getRustfs().getAccessKey(),
                                properties.getRustfs().getSecretKey())))
                .region(Region.of("us-east-1"))
                .serviceConfiguration(S3Configuration.builder()
                        .checksumValidationEnabled(false)
                        .chunkedEncodingEnabled(false)
                        .build())
                .build();
    }
}

11.3 安全配置

创建 config/SecurityConfig.java:

package com.knowledge.base.file.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.web.SecurityFilterChain;

/**
 * 文件服务安全配置
 *
 * @author 苏三
 * @since 1.0.0
 */
@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig {

    /**
     * 配置安全过滤链
     */
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
                // 禁用CSRF保护(文件上传不需要)
                .csrf(AbstractHttpConfigurer::disable)

                // 配置无状态会话
                .sessionManagement(session -> session
                        .sessionCreationPolicy(SessionCreationPolicy.STATELESS))

                // 禁用CORS(由网关统一处理)
                .cors(AbstractHttpConfigurer::disable)

                // 所有请求都允许访问(认证由网关统一处理)
                .authorizeHttpRequests(auth -> auth
                        // 健康检查和监控:完全开放
                        .requestMatchers("/actuator/**").permitAll()

                        // API文档:完全开放(开发环境)
                        .requestMatchers("/doc.html", "/swagger-resources/**",
                                "/v3/api-docs/**", "/webjars/**", "/swagger-ui/**").permitAll()

                        // 文件上传和下载接口:完全开放(由网关控制访问权限)
                        .requestMatchers("/files/**").permitAll()

                        // 其他所有请求:允许访问(由网关统一处理认证)
                        .anyRequest().permitAll()
                );

        return http.build();
    }
}

十二、启动类

创建启动类 FileApplication.java:

package com.knowledge.base.file;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * 文件服务启动类
 *
 * @author 苏三
 * @since 1.0.0
 */
@SpringBootApplication(scanBasePackages = {"com.knowledge.base.file", "com.knowledge.base.common"})
public class FileApplication {

    public static void main(String[] args) {
        SpringApplication.run(FileApplication.class, args);
    }
}

十三、功能测试

13.1 启动服务

# 进入kb-file目录
cd kb-file

# 启动服务
mvn spring-boot:run

13.2 访问API文档

启动成功后,访问Knife4j文档:http://localhost:8084/doc.html

13.3 测试文件上传

使用Postman或curl测试文件上传:

# 上传图片
curl -X POST "http://localhost:8084/files/upload" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/image.png" \
  -F "uploaderId=1" \
  -F "accessLevel=0" \
  -F "storageType=rustfs"

13.4 验证返回数据

上传成功后,接口会返回:

{
    "code": 200,
    "message": "操作成功",
    "data": {
        "id": 315091148181999616,
        "originalName": "image.png",
        "fileSize": 50214,
        "fileSizeReadable": "49.04 KB",
        "fileType": "IMAGE",
        "mimeType": "image/png",
        "fileUrl": "http://117.72.88.11:9091/mall-dev/2026/05/19/ab/abc123...png",
        "previewUrl": "http://117.72.88.11:9091/mall-dev/2026/05/19/ab/abc123...png",
        "uploaderId": 1,
        "accessLevel": 0,
        "downloadCount": 0,
        "storageType": "RUSTFS",
        "createdAt": "2026-05-19T19:39:43"
    }
}

总结

本文详细介绍了如何从零开始搭建文件服务模块,实现完整的图片上传功能。

通过本教程,你可以:
实现完整的文件上传下载功能

文件服务作为系统的基础设施,为其他模块提供稳定的文件存储能力,是企业应用开发中的重要组成部分。

最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏