Files
go-omni/reports/nullableMappingAcceptance.md

3.7 KiB
Raw Permalink Blame History

可空映射与配置拆分验收(v0.18.0-preview)

基于 v0.17.0-preview 补齐通用生成能力,未添加业务模型、权限、金额默认值或领域校验。运行时和依赖不变,旧单文件配置与已有映射函数保留。

本轮完成

  • 显式嵌套 mapping 支持 S → T、*S → *T、S → *T、显式 nil 策略下的 *S → T,也适用于 elements 下的 slice/等长数组。默认保留可空对象;非空目标必须明确选 zero/error。
  • 同类型 *T → T 可显式选择 nil zero/error,省去重复解引用 converter。自定义 converter 继续独立控制行为,禁止同时配置 nil 策略。
  • pointerResult: true 额外生成 <Name>Ptr(S) (*T,error),原值函数不变。转换失败返回 nil 与原错误链;辅助函数名统一查重。
  • 主配置以 mappingFiles 列出项目内子文件。子文件只含 mappings,统一解析跨文件引用、严格类型和字段覆盖;不做递归导入或隐式覆盖。
  • 配置均为项目文件,生成不会改写。check、dry-run、workspace generate/check 共享加载过程;对子文件变化重新核对,保留边界与大小限制。

回归证据

回归记录:全仓库 44 个有测试的包通过 -race,包含实际生成消费者;go vet、go build、diff 检查通过。

TestNullableMappingConsumer 生成独立项目,配置跨文件向前引用与项目自定义转换函数,验证:

  • nil、缺失、非 nil 零值对象、nil/非 nil 空 slice、nil 元素,以及 slice/array 内的嵌套转换。
  • zero/error 空值策略、值到指针、可选指针返回;未显式映射的同类型指针仍共享引用。
  • 子转换失败时父结果归零,指针辅助返回 nil,errors.Is 保留原因,错误含子字段与数组索引;内部原因和映射路径不进入公开 HTTP 提示。
  • 32 个并发调用;通过实际生成 Handler 和 Logic 测试 JSON 请求与响应;生成模块执行 race 测试和根目录 build。
  • 主配置与子文件、业务 Logic 在重新生成后逐字保留;check/preview 只读。子文件修改触发漂移,workspace generate 后 workspace check 通过。
  • 未声明 nil 行为、错误类型/策略、辅助函数重名、未知映射、跨文件循环和字段遗漏均在写入前拒绝。

TestMappingFileConfiguration/Rejection/Bounds 覆盖文件加载顺序、来源诊断、配置变化摘要、重复文件/定义/JSON key、路径越界、符号链接、嵌套导入拒绝,以及单文件/总大小/文件数/合并映射数限制。

原始最小复现:在隔离副本中,用源码构建的真实 CLI 成功生成原来报 nested mapping Child has incompatible types 的项目;生成检查、模块编译测试和 build 通过。原项目文件快照一致,临时目录已清理。

实际进程回归:原有根目录启动、nethttp/native 信号退出、监听端口释放、上传下载、原始回调、错误响应与生成文件保护通过。

使用与边界

使用及迁移见 生成能力指南。子文件仅拆分配置,不生成需要人工补齐的赋值代码;普通映射仍为编译器检查的 Go 代码,无运行时反射或 JSON 往返。

zero 表示目标 Go 零值,并跳过子映射;领域必填、金额精度、时间/编号格式和快照深拷贝仍由项目负责。普通指针输入已合并的 missing/null 不能在映射阶段恢复。nil error 是普通转换错误,特定业务错误码用自定义 converter 表达。

当前已完成发布前验收;远程验收将在固定标签发布后补充。框架验收不代表完整业务项目已迁移,本轮没有修改 eTax 业务代码。