atomctl v2 命令行工具

Atom 应用脚手架与代码生成工具。基于 cobra 构建，集成新项目/模块脚手架、HTTP 路由与 Provider 生成、数据库迁移与模型生成、Swagger 文档、Proto 生成与代码格式化等能力。

安装与使用

• 安装已发布版本：go install go.ipao.vip/atomctl/v2@latest
• 本地构建：go build -o atomctl .
• 开发运行：go run . --help
• 运行测试：go test ./...

运行 atomctl --help 查看总览。

顶级命令

• new：项目脚手架与代码模板初始化
• gen：代码生成（route/provider/model/enum/service）
• migrate：数据库迁移（pressly/goose）
• swag：Swagger 文档生成与格式化
• fmt：Go 代码格式化（自动安装/调用 gofumpt）
• buf：Proto 代码生成（自动安装 buf 并执行 generate）

---

new 脚手架

创建项目/组件初始文件。该命令组带有以下持久化参数（所有子命令通用）：

• --force, -f：覆盖已存在文件/目录
• --dry-run：仅预览生成动作，不写入文件
• --dir：输出基目录（默认 .）

子命令：

new project (别名：p)

• 功能：基于内置模板创建新项目，或在已有 go.mod 的项目内进行就地初始化
• 参数：
  • [module]：可选。在空目录中创建项目时必填（例如 github.com/acme/myapp）；在已有项目内可省略
• 选项：
  • --force：当目标目录存在时强制覆盖
• 行为说明：
  • 识别模板中的隐藏文件占位（模板以 - 开头的文件名会渲染为 . 前缀，例如 -.gitignore -> .gitignore）
  • 支持 .tpl 渲染与 .raw 直写；也支持文件内通过 atomctl:mode=tpl|raw 指示
  • 在当前模块内执行时会跳过覆盖已有的 go.mod
  • 生成后提示后续步骤（cd 与 go mod tidy）

示例：

atomctl new project github.com/acme/demo
atomctl new -f --dir ./playground project github.com/acme/demo
atomctl new project        # 在已有 go.mod 的项目中就地初始化

new provider

• 功能：创建 Provider 脚手架到 providers/<name>
• 参数：
  • <name>：可选。省略名称时会列出可用的内置预置 providers 供选择
• 选项：继承 --dry-run、--dir
• 行为：
  • 若 <name> 与内置 templates/providers/<name> 目录同名，则渲染该目录
  • 否则回退渲染 templates/providers/default 到 providers/<name>

示例：

atomctl new provider              # 列出可用预置 providers
atomctl new provider redis        # 渲染 providers/redis 预置
atomctl new provider email        # 未命中预置，回退 default 渲染到 providers/email
atomctl new --dry-run --dir ./demo provider cache

new event (别名：e)

• 功能：生成事件发布者与订阅者模板
• 参数：
  • <name>：必填，事件名（驼峰自动转换为 snake 作为 topic）
• 选项：
  • --only：仅生成某一侧，publisher 或 subscriber
  • 继承 --dry-run、--dir
• 行为说明：
  • 生成 publisher 到 app/events/publishers/<snake>.go
  • 生成 subscriber 到 app/events/subscribers/<snake>.go
  • 追加常量到 app/events/topics.go：const Topic{Name} = "event:<snake>"（避免重复）

示例：

atomctl new event UserCreated
atomctl new event UserCreated --only=publisher

new job

• 功能：生成任务模板文件；支持可选的定时任务模板
• 参数：
  • <name>：必填，任务名
• 选项：
  • 继承 --dry-run、--dir
  • --cron：除生成 app/jobs/<snake>.go 外，额外生成 app/jobs/cron_<snake>.go

示例：

atomctl new job SendDailyReport               # 生成 app/jobs/send_daily_report.go
atomctl new job SendDailyReport --cron        # 同时生成 cron 版本 app/jobs/cron_send_daily_report.go

说明：代码中已存在 new module 实现，但当前未注册到 new 子命令中（处于弃用状态）。

---

gen 代码生成

