85 lines
13 KiB
Markdown
85 lines
13 KiB
Markdown
# GoOmni 成熟度计划
|
||
|
||
## 1. 新项目启动与发布流程（已完成，v0.1.1）
|
||
|
||
- 修正脚手架固定版本引用，保留显式本地开发选项。
|
||
- 生成服务处理退出信号，等待请求完成后清理资源。
|
||
- 验收：源码目录外安装远程 CLI → 生成无 replace 的项目 → 编译 → 请求健康接口和业务接口 → SIGINT/SIGTERM 正常退出。
|
||
- 自动验收入口：`python3 scripts/verifyScaffold.py --version v0.1.1`。
|
||
- 已通过全量 race 测试、vet、build，以及从远程提交安装 CLI 后的无 replace 端到端验收；覆盖生成服务和 `App.Run` 的两种退出信号。
|
||
|
||
## 2. 业务数据接入（已完成，v0.2.0）
|
||
|
||
- 数据库初始化、Repository 和 ServiceContext 组合成完整业务启动流程。
|
||
- Readiness 注册数据库探针，启动失败与服务退出时清理连接池。
|
||
- 验收：真实数据库 CRUD、事务回滚、数据库不可用时 readiness 返回 503。
|
||
- `go-omni new --database mysql` 已生成完整数据接入流程，默认内存模式仍然可用。
|
||
- 独立 MySQL 8.4 容器已验证 CRUD、唯一邮箱、分页、服务重启持久化、事务提交与错误/panic/取消回滚。
|
||
- 已验证初始化失败、缺少表结构、正常退出时关闭连接池，以及数据库停止后的 readiness 503、恢复后的 200。
|
||
- 自动验收入口：`python3 scripts/verifyDatabase.py --version v0.2.0`；结束后清理本次测试容器、匿名卷和临时项目。
|
||
|
||
## 3. 网络适配一致性（已完成，v0.4.0）
|
||
|
||
- 标准库适配器运行公共契约测试，并为自研网络层保留相同的接入边界。
|
||
- 覆盖路由参数、分组、中间件、错误响应和取消传播。
|
||
- 验收：切换适配器后，业务 Handler 和 Service 无需修改，约定的 HTTP 行为一致。
|
||
- 新增公共 `transport/transporttest.Run`，自研适配器可直接复用；覆盖静态 / 参数 / 通配路由、分组、405 Allow、鉴权短路、错误与 panic、响应提交、requestId、并发隔离、截止时间及真实客户端取消。
|
||
- 标准库路由实现明确的路径、方法、尾部斜杠、通配参数、Any 和 404/405 约定；不再引入 Gin 依赖。
|
||
- 完整用户 CRUD 已用标准库适配器验证；自研适配器可直接复用同一公共契约测试包。
|
||
- 自动验收入口：`python3 scripts/verifyTransports.py --version v0.4.0`，从源码目录外消费远程版本与公共契约测试包。
|
||
|
||
## 4. 实际业务试用（已完成，v0.4.0）
|
||
|
||
- 在独立业务目录生成 billing service，先固定远程 `v0.2.0`，再升级到 `v0.4.0`，全程无本地 replace。
|
||
- 验证环境配置、结构化访问日志、requestId 关联、参数校验、业务错误映射、CRUD、优雅退出和升级后的 race 测试。
|
||
- 业务试用没有要求修改 Handler / Service；现有公共 API 足以支撑一套分层业务模块。
|
||
- 自动验收入口：`python3 scripts/verifyBusiness.py --version v0.4.0`。
|
||
|
||
## 5. 自研网络层、稳定性与性能基线（v0.6.0-preview 验收完成）
|
||
|
||
- 已加入标准库路由和完整 GoOmni 请求链 benchmark，输出分配次数和耗时，作为未来自研网络层的对照基线。
|
||
- 新增 `transport/native` 第一版自研 HTTP/1.1 服务端：自行管理 TCP listener、Keep-Alive、Content-Length / chunked 请求解析、响应写回、读写超时和优雅关闭；通过 `App.RunWith` 接入，业务 Handler / Service 保持不变。
|
||
- 标准库与 native 共用 TCP benchmark，固定 1 / 32 / 128 并发；相同应用、客户端、超时和响应检查，避免两个测试入口逐渐失去可比性。
|
||
- 新增独立服务进程压测 `internal/perfcheck`，记录成功吞吐、P50/P95/P99、服务端分配、采样堆峰值，以及 128 / 1,024 条空闲长连接的堆内存、goroutine 和断开后的回收情况。原始报告保存在 `performance/tcpBaseline.json`。
|
||
- native 已支持受 `MaxBodyBytes` 约束的 `Content-Length` / chunked 请求体，仍使用标准 `http.Request` / `http.ResponseWriter` 作为桥接；解析器、连接抽象和生产压测将在后续阶段继续下沉。
|
||
- native 请求体已改为流式读取，Handler 可边到边处理，服务端只在 Handler 返回后排空剩余 body，超时、畸形和超限 body 会取消请求并关闭连接。
|
||
- native 响应已支持标准 `http.Flusher`；HTTP/1.1 流式响应使用 chunked framing，普通响应继续走 `Content-Length`，HTTP/1.0 回退到关闭连接分帧。
|
||
- native 长请求已补客户端断开及流式写失败取消，监测退出后再复用 Reader；已验收普通/流式断开、慢 Handler 后连续 Keep-Alive 和管线数据不被误消费。短请求延迟启动监测，已有管线数据时取消依赖后续写失败或 Handler 返回。
|
||
- 已补充慢请求头、慢 Content-Length body、慢 chunked body、慢 TLS 握手、大请求体、HTTP/1.0 Keep-Alive、HEAD/204 和管线请求验收；Linux/arm64 容器已通过全量 race、vet、build，以及 3 秒 TLS 并发/空闲连接矩阵。原始报告见 [tlsBaselineLinux.json](performance/tlsBaselineLinux.json)。
|
||
- 已验证 `MaxConnections` 满载时快速拒绝新连接、请求完成后释放容量；后续仍需在目标部署环境观察文件描述符、内核 socket 缓冲和反向代理联动。
|
||
- 已验证 `MaxConcurrentRequests` 满载返回 503，活动请求结束后槽位释放，后续请求可以恢复处理。
|
||
- native `Stats()` 已记录连接和请求过载拒绝数；访问日志已支持可信代理网段配置，默认拒绝伪造的 `X-Forwarded-For`。
|
||
- native TLS 已明确只宣告 HTTP/1.1 ALPN；HTTP/2 暂由边缘代理终止或使用 `transport/nethttp`，已整理独立协议设计、流控和压测门槛，见 [native HTTP/2 进入条件](transport/native/HTTP2.md)，完成后再接入 native。
|
||
- 已加入独立 `transport/http2` 实验 Runner，验证 h2c/TLS h2、连接上限、全局请求并发拒绝和恢复，以及 GOAWAY 排空、RST_STREAM 单流取消和服务关闭超时；它使用 `x/net/http2` 作为临时帧/流控实现，已完成下述 Nginx HTTP/2 回源联调，尚未接入 native 默认路径。
|
||
- HTTP/2 实验已补齐头部/请求体上限、128 路同连接多路复用、慢读取流控、协议错误、RST_STREAM 与 GOAWAY 统计，并提供 `scripts/verifyHTTP2.py --duration 30m` 的 Linux TLS 长测入口；长测默认不启用 race，短时并发检查使用 `--race`（默认 60 秒）。测试容器默认限制为 2 核、2 GiB 内存、256 个进程/线程，并设总时限和退出清理；受限长测和 Nginx 回源联调结果见下方。
|
||
- 新 Linux amd64 环境在上述硬上限内完成 HTTP/2 普通模式 2 分钟与 race 模式 60 秒短测，分别为 3,885,273 和 377,788 次请求，均为 0 失败；连接/请求归零、FD 回到基线。SIGTERM、SIGHUP 和总时限退出清理已实测。报告见 [HTTP/2 短测记录](performance/http2SmokeLinux.json)；此前无资源上限的 race 长测因 RSS 增长而停止，不作为通过依据。
|
||
- 已完成受限的 HTTP/2 单连接 TLS 30 分钟长测：128 个 worker、58,102,476 次请求、0 失败及协议错误；包含客户端与服务端的采样 RSS 峰值约 22.6 MiB，连接/活动请求归零，FD 由 9 回到 6。120 份定时采样见 [HTTP/2 长测报告](performance/http2SoakLinux.json)，测试提交和原始日志校验值保存在报告中。Nginx HTTP/2 回源的 GOAWAY/排空结果见下方。
|
||
- 已完成 8 条 TLS 连接、128 个 worker 的 30 分钟混合长测：53,079,128 次普通请求、106,971 次慢上传、5,588 次慢下载，0 失败及协议错误。采样 RSS 峰值约 116.6 MiB（包含客户端和服务端），前段与最后 5 分钟 RSS 中位数分别约 111.3/110.4 MiB；退出后活动连接/请求归零，goroutine 2、FD 6 均回到基线，两次 GC 后存活堆约 450 KiB。原始日志、120 份采样、测试提交和校验值见 [混合长测报告](performance/http2MixedSoakLinux.json)。
|
||
- 已补连接级窗口耗尽时的暂停、同连接 204/跨连接隔离、WINDOW_UPDATE 恢复和连接复用；已补零窗口写阻塞在关闭超时后的解除阻塞、请求取消与回收。Linux amd64 的 HTTP/2 全包 race、vet、build 已通过，见 [边界回归报告](performance/http2FlowControlLinux.json)。
|
||
- 新增 HTTP/2 零 stream 窗口时的慢响应隔离、WINDOW_UPDATE 恢复、RST_STREAM 取消与请求槽位回收测试；补充 TLS 半开握手占满连接上限时的及时拒绝、超时回收及正常请求恢复测试。
|
||
- 已完成 Nginx 1.30.5 → HTTP/2 的 TLS 回源联调：普通与 race 模式各 3 轮，共 18 个子场景通过；覆盖两段证书校验、32 次 POST 复用一条回源连接、不可信 CA/主机名拒绝、504 超时、客户端取消、GOAWAY 后旧 POST 完成及 20 个新 POST 转入新实例，无重复业务执行。见 [验收说明与报告](transport/http2/PROXY.md)。
|
||
- `scripts/verifyHTTP2Proxy.py` 顺序运行受限编译容器和禁用外部网络的测试容器；总时限、SIGTERM、SIGHUP 清理已在 Linux 实测，原有 7 个业务容器仍运行。当前结果不覆盖 Nginx master/worker 重载或 Cloudflare 实网部署。
|
||
- 已接入 `omni.New` 的统一 transport / TLS / shutdownTimeout 配置：默认 nethttp，可显式选择 native 或实验 HTTP/2；证书在监听前加载，HTTP/2 配置必须启用 TLS。`RunWith` 继续支持自定义网络层，业务不依赖具体适配器。
|
||
- 参考业务已增加五种真实 TCP/TLS 组合的 CRUD、认证权限、错误响应、requestId 日志与协议协商测试；三种适配器共用排空和超时退出测试。修复 native 退出时过早取消在途请求，并使关闭超时错误返回调用方。下一步仍为业务环境试用、native 多协议监听器设计与接入回归，HTTP/2 保持实验状态。
|
||
- 统一启动已通过 Linux 全仓库 race/vet/build 及关键场景 10 次重复验证；修复了重复测试发现的 native 活动连接转为空闲时错过关闭的竞态，并保证不响应取消的 Handler 不阻塞关闭超时返回。脚手架独立项目的 native SIGINT/SIGTERM 验证通过；失败复现与最终验收证据见 [统一启动验收](performance/transportStartup.md)。
|
||
- 已用 16 个并发 worker 完成 3,200 次建连/断连 race 验收；MaxConnections 满载拒绝、槽位释放和 TLS 连接上限均已覆盖。
|
||
- 新增 `scripts/verifyLinux.py`，固定在 Go 1.25 Linux 容器内运行 race、vet、build 和可选 TLS/非 TLS perfcheck；perfcheck 记录堆、goroutine、连接和 Linux 文件描述符。
|
||
- Linux/arm64 已完成 30 秒、128 并发、512 空闲连接的 TLS 与非 TLS 持续回归，报告见 `performance/linuxSoak.json` 和 `performance/linuxSoakTLS.json`，均为 0 错误且连接、goroutine、FD 回收正常。
|
||
- 目标 Linux amd64 服务器已完成 30 分钟、128 并发、512 空闲连接的 TLS 验收：net/http 约 11,865 req/s、native 约 13,098 req/s，均为 0 错误；native P95/P99 为 44.040/52.429 ms，空闲连接堆增量约 4.50 MiB，FD 由 7 增至 519 后回到 7。
|
||
- 新增 `scripts/verifyProxy.py`，在 Linux Docker 中用 Nginx 反向代理 native TLS 服务，检查真实 TLS、Keep-Alive、上游超时和 native 优雅关闭。
|
||
- 自动验收入口：`python3 scripts/verifyPerformance.py`；Linux 固定验收入口：`python3 scripts/verifyLinux.py --load --tls --duration 30m`；代理联调入口：`python3 scripts/verifyProxy.py`。
|
||
|
||
## 6. 可复用业务基础模块（第一版）
|
||
|
||
- `cache`：有界 LRU 内存缓存、TTL、数据复制、同进程合并回源；`cache/redis` 适配 go-redis 客户端，保留借用连接池的生命周期边界。
|
||
- `httpc`：复用出站连接、每目标主机连接上限、覆盖响应体的总超时、保守重试、requestId 传递、JSON 响应大小限制与安全日志字段。
|
||
- `middleware`：有容量上限的令牌桶限流；按已认证身份隔离的幂等保护，覆盖冲突、处理中记录、失败记录、容量与请求/响应大小上限；协作式请求 deadline。
|
||
- `task`：固定 worker、有界队列、任务超时、panic 隔离、间隔调度、不重叠执行、停止接收与排空/取消。
|
||
- `go-omni add`：向已有项目生成 Handler / Service / Repository / Model 和模块注册入口；目标存在时拒绝覆盖，默认内存 CRUD 可注入持久化 Repository。
|
||
- `examples/modules` 将以上运行时能力串联，使用真实 TLS 在 nethttp、native、实验 HTTP/2 下验证缓存、出站 requestId、认证、幂等、后台任务与退出。
|
||
- 使用文档：[业务基础模块](MODULES.md)。验证入口：`GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race ./...` 和 `python3 scripts/verifyModules.py`；Linux runner 顺序运行全量检查及独立 Redis 容器，硬限制 2 CPU / 2 GiB / 256 pids。
|
||
- 最终代码已通过 Linux amd64 全仓库 race/vet/build、独立生成项目 CRUD、真实 Redis 7.4.11 与三种网络层 TLS 组合测试；测试容器清理完成、原有 7 个业务容器仍运行。提交、源码摘要与完整输出见 [验收记录](performance/modulesAcceptance.md)。
|
||
- 当前幂等、限流、任务调度和合并回源均为单进程能力；Redis 仅提供缓存存储，不代表已实现分布式去重、任务持久化或跨副本选主。eTax 指定业务模块接入依用户要求暂缓。
|
||
|
||
以上阶段以验收结果判断完成。当前仍是基础框架试用阶段；MySQL、适配层契约和一次业务模块试用已完成，自研网络层已有可运行预览，稳定性与生产规模验证尚未完成。
|