go-sdk

Imported from qiniu/go-sdk (AGENTS.md). Install upstream with npx skills add qiniu/go-sdk. Copyright stays with the author.

七牛云 Go SDK — 开发维护指南

七牛云官方 Go SDK，模块路径 github.com/qiniu/go-sdk/v7，Go 1.22+，MIT 许可。

本文档面向 SDK 维护者和贡献者，帮助理解项目结构、架构模式和开发流程。 SDK 的 API 使用说明请参考各包的 doc.go 文件和 examples/ 目录。

项目结构

顶层包

internal 包

storagev2 子包

其他目录

核心架构模式

Manager 模式（storage v1）

v1 的对象存储使用 Manager 模式，每个功能域对应一个 Manager 结构体：

• storage.BucketManager — Bucket 和对象管理
• storage.FormUploader / storage.ResumeUploader — 上传
• storage.OperationManager — 数据处理

构造方式统一为 New*(mac, &cfg) 或 New*(&cfg)，通过 auth.Credentials 传递认证信息。

Provider/Interface 模式（storagev2）

v2 通过接口抽象实现可插拔：

• credentials.CredentialsProvider — 凭证提供者
• region.RegionsProvider — 区域信息提供者
• chooser.Chooser — 主机选择策略
• resolver.Resolver — 域名解析
• retrier.Retrier — 重试策略
• backoff.Backoff — 退避策略

所有组件通过 http_client.Options 注入，支持自定义替换。

Interceptor 拦截器链（internal/clientv2）

HTTP 请求通过拦截器链处理，拦截器按优先级排序（数字越小优先级越高）：

RetryHosts(200) → RetrySimple(300) → Uplog(310) → BufferResponse(320)
  → SetHeader(400) → Normal(500) → Auth(600) → AntiHijacking(700) → Debug(800)

核心接口：

type Interceptor interface {
    Priority() InterceptorPriority
    Intercept(req *http.Request, handler Handler) (*http.Response, error)
}

Context 传递认证

storage v1 通过函数参数传递 auth.Credentials，storagev2 通过 http_client.Options 结构体传递。reqid 包提供 Context 传递请求 ID 的机制（X-Reqid 头）。

双版本共存

storage（v1）和 storagev2（v2）并行维护：

• v1：稳定的对外 API，Manager 模式，手写代码
• v2：新一代 API，Provider/Interface 模式，代码生成 + 手写
• 两者共享 auth、client、conf、reqid 等基础包
• 新功能优先在 v2 实现，v1 仅做维护性修改

代码生成

API 代码生成（make generate）

internal/api-generator 读取 api-specs/ 中的 YAML 规范，生成类型化 Go 代码：

