SpringBoot3.X 整合 MinIO 存储原生方案

 更新时间:2025年07月11日 11:57:46   作者:软件编程在线接单(需要可私)  
本文详细介绍了SpringBoot3.X整合MinIO的原生方案,从环境搭建到核心功能实现,涵盖了文件上传、下载、删除等常用操作,并补充了异常处理、参数校验、安全实践等内容,感兴趣的朋友一起看看吧

SpringBoot3.X整合MinIO存储原生方案:从环境搭建到实战开发

一、前言:为什么选择MinIO?

在分布式存储领域,MinIO作为一款高性能的对象存储服务,凭借兼容S3 API、轻量级部署、支持分布式集群等特性,成为企业级文件存储的热门选择。尤其在SpringBoot生态中,通过原生SDK整合MinIO可以快速实现文件的上传、下载、删除等功能,适用于云存储、大数据场景、内容管理系统等多种业务场景。

本文将基于SpringBoot3.X版本,从零开始构建MinIO文件存储方案,涵盖环境准备、依赖配置、核心功能开发、进阶特性及问题排查,帮助开发者快速掌握原生整合方案。

二、环境准备

1. 基础环境清单

  • JDK 17+(SpringBoot3.X最低要求)
  • Maven 3.6+
  • MinIO服务(本文使用虚拟机部署的MinIO)
  • IDE:IntelliJ IDEA 2024.3

2. MinIO服务部署

如果没有现成的MinIO服务,可通过Docker快速部署本地测试环境:

# 拉取镜像
mkdir -p /minio/data
 chmod 777 /minio/data
 docker run \-d --restart=always \--name minio \--hostname minio-server \
 -p 9000:9000 \-p 9001:9001 \-v /minio/data:/bitnami/minio/data \-e MINIO_ROOT_USER="minio_root" \-e MINIO_ROOT_PASSWORD="minio_123456" \-e MINIO_DEFAULT_BUCKETS="bucket" \-e "MINIO_SERVER_URL=http://192.168.229.128:9000" \
 bitnami/minio:2023.12.7

启动后访问http://192.168.229.128:9001,使用账号(minio_root)密码(minio_123456)登录控制台,创建本文所需的ai-pan桶(Bucket)。

注意ip需要改成自己的,访问页面如下,输入账号密码,点击login

成功进入页面之后,创建我们的Bucket

三、项目初始化与依赖配置

1. 创建SpringBoot项目

通过Spring Initializr创建项目,选择以下依赖:

  • Spring Web(用于接口开发)
  • Lombok(简化实体类代码)

2. 核心依赖引入

pom.xml中添加MinIO SDK依赖(注意版本兼容性,8.3.7兼容SpringBoot3):

<dependency>
  <groupId>io.minio</groupId>
  <artifactId>minio</artifactId>
  <version>8.3.7</version>
</dependency>
<!-- 工具类依赖(非必需,用于文件路径处理) -->
<dependency>
  <groupId>cn.hutool</groupId>
  <artifactId>hutool-all</artifactId>
  <version>5.8.20</version>
</dependency>
<dependency>
			<groupId>org.projectlombok</groupId>
			<artifactId>lombok</artifactId>
			<version>1.18.30</version>
		</dependency>

四、配置详解

1. 核心配置文件(application.yml)

# MinIO核心配置
minio:
  endpoint: http://192.168.229.128:9000 # API访问地址
  access-key: minio_root # 访问密钥
  access-secret: minio_123456 # 密钥密码
  bucket-name: ai-pan # 创建的桶名称

2. MinIO配置类

import io.minio.MinioClient;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Data
@Component
@ConfigurationProperties(prefix = "minio")
public class MinioConfig {
    @Value("endpoint")
    private String endpoint;
    @Value("access-key")
    private String accessKey;
    @Value("access-secret")
    private String accessSecret;
    @Value("bucket-name")
    private String bucketName;
    // 预签名url过期时间(ms)
    private Long PRE_SIGN_URL_EXPIRE = 60 * 10 * 1000L;
    @Bean
    public MinioClient getMinioClient() {
        return MinioClient.builder()
                .endpoint(endpoint)
                .credentials(accessKey, accessSecret)
                .build();
    }
}

五、核心功能开发

1. 工具类:文件路径生成

public class CommonUtil {
   public static String getFilePath(String fileName) {
        String suffix = getFileSuffix(fileName);
        // ⽣成⽂件在存储桶中的唯⼀键
        return StrUtil.format("{}/{}/{}/{}.{}", DateUtil.thisYear(),
                DateUtil.thisMonth() + 1,DateUtil.thisDayOfMonth(), IdUtil.randomUUID(), suffix);
    }
}

2. 控制器(TestController)

