# go-omni CLI

首次接入见 [README](../../README.md)，无需克隆框架源码。本页说明命令参数；下方 `go run ./cmd/go-omni` 示例在框架仓库中执行，并显式引用本地源码。

## API 契约驱动项目

```sh
# 创建包含可运行问候接口的新项目
go run ./cmd/go-omni api new --module example.com/demo --framework-dir . ../demo

# 从已有定义生成对应目录、类型、路由和业务骨架
go run ./cmd/go-omni api generate --api examples/contracts/user.api \
  --dir ../userService --module example.com/userService --framework-dir .

# 校验定义；也接受 goctl 风格的 api go -api ... -dir ...
go run ./cmd/go-omni api validate --api examples/contracts/user.api
```

`new --api <file>` 是契约项目的另一个入口。可以组合 `--database mysql --storage local --log-output file`，生成配置、依赖初始化与资源关闭。API 默认无数据库、无对象存储；`--database memory` 等同于不打开连接。`--force` 不允许覆盖 API 项目。初始配置选择写入 manifest，重新生成自动沿用。

后续在生成项目内执行 `go-omni api generate --api api/user.api --dir .`。
项目内可省略 `--api` / `--dir`。`api inspect` 展示路由和鉴权/业务错误，`api export` 向 stdout 导出 OpenAPI，`api generate --dry-run` 预览文件变化。`--check` 只读检查生成产物是否过期。生成器记录所有权，保留 Service / Repository / 配置 / main 的手写内容，遇到生成文件被手动修改则报冲突。新 Service 与中间件占位实现返回 501。支持 `error (...)`、具名 `auth`、路由 `@errors` / `@auth` 和多行 `@doc`；错误目录同步生成 `internal/apierrors` 调用函数。

`v0.10.0-preview` 新增 `errorCatalog`：集中配置业务码、提示和 HTTP 状态，支持默认 HTTP 200 与单条覆盖，生成函数、路由策略和 OpenAPI 共用一份定义。语法及配置方式见 [统一错误目录](../../errors/README.md)。

支持范围、参数语义、目录及安全更新策略见 [API 开发指南](../../API.md)。本版借鉴 go-zero 的工作流，不宣称兼容全部 goctl 语法；仍通过 Omni/httpx 保留网络层替换能力。

## 日志与对象存储按需装配

新增 `--log-output stdout|stderr|file`、`--log-format json|text`、`--storage none|local|s3|r2|oss`。
指定任意一个新选项后，生成严格的配置文件、初始化代码和项目自身的测试；不指定则保留原有轻量骨架。
对象存储独立于 `--database memory|mysql`。只有选择文件存储才会生成文件 Handler / Service 和对应适配器。

开发阶段可以使用本地源码；固定远程版本的安装和验收见 [发布说明](../../RELEASE.md)：

```sh
# 在 go-omni 仓库中运行；目标目录须为空。
go run ./cmd/go-omni new --framework-dir . \
  --module example.com/fileService --log-output file --log-format json \
  --storage local ../fileService
```

生成项目包含 `etc/config.yaml`、`internal/settings`、`internal/servicecontext/storage.go`、
文件 Service/Handler、测试和 `MODULES.md`。按生成的 MODULES.md 配置示例 Token 和本地签名密钥后，
`go mod tidy && go run ./cmd/server` 即可体验。云存储分别选择 `--storage s3`、`r2`、`oss`，
再设置已有桶/凭据等环境变量；不自动创建桶或修改云资源。

配置优先级为默认值 → YAML/JSON → 环境变量；密钥仅允许环境变量。Service 依赖统一存储接口，
组合处负责创建客户端与有界连接池，退出时关闭自己创建的资源。文件接口提供服务端上传、直传签名、
临时下载链接及统一错误处理；日志示例携带 requestId，文件输出默认带轮转。没有固定业务身份上下文。

新模板要求 `v0.7.0-preview` 或更新版本；明确指定旧版本并启用新模块会被拒绝，
避免模板引用旧框架不存在的接口。本地 `--framework-dir` 验证不受此限制。`--force` 可重新生成兼容配置，
但如果切换配置会遗留引用已移除依赖的旧文件，则拒绝操作，要求使用新目录；不会自动删除修改过的代码。

验证当前生成器：

```sh
GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race ./cmd/go-omni/...
python3 scripts/verifyScaffoldModules.py
```

前者覆盖两种数据库与五种文件存储选择、日志方式/格式，以及生成项目的配置、资源关闭和接口测试。
后者实际编译启动服务，验证日志、上传/下载/直传链接、错误状态、nethttp/native 下的 SIGINT/SIGTERM 和监听端口释放。
云端选项的测试使用本地替身，不代表 OSS/R2 实网验收；本批不访问业务服务器。报告见
[脚手架模块验收](../../performance/scaffoldModulesLocal.json)。

