feat: support primitive response arrays and shared catalog tooling
This commit is contained in:
@@ -1,4 +1,4 @@
|
||||
# 通用业务开发指南（v0.15.0-preview）
|
||||
# 通用业务开发指南（v0.16.0-preview）
|
||||
|
||||
从 [README](README.md) 创建服务后，业务主要维护 `.api`、配置、`svc.Init`、Logic、Repository 和项目中间件。本页说明通用接入能力；字段、错误码、权限、表结构和事务边界都由项目定义。
|
||||
|
||||
@@ -21,12 +21,17 @@ delete /item
|
||||
| 契约 | Logic 返回 | 成功数据 |
|
||||
| --- | --- | --- |
|
||||
| `returns (Item)` | `(*types.Item, error)` | 对象；nil 被视为实现错误 |
|
||||
| `returns ([]Item)` | `([]types.Item, error)` | 数组；nil 统一输出 `[]` |
|
||||
| `returns ([]Item)` | `([]types.Item, error)` | 对象数组；nil 统一输出 `[]` |
|
||||
| `returns ([]string)` | `([]string, error)` | 字符串数组 |
|
||||
| `returns ([]int64)` / `([]bool)` | `([]int64, error)` / `([]bool, error)` | 数值 / 布尔数组 |
|
||||
| `returns ([]any)` | `([]any, error)` | 动态 JSON 数组，元素允许对象、数组、标量和 null |
|
||||
| `returns (*Item)` | `(*types.Item, error)` | 对象或 `null` |
|
||||
| `returns (null)` | `error` | HTTP 200 和空业务数据 |
|
||||
| 不写 returns | `error` | HTTP 204，无响应体 |
|
||||
|
||||
统一响应中的空数据是否显示，仍遵循项目模板的 `dataMode`；需要 `data:null` 就设置 `dataMode: always`。`@response raw` 输出业务数据本身，包括 `[]`、对象或 `null`。可用 `@status 201/202`；204 不能声明响应类型。根类型当前支持以上四种形式，嵌套字段继续支持既有 slice/map/pointer/scalar/any。
|
||||
统一响应中的空数据是否显示，仍遵循项目模板的 `dataMode`；需要 `data:null` 就设置 `dataMode: always`。`@response raw` 输出业务数据本身，包括 `[]`、对象或 `null`。可用 `@status 201/202`；204 不能声明响应类型。嵌套字段继续支持既有 slice/map/pointer/scalar/any。
|
||||
|
||||
基础类型数组还支持 int/int8/int16/int32、uint/uint16/uint32/uint64、float32/float64。nil 根数组都输出 `[]`；`[]any` 在 OpenAPI 中是 `type: array, items: {}`，不限制元素形状，但元素必须可被标准 JSON 编码器序列化。`[]uint8`（Go 的 byte slice）会编码为 base64，故明确拒绝；数字数组可用 `[]int32`，二进制用下载接口。当前不支持根嵌套数组或根自定义 scalar 数组。
|
||||
|
||||
## 契约驱动的请求策略
|
||||
|
||||
@@ -113,6 +118,23 @@ duration 使用 `250ms`、`3s`；slice/map 使用 JSON，如 `[1,3,5]`、`{"retr
|
||||
|
||||
手写项目可使用 `config.LoadProject(path, defaults, config.EnvOptions{Prefix:"MY_APP_"})`，或分别调用 `ApplyDefaults/DecodeFile/OverlayEnv`。读取失败不修改输入默认值；诊断不会打印输入值。不要主动打印含密钥的整个配置，或把底层解析错误展开到公开响应。Validate 不打开日志文件、数据库或存储连接；证书的可读性和握手信任在依赖初始化阶段验证。
|
||||
|
||||
### 一次覆盖完整配置与 HTTP/日志短名称
|
||||
|
||||
```go
|
||||
cfg, err = config.OverlayEnv(cfg, config.EnvOptions{
|
||||
Prefix: "MY_APP_",
|
||||
Empty: "reject", // allow / ignore / reject，项目自行选择
|
||||
Aliases: config.ServerEnvAliases("MY_APP_", "server"),
|
||||
// Lookup 可注入测试或项目配置源；默认 os.LookupEnv。
|
||||
})
|
||||
```
|
||||
|
||||
不要再紧接着调用 `ApplyEnv(cfg.Server, ...)`。上面的调用同时处理完整配置和 HTTP_ADDR、SERVICE、LOG_LEVEL 等框架短名称。例如 `MY_APP_SERVER_ADDRESS` 与 `MY_APP_HTTP_ADDR` 指向同一字段，**完整名称优先**；未设置时才读取短名称。完整名称显式设空仍优先：allow 交给该字段解析（string 可清空；数字等仍要求合法值），ignore 保留文件/默认值，reject 报错。不会因 ignore 再退回别名。字段 `env` 标签的 empty 规则优先于全局规则。
|
||||
|
||||
自定义别名用 `EnvOptions.Aliases`，键是完整环境名、值是按优先级排列的别名数组。两种名称都使用同一 Lookup、空值策略和类型转换；布尔 false、数值 0 与未设置不同。集合始终使用 JSON，包括 `MY_APP_TRUSTED_PROXIES='["127.0.0.1"]'`。
|
||||
|
||||
新项目模板一次调用 OverlayEnv，默认 `Empty: "ignore"`。旧 `ApplyEnv` 保留原有忽略空值、修剪空白及 TRUSTED_PROXIES 逗号列表行为。已有项目的 `internal/config` 属于开发者文件，升级不覆盖它；按上例合并原来的两次覆盖调用后，保留项目自己的 Validate。日志输出的显式完整名称也优先于短名称。
|
||||
|
||||
## 依赖、日志与中间件
|
||||
|
||||
`internal/svc/runtimeGen.go` 持续由生成器维护。项目的 ServiceContext 嵌入 `*lifecycle.Runtime`，只在 `Init(ctx)` 中装配额外依赖：
|
||||
@@ -185,21 +207,9 @@ go-omni api generate --check
|
||||
|
||||
格式化保留注释、token 和多行字面量，规范四空格缩进、空行、行首尾空白及相邻单行字段的类型/标签/行尾注释对齐；结果幂等。先校验完整契约，check 不写文件；导入的共享目录不被某个服务的格式化命令修改。DTO 按源 `.api` 输出 `dto<Source><摘要>Gen.go`，都属于 `types` 包，跨文件引用无需改包名。
|
||||
|
||||
Go Catalog 是错误的唯一来源时，显式导出文档元数据：
|
||||
Go Catalog 是错误的唯一来源时，优先使用 workspace 的显式导出配置，不再维护导出/复制脚本。AppOptions 仍通过 `omni.WithErrors(apierrors.Catalog())` 注册同一个 Go 函数，运行期只注册一次。单个项目也可继续使用 `errors.ExportCatalog` 导出入口目录的 `api/omni.errors.json`；此文件和下面的共享 source 二选一。
|
||||
|
||||
```go
|
||||
// 在项目自己的导出命令中；appErrors.Catalog 与 AppOptions 注册同一函数。
|
||||
if err := omnierrors.ExportCatalog(os.Stdout, appErrors.Catalog()); err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
```
|
||||
|
||||
```sh
|
||||
go run ./cmd/exportErrors > api/omni.errors.json
|
||||
go-omni api generate
|
||||
```
|
||||
|
||||
文件是派生产物，应纳入版本控制并由业务 CI 检查导出漂移。CLI 自动读取入口目录的 `omni.errors.json`，校验错误目录、合并状态/模板参数/具体示例到 OpenAPI；不会运行项目 Go，不创建另一份运行期注册器。带独立错误目录的路由继续使用自己的目录。没有路由级精确错误列表时，文档描述 App 目录的公共错误集合；特殊自定义 Encoder 的文档由项目显式扩展。
|
||||
OpenAPI 自动把有收益的重复响应、schema 和示例移到 `components.responses/schemas/examples`，通过标准 `$ref` 引用。HTTP 200 同时含成功和业务失败时保留两种 schema、业务码、模板参数示例和 data:null；业务响应内容不会改变。消费 OpenAPI 的工具需要支持标准本地引用。
|
||||
|
||||
## 两个服务共享契约
|
||||
|
||||
@@ -241,9 +251,57 @@ go-omni workspace check --file omni.workspace.json
|
||||
|
||||
各服务保持独立 module；可显式填写各服务的 `api`（相对服务目录）和 `module`。所有服务预检通过后再写；每个服务独立提交文件事务，不承诺跨项目的崩溃原子性。check 汇总格式与生成漂移；业务编译/测试仍在各 module 执行。
|
||||
|
||||
### 同一份 Go 错误目录供多个服务生成
|
||||
|
||||
在 workspace 清单显式声明提供目录的 Go 包和函数：
|
||||
|
||||
```json
|
||||
{
|
||||
"errorCatalogs": [{
|
||||
"dir": ".",
|
||||
"package": "example.com/project/internal/apierrors",
|
||||
"function": "Catalog",
|
||||
"output": "contracts/common/errors.json"
|
||||
}],
|
||||
"services": [{"dir":"services/api"}, {"dir":"services/id"}]
|
||||
}
|
||||
```
|
||||
|
||||
`dir` 相对 workspace，必须包含 go.mod；函数签名为 `func Catalog() errors.Catalog`。允许 module 内的 internal 包。先准备 output 的父目录。生成器构建一个临时导出程序，使用 Go overlay、临时 go.mod/go.sum 和 `-mod=readonly`，不会往项目增加导出命令或修改 go.mod/go.sum。最多 16 个提供方，每个有 90 秒构建/执行总时限和 1 MiB stdout 限制。错误消息不回显程序输出。
|
||||
|
||||
只有显式运行 **workspace generate/check** 会执行清单指定的 Go 包及其依赖初始化；不要指向不信任的包。提供目录的函数应只构造目录，不连接数据库、启动服务、写 stdout 或修改项目。框架不扫描其他包，也不通过 shell 执行配置字符串。普通 api validate/export/generate 和 workspace format 只读取现有元数据。
|
||||
|
||||
各服务在自己的 `api/omni.imports.json` 引用共享 JSON：
|
||||
|
||||
```json
|
||||
{
|
||||
"roots": {"common":{"path":"../../../contracts/common","version":"1.0.0"}},
|
||||
"errors": {
|
||||
"source": "@common/errors.json",
|
||||
"include": ["USERNAME_INVALID", "INTERNAL_ERROR"],
|
||||
"routes": {"GET /permissions":["INTERNAL_ERROR"]}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`include` 省略或 null 表示全部目录，`[]` 表示不列业务错误；routes 按 **大写方法 + 空格 + .api 原路径**（如 `GET /users/:id`）覆盖服务级列表。错误标识、路由拼错或重复标识会明确报错。路由已经通过 `.api @errors` 声明独立运行期目录时，不能再给它设置文档 routes 列表。
|
||||
|
||||
**这些列表只决定文档展示，不修改 App 错误目录、路由继承或运行期可返回的错误。** `.api` 不需要重复定义 Go 错误表。状态、业务码、提示和模板参数仍来自同一 Catalog；特殊自定义 Encoder 的文档由项目显式扩展。
|
||||
|
||||
```sh
|
||||
# 首次生成导出一次共享目录，所有服务预检通过才写入
|
||||
# 共享 JSON 不复制到各服务；已有 api/omni.errors.json 请显式移除后改用 source。
|
||||
go-omni workspace generate --file omni.workspace.json
|
||||
go-omni workspace format --file omni.workspace.json
|
||||
go-omni workspace generate --file omni.workspace.json
|
||||
go-omni workspace check --file omni.workspace.json
|
||||
```
|
||||
|
||||
共享 JSON 应纳入版本控制。check 在内存重新导出并比较 JSON，然后检查所有服务；缺失或过期时失败，不更新项目文件。Go 构建缓存仍可能更新；显式提供方的自有副作用不属于生成器可隔离范围。业务 CI 仍执行各 module 的编译与测试。目录函数本身有变化时重新 generate，受控共享根的固定 SHA256 如需改变仍由项目显式更新。
|
||||
|
||||
## v0.13 项目升级
|
||||
|
||||
先使用与目标框架匹配的 CLI；CLI 会提示与 go.mod 不同的版本。当前生成模板至少需要 v0.15.0-preview（或显式引用当前源码）。
|
||||
先使用与目标框架匹配的 CLI；CLI 会提示与 go.mod 不同的版本。当前生成模板至少需要 v0.16.0-preview（或显式引用当前源码）。
|
||||
|
||||
```sh
|
||||
go-omni api upgrade --dir . --dry-run
|
||||
|
||||
Reference in New Issue
Block a user