SpringBoot 文件上传与阿里云 OSS 集成

一、文件上传基础

1. 简介

文件上传指将本地文件（图片、音视频等）传输至服务器存储，广泛应用于社交、内容发布等场景。

2. 前端表单三要素（必填）

提交方式：method="post"
编码格式：enctype="multipart/form-data"
文件组件：<input type="file">

示例代码

html 复制代码

<form action="/upload" method="post" enctype="multipart/form-data">
    姓名: <input type="text" name="name"><br>
    图像: <input type="file" name="file"><br>
    <input type="submit" value="上传">
</form>

3. SpringBoot 服务端接收

使用 MultipartFile 接收前端上传文件

java 复制代码

@Slf4j
@RestController
public class UploadController {
    @PostMapping("/upload")
    public Result upload(String name, Integer age, MultipartFile file) {
        log.info("接收上传文件：{}", file);
        return Result.success();
    }
}

二、本地上传存储

1. 核心API

getOriginalFilename()：获取文件原始名称
transferTo(File dest)：将文件保存至服务器本地路径

2. 生成唯一文件名（防止覆盖）

借助 UUID 拼接文件后缀

java 复制代码

private String getUniqueFileName(String originalFilename) {
    String uuid = UUID.randomUUID().toString().replace("-", "");
    String suffix = originalFilename.substring(originalFilename.lastIndexOf("."));
    return uuid + suffix;
}

3. 完整上传接口

java 复制代码

@PostMapping("/upload")
public Result upload(MultipartFile file) throws Exception {
    String fileName = getUniqueFileName(file.getOriginalFilename());
    // 保存到指定目录
    file.transferTo(new File("D:/images/" + fileName));
    return Result.success();
}

4. 文件大小限制（application.yml）

yaml 复制代码

spring:
  servlet:
    multipart:
      max-file-size: 10MB    # 单个文件上限
      max-request-size: 100MB # 单次请求总数据上限

三、阿里云 OSS 对象存储

1. 简介

OSS 是阿里云云存储服务，用于存放图片、视频等资源，可通过网络随时访问。

2. 核心概念

Bucket：存储空间，所有文件必须存放在指定 Bucket 中
SDK：官方开发工具包，提供上传、下载等操作能力

3. 开通使用步骤

注册阿里云账号并完成实名认证
开通对象存储 OSS 服务
创建 Bucket 存储空间
获取 AccessKey（密钥）
引入 SDK、编写代码实现上传

4. AccessKey 环境变量配置

临时配置（当前命令行有效）

cmd 复制代码

set OSS_ACCESS_KEY_ID=你的ID
set OSS_ACCESS_KEY_SECRET=你的密钥

永久配置

cmd 复制代码

setx OSS_ACCESS_KEY_ID "你的ID"
setx OSS_ACCESS_KEY_SECRET "你的密钥"

验证

cmd 复制代码

echo %OSS_ACCESS_KEY_ID%
echo %OSS_ACCESS_KEY_SECRET%

四、SpringBoot 集成阿里云 OSS

1. 配置文件（application.yml）

yaml 复制代码

aliyun:
  oss:
    endpoint: https://oss-cn-beijing.aliyuncs.com
    bucketName: java-ai
    region: cn-beijing

2. 配置注入两种方式

方式一：@Value（少量配置）

java 复制代码

@Component
public class AliyunOSSOperator {
    @Value("${aliyun.oss.endpoint}")
    private String endpoint;
    @Value("${aliyun.oss.bucketName}")
    private String bucketName;
}

方式二：@ConfigurationProperties（多配置、推荐）

配置实体类

java 复制代码

@Data
@Component
@ConfigurationProperties(prefix = "aliyun.oss")
public class AliyunOssProperties {
    private String endpoint;
    private String bucketName;
    private String region;
}

工具类注入使用

java 复制代码

@Component
public class AliyunOSSOperator {
    @Autowired
    private AliyunOssProperties ossProperties;

    // 上传方法
    public String upload(byte[] fileBytes, String originalName) throws Exception {
        // 上传逻辑
        return "";
    }
}

3. 上传接口

java 复制代码

@RestController
public class UploadController {
    @Autowired
    private AliyunOSSOperator ossOperator;

    @PostMapping("/upload")
    public Result upload(MultipartFile file) throws Exception {
        String url = ossOperator.upload(file.getBytes(), file.getOriginalFilename());
        return Result.success(url);
    }
}