3. 对象存储核心概念：桶(Bucket)、对象(Object)、键(Key)、元数据(Metadata)

对象存储的抽象模型围绕四个核心概念构建：桶作为顶层容器，对象作为数据实体，键作为唯一标识符，元数据作为描述数据的属性集合。理解这四者的关系与边界，是掌握对象存储系统设计与Go语言客户端开发的基础。

3.1 桶 (Bucket) —— 顶层命名空间

桶是对象存储中最高级别的逻辑容器，类似于文件系统中的根目录或数据库中的Schema。每个桶拥有全局唯一的名称，并承载访问策略、版本控制、生命周期等配置属性。

3.2 对象 (Object) —— 数据存储的基本单元

对象是对象存储中实际存储数据的基本单元，由数据内容、键和元数据三部分组成。与文件系统的inode不同，对象是不可变的——每次上传都会生成新版本，而非原地修改。

• 数据内容 (Data)：任意二进制流，大小从0字节到单文件5TB（AWS S3限制）。
• 键 (Key)：桶内唯一标识符，用于定位对象。
• 元数据 (Metadata)：系统元数据 + 用户自定义元数据，描述对象属性。
• 实体标签 (ETag)：内容的MD5哈希，用于完整性校验。

// Go 中上传对象的标准模式
// 使用 minio-go v7 SDK
object, err := client.PutObject(ctx, bucketName, objectKey, reader, objectSize,
    minio.PutObjectOptions{
        ContentType: "application/json",
        UserMetadata: map[string]string{
            "X-Amz-Meta-AppVersion": "2.1.0",
            "X-Amz-Meta-Encrypted":  "true",
        },
    })
if err != nil {
    log.Fatalf("上传对象失败: %v", err)
}
log.Printf("上传成功，ETag: %s", object.ETag)

3.3 键 (Key) —— 对象的唯一地址

键是对象在桶内的唯一标识符，采用扁平命名空间设计。虽然键可以包含斜杠（如 images/2025/photo.jpg），但这只是模拟目录结构的约定，底层并无真实目录层级。

3.4 元数据 (Metadata) —— 对象的属性描述

元数据是附着在对象上的键值对集合，分为系统元数据和用户自定义元数据两类。系统元数据由存储服务自动管理，用户自定义元数据允许开发者附加业务上下文。

// Go 中读取对象元数据（不下载数据体）
objInfo, err := client.StatObject(ctx, bucketName, objectKey, minio.StatObjectOptions{})
if err != nil {
    log.Fatalf("获取元数据失败: %v", err)
}

fmt.Printf("对象大小: %d bytes\n", objInfo.Size)
fmt.Printf("内容类型: %s\n", objInfo.ContentType)
fmt.Printf("最后修改: %s\n", objInfo.LastModified)
fmt.Printf("ETag: %s\n", objInfo.ETag)

// 读取用户自定义元数据
if version, ok := objInfo.UserMetadata["AppVersion"]; ok {
    fmt.Printf("应用版本: %s\n", version)
}

3.5 四者关系与数据流

下图展示了桶、对象、键、元数据在对象存储系统中的层级关系与一次完整的上传数据流：

3.6 概念边界与Go类型映射

在Go语言的对象存储SDK中，这四个概念有明确的类型映射关系。理解这些映射有助于编写类型安全的存储操作代码：

// 推荐：定义常量管理桶和键前缀
const (
    BucketAssets    = "myapp-assets"
    BucketLogs      = "myapp-logs"
    KeyPrefixImages = "images/"
    KeyPrefixVideos = "videos/"
)

// 构建层级键
func BuildObjectKey(userID string, filename string) string {
    return path.Join(KeyPrefixImages, userID, filename)
}

// 使用示例
key := BuildObjectKey("u1001", "avatar.jpg")
// 结果: "images/u1001/avatar.jpg"

3.7 常见误区与避坑指南

• 误区一： 认为键支持目录树操作。实际上对象存储没有真正的目录，ListObjects("images/") 只是前缀匹配，删除 images/ 前缀不会级联删除子对象。
• 误区二： 元数据与对象数据混淆。元数据存储在独立的索引系统中，查询元数据（StatObject）不消耗数据下载带宽，但频繁调用会产生请求费用。
• 误区三： 桶名使用大写字母。桶名必须符合DNS命名规范（小写字母、数字、连字符），Go SDK 不会自动转换大小写，错误命名直接导致请求失败。
• 误区四： 忽略ETag校验。上传后应验证返回的ETag与本地计算的MD5是否一致，防止传输损坏。minio-go 默认开启MD5校验，但自定义Reader时需手动处理。