6.7 KiB
go-omni CLI
v0.28.1 的 workspace generate/check 支持 API 与通用工程混合处理。每个 services 项可指定 kind: api | project，省略时按工程清单识别，旧 API 配置继续有效。format 只处理 API 契约，通用工程显示 SKIP；check 只读并汇总各工程失败。见 可运行示例。
v0.28 新增 project new/generate/check：生成无 API、无监听端口和无外部服务依赖的通用 Go 程序，配置/日志/生命周期自动装配，项目维护 svc 与 Run。project generate --dry-run 预览，project check 只读检查；详见 通用工程指南。
v0.26 新增 i18n check|export|types|extract：检查独立语言资源、提取 Go 静态消息引用或已导出的错误目录，导出指定命名空间的前端包和 TypeScript 类型。输入只读，结果写 stdout；动态引用明确报告。完整命令见 国际化工具链。.api errorCatalog 可声明 translation 引用，旧 runtime 在生成前拒绝，接入时使用当前同版 CLI 与框架。
v0.19 移除结构映射生成：omni.gen.json 只保留 Repository 和中间件选项。普通接口直接使用生成 DTO；需要类型转换时用普通 Go 或可选 copyx。旧 mappings / mappingFiles 必须按迁移步骤清理，CLI 不会静默删除仍在调用的旧生成文件。
公共字段组合、中间件工厂和按需 Repository 继续支持，见 生成能力指南。
v0.16 增加基础类型/动态 JSON 数组返回、OpenAPI 公共引用和 workspace Go Catalog 统一导出。见 接入与筛选规则。
v0.14 新增 api format [--check]、api upgrade [--dry-run|--preview <空目录>|--apply]，以及 workspace format|generate|check --file omni.workspace.json。详见 通用开发指南。
API 新项目采用根目录 main.go 与 internal/config、svc、logic、handler、types。完整职责、启动扩展、流式接口和生成文件边界见 项目指南。
创建 API 项目
# 仓库读取权限与 PATH 配置见根目录 README
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.28.2-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；中间件工厂未实现时阻止启动，既有 handler 模式仍返回 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 定义。认证与存储路径由项目实现。
响应 DTO 支持自引用及相互引用，生成强类型 Go 字段与 OpenAPI $ref；见递归响应示例。请求递归仍会报错。
日常生成
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.28.2-preview。远程安装的 CLI 默认把自身版本写入 go.mod，不添加本地 replace；--framework-version 可显式指定已发布的兼容版本。仅在开发框架源码时使用本地替换：
# 在 go-omni 源码仓库中执行
go run ./cmd/go-omni new --module example.com/hello --framework-dir . ../hello
当前模板与依赖以 v0.28.2-preview 为基线，继续使用 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。细节见 扩展模块。
v0.22 文件显式配置
新生成 internal/config/loadGen.go 调用统一加载，纳入生成检查；项目 config.go 只维护字段、默认值和校验，loader.go 用于注册额外格式。JSON/YAML/XML 内置。旧手写 Load 会阻止生成，请先按 迁移步骤 整理，不会自动覆盖业务代码。
go run . -config etc/config.test.yaml -check-config 只做配置解析和校验，不初始化日志、数据库或监听。文件中的固定值不受环境自动覆盖；${NAME} 为必填引用，${NAME:-fallback} 提供备用值。