Files

k2safe 0d2c6040e2 feat: release v0.28.1 mixed API and generic project workspaces

2026-09-30 00:20:17 +08:00

44 KiB

Raw Blame History

v0.28.1-preview

workspace generate/check 支持 API 与通用工程混合分发，也可处理纯通用工程工作区。services 新增可选 kind（api/project）；省略时按生成清单识别，保留无清单时显式 api 入口的原有用法。类型与清单冲突、歧义和不合法选项会报错，项目身份、路径与文件归属继续由各生成器校验。

check 只读并汇总独立工程的失败；format 只处理 API 契约，对通用工程明确显示 SKIP。generate 预检所有工程后再写入，预检失败时不修改其他工程；不改变各模块依赖或 go.work，不增加业务逻辑和第三方依赖。模板与运行时接口未变，新 workspace 功能需要更新 CLI，旧生成工程可直接纳入。

go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.28.1-preview
go-omni workspace generate
go-omni workspace check

混合工作区示例、清单规则、验收记录。56 个测试包全量 race、5 个 CLI 包的 Go 1.22 回归、实际生成的多模块构建、vet/build 均通过。

v0.28.0-preview

新增通用 Go 工程生成命令 project new/generate/check。默认只有配置、日志、svc 依赖装配、生命周期与项目维护的 Run 入口，不生成 API、HTTP Handler、Swagger、业务任务或网络监听，也不自动连接数据库/队列或重试任务。常驻和一次性程序由普通 Go 代码决定。

入口监督 Run 的真实完成并复用现有 Runtime：信号、正常结束、运行错误或初始化失败都会进入收尾；先停止接收工作、等待已登记工作及 Run 结束，再反序释放依赖并关闭日志。Run/Init panic 转为失败；超时仍有工作则传播 ErrResourcesRetained，保留共享资源及日志，以非零状态退出。组件登记在 svc.Init 完成，业务语义和调度方式由项目负责。

配置遵守现有显式文件引用约定；支持 -check-config，在初始化日志和依赖前校验。生成器只管理 main/loadGen/runtimeGen，手写文件保留，生成文件被修改时拒绝覆盖；check/预览只读，独立 manifest/锁和共享文件事务保障生成。新模板要求框架 v0.28.0-preview；已有 new/api/workspace 行为保留，无强制迁移和新增第三方依赖。

go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.28.0-preview
go-omni project new demo --module example.com/demo
cd demo
go mod tidy
go run . -check-config
go run .
go-omni project check

完整通用工程指南、可运行示例、回归记录。56 个测试包全量 race 与 Go 1.22 回归、生成消费者、vet/build 和真实进程退出验证通过。

空缓存远程安装已完成：通用工程 30 项检查通过（26.45 秒），原有生成项目 98 项检查、10 组消费者通过（111.07 秒），均无本地 replace。见通用远程报告、原有能力远程报告。标签固定在 0b6c0043b6c3b58648645aeee03bf80801e6aa3f。

v0.27.0-preview

新增统一请求体策略与请求完成屏障，无业务字段、数据库依赖或新第三方包。server.http.defaultMaxBodyBytes 控制普通路由默认值（零为 8 MiB），maxBodyBytes 为不可由路由突破的服务硬上限（零仅保留 1 TiB 框架上界）。已有显式路由和生成契约限额保持，冲突会在启动前报错；旧 nethttp 手写大请求需显式设置路由或默认上限。multipart 单文件、中间件缓存及代理限额仍各自配置。

HTTP 关闭连接后继续等待处理器实际退出，收尾窗口由 server.http.shutdownCancelTimeout 设置（零默认 5s）。超时仍有处理器运行时返回 lifecycle.ErrResourcesRetained，App/Runtime/生成入口保留共享依赖和日志；不再将连接关闭当成业务完成。Runtime.Finish(runErr) 会传播该信号，手写入口必须处理它，避免无条件关闭额外资源。该行为适用于全部 App 服务入口；HTTP/2 低层 Shutdown 同时等待独立处理器。

详见请求体策略、停机规则、运行示例。CLI 与框架固定使用同版 v0.27.0-preview；模板最低兼容版本仍为 v0.22，HTTP 安全改进需要升级运行时。

go get git.yuntuo.hk/k2safe/go-omni@v0.27.0-preview
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.27.0-preview
go-omni api generate --check
go test ./...

54 个测试包全量 race、Go 1.22 兼容检查、生成项目集成测试、vet/build 及真实进程关闭检查通过，见验收记录。

空模块缓存安装远程固定版本后，10 组生成消费者和 98 项发布检查通过，耗时 107.57 秒，无本地 replace；覆盖上传限额、取消收尾、HTTP/2 断连、生成项目依赖与日志保留。标签固定在 3b00bb55d189cbe480c7d15c8d14bcd09d3f2d52，见远程验收记录。

v0.26.0-preview

新增可独立使用的 i18n 底层模块及可选 HTTP/错误适配。项目维护文案和语言设置，框架提供不可变词典、语言匹配、回退、参数与分支、检查和导出；没有绑定业务身份、页面框架、数据库或响应字段名。

