66 lines
4.1 KiB
Markdown
66 lines
4.1 KiB
Markdown
# go-omni CLI
|
||
|
||
v0.14 新增 `api format [--check]`、`api upgrade [--dry-run|--preview <空目录>|--apply]`，以及 `workspace format|generate|check --file omni.workspace.json`。详见 [通用开发指南](../../DEVELOPMENT.md)。
|
||
|
||
新项目采用根目录 `main.go` 与 `internal/config、svc、logic、handler、types`。完整职责、启动扩展、流式接口和生成文件边界见 [项目指南](../../PROJECT.md)。
|
||
|
||
## 创建项目
|
||
|
||
```sh
|
||
# 仓库读取权限与 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` 定义。认证与存储路径由项目实现。
|
||
|
||
## 日常生成
|
||
|
||
```sh
|
||
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 ./...` 验证。完整行为见 [契约变更提示](../../PROJECT.md#契约变更提示)。
|
||
|
||
`@app(defaultResponse: TemplateName)` 选择 App 默认响应，路由/分组可以覆盖。错误表可以只在 Go 中维护，通过 svc.AppOptions 注册一次。上传和原始 body 的自动 Logic 参数、下载输出见 [项目指南](../../PROJECT.md)。
|
||
|
||
## 版本与迁移
|
||
|
||
CLI 与框架依赖固定使用 v0.14.1-preview。远程安装的 CLI 默认把自身版本写入 go.mod，不添加本地 replace；`--framework-version` 可显式指定已发布的兼容版本。仅在开发框架源码时使用本地替换：
|
||
|
||
```sh
|
||
# 在 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 提供。已有项目使用 [定点升级与预览](../../DEVELOPMENT.md#v013-项目升级)：原始模板可自动替换，含业务修改的基础文件按预览合并；通用清理由 Runtime 负责。独立工具命令不会被删除。受管理项目通过 `.api` 模块导入增加业务，不使用旧 `add` 命令的手动路由装配。
|
||
|
||
## 数据库迁移命令
|
||
|
||
保留独立迁移工具，应用启动不自动迁移：
|
||
|
||
```sh
|
||
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。细节见 [扩展模块](../../ADVANCED.md)。
|