k2safe/go-omni
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add typed error message templates and stable replay snapshots

Browse Source
This commit is contained in:
k2safe
2026-09-24 15:05:08 +08:00
parent 2041e7f661
commit 6e3f025aad
32 changed files with 1570 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
README.md
View File

@@ -2,7 +2,7 @@
GoOmni 是面向多个业务项目复用的 Go 后端框架：用 `.api` 定义接口、请求和返回类型，生成项目目录、HTTP 接入代码及 OpenAPI，业务代码负责 Service 和 Repository。也可以在已有项目中直接使用 `omni.New()`，或单独引入日志、存储等模块。
**从这份 README 开始即可接入。** 当前版本为 **`v0.10.0-preview`**，Go **1.22+**；CLI 和项目依赖使用同一固定版本。框架不依赖 Gin，默认使用标准库网络层，提供可切换的 native HTTP/1.1 和实验性 HTTP/2 适配器。
**从这份 README 开始即可接入。** 当前版本为 **`v0.11.0-preview`**，Go **1.22+**；CLI 和项目依赖使用同一固定版本。框架不依赖 Gin，默认使用标准库网络层，提供可切换的 native HTTP/1.1 和实验性 HTTP/2 适配器。
响应字段、业务码、登录方式、权限规则和数据库表结构由接入项目决定。文中的 `code/msg/data`、`200/9999` 都是示例配置，可以替换。
@@ -26,7 +26,7 @@ module 地址是 `git.yuntuo.hk/k2safe/go-omni`。先确保本机 Go 和 Git 可
```sh
export GOPRIVATE=git.yuntuo.hk
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.10.0-preview
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.11.0-preview
export PATH="$(go env GOPATH)/bin:$PATH"
go-omni --help
```
@@ -38,7 +38,7 @@ go-omni --help
在准备存放业务项目的目录执行，`./hello` 必须是新目录或空目录；把 `example.com/hello` 换成自己的 Go module 名称。
```sh
go-omni api new --framework-version v0.10.0-preview \
go-omni api new --framework-version v0.11.0-preview \
--module example.com/hello ./hello
cd hello
go mod tidy
@@ -126,7 +126,7 @@ service catalog-api {
```sh
go-omni api validate --api catalog.api
go-omni new --api catalog.api --framework-version v0.10.0-preview \
go-omni new --api catalog.api --framework-version v0.11.0-preview \
--module example.com/catalog ./catalog
cd catalog
go mod tidy
@@ -167,21 +167,21 @@ curl -i http://127.0.0.1:8080/api/v1/items/missing
需要 MySQL、文件存储或文件日志时，**首次生成**可以使用：
```sh
go-omni new --api catalog.api --framework-version v0.10.0-preview \
go-omni new --api catalog.api --framework-version v0.11.0-preview \
--module example.com/catalogFull --database mysql --storage local \
--log-output file --log-format json ./catalogFull
```
该命令在 `catalog.api` 所在目录执行，目标仍需是新目录。数据库迁移、表结构和 Repository 由项目维护，API 模板不自动建表；MySQL DSN 通过 `GO_OMNI_DB_DSN` 提供。存储还可选 `s3`、`r2`、`oss`，按生成项目的配置说明提供桶、端点和凭据。完整装配例子见 [userService](examples/userService/README.md)。
不采用 `.api` 时，也可以用 `go-omni new --framework-version v0.10.0-preview --module example.com/billing ./billing` 创建手写接口的 CRUD 示例项目；两种生成方式选择一种即可。
不采用 `.api` 时，也可以用 `go-omni new --framework-version v0.11.0-preview --module example.com/billing ./billing` 创建手写接口的 CRUD 示例项目；两种生成方式选择一种即可。
## 已有项目：按模块接入
在业务项目的 **go.mod 所在目录**执行：
```sh
go get git.yuntuo.hk/k2safe/go-omni@v0.10.0-preview
go get git.yuntuo.hk/k2safe/go-omni@v0.11.0-preview
```
已有项目可直接复用现有目录、Service、Repository 和数据库连接，先选择一个接口接入。也可以只用 `logx`、`storage` 等包，暂时保留原来的 HTTP 框架。
@@ -362,6 +362,15 @@ app := omni.New(
访问日志保留实际 HTTP 状态，并增加失败标记、逻辑错误标识和目录业务码；指标、链路及框架标准中间件/幂等重放也保留失败语义。未知标识使用系统错误兜底，内部 cause 不写入默认公开响应。旧 `error (...)`、`New` / `BadRequest` / `Codes` / `Messages` 继续支持；新目录与旧映射冲突会报错，避免静默覆盖。
动态提示也可以集中配置，在目录中声明 `message: "{label}不能超过{max}个字符"` 和有序 `params`（label/string、max/int），生成带类型的调用：
```go
return apierrors.TextTooLong("企业名称", 100)
// 最终提示：企业名称不能超过100个字符
```
运行时支持 `omnierrors.ByCode("TEXT_TOO_LONG").WithParams(...)`，与生成函数共用解析器。固定错误继续无参数调用；缺参或类型错误使用系统兜底。模板、参数类型及具体响应示例同步写入 OpenAPI。完整示例见 [errorParams.api](examples/contracts/errorParams.api)。
更详细的配置、作用域和升级步骤见 [统一错误目录](errors/README.md)。
### 数据库、存储及其他模块
@@ -438,7 +447,7 @@ go test ./...
`Gen.go`、`docs/openapi.json` 和 manifest 由生成器管理，手动修改会报告冲突。Service、Repository、中间件实现、main、配置和依赖装配属于项目，重复生成保留手写内容；契约改变后仍需自行调整业务签名并通过编译。将 `.api`、生成文件和 `.goOmni/apiManifest.json` 一起提交，CI 可运行 `generate --check` 检查是否同步。
升级时先安装目标版本的 CLI，再在业务 module 中 `go get` **同一版本**；API 项目随后执行上述生成与测试步骤，手写项目只需依赖升级及业务回归。`v0.10.0-preview` 的变化、迁移边界和验收记录见 [发布说明](RELEASE.md)。
升级时先安装目标版本的 CLI，再在业务 module 中 `go get` **同一版本**；API 项目随后执行上述生成与测试步骤，手写项目只需依赖升级及业务回归。`v0.11.0-preview` 的变化、迁移边界和验收记录见 [发布说明](RELEASE.md)。
## 按需深入