网站导航
> 技术文档 > 【SpringBoot实战系列】SpringBoot3.X 整合 MinIO 存储原生方案_springboot3 minio

【SpringBoot实战系列】SpringBoot3.X 整合 MinIO 存储原生方案_springboot3 minio

网友: 技术文档 2025-07-30 21:43:59
大家好，我是工藤学编程 🦉 一个正在努力学习的小博主，期待你的关注 实战代码系列最新文章😉 C++实现图书管理系统（Qt C++ GUI界面版） SpringBoot实战系列🐷 【SpringBoot实战系列】Sharding-Jdbc实现分库分表到分布式ID生成器Snowflake自定义wrokId实战 环境搭建大集合 环境搭建大集合(持续更新） 分库分表 分库分表之实战-sharding-JDBC绑定表配置实战

【亲测宝藏】发现一个让 AI 学习秒变轻松的神站！不用啃高数、不用怕编程，高中生都能看懂的人工智能教程来啦！

👉点击跳转，和 thousands of 小伙伴一起用快乐学习法征服 AI，说不定下一个开发出爆款 AI 程序的就是你！

本文章目录

  • SpringBoot3.X整合MinIO存储原生方案：从环境搭建到实战开发
    • 一、前言：为什么选择MinIO？
    • 二、环境准备
      • 1. 基础环境清单
      • 2. MinIO服务部署
    • 三、项目初始化与依赖配置
      • 1. 创建SpringBoot项目
      • 2. 核心依赖引入
    • 四、配置详解
      • 1. 核心配置文件（application.yml）
      • 2. MinIO配置类
    • 五、核心功能开发
      • 1. 工具类：文件路径生成
      • 2. 控制器（TestController）
    • 六、测试与验证
      • 1. 接口测试（Apifox）
      • 2. 控制台验证
    • 七、注意事项
      • 桶权限管理
    • 八、总结

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

【SpringBoot实战系列】SpringBoot3.X 整合 MinIO 存储原生方案_springboot3 minio

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

【SpringBoot实战系列】SpringBoot3.X 整合 MinIO 存储原生方案_springboot3 minio
【SpringBoot实战系列】SpringBoot3.X 整合 MinIO 存储原生方案_springboot3 minio

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

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); }}// 统一响应类@Datapublic 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需要我们选择如下

【SpringBoot实战系列】SpringBoot3.X 整合 MinIO 存储原生方案_springboot3 minio

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

【SpringBoot实战系列】SpringBoot3.X 整合 MinIO 存储原生方案_springboot3 minio

结果如下：

【SpringBoot实战系列】SpringBoot3.X 整合 MinIO 存储原生方案_springboot3 minio

2. 控制台验证

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

【SpringBoot实战系列】SpringBoot3.X 整合 MinIO 存储原生方案_springboot3 minio

七、注意事项

桶权限管理

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

八、总结

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

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

觉得有用请点赞收藏！
如果有相关问题，欢迎评论区留言讨论~

网络标签：

相关问题