a6-shared

什么是 a6？

a6 是基于 Go 开发的 Apache APISIX Admin API 命令行工具。它支持对 14 种 APISIX 资源执行常用的 CRUD 操作，还提供声明式配置同步、多 APISIX 实例上下文管理和调试工具。

• 二进制文件：a6
• Go 模块：github.com/api7/a6
• Go 版本：1.22+
• 命令约定：名词-动词结构（a6 <resource> <action> [flags]）

项目结构

a6/
├── cmd/a6/main.go                  # Entry point
├── pkg/cmd/                        # Command implementations
│   ├── root/root.go                # Root command, registers all subcommands
│   ├── factory.go                  # DI: IOStreams, HttpClient, Config
│   ├── route/                      # a6 route list|get|create|update|delete
│   ├── upstream/                   # a6 upstream list|get|create|update|delete|health
│   ├── service/                    # a6 service ...
│   ├── consumer/                   # a6 consumer ...
│   ├── ssl/                        # a6 ssl ...
│   ├── plugin/                     # a6 plugin list|get
│   ├── config/                     # a6 config sync|diff|dump|validate
│   └── context/                    # a6 context create|use|list|delete|current
├── pkg/api/                        # Admin API HTTP client + types
│   ├── client.go                   # Thin net/http wrapper with auth
│   └── types_*.go                  # Go structs per resource (Route, Upstream, etc.)
├── pkg/iostreams/                  # I/O abstraction (TTY detection)
├── pkg/cmdutil/                    # Shared utilities (errors, exporter, flags)
├── pkg/tableprinter/               # Table rendering
├── pkg/httpmock/                   # HTTP mock for unit tests
├── internal/config/                # Context/config file management
├── test/fixtures/                  # JSON fixtures for unit tests
├── test/e2e/                       # E2E tests (build tag: e2e)
├── skills/                         # AI agent skill files
└── docs/                           # Project documentation

架构模式

工厂模式（依赖注入）

每条命令都会接收一个 *cmd.Factory，其中包含 IOStreams、HttpClient() 和 Config()。代码不使用全局状态，因此测试可以完全隔离。

type Factory struct {
    IOStreams   *iostreams.IOStreams
    HttpClient func() (*http.Client, error)
    Config     func() (config.Config, error)
}

命令模式（Options + NewCmd + Run）

每条命令都遵循相同的结构：

type Options struct {
    IO     *iostreams.IOStreams
    Client func() (*http.Client, error)
    Config func() (config.Config, error)
    // command-specific fields
}

func NewCmdXxx(f *cmd.Factory) *cobra.Command { ... }
func xxxRun(opts *Options) error { ... }

输出模式

• TTY：默认输出表格，便于阅读
• 非 TTY：默认输出机器可读的 JSON
• --output json|yaml|table：显式指定输出格式，覆盖自动检测结果

测试模式

• 单元测试：使用 httpmock 和测试用 IOStreams，不发起真实网络请求。
• E2E 测试：使用 //go:build e2e，在 Docker 中运行真实 APISIX，并调用编译后的二进制文件。
• 测试夹具：使用 test/fixtures/*.json 提供接近真实情况的模拟响应。

添加新命令

1. 阅读 API 规范：docs/admin-api-spec.md
2. 创建类型：pkg/api/types_<resource>.go，并同时添加 json: 和 yaml: 标签
3. 创建父命令：pkg/cmd/<resource>/<resource>.go
4. 创建操作：pkg/cmd/<resource>/<action>/<action>.go（参考 docs/golden-example.md）
5. 在同一个包中添加 *_test.go（覆盖 TTY、非 TTY、过滤和错误场景）
6. 添加测试夹具：test/fixtures/<resource>_<action>.json
7. 注册命令：将命令添加到 pkg/cmd/root/root.go
8. 更新文档：docs/user-guide/<resource>.md

常用命令

make build          # Build to ./bin/a6
make test           # Unit tests (excludes e2e)
make test-e2e       # E2E tests (requires running APISIX)
make lint           # golangci-lint
make fmt            # gofmt
make check          # fmt + vet + lint + test
make docker-up      # Start local APISIX stack
make docker-down    # Stop local APISIX stack

代码约定

• 使用 gofmt 和 goimports 格式化代码
• 错误消息使用小写字母开头，不添加句号
• 局部标识符使用 camelCase，导出标识符使用 PascalCase
• 不使用 any 或 interface{}，优先使用具体类型或泛型
• 所有结构体字段都必须包含 json: 和 yaml: 标签
• 不忽略错误；始终处理并向上传递

覆盖的资源类型

资源	密钥字段	API 路径
路由	id	/apisix/admin/routes
服务	id	/apisix/admin/services
上游	id	/apisix/admin/upstreams
消费者	username	/apisix/admin/consumers
SSL 证书	id	/apisix/admin/ssl
全局规则	id	/apisix/admin/global_rules
插件配置	id	/apisix/admin/plugin_configs
消费者组	id	/apisix/admin/consumer_groups
Stream Route	id	/apisix/admin/stream_routes
Proto	id	/apisix/admin/protos
Secret	id	/apisix/admin/secrets/{manager}/{id}
插件元数据	plugin_name	/apisix/admin/plugin_metadata/{name}
插件（只读）	name	/apisix/admin/plugins
消费者凭证	id	/apisix/admin/consumers/{username}/credentials

配置同步工作流程

声明式配置系统（a6 config sync/diff/dump/validate）通过 YAML 文件管理资源：

version: "1"
routes:
  - id: my-route
    uri: /api/*
    upstream_id: my-upstream
upstreams:
  - id: my-upstream
    type: roundrobin
    nodes:
      "httpbin:8080": 1

同步时会按照依赖顺序处理资源：先处理上游和服务，最后处理路由和 Stream Route；删除时则使用相反顺序。删除过程中出现短暂的“仍被引用”错误时，会采用指数退避策略重试。

---

本文根据 api7/a6 仓库中的 a6-shared/SKILL.md 生成。可在 AI Agent Skills 页面浏览全部 Skill。