# v0.7.0-preview.1

这一版完善接口开发体验：业务错误和鉴权可在 .api 中声明，代码调用与 OpenAPI 同步；增加路由总览、文档导出和无写入的生成预览。
预览版用于固定版本试用；API 方言有明确范围，HTTP/2 仍是独立实验适配器。

## 安装与开始

```sh
GOPRIVATE=git.yuntuo.hk go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.7.0-preview.1

go-omni api new --module example.com/demo ./demo
cd demo
GOPRIVATE=git.yuntuo.hk go mod tidy
go run ./cmd/server
```

需要该 Git 仓库的读取权限时，通过自己的 Git 凭据管理器配置；不要将凭据写入 module path 或 go.mod。
CLI 会将自身下载版本固定到生成项目的 go.mod。业务项目正常使用远程模块，不需要本地 replace。

使用已有定义，并一次选择基础模块：

```sh
go-omni new --api user.api --module example.com/userService \
  --database mysql --storage local --log-output file ./userService
```

MySQL 与存储需要按生成 README 设置环境变量。任意契约生成的业务方法先返回 501，
由业务方实现；可直接参考 [完整用户示例](examples/userService/README.md)。

## 主要变化

- `error (...)` + `@errors` 声明业务错误，生成 `apierrors.EmailTaken()` 等全新实例构造函数和错误码常量。
- `auth Name (...)` + `@auth` 同步 OpenAPI security 与实际路由中间件，声明本身不替代凭证验证。
- 多行 `@doc` 支持 description/tags/deprecated；一个状态可有多个业务错误示例。
- 项目内直接 `api inspect`、`api export`、`api generate --dry-run`，无需重复指定入口文件。

此前 v0.7.0-preview 已提供：

- `.api` 生成项目、绑定/校验、路由、业务骨架和 OpenAPI；支持分组、导入、命名中间件。
- 同一入口初始化 MySQL、日志、Local / S3 / R2 / OSS；标准 context 与 httpx 保持业务/网络分离。
- 生成器保护手写业务文件，校验自有文件哈希，支持只读 --check；基础设施选项持久化到 manifest。
- 完整用户示例包含数据库迁移、CRUD / 分页、事务审计、鉴权、文件导出与 requestId 日志。
- 日志文件轮转/结构化脱敏、上传策略/直传/分片，以及此前 main 分支的通用业务模块一并提供。

所有变化及网络层验收记录见 [CHANGELOG](CHANGELOG.md)。

## 升级注意

1. 将 CLI 和项目框架依赖固定为相同版本。旧版 CRUD 项目继续使用现有目录；不能直接用 API 生成器接管已有 Go 目录。
2. Gen.go 由生成器维护，业务实现/配置/迁移由项目维护。新增 API 后执行 generate 和 go test；修改或删除类型需要同步处理自己的业务代码。
3. `.goOmni/apiManifest.json` 需随代码提交。切换数据库或存储选项时，在新目录生成对照后迁移；重新生成不会改写现有基础设施文件。
4. 配置使用 lowerCamelCase。DSN、Token、存储密钥由环境变量提供；`database.Config` 的 DSN 不会被 JSON/YAML 序列化。
5. 旧 `.api` 仍可解析。新语法需要本版 CLI；生成的错误函数沿用已有框架错误类型。旧 CLI 无法解析新增声明，请一起升级。鉴权引用的已有 hook 和业务函数仍保留，不会自动重写。
6. API 的 none/memory 数据库选项仅表示不打开连接，不会从 HTTP DTO 自动推导内存仓库或数据表。

## 验证入口

```sh
GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -p=2 -count=1 -timeout=300s ./...
go vet ./...
go build ./...
python3 scripts/verifyAPIWorkflow.py --report performance/apiDeveloperExperienceLocal.json
python3 scripts/verifyAPIWorkflow.py --version v0.7.0-preview.1 \
  --report performance/apiDeveloperExperienceRemote.json
```

最后一项在全新 module cache 安装远程 CLI，并验证无本地 replace 的项目生成、
真实 MySQL、nethttp/native 启动与业务流程。容器只使用本机临时资源，结束时清理。
本轮验收见 [接口开发体验报告](performance/apiDeveloperExperienceAcceptance.md)；此前业务闭环见 [API 业务验收](performance/apiWorkflowAcceptance.md)。

OSS/R2 云端仍需项目自己的账号做上线环境验收；当前云端适配器检查不等同于这些账号的实网测试。