Introduction |
Dante OSS is an open source framework that simplifies Minio operations. Through the deep encapsulation of the original Minio Java SDK, the complexity of using the Minio API is simplified, the convenience of using Minio is improved, and the threshold for Minio application development is lowered.
MinIO is a high-performance, distributed object storage system. Minio, an open source distributed object storage service, has become very popular abroad, and many small and medium Internet companies in China use it as an object storage service. Although the information and examples related to Minio are already abundant on the Internet, why is there a project like Dante OSS?
- The first time you get in touch with Minio, especially if you want to integrate Minio with Java to develop object storage applications, you still need to invest a certain amount of time and effort to understand its principles and read related documents.
- The function methods in the Minio SDK involve many parameters and a relatively high level of abstraction. Every time you use them, you need to check the source code repeatedly to find out the specific usage methods.
- If you want to integrate with existing applications, you need to spend more or less time and effort, and carry out a certain degree of packaging and transformation.
- There is a lot of relevant information on the Internet, either relatively scattered and unsystematic, or relatively simple and only for conventional upload and download applications, and many features of Minio itself are not involved.
Advantages |
- Zero additional learning costs : developers can seamlessly integrate and use Dante OSS as long as they know basic Spring and REST development
- Lower barriers for developers : Shield the complexity of using the Minio standard Java SDK, and use the Spring environment standard method to simplify the packaging of the original API. Service API and REST API out of the box
- It contains rich functions : almost all the functions of the Minio Java SDK have been transformed, and functions such as large file fragment upload, second transmission, direct transmission, and breakpoint resume transmission are all implemented and integrated with the best solutions in the industry
- Standardized and elegant code : All function parameters do not destroy the original Minio code constructor structure, but are abstracted and simplified on the basis of the original method, greatly improving the programming experience and code readability
- Complete annotation documentation : Provide detailed annotations, instructions, and OpenAPI annotations for request parameters, methods, REST API, and Validation. The purpose and usage are clear at a glance, and you don't need to read Minio documentation and source code, helping you save more time
- Complete front-end example : The front-end adopts a complete project rather than a demo, which fully demonstrates the front-end and back-end interaction, interface calls, parameter usage, TS type definition, etc., and can be directly used in actual projects or after simple transformation build your own product
Compare | Compare
1. More than just a simple Spring Boot Starter build
- Constructing a unified error can return more humane and easier-to-understand error information, while taking into account the return of more detailed error information, which is convenient for developers to understand and locate problems.
- Redefinition of Minio Java SDK parameters in a format that is easier to understand and use. Avoid the problems of Minio's default XML method, which has many parameters, is difficult to understand and use, and is inconvenient to interact with the front end.
- Hide the details that are difficult to understand and use of Minio Java SDK, and provide detailed annotations. Developers no longer need to read the Minio online documentation and source code to understand the details of each API when using it.
- Provide a unified standard REST API, as well as OpenAPI Swagger3 document description and accurate Spring Validation verification, which can be directly integrated into the system for use.
- Minio Client object pool, custom minimalist Minio Server access reverse proxy, improve
2. Standardized business logic and solution set
- It is not just the encapsulation of common methods such as upload and download, but also covers all methods and operations supported by Minio Java SDK.
- Select the best solution in the industry to realize and integrate major business requirements functions such as large file upload in pieces, instant transfer, direct transfer, and resumable transfer.
- Combined with its own application experience and needs, the Minio API is further combined into business logic and functional processing that conform to actual applications.
- A complete front-end project based on Vue3, Typescript5, Vite4, and Pinia 2 is used as an integration example, including detailed Typescript type definitions and mainstream component integration and usage methods such as vue-simple-uploader.
- Provide single version and microservice version cases based on Spring Authorization Server, you can choose from SDK, Spring Boot Starter to complete projects.
Structure | 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 | function
- [1] Basic functions
| Function | illustrate |
|---|---|
| Bucket list | Bucket list query, including Service, REST API and front-end display |
| Whether the bucket name exists | Whether the Bucket name exists, including Service, REST API, and front-end asynchronous verification processing |
| Bucket creation | Create Bucket, including Service, REST API and front-end Validation processing |
| Bucket delete | Delete Bucket, including Service, REST API and front-end display processing |
| Bucket encryption setting acquisition | Get Bucket Encryption settings, including Service, REST API |
| Bucket modify encryption settings | Modify Bucket Encryption settings, including Service, REST API |
| Bucket delete encryption settings | Delete Bucket Encryption settings, including Service, REST API |
| Bucket access policy setting acquisition | Get Bucket Policy settings, including Service, REST API |
| Bucket modify access policy settings | Modify Bucket Policy settings, including Service, REST API |
| Bucket delete access policy setting | Delete Bucket Policy settings, including Service, REST API |
| Bucket label acquisition | Get Bucket Tags, including Service, REST API |
| Bucket modification label | Modify Bucket Tags, including Service, REST API |
| Bucket delete tag | Delete Bucket Tags, including Service, REST API |
| Bucket object lock setting acquisition | Get Bucket ObjectLockConfiguration settings, including Service, REST API |
| Bucket modify object lock settings | Modify Bucket ObjectLockConfiguration settings, including Service, REST API |
| Bucket delete object lock setting | Delete Bucket ObjectLockConfiguration settings, including Service, REST API |
| Object list | Object list query, including Service, REST API and front-end display |
| Object delete | Delete Object, including Service, REST API and front-end display processing |
| Object batch deletion | Delete Objects in batches, including Service, REST API and front-end display processing |
| Object metadata acquisition | Obtain Object Stat, including Service, |
| Object download (server) | Object download (server download, non-streaming mode), including Service, |
| Object tag acquisition | Get Object Tags, including Service, REST API |
| Object Modification Tag | Modify Object Tags, including Service, REST API |
| Object delete tag | Delete Object Tags, including Service, REST API |
| Object gets the reserved settings | Get Object Retention, including Service, REST API |
| Object modification retention settings | Modify Object Retention, including Service, REST API |
| Object open holds settings | Get Object LegalHold, including Service, REST API |
| Object close hold set | Modify Object LegalHold, including Service, REST API |
| other functions | It is gradually improving, mainly involving front-end and back-end interaction, as well as usability verification and development of front-end related functions, so stay tuned, welcome PR |
- [2] Extended functions
| Function | illustrate |
|---|---|
| Create a multipart upload request | Create a multipart upload request and return Minio UploadId |
| Create a file pre-upload address | According to the UploadId and the specified number of shards, the returned number matches the Minio and upload address |
| Get all shard files | Get all the fragmented files under the specified uploadId |
| Create multipart uploads for large files | Unified creation of large file fragment upload business logic encapsulation, reducing repeated interactions between front and back ends, including Service and REST API |
| Merge the uploaded shards | Merge the uploaded fragments according to the UploadId, and complete the upload of large file fragments including Service and REST API |
| Uniform Constant Interface | Return the involved Enums and constants to the front-end in a unified interface, which is convenient for display and use, including Service, REST API and front-end display |
| Minio Client object pool | Realize the Minio Client object pool, reduce the repeated creation and destruction of Minio Client, and improve the performance of accessing Minio Server |
| Bucket settings | Unified Bucket settings: Bucket label settings, access policies, encryption methods, object locking, etc., including Service, REST API and front-end display |
| Object settings | Unified Object settings: Bucket label settings, including Service, REST API and front-end display |
| Object download (streaming mode) | Minio object download, using stream mode to support vue front-end post download, including Service, REST API and front-end display |
| Ultra Lightweight Reverse Proxy | Implement a lightweight reverse proxy to solve the problem of directly exposing the Minio Server address to the front end in the way of PresignedObjectUrl |
- [3] Mainstream solution
| Function | illustrate |
|---|---|
| OpenAPI support | In the environment that supports Open API, display Swagger documents, it is recommended to use Springdoc |
| Integration with Spring Authorization Server architecture | 提供完整的与 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: 包含所有内容，注意：需要依赖数据库等相关内容。
贡献 | Committer
- 在Gitee fork项目到自己的repo
- 把fork过去的项目也就是你的项目clone到你的本地
- 修改代码（记得一定要修改 develop 分支）
- commit 代码，push 到自己的库（develop分支）
- 登录Gitee 在你首页可以看到一个 pull request 按钮，点击它，填写一些说明信息，然后提交即可。
- 等待维护者合并
反馈 | Feedback
- 欢迎提交ISSUS ，请写清楚问题的具体原因，重现步骤和环境
演示 | Example
Dante OSS 作为 Dante Cloud 生态产品，不在单独提供演示环境和示例，请直接使用 Dante 环境查看效果和了解使用，这样也更贴近实际。
- 微服务演示环境：https://gitee.com/dromara/dante-cloud
- 单体架构演示环境：https://gitee.com/herodotus/dante-cloud-athena
- 前端工程演示：https://gitee.com/herodotus/dante-cloud-ui
注意：如果您仅是想了解基本的使用方式和使用效果，建议使用单体架构演示环境。具体搭建方式参见【在线文档】中，单体版章节。