前后端共享版本化消息资源和固定 Unicode CLDR 46.1 基数复数规则。CLI 只读输入，支持源目录提取、缺译/参数/动态引用检查、按命名空间导出语言包和 TypeScript 类型。可选浏览器模块先加载并验证再切换，失败保留当前语言，旧请求不能覆盖新选择。

错误目录新增可选 translation 引用。内置响应使用展示译文，原目录文案继续参与契约校验；自定义 Encoder 通过 PublicMessage() 显式采用译文。业务码、HTTP 状态、成功/失败语义、cause、直接协议输出和幂等首次快照保持。旧配置与生成项目不启用时无需迁移。

完整使用指南、通用示例、验收记录。包含 translation 的新契约远程依赖最低版本为 v0.26.0-preview；未使用该元数据的模板最低版本仍为 v0.22。CLI 与框架使用同版。

同时修复 JSON 结束定界符读取失败时丢失原始错误的问题，使请求体超过外层限制时在 Go 1.22 中也保持 HTTP 413；共享目录测试工程使用 Go 1.22。

go get git.yuntuo.hk/k2safe/go-omni@v0.26.0-preview
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.26.0-preview
go-omni api generate --check
go test ./...

发布前 54 个测试包全量 race 与 Go 1.22（含生成消费者）、vet/build、真实进程检查通过。空缓存安装远程固定版本后，10 组生成消费者和 87 项发布检查通过，耗时 83.76 秒，无本地 replace；包含下载模块的国际化、CLDR/浏览器一致性、TypeScript 类型和 CLI 工具链验证。标签固定在 d1a747c36f15d964dd445d661623b68a45892adf，远程验收记录。

v0.25.0-preview

事务失败可以按阶段和已知结果处理，避免把“提交错误”误判为“数据库没有保存”。

database.InTx 签名不变，普通错误返回 *database.TxError；Stage 为 begin/work/commit，Outcome 为 notStarted/rolledBack/unknown。成功提交仍返回 nil。
Commit 报错一律 unknown；回调失败且显式 Rollback 返回 nil 才标记 rolledBack。BeginTx 失败不执行回调。ErrTxDone 不作为回滚成功证据，框架不重试事务。
Err 与 RollbackErr 保留两条原因链，可通过 errors.Is/As 识别；APIError、目录参数提示和公开响应继续工作。内部原因不自动进入 HTTP 提示。
提供无需外部数据库的故障演示。真实 MySQL 与性能结果见验收记录。不引入新依赖，不包含文件删除、补偿任务或业务规则。

go get git.yuntuo.hk/k2safe/go-omni@v0.25.0-preview
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.25.0-preview
go-omni api generate --check
go test ./...

兼容边界： 既有 errors.Is/As 保持；直接 err == sentinel、直接类型断言或字符串匹配需调整。nil context 使用 Background，nil 回调在开启前返回 typed error。panic/Goexit 继续传播并尝试回滚，不转换为 error；标准库自动回滚不公开的原因无法还原，不能推断已回滚。结果仅覆盖按约定使用的当前事务，不覆盖非事务表、隐式提交 SQL、其他连接或外部副作用。GORM 原生 Transaction 没有被替换。

database 使用规则已同步。本轮 runtime 能力需要 v0.25，模板最低版本仍为 v0.22；没有新增必填配置，当前仍为 preview。

49 个测试包全量 race、Go 1.22、vet/build、取消竞争复测通过；成功事务没有新增分配。固定远程版本在空缓存下通过 77 项发布检查和 9 组生成消费者，耗时 71.93 秒。独立 MySQL TLS 容器的 53 条测试记录（含子用例）通过，包含真实提交/回滚后的确认丢失、可选 GORM、生成项目和后台关闭，耗时 28.49 秒。均无本地 replace，标签固定在 7a177744ab2bb85f23efc0ec267fd905d349bd4b。见远程发布记录、远程 MySQL 记录。

v0.24.0-preview（历史版本）

业务项目通过配置开启跨域，不需要手写 OPTIONS Handler 或逐条修改接口。

默认关闭，在 server.cors 显式配置来源、方法和请求头；统一文件加载、环境引用和字段级诊断自动生效。生成项目无需修改 main、svc 或 .api。
预检在鉴权前返回 204/403 空响应；实际请求继续鉴权、业务错误编码和路由处理。允许来源可读取 401/403/404/405/500，上传下载和流式能力保留。
只支持精确 HTTP(S) 来源，公开无凭据服务可配置单一 *；禁止 * 与凭据混用。配置初始化快照、请求并发隔离、Vary 缓存分流和有界请求头处理。
同一个 App 策略覆盖标准库、native 和 HTTP2；独立服务可使用 cors.New(...).Wrap(handler)。没有新增第三方依赖，没有移除现有功能。

go get git.yuntuo.hk/k2safe/go-omni@v0.24.0-preview
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.24.0-preview
go-omni api generate
go-omni api generate --check
go run . -config etc/config.yaml -check-config

现有项目不配置 CORS 时行为不变。代理已处理 CORS 的项目继续关闭；跨域不替代登录、权限或 CSRF 防护。通过 App/Engine/Run 接入，直接对外暴露底层 Router 会绕过应用外层策略。本轮新增 runtime 配置需 v0.24，未使用该配置的模板最低版本仍为 v0.22。