## 其他命令与远程安装

main 分支还提供 `go-omni add orderItems --dir /path/to/project`，向已有 GoOmni 项目增加
Handler / Service / Repository / Model 与模块注册入口。模块名为 lowerCamelCase，
目标目录存在时拒绝覆盖，已有启动代码保持原样。生成模块带可替换的内存 CRUD Repository，
导入后使用 `orderItems.Register(application, repository, authMiddleware)` 注册。
该命令从 `v0.7.0-preview` 提供；源码可用 `go build -o /tmp/go-omni ./cmd/go-omni` 构建。
边界和验证方式见 [业务基础模块](../../MODULES.md)。

从远程安装，生成一个带 Handler / Service / Repository / Model 分层的服务骨架：

```sh
GOPRIVATE=git.yuntuo.hk go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.10.0-preview
go-omni new --framework-version v0.10.0-preview --module example.com/billing ./billing
cd billing
go mod tidy
go run ./cmd/server
```

通过 `go install ...@版本` 安装的 CLI 从构建信息中读取版本，并把它固定到生成项目的
`go.mod`。不会使用不存在的 `v0.0.0`，也不会在普通业务目录中添加本地 `replace`。

需要选择其他已发布版本时，使用完整版本号：

```sh
go-omni new --framework-version v0.6.0-preview --module example.com/billing ./billing
```

`--framework-version` 禁用自动本地替换；`main`、`latest` 等浮动引用不接受为固定版本。
源码构建的 CLI 使用代码中声明的目标发布版本；该版本未发布时请显式选择已发布版本，或用 `--framework-dir` 验证本地源码。

在 GoOmni 源码目录执行时，命令会自动在生成项目的 `go.mod` 中加入本地
`replace git.yuntuo.hk/k2safe/go-omni => ...`，便于立即运行和测试。目标目录非空时命令会停止，明确传入
`--force` 才会覆盖脚手架文件。

也可以在任意目录显式指定源码路径：

```sh
go-omni new --framework-dir /path/to/go-omni --module example.com/billing ./billing
```

默认生成内存存储版本；选择 MySQL 时：

```sh
go-omni new --database mysql --module example.com/billing ./billing
```

MySQL 项目额外包含 `schema.sql`、MySQL Repository 和可选的数据库集成测试。
先应用建表脚本，再设置 `GO_OMNI_DB_DSN` 启动。ServiceContext 负责连接池初始化、表结构检查、
就绪探针注册和关闭。两种模式都提供用户 CRUD、分页、输入校验和统一错误响应。

生成服务默认包含 `/health/live`、`/health/ready` 和示例 `/users` CRUD。
退出信号通过 `signal.NotifyContext` 传入 `RunContext`，Logger 的关闭函数注册到应用生命周期。

发布验收使用 Python 3 标准库脚本，不需要额外 Python 依赖：

```sh
python3 scripts/verifyScaffold.py --version v0.6.0-preview
python3 scripts/verifyDatabase.py --version v0.6.0-preview
```

脚本在源码目录外安装远程 CLI、生成项目，确认固定版本且没有 `replace`，再下载依赖、
编译、请求接口，并对真实二进制分别发送 `SIGINT` 和 `SIGTERM`。同时验证框架 `Run` 的
信号处理和清理回调。每个进程都必须退出码为 0、释放监听端口；临时项目和测试进程会被清理。

发布前验证当前源码：

```sh
go build -o /tmp/go-omni ./cmd/go-omni
python3 scripts/verifyScaffold.py --cli /tmp/go-omni --framework-dir .
python3 scripts/verifyDatabase.py --cli /tmp/go-omni --framework-dir .
```

数据库验收需要本地 Docker，使用独立 MySQL 8.4 容器；不会连接已有业务数据库，结束后清理测试容器与数据卷。

## 显式迁移（main）

SQL 命名为 `0001_createUsers.up.sql`。先预览版本和 SHA-256 清单：

```sh
go-omni migrate --dir migrations
```

部署步骤配置 `GO_OMNI_DB_DSN`，显式执行：

```sh
go-omni migrate --dir migrations --apply
```

预览不连接数据库；应用启动不自动迁移。失败保留 dirty 状态，不提供自动 down/force。
脚手架原有 `schema.sql` 不会自动变成有版本的迁移，已有库需要先确定基线。详见 [扩展模块](../../ADVANCED.md)。