3.7 KiB
go-omni CLI
新项目采用根目录 main.go 与 internal/config、svc、logic、handler、types。完整职责、启动扩展、流式接口和生成文件边界见 项目指南。
创建项目
# 仓库读取权限与 PATH 配置见根目录 README
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.12.0-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.12.0-preview。远程安装的 CLI 默认把自身版本写入 go.mod，不添加本地 replace；--framework-version 可显式指定已发布的兼容版本。仅在开发框架源码时使用本地替换：
# 在 go-omni 源码仓库中执行
go run ./cmd/go-omni new --module example.com/hello --framework-dir . ../hello
新模板需要 v0.12.0-preview 的流式能力与 manifest v2。不兼容旧目录，旧生成项目请在新目录重新生成后移入业务代码，不覆盖手写 main。独立工具命令不会被删除。受管理项目通过 .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。细节见 扩展模块。