4. 对象存储核心模型：Bucket 与 Object 的抽象

对象存储的领域模型围绕两个核心实体展开：Bucket（存储桶）和Object（对象）。Bucket 是命名空间和权限的边界，Object 是数据与元数据的载体。理解这两个实体的抽象方式，是设计 Go 语言对象存储接口的第一步。

4.1 Bucket 与 Object 的职责边界

4.2 命名空间设计：扁平 vs 层级

对象存储的命名空间通常采用扁平键空间 + 前缀模拟目录的模式。Go 接口需要同时支持这两种视图：

• 扁平视图：直接通过 Key 定位 Object，适合哈希路由和水平扩展。
• 层级视图：通过分隔符（如 /）模拟目录树，方便用户浏览。

// 扁平命名空间接口示例
type ObjectStorage interface {
    PutObject(ctx context.Context, bucket, key string, data io.Reader, opts ...PutOption) (*PutResult, error)
    GetObject(ctx context.Context, bucket, key string, opts ...GetOption) (*Object, error)
    DeleteObject(ctx context.Context, bucket, key string, opts ...DeleteOption) error
}

// 层级列举接口示例
type Lister interface {
    ListObjects(ctx context.Context, bucket, prefix, delimiter string, maxKeys int) (*ListResult, error)
    ListObjectVersions(ctx context.Context, bucket, prefix, delimiter string, maxKeys int) (*VersionListResult, error)
}

4.3 元数据模型：系统元数据与用户元数据

每个 Object 都附带元数据，分为两类：

// 对象元数据模型
type ObjectInfo struct {
    Key          string            `json:"key"`
    Bucket       string            `json:"bucket"`
    ETag         string            `json:"etag"`
    Size         int64             `json:"size"`
    ContentType  string            `json:"contentType"`
    LastModified time.Time         `json:"lastModified"`
    StorageClass string            `json:"storageClass"`
    Metadata     map[string]string `json:"metadata"` // 用户自定义元数据
    VersionID    string            `json:"versionId,omitempty"`
}

4.4 版本控制模型

版本控制是对象存储区别于传统文件系统的重要特性。每个 Object 的每次写入都会生成一个新版本，Go 接口需要处理以下场景：

• 开启/暂停版本控制：Bucket 级别的配置，影响后续写入。
• 版本 ID 管理：显式指定或由服务端自动生成。
• 删除标记（Delete Marker）：软删除，保留历史版本。
• 版本列举与恢复：通过版本 ID 读取或删除特定版本。

// 版本控制相关接口
type VersionedStorage interface {
    // 设置 Bucket 版本控制状态
    SetBucketVersioning(ctx context.Context, bucket string, status VersioningStatus) error
    // 获取 Bucket 版本控制状态
    GetBucketVersioning(ctx context.Context, bucket string) (VersioningStatus, error)
    // 带版本 ID 的对象操作
    GetObjectVersion(ctx context.Context, bucket, key, versionID string) (*Object, error)
    DeleteObjectVersion(ctx context.Context, bucket, key, versionID string) error
    // 列举所有版本（包含删除标记）
    ListObjectVersions(ctx context.Context, bucket, prefix string) (*VersionList, error)
}

type VersioningStatus int

const (
    VersioningUnspecified VersioningStatus = iota
    VersioningEnabled
    VersioningSuspended
)

4.5 模型组合与 Go 接口设计

将上述模型组合为完整的 Go 接口体系，推荐采用接口组合模式：

// 基础对象存储接口
type ObjectStorage interface {
    BucketOperator
    ObjectOperator
    VersionedOperator
}

// 拆分为子接口，便于单元测试和依赖注入
type BucketOperator interface {
    CreateBucket(ctx context.Context, bucket string, opts ...BucketOption) error
    DeleteBucket(ctx context.Context, bucket string) error
    ListBuckets(ctx context.Context) ([]BucketInfo, error)
    SetBucketVersioning(ctx context.Context, bucket string, status VersioningStatus) error
}

type ObjectOperator interface {
    PutObject(ctx context.Context, bucket, key string, data io.Reader, opts ...PutOption) (*PutResult, error)
    GetObject(ctx context.Context, bucket, key string, opts ...GetOption) (*Object, error)
    DeleteObject(ctx context.Context, bucket, key string, opts ...DeleteOption) error
    ListObjects(ctx context.Context, bucket, prefix, delimiter string) (*ListResult, error)
}

type VersionedOperator interface {
    GetObjectVersion(ctx context.Context, bucket, key, versionID string) (*Object, error)
    DeleteObjectVersion(ctx context.Context, bucket, key, versionID string) error
    ListObjectVersions(ctx context.Context, bucket, prefix string) (*VersionListResult, error)
}

4.6 模型对比：对象存储 vs 传统文件系统