k2safe
7670b222ac
Define reusable response bodies in .api with typed code mappings, per-route overrides and matching OpenAPI schemas. Add application and callback encoders, early response policy selection, and isolated remote-consumer release verification. Release v0.8.0-preview after full race, vet, build and local MySQL workflow acceptance.
42 lines
4.4 KiB
Markdown
42 lines
4.4 KiB
Markdown
# 公共响应模板验收
|
||
|
||
版本 `v0.8.0-preview`。本报告记录实现验收与发布验证，旧版本标签保持不变。
|
||
|
||
## 实现范围
|
||
|
||
- `.api` 定义具名公共响应体，可跨文件导入、分组引用、接口覆盖；业务类型放入 `${data}`。支持嵌套 JSON、独立 errorBody、固定字段与类型保持的占位符。
|
||
- 数字/字符串错误码、默认码、按逻辑码映射、消息映射、null/省略行为可配置；OpenAPI 同步结构、类型和真实错误示例。
|
||
- `@response raw` 成功返回原始业务 JSON，错误继承组级模板。文本、XML及特殊状态的回调通过 Go 编码器实现，不冒充 `.api` 已支持任意媒体类型。
|
||
- 应用之间的配置独立；创建/快照深复制；空对象模板序列化后保持有效，非法占位符、配置冲突、循环和过深结构拒绝。
|
||
- 接口策略在全局中间件前设置；提前拒绝、panic、Context 克隆和错误边界使用正确策略。显式 JSON/Text/XML/Bytes/NoContent 绕过包装，已提交响应不追加内容。
|
||
- 内置路由 404/405 使用应用默认格式。网络层进入应用前的 TLS/HTTP协议错误仍由 transport 处理。
|
||
|
||
## 验证结果
|
||
|
||
1. `GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -p=1 -count=1 -timeout=300s ./...`：40 个有测试的包全部通过。
|
||
2. 首轮 `-p=2` 的原有 S3 fixture 测试遇到 10 秒 deadline；单包复跑通过，随后上述串行全量复跑通过，未修改 S3 实现或放宽断言。
|
||
3. 专项集成生成临时消费者项目，执行真实生成路由和业务 Service：具名公共体、数字 401、路由覆盖、raw JSON、错误文档，以及重复生成业务文件保护通过。
|
||
4. App 在 nethttp/native 的真实 TCP 请求中验证配置响应、callback panic 和超时；并发应用配置隔离、克隆、全局中间件提前拒绝及已提交响应保护通过。
|
||
5. 原有 API 实际 HTTP 回归 54 项通过：starter 两种 transport 各 6 项，contract 两种 transport 各 21 项；见 [回归报告](responsePoliciesAPI.json)。
|
||
6. `go vet ./...`、`go build ./...`、示例 `.api` validate/inspect、差异空白检查通过。既有用户示例重新生成及 `--check` 通过，28 份原有业务文件保持不变；go.mod 显式升级目标版本并继续使用本地 replace。
|
||
|
||
完整框架记录见 [race 测试](responsePoliciesTests.txt)。本轮仅使用本机临时目录和回环监听，没有连接业务服务器，没有执行远程云存储/数据库验收或压力长测。远程模块下载验收需发布后另行完成。
|
||
|
||
## 使用入口
|
||
|
||
[公共响应说明](../RESPONSE.md) 与 [可生成的 .api 示例](../examples/contracts/responses.api)。远程使用请安装同版本 CLI 和框架；源码开发可带 `--framework-dir`。
|
||
|
||
## 后续：类型名与业务字段统一
|
||
|
||
`codeType` 新增 `int32` / `int64`，保留 `string` 与旧 `integer`；int32/int64 使用各自有符号整数范围，默认码和映射都校验。OpenAPI 为 integer + 对应 format。配置 JSON/YAML、生成项目的 int64 数值保留完整精度。
|
||
|
||
本次增量运行根包、response、config、httpx、openapi、CLI/apigen/scaffold 共 8 个包的 race 测试及生成消费者集成，全部通过。覆盖边界/越界、小数拒绝、int64 最大值真实输出、配置精度、平铺/嵌套文档和旧 integer 兼容。vet、全模块 build、示例 validate 与差异检查通过；见 [类型测试记录](responseCodeTypesTests.txt)。上方全量及 HTTP 报告是此前公共响应体验收，此次未重复远程或数据库验收。
|
||
|
||
## v0.8.0-preview 封版前验证
|
||
|
||
- 最终代码全量 race 通过：40 个有测试的包；包括源码 CLI 的生成消费者、完整 int64 输出和模板配置回归，见 [封版测试记录](responseReleaseTests.txt)。
|
||
- `go vet ./...`、`go build ./...`、格式检查、差异检查和 userService `api generate --check` 通过。
|
||
- 本机隔离 MySQL 下，nethttp/native 共 34 项 HTTP、业务和生命周期检查通过；数据库事务提交/错误回滚/panic回滚/取消回滚、初始化清理和迁移通过。
|
||
- 重生成保留 29 份开发者文件，见 [封版本地业务报告](responsePoliciesWorkflowLocal.json)。临时容器已清理。
|
||
- 发布后将使用 `verifyResponseRelease.py` 和 `verifyAPIWorkflow.py --version v0.8.0-preview` 验证真实远程 CLI、无本地 replace 的模块、公共模板及完整业务流程。标签不随验收记录变动。
|