Dante OSS 1.0.0 发布，一款简化 Minio 操作的开源框架

简介 | Intro

Dante OSS 是一款简化Minio操作的开源框架。通过对原有 Minio Java SDK 的深度封装，简化 Minio API 使用复杂度，提升 Minio 使用的便捷性，降低 Minio 应用开发门槛。

MinIO 是一款高性能、分布式的对象存储系统。Minio这款开源的分布式对象存储服务在国外已经相当受欢迎，并且国内也有多中小型互联网公司使用它来作为对象存储服务。虽然 Minio 相关的资料和示例在网络上已经非常丰富，但是为什么还要推出 Dante OSS 这样的项目？

初次接触 Minio，特别是想要通过 Java 集成 Minio 开发对象存储应用是，还是需要投入一定的时间和精力去了解其原理阅读相关文档。
Minio SDK 中的函数方法，涉及的参数较多，抽象层度比较高，每次使用都需要反复查阅源代码才能摸清具体使用方式。
想要与已有的应用进行整合，多少都要投入时间精力，进行一定程度的封装和改造。
网上相关资料多，要么比较零散不成体系，要么比较单一仅针对常规上传下载应用，Minio 自身很多特性都不涉及。

发布 | Releases

【本次更新内容】：

[安全] 修复 snappy-java 的 compress 方法整数溢出漏洞导致拒绝服务(CVE-2023-34454)
[升级] Minio 版本升级至 8.5.4
[新增] 新增 Object Legal Hold Service、REST API
[新增] 新增 Object 设置 Service、REST API
[新增] 新增服务端上传下载 Service，拆分服务端上传下载与流式上传下载，以避免混淆，清晰逻辑。
[新增] 新增基础上传功能，完成前后端联调验证
[新增] 新增 Minio Admin 对象池及基础服务。
[新增] Minio Admin 用户创建、列表、删除、信息获取 Service、REST API
[新增] Minio Admin 组创建、列表、删除、信息获取 Service、REST API
[新增] Minio Admin 屏蔽策略创建、列表、删除、信息获取 Service、REST API
[新增] Bucket 配额设置、清除、获取 Service
[新增] 新增存储桶配额管理 Service 及 Rest API
[新增] 新增存储桶版本设置 Server 及 REST API
[新增] 前端对象列表界面，增加文件夹显示及查看功能
[重构] 重构对象保留相关实体、转换器代码，优化相关调用逻辑
[重构] 调整 Minio 方法返回实体所在包，统一命名规则，减少多处出现类似代码。
[重构] 全面使用枚举替代原有整形参数传递方式，以简化代码减少出错，降低转换逻辑复杂度。
[重构] 所有 Minio 基础封装 Service 中，Get 类型方法，修改为使用 Minio API 原始返回值，以保持基础 API 包逻辑干净清楚
[重构] 重构 Bucket、Object 保留设置对应域实体、枚举以及转换器，去除无用内容降低前端集成复杂度。
[修复] 修复获取对象列表实体转换不支持文件夹，导致抛空错误问题
[修复] 修复上传文件参数校验错误，导致必要参数确实产生错误提示问题
[修复] 修复 RestTemplate 初始配置，解决 RestTemplate 默认的 HttpMessageConverter 被清除，导致代理请求转发出错问题。
[修复] 修复大文件分片上传，在自定义代理模式下上传失败问题。
[修复] 修复大文件分片上传脱离系统认证体系问题。
[修复] 修复大文件分片上传，在自定义代理模式下传递 Token 会导致上传失败问题。
[修复] 修复 Admin 相关操作以及部分新增 Service 没有注入错误。
[修复] 修复 Minio Admin 相关操作没有正常关闭对象引用，导致请求死锁问题。
[修复] 修复 Bucket Versioning 设置 REST API 请求参数传递格式错误。
[优化] 优化 Put Object Service 代码新增基础 API 重载方法；优化 Put Object 请求参数实体。
[优化] 优化 Upload Object Service 代码新增基础 API 重载方法；优化 Upload Object 请求参数实体。
[优化] 优化 Stat Object Service 代码新增基础 API 重载方法；优化 StatObject 请求参数实体。
[优化] 重新命名相关域对象名称，调整前端 Typescript 声明定义。
[优化] 根据最新定义及参数，完成存储桶列表、存储桶是否存在、存储桶创建、存储桶删除、存储桶全部设置、对象列表、对象删除、对象批量删除、对象信息、服务端下载、流式下载。
[优化] 策略化设置使用 OkHttp 还是 HttpClient 作为 RestTemplate 的基础 HttpClient。
[优化] 重新定义预下载代理中使用的 RestTemplate 创建方式，避免与系统中已有的体系化 Rest Client 冲突。
[优化] 重命名大文件分片上传直传相关代码，明晰代码用途，减少冲突
[优化] 优化存储桶设置功能相关参数设置，完善存储桶保留设置前端功能
[优化] OSS BOM 不再单独配置依赖，直接继承使用 Dante Engine，方便统一管控配置以及依赖版本

