feat: release v0.28 generic Go project scaffolding and lifecycle entry

2026-09-29 23:58:20 +08:00
parent f8e0dcc5a6
commit 0b6c0043b6
42 changed files with 2134 additions and 117 deletions
--- a/PROGRAM.md
+++ b/PROGRAM.md
@@ -0,0 +1,81 @@
+# 通用 Go 项目模板
+
+从 v0.28.0-preview 起，`project new/generate/check` 提供不绑定协议与业务的工程骨架。默认只有配置、日志、依赖装配、生命周期和普通 Go 运行入口；不生成 `.api`、HTTP Handler、Swagger、业务任务，也不监听端口、连接数据库或队列。不增加第三方依赖。
+
+## 创建与运行
+
+```sh
+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 .                 # 默认等待 SIGINT / SIGTERM
+go build -o program .
+```
+
+目标目录必须为空；未指定 module 时使用目录名。远程安装的 CLI 将自己的固定版本写入 go.mod，无本地替换。当前通用模板要求框架 v0.28.0-preview 或更新版本。源码开发可显式 `--framework-dir /path/to/go-omni`，不会从当前工作目录隐式选择本地框架。`--framework-version` 可指定兼容版本。框架版本、依赖更新由项目修改 go.mod，重新生成不会代为升级依赖。
+
+常驻程序、一次性程序用同一份骨架：项目自己的 `Run` 决定何时完成。完整生成项目见 [examples/program](examples/program/README.md)，不需要外部服务。
+
+## 文件职责
+
+| 路径 | 维护方与职责 |
+| --- | --- |
+| `main.go` | 生成器：信号、启动、运行入口监督、退出状态与日志收尾 |
+| `internal/config/loadGen.go` | 生成器：统一配置加载 |
+| `internal/svc/runtimeGen.go` | 生成器：依赖初始化及失败收尾 |
+| `internal/config/config.go` | 项目：Config、Default、Validate；初始只含 log/lifecycle |
+| `internal/config/loader.go` | 项目：按需注册额外文件格式 |
+| `etc/config.yaml` | 项目：配置与显式环境引用 |
+| `internal/svc/serviceContext.go` | 项目：依赖字段、Init、资源与后台工作登记 |
+| `internal/run/run.go` | 项目：Run 的实际实现 |
+| `go.mod`、README、.gitignore、其他 Go 文件 | 项目：生成器不覆盖 |
+| `.goOmni/projectManifest.json` | 生成器：工程身份、模板版本、生成文件哈希；应提交 Git |
+
+配置遵守 [CONFIG.md](CONFIG.md)：默认值 → 文件显式 `${NAME}` / `${NAME:-fallback}` → 类型绑定 → 校验，没有隐式环境覆盖。JSON/YAML/XML 内置；`-config ""` 只用默认值。`-check-config` 不打开日志文件、不初始化依赖、不调用 Run。日志通过独立实例传给 svc，并注入 Context/WorkContext；不替换进程级默认日志实例。
+
+## 运行与退出
+
+```go
+func Run(ctx context.Context, deps *svc.ServiceContext) error {
+    // 一次性程序可完成处理后直接 return nil。
+    // 常驻程序收到 ctx.Done() 后停止自己的主流程。
+    <-ctx.Done()
+    return nil
+}
+```
+
+`nil` 表示正常完成，返回 error 表示运行失败。后台组件用 `RequestShutdown(err)` 报告致命故障，`RequestShutdown(nil)` 请求正常停止。框架不替项目重试、重新调度或重启任务。
+
+依赖在 `svc.Init` 中装配：创建后立即用 `OnClose` 登记清理，后台组件同时登记同名 `OnStop` 和 `OnDrain`。所有登记应在 Init 返回前完成；Run 不得并发追加生命周期登记。组件何时接收工作由项目决定，停止后不得重新开始领取或启动未登记的工作。
+
+- `Context()` 是提前停止通知，用来停止主流程或接收新工作。
+- `WorkContext()` 在正常排空期间仍有效，用于已接受的工作。
+- `OnStop` 停止接收新工作，不关闭处理中的工作仍依赖的资源。
+- `OnDrain` 返回 nil，必须意味着组件处理、确认和 defer 收尾均已结束。仅返回 `ctx.Err()` 不能证明结束。
+- 全部停止钩子先于全部排空钩子；同阶段并行。有先后依赖的组件在一个钩子内显式排序。
+- 全部工作确认结束后，资源按 `OnClose` 登记的反序释放，最后关闭入口拥有的日志。
+
+生成入口自动监督 Run 本身，以 `go-omni/project/run` 保留名称登记完成屏障。收到信号、Run 返回或报告故障后开始收尾，同时等待 Run 及其他已登记工作。Run 不应等待资源关闭：资源关闭发生在 Run 完成之后。
+
+初始化失败同样收尾已创建的资源和已启动的工作。Init/Run 内 panic 被转为失败，安全收尾后进程以非零状态退出；任意自建 goroutine 的 panic 仍由项目负责处理。Run 不响应取消或其他工作无法确认结束时，`lifecycle.stopTimeout/drainTimeout/cancelTimeout` 限定等待窗口，返回 `ErrResourcesRetained`，跳过共享资源和日志关闭，以失败状态退出。取消后的工作不能被 Go 强制终止，保留资源不代表工作已经完成。SIGKILL 和进程崩溃不会执行退出钩子。
+
+详见 [生命周期契约](lifecycle/README.md)。现成组件必须按其真实停止/完成语义适配，不能把某个 `Run/Close` 返回直接视为业务结束。
+
+## 生成检查与兼容
+
+```sh
+go-omni project generate --dry-run
+go-omni project generate
+go-omni project check              # 等价于 project generate --check
+go test ./...
+```
+
+生成器不执行项目 Go 代码、不下载依赖。check/预览只读，不创建锁文件；生成时使用独立项目锁、路径和哈希预检。生成文件被手工修改会报冲突，不提供强制覆盖。删除的生成文件可补回；缺失的项目所有文件必须显式恢复，避免把删除的业务文件当成空白骨架重建。
+
+每个文件通过原子替换写入，普通写入失败回滚此前变更；整个目录不具备崩溃事务性。生成期间不要同时手工编辑。发现遗留 project.lock 时，先确认没有生成进程再手工移除。
+
+check 检查模板漂移和必要文件，不检查业务正确性，也不能替代 Go 编译与测试。新的模板版本会重新生成受管文件；不自动合并项目所有文件或更新 go.mod。未知的新清单版本会要求使用兼容 CLI。
+
+原有 `new` / `api new` 及 API 工程行为保留。通用工程使用自己的清单和命令，不能交给 `api generate` 或 `add` 转换；新增业务包直接写普通 Go。现有 `workspace` 命令仍面向 API 契约工程；多个通用工程可分别执行 `project check --dir <目录>`，本版不引入混合工作区配置。