配置与规则、可运行示例、验收与性能已同步。49 个测试包全量 race、Go 1.22、vet/build、实际生成项目、三种 transport 的 TLS 场景和 20 项真实浏览器检查通过；30 秒 fuzz 约 288 万次。当前仍为 preview。

空缓存安装远程版本后，9 组生成消费者和 70 项发布检查通过，耗时 66.78 秒，无本地 replace；包括下载模块的 cors/app race、三种 transport 的 TLS 检查和只改配置的生成项目。标签固定在 800974cfff6228c2697373d9961d3c7c75611d08，见远程记录。

v0.23.0-preview（历史版本）

减少业务接入时重复维护的配置校验、HTTP 包装和类型检查。

配置诊断定位 database.port、database.pool.maxIdleConns、server.log.level/timeZone 等具体字段，保留文件、环境变量、行列和安全原因；凭据不进入公开提示，原始原因可 errors.Is/As。
JSON 可传 httpc.WithSuccessStatuses(200)，默认仍接受全部 2xx；不匹配时不改目标，继续负责有界读取、关闭和连接回收，不添加新的重试规则。
copyx.Check[S,T](options...) 或已有 Copier.Check 复用同一组 Go 选项，无需样本和映射文件；实际拷贝不再因集合为空而漏过确定的类型不匹配。动态 interface、nil 值、converter 失败及深拷贝共享引用仍有运行时检查。
server.log.timeZone: Asia/Shanghai 配置实例时区；JSON/text/子日志一致，业务 time.Time 属性保持原样。极简镜像可用 go build -tags timetzdata . 内置时区数据，库不强制增加体积。

go get git.yuntuo.hk/k2safe/go-omni@v0.23.0-preview
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.23.0-preview
go-omni api generate
go-omni api generate --check
go run . -config etc/config.yaml -check-config

现有调用接口保留；配置错误文本现在更精确，业务应通过类型/字段识别错误。空集合里确定的类型错误会提前暴露，需要显式 converter 或调整实际类型，不应靠空值跳过校验。预检通过不代表 converter 对所有业务值必定成功。当前模板最低版本仍是 v0.22，本轮新增 runtime 能力需使用 v0.23。

完整示例、配置、JSON 选项、类型预检、日志时区。验收与性能记录见本轮验收。仍为 preview。

48 个测试包全量 race、Go 1.22、vet/build、实际生成消费者及约 392 万次 copyx fuzz 通过。空缓存安装远程版本后，66 项发布检查通过，包括下载模块的 config/httpc/copyx/logx race；耗时 57.06 秒，无本地 replace。标签固定在 3bbc6f60d76cb9eae6f01fa6ca122eb1fbf481af，见远程验收。

v0.22.0-preview（历史版本）

配置文件明确决定每个值的来源，项目只维护 Config、Default()、Validate() 和文件。

${NAME} 必填，${NAME:-fallback} 在未设置/空字符串时使用备用值，$$ 转义 $。支持字符串组合；环境值不二次展开，凭据空格和特殊字符原样保留。
在 JSON/YAML/XML 已解析的字段值上展开，再按目标 Go 类型绑定；缺失字段保留默认值，0/false/空字符串可显式覆盖。字段错误定位文件、环境名和可用行列，不回显值。
生成 Load/main 自动接入；新增 -check-config，选定一个文件检查，成功退出，不启动日志/依赖/监听。精简生成配置，重新生成保留业务 Config、Default、Validate 和文件。
不兼容变更：旧自动环境覆盖、前缀/别名、env/envDefault、database.ConfigFromEnv/ApplyEnv 已移除。 LoadFile/NewReloader 不再接收 prefix，omni.LoadConfig 参数改为文件路径。发现旧标签提示迁移。
配置文件中的响应模板用 $${code} 等转义；.api 中的 ${code} 不变。日志 file/output/rotation 均由显式文件配置决定，不再隐式清除。

go get git.yuntuo.hk/k2safe/go-omni@v0.22.0-preview
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.22.0-preview
# 按 CONFIG.md 迁移开发者配置后：
go-omni api generate
go-omni api generate --check
go run . -config etc/config.yaml -check-config

完整规则与迁移、可运行示例、场景与性能验收已同步。48 个测试包全量 race、实际生成消费者、Go 1.22、vet/build 和约 28 万次引用 fuzz 通过；小配置固定值/带引用加载约 25 µs，属于本机启动阶段基准。当前仍为 preview。

空缓存远程 CLI 安装、下载模块 config/httpc race、8 组实际生成消费者与 -check-config 验收通过，无本地 replace。标签固定在 d598b2ebee8cde36859021e882a6bc1e0bb4fd4c；见远程验收记录。

v0.21.0-preview（历史版本）

让带认证的 HTTP 调用和内部直连可以直接使用 httpc，减少手写 Transport 与 JSON 响应处理。

