go-omni/CHANGELOG.md

Changelog

v0.10.0-preview

• 新增 App/路由独立错误目录：omni.WithErrors、errors.Catalog、ByCode 与不可变 Registry，业务只选逻辑标识；对外码和提示由项目配置。
• 默认 HTTP 状态与逐项覆盖均可配置，包括 HTTP 200 的业务失败；错误模板、RawJSON、日志、业务失败指标、链路、标准中间件桥接和幂等重放保留失败语义。
• .api errorCatalog 同源生成 Catalog、独立错误函数、路由目录和 OpenAPI；允许重复对外码、不同路由不同码类型、公共契约导入。旧 error 声明也允许 HTTP 200。
• 同一 200 的成功/错误响应使用 anyOf 保留两种 schema，错误示例保持各自提示；自定义 Encoder 和直接输出继续支持。
• 目录校验类型、范围、状态和冲突；JSON 配置拒绝重复键，整数保留 int64 精度；未知标识使用系统兜底，默认公开响应不暴露 cause。
• 新生成代码最低要求 v0.10.0-preview；原有构造函数、Codes/Messages 与旧生成代码继续可用。Catalog 为生成错误包保留函数名。

v0.9.1-preview

• 新增标准 database.OpenConnector 和独立 PoolConfig；与 DSN 入口共享池参数、限时启动 Ping、失败清理、Health、事务，不注册全局驱动配置。
• 新增 omni.WithHTTPConfig / Config.HTTP：读头、读请求、写响应、空闲超时和头大小，贯通代码、JSON/YAML、环境变量、Run/Serve 与 NewServer；nethttp 支持 Go-only ErrorLog。
• 保持已有默认行为；负值和实验 http2 不支持的超时项在监听前报错；记录各网络层的具体语义。
• 增加真实 MySQL TLS/驱动日志隔离、连接池归属/取消/事务、nethttp/native 慢连接与写背压验收，以及无本地 replace 的远程消费者脚本。
• 兼容 v0.9.0-preview 生成代码；不修改业务项目的数据库策略或生成代码最低版本。

v0.9.0-preview

• 标准 HTTP Handler/Middleware 桥接：跟踪 Raw 状态与提交，保留取消、流式能力和中间件跨请求状态；已提交响应不追加 JSON。
• .api 支持动态 JSON any / interface{}，保持重复键、大小、外围未知字段校验和数字精度。
• 路由级请求体限额、自定义绑定和 manual Handler；上传、原始 body、下载可保留手写实现，重生成受保护。
• 自定义 scalar 显式对接项目 JSON/Text 方法；支持可空和集合，分别生成请求/响应 OpenAPI；不放宽其他字段。
• 新增 迁移扩展指南、可运行示例和真实生成项目回归。CLI 与框架依赖一起升级。

v0.8.0-preview

• 公共响应 codeType 支持 int32 / int64 / string，校验默认码及映射范围，OpenAPI 标注整数位宽；JSON/YAML 和生成代码保留 int64 精度，旧 integer 兼容。
• 公共 JSON 响应体改为可配置模板：支持嵌套结构、独立错误体、错误码类型/映射、提示与空值行为；旧 DTO 仅保留源代码兼容。
• .api 支持 response Name (...)、分组引用和单路由覆盖；@response raw 输出原始业务 JSON。生成的模板、路由和 OpenAPI 使用同一份配置。
• 提供应用级/接口级编码器，以及 Text / XML / Bytes 直接输出，允许三方回调独立控制成功和失败的状态、Header、内容。
• 接口响应策略可在全局中间件之前挂载，覆盖提前鉴权/限流失败和 Context 克隆；内置路由 404/405 使用应用配置。
• 详见 公共响应体。CLI 与项目框架依赖需要一起升级到本版。

v0.7.0-preview.1

• .api 支持集中业务错误目录、组级与路由级错误声明，生成状态/错误码/提示一致的 internal/apierrors 函数，以及 OpenAPI 命名响应示例。
• 具名鉴权声明支持 Bearer、header/cookie API key，关联真实中间件；支持组级继承、单路由覆盖与公共接口，认证 hook 优先执行并在启动时校验。
• 新增多行 @doc 的摘要、描述、标签与弃用标记，info.description 同步文档。
• 新增 api inspect、api export、api generate --dry-run；项目内自动识别 manifest 的 API 入口，减少重复参数。
• 用户示例用真实 401/403/409 验证声明与行为，业务直接使用生成的错误函数；生成不会改写现有手写 hook 和 Service。
• 纠正旧文档误将事务 Outbox、分布式锁列为已实现的描述；这两个模块当前没有实现。

v0.7.0-preview

