一、概述
文件服务(kb-file)是知识库系统的核心支撑模块,提供文件存储、上传、下载、预览等功能。
本文将详细介绍如何从零开始搭建文件服务模块,实现完整的图片上传功能。
1.1 服务定位
文件服务作为系统的文件基础设施层,为其他业务模块提供:
| 功能模块 | 说明 | 使用场景 |
|---|---|---|
| 文件上传 | 支持多种文件格式上传 | 文档编辑器插入图片、头像上传等 |
| 文件存储 | 分布式文件存储系统 | 大容量、高可靠文件存储 |
| 文件下载 | 安全的文件下载服务 | 文档附件下载、图片访问 |
| 文件预览 | 在线预览功能 | 图片预览、文档预览 |
| 断点续传 | 大文件分块上传 | 大视频文件上传、断网恢复 |
1.2 技术架构
kb-file
├── 数据持久层:MyBatis Plus + MySQL
├── 缓存层:Redis(文件信息缓存)
├── 存储层:RustFS(分布式文件系统)
├── API文档:Knife4j
├── 服务注册:Nacos
└── 基础设施:Spring Boot 3.21.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/resources3.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 字段说明
| 字段 | 类型 | 说明 | 示例 |
|---|---|---|---|
| id | BIGINT | 文件唯一标识,使用雪花算法生成 | 315091148181999616 |
| original\_name | VARCHAR(255) | 原始文件名 | 截屏2026-05-19.png |
| stored\_name | VARCHAR(255) | 存储文件名(系统生成) | a1b2c3d4e5f6.png |
| file\_path | VARCHAR(500) | 文件在存储系统中的路径 | 2026/05/19/ab/abc123...png |
| file\_size | BIGINT | 文件大小(字节) | 50214 |
| file\_type | VARCHAR(50) | 文件类型分类 | IMAGE |
| mime\_type | VARCHAR(100) | MIME类型 | image/png |
| file\_hash | VARCHAR(64) | 文件SHA256哈希值,用于去重 | a1b2c3d4... |
| storage\_type | VARCHAR(50) | 存储类型 | RUSTFS |
| bucket\_name | VARCHAR(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 <= #{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:run13.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"
}
}总结
本文详细介绍了如何从零开始搭建文件服务模块,实现完整的图片上传功能。
通过本教程,你可以:
实现完整的文件上传下载功能
文件服务作为系统的基础设施,为其他模块提供稳定的文件存储能力,是企业应用开发中的重要组成部分。