Proxy 支持环境、直连、固定代理；默认保留既有策略。
建连、TCP keepalive、TLS 握手、响应头、100-continue、空闲超时和独立空闲连接数量可选配置；不修改全局 Transport，不关闭借用实例。
JSON 支持 WithHeader / WithHeaders / WithMaxResponseBytes；认证信息逐请求隔离，自动关闭和有界响应处理保留。
成功路径减少请求复制和无用退避；output=nil 按限额流式丢弃；小错误体在大小和时间预算内尝试复用连接。
不新增依赖、不增加业务规则；Do 保留标准流式扩展。CLI 最新版本与模板最低版本分开，本轮模板兼容门槛仍是 v0.20。

go get git.yuntuo.hk/k2safe/go-omni@v0.21.0-preview
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.21.0-preview

兼容注意：JSON 旧的直接调用仍有效，自定义 interface/函数值需要同步新增的 variadic 参数。自定义 Transport 与显式连接/代理/阶段参数混用现在报错，避免参数被忽略；迁移时在自己的 Transport 配置，或改用内置字段。没有删除原调用入口。

参数与使用说明、可运行示例、场景与性能验收已同步到 README。48 个测试包全量 race、Go 1.22 兼容、vet/build、约 110 万次请求头 fuzz 通过。性能来自本机同条件基准，不能代替项目实际流量验证；仍为 preview。

空缓存远程安装、下载模块的 httpc race 与示例、8 组生成消费者验收通过，无本地 replace。标签固定在 96e7d9629b5c8b78e9cfefbcb05da0ab702c242b，见远程记录。

v0.20.0-preview（历史版本）

统一配置加载，减少生成项目重复维护的启动代码。

生成器维护 internal/config/loadGen.go，调用 config.LoadProject；项目只扩展 Config/Default/Validate，可选在 loader.go/NewLoader 注册新格式。入口、环境覆盖、日志输出规范化无需业务重复实现。
JSON/YAML/XML 使用同一个加载与绑定流程；Decoder 通过实例注册，无全局 init 或额外强制依赖。内置格式、字段、文件大小与层数均有明确限制。
config.Error 携带文件、字段、环境变量、可用行列及安全原因；Invalid / AtField 支持业务验证。保留内部错误链，不自动输出原值；大整数、空集合、null、默认值隔离和自定义反序列化有回归覆盖。
配置解析在日志、依赖和监听初始化之前；生成/check/dry-run 使用一致入口和文件所有权规则。
迁移要求：旧项目先整理手写 Load，再重新生成。 不静默覆盖业务文件。低层配置 API 保留；新项目不再复制手写加载流程。固定 Go 数组严格检查长度，YAML alias/merge/custom tag 不再接受，避免模糊覆盖和扩展行为。

go get git.yuntuo.hk/k2safe/go-omni@v0.20.0-preview
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.20.0-preview
# 先按 CONFIG.md 迁移旧 Load，再执行：
go-omni api generate
go-omni api generate --check
go test ./...
go build .

完整用法、格式、脱敏边界和迁移见统一配置指南，可运行例子见 examples/configuration。回归、模糊测试与启动加载性能见验收记录。47 个测试包的全量 race、Go 1.22 兼容、vet/build、30 秒 fuzz 与 5 个基准场景三轮测量通过。空缓存远程安装和 8 组生成消费者回归通过，无本地 replace；标签固定在 c60841f901a3bcc3e9582eece6cfb2cad008fb9e，见远程记录。仍为 preview；项目的实际配置和业务依赖应自行验收。

v0.19.0-preview（历史版本）

将可选结构转换改为直接 Go 调用，减少业务项目需要维护的配置。普通接口继续使用 .api 生成 DTO，不要求增加独立模型或任何拷贝规则。

新增只依赖标准库的 copyx：Copy、Clone、可复用 Copier；浅/深拷贝、严格字段覆盖、nil/零值策略、字段改名、忽略字段、精确类型 converter。没有全局注册和隐式数字强转。
深拷贝检查整个输入和输出图。自定义 converter 原样返回指针、map、slice，或新对象仍嵌套旧引用时返回错误；保留普通循环图，拒绝资源对象及超出遍历/估算分配预算的输入。
转换失败不提交部分目标；保留错误路径和原始错误链。并发复用只共享不可变类型元数据；源/目标读写和 converter 副作用由调用方负责。
不兼容变更：删除 mappings / mappingFiles、Go 类型加载与映射代码生成。 检出旧配置/旧生成文件时给出迁移提示；不会静默删除业务正在使用的代码。公共字段组合、scalar、中间件工厂、Repository 选项保留。
README 补齐当前能力入口、解释和用法，新增完整 copyx 指南、可运行示例；AGENTS.md 记录每次修改同步文档/示例/移除说明的约定。

go get git.yuntuo.hk/k2safe/go-omni@v0.19.0-preview
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.19.0-preview
# 如用过旧 mapping，先按 COPY.md 完成迁移：
go-omni api generate
go-omni api generate --check
go test ./...

迁移步骤和语义边界见 copyx。新工具做运行时检查，不能声称具备旧生成器的编译期字段覆盖保证；实际类型对必须有测试。独立三端工资示例验证金额精度、缺失/null/零值、空集合、错误链和字段新增；不修改或代替接入项目的完整业务回归。

