fix: inherit App error catalogs on generated routes without local errors
This commit is contained in:
22
README.md
22
README.md
@@ -2,7 +2,7 @@
|
||||
|
||||
GoOmni 是面向多个业务项目复用的 Go 后端框架：用 `.api` 定义接口、请求和返回类型，生成项目目录、HTTP 接入代码及 OpenAPI，业务代码负责 Service 和 Repository。也可以在已有项目中直接使用 `omni.New()`，或单独引入日志、存储等模块。
|
||||
|
||||
**从这份 README 开始即可接入。** 当前版本为 **`v0.11.0-preview`**，Go **1.22+**；CLI 和项目依赖使用同一固定版本。框架不依赖 Gin，默认使用标准库网络层，提供可切换的 native HTTP/1.1 和实验性 HTTP/2 适配器。
|
||||
**从这份 README 开始即可接入。** 当前版本为 **`v0.11.1-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.11.0-preview
|
||||
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.11.1-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.11.0-preview \
|
||||
go-omni api new --framework-version v0.11.1-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.11.0-preview \
|
||||
go-omni new --api catalog.api --framework-version v0.11.1-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.11.0-preview \
|
||||
go-omni new --api catalog.api --framework-version v0.11.1-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.11.0-preview --module example.com/billing ./billing` 创建手写接口的 CRUD 示例项目；两种生成方式选择一种即可。
|
||||
不采用 `.api` 时，也可以用 `go-omni new --framework-version v0.11.1-preview --module example.com/billing ./billing` 创建手写接口的 CRUD 示例项目；两种生成方式选择一种即可。
|
||||
|
||||
## 已有项目：按模块接入
|
||||
|
||||
在业务项目的 **go.mod 所在目录**执行：
|
||||
|
||||
```sh
|
||||
go get git.yuntuo.hk/k2safe/go-omni@v0.11.0-preview
|
||||
go get git.yuntuo.hk/k2safe/go-omni@v0.11.1-preview
|
||||
```
|
||||
|
||||
已有项目可直接复用现有目录、Service、Repository 和数据库连接，先选择一个接口接入。也可以只用 `logx`、`storage` 等包，暂时保留原来的 HTTP 框架。
|
||||
@@ -309,7 +309,9 @@ auth UserAuth (
|
||||
|
||||
业务错误可以集中定义，业务只选择发生了哪个错误。**HTTP 状态由项目配置，业务失败可以返回 HTTP 200**；框架不根据 HTTP 状态单独判断成功与否。
|
||||
|
||||
API 项目推荐在公共 `.api` 中声明目录，其他契约通过 `import` 引用：
|
||||
错误目录支持两种维护方式，按项目选择一种：**Go 中定义并用 `omni.WithErrors` 注册一次**，或者在公共 `.api` 中声明并生成调用函数。前者不要求 `.api` 重复声明目录或逐路由列出错误；生成路由默认继承 App 目录。
|
||||
|
||||
采用 `.api` 管理时，其他契约可通过 `import` 引用：
|
||||
|
||||
```text
|
||||
errorCatalog CommonErrors (
|
||||
@@ -358,7 +360,7 @@ app := omni.New(
|
||||
// return omnierrors.ByCode("USERNAME_INVALID").WithCause(err)
|
||||
```
|
||||
|
||||
目录也可放入 `config.Config.Errors`，由 JSON/YAML 加载；生成项目的路径为 `server.errors`，但契约生成路由以 `.api` 绑定的目录为准。不同 App 独立持有配置，单路由也可通过 `response.WithErrors` 绑定专用目录与自定义 Encoder。直接输出文本、XML、下载或已提交的响应继续保留原协议。
|
||||
目录也可放入 `config.Config.Errors`，由 JSON/YAML 加载；生成项目的路径为 `server.errors`，生成路由只有显式引用错误定义时才使用 `.api` 独立目录，未声明则继承 App。不同 App 独立持有配置，单路由也可通过 `response.WithErrors` 绑定专用目录与自定义 Encoder。直接输出文本、XML、下载或已提交的响应继续保留原协议。
|
||||
|
||||
访问日志保留实际 HTTP 状态，并增加失败标记、逻辑错误标识和目录业务码；指标、链路及框架标准中间件/幂等重放也保留失败语义。未知标识使用系统错误兜底，内部 cause 不写入默认公开响应。旧 `error (...)`、`New` / `BadRequest` / `Codes` / `Messages` 继续支持；新目录与旧映射冲突会报错，避免静默覆盖。
|
||||
|
||||
@@ -447,7 +449,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.11.0-preview` 的变化、迁移边界和验收记录见 [发布说明](RELEASE.md)。
|
||||
升级时先安装目标版本的 CLI，再在业务 module 中 `go get` **同一版本**；API 项目随后执行上述生成与测试步骤，手写项目只需依赖升级及业务回归。`v0.11.1-preview` 的变化、迁移边界和验收记录见 [发布说明](RELEASE.md)。
|
||||
|
||||
## 按需深入
|
||||
|
||||
|
||||
Reference in New Issue
Block a user