命令组持久化参数：

• -c, --config：数据库配置文件路径（默认 config.toml），用于 gen model
• 执行完成后自动调用 atomctl fmt 格式化生成代码

子命令：

gen model (别名：m)

• 功能：连接 PostgreSQL，基于配置生成 GORM 模型与相关文件（委托 go.ipao.vip/gen）到 ./database，并读取 ./database/.transform.yaml 做类型/命名转换
• 配置文件 [Database] 字段：
  • Username、Password、Database、Host、Port、Schema、SslMode、TimeZone
• 示例 config.toml：

[Database]
Host = "127.0.0.1"
Port = 5432
Username = "postgres"
Password = "secret"
Database = "app"
Schema = "public"
SslMode = "disable"
TimeZone = "Asia/Shanghai"

示例：

atomctl gen -c config.toml model

gen route

• 功能：扫描项目 app/http 目录的控制器，解析注释生成 routes.gen.go
• 参数：
  • --path：扫描根目录（默认当前工作目录）；也可作为位置参数传入项目根路径
• 注释规则：
  • @Router <path> [<method>] 指定路由与方法，如 @Router /users/:id [get]
  • @Bind <name> (<position>) key(<key>) [model(<field[:field_type]>)]
    • position 枚举：path|query|body|header|cookie|local|file
    • model() 定义形式：
      1. model() 默认字段 id，类型 int
      2. model(id) 指定字段 id，类型默认 int
      3. model(id:int) 指定字段 id，类型 int
    • 示例：
      • @Bind id path key(id)（PathParam 绑定）
      • @Bind page query key(page)（QueryParam 绑定）
      • @Bind auth header key(Authorization)
      • @Bind file file key(upload)（文件）
      • @Bind user path key(id) model(id:int)（从路径 id 加载模型，按 id:int 查询）

示例：

// UserController
// @Router /users/:id [get]
// @Bind id path key(id) model(id:int)
func (c *UserController) Show(ctx context.Context, id int) (*User, error) { /* ... */ }

执行：

atomctl gen route --path .

注意：生成完成后会自动触发 gen provider 以补全依赖注入。

Bind 参数类型与位置支持

• 标量类型（scalar）：string、bool、int|int8|int16|int32|int64、uint|uint8|uint16|uint32|uint64、float32|float64
• 位置与类型支持：
  • path：支持标量；也支持通过 model() 从路径值加载模型记录（推荐标量或 model 查找）。
    • 示例：@Bind id path key(id)、@Bind user path key(id) model(id:int)
  • query：支持标量或结构体（结构体将按字段名/标签聚合解析查询参数）。
    • 示例：@Bind page query key(page)、@Bind filter query key(q) 或 @Bind opts query key(_)
  • header：支持标量或结构体（按字段名/标签解析请求头）。
    • 示例：@Bind auth header key(Authorization)
  • cookie：支持标量；string 有快捷写法（CookieParam）。
    • 示例：@Bind sid cookie key(session_id)
  • body：支持结构体或标量（通常用于 JSON 体，推荐结构体）。
    • 示例：@Bind input body key(_)
  • file：固定类型为 multipart.FileHeader，用于文件上传。
    • 示例：@Bind file file key(upload)
  • local：任意类型（从上下文本地存取，而非请求来源）。
    • 示例：@Bind user local key(currentUser)

gen provider (别名：p)

• 功能：扫描 Go 源码查找带 @provider 注释的结构体，生成 provider.gen.go 实现依赖注入与分组注册
• 注释语法：@provider(<mode>):[except|only] [returnType] [group]
  • mode：grpc|event|job|cronjob|model（留空为默认）
  • :only：仅注入标注了结构体字段 tag inject:"true" 的依赖
  • :except：注入全部非标量字段，除非字段 tag inject:"false"
  • returnType：Provide 返回类型（如 contracts.Initial）
  • group：归属分组（如 atom.GroupInitial）
