go-omni/performance/apiDeveloperExperienceAcceptance.md

API 错误、鉴权声明与开发体验验收

目标版本：v0.7.0-preview.1。本轮修改 CLI 和示例，不改变网络适配器或业务 Service 的调用接口。

完成范围

• .api 集中声明业务错误，可通过 import 拆分；组级继承、路由追加/清空，生成错误码常量和每次返回新实例的 apierrors 函数。
• bearer、header API key、cookie API key 声明关联实际命名中间件；鉴权先于普通中间件执行，支持单接口覆盖和公共接口。
• OpenAPI 同步安全方案、401/403/409 等响应、同状态多个错误示例及业务错误码；支持接口描述、标签、弃用标记。
• 项目根目录自动发现契约入口；api inspect 查看路由，api export 输出文档，api generate --dry-run 预览文件变更。
• 用户示例使用同一份错误声明，并增加只读凭证，实际覆盖未认证 401、写入被拒绝 403、重复邮箱 409。

本地验证

• 完整框架 GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -p=2 -count=1 -timeout=300s ./...：39 个有测试的包通过。
• 包含 10 种 API 基础设施组合、10 种既有 CRUD 模块组合，以及新增的错误/鉴权消费者项目实际编译、运行与 race 检查。
• CLI 最后补充路径参数前缀回归（:id 和 :idLong），再次执行 go test -race ./cmd/go-omni/... 通过。
• go vet ./...、go build ./... 和格式/差异检查通过。
• 现有 API 真实 HTTP 回归在 nethttp/native 共 54 项通过。
• 用户示例在真实临时 MySQL 下，nethttp/native 共 34 项 HTTP、业务和生命周期检查通过；事务提交/回滚、初始化失败清理等测试同时通过。
• 检查鉴权优先顺序、未实现 hook 拒绝放行、缺失 hook 时不注册任何路由、公共接口覆盖、多鉴权方案和错误实例独立性。
• 检查只读预览不创建目录/锁文件、不改变文件；重复生成保留业务实现；无效声明报告源文件位置；恶意 manifest 路径被拒绝。

证据：完整框架测试、本地业务报告、API 基础回归。

远程版本验证

发布后执行以下命令，从全新 module cache 下载 CLI 和框架，验证固定版本且没有本地 replace 的业务项目：

python3 scripts/verifyAPIWorkflow.py --version v0.7.0-preview.1 \
  --report performance/apiDeveloperExperienceRemote.json

远程结果在实际完成后记录；本地通过不代替远程下载验证。

边界

鉴权声明负责文档及路由中间件装配；凭证校验、登录和权限策略仍由业务 hook 实现。新 hook 默认返回 501，不会自动放行。 错误声明不会自动映射数据库错误，也不会拦截运行时返回；Service 需要使用对应错误函数。 本版每个接口只选择一个认证方案，不含 OAuth2 scopes、组合认证或 SDK 生成；现有 .api 继续支持，新声明需升级 CLI。

验收只使用本机临时服务和 MySQL 容器，限制 1 CPU / 768 MiB、绑定 localhost，结束删除临时资源；未使用业务服务器。 OSS/R2 云账号验收与网络层长时间压力测试不属于本轮。