46 个测试包的全量 race（含实际生成项目）、vet/build、Go 1.22 兼容测试通过；30 秒 fuzz 无失败，14 种基准场景各测量三轮。验收条件、性能数据及本轮未覆盖的外部环境见 v0.19 验收记录。本版仍为 preview。空缓存远程 CLI 与 7 组真实生成消费者验收通过，无本地 replace；标签固定在 fd83235ce7fc15ce88a482d385d70e61f25d7b32，详见远程记录。

以下是历史版本记录，其中 mapping 功能已在 v0.19 移除，不应继续作为当前接入方式。

v0.18.0-preview（历史版本）

补齐可空嵌套映射和按模块拆分配置，减少重复转换代码，业务空值规则仍由项目显式选择：

嵌套 mapping 支持 *S → *T 保留 nil、S → *T，以及指定 nil zero/error 后的 *S → T；同样适用于 slice/等长数组元素。错误保留字段路径、索引和内部错误链，失败不返回部分结果。
mappingFiles 显式引用项目内的映射文件，支持跨文件向前引用；统一检查重名、循环、类型与字段覆盖。禁止多层导入、路径越界和隐式覆盖，生成期间核对全部配置输入。
同类型 *T → T 可显式配置 nil zero/error；现有 converter 保持完整控制，不默认放宽类型或混入领域规则。
pointerResult: true 额外生成 <Name>Ptr(S) (*T,error)，原值函数保留；失败返回 nil 与原错误，辅助函数名冲突在生成前拒绝。

go get git.yuntuo.hk/k2safe/go-omni@v0.18.0-preview
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.18.0-preview
go-omni api generate
go-omni api generate --check
go test ./...

v0.17 的单文件 mappings、现有 converter 和业务文件继续保留。配置拆分时移动完整映射条目，主配置显式列出子文件；不保留重复定义。新能力均为可选生成配置，不增加运行时依赖。nil zero 表示 Go 零值并跳过子映射；业务必填、金额精度、编号格式和快照复制仍由项目负责。

使用与迁移见生成能力指南，回归和发布后验收见验收记录。本版仍为 preview。

全量 44 个测试包的 race、vet、build 和实际进程验收通过；空缓存远程 CLI 与 8 组实际生成消费者回归也通过，同版依赖且无本地 replace。标签固定在 4563a6354fac19f22cd8d407fd76d98b8cc9c406。

v0.17.0-preview（历史版本）

减少项目里的重复声明、字段赋值和中间件装配代码，业务规则继续由项目控制：

.api 公共字段组合：保持 JSON 平铺，DTO、绑定、校验和 OpenAPI 同步；字段冲突、循环和超限明确报错。
可选结构映射：在 omni.gen.json 显式声明源与目标，生成编译期检查的普通 Go 赋值。不同字段名、金额、时间和指针转换由项目指定函数；遗漏字段与类型错误在写文件前失败。不使用 JSON 往返或运行时反射。
带依赖的中间件工厂：svc 初始化依赖后自动调用 New<Name>(deps) 并注册；错误、nil 或 panic 阻止启动，已登记资源按生命周期清理。
Repository 骨架默认关闭，可按 group 启用；已有业务文件始终保留。生成选项与映射纳入重新生成和 --check。

go get git.yuntuo.hk/k2safe/go-omni@v0.17.0-preview
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.17.0-preview
go-omni api generate
go-omni api generate --check
go test ./...

新项目默认使用 factories；已有项目首次升级保留 handlers 模式，需要显式迁移后再切换。映射按需开启，先准备业务类型、转换函数和依赖，再声明映射；普通引用赋值保留 Go 语义，缺失/null 语义由项目类型与转换函数定义。

使用方法、文件归属和升级步骤见生成能力指南，回归与发布验收见验收记录。本版仍为 preview；框架验收不等于业务项目完成迁移。

全量 44 个测试包的 race、vet、build 和实际进程验收通过；发布后的空缓存远程 CLI 与 7 组生成消费者回归也通过，同版依赖且无本地 replace。标签固定在 8b588a24cd653dac77dd68f6777e0db367981f19。

v0.16.0-preview（历史版本）

补齐通用契约与生成体验，业务响应协议继续由项目定义：

returns([]string/[]int64/[]bool/[]any) 及其他支持的基础类型数组，贯通 Logic、Handler、OpenAPI 和生成检查。nil 根数组输出 []；DTO 数组、nullable、null、raw 和 204 保持原语义。字节数组明确拒绝 base64/数组歧义。
OpenAPI 以标准 components / $ref 共享重复响应、schema、示例；保留同一 HTTP 200 下的成功与失败、模板参数、数字业务码和 data:null。
workspace 显式配置 Go Catalog 提供方，一次导出共享 JSON，多服务通过受控根引用。支持服务/路由的文档错误列表，运行期 App 目录继承不变。check 核对导出漂移并保持项目文件不变。
EnvOptions.Aliases + ServerEnvAliases 统一完整配置与框架短名称的 Lookup、类型转换、空值规则。完整名称优先，显式空值不等于未设置；旧 ApplyEnv 的空值/逗号列表行为保留。

go get git.yuntuo.hk/k2safe/go-omni@v0.16.0-preview
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.16.0-preview
go-omni api generate
go-omni api generate --check
go test ./...