• 行为特性：
  • 自动分析字段类型与 import，忽略标量类型
  • grpc：注入 providers/grpc.Grpc，设置 GrpcRegisterFunc
  • event：注入 providers/event.PubSub
  • job|cronjob：注入 providers/job.Job 并引入 github.com/riverqueue/river
  • model：标记需要 Prepare 钩子

示例：

// @provider(job):only contracts.Initial atom.GroupInitial
type UserJob struct {
    // 仅在 only 模式下注入
    Repo *repo.UserRepo `inject:"true"`
    Log  *log.Logger    `inject:"true"`
}

执行：atomctl gen provider（支持在任意子目录执行，自动写入对应包下的 provider.gen.go）

gen enum (别名：e)

• 功能：在工程内扫描包含 ENUM(...) 且带 swagger:enum 的类型定义文件，为每个文件生成 *.gen.go
• 选项：
  • -f, --flag：生成 flag.Value 支持（默认 true）
  • -m, --marshal：生成 JSON 编解码支持
  • -s, --sql：生成 database/sql 相关驱动与 Null 支持（默认 true）

示例：atomctl gen enum -m -s

gen service

• 功能：根据 app/services 下的服务文件聚合生成 services.gen.go
• 选项：
  • --path：服务目录（默认 ./app/services）

示例：atomctl gen service --path ./app/services

---

migrate 数据库迁移（goose）

• 用法：atomctl migrate [action] [args...]
• 支持 action：up|up-by-one|up-to|create|down|down-to|fix|redo|reset|status|version
• 选项：
  • -c, --config：数据库配置文件（默认 config.toml，读取 [Database]）
  • --dir：迁移目录（默认 database/migrations）
  • --table：迁移版本表名（默认 migrations）
• 说明：
  • 执行 create 时若未指定脚本类型，会自动追加 sql 类型
  • 连接配置同上 gen model 的 [Database] 字段

示例：

atomctl migrate status
atomctl migrate up
atomctl migrate create add_users_table

---

swag 文档

swag init (别名：i)

• 功能：生成 Swagger 文档（go/json/yaml）
• 选项：
  • --dir：项目根目录（默认 .）
  • --out：输出目录（默认 docs）
  • --main：主入口文件（默认 main.go）

示例：atomctl swag init --dir . --out docs --main cmd/server/main.go

swag fmt (别名：f)

• 功能：格式化接口注释与路由
• 选项：
  • --dir：扫描目录（默认 ./app/http）
  • --main：主入口文件（默认 main.go）

示例：atomctl swag fmt --dir ./app/http --main main.go

---

fmt 代码格式化

• 功能：调用 gofumpt -extra 格式化全项目；若未安装将自动 go install mvdan.cc/gofumpt@latest
• 选项：
  • --check：仅检查不写入，输出未格式化文件列表
  • --path：格式化范围（默认 .）

示例：

atomctl fmt                 # 写入格式化
atomctl fmt --check --path ./pkg

---

buf Proto 生成

• 功能：检查/安装 buf 并执行 buf generate（在指定目录）
• 选项：
  • --dir：执行目录（默认 .）
  • --dry-run：仅预览不执行
• 说明：若找不到 buf.yaml 会给出提示但仍尝试生成

示例：atomctl buf --dir ./proto

---

配置与约定

• Go 版本：1.23+
• 数据库配置段落：[Database]（被 gen model 与 migrate 读取）
• 代码生成默认位置：
  • 路由：app/http/**/routes.gen.go
  • Provider：每个包内的 provider.gen.go
  • 模型：./database（含 .transform.yaml）
  • Enum：原文件同目录生成 *.gen.go
  • Services：app/services/services.gen.go

---

常见问题

• 路由未生成？确保控制器方法注释包含 @Router，且形参通过 @Bind 标注位置/键名。
• Provider 未注入期望字段？检查 @provider:only|:except 与字段 tag inject:"true|false" 的组合是否正确。
• 执行 fmt 报 gofumpt 不存在？工具会自动安装，如仍失败请检查网络与 GOBIN/PATH。
• buf generate 找不到命令？工具会自动安装 buf，若仍失败请手动安装或检查网络代理。