# 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`：

```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 查询）

示例：

```go
// 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` 钩子

示例：

```go
// @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，若仍失败请手动安装或检查网络代理。