• 新增 .api 契约驱动生成器：DTO、严格多来源绑定与校验、路由、分组 Handler / Service / Repository、命名中间件及 OpenAPI；生成文件哈希管理、业务文件保护和只读 --check。
• new --api / api new / api generate 可以组合 MySQL、日志以及 Local / S3 / R2 / OSS。保存初始基础设施选项，重生成自动沿用；显式切换已有项目选项会拒绝，避免静默丢失初始化代码。
• 新增 examples/userService 独立业务示例与 verifyAPIWorkflow.py：用户 CRUD / 分页、管理员 Token 鉴权、MySQL 事务审计、故障回滚、文件导出、requestId 日志、数据库 readiness 和优雅退出；支持从远程版本验收。
• 日志新增文件轮转、结构化敏感字段脱敏、异常堆栈及慢请求配置；存储新增统一上传策略、直传签名和云端分片能力。
• 新增缓存、HTTP 客户端、限流 / 幂等 / 超时、后台任务、Redis 队列、审计、迁移与 telemetry 等可选模块；业务身份与 Orbit 保持由应用自行组合。
• database.ApplyEnv 支持文件/默认配置叠加环境变量；数据库配置使用 lowerCamelCase，DSN 不参与 JSON/YAML 序列化。
• 修复 native 在业务层提前拒绝请求体为 413 时等待继续读取 body 的问题，拒绝后关闭未读连接。

以下是自上一版本以来的网络层变化与历史验收记录：

• 新增 TestNginxHTTP2Proxy 与 scripts/verifyHTTP2Proxy.py：验证两段 TLS/h2、回源连接复用、证书校验拒绝、超时/客户端取消恢复，以及 GOAWAY 下的新旧实例切换和请求排空。Linux amd64、Nginx 1.30.5 普通与 race 模式各 3 轮通过；保留源码/镜像/日志校验信息和实际执行记录。
• HTTP/2 代理验收的编译与测试阶段顺序运行，均限制 2 核、2 GiB、256 个进程/线程；集成测试禁用外部网络并使用只读根文件系统。总时限、SIGTERM、SIGHUP 清理实测通过；native 默认协议保持 HTTP/1.1。
• 新增 TestTLSMixedSoak 与 verifyHTTP2.py --scenario mixed：8 条 TLS 连接、128 个 worker 持续混跑普通请求、慢上传和慢下载，校验 TLS/HTTP2、requestId、响应内容及传输摘要；分别统计三类请求与每条连接覆盖情况，并记录退出/GC 后的回收数据。
• 完成 Linux amd64 30 分钟多连接慢客户端混合长测：53,191,687 次请求（含 106,971 次慢上传、5,588 次慢下载），0 失败与协议错误；采样 RSS 峰值约 116.6 MiB，连接/请求、goroutine 和 FD 回收，释放测试数据后存活堆约 450 KiB。保留完整日志、120 份采样及每条连接的分类计数。
• 新增独立 transport/http2 实验 Runner：支持 h2c/TLS h2、连接上限、全局请求并发闸门、GOAWAY 排空、RST_STREAM 单流取消和生命周期统计；不改变 native HTTP/1.1 默认路径。
• HTTP/2 实验 Runner 增加标准 1 MiB 头部上限、默认 8 MiB 请求体上限、128 路同连接多路复用、2 MiB 慢读取流控验收、协议错误、RST_STREAM 和 GOAWAY 帧计数；已声明超限请求在进入业务 handler 前返回 413。
• 新增可配置时长的 HTTP/2 TLS soak：默认 3 秒，Linux 验收可通过 GO_OMNI_HTTP2_SOAK_DURATION=30m 覆盖，混合验证 128 路 stream、慢 handler、请求体、Keep-Alive 和退出回收。
• HTTP/2 soak 每 15 秒输出请求/失败数、Go 堆、Linux RSS、goroutine、FD 和协议统计；校验响应协议、内容和独立请求 ID，不再忽略压测期限附近已发出请求的失败。
• 补充 HTTP/2 慢响应流窗口为零时的隔离与恢复验收：同连接 204、另一连接带 body 响应、WINDOW_UPDATE 恢复发送及 RST_STREAM 释放请求槽位；补充 TLS 握手未完成时的连接上限拒绝、握手超时回收和正常请求恢复。
• 补充连接级接收窗口耗尽测试：保持 stream 信用充足，消费完 65,535 字节连接窗口后确认大响应暂停，同连接 204 和另一条连接仍可完成，连接级 WINDOW_UPDATE 恢复后继续复用；补充零窗口阻塞写在关闭超时后解除阻塞、取消请求与连接回收的验收。
• 新增 scripts/verifyHTTP2.py，固定在 Go 1.25 Linux 容器中运行 HTTP/2 TLS 长测；默认使用普通模式，--race 默认运行 60 秒。容器默认限制为 2 核、2 GiB 内存、256 个进程/线程，带总时限、中断清理和日志大小限制。
• 完成 Linux amd64 单 TLS 连接、128 个 worker 的 30 分钟 HTTP/2 长测：58,102,476 次请求，0 失败与协议错误，采样 RSS 峰值约 22.6 MiB（包含客户端和服务端），退出后连接/请求/FD 回收；保留原始日志和 120 份采样。
• native TLS 明确限制 ALPN 为 http/1.1：缺省自动宣告该协议，误配置 h2 等未实现协议时在启动阶段报错。
• native Server.Stats() 新增连接和请求过载拒绝计数；新增可信代理配置，访问日志只在 socket 对端属于配置网段时解析 X-Forwarded-For。
• 新增 transport-neutral metrics 包，支持请求数、错误数、in-flight、累计耗时和状态分布，并可直接注册 /metrics 接口。
• native 新增 Server.Stats()，提供 accepted connections、active connections 和 active requests 生命周期指标。
• native 请求体改为流式读取，Content-Length 与 chunked body 不再在进入 Handler 前整体复制到内存；保留大小限制、读超时、trailer 校验和 Keep-Alive 排空。
• 统一标准库与 native 的真实 TCP benchmark，增加固定并发档位、响应状态与读写错误检查。
• 新增独立进程并发与长连接内存测量工具，记录成功吞吐、P95/P99、服务端分配、空闲连接堆内存和回收情况；修正并行 ns/op 与客户端/服务端混合分配的解释。
• 加固 native HTTP/1.1 解析边界：校验 Host、重复 Content-Length、Connection token、Transfer-Encoding、控制字符和响应头名称；补充 HTTP/1.0 Keep-Alive、HEAD、204 以及异常请求测试。
• native 支持带 trailers 的 chunked 请求体，并继续通过 MaxBodyBytes、读超时和头部上限控制解析内存与连接占用。
• native 响应实现 http.Flusher：HTTP/1.1 流式响应自动使用 chunked framing，普通响应继续自动生成 Content-Length。
• native 在长 Handler 运行期间监测客户端断开并取消请求 context，流式写失败同步取消；短请求延迟启动监测，管线数据保留给下一次请求。补充断开、监测退出和长连接复用验收。
• native 增加 ServeTLS / RunTLS 和 TLSConfig 启动入口，App.RunWith 可以直接启用 TLS；补充真实 TLS 客户端握手、请求和优雅退出验收。
• native 请求补齐 Request.TLS 连接状态；Linux/arm64 容器通过全量 race、vet、build，以及 TLS 并发、Keep-Alive、慢握手和连接上限回收验收。
• 补充慢请求体超时、大请求体和同连接管线请求验收，确认流式 body 读取超时会取消请求并关闭连接，连续请求不会串线。
• 补充 MaxConnections 满载拒绝与槽位释放验收，确认请求完成后连接容量可再次使用。
• 补充 MaxConcurrentRequests 过载恢复验收，确认 503 拒绝后请求槽位释放并可继续处理新请求。
• 增加高频建连/断连的状态池 churn 验收，覆盖连接对象回收与容量复用。
• 新增 Linux Nginx 反向代理验收脚本，覆盖 native TLS、Keep-Alive、上游超时和优雅关闭。

