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

go-omni CLI

v0.14 新增 api format [--check]、api upgrade [--dry-run|--preview <空目录>|--apply]，以及 workspace format|generate|check --file omni.workspace.json。详见 通用开发指南。

新项目采用根目录 main.go 与 internal/config、svc、logic、handler、types。完整职责、启动扩展、流式接口和生成文件边界见 项目指南。

创建项目

# 仓库读取权限与 PATH 配置见根目录 README
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.14.1-preview
go-omni new --module example.com/hello ./hello

# 从自己的契约生成；service.api 及其相对 import 文件需要在本地存在
go-omni new --api service.api --module example.com/example ./example

new 与 api new 统一生成契约项目；不再提供另一套 CRUD 启动目录。未实现的 Logic / 中间件骨架返回 501。进入项目执行 go mod tidy、go run .、go build .。

参数：--database none|memory|mysql（默认 none；memory 等同 none），--storage none|local|s3|r2|oss，--log-output stdout|stderr|file，--log-format json|text。基础设施按需生成，连接凭据由环境提供，不自动创建数据库、表或云资源。选择 MySQL 不会凭空生成业务表或 Repository 查询。

存储配置和客户端位于 config/svc，业务使用统一接口。local 存储签名端点由生成器接入；上传、下载等业务路由由 .api 定义。认证与存储路径由项目实现。

日常生成

go-omni api validate
go-omni api inspect
go-omni api generate --dry-run
go-omni api generate
go-omni api generate --check
go-omni api export > openapi.json
go test ./...

项目内自动发现 manifest 中的 API 入口，也可显式 --api ... --dir ...。api go -api ... -dir ... 为命令别名，不代表兼容全部 goctl 语法。

main、Gen.go、OpenAPI 和 manifest 由生成器维护；业务文件按字节保留。手改生成文件会报冲突，--check 检查入口与所有生成产物。没有 --force 覆盖业务的入口。初始基础设施 profile 在重新生成时沿用，后续项目依赖由用户修改 config/svc。

生成/预览会比较上次契约快照，提示受影响的 Logic 文件、DTO 字段和 body/流式模式变化。明确的 Logic 签名错误显示文件行号、原签名和期望签名；生成后未调整业务时，--check 仍返回失败。REVIEW 不强制确认，类型别名/build tags 等不确定情况交给 go test ./... 验证。完整行为见 契约变更提示。

@app(defaultResponse: TemplateName) 选择 App 默认响应，路由/分组可以覆盖。错误表可以只在 Go 中维护，通过 svc.AppOptions 注册一次。上传和原始 body 的自动 Logic 参数、下载输出见 项目指南。

版本与迁移

CLI 与框架依赖固定使用 v0.14.1-preview。远程安装的 CLI 默认把自身版本写入 go.mod，不添加本地 replace；--framework-version 可显式指定已发布的兼容版本。仅在开发框架源码时使用本地替换：

# 在 go-omni 源码仓库中执行
go run ./cmd/go-omni new --module example.com/hello --framework-dir . ../hello

模板最低需要 v0.14.0-preview 的通用 Runtime、配置和绑定能力，继续使用 manifest v2；GORM 可选适配器从 v0.14.1-preview 提供。已有项目使用 定点升级与预览：原始模板可自动替换，含业务修改的基础文件按预览合并；通用清理由 Runtime 负责。独立工具命令不会被删除。受管理项目通过 .api 模块导入增加业务，不使用旧 add 命令的手动路由装配。

数据库迁移命令

保留独立迁移工具，应用启动不自动迁移：

go-omni migrate --dir migrations
# 检查预览，配置 GO_OMNI_DB_DSN 后显式应用
go-omni migrate --dir migrations --apply

SQL 命名示例 0001_createUsers.up.sql；预览只显示版本和 SHA-256，不连接数据库。失败保留 dirty 状态，不自动 down/force。细节见 扩展模块。