优点 | Advantages

零额外学习成本: 开发者只要会 Spring 和 REST 基本开发，即可无缝集成和使用 Dante OSS
降低开发者门槛: 屏蔽 Minio 标准 Java SDK 使用复杂度，使用 Spring 环境标准方式对原有 API 进行简化封装。Service API 和 REST API 开箱即用
包含的功能丰富: 改造了 Minio Java SDK 的几乎全部功能，且对大文件分片上传、秒传、直传、断点续传等功能，均采用业内最优解决方案进行实现和融合
规范优雅的代码: 所有函数参数，并未破坏原有 Minio 代码构造器结构，而是在原有方式的基础上抽象简化，编程体验和代码可读性大幅提升
完善的注释文档: 对请求参数、方法、REST API、Validation 提供详实的注释、说明和 OpenAPI 标注，用途用法一目了然，无需再翻阅 Minio 文档和源代码，帮助您节省更多时间
完整的前端示例：前端采用一个完整的项目而非Demo的形式，全面的展示了前后端交互涉及、接口调用、参数使用、TS 类型定义等各方面内容，可直接用于实际项目或简单改造后构建自己的产品

对比 | Compare

1. 不只是简单的 Spring Boot Starter 构建

构建统一的错误，可以返回更人性化、更易理解的错误信息，同时兼顾更详细错误信息的返回，方便开发人员理解和定位问题。
采用更易理解和使用的格式对 Minio Java SDK 参数进行重新定义。规避 Minio 默认 XML 方式参数多、不易理解使用、与前端交互不方便等问题。
隐藏 Minio Java SDK 不易理解和使用的细节，提供详实的注释说明，开发人员在使用时无需再通过翻阅 Minio 在线文档和源代码来了解各个 API 使用细节。
提供统一标准的 REST API，以及 OpenAPI Swagger3 文档描述和准确的 Spring Validation 校验，可直接集成至系统中使用。
Minio Client 对象池、自定义极简 Minio Server 访问反向代理，提升

2. 标准化业务逻辑和解决方案集合

不只是上传、下载等常用方法的封装，涵盖 Minio Java SDK 支持的所有方法和操作。
选择业内最优的解决方案，实现和集成大文件分片上传、秒传、直传、断点续传等主要业务需求功能。
结合自身应用经验和需求，将 Minio API 进一步组合成符合实际应用的业务逻辑和功能处理。
采用一个基于 Vue3、Typescript5、Vite4、Pinia 2 的完整的前端项目作为集成示例，包括详细的 Typescript 类型定义以及 vue-simple-uploader 等主流组件集成和使用方法。
提供基于 Spring Authorization Server 的单体版、微服务版案例，从 SDK、Spring Boot Starter 到完整项目任你选择。

3. 具体差异说明

[1] 基础API方法以及方法参数

Minio SDK	Dante OSS
仅包含基础操作API	提供大量重载方法
必须用构造器创建参数对象	重载方法覆盖所有常见参数，按需传参即可
API全部混在同一个类中	根据差异、用途、场景拆分为不同的 Service，例如：getObject 和 downloadObject
源于XML对象参数结构复杂	自定义实体和转换器简化参数结构
基础API会抛出大量 Exception，具体问题需要自己摸索对应	对所有错误进行标准化处理，提供更准确和交互友好的描述信息，可方便地与系统错误体系融合

[2] 前后端交互

Minio SDK	Dante OSS
复杂结构参数不利于JSON互转	采用最简化参数方便传输并可准确转换成对应Minio复杂对象参数
参数层次结构复杂	自定义请求参数实体保持继承结构的同时简化传递参数
参数多用途不明晰必须查阅源代码	使用 OpenAPI 注解详细说明各参数用途可使用 Swagger 查阅
参数校验规则细节多没有文档说明	对照 Minio 源代码，结合自定义实体，增加匹配的 Spring Validation 校验
不提供 REST API	提供标准的 REST API 可直接使用

[3] 业务支持

