go-omni/DEVELOPMENT.md

通用业务开发指南（v0.24.0-preview）

从 README 创建服务后，业务主要维护 .api、配置、svc.Init、Logic、Repository 和项目中间件。本页说明通用接入能力；字段、错误码、权限、表结构和事务边界都由项目定义。

公共字段组合、自动中间件工厂和 Repository 开关，见 生成能力指南。必要的结构转换使用可选 copyx，v0.19 已移除旧 JSON 映射生成。

返回数组、可空对象和 null

@handler list
get /items returns ([]Item)

@handler find
get /item returns (*Item)

@handler save
post /item returns (null)

@handler remove
delete /item

契约	Logic 返回	成功数据
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。

基础类型数组还支持 int/int8/int16/int32、uint/uint16/uint32/uint64、float32/float64。nil 根数组都输出 []；[]any 在 OpenAPI 中是 type: array, items: {}，不限制元素形状，但元素必须可被标准 JSON 编码器序列化。[]uint8（Go 的 byte slice）会编码为 base64，故明确拒绝；数字数组可用 []int32，二进制用下载接口。当前不支持根嵌套数组或根自定义 scalar 数组。

契约驱动的请求策略

入口文件可以声明默认策略，单个接口按需覆盖：

@app (
    defaultResponse: CommonResponse
    request: {"unknownQuery":"reject", "utf8":"reject", "charset":"utf8"}
)

@handler create
@request (body: required)
post /items (CreateReq) returns (Item)

@handler touch
@request (body: emptyObject)
post /touch returns (null)

• unknownQuery: reject|ignore：是否拒绝未声明的 URL 查询字段；重复标量仍拒绝，数组用重复的同名 query。
• utf8: reject|replace：拒绝原始非法 UTF-8，或采用 JSON 的替换字符行为。不是只检查解码后的字符串。
• charset: utf8|any：utf8 仅接受未声明 charset 或 utf-8；不会对其他编码做转码。
• body: auto|required|optional|none|emptyObject：auto 按 JSON 字段推断；required 要求一个对象；optional 允许完全没有 body，但提供 body 后仍完整校验；none 禁止任何 body 字节；emptyObject 必须是 {}。

未设置的项继承 App 的 config.Config.Request，最后采用既有默认行为。.api 的 @app 显式字段优先于项目配置；路由 @request 优先于 App。raw/multipart 使用各自解析流程，不能套 JSON body 策略。普通 JSON 只解析一次；重复/未知 JSON 字段、约束、scalar 和 any 仍使用同一编译器。自定义 binder/manual Handler 的输入逻辑由项目显式负责。

没有 body 与提供 {} 不等价。optional 无 body 时 JSON 字段保留零值；需要业务区分是否出现某字段时使用 optional 指针字段。raw/multipart 不继承 App 的 JSON body 策略；GET/HEAD 如遇 App 的 required/optional/emptyObject 默认值，须明确覆盖为 auto 或 none。参数校验不会替代企业权限、记账规则或数据库约束。

声明式 multipart

type UploadReq {
    Title string `multipart:"title" binding:"required,max=80"`
    Metadata AttachmentMeta `multipartJSON:"metadata,maxBytes=16384"`
    Attachment File `file:"attachment,maxBytes=10485760"`
    Extras []File `file:"extras,optional,maxFiles=3,maxBytes=1048576"`
}
type AttachmentMeta {
    Category string `json:"category"`
}

@handler upload
@body (mode: multipart; maxBytes: 16777216; maxParts: 8; maxFieldBytes: 65536)
post /attachments (UploadReq) returns (AttachmentResp)

Logic 直接得到 *types.UploadReq，无需维护 Handler。form 仍表示 URL query；multipart 表示文本表单字段，可用基础类型、文本 scalar 和重复 scalar 数组；multipartJSON 是一个严格解码的 JSON 表单字段，可包含对象、数组和已声明的 scalar。

File 提供 Name、ContentType、Size、Present() 和 Open() (io.ReadCloser, error)。文件名和媒体类型属于客户端元数据，项目继续决定内容检测、存储权限和目标对象名。不要把客户端文件名直接用作存储路径。

reader, err := req.Attachment.Open()
if err != nil { return nil, err }
defer reader.Close()
// 将 reader 传给项目选定的流式存储接口；不要先 io.ReadAll 整个大文件。

所有声明字段、重复/未知字段、文件数量和各级限额都会在进入 Logic 前校验。缺少必填项、重复标量/JSON 字段、文件与文本类型混用、畸形 JSON 均失败。JSON 的类型、未知字段和重复 key 检查与普通 JSON 一致。

