k2safe/go-omni
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: replace mapping generation with checked copy utilities

Browse Source
This commit is contained in:
k2safe
2026-09-25 17:27:28 +08:00
parent ad9257d202
commit fd83235ce7
45 changed files with 2366 additions and 1872 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
reports/copyxAcceptance.md Normal file
View File

@@ -0,0 +1,70 @@
# v0.19 copyx 与映射移除验收
日期：2026-09-25。环境：Apple M2 Max、darwin/arm64、Go 1.27.1，基准默认 GOMAXPROCS=12。最低支持版本另用 Go 1.22.12 验证 copyx 与可运行示例。
## 范围与行为
本轮新增可选 Go 工具包并删除原映射配置/生成机制，没有修改接入项目代码、数据库或线上服务。没有新增第三方依赖，没有内置工资、金额或权限规则；工资只是生成器的独立通用验收 fixture。
| 场景 | 验证内容 |
| --- | --- |
| 浅/深复制 | 值、结构、指针、数组、map、slice、interface；浅共享与深隔离分别验证 |
| 空值与精度 | nil 与空集合、默认保留 false/0、显式 nil/skip 策略；不兼容类型不能借 nil/零值绕过检查 |
| 可变引用 | 原指针/map、子切片、零长度但有容量的视图、源元素指针、私有子引用、其他字段的引用均拒绝 |
| 自定义函数 | 字段改名、精确类型对、金额私有状态复制、nil interface；重复/冲突配置拒绝 |
| 失败语义 | errors.Is 保留 cause、目标不提交部分结果、嵌入目标指针不提前修改 |
| 对象图 | 指针/map/slice 循环，重复引用；循环指针根压成值结构拒绝 |
| 并发与资源 | 同一 Copier 64 goroutine 各复制 20 次，race；深度/节点/估算分配超限拒绝；锁/资源/函数等明确限制 |
| 真正生成的消费者 | 三端工资公共字段，Money scalar，大数精度/舍入、非法金额、缺失/null/零值、完整表单、错误码与错误链 |
| 维护成本 | 公共字段新增：改一处契约和一处独立业务结构；三个接口共用 helper，不增加拷贝规则 |
| 生成与生命周期 | 重复 generate/check/dry-run 保留业务文件；工厂异常、初始化/监听失败及资源关闭由既有回归验证 |
| 移除与 workspace | 旧配置/旧生成文件阻断且不写入，明确迁移后所有权清理；workspace 失败不部分更新服务 |
FuzzClone 使用动态 JSON 容器、随机 bytes 和嵌套 slice，验证值一致与引用隔离。输入超过 1 KiB 时截取继续验证，运行 30 秒、4 workers：**4,237,917 次执行，未发现失败**。这不等于所有形状都已 fuzz；循环、类型转换及资源拒绝另外用定向用例覆盖。
全量 46 个测试包通过 race 回归（含实际生成项目），vet/build、Go 1.22.12、示例运行与生成漂移检查均通过。
## 可复现命令
```sh
GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -count=1 ./...
go vet ./...
go build ./...
GOTOOLCHAIN=go1.22.12 go test ./copyx ./examples/copying
go test ./copyx -run '^$' -fuzz FuzzClone -fuzztime 30s -parallel 4
go test ./copyx -run '^$' -bench . -benchmem -benchtime 300ms -count 3
go run ./examples/copying
go run ./cmd/go-omni api generate --dir examples/managedService --check
# examples/managedService 中另执行 go test -race ./... 与 go build .
```
全量回归包含真实临时生成项目，集成测试的子进程使用 go test -race / go build，并不只比较生成字符串。基准测量时没有同时运行本轮 fuzz 或全量测试；原始三轮结果见 [copyxBenchmark.txt](copyxBenchmark.txt)。
## 性能与分配
下表取三轮中位数。构造器复用与一次性调用都包含真实复制；`fields1000` 指整数 slice 的长度，不是 1,000 个结构字段。所有深拷贝保留引用检查。
| 场景 | 中位耗时 | B/op | allocs/op |
| --- | ---: | ---: | ---: |
| 相同结构浅拷贝（含引用字段） | 85.8 ns | 96 | 2 |
| 3 字段跨结构改名，复用 Copier | 697.5 ns | 168 | 7 |
| 相同跨结构，每次构建 Copier | 1,181 ns | 1,120 | 17 |
| 嵌套结构 + 1 个整数 + map，深拷贝 | 2,758 ns | 1,368 | 42 |
| 嵌套结构 + 100 个整数 + map，深拷贝 | 2,787 ns | 2,256 | 42 |
| 嵌套结构 + 1,000 个整数 + map，深拷贝 | 3,806 ns | 9,552 | 42 |
| 64 KiB byte slice 深拷贝 | 5,780 ns | 65,768 | 9 |
| 100 项 map，每项含整数 slice | 88,859 ns | 87,704 | 1,554 |
| 自引用循环对象深拷贝 | 2,128 ns | 640 | 26 |
| converter 新建 slice 并通过检查 | 539.7 ns | 280 | 10 |
| converter 返回原 slice 被拒绝 | 383.8 ns | 320 | 11 |
并行循环对象基准中位 515.2 ns/op 是多核聚合吞吐均摊，**不是单请求延迟**。复杂 map 的多次图扫描、字段路径和反射分配明显更贵；不据此宣称运行时工具快于手写赋值。热点复用 Copier；大对象和高频映射应按实际业务结构衡量是否改用直接 Go。
优化只包括不可变类型元数据缓存、纯值快速路径、纯值 slice 批量复制；没有去掉深拷贝别名检查。内置估算分配上限 64 MiB 不是硬堆内存隔离，converter 的外部分配及副作用不受该预算控制。
## 边界
- 新方式在运行时做类型与覆盖检查，不再有旧映射生成时的静态保证；字段变更要运行实际类型对测试。
- converter 是受信项目代码，必须只读输入；不能自动回滚其副作用、证明其未共享外部全局对象，或强杀无限循环。
- 当前记录是本机库/生成器验收，不是线上服务吞吐、Linux soak、真实业务数据库回归或 OSS/R2 云账号验收。本轮没有对线上服务器施压。
- 旧消费者仍需按 [COPY.md](../COPY.md#从旧-mapping-迁移) 迁移，不会被这次框架发布自动修改。

48
reports/copyxBenchmark.txt Normal file
View File

@@ -0,0 +1,48 @@
goos: darwin
goarch: arm64
pkg: git.yuntuo.hk/k2safe/go-omni/copyx
cpu: Apple M2 Max
BenchmarkScenarios/struct/reusefalse-12 251924 1209 ns/op 1120 B/op 17 allocs/op
BenchmarkScenarios/struct/reusefalse-12 316450 1181 ns/op 1120 B/op 17 allocs/op
BenchmarkScenarios/struct/reusefalse-12 314466 1140 ns/op 1120 B/op 17 allocs/op
BenchmarkScenarios/struct/reusetrue-12 517544 703.0 ns/op 168 B/op 7 allocs/op
BenchmarkScenarios/struct/reusetrue-12 517842 691.9 ns/op 168 B/op 7 allocs/op
BenchmarkScenarios/struct/reusetrue-12 522170 697.5 ns/op 168 B/op 7 allocs/op
BenchmarkScenarios/bytes64KiB-12 67933 5857 ns/op 11189.69 MB/s 65768 B/op 9 allocs/op
BenchmarkScenarios/bytes64KiB-12 61680 5780 ns/op 11337.56 MB/s 65768 B/op 9 allocs/op
BenchmarkScenarios/bytes64KiB-12 61843 5771 ns/op 11355.66 MB/s 65768 B/op 9 allocs/op
BenchmarkScenarios/map100-12 3808 88598 ns/op 87704 B/op 1554 allocs/op
BenchmarkScenarios/map100-12 4136 88859 ns/op 87704 B/op 1554 allocs/op
BenchmarkScenarios/map100-12 4051 89614 ns/op 87704 B/op 1554 allocs/op
BenchmarkScenarios/cycle-12 168308 2128 ns/op 640 B/op 26 allocs/op
BenchmarkScenarios/cycle-12 169057 2163 ns/op 640 B/op 26 allocs/op
BenchmarkScenarios/cycle-12 169892 2120 ns/op 640 B/op 26 allocs/op
BenchmarkScenarios/parallelCycle-12 963274 660.6 ns/op 640 B/op 26 allocs/op
BenchmarkScenarios/parallelCycle-12 582906 515.1 ns/op 640 B/op 26 allocs/op
BenchmarkScenarios/parallelCycle-12 748388 515.2 ns/op 640 B/op 26 allocs/op
BenchmarkScenarios/converter/freshfalse-12 828752 382.8 ns/op 320 B/op 11 allocs/op
BenchmarkScenarios/converter/freshfalse-12 897363 383.8 ns/op 320 B/op 11 allocs/op
BenchmarkScenarios/converter/freshfalse-12 1000000 387.5 ns/op 320 B/op 11 allocs/op
BenchmarkScenarios/converter/freshtrue-12 665454 541.2 ns/op 280 B/op 10 allocs/op
BenchmarkScenarios/converter/freshtrue-12 647089 535.0 ns/op 280 B/op 10 allocs/op
BenchmarkScenarios/converter/freshtrue-12 704719 539.7 ns/op 280 B/op 10 allocs/op
BenchmarkCopy/fields1/deepfalse-12 4058166 87.96 ns/op 96 B/op 2 allocs/op
BenchmarkCopy/fields1/deepfalse-12 4137807 85.79 ns/op 96 B/op 2 allocs/op
BenchmarkCopy/fields1/deepfalse-12 4201804 85.07 ns/op 96 B/op 2 allocs/op
BenchmarkCopy/fields1/deeptrue-12 131413 2739 ns/op 1368 B/op 42 allocs/op
BenchmarkCopy/fields1/deeptrue-12 131658 2771 ns/op 1368 B/op 42 allocs/op
BenchmarkCopy/fields1/deeptrue-12 131880 2758 ns/op 1368 B/op 42 allocs/op
BenchmarkCopy/fields100/deepfalse-12 4209133 85.61 ns/op 96 B/op 2 allocs/op
BenchmarkCopy/fields100/deepfalse-12 4239586 84.30 ns/op 96 B/op 2 allocs/op
BenchmarkCopy/fields100/deepfalse-12 4248972 84.59 ns/op 96 B/op 2 allocs/op
BenchmarkCopy/fields100/deeptrue-12 127617 2787 ns/op 2256 B/op 42 allocs/op
BenchmarkCopy/fields100/deeptrue-12 129816 2826 ns/op 2256 B/op 42 allocs/op
BenchmarkCopy/fields100/deeptrue-12 124041 2780 ns/op 2256 B/op 42 allocs/op
BenchmarkCopy/fields1000/deepfalse-12 4214600 85.59 ns/op 96 B/op 2 allocs/op
BenchmarkCopy/fields1000/deepfalse-12 4250719 85.20 ns/op 96 B/op 2 allocs/op
BenchmarkCopy/fields1000/deepfalse-12 4247498 85.05 ns/op 96 B/op 2 allocs/op
BenchmarkCopy/fields1000/deeptrue-12 92329 3818 ns/op 9552 B/op 42 allocs/op
BenchmarkCopy/fields1000/deeptrue-12 93945 3806 ns/op 9552 B/op 42 allocs/op
BenchmarkCopy/fields1000/deeptrue-12 96010 3782 ns/op 9552 B/op 42 allocs/op
PASS
ok git.yuntuo.hk/k2safe/go-omni/copyx 17.513s

15
reports/copyxFuzz.txt Normal file
View File

@@ -0,0 +1,15 @@
fuzz: elapsed: 0s, gathering baseline coverage: 0/10 completed
fuzz: elapsed: 0s, gathering baseline coverage: 10/10 completed, now fuzzing with 4 workers
fuzz: elapsed: 3s, execs: 426851 (142240/sec), new interesting: 5 (total: 15)
fuzz: elapsed: 6s, execs: 837791 (137019/sec), new interesting: 5 (total: 15)
fuzz: elapsed: 9s, execs: 1281087 (147767/sec), new interesting: 5 (total: 15)
fuzz: elapsed: 12s, execs: 1705531 (141463/sec), new interesting: 5 (total: 15)
fuzz: elapsed: 15s, execs: 2125995 (140169/sec), new interesting: 6 (total: 16)
fuzz: elapsed: 18s, execs: 2547285 (140432/sec), new interesting: 6 (total: 16)
fuzz: elapsed: 21s, execs: 2954940 (135854/sec), new interesting: 6 (total: 16)
fuzz: elapsed: 24s, execs: 3389762 (144941/sec), new interesting: 6 (total: 16)
fuzz: elapsed: 27s, execs: 3808273 (139491/sec), new interesting: 6 (total: 16)
fuzz: elapsed: 30s, execs: 4237917 (143257/sec), new interesting: 6 (total: 16)
fuzz: elapsed: 30s, execs: 4237917 (0/sec), new interesting: 6 (total: 16)
PASS
ok git.yuntuo.hk/k2safe/go-omni/copyx 30.363s

59
reports/copyxRegression.txt Normal file
View File

@@ -0,0 +1,59 @@
ok git.yuntuo.hk/k2safe/go-omni 1.519s
ok git.yuntuo.hk/k2safe/go-omni/app 3.503s
ok git.yuntuo.hk/k2safe/go-omni/audit 1.970s
ok git.yuntuo.hk/k2safe/go-omni/auth 2.265s
ok git.yuntuo.hk/k2safe/go-omni/cache 2.566s
ok git.yuntuo.hk/k2safe/go-omni/cache/redis 2.712s
ok git.yuntuo.hk/k2safe/go-omni/cmd/go-omni 5.321s
ok git.yuntuo.hk/k2safe/go-omni/cmd/go-omni/apigen 76.921s
ok git.yuntuo.hk/k2safe/go-omni/cmd/go-omni/scaffold 47.757s
ok git.yuntuo.hk/k2safe/go-omni/config 4.374s
ok git.yuntuo.hk/k2safe/go-omni/contract 4.702s
ok git.yuntuo.hk/k2safe/go-omni/copyx 5.171s
ok git.yuntuo.hk/k2safe/go-omni/database 4.141s
ok git.yuntuo.hk/k2safe/go-omni/database/gormx 3.916s
ok git.yuntuo.hk/k2safe/go-omni/database/migrate 3.856s
ok git.yuntuo.hk/k2safe/go-omni/database/mysql 3.816s
ok git.yuntuo.hk/k2safe/go-omni/errors 3.930s
? git.yuntuo.hk/k2safe/go-omni/examples/basic [no test files]
? git.yuntuo.hk/k2safe/go-omni/examples/compatibility [no test files]
? git.yuntuo.hk/k2safe/go-omni/examples/compatibility/ids [no test files]
ok git.yuntuo.hk/k2safe/go-omni/examples/copying 3.198s
ok git.yuntuo.hk/k2safe/go-omni/examples/modules 2.930s
ok git.yuntuo.hk/k2safe/go-omni/examples/platform 2.766s
ok git.yuntuo.hk/k2safe/go-omni/examples/reference 2.794s
? git.yuntuo.hk/k2safe/go-omni/examples/reference/handler [no test files]
? git.yuntuo.hk/k2safe/go-omni/examples/reference/model [no test files]
ok git.yuntuo.hk/k2safe/go-omni/examples/reference/repository 2.880s
? git.yuntuo.hk/k2safe/go-omni/examples/reference/service [no test files]
ok git.yuntuo.hk/k2safe/go-omni/health 3.091s
ok git.yuntuo.hk/k2safe/go-omni/httpc 3.345s
ok git.yuntuo.hk/k2safe/go-omni/httpx 3.870s
ok git.yuntuo.hk/k2safe/go-omni/internal/perfcheck 3.284s
? git.yuntuo.hk/k2safe/go-omni/internal/storagefixture [no test files]
? git.yuntuo.hk/k2safe/go-omni/internal/testutil [no test files]
ok git.yuntuo.hk/k2safe/go-omni/lifecycle 3.390s
ok git.yuntuo.hk/k2safe/go-omni/logx 3.459s
ok git.yuntuo.hk/k2safe/go-omni/metrics 2.732s
ok git.yuntuo.hk/k2safe/go-omni/middleware 2.718s
ok git.yuntuo.hk/k2safe/go-omni/middleware/redis 3.086s
ok git.yuntuo.hk/k2safe/go-omni/openapi 3.319s
ok git.yuntuo.hk/k2safe/go-omni/pagination 3.356s
? git.yuntuo.hk/k2safe/go-omni/queue [no test files]
ok git.yuntuo.hk/k2safe/go-omni/queue/redis 3.060s
ok git.yuntuo.hk/k2safe/go-omni/resilience 2.898s
ok git.yuntuo.hk/k2safe/go-omni/response 3.157s
ok git.yuntuo.hk/k2safe/go-omni/storage 3.414s
ok git.yuntuo.hk/k2safe/go-omni/storage/local 3.617s
ok git.yuntuo.hk/k2safe/go-omni/storage/oss 3.572s
ok git.yuntuo.hk/k2safe/go-omni/storage/s3 3.752s
? git.yuntuo.hk/k2safe/go-omni/storage/storagetest [no test files]
ok git.yuntuo.hk/k2safe/go-omni/task 3.094s
ok git.yuntuo.hk/k2safe/go-omni/telemetry 3.089s
ok git.yuntuo.hk/k2safe/go-omni/transport 3.311s
ok git.yuntuo.hk/k2safe/go-omni/transport/http2 14.938s
? git.yuntuo.hk/k2safe/go-omni/transport/internal/routing [no test files]
ok git.yuntuo.hk/k2safe/go-omni/transport/native 4.422s
ok git.yuntuo.hk/k2safe/go-omni/transport/nethttp 3.401s
? git.yuntuo.hk/k2safe/go-omni/transport/transporttest [no test files]
? git.yuntuo.hk/k2safe/go-omni/validate [no test files]