v0.6.0-preview

• native 网络层完成流式 Content-Length / chunked body、慢请求头、慢 body、慢 TLS 握手和 TLS 请求元数据验收；Handler 可在 body 未完全到达时开始读取，超时、畸形和超限 body 会被拒绝并关闭连接。
• 将 native 连接 churn race 验收扩展为 16 个 worker、3,200 次建连/断连，并覆盖明文与 TLS 的连接上限、Keep-Alive 和槽位回收。
• perfcheck 支持最长 30 分钟持续场景，新增 Linux 文件描述符采样；固定记录服务端堆、goroutine、连接数、accept 数和 FD 回收状态。
• 新增 scripts/verifyLinux.py，在 golang:1.25 Linux 容器内统一执行 race、vet、build 和可选 TLS / 非 TLS 压测。
• 完成 Linux/arm64 30 秒高并发回归：128 并发流量、512 条空闲连接，TLS 与非 TLS 均为 0 错误，连接、goroutine 和 FD 回收正常；原始报告见 performance/linuxSoak.json 和 performance/linuxSoakTLS.json。

v0.5.0

• 新增 transport/native 第一版自研 HTTP/1.1 服务端，接管 TCP 监听、连接、Keep-Alive、请求解析、响应写回和优雅关闭。
• 新增 App.RunWith / omni.Runner 启动边界；native 通过标准 http.Handler 接入，现有 Handler、Service 和 Repository 无需修改。
• native 支持 Content-Length / chunked 请求体、请求头 / 请求体限制、读写超时和服务关闭时的请求取消；通过对象池和 MaxConnections / MaxConcurrentRequests 控制高并发内存。
• omni.New() 默认仍使用只依赖标准库的 transport/nethttp 路由，native 作为显式启用的网络层预览实现。