内容	Minio SDK	Dante OSS
常规业务	独立方法需要自己按需组合	封装常规业务逻辑，可直接调用 REST API使用
设置管理	对于存储桶、对象的管理只能通过 Minio 服务器管理界面	对照 Minio 管理界面方式，将管理功能封装为 Service、REST API 以及 Vue 管理界面
文件直传	提供直传机制，直接暴露Minio服务器地址	增加超简化反向代理，在满足直传需求的前提下，很好的隐藏Minio 服务器以提升安全性
文件直传	直传接口无法与现有系统安全体系融合（无法鉴权）	提供基于 Spring Authorization Server 的、完整的单体版和微服务版案例
接口防护	不提供 REST API 及接口防护	根据REST接口类型，默认设置幂等、防刷等接口调用防刷机制
对象池化	Builder 模式创建基础 Client	构建 Minio Client 和 Minio Admin 对象池模式，支持重用 Minio 基础对象来提高应用程序性能和效率
大文件分片	内部机制无法直接使用	封装主流大文件分片方案，提供前后端使用案例

[4] 前端开发

Dante OSS
只要Minio API支持，对应的管理功能均会在标准的 Vue3 工程中实现
提供与后端一致 Typescript 声明文件，可以直接用于基于Typescript的前端开发
完整的、基于 Vue3、Vite4、Typescript5 的前端项目案例，可清晰的了解 Minio 前后端交互和使用，甚至直接使用

结构 | Structure

 dante-oss ├── oss-bom -- 工程Maven顶级依赖，统一控制版本和依赖 ├── oss-minio -- Minio 模块 ├    ├── minio-core -- Minio 通用代码包 ├    ├── minio-sdk-logic -- Minio 基础 API 模块 ├    ├── minio-sdk-rest -- Minio 基础 REST API模块 ├    ├── minio-sdk-scenario -- Minio 扩展及应用方案整合模块 ├    └── minio-spring-boot-starter -- 仅包含 Minio 基础 API 和 REST API 的 Starter └── oss-spring-boot-starter -- 完整的、包含所有内容的 Starter

功能 | function

[1] 基础功能

功能	说明
Bucket 列表	Bucket 列表查询，包括 Service、REST API 和前端展示
Bucket 名称是否存在	Bucket 名是否存在，包括 Service、REST API 和前端异步校验处理
Bucket 创建	创建 Bucket，包括 Service、REST API 和前端Validation校验处理
Bucket 删除	删除 Bucket，包括 Service、REST API 和前端展示处理
Bucket 加密设置获取	获取 Bucket Encryption 设置，包括 Service、REST API
Bucket 修改加密设置	修改 Bucket Encryption 设置，包括 Service、REST API
Bucket 删除加密设置	删除 Bucket Encryption 设置，包括 Service、REST API
Bucket 访问策略设置获取	获取 Bucket Policy 设置，包括 Service、REST API
Bucket 修改访问策略设置	修改 Bucket Policy 设置，包括 Service、REST API
Bucket 删除访问策略设置	删除 Bucket Policy 设置，包括 Service、REST API
Bucket 标签获取	获取 Bucket Tags，包括 Service、REST API
Bucket 修改标签	修改 Bucket Tags，包括 Service、REST API
Bucket 删除标签	删除 Bucket Tags，包括 Service、REST API
Bucket 对象锁定设置获取	获取 Bucket ObjectLockConfiguration 设置，包括 Service、REST API
Bucket 修改对象锁定设置	修改 Bucket ObjectLockConfiguration 设置，包括 Service、REST API
Bucket 删除对象锁定设置	删除 Bucket ObjectLockConfiguration 设置，包括 Service、REST API
Object 列表	Object 列表查询，包括 Service、REST API 和前端展示
Object 删除	删除 Object，包括 Service、REST API 和前端展示处理
Object 批量删除	批量删除 Object，包括 Service、REST API 和前端展示处理
Object 元信息获取	获取 Object Stat，包括 Service、
Object 下载(服务端)	Object 下载(服务端下载，非流模式)，包括 Service、
Object 标签获取	获取 Object Tags，包括 Service、REST API
Object 修改标签	修改 Object Tags，包括 Service、REST API
Object 删除标签	删除 Object Tags，包括 Service、REST API
Object 获取保留设置	获取 Object Retention，包括 Service、REST API
Object 修改保留设置	修改 Object Retention，包括 Service、REST API
Object 开启持有设置	获取 Object LegalHold，包括 Service、REST API
Object 关闭持有设置	修改 Object LegalHold，包括 Service、REST API
Admin User 列表	User 列表查询，包括 Service、REST API
Admin User 信息	获取 User 信息，包括 Service、REST API
Admin User 创建	创建 User，包括 Service、REST API
Admin User 删除	删除 User，包括 Service、REST API
Admin Group 列表	Group 列表查询，包括 Service、REST API
Admin Group 信息	获取 Group 信息，包括 Service、REST API
Admin Group 创建	创建 Group，包括 Service、REST API
Admin Group 删除	删除 Group，包括 Service、REST API
Admin Policy 列表	Policy 列表查询，包括 Service、REST API
Admin Policy 创建	创建 Policy，包括 Service、REST API
Admin Policy 删除	删除 Policy，包括 Service、REST API
Admin Bucket 配额设置	存储桶配额设置，包括 Service
Admin Bucket 配额获取	存储桶配额获取，包括 Service
Admin Bucket 配额清除	存储桶配额清除，包括 Service
其它功能	正逐步完善，主要涉及前后端交互、以及可用性验证和前端相关功能的开发，敬请期待，欢迎 PR

