MinIO Java Client API 参考总结

---

1. 客户端构建（Client Construction）

核心方法 通过 MinioClient.builder() 使用链式调用配置客户端：

方法名	参数类型/描述	示例场景
endpoint()	字符串、URL 或 okhttp3.HttpUrl，可选端口和是否启用 TLS。格式如 https://play.min.io:9000	匿名访问 TLS 端点、自定义端口、非安全连接等。
credentials()	访问密钥（Access Key）和秘密密钥（Secret Key）	认证访问 MinIO 或 AWS S3 服务。
region()	区域名称（如 us-west-1）	指定桶操作默认区域。
httpClient()	自定义 HTTP 客户端	覆盖默认 HTTP 配置，实现高级网络行为。

示例

java
// 匿名访问 MinIO
MinioClient client = MinioClient.builder()
    .endpoint("https://play.min.io")
    .build();

// 认证访问 AWS S3
MinioClient client = MinioClient.builder()
    .endpoint("https://s3.amazonaws.com")
    .credentials("YOUR-ACCESSKEY", "YOUR-SECRETKEY")
    .region("us-west-1")
    .build();

---

2. 桶操作（Bucket Operations）

核心方法

方法名	参数类型	描述	示例
bucketExists(BucketExistsArgs)	BucketExistsArgs	检查桶是否存在，返回 boolean。	minioClient.bucketExists(BucketExistsArgs.builder().bucket("my-bucket").build())
makeBucket(MakeBucketArgs)	MakeBucketArgs	创建新桶，支持区域和对象锁配置。	指定区域或启用对象锁（合规模式）。
removeBucket(RemoveBucketArgs)	RemoveBucketArgs	删除空桶。	需确保桶内无对象。
setBucketEncryption(SetBucketEncryptionArgs)	SetBucketEncryptionArgs	设置桶的加密配置。	配置 SSE-S3 或 SSE-KMS 加密策略。
listBuckets()	无或 ListBucketsArgs	列出所有桶信息。	支持附加请求头过滤结果。
setBucketLifecycle(SetBucketLifecycleArgs)	SetBucketLifecycleArgs	设置生命周期规则（如自动转存到 Glacier 或过期删除）。	按前缀匹配对象并定义规则。

示例

java
// 创建带区域配置的桶
minioClient.makeBucket(MakeBucketArgs.builder()
    .bucket("my-bucket")
    .region("us-east-1")
    .build());

// 设置生命周期规则
LifecycleConfiguration config = new LifecycleConfiguration(rules);
minioClient.setBucketLifecycle(SetBucketLifecycleArgs.builder()
    .bucket("my-bucket")
    .config(config)
    .build());

---

3. 对象操作（Object Operations）

核心方法

方法名	参数类型	描述	示例
putObject(PutObjectArgs)	PutObjectArgs	上传对象（支持流、文件、元数据和加密）。	上传本地文件或内存流，指定内容类型和存储类。
getObject(GetObjectArgs)	GetObjectArgs	获取对象数据，返回 InputStream。	需手动关闭流，支持分段下载和 SSE-C 解密。
copyObject(CopyObjectArgs)	CopyObjectArgs	服务端复制对象。	跨桶复制或修改元数据。
removeObject(RemoveObjectArgs)	RemoveObjectArgs	删除单个对象或指定版本。	支持绕过保留策略删除版本化对象。
composeObject(ComposeObjectArgs)	ComposeObjectArgs	合并多个对象为新对象。	分片上传后合并文件。
statObject(StatObjectArgs)	StatObjectArgs	获取对象元数据（大小、ETag、版本等）。	检查对象状态或验证完整性。
getPresignedObjectUrl(GetPresignedObjectUrlArgs)	GetPresignedObjectUrlArgs	生成预签名 URL 用于临时访问。	设置过期时间和自定义响应头（如强制下载）。

示例

java
// 上传文件并设置元数据
minioClient.putObject(PutObjectArgs.builder()
    .bucket("my-bucket")
    .object("data.csv")
    .filename("local/data.csv")
    .contentType("text/csv")
    .userMetadata(Collections.singletonMap("project", "alpha"))
    .build());

// 生成预签名下载链接
String url = minioClient.getPresignedObjectUrl(GetPresignedObjectUrlArgs.builder()
    .method(Method.GET)
    .bucket("my-bucket")
    .object("data.csv")
    .expiry(1, TimeUnit.HOURS)
    .build());