旧项目 config/Logic/svc 继续由开发者维护，不会被重新生成覆盖。已有环境配置需按本版当时的统一覆盖方式合并 OverlayEnv 与 ApplyEnv（该模式已在 v0.22 移除，当前升级见配置迁移）；共享错误目录接入见 workspace 配置。已有手写权限 Handler 切换自动生成前，先迁出实现并显式移除 Manual 文件，生成器不会静默删除。

全量 race（含实际生成消费者）、vet、build、根入口/退出/再生成验证通过。eTax 只读契约验收：API 文档 20,751,149 → 847,171 字节，ID 文档 1,008,210 → 392,481 字节；70 个操作展开引用后与原文档完全一致。空缓存远程 CLI / 固定版本消费者验收也已通过，没有本地 replace；标签固定在 64e3bd6cfced225476d58e95037249cd0a4fe695。详见验收记录。这不代表已完成业务项目迁移。

v0.15.0-preview（历史版本）

增加通用后台分阶段关闭：生成入口先完成 HTTP 排空，再运行全部 OnStop、全部 OnDrain，确认组件收尾后逆序释放 OnClose 资源，最后关闭日志。适用于任意后台组件；不引入 Orbit，不改变业务事务或任务一致性策略。

svc 登记成对、同名的 OnStop/OnDrain，Context 用于早期退出通知，WorkContext 供已接受工作在收尾期间使用。同一阶段并发执行，存在内部先后依赖的组件组合登记。
server.lifecycle 配置 stopTimeout、drainTimeout、cancelTimeout。阶段超时取消工作并给未返回钩子收尾窗口；错误与阶段/组件名称可通过错误链追踪。
不能确认后台已经结束时，返回 ErrResourcesRetained，保留共享资源和借用日志，生成进程非零退出。未返回的 Stop 不会与自己的 Drain 重叠；错误、panic 不阻止其他组件尝试收尾。
task.Runner 增加 StopAccepting/Wait，原 Shutdown/Close 继续可用。核心 lifecycle 不依赖 task 或其他适配器。
初始化和监听失败复用同一流程；重复关闭只执行一次。生成器继续保留配置、svc 和业务代码。

go get git.yuntuo.hk/k2safe/go-omni@v0.15.0-preview
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.15.0-preview
go-omni api generate
go-omni api generate --check
go test ./...

v0.14.x 无需重写 svc/config；生成器更新 main/runtimeGen，未配置时使用默认时限。也可 api upgrade --dry-run/--apply 更新依赖与生成文件，保留已有项目扩展。需要阶段保证的旧后台 OnClose 登记，应显式迁到 Stop/Drain；v0.13 及更早版本仍按原迁移指南处理。

全量 race（含实际生成项目）、vet、build 和隔离 MySQL/GORM 验收已通过。发布后的空缓存远程生成项目与真实 MySQL/GORM 验收也通过，CLI/框架同版且无本地 replace；标签固定在 16deead70e860052c5b629511207578c03f9b2cb。详见生命周期接入与验收记录。Go 无法强制结束任意 goroutine；OnClose 仍须能返回，HTTP 处理器仍须响应取消。此版不会将未知的第三方组件自动改造成优雅关闭组件。

v0.14.1-preview（历史版本）

增加可选 database/gormx：GORM 复用 go-omni 已初始化的标准池、TLS、限额、健康检查和关闭流程，业务继续使用原生 GORM 模型与事务。核心 App/数据库包的编译依赖链不引入 GORM。

在 svc.Init 中调用 gormx.MySQL(ctx, c.DB, gormx.WithLogger(c.Logger))；通用 Open 工厂保留其他方言入口。适配器保护借用池不被初始化失败路径关闭，并为初始化查询设置时限。查询使用 WithContext，SQL 日志接入 logx，请求标识、慢查询和错误分类贯通；默认不输出绑定参数与驱动完整错误文本。

v0.14.0 项目更新 module 与 CLI 即可，不改生成目录或 main。模板最低运行时保持 v0.14.0；修正新版 CLI 把最低兼容版本误当自身版本、导致同版消费者出现版本提示的问题。其他数据库方言和管理额外池的插件未纳入本次实库验收，原生 PrepareStmt 的生命周期限制见接入说明。

go get git.yuntuo.hk/k2safe/go-omni@v0.14.1-preview
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.14.1-preview

全量 race（含生成消费者）、vet、build，以及隔离 MySQL 的事务/取消/日志/生成项目接入通过。发布后的空缓存远程 MySQL/GORM 和生成项目验收均通过，无本地 replace，CLI 与框架使用同版。标签固定在 b8ab6b35219d53d6de392c920fe7ecbe9a76dade，详见 GORM 验收。

v0.14.0-preview（历史版本）

本版补齐契约驱动的业务开发与通用基础设施。项目继续维护接口、配置、依赖装配、Logic、SQL 和业务规则；生成器维护入口、请求绑定、路由、响应与文档。

安装与升级

go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.14.0-preview
go-omni new --module example.com/billing ./billing

新生成器与运行时一起升级。已有 v0.13 项目先运行 go-omni api upgrade --dry-run，再按定点迁移步骤处理；不会静默覆盖自定义 svc/config。运行期的新构造器由生成器维护，项目初始化迁入 svc.Init，使用 OnClose 登记资源。

本版能力

