213 lines
12 KiB
Markdown
213 lines
12 KiB
Markdown
# 公共字段、结构映射与生成选项
|
||
|
||
本页对应 `v0.17.0-preview`。CLI 与框架依赖固定到同一版本：
|
||
|
||
```sh
|
||
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.17.0-preview
|
||
# 已有业务项目内执行：
|
||
go get git.yuntuo.hk/k2safe/go-omni@v0.17.0-preview
|
||
```
|
||
|
||
私有仓库访问设置见 [安装说明](README.md#准备环境与安装)。升级不会覆盖业务文件；已有中间件保持 handlers 模式，切换工厂模式按本页迁移步骤完成。
|
||
|
||
## 一份项目生成配置
|
||
|
||
新项目根目录生成开发者维护的 `omni.gen.json`：
|
||
|
||
```json
|
||
{
|
||
"repository": "none",
|
||
"middleware": "factories"
|
||
}
|
||
```
|
||
|
||
该文件与 `.api` 一起提交。每次 `api generate`、`--check`、`--dry-run` 和 `workspace generate/check` 都会读取；`api validate/export/format` 只处理契约，不加载业务 Go 类型。
|
||
|
||
- `repository: none` 是默认值，不创建空 Repository 文件。`group` 按 `.api` 的 group 补齐 `internal/repository/<group>/repository.go`；文件始终属于业务。切回 none 后不再补骨架，已有文件不删除、不覆盖。实际 SQL、ORM 和仓储划分由项目决定。
|
||
- `middleware: factories` 是新项目默认值，按下文自动初始化。`handlers` 保留原有 `Defaults()` 与 `func(next Handler) Handler` 接口，供既有项目逐步迁移。
|
||
- `mappings` 可省略；只有明确列出的类型对才生成映射。未启用时不会运行 Go 类型加载命令，也不增加运行时依赖。
|
||
- 升级首次遇到没有配置的旧 manifest 时，补一份 `middleware: handlers` 的配置，保留原有手写注册；Repository 默认 none。生成配置建立后不能直接删除，否则生成失败，避免误关闭映射或改变中间件模式。
|
||
|
||
## 公共字段组合
|
||
|
||
```text
|
||
type EmployeeFields {
|
||
// 员工姓名。
|
||
Name string `json:"name" binding:"max=80"`
|
||
Salary Money `json:"salary"`
|
||
}
|
||
|
||
type EnterpriseRequest {
|
||
EmployeeFields
|
||
}
|
||
|
||
type AdminRequest {
|
||
EmployeeFields
|
||
CompanyID string `path:"companyId"`
|
||
}
|
||
```
|
||
|
||
`Money` 由项目按既有 scalar 语法声明。组合行只有已声明的对象类型名，不加指针或字段 tag。公共对象可以通过已有相对 import 或声明过的共享根 `@common/...` 引入。
|
||
|
||
生成器展开为普通 Go 字段。JSON 保持平铺；字段的绑定来源、校验、注释、可空性和 OpenAPI 使用同一份展开结果。不会在 JSON 中增加 `EmployeeFields` 一层。重复 Go 字段、重复来源字段名、循环组合、未知对象和过深展开均失败；即使重复字段类型相同，也不能隐式覆盖。要改变某个字段的规则，应拆出更小的公共组合。
|
||
|
||
允许多层组合，上限 32 层、单类型 4096 字段、全契约展开 65536 字段。Go 匿名指针嵌入并非本功能；生成 DTO 中不会使用匿名嵌入。
|
||
|
||
## 可选结构映射
|
||
|
||
`.api` 生成 DTO，业务独立维护输入/结果类型。项目明确选择需要自动赋值的类型对；不从数据库反向生成公开接口，不自动推断反向映射。
|
||
|
||
假设 `types.AdminRequest` 有 `Name string`、`Salary amount.Money`、`CompanyID string`，业务的 `domain.EmployeeInput` 有 `EmployeeName string` 和同类型 `Salary`：
|
||
|
||
```json
|
||
{
|
||
"repository": "none",
|
||
"middleware": "factories",
|
||
"mappings": [
|
||
{
|
||
"name": "ToEmployeeInput",
|
||
"source": {"package": "example.com/payroll/internal/types", "type": "AdminRequest"},
|
||
"target": {"package": "example.com/payroll/internal/domain", "type": "EmployeeInput"},
|
||
"fields": {
|
||
"EmployeeName": {"source": "Name"}
|
||
},
|
||
"ignoreSource": {
|
||
"CompanyID": "由 Logic 单独做企业范围授权，不属于请求体输入"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
执行 `go-omni api generate` 后，产生独立的生成文件 `internal/mapping/mappingsGen.go`：
|
||
|
||
```go
|
||
func ToEmployeeInput(source types.AdminRequest) (domain.EmployeeInput, error) {
|
||
var result domain.EmployeeInput
|
||
result.EmployeeName = source.Name
|
||
result.Salary = source.Salary
|
||
return result, nil
|
||
}
|
||
```
|
||
|
||
包别名由生成器决定。业务调用 `mapping.ToEmployeeInput(*req)`；反向响应映射按另一条 source/target 规则声明。两个类型完全相同时通常无需映射。
|
||
|
||
### 类型与覆盖检查
|
||
|
||
自动赋值要求同名且 **Go 类型一致**（类型别名按 Go 类型系统处理），字段名使用 Go 名称，不按 JSON 标签猜对应关系。int32 → int64、`*Money` → Money、数值 ID → string 都必须显式转换。不会暗中补零、解引用或执行数字强转。
|
||
|
||
每个源字段必须被使用或出现在 `ignoreSource`；每个目标字段必须被赋值或出现在 `ignoreTarget`。忽略规则必须给出非空原因，目标忽略明确意味着保留零值；规则引用不存在的字段也会失败。新字段若无法自动匹配，会在生成阶段报错。两边同时添加的同名同类型字段会自动加入生成代码，`--check` 检出未重新生成的差异。
|
||
|
||
根类型是项目可导入的具名结构；支持值类型匿名嵌入，规则可用 `Employee.EmployeeName` 这样的实际 Go 字段路径。同名提升歧义、未导出字段和匿名指针嵌入拒绝处理。普通具名嵌套字段使用独立映射或转换函数，不猜测内部结构。泛型声明不能直接作为根；具体字段类型按 Go 类型系统检查。
|
||
|
||
配置变化、遗漏映射、类型错误会在写入前失败。映射生成与其他生成产物使用同一套文件所有权机制；手改映射生成文件会被拒绝覆盖。
|
||
|
||
### 显式转换函数
|
||
|
||
```json
|
||
"fields": {
|
||
"Salary": {
|
||
"source": "Salary",
|
||
"convert": {"package": "example.com/payroll/internal/convert", "name": "SalaryValue"}
|
||
}
|
||
}
|
||
```
|
||
|
||
支持这两种精确签名：
|
||
|
||
```go
|
||
func SalaryValue(source *amount.Money) amount.Money
|
||
func SalaryValue(source *amount.Money) (amount.Money, error)
|
||
```
|
||
|
||
项目选择一种实现。nil、默认值、金额精度、日期格式和错误码由函数负责；若两边已经是同一个 Money 类型，无需再次解析或序列化。转换函数应仅负责值转换，不执行 SQL 或改变授权范围。
|
||
|
||
错误通过 `%w` 加上映射名/目标字段路径，保留 `errors.Is/As` 和框架错误链；返回零目标值，不交付部分完成的结果。包装不主动添加源值或转换后的值。错误是否公开仍由项目错误目录和响应策略决定。
|
||
|
||
### 嵌套对象、数组与引用
|
||
|
||
`mapping` 指向同配置中的另一条映射，`elements` 明确要求逐项映射：
|
||
|
||
```json
|
||
"fields": {
|
||
"Summary": {"source": "Summary", "mapping": "ToSummary"},
|
||
"Items": {"source": "Items", "mapping": "ToItem", "elements": true}
|
||
}
|
||
```
|
||
|
||
`mapping` 与 `convert` 互斥。`elements` 可以配合其中任意一种，也可以对类型相同的元素直接赋值；支持 slice→slice、等长 array→array，禁止隐式互转。nil slice 保持 nil，非 nil 空 slice 保持非 nil，逐项失败的错误包含索引，循环映射声明被拒绝。
|
||
|
||
未选择 elements 的同类型指针、map、slice 使用普通 Go 赋值，**共享引用**，不做隐式深拷贝。elements 会分配新的目标 slice，但元素内的引用仍遵循其映射规则。需要深拷贝时显式提供转换函数。
|
||
|
||
映射不保存原 JSON 的字段存在信息。普通 `*T` 在绑定后可能已把缺失和 null 合并为 nil；无法在转换阶段恢复区分。有三态需要的项目必须先使用能携带该信息的输入类型及绑定扩展；没有声明三态时，保持当前输入类型的语义。完整表单更新和局部更新由业务决定，框架不把 nil 自动解释成“保留旧值”。
|
||
|
||
### 生成顺序与 CI
|
||
|
||
1. 先从 `.api` 生成项目，添加业务结构、scalar 和转换函数，执行 `go mod tidy`。
|
||
2. 在 `omni.gen.json` 列出映射，执行 `go-omni api generate`。
|
||
3. Logic 调用生成函数。后续改字段后重复生成，不修改 `*Gen.go`。
|
||
4. CI 同时运行 `go-omni api generate --check` 与 `go test ./...`。
|
||
|
||
启用映射后，CLI 通过 `go list -deps -export` 加载明确声明的包与依赖，按当前构建环境做类型检查，不执行业务代码、init 或转换函数。采用待生成 DTO 的临时 overlay，避免“新增字段还看旧 DTO”。go.mod/go.sum 的副本及 overlay 都在临时目录，check 不修改项目文件；Go 自己的构建/模块缓存可能更新。使用当前 GOOS/GOARCH/GOFLAGS、`GOWORK=off`；依赖用 go.mod 与 replace 表达，生成超时为 90 秒。
|
||
|
||
类型包/转换函数包不能依赖输出包 `internal/mapping`；把转换函数放在独立包中，避免导入环。若包本身无法编译，先运行 `go list -deps -export <相关包>` 排查；CLI 不回显可能含私有仓库凭据的 Go 下载输出。纯值字段转换只生成标准 Go 代码，不引入运行时反射搬运、JSON 往返、ORM 或队列依赖。
|
||
|
||
## 中间件工厂自动注册
|
||
|
||
`.api` 沿用 `middleware: RequireAccess` 或 auth 对应的中间件声明。新项目会生成可编辑的 `internal/middleware/requireAccessFactory.go`，只需实现一次：
|
||
|
||
```go
|
||
// internal/middleware/dependencies.go，由项目维护。
|
||
type AccessChecker interface {
|
||
CheckAccess(context.Context, string) error
|
||
}
|
||
type Dependencies interface {
|
||
AccessChecker() AccessChecker
|
||
}
|
||
|
||
// internal/middleware/requireAccessFactory.go，由项目维护。
|
||
func NewRequireAccess(deps Dependencies) (httpx.Middleware, error) {
|
||
checker := deps.AccessChecker()
|
||
if checker == nil { return nil, errors.New("access checker is required") }
|
||
return func(next httpx.Handler) httpx.Handler {
|
||
return func(c *httpx.Context) error {
|
||
if err := checker.CheckAccess(c.Context(), c.Header("Authorization")); err != nil {
|
||
return err
|
||
}
|
||
return next(c)
|
||
}
|
||
}, nil
|
||
}
|
||
|
||
// internal/svc/access.go，由项目维护；ServiceContext.Init 初始化 c.Auth。
|
||
func (c *ServiceContext) AccessChecker() middleware.AccessChecker { return c.Auth }
|
||
```
|
||
|
||
编译器检查 ServiceContext 是否实现依赖接口，middleware 不导入 svc。多个工厂可以共用这些小接口。所需 imports 和具体鉴权服务仍属于项目。
|
||
|
||
启动顺序为：框架基础依赖 → `svc.Init` → 生成的 `middleware.New(c)` 调用各具名工厂 → 创建 App/注册路由 → 监听。中间件实例创建一次，由请求并发复用；不要把单次请求信息存在实例字段里。工厂之间没有初始化顺序依赖；路由执行顺序仍以 `.api` 声明为准。
|
||
|
||
工厂返回错误或 nil 中间件均阻止监听；错误链保留，已登记资源按现有生命周期清理。工厂 panic 也先清理依赖再传播。资源初始化和清理登记放在 svc.Init，工厂借用资源；HTTP 请求排空之前不会关闭这些依赖。
|
||
|
||
factory 模式不再在 Init 写 `Middlewares["..."]`；残留非空手写注册表会明确报错，防止生成注册静默覆盖它。未实现的工厂让启动失败；未实现的 Logic 仍返回 501。
|
||
|
||
### 既有项目迁移
|
||
|
||
1. 首次更新保持 `middleware: handlers`，现有 hook 和手写 Configure 不变。
|
||
2. 改为 factories 并重新生成，会补 `dependencies.go` 和 `*Factory.go`，保留原来的手写文件。
|
||
3. 将旧实现迁入工厂，提供 Dependencies 的访问器；移除 Init 中按名字覆盖 map 的代码。
|
||
4. 旧函数不再需要时由项目删除。若新工厂符号与旧文件中的同名函数冲突，整理旧文件；生成器不覆盖业务代码。
|
||
5. `generate --check` 与 `go test ./...` 检查后再运行。工厂没有全部实现前，服务不会启动。
|
||
|
||
## 文件维护边界
|
||
|
||
| 项目维护 | 生成器持续维护 |
|
||
| --- | --- |
|
||
| `.api` 公共字段与接口 | 展开后的 DTO、Handler、OpenAPI |
|
||
| `omni.gen.json` 的映射与选项 | `internal/mapping/mappingsGen.go` |
|
||
| Go 业务类型、scalar、转换函数 | 编译期可检查的赋值与调用代码 |
|
||
| middleware Dependencies、具名工厂、svc 访问器 | 中间件 registry、启动调用 |
|
||
| Logic、按需 Repository、配置、svc 初始化/清理登记 | main、runtime、路由接入 |
|
||
|
||
回归样例位于 `cmd/go-omni/apigen/testdata/composition`，为独立三端服务，不导入任何 eTax 代码。
|