37 lines
3.1 KiB
Markdown
37 lines
3.1 KiB
Markdown
# API 契约生成阶段验收
|
||
|
||
日期：2026-09-23。目标已完成：从 `.api` 生成可运行项目、请求/响应 DTO、绑定校验、Handler、分组路由、Service / Repository 扩展位置与 OpenAPI；支持安全重复生成，保持业务与网络实现分离。
|
||
|
||
## 交付
|
||
|
||
- `api new` 可直接启动的问候项目；`new --api` / `api generate` 从自定义契约创建项目。
|
||
- `api go -api ... -dir ...` 别名、`api validate`、只读 `api generate --check`。
|
||
- 导入、分组、路径前缀、命名中间件、混合请求来源、类型与校验语义，详见 [API.md](../API.md)。
|
||
- `contract` 同源绑定与文档编译器，包括严格 JSON、缺失/零值、嵌套集合、精确整数默认值及约束。
|
||
- manifest 所有权、内容指纹、业务文件保留、过期生成文件清理、路径/符号链接/大小写保护及生成锁。
|
||
- `examples/contracts` 多分组示例、框架/CLI/生成项目文档。
|
||
- 实际联调发现并修复 native 在应用层提前返回 413 后仍等待未发送请求体的问题。现在放弃未读 body 并关闭连接，避免延迟响应或把 body 当成后续请求。Content-Length/chunked 两种 framing 均有回归测试；保留其他状态原有协议错误优先级。
|
||
|
||
## 检查结果
|
||
|
||
| 验证 | 结果 |
|
||
| --- | --- |
|
||
| `GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -p=2 -count=1 -timeout=240s ./...` | 39 个有测试的包全部通过；包含原有 memory/mysql × none/local/s3/r2/oss 共 10 种生成组合 |
|
||
| 生成后的独立消费者模块 | starter 与多分组 contract 项目均通过编译、race 和请求测试 |
|
||
| `go vet ./...` | 通过 |
|
||
| `go build ./...` | 通过 |
|
||
| `git diff --check` | 通过 |
|
||
| Parser fuzz（2 workers，4s 目标时长） | 69,457 次输入执行，通过 |
|
||
| 严格 body binder fuzz（2 workers，4s 目标时长） | 109,477 次输入执行，通过 |
|
||
| `python3 scripts/verifyAPI.py` | starter/contract × nethttp/native，4 组共 54 项检查通过 |
|
||
|
||
真实 HTTP 检查包括：就绪、文档与文件一致、问候接口、请求 ID、JSON/path/query/header 组合、false/0、必填和范围、重复标量、未知字段、尾随 JSON、413/415、认证 401、中间件顺序、成功 201/202/204、业务日志 requestId、SIGTERM 退出以及监听端口释放。更新契约后检查过期检测、重新生成和手写 Service 保留，再编译启动。
|
||
|
||
完整测试输出：[apiGenerationTests.txt](apiGenerationTests.txt)。真实服务报告及验收时源码 SHA-256：[apiGenerationLocal.json](apiGenerationLocal.json)。临时服务和消费者目录由验收脚本自动清理。
|
||
|
||
## 范围说明
|
||
|
||
本阶段是文档中列明的 go-zero 风格 `.api` 子集。未包含完整 goctl 语法、客户端 SDK、数据库模型生成、已有业务项目的自动迁移或线上发布。自定义 Service / 中间件初始为 501 占位，业务自行实现。
|
||
|
||
本轮使用本机临时服务、离线存储替身和已有测试。未连接业务服务器、未做云账号实网测试、未推送或创建发布标签。远程旧版本还不能使用这些新命令；当前通过本地框架 replace 验证。
|