.api 支持根数组、可空对象、成功 null；真正 204 独立保留。生成 Logic、Handler、OpenAPI 和漂移检查使用相同语义。
请求契约控制未知 query、原始 UTF-8、charset、必须/可选/禁止 body 和严格空对象。路由覆盖 App 策略，普通 JSON 只解析一次。
multipart 声明文件、文本和 JSON 表单字段。Logic 收到校验后的 DTO；文件有界暂存、流式读取、请求结束清理，保留底层 raw/multipart/下载扩展。
完整项目配置支持环境覆盖、显式零值、空值策略、必填、嵌套及复杂类型。独立校验先于日志和连接创建。
lifecycle.Runtime 统一逆序清理、幂等关闭、失败回滚及故障保留；App Logger 独立，支持标准 log.Logger 与可信请求元数据。提供依赖中间件装配示例和可选 context 错误映射。
官方 database/mysql 适配器提供结构化配置、每连接池独立 TLS/mTLS、驱动日志、启动检查与失败清理。继续返回同一 database.DB，不自动迁移表或重试业务事务。
字段注释、示例和枚举说明进入 DTO/OpenAPI；api format 幂等格式化。Go 错误目录可显式导出供文档使用，无需复制错误定义。
显式共享契约 roots、来源摘要、分文件 DTO、多服务 workspace 命令、基础模板升级预览；保留目录边界及业务文件所有权。

详见业务开发指南、数据库接入和验收记录。

全量 race（含生成项目）、vet、build 与本地进程验收通过。发布后的空缓存远程消费者和隔离 MySQL 验收也均通过；CLI/框架同版且无本地 replace。标签固定在 f5478cdc7662704b164637649305361e52f7c598，报告单独提交。

仍需业务维护：契约、配置、svc 依赖创建/探针/清理登记、错误目录、Logic、Repository 和权限中间件。特殊协议可使用保留的扩展点。声明式上传的暂存磁盘和并发量需配置容量；共享契约版本标签由项目管理，框架校验摘要但不下载依赖。此版仍为 preview，不代表 eTax/ePay 已完成业务迁移。

v0.13.0-preview（历史版本）

本版补齐项目依赖主动退出与内置接口配置。ID 租约、数据库或后台任务等故障由项目判断，框架通过统一生命周期完成退出；不内置业务规则。

使用与升级

go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.13.0-preview
# 在业务 module 中执行
go get git.yuntuo.hk/k2safe/go-omni@v0.13.0-preview
go-omni api generate

新项目自动获得全部扩展。v0.12 的 config/svc 属于项目文件，重新生成会保留它们；需按升级步骤给 svc 补入 Lifecycle、RequestShutdown 与清理衔接，main 和 Handler 由生成器更新。旧 v0.11 目录仍按原迁移规则在新目录生成。

行为

svc.RequestShutdown(err) 非阻塞通知：停止接收请求、排空、关闭依赖和日志。首个非空故障保留，故障退出码为 1；正常停止在没有其他故障时退出码为 0。初始化期间通知、并发通知和排空期间报告故障均可处理。
App 生命周期入口保留异常 context 取消原因；符合 context.Canceled 的信号取消保持正常停止。生成入口还读取 Controller.Err，保留显式依赖故障，即使该故障包装了 context.Canceled。
/health/ready 修复绕过响应配置的问题，默认与 liveness 一起使用项目 App 的响应格式。就绪成功使用项目成功码与提示；未就绪使用 NOT_READY 的项目错误定义，同时固定 HTTP 503。raw 模式只返回健康数据；内部探针原因仅供日志。
server.endpoints 控制三个内置 GET 接口的开关和路径，健康端点另有 responseMode。支持环境变量覆盖。OpenAPI 保持原始规范，不包业务公共体；关闭 HTTP 端点不影响生成文档。
.api 不再固定保留三个默认路径；启用的内置路径与业务 GET/参数/通配路由重叠时，启动前返回明确错误并清理已创建的依赖。关闭或改名后允许项目接管旧路径。全局中间件继续执行。

验收

源码测试和实际生成项目验证记录见生命周期与端点验收。复验命令：

GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -p=1 -count=1 -timeout=300s ./...
go vet ./...
go build ./...
python3 scripts/verifyManagedProject.py --report performance/lifecycleEndpointsLocal.json
python3 scripts/verifyManagedRelease.py --version v0.13.0-preview --report performance/lifecycleEndpointsRemote.json

发布后的远程空缓存验收已通过，耗时 26.55 秒；机器报告确认 CLI 和生成项目使用同版远程 module，无本地 replace。报告单独提交，发布标签保持在代码提交 f0991d3ff248e4cb32812c368f0f8ba28740a6c7。此版仍为 preview；具体业务的租约失效保护、鉴权与事务回归由接入项目验证。资源清理顺序不代表能强行结束忽略 context 取消的业务 goroutine；项目 Close 必须停止并等待自己启动的后台任务。

v0.12.0-preview（历史版本）

本版用于固定版本开展业务接入。生成器统一维护服务根目录 main.go、路由、HTTP Handler、DTO 和 OpenAPI，业务方维护 .api、config、svc、logic、repository 与项目中间件。目录不再生成 cmd/server、settings、servicecontext 或 service。

