文件上传

youlai-boot 提供统一的文件上传服务，支持多种存储方式切换，前端无需关心具体实现。

存储方式

通过 oss.type 配置切换：

存储类型	配置值	说明
本地存储	local	存储在服务器本地文件系统
MinIO	minio	开源对象存储服务
阿里云 OSS	aliyun	阿里云对象存储服务

接口说明

上传接口：

POST /api/v1/files
Content-Type: multipart/form-data

参数	类型	必填	说明
file	File	是	表单文件对象

删除接口：

DELETE /api/v1/files?filePath={url}

参数	类型	必填	说明
filePath	String	是	文件完整 URL

响应结构：

{
  "code": "00000",
  "msg": "成功",
  "data": {
    "name": "原始文件名.png",
    "url": "https://static.xxx.com/upload/20250212/abc123.png"
  }
}

字段	说明
name	原始文件名
url	文件访问地址，前端直接使用

配置说明

本地存储

oss:
  type: local
  local:
    # 文件存储路径
    storage-path: /data/upload

特点：

• 文件存储在服务器本地
• 返回相对路径，前端需拼接访问前缀
• 适用于单机部署、开发测试环境

MinIO

oss:
  type: minio
  minio:
    # 服务地址
    endpoint: http://localhost:9000
    # 访问凭据
    access-key: minioadmin
    # 凭据密钥
    secret-key: minioadmin
    # 存储桶名称
    bucket-name: public
    # 自定义域名（可选）
    custom-domain: https://oss.youlai.tech

配置说明：

配置项	说明
endpoint	MinIO 服务地址
access-key	访问密钥
secret-key	密钥
bucket-name	存储桶名称，不存在时自动创建
custom-domain	自定义域名，未配置时返回 endpoint 格式 URL

存储桶策略：

自动设置存储桶为公开访问策略，无需额外配置。

阿里云 OSS

oss:
  type: aliyun
  aliyun:
    # 服务Endpoint（不含 https://）
    endpoint: oss-cn-hangzhou.aliyuncs.com
    # 访问凭据
    access-key-id: your-access-key-id
    # 凭据密钥
    access-key-secret: your-access-key-secret
    # 存储桶名称
    bucket-name: default

配置说明：

配置项	说明
endpoint	OSS 服务地域节点，如 oss-cn-hangzhou.aliyuncs.com
access-key-id	阿里云 AccessKey ID
access-key-secret	阿里云 AccessKey Secret
bucket-name	存储桶名称

URL 格式：

https://{bucketName}.{endpoint}/{dateFolder}/{uuid}.{suffix}

文件命名规则

所有存储方式统一采用以下命名规则：

{dateFolder}/{uuid}.{suffix}

组成	说明	示例
dateFolder	日期文件夹	20250212
uuid	唯一标识	abc123def456
suffix	文件后缀	png

示例：20250212/abc123def456.png

实现原理

策略模式

基于 FileService 接口，通过 @ConditionalOnProperty 实现存储方式切换：

自动装配

每个实现类通过 @ConfigurationProperties 绑定配置：

@Component
@ConditionalOnProperty(value = "oss.type", havingValue = "minio")
@ConfigurationProperties(prefix = "oss.minio")
public class MinioFileService implements FileService {
    // 配置属性自动注入
}

初始化流程

前端对接

Vue 3 + Element Plus

<template>
  <el-upload
    action="/api/v1/files"
    name="file"
    :headers="{ Authorization: token }"
    :show-file-list="false"
    :on-success="handleUploadSuccess"
  >
    <el-button type="primary">上传文件</el-button>
  </el-upload>
</template>

<script setup lang="ts">
const handleUploadSuccess = (res: any) => {
  if (res.code === '00000') {
    console.log('文件地址：', res.data.url);
  }
};
</script>

统一要求

• 参数名必须为 file
• Header 需携带 Authorization: Bearer {token}
• 只依赖 data.url，不关心存储类型

最佳实践

生产环境推荐：

1. MinIO：自建对象存储，成本低，适合内网环境
2. 阿里云 OSS：云服务，稳定性高，适合公网访问

开发环境推荐：

• 本地存储：快速开发，无需额外依赖
• MinIO：Docker 快速启动，与生产环境一致

安全建议：

1. 存储桶权限按需配置，避免公开访问敏感文件
2. 定期清理无用文件，控制存储成本
3. 配置 HTTPS，保障传输安全

相关文件

文件	说明
file/controller/FileController.java	文件上传控制器
file/service/FileService.java	文件服务接口
file/service/impl/LocalFileService.java	本地存储实现
file/service/impl/MinioFileService.java	MinIO 实现
file/service/impl/AliyunFileService.java	阿里云 OSS 实现
file/model/FileInfo.java	文件信息模型