v0.4.0

• 破坏性变更：移除 Gin 适配器及其全部依赖，omni.New() 默认使用只依赖标准库的 transport/nethttp。
• 移除 Gin 专属的 Config.Mode / WithMode API；网络层运行模式由具体适配器或启动层自行配置。
• 公共 httpx.Router、transport/transporttest.Run 和 omni.NewWithRouter 保留，自研网络层无需修改业务 Handler / Service 即可接入。
• benchmark 改为标准库路由和完整 GoOmni 请求链，新增 scripts/verifyPerformance.py 作为 race、vet、build 和性能基线入口。
• 远程业务试用、脚手架、适配器契约和 MySQL 验收全部迁移到 v0.4.0。

v0.3.1

• 新增独立业务模块验收 scripts/verifyBusiness.py：从远程 v0.2.0 升级到 v0.3.1，验证无本地 replace、配置加载、结构化日志、requestId、CRUD、校验错误、业务错误和优雅退出。
• 脚手架与各项远程验收脚本默认跟随 v0.3.1，新项目会固定到最新补丁版本。

v0.3.0

• 新增公共适配器验收套件 transport/transporttest.Run 和远程消费验收脚本 scripts/verifyTransports.py。Gin、nethttp 使用同一套路由与业务处理链测试，并通过完整用户 CRUD 与 race 验证。
• 统一参数、分组、方法、URL 解码、路由优先级及 404/405 规则；Gin 405 的 Allow 由适配层计算，避免方法树回退状态带入无关方法。
• 统一路由注册校验；非法路径、重复路由、参数名冲突和 catch-all 冲突在注册时 panic。
• App.Handle / RouterGroup.Handle 支持在完整业务中间件链内显式注册 HEAD、OPTIONS 与扩展方法。
• JSON 在提交响应前编码，编码失败可正确返回统一 500；通过 Context 已提交的响应不会因后续错误、panic 或重复响应追加内容，访问日志保留实际提交的状态。
• 验证 requestId 与业务日志关联、认证授权短路、请求并发隔离、context 值与 deadline 保留，以及真实客户端取消传入 Service。
• 升级行为调整：Gin 不再自动重定向尾部斜杠；nethttp 不再忽略尾部斜杠，通配参数包含开头的 /，Any 收敛为九种标准方法。HEAD 不自动回退 GET，其他方法需显式注册。404/405 为统一纯文本响应，405 附排序后的 Allow。
• gin.NewWithEngine 应用 GoOmni 路由策略；原生 Gin 扩展与 Raw 流式响应不属于可移植契约。详见 transport/README.md。
• 新增业务试用验收 scripts/verifyBusiness.py：独立目录内固定远程版本，执行 v0.2.0 → v0.3.0 升级，验证生成业务服务的配置、日志、requestId、CRUD、参数校验、错误映射和优雅退出。

v0.2.0

• 新增 go-omni new --database mysql，生成数据库配置、MySQL Repository、ServiceContext、schema.sql 和数据库就绪探针；默认仍使用内存存储。
• 两种存储模式的脚手架均提供完整 CRUD、分页、输入校验与统一响应。新生成项目的 POST /users 从直接返回用户对象改为标准响应封装，用户对象位于 data。
• MySQL 启动时检查连接和表结构，失败时清理连接池；数据库停机后 readiness 返回 503，恢复后自动重新检查。
• MySQL Repository 支持 *sql.DB 和 *sql.Tx，可在同一事务中复用业务查询。
• 修复 MaxIdleConns=0 未生效的问题，数据库健康检查增加超时限制。
• 新增隔离 MySQL 容器验收脚本，覆盖真实 CRUD、事务提交和错误/panic/取消回滚、持久化、资源清理及数据库停机恢复。

v0.1.1

• 修复脚手架生成项目固定依赖不存在的 v0.0.0；远程安装的 CLI 默认使用自身版本，支持 --framework-version 指定完整版本号。
• 显式远程版本禁用自动本地替换；本地替换路径支持空格，并按精确 module path 识别框架目录。
• 生成项目通过 signal.NotifyContext 接入优雅退出，启动过程中的错误会先执行 defer 清理再报告。
• App.Run 自动处理 SIGINT / SIGTERM；RunContext 仍由调用方控制，退出超时会关闭活跃连接。
• 增加请求排空、超时取消、启动失败清理测试，以及远程脚手架和真实进程信号验收脚本。

v0.1.0

• 首个可试用版本：应用生命周期、HTTP 抽象、Gin 与标准库路由适配器、统一响应与错误。
• 提供配置、日志、校验、认证接口、数据库基础能力、健康探针和项目脚手架。