安装与接入

仓库权限及 PATH 配置见 README。CLI 与框架使用同一版本：

go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.12.0-preview
go-omni new --module example.com/hello ./hello
cd hello
go mod tidy
go run .

已存在的手写项目可直接 go get git.yuntuo.hk/k2safe/go-omni@v0.12.0-preview。采用生成目录的旧项目在新目录生成后迁入业务代码，详见接入步骤和文件维护边界。新 manifest v2 不兼容旧 manifest；不会静默覆盖手写 main，也不会删除独立 cmd/migrate 等工具。

本版行为

根目录支持 go run / go build；入口负责配置、日志、依赖、HTTP 启动与信号退出。svc 的 AppOptions、GlobalMiddleware 和 OnClose 是显式扩展入口；初始化/监听失败会释放资源，正常退出先排空请求再关闭依赖和日志。
.api 入口通过 @app(defaultResponse: Name) 选择默认响应，覆盖普通路由、404/405 与相应中间件错误；多模板不会按声明顺序猜默认值。字段、状态、业务码和文案由项目配置。
保持 v0.11.1 的错误目录继承：Go 中注册一次，无独立错误目录的生成路由继承 App。带参数提示、内部错误链、raw 响应和独立目录保持各自行为。
raw/multipart 上传及 @produces 下载可直接编写 Logic，由生成 Handler 完成受限读取、响应和流关闭。损坏 multipart 默认 400，超限 413；项目可以定制公开错误。
契约变更提示受影响的 Logic、DTO 字段和请求模式；明确的签名/语法/重复方法错误使 generate --check 失败。重新生成保留业务文件，main 和其他生成文件的漂移也会被检查。

验收与范围

发布前全量 race 测试、go vet、go build 和本地实际生成项目进程验收通过。发布后的空缓存远程验收也已通过，记录见生成项目验收和远程产物报告。报告作为单独提交保存，v0.12.0-preview 标签保持在发布代码提交 158b8002b355f09237cd12f49d9b66ee78d493f3，没有改写。复验命令：

GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -p=1 -count=1 -timeout=300s ./...
go vet ./...
go build ./...
python3 scripts/verifyManagedProject.py
python3 scripts/verifyManagedRelease.py --version v0.12.0-preview

远程验收使用空 module 缓存安装已发布 CLI，生成的业务项目仅依赖同版远程 module，无本地 replace；检查根目录运行/构建、重新生成、错误继承/模板参数、上传下载、nethttp/native 的真实请求与退出信号，以及初始化失败/监听失败/请求排空后的清理。

本版不代表具体业务项目已完成迁移验收。HTTP/2 仍为实验状态；真实数据库、云账号和业务服务器不属于本轮验收范围。轻量 Logic 检查不能代替 Go 编译器或业务测试。静态 OpenAPI 不执行 Go 代码，因此不会自动列举仅在 Go 中维护的错误目录。请求流校验不能回滚业务提前执行的副作用，关键写入应放在 body.Complete() 成功之后。

v0.11.1-preview（历史版本）

修复生成路由使用空错误目录遮蔽 omni.WithErrors(catalog) 的问题。错误现在可以只在 Go 中注册一次，.api 无需重复定义错误目录或逐条列出错误。

行为

未声明路由错误列表：继承 App 目录，包括带参数提示及项目自定义 INTERNAL_ERROR 兜底。
显式引用路由错误：继续使用路由独立目录，不与 App 合并。
@errors none 清空 .api 分组错误列表，随后继承 App。
错误继承不覆盖 .api 的返回格式、RawJSON、手写绑定或请求体限额；全局中间件提前返回、标准桥接与克隆保持一致。
空 response.WithErrors / MustWithErrors 返回原 Encoder，既不覆盖 Context 的目录，也不在编码阶段按空目录重新解析错误。

升级

go get git.yuntuo.hk/k2safe/go-omni@v0.11.1-preview
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.11.1-preview
go-omni api generate --dry-run
go-omni api generate
go test ./...

运行时修复也适用于旧 v0.11.0 生成代码，因此升级运行时后即可解除空目录遮蔽。同步升级 CLI 重新生成时不再创建空目录包装；已生成业务文件继续受保护。代码生成最低运行时仍为 v0.11.0-preview。

接入见 README、错误目录继承和只在 Go 注册错误的契约示例。静态 OpenAPI 不执行 Go 配置，保留契约响应结构，不自动列举运行时目录内容。

验收

复现用例在修复前：普通路由通过，生成/RawJSON 路由和提前返回中间件共 12 项失败，均变成 500/英文系统提示。修复后同一批用例通过。

GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -p=1 -count=1 -timeout=300s ./...
go vet ./...
go build ./...
python3 scripts/verifyErrorInheritanceRelease.py --version v0.11.1-preview
python3 scripts/verifyErrorParamsRelease.py --version v0.11.1-preview --report performance/errorInheritanceParamsRemote.json
python3 scripts/verifyCompatibilityRelease.py --version v0.11.1-preview --report performance/errorInheritanceCompatibilityRemote.json

结果见目录继承验收。本轮未修改 eTax/ePay 业务代码，没有使用业务服务器。

44 KiB Raw Blame History Unescape Escape