默认总量 1 MiB、最多 128 个 part、单文本/JSON 字段 64 KiB；单文件默认受总量约束，文件数组默认最多 16 个。@body 可设置 maxBytes/maxParts/maxFieldBytes/maxFileBytes；字段上的 maxBytes/maxFiles 再收紧对应限额。总量包括 MIME 头和结尾数据；传输编码的 part 被拒绝，避免字节含义不明确。

文件使用有界复制写入权限为 0600 的临时文件，文本/JSON 字段在各自限额内缓冲。生成 Handler 返回或 panic 时关闭打开的文件 reader 并删除临时文件；不能把请求的 File 留到异步任务使用。失败不会交付半个 DTO，也不会进入 Logic。临时磁盘容量、并发请求上限与 HTTP 超时由部署配置共同约束。

不声明 multipart 字段时，保留原来的 body *httpx.Body 流式入口，不创建临时文件。该方式适合特殊协议；项目应在不可撤销副作用之前完成校验并调用 body.Complete()。下载和原始回调继续使用 @produces / @body(mode: raw)。

文件声明配置来源

项目维护 Config、Default()、Validate() 和配置文件；生成器维护 Load/main。流程为默认值→选定文件→显式 ${NAME} / ${NAME:-fallback} 引用→类型绑定→校验。没有前缀、别名或 env/envDefault 隐式覆盖。

固定值保持固定，缺失字段保留 Default()，0/false/空字符串正常覆盖；引用失败不回退初始化默认值。$$ 转义 $，字符串凭据保留空格与特殊字符。

go run . -config etc/config.test.yaml -check-config 只校验，不打开日志、数据库或端口。生成/check/dry-run 保留业务文件；新的模板要求 v0.22。完整格式、错误定位、解析器与移除清单见 CONFIG.md。

依赖、日志与中间件

internal/svc/runtimeGen.go 持续由生成器维护。项目的 ServiceContext 嵌入 *lifecycle.Runtime，只在 Init(ctx) 中装配额外依赖：

func (c *ServiceContext) Init(ctx context.Context) error {
    client, err := NewClient(c.Config.Client)
    if err != nil { return err }
    c.Client = client
    c.OnClose(client.Close)
    return nil
}

每个资源初始化成功就登记清理；后续初始化失败自动逆序回滚。正常退出先排空 HTTP 请求，再执行后台组件的 Stop/Drain 阶段，确认收尾后逆序关闭依赖，最后关闭日志。关闭幂等，单个清理函数 panic/返回错误不会跳过其他清理；初始化 panic 清理后继续传播。后台组件按 分阶段关闭 登记；无法确认收尾完成时保留共享依赖并异常退出，不能把取消等同于任务已经结束。

新项目使用中间件工厂：项目维护 middleware.Dependencies 小接口与 New<Name>(deps) (httpx.Middleware, error)，svc 提供对应访问器。生成的 runtime 在 Init 成功后自动调用工厂并注册，不再按名字替换 map；工厂失败会释放已经登记的依赖。示例与现有项目迁移步骤见 中间件工厂。

v0.16 项目及 omni.gen.json 中选择 middleware: handlers 的项目继续使用原有 Defaults()，可以在 Init 设置 c.Middlewares["RequireAccess"]。更新时不会重写这部分业务代码；只有显式切换到 factories 后才使用新流程。

生成入口为每个 App 注入独立 Logger，不修改进程默认 Logger。业务可用 c.Logger.InfoContext(...)，或请求链中的 logx.InfoContext(ctx,...)。标准库/第三方需要 *log.Logger 时使用 c.Logger.Standard(slog.LevelWarn)；适配器借用原 Logger，不负责关闭。手写多 App 用 omni.WithLogInstance(logger) 显式注入。

httpx.Metadata(ctx) 在业务的标准 context 中提供可信代理规则解析后的 ClientIP、HTTP Method 和路由模板；不放入凭据、完整 URL、查询或 body。业务 userId/tenantId 等仍由项目选择，框架不预设身份模型。

middleware.ContextErrors("REQUEST_CANCELED", "REQUEST_TIMEOUT") 可将原始取消/超时错误映射到项目错误目录；显式 APIError 优先，内部 cause 链保留。状态、业务码与提示仍在项目 Catalog 配置。

字段文档、格式化、Go 错误目录导出

type Item {
    // 企业名称
    Name string `json:"name" example:"示例企业"`
    State int `json:"state,options=0|1" example:"1" enumDescriptions:"[\"禁用\",\"启用\"]"` // 状态
}

