go-omni/ROADMAP.md

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 响应已支持标准 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。
• 已验证 MaxConnections 满载时快速拒绝新连接、请求完成后释放容量；后续仍需在目标部署环境观察文件描述符、内核 socket 缓冲和反向代理联动。
• 已用 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 回收正常。
• 自动验收入口：python3 scripts/verifyPerformance.py；Linux 固定验收入口：python3 scripts/verifyLinux.py --load --tls --duration 30m。真实部署仍需按目标代理和内核参数执行 30 分钟发布前压测。

以上阶段以验收结果判断完成。当前仍是基础框架试用阶段；MySQL、适配层契约和一次业务模块试用已完成，自研网络层已有可运行预览，稳定性与生产规模验证尚未完成。