[2] 扩展功能

功能	说明
创建分片上传请求	创建分片上传请求，返回 Minio UploadId
创建文件预上传地址	根据 UploadId 和指定的分片数量，返回数量像匹配的 Minio 与上传地址
获取所有分片文件	获取指定 uploadId 下所有的分片文件
创建大文件分片上传	统一的创建大文件分片上传业务逻辑封装，减少前后端反复交互，包括 Service、REST API
合并已经上传完成的分片	根据 UploadId 合并已经上传完成的分片，完成大文件分片上传包括 Service、REST API
统一常量接口	将涉及的 Enums、常量以统一接口的方式返回给前端，方便展示使用，包括 Service、REST API 和前端展示
Minio Client 对象池	实现 Minio Client 对象池，减少 Minio Client 的反复创建和销毁，提升访问 Minio Server性能
Minio Async Client 对象池	实现 Minio Async Client 对象池，减少 Minio Async Client 的反复创建和销毁，提升访问 Minio Server性能
Minio Admin 对象池	实现 Minio Admin 对象池，减少 Minio Admin 的反复创建和销毁，提升访问 Minio Server性能
Bucket 设置	统一 Bucket 设置： Bucket 标签设置、访问策略、加密方式、对象锁定、版本控制、保留设置等，包括 Service、REST API 和前端展示
Object 设置	统一 Object 设置： Bucket 标签设置，包括 Service、REST API 和前端展示
Object 下载(流模式)	Minio 对象下载，采用流模式支持vue前端post方式下载，包括 Service、REST API 和前端展示
超轻量级反向代理	实现轻量级反向代理解决 PresignedObjectUrl 方式直接向前端暴露 Minio Server地址问题

[3] 主流方案

功能	说明
OpenAPI 支持	在支持 Open API 环境下，显示 Swagger 文档，建议使用 Springdoc
与 Spring Authorization Server 体系集成	提供完整的与 Spring Authorization Server 集成，实现认证、授权、鉴权、动态权限等完整案例，包括单体版和微服务版
大文件分片上传	采用 PresignedObjectUrl 方案的大文件分片上传。扩展 Minio Client，封装相应的 Service、REST API
vue-simple-uploader	前端基于 vue-simple-uploader 组件，配合自定义 REST API 实现大文件分片上传

使用 | How to use

一、基本使用

maven 中引入

 <dependency>     <groupId>cn.herodotus.oss</groupId>     <artifactId>oss-spring-boot-starter</artifactId>     <version>最新版本</version> </dependency>

配置 yml 参数

 herodotus:   oss:     minio:       endpoint: http://127.0.0.1:9000       access-key: xxxxxx       secret-key: xxxxxx

结合实际需求配置数据源

统一错误处理

 // 参考代码 public static Result<String> resolveException(Exception ex， String path) {     return GlobalExceptionHandler.resolveException(ex， path); }  // 或者  @ExceptionHandler({HerodotusException.class， PlatformException.class}) public static Result<String> exception(Exception ex， HttpServletRequest request， HttpServletResponse response) {     ······ }

交互性错误信息反馈

 // 在系统统一错误处，调用以下代码即可返回包含自定义错误码的、更具交互性错误信息。 if (ex instanceof HerodotusException exception) {     Result<String> result = exception.getResult();     result.path(path);     log.error("[Herodotus] |- Global Exception Handler, Error is : {}", result);     return result; }

二、选择使用

除了 minio-core 模块以外，其它所有模块均可以单独使用。可以根据自身需要，仅选择某个模块进行使用。

minio-sdk-logic: 仅包含对 Minio 基础 API 封装的 Service 代码。使用注解 @EnableHerodotusMinioLogic 可开启相关内容。
minio-sdk-rest: 包含对 Minio 基于 API 封装的 Service 以及 REST 代码。使用注解 @EnableHerodotusMinioRest 可开启相关内容。
minio-sdk-scenario: 包含扩展应用以及各OSS常规场景应用，注意：不包含 minio-sdk-rest 内容。使用注解 @EnableHerodotusMinioScenario 可开启相关内容。
minio-spring-boot-starter: 包含 minio-sdk-logic 和 minio-sdk-rest 两部分内容，可直接引入使用。
oss-spring-boot-starter: 包含所有内容，注意：需要依赖数据库等相关内容。