字段前/同行注释同步到 Go 注释和 OpenAPI description。显式 description 标签优先；example 的基础字段值也检查类型和约束，枚举说明按声明值顺序填写。字符串 example 直接写内容，其他类型写 JSON。自定义 scalar 的示例不能替代其项目解码器验证；输入输出类型不同时，不把输入示例冒充输出示例。

go-omni api format --api api/service.api
go-omni api format --api api/service.api --check
go-omni api generate
go-omni api generate --check

格式化保留注释、token 和多行字面量，规范四空格缩进、空行、行首尾空白及相邻单行字段的类型/标签/行尾注释对齐；结果幂等。先校验完整契约，check 不写文件；导入的共享目录不被某个服务的格式化命令修改。DTO 按源 .api 输出 dto<Source><摘要>Gen.go，都属于 types 包，跨文件引用无需改包名。

Go Catalog 是错误的唯一来源时，优先使用 workspace 的显式导出配置，不再维护导出/复制脚本。AppOptions 仍通过 omni.WithErrors(apierrors.Catalog()) 注册同一个 Go 函数，运行期只注册一次。单个项目也可继续使用 errors.ExportCatalog 导出入口目录的 api/omni.errors.json；此文件和下面的共享 source 二选一。

OpenAPI 自动把有收益的重复响应、schema 和示例移到 components.responses/schemas/examples，通过标准 $ref 引用。HTTP 200 同时含成功和业务失败时保留两种 schema、业务码、模板参数示例和 data:null；业务响应内容不会改变。消费 OpenAPI 的工具需要支持标准本地引用。

两个服务共享契约

workspace/
├── contracts/common/response.api
├── services/api/api/service.api
├── services/api/api/omni.imports.json
├── services/id/api/service.api
├── services/id/api/omni.imports.json
└── omni.workspace.json

两个服务的 omni.imports.json 可以分别声明：

{"roots":{"common":{"path":"../../../contracts/common","version":"1.0.0"}}}

import "@common/response.api"

只读取入口目录和显式声明的根。保留真实路径检查、symlink 越界拒绝、循环检测、32 层、64 文件、单文件 1 MiB/总量 8 MiB 限额；最多 16 个共享根。不会下载依赖或复制共享定义进服务。移动目录时显式更新 roots。

version 是项目管理的版本标签。生成文档记录每个文件 SHA-256，以及每个共享根所导入文件集合的摘要；可把文档中的 x-omni-contract-sources.shared.common.sha256 填入 root 的 sha256，固定输入集合，内容变化后必须显式更新。摘要算法是对“该根内相对路径→文件 SHA-256”的键排序 JSON 对象再做 SHA-256，未导入的文件不参与。

工作区清单：

{"services":[{"dir":"services/api"},{"dir":"services/id"}]}

go-omni workspace format --file omni.workspace.json
go-omni workspace generate --file omni.workspace.json
go-omni workspace check --file omni.workspace.json

各服务保持独立 module；可显式填写各服务的 api（相对服务目录）和 module。所有服务预检通过后再写；每个服务独立提交文件事务，不承诺跨项目的崩溃原子性。check 汇总格式与生成漂移；业务编译/测试仍在各 module 执行。

同一份 Go 错误目录供多个服务生成

在 workspace 清单显式声明提供目录的 Go 包和函数：

{
  "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：

{
  "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 的文档由项目显式扩展。

# 首次生成导出一次共享目录，所有服务预检通过才写入
# 共享 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.22.0-preview（或显式引用当前源码）。

go-omni api upgrade --dir . --dry-run
go-omni api upgrade --dir . --preview .goOmni/upgradePreview
# 只有标为 safe 的原始模板才会自动替换；review 阻止全部写入。
go-omni api upgrade --dir . --apply
go mod tidy
go-omni api generate --check
go test ./...
go build .

自动迁移只替换与 v0.13 原始模板一致的配置/svc 基础文件、移除原始 close.go，并更新最低依赖及生成产物；保留 Logic、Repository、AppOptions、独立命令。迁移失败回滚已改的项目文件。存在业务修改时，仅输出这些基础文件的候选版本和清单，不生成整棵业务代码让人重新拼接。

定制项目按预览定点迁移：保留依赖字段，把初始化移到 Init，嵌入 Runtime，清理改为 OnClose 登记；移除旧 New/Close/OnClose；合并业务配置和结构化 MySQL 配置，更新 go.mod，再正常 generate。生成器会拒绝遗留构造/关闭实现，避免重复函数或悄悄绕过清理。v0.12 及更早的定制结构不能被精确自动合并，使用同一预览逐项迁移并编译验证。