@RestController
@RequestMapping("/api/test/v1")
public class TestController {
    @Autowired
    private MinioConfig minioConfig;
    @Autowired
    private MinioClient minioClient;
    @PostMapping("/upload")
    public JsonData upload(@RequestParam("file") MultipartFile file) {
        String filename = CommonUtil.getFilePath(file.getOriginalFilename());
        try {
            InputStream inputStream = file.getInputStream();
            minioClient.putObject(PutObjectArgs.builder()
                    .bucket(minioConfig.getBucketName())
                    .object(filename)
                    .stream(inputStream, file.getSize(), -1)
                    .contentType(file.getContentType())
                    .build());
        } catch (Exception e) {
            e.printStackTrace();
        }
      String url =  minioConfig.getEndpoint() + "/" + minioConfig.getBucketName() +
                "/" + filename;
        return JsonData.buildSuccess(url);
    }
}
// 统一响应类
@Data
public class JsonData {
    private int code;
    private String msg;
    private Object data;
    public static JsonData buildSuccess(Object data) {
        JsonData jsonData = new JsonData();
        jsonData.setCode(0);
        jsonData.setData(data);
        return jsonData;
    }
}

六、测试与验证

1. 接口测试(Apifox)

  • 文件上传
    • 请求方式:POST
    • URL:http://localhost:8081/api/test/v1/upload
    • 参数:form-data,key=file,value=选择本地文件
    • 响应:返回文件访问URL

Header需要我们选择如下

Body需要我们选择如下,并上传本地文件

结果如下:

2. 控制台验证

登录MinIO控制台,进入ai-pan桶,查看上传的文件是否存在。

七、注意事项

桶权限管理

  • 若未设置桶为公开访问,直接访问URL会报403错误,需使用预签名URL(getPresignedDownloadUrl方法)
  • 设置公开访问:在MinIO控制台→桶设置→访问策略→添加规则,允许所有人访问

八、总结

本文详细介绍了SpringBoot3.X整合MinIO的原生方案,从环境搭建到核心功能实现,涵盖了文件上传、下载、删除等常用操作,并补充了异常处理、参数校验、安全实践等内容。通过原生SDK整合,开发者可以灵活定制存储逻辑,满足不同业务场景需求。

MinIO作为轻量级对象存储方案,非常适合中小规模项目使用,结合SpringBoot的自动化配置,能大幅提升开发效率。后续可进一步扩展断点续传、文件预览、权限控制等功能,丰富存储服务的能力。

到此这篇关于SpringBoot3.X 整合 MinIO 存储原生方案的文章就介绍到这了,更多相关SpringBoot3.X MinIO 存储内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家!

相关文章

  • Java中的synchronized锁膨胀详解

    Java中的synchronized锁膨胀详解

    这篇文章主要介绍了Java中的synchronized锁膨胀详解,正常创建的对象,状态为无锁,对象头的Mark Word 中主要记录了 对象的年龄,也就是经历了多少次GC还存活下来,需要的朋友可以参考下
    2024-01-01
  • SpringBoot实现全局异常处理方法总结

    SpringBoot实现全局异常处理方法总结

    在项目开发中出现异常时很平常不过的事情,我们处理异常也有很多种方式。本文将详细为大家讲解SpringBoot实现全局异常处理几种方法,感兴趣的可以学习一下
    2022-03-03
  • 剖析Java中的事件处理与异常处理机制

    剖析Java中的事件处理与异常处理机制

    这篇文章主要介绍了Java中的事件处理与异常处理机制,讲解Java是如何对事件或者异常作出响应以及定义异常的一些方法,需要的朋友可以参考下
    2016-01-01
  • 如何使用Idea搭建全注解式开发的SpringMVC项目

    如何使用Idea搭建全注解式开发的SpringMVC项目

    这篇文章主要介绍了如何使用Idea搭建全注解式开发的SpringMVC项目,本文给大家介绍的非常详细,对大家的学习或工作具有一定的参考借鉴价值,需要的朋友可以参考下
    2023-03-03
  • maven项目不编译xml文件问题

    maven项目不编译xml文件问题

    这篇文章主要介绍了maven项目不编译xml文件问题,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教
    2024-09-09
  • Spring Integration概述与怎么使用详解

    Spring Integration概述与怎么使用详解

    公司项目需要用到spring integration,而网上关于spring integration的有价值的参考资料比较少,下面这篇文章主要给大家介绍了关于Spring Integration概述与怎么使用的相关资料,需要的朋友可以参考下
    2023-02-02
  • 使用SpringAOP实现公共字段填充功能

    使用SpringAOP实现公共字段填充功能

    在新增员工或者新增菜品分类时需要设置创建时间、创建人、修改时间、修改人等字段,在编辑员工或者编辑菜品分类时需要设置修改时间、修改人等字段,这些字段属于公共字段,本文将给大家介绍使用SpringAOP实现公共字段填充功能,需要的朋友可以参考下
    2024-08-08
  • Java Thread之Sleep()使用方法总结

    Java Thread之Sleep()使用方法总结

    这篇文章主要介绍了Java Thread之Sleep()使用方法总结,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧
    2020-05-05
  • Java SwingWorkder使用实例

    Java SwingWorkder使用实例

    最近在学习Swing,我们都知道在UI表现线程里面长时间执行操作时,画面会假死,为了能够让费时操作不影响画面表现,就需要用多线程了
    2014-04-04
  • 为什么在重写 equals方法的同时必须重写 hashcode方法

    为什么在重写 equals方法的同时必须重写 hashcode方法

    Object 类是所有类的父类,其 equals 方法比较的是两个对象的引用指向的地址,hashcode 是一个本地方法,返回的是对象地址值。他们都是通过比较地址来比较对象是否相等的
    2016-07-07

最新评论