MINIO 之 常用操作

MinIO 是一个高性能、开源的对象存储系统，兼容 Amazon S3 API。在 Java 应用中，可以使用 MinIO 官方提供的 MinIO Java SDK 来操作 MinIO 服务，实现上传、下载、删除、列举对象等常见功能。

---

一、添加依赖（Maven）

<dependency>
    <groupId>io.minio</groupId>
    <artifactId>minio</artifactId>
    <version>8.5.12</version> <!-- 建议使用最新版 -->
</dependency>

注意：从 MinIO Java SDK 8.x 开始，API 使用了 OkHttp + Retrofit，且所有方法均为异步非阻塞（返回 CompletableFuture），但提供了同步调用方式（通过 .get() 或使用 MinioClient 的同步方法）。

---

二、初始化 MinIO 客户端

import io.minio.MinioClient;

MinioClient minioClient = MinioClient.builder()
    .endpoint("http://localhost:9000") // MinIO 服务地址
    .credentials("YOUR-ACCESSKEY", "YOUR-SECRETKEY") // 访问密钥
    .build();

如果使用 HTTPS，请确保证书有效或设置信任所有证书（仅测试环境）。

---

三、常用操作示例

1. 创建 Bucket（存储桶）

boolean found = minioClient.bucketExists(BucketExistsArgs.builder().bucket("my-bucket").build());
if (!found) {
    minioClient.makeBucket(MakeBucketArgs.builder().bucket("my-bucket").build());
}

2. 上传文件（本地文件）

minioClient.uploadObject(
    UploadObjectArgs.builder()
        .bucket("my-bucket")
        .object("example.txt")
        .filename("/path/to/local/example.txt")
        .build()
);

3. 上传 InputStream（适合 Web 上传）

InputStream inputStream = new FileInputStream("/path/to/file.jpg");
minioClient.putObject(
    PutObjectArgs.builder()
        .bucket("my-bucket")
        .object("file.jpg")
        .stream(inputStream, inputStream.available(), -1)
        .contentType("image/jpeg")
        .build()
);
inputStream.close();

注意：-1 表示未知大小，MinIO 会自动分块上传；若已知大小，建议传入实际字节数以提升性能。

4. 下载文件到本地

minioClient.downloadObject(
    DownloadObjectArgs.builder()
        .bucket("my-bucket")
        .object("example.txt")
        .filename("/tmp/downloaded_example.txt")
        .build()
);

5. 获取对象为 InputStream（用于流式处理）

InputStream stream = minioClient.getObject(
    GetObjectArgs.builder()
        .bucket("my-bucket")
        .object("example.txt")
        .build()
);
// 读取内容
String content = new String(stream.readAllBytes(), StandardCharsets.UTF_8);
stream.close();

6. 列出 Bucket 中的对象

ListObjectsArgs args = ListObjectsArgs.builder()
    .bucket("my-bucket")
    .prefix("") // 可选前缀过滤
    .recursive(true) // 是否递归列出子目录
    .build();

Iterable<Result<Item>> results = minioClient.listObjects(args);
for (Result<Item> result : results) {
    Item item = result.get();
    System.out.println(item.objectName() + " (" + item.size() + " bytes)");
}

7. 删除对象

minioClient.removeObject(
    RemoveObjectArgs.builder()
        .bucket("my-bucket")
        .object("example.txt")
        .build()
);

8. 删除多个对象（批量）

List<DeleteObject> objects = Arrays.asList(
    new DeleteObject("file1.txt"),
    new DeleteObject("file2.txt")
);

Iterable<Result<DeleteError>> errors = minioClient.removeObjects(
    RemoveObjectsArgs.builder()
        .bucket("my-bucket")
        .objects(objects)
        .build()
);

for (Result<DeleteError> error : errors) {
    DeleteError err = error.get();
    System.err.println("Failed to delete " + err.objectName() + ": " + err.message());
}

9. 生成预签名 URL（用于临时访问）

String url = minioClient.getPresignedObjectUrl(
    GetPresignedObjectUrlArgs.builder()
        .method(Method.GET)
        .bucket("my-bucket")
        .object("private-file.pdf")
        .expiry(60 * 60) // 1小时有效（秒）
        .build()
);
System.out.println("Download URL: " + url);

---

四、异常处理

MinIO SDK 抛出 ErrorResponseException（服务端错误）、InsufficientDataException、InternalException、InvalidKeyException、IOException 等。

建议统一捕获：

try {
    // MinIO 操作
} catch (ErrorResponseException e) {
    System.err.println("MinIO Error: " + e.errorResponse().message());
} catch (Exception e) {
    e.printStackTrace();
}

---

五、完整示例：上传并生成下载链接

import io.minio.*;
import io.minio.http.Method;
import java.nio.file.Paths;

public class MinioExample {
    public static void main(String[] args) throws Exception {
        MinioClient client = MinioClient.builder()
            .endpoint("http://localhost:9000")
            .credentials("minioadmin", "minioadmin")
            .build();

        String bucket = "test-bucket";
        String objectName = "hello.txt";
        String filePath = "/tmp/hello.txt";

        // 创建 bucket
        if (!client.bucketExists(BucketExistsArgs.builder().bucket(bucket).build())) {
            client.makeBucket(MakeBucketArgs.builder().bucket(bucket).build());
        }

        // 上传
        client.uploadObject(
            UploadObjectArgs.builder()
                .bucket(bucket)
                .object(objectName)
                .filename(filePath)
                .build()
        );

        // 生成预签名 URL
        String url = client.getPresignedObjectUrl(
            GetPresignedObjectUrlArgs.builder()
                .method(Method.GET)
                .bucket(bucket)
                .object(objectName)
                .expiry(3600)
                .build()
        );

        System.out.println("File uploaded. Download URL: " + url);
    }
}

---

六、注意事项

1. 线程安全：MinioClient 是线程安全的，可全局单例使用。
2. 大文件上传：SDK 自动处理 multipart upload，无需手动分片。
3. HTTPS 配置：生产环境务必启用 HTTPS，并配置有效证书。
4. 权限控制：建议为应用创建专用的 Access Key，并限制其权限（通过 MinIO 的 IAM 策略）。
5. 版本兼容性：MinIO Server 和 Java SDK 版本尽量保持较新，避免兼容问题。

---

如需更多高级功能（如设置对象元数据、生命周期管理、事件通知等），请参考官方文档：
👉 https://min.io/docs/minio/linux/developers/java/MinIO-Java-SDK.html