api-specs/<service>/*.yml  →  internal/api-generator  →  <service>/apis/*.go

涉及的包及 //go:generate 指令：

• storagev2/ → storagev2/apis/（struct: Storage）
• iam/ → iam/apis/（struct: IAM）
• media/ → media/apis/（struct: Media）
• audit/ → audit/apis/（struct: Audit）

运行命令：

make generate   # 运行所有 go generate 并格式化代码

Sandbox 代码生成（make generate-sandbox）

sandbox 使用不同的生成工具链：

• 控制面 API：oapi-codegen（OpenAPI → Go）→ sandbox/internal/apis/
• envd HTTP API：oapi-codegen → sandbox/internal/envdapi/
• envd ConnectRPC：buf + protoc-gen-go + protoc-gen-connect-go → sandbox/internal/envdapi/

运行命令：

make generate-sandbox   # 需要安装 buf、protoc-gen-go、protoc-gen-connect-go

生成代码标记

所有生成的代码文件首行包含如下标记之一：

• // THIS FILE IS GENERATED BY api-generator, DO NOT EDIT DIRECTLY!
• // Code generated by protoc-gen-go. DO NOT EDIT.
• // Code generated by protoc-gen-connect-go. DO NOT EDIT.
• // Code generated by github.com/oapi-codegen/oapi-codegen/v2 ... DO NOT EDIT.

绝对不要手动修改这些文件，如需修改请更新对应的 API 规范后重新生成。

编码规范

格式化

• 使用 gofmt -s 格式化代码（CI 会检查）
• make generate 会自动运行 gofmt -w . 和 gofumpt -w .

静态检查

• 使用 staticcheck（CI 会检查）
• 运行：make staticcheck

注释规范

• 注释默认使用中文
• 导出的 API、函数、类型、常量、变量必须添加注释
• 注释以被注释的标识符名称开头（符合 Go 官方 godoc 规范）
• 包级别注释写在 doc.go 的 package 声明之前

命名规范

• 构造函数使用 New*() 或 New*Ex() 命名
• 错误类型：根包使用 client.ErrorInfo（Code + Err + Reqid），storagev2 使用 storagev2/errors 包

错误处理

• 错误使用 Go 标准的 fmt.Errorf("context: %w", err) 包装
• 使用 errors.Is() / errors.As() 判断错误类型

测试规范

Build Tags

测试文件必须添加 build tag：

//go:build unit

package xxx_test

• unit — 单元测试，不依赖外部服务
• integration — 集成测试，需要七牛账号和网络

Makefile 测试命令

所有测试命令排除 examples/ 和 sms/ 目录。

测试实践

• 使用 testify/assert 进行断言
• 推荐使用表驱动测试
• mock 测试可参考 storagev2/apistest 包

CI 流程

CI 在 push 和 pull_request 时触发（.github/workflows/ci-test.yml）：

Linux（主要检查）

Go 1.22 + stable 两个版本矩阵：

1. gofmt 检查（仅 stable）：gofmt -s -l . 检查未格式化文件
2. staticcheck（仅 stable）：make staticcheck
3. 编译 examples（仅 stable）：go build ./examples/...
4. 单元测试（两个版本）：make unittest

Windows / macOS

Linux 通过后依次运行，仅执行 make unittest（stable 版本）。

版本检查

发布 tag 时（.github/workflows/version-check.yml），检查以下三处版本号一致：

• CHANGELOG.md 包含 ## <version>
• README.md 包含 require github.com/qiniu/go-sdk/v7 v<version>
• conf/conf.go 包含 const Version = "<version>"

开发工作流

环境准备

# 初始化 api-specs submodule
git submodule update --init --recursive

# 验证当前状态
make unittest
make staticcheck

日常开发

1. 确保分支基于最新 master：git fetch upstream && git rebase upstream/master
2. 修改代码前先运行 make unittest 确认当前状态
3. 修改 API 规范后运行 make generate 或 make generate-sandbox
4. 提交前运行 make unittest 和 make staticcheck 确保通过
5. 代码格式化：gofmt -s -w .

修改生成代码的正确流程

1. 更新 api-specs/ 中对应的 YAML 规范（如需）
2. 运行 make generate（或 make generate-sandbox）
3. 检查生成结果，确认无误后提交规范和生成代码

测试与验证

实现新功能或修复 bug 时，应同时提供单元测试和集成测试。对于涉及幂等、重试等逻辑的接口，单元测试用 mock 覆盖边界条件，集成测试用真实凭证验证端到端行为。

运行规则

# 单测（提交前必须通过）
make unittest

# 特定包的单测
go test -tags=unit -count=1 -v ./sandbox/

# 集成测试（需要 .env 文件）
set -a && source sandbox/.env && set +a && go test -tags=integration -count=1 -v ./sandbox/

环境变量 .env 文件

sandbox/.env 用于集成测试和示例程序的环境变量配置：

QINIU_API_KEY=          # 七牛 API Key（必填）
QINIU_SANDBOX_API_URL=  # API 端点（可选，默认 https://cn-yangzhou-1-sandbox.qiniuapi.com）
SANDBOX_RETRY_MAX=      # 可重试 API 的最大重试次数（可选，默认 5，设为 0 禁用重试）

使用方式：

cd sandbox/
set -a && source .env && set +a
# 后续 go test / go run 命令可直接读取环境变量

运行示例

# 需要先 source sandbox/.env
go run ./examples/sandbox_idempotency_retry/

重要约定

1. 不要手动修改生成代码 — 带 DO NOT EDIT DIRECTLY 标记的文件由代码生成器维护
2. 不要删除 sms 测试排除 — Makefile 中 egrep -v 'examples|sms' 是有意为之
3. examples 是独立子目录 — 每个示例是独立的 main 包，编译方式为 go build ./examples/...
4. 版本号三处同步 — 发布时确保 conf/conf.go、CHANGELOG.md、README.md 版本一致
5. api-specs 是 git submodule — 更新规范需要在 submodule 中操作
6. 保持双版本兼容 — storage v1 和 storagev2 v2 并行维护，不要在 v1 中引入 v2 的依赖