56 lines
3.9 KiB
Markdown
56 lines
3.9 KiB
Markdown
# 统一启动配置与业务接入验收
|
||
|
||
2026-09-23，代码提交 `be620d2243ff85288f0afc44689c2e46abd714ec`。
|
||
|
||
`omni.New(omni.WithConfig(settings))` 现在通过 `Run`、`RunContext` 或 `ServeContext`
|
||
统一选择 nethttp、native 或实验 HTTP/2，加载 TLS 证书，并应用退出等待时间。
|
||
默认仍是 nethttp；HTTP/2 必须显式选择并配置 TLS，native 仍只支持 HTTP/1.1。
|
||
`RunWith` 继续支持自定义 Runner，由 Runner 管理自己的 TLS、超时及其他网络参数。
|
||
|
||
## 验证范围
|
||
|
||
| 场景 | 检查 |
|
||
| --- | --- |
|
||
| nethttp / native 明文；nethttp / native / HTTP2 TLS | 参考业务通过真实 TCP 执行 CRUD、分页、认证权限、参数错误、冲突和 404；校验响应及日志 requestId |
|
||
| 三种 TLS 启动 | 使用临时受信任证书，验证证书链及 ALPN；nethttp、HTTP2 为 h2，native 为 http/1.1 |
|
||
| 配置错误 | 未知适配器、HTTP2 缺 TLS、证书不配对、证书无法读取，在监听前失败且只清理一次 |
|
||
| 已有 listener / 自定义 Runner | 配置失败或取消时关闭 listener；自定义 Runner 入口继续独立于内置适配器选择 |
|
||
| 正常关闭 | 停止监听后，在途请求仍能成功完成，然后清理资源 |
|
||
| 关闭超时 | 取消请求、关闭连接并返回超时；不响应取消的 Handler 不会无限阻塞框架返回 |
|
||
| native 响应完成与关闭并发 | 在响应已经选择 Keep-Alive 后暂停写入，再触发关闭；响应写完后连接立即回收，退出无超时 |
|
||
|
||
框架无法强制终止不响应取消的业务 goroutine。业务仍需处理 context 取消；每个 native Server
|
||
只用于一次服务生命周期，重启时创建新实例，以免超时后的旧 Handler 与新实例混用。
|
||
|
||
## Linux 结果
|
||
|
||
Go 1.25.14、Linux amd64、`golang:1.25` 镜像的实际 image ID、完整命令与代码提交
|
||
记录于 [通过报告](transportStartupLinux.json)，[原始输出](transportStartupLinux.txt) 的 SHA-256 已核对。
|
||
|
||
- 全仓库 `go test -race -p 1 -count=1 -timeout=3m ./...`、`go vet -p 1 ./...`、`go build -p 1 ./...` 通过。
|
||
- 上表的配置、TLS 业务、退出和 native 并发回收测试重复 10 次，全部通过。
|
||
- 单个验证容器限制为 2 核、2 GiB 内存、同额 memory-swap（无额外 swap）、256 个进程/线程，GOMAXPROCS=2。
|
||
- Docker inspect 已确认限制生效，代码只读挂载，没有发布端口；测试流量仅访问容器内 loopback。
|
||
- 总时限 480 秒；完成后验证容器已删除，之前运行的 7 个业务容器仍在运行。
|
||
|
||
首轮重复测试曾在 native 排空阶段失败，记录保留在
|
||
[修复前报告](transportStartupBeforeFixLinux.json) 和 [修复前输出](transportStartupBeforeFixLinux.txt)。
|
||
原因是响应写入和关闭并发时，连接转为空闲后可能再次等待 Keep-Alive 请求，直到关闭超时。
|
||
新增暂停响应写入的确定性测试在修复前失败；修复将“转为空闲”和“判断是否关闭”置于同一临界区，
|
||
最终报告包含修复后的重复回归。首轮失败不计作通过证据。
|
||
|
||
## 本地与脚手架
|
||
|
||
macOS arm64、Go 1.27.1 的全仓库 race、vet、build 通过；app/native 包额外重复 10 次 race 检查通过。
|
||
实际生成的独立业务模块通过以下入口验证 native 启动、HTTP 请求、SIGINT / SIGTERM、退出码 0、
|
||
端口关闭，以及 `omni.New().Run` 的资源清理回调：
|
||
|
||
```sh
|
||
go build -o /tmp/go-omni-startup-cli ./cmd/go-omni
|
||
python3 scripts/verifyScaffold.py --cli /tmp/go-omni-startup-cli --framework-dir . --transport native
|
||
```
|
||
|
||
独立模块通过本地 replace 引用被测源码；这不表示旧的 `v0.6.0-preview` 发布标签已包含新增配置。
|
||
本轮是功能、并发和生命周期验收，没有重新进行 30 分钟长测，也不代表 native 已合并 HTTP/2
|
||
或已经在真实业务环境发布。下一步是业务试用及 native 多协议监听器的独立设计与验收。
|