go-omni/cmd/go-omni/README.md

go-omni CLI

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

API 契约驱动项目

# 创建包含可运行问候接口的新项目
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 共用一份定义。语法及配置方式见 统一错误目录。

支持范围、参数语义、目录及安全更新策略见 API 开发指南。本版借鉴 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 和对应适配器。

开发阶段可以使用本地源码；固定远程版本的安装和验收见 发布说明：

# 在 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 可重新生成兼容配置， 但如果切换配置会遗留引用已移除依赖的旧文件，则拒绝操作，要求使用新目录；不会自动删除修改过的代码。

验证当前生成器：

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

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

其他命令与远程安装

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 构建。 边界和验证方式见 业务基础模块。

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

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。

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

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 才会覆盖脚手架文件。

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

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

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

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 依赖：

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

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

发布前验证当前源码：

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 清单：

go-omni migrate --dir migrations

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

go-omni migrate --dir migrations --apply

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