---

4. 公共异常（Common Exceptions）

异常类型	触发原因
ErrorResponseException	S3 服务返回错误响应（如权限不足或桶不存在）。
IllegalArgumentException	参数无效（如空桶名）。
IOException	网络或 I/O 错误（如连接超时）。
ServerException	服务器端错误（HTTP 5xx）。
InsufficientDataException	输入流数据不足。

---

5. 高级功能

• 事件监听：listenBucketNotification 监听桶内对象事件（如创建或删除）。
• 合规保留：setObjectLockConfiguration 配置对象锁模式（Governance/Compliance）。
• 批量操作：removeObjects 批量删除对象，uploadSnowballObjects 批量上传小文件。

MinIO/S3 对象元数据属性详解

通过 statObject 方法返回的 ObjectStat 对象（或类似结构）包含以下元数据属性，涵盖标准 HTTP 头、S3 扩展属性及用户自定义元数据：

---

1. 核心属性

属性名	数据类型	含义
bucketName	String	对象所属的桶名称。
objectName	String	对象的唯一标识符（键名）。
size	Long	对象数据的实际大小（字节）。
etag	String	对象的唯一哈希标识符（MD5 校验和）。分块上传时可能为分块哈希的组合值。
lastModified	Date/ZonedDateTime	对象最后修改时间（UTC 时区）。
contentType	String	MIME 类型（如 image/png）。未指定时可能默认为 application/octet-stream。

---

2. 版本控制相关

属性名	数据类型	含义
versionId	String	对象的版本 ID（仅当桶启用版本控制时存在）。null 表示最新版本。
isLatest	Boolean	标识当前版本是否为最新版本。
deleteMarker	Boolean	若为 true，表示此对象是一个删除标记（用于版本控制中的软删除）。

---

3. 存储配置与状态

属性名	数据类型	含义
storageClass	String	对象的存储类别： STANDARD（默认）、REDUCED_REDUNDANCY、GLACIER 等。
expirationTime	Date/ZonedDateTime	对象过期时间（若配置了生命周期规则自动删除）。
legalHoldStatus	String	法律保留状态：ENABLED（启用）或 DISABLED（禁用）。
retentionMode	String	保留模式：COMPLIANCE（合规，不可覆盖）或 GOVERNANCE（治理，需权限覆盖）。
retainUntilDate	Date/ZonedDateTime	对象保留截止时间（合规/治理模式下有效）。

---

4. 安全与加密

属性名	数据类型	含义
sseAlgorithm	String	服务器端加密算法：AES256（SSE-S3）、aws:kms（SSE-KMS）或 null（未加密）。
encryptionKey	String	加密密钥的 KMS ID（仅当使用 SSE-KMS 时存在）。
sseCustomerAlgorithm	String	客户端提供的加密算法（SSE-C 场景下存在）。

---

5. 扩展 HTTP 头属性

属性名	数据类型	含义
cacheControl	String	缓存控制指令（如 max-age=3600, public）。
contentEncoding	String	内容编码方式（如 gzip）。
contentDisposition	String	下载时建议的文件名（如 attachment; filename="report.pdf"）。
contentLanguage	String	内容语言（如 en-US）。
contentMD5	String	客户端提供的对象数据 MD5 校验和（用于校验完整性）。

---

6. 用户自定义元数据

以 x-amz-meta- 开头的键值对，由用户在上传时指定：

属性名示例	数据类型	含义
x-amz-meta-project	String	用户自定义的项目标识符（如 alpha）。
x-amz-meta-author	String	对象创建者（如 user@example.com）。

---

7. 其他系统属性

属性名	数据类型	含义
replicationStatus	String	跨区域复制状态：PENDING（等待复制）、COMPLETED（已完成）、FAILED（失败）。
tagCount	Integer	对象关联的标签数量。
websiteRedirectLocation	String	对象重定向地址（用于静态网站托管）。

---

关键说明

• ETag 的特殊性：对于分块上传的对象，ETag 可能包含分块哈希的组合值（如 "etag": "d41d8cd98f00b204e9800998ecf8427e-3"），此时不可直接作为 MD5 校验。
• 版本控制依赖：versionId、isLatest 等属性仅在桶启用版本控制时有效。
• 加密上下文：加密相关属性（如 sseAlgorithm）仅在对象使用服务器端加密时存在。