github.com/qiniu/go-sdk/v7@v7.27.0/.agents/rules/dev-guide.md (about)

     1  # 七牛云 Go SDK — 开发维护指引
     2  
     3  七牛云官方 Go SDK（`github.com/qiniu/go-sdk/v7`），Go 1.22+，MIT 许可。
     4  
     5  完整开发维护指南见项目根目录 `AGENTS.md`。
     6  
     7  ## 项目结构
     8  
     9  - `auth` — 认证凭证（AK/SK）、签名
    10  - `storage` — 对象存储 v1（Manager 模式：BucketManager、FormUploader、ResumeUploader）
    11  - `storagev2` — 对象存储 v2（Provider/Interface 模式，代码生成，推荐新功能使用）
    12  - `cdn` / `pili` / `rtc` / `sms` / `linking` / `qvs` — 各业务服务
    13  - `iam` / `media` / `audit` — 生成代码（`make generate` 维护）
    14  - `sandbox` — 沙箱环境（`make generate-sandbox` 维护）
    15  - `client` / `conf` / `reqid` — 基础设施包
    16  - `internal/clientv2` — HTTP 拦截器链（Auth、Retry、AntiHijacking 等）
    17  - `internal/api-generator` — YAML API 规范 → Go 代码生成器
    18  - `api-specs/` — API 规范（git submodule）
    19  - `examples/` — 使用示例（独立 main 包）
    20  
    21  ## 架构模式
    22  
    23  - **Manager 模式**（storage v1）：`New*(mac, &cfg)` 构造，通过参数传递认证
    24  - **Provider/Interface 模式**（storagev2）：通过 `http_client.Options` 注入凭证、区域、重试等组件
    25  - **Interceptor 拦截器链**（internal/clientv2）：按优先级排序的请求处理链
    26  - **双版本共存**：storage v1 和 storagev2 v2 并行维护，共享 auth/client/conf/reqid
    27  
    28  ## 编码规范
    29  
    30  - `gofmt -s` 格式化（CI 检查）
    31  - `staticcheck` 静态检查（CI 检查）
    32  - 注释使用**中文**，导出标识符注释以名称开头（godoc 规范）
    33  - 构造函数 `New*()` / `New*Ex()` 命名
    34  - 错误使用 `fmt.Errorf("context: %w", err)` 包装
    35  - 包级别注释写在 `doc.go` 文件中
    36  
    37  ## 测试要求
    38  
    39  - 测试文件添加 `//go:build unit` 或 `//go:build integration` 标签
    40  - `make unittest` — 单元测试（提交前必须通过）
    41  - `make staticcheck` — 静态检查（提交前必须通过）
    42  - 使用 `testify/assert` 断言，推荐表驱动测试
    43  
    44  ## CI 流程
    45  
    46  gofmt 检查 → staticcheck → 编译 examples → 单元测试（Go 1.22 + stable，Linux → Windows → macOS）
    47  
    48  ## 关键约定
    49  
    50  - 不要修改 `DO NOT EDIT DIRECTLY` 标记的生成代码
    51  - 修改 API 规范后运行 `make generate` 重新生成
    52  - 发布时同步 `conf/conf.go`、`CHANGELOG.md`、`README.md` 版本号
    53  - `api-specs/` 是 git submodule，更新需在 submodule 中操作