feat: add precise diagnostics and optional client copy logging controls
This commit is contained in:
60
reports/developerToolsAcceptance.md
Normal file
60
reports/developerToolsAcceptance.md
Normal file
@@ -0,0 +1,60 @@
|
||||
# v0.23 接入工具验收（2026-09-26）
|
||||
|
||||
本轮补齐通用配置诊断、JSON 成功状态限制、copyx 类型预检和实例日志时区；没有引入业务类型、映射配置或全局时区修改。
|
||||
|
||||
## 回归
|
||||
|
||||
- `GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race ./...`：48 个有测试的包通过，包含实际生成消费者、失败清理、后台收尾、错误目录和上传下载。
|
||||
- 最后调整 copyx 空集合检查和分配后，copyx/config/logx/httpc 的 race 复测通过。
|
||||
- Go 1.22.12 的 config/copyx/logx/httpc/database 测试通过；最后调整后前四个包复测通过。
|
||||
- `go vet ./...`、`go build ./...` 通过。
|
||||
- managedService 生成检查、race 和根目录构建通过；userService 的 race 通过。外部数据库测试没有提供连接配置时按原规则跳过。
|
||||
- developerTools 示例的默认配置、UTC、非法数据库端口、非法日志等级验证通过。错误非零退出，具体字段/原因可见，非法输入值未输出。
|
||||
- `FuzzClone` 最终运行 30 秒、4 worker，执行 3,925,833 次，通过（总时间 30.391 秒）。另有确定性的类型、nil、资源句柄和深拷贝隔离测试；fuzz 执行次数不代表形式化证明。
|
||||
|
||||
| 能力 | 验收场景 |
|
||||
| --- | --- |
|
||||
| 字段诊断 | database.port/pool/tls、server.log.level/rotation/timeZone、HTTP 连接配置、后台关闭超时、请求策略定位具体字段；文件/环境名/行列保留；errors.Is/As 保留原因链；未知业务校验仍安全脱敏 |
|
||||
| JSON 成功状态 | 默认全部 2xx；指定 200；200..299 范围与空列表校验；选项快照/并发隔离；拒绝状态不改输出、不额外重试；响应体关闭；小响应复用连接；无限慢响应有界回收；成功响应大小限制保留 |
|
||||
| copyx 预检 | 无样本检查结构、数组/map、指针、递归类型、重命名/忽略/严格字段覆盖；converter 不执行；并发 Copier 选项隔离；空集合也拒绝确定类型错误；失败不修改目标 |
|
||||
| copyx 值语义 | nil 与空集合保持区别；允许原有合法的 nil 函数/空函数集合；实际非 nil 句柄仍拒绝；动态 interface 提示需要实际值或显式 converter；深拷贝 converter 返回原引用仍报错 |
|
||||
| 日志时区 | JSON/text/子日志/标准库日志；上海和 UTC 实例隔离；纽约夏令时；默认保留原时间；业务 time.Time 属性不改；脱敏保留；非法时区不创建文件；200 条并发日志 race 通过 |
|
||||
| 生成消费者 | 生成 Load 直接定位 server.log.level 和环境变量，校验先于依赖初始化；timeZone 直接绑定；重复生成/check 和业务文件保留通过 |
|
||||
|
||||
## 性能
|
||||
|
||||
Go 1.27.1、darwin/arm64、Apple M2 Max。无 race，每场景三轮、benchtime=200ms，表中取中位数。[基线原始结果](developerToolsBaseline.txt)、[当前原始结果](developerToolsBenchmark.txt)。
|
||||
|
||||
| 场景 | 修改前 | 修改后 | 修改后分配 |
|
||||
| --- | ---: | ---: | ---: |
|
||||
| 结构转换，每次创建 Copier | 1221 ns | 1261 ns | 1120 B / 17 allocs（不变） |
|
||||
| 结构转换，复用 Copier | 733.4 ns | 719.1 ns | 168 B / 7 allocs（不变） |
|
||||
| 64 KiB 字节深拷贝 | 6067 ns | 5613 ns | 65768 B / 9 allocs（不变） |
|
||||
| HTTP 128 B JSON 解码 | 1374 ns | 1369 ns | 约 2348 B / 22 allocs |
|
||||
| HTTP 4 KiB JSON 解码 | 7020 ns | 7130 ns | 约 17085 B / 31 allocs |
|
||||
| HTTP 64 KiB JSON 解码 | 80622 ns | 80571 ns | 约 213924 B / 38 allocs |
|
||||
| HTTP Do | 664.2 ns | 664.5 ns | 1296 B / 17 allocs（不变） |
|
||||
|
||||
新增功能的独立基准：
|
||||
|
||||
- 复用 Copier，预检含嵌套切片和显式 converter 的类型：597.8 ns、32 B、3 次分配。每次显式 Check 检查类型，不在每个正常业务 Copy 前重复完整预检。
|
||||
- 同一简单 JSON 调用默认策略 1224 ns / 2345 B / 22 次分配，传成功状态选项 1249 ns / 2393 B / 23 次分配；此用例每次创建选项，应用也可复用选项。
|
||||
- 同一日志输出到 io.Discard：默认 851.5 ns、UTC 885.0 ns、上海 888.7 ns；均为 112 B / 3 次分配。时区解析只发生在初始化/校验阶段。
|
||||
|
||||
这些是本机微基准，HTTP 使用模拟 Transport，日志使用 io.Discard，不代表实际网络或磁盘吞吐量；三轮测量有波动（64 KiB JSON 有一次较慢样本），不承诺固定性能比例。中途发现的普通拷贝额外分配已在最终测量前消除。
|
||||
|
||||
复现命令：
|
||||
|
||||
```sh
|
||||
go test ./copyx ./httpc ./logx -run '^$' -bench 'BenchmarkScenarios/(struct|bytes64KiB)|BenchmarkHTTPClient|BenchmarkTypeCheck|BenchmarkJSONSuccessStatus|BenchmarkLoggerTimeZone' -benchmem -benchtime=200ms -count=3
|
||||
go test ./copyx -run '^$' -fuzz '^FuzzClone$' -fuzztime=30s -parallel=4
|
||||
go run ./examples/developerTools
|
||||
```
|
||||
|
||||
## 使用边界
|
||||
|
||||
- 错误文本变得更具体，识别诊断应使用错误类型/字段。自定义业务校验继续通过 config.Invalid/AtField 声明安全原因。
|
||||
- 空集合中的确定类型错误现在会提前返回；需要调整实际类型或显式 converter。Check 不验证具体值、converter 成功性、nil 输入或深拷贝引用隔离，这些仍由实际 Copy 执行。
|
||||
- 成功状态选项只接受 2xx 子集，不改变 HTTP 重试策略；业务响应内容是否完整仍由项目协议校验。
|
||||
- 时区数据由运行环境提供；极简镜像可用 `go build -tags timetzdata .` 内置。logx 不强制引入约 450 KB 的时区数据库。
|
||||
- 本轮未修改接入项目业务代码，未连接业务数据库或使用远程服务器压测。仍需项目升级后的业务验收。
|
||||
42
reports/developerToolsBaseline.txt
Normal file
42
reports/developerToolsBaseline.txt
Normal file
@@ -0,0 +1,42 @@
|
||||
goos: darwin
|
||||
goarch: arm64
|
||||
pkg: git.yuntuo.hk/k2safe/go-omni/copyx
|
||||
cpu: Apple M2 Max
|
||||
BenchmarkScenarios/struct/reusefalse-12 195284 1218 ns/op 1120 B/op 17 allocs/op
|
||||
BenchmarkScenarios/struct/reusefalse-12 194980 1227 ns/op 1120 B/op 17 allocs/op
|
||||
BenchmarkScenarios/struct/reusefalse-12 186867 1221 ns/op 1120 B/op 17 allocs/op
|
||||
BenchmarkScenarios/struct/reusetrue-12 340254 780.4 ns/op 168 B/op 7 allocs/op
|
||||
BenchmarkScenarios/struct/reusetrue-12 339192 733.4 ns/op 168 B/op 7 allocs/op
|
||||
BenchmarkScenarios/struct/reusetrue-12 330416 730.4 ns/op 168 B/op 7 allocs/op
|
||||
BenchmarkScenarios/bytes64KiB-12 37689 6035 ns/op 10858.43 MB/s 65768 B/op 9 allocs/op
|
||||
BenchmarkScenarios/bytes64KiB-12 41599 6222 ns/op 10533.71 MB/s 65768 B/op 9 allocs/op
|
||||
BenchmarkScenarios/bytes64KiB-12 38743 6067 ns/op 10801.83 MB/s 65768 B/op 9 allocs/op
|
||||
PASS
|
||||
ok git.yuntuo.hk/k2safe/go-omni/copyx 2.867s
|
||||
goos: darwin
|
||||
goarch: arm64
|
||||
pkg: git.yuntuo.hk/k2safe/go-omni/httpc
|
||||
cpu: Apple M2 Max
|
||||
BenchmarkHTTPClient/128B/decode-12 152140 1398 ns/op 2348 B/op 22 allocs/op
|
||||
BenchmarkHTTPClient/128B/decode-12 181575 1372 ns/op 2348 B/op 22 allocs/op
|
||||
BenchmarkHTTPClient/128B/decode-12 177343 1374 ns/op 2348 B/op 22 allocs/op
|
||||
BenchmarkHTTPClient/128B/discard-12 235099 997.7 ns/op 1836 B/op 21 allocs/op
|
||||
BenchmarkHTTPClient/128B/discard-12 234962 1012 ns/op 1836 B/op 21 allocs/op
|
||||
BenchmarkHTTPClient/128B/discard-12 231510 990.5 ns/op 1836 B/op 21 allocs/op
|
||||
BenchmarkHTTPClient/4KiB/decode-12 34695 7010 ns/op 17086 B/op 31 allocs/op
|
||||
BenchmarkHTTPClient/4KiB/decode-12 34256 7020 ns/op 17084 B/op 31 allocs/op
|
||||
BenchmarkHTTPClient/4KiB/decode-12 34084 7043 ns/op 17087 B/op 31 allocs/op
|
||||
BenchmarkHTTPClient/4KiB/discard-12 223120 1058 ns/op 1836 B/op 21 allocs/op
|
||||
BenchmarkHTTPClient/4KiB/discard-12 205618 1067 ns/op 1836 B/op 21 allocs/op
|
||||
BenchmarkHTTPClient/4KiB/discard-12 224156 1079 ns/op 1836 B/op 21 allocs/op
|
||||
BenchmarkHTTPClient/64KiB/decode-12 3010 80622 ns/op 213909 B/op 38 allocs/op
|
||||
BenchmarkHTTPClient/64KiB/decode-12 3122 81358 ns/op 213949 B/op 38 allocs/op
|
||||
BenchmarkHTTPClient/64KiB/decode-12 2982 80473 ns/op 213901 B/op 38 allocs/op
|
||||
BenchmarkHTTPClient/64KiB/discard-12 110815 2154 ns/op 1836 B/op 21 allocs/op
|
||||
BenchmarkHTTPClient/64KiB/discard-12 112252 2107 ns/op 1836 B/op 21 allocs/op
|
||||
BenchmarkHTTPClient/64KiB/discard-12 114548 2094 ns/op 1835 B/op 21 allocs/op
|
||||
BenchmarkHTTPClient/Do-12 366976 662.1 ns/op 1296 B/op 17 allocs/op
|
||||
BenchmarkHTTPClient/Do-12 351373 664.2 ns/op 1296 B/op 17 allocs/op
|
||||
BenchmarkHTTPClient/Do-12 335104 679.0 ns/op 1296 B/op 17 allocs/op
|
||||
PASS
|
||||
ok git.yuntuo.hk/k2safe/go-omni/httpc 5.889s
|
||||
66
reports/developerToolsBenchmark.txt
Normal file
66
reports/developerToolsBenchmark.txt
Normal file
@@ -0,0 +1,66 @@
|
||||
goos: darwin
|
||||
goarch: arm64
|
||||
pkg: git.yuntuo.hk/k2safe/go-omni/copyx
|
||||
cpu: Apple M2 Max
|
||||
BenchmarkScenarios/struct/reusefalse-12 185918 1261 ns/op 1120 B/op 17 allocs/op
|
||||
BenchmarkScenarios/struct/reusefalse-12 191277 1254 ns/op 1120 B/op 17 allocs/op
|
||||
BenchmarkScenarios/struct/reusefalse-12 192738 1267 ns/op 1120 B/op 17 allocs/op
|
||||
BenchmarkScenarios/struct/reusetrue-12 336856 716.9 ns/op 168 B/op 7 allocs/op
|
||||
BenchmarkScenarios/struct/reusetrue-12 333480 719.1 ns/op 168 B/op 7 allocs/op
|
||||
BenchmarkScenarios/struct/reusetrue-12 338338 753.9 ns/op 168 B/op 7 allocs/op
|
||||
BenchmarkScenarios/bytes64KiB-12 43203 5588 ns/op 11727.22 MB/s 65768 B/op 9 allocs/op
|
||||
BenchmarkScenarios/bytes64KiB-12 43075 5613 ns/op 11675.18 MB/s 65768 B/op 9 allocs/op
|
||||
BenchmarkScenarios/bytes64KiB-12 42343 5646 ns/op 11608.06 MB/s 65768 B/op 9 allocs/op
|
||||
BenchmarkTypeCheck-12 377830 599.8 ns/op 32 B/op 3 allocs/op
|
||||
BenchmarkTypeCheck-12 408428 597.8 ns/op 32 B/op 3 allocs/op
|
||||
BenchmarkTypeCheck-12 409514 597.7 ns/op 32 B/op 3 allocs/op
|
||||
PASS
|
||||
ok git.yuntuo.hk/k2safe/go-omni/copyx 3.326s
|
||||
goos: darwin
|
||||
goarch: arm64
|
||||
pkg: git.yuntuo.hk/k2safe/go-omni/httpc
|
||||
cpu: Apple M2 Max
|
||||
BenchmarkHTTPClient/128B/decode-12 170685 1369 ns/op 2347 B/op 22 allocs/op
|
||||
BenchmarkHTTPClient/128B/decode-12 174030 1384 ns/op 2348 B/op 22 allocs/op
|
||||
BenchmarkHTTPClient/128B/decode-12 179733 1368 ns/op 2348 B/op 22 allocs/op
|
||||
BenchmarkHTTPClient/128B/discard-12 242395 1009 ns/op 1836 B/op 21 allocs/op
|
||||
BenchmarkHTTPClient/128B/discard-12 242695 1010 ns/op 1836 B/op 21 allocs/op
|
||||
BenchmarkHTTPClient/128B/discard-12 230649 1008 ns/op 1836 B/op 21 allocs/op
|
||||
BenchmarkHTTPClient/4KiB/decode-12 34294 7130 ns/op 17085 B/op 31 allocs/op
|
||||
BenchmarkHTTPClient/4KiB/decode-12 34273 6992 ns/op 17085 B/op 31 allocs/op
|
||||
BenchmarkHTTPClient/4KiB/decode-12 33758 7184 ns/op 17086 B/op 31 allocs/op
|
||||
BenchmarkHTTPClient/4KiB/discard-12 215698 1059 ns/op 1836 B/op 21 allocs/op
|
||||
BenchmarkHTTPClient/4KiB/discard-12 226962 1108 ns/op 1837 B/op 21 allocs/op
|
||||
BenchmarkHTTPClient/4KiB/discard-12 227298 1045 ns/op 1836 B/op 21 allocs/op
|
||||
BenchmarkHTTPClient/64KiB/decode-12 3099 79497 ns/op 213929 B/op 38 allocs/op
|
||||
BenchmarkHTTPClient/64KiB/decode-12 2742 80571 ns/op 213924 B/op 38 allocs/op
|
||||
BenchmarkHTTPClient/64KiB/decode-12 2696 121378 ns/op 213907 B/op 38 allocs/op
|
||||
BenchmarkHTTPClient/64KiB/discard-12 111092 2144 ns/op 1836 B/op 21 allocs/op
|
||||
BenchmarkHTTPClient/64KiB/discard-12 103948 2132 ns/op 1836 B/op 21 allocs/op
|
||||
BenchmarkHTTPClient/64KiB/discard-12 115408 2111 ns/op 1835 B/op 21 allocs/op
|
||||
BenchmarkHTTPClient/Do-12 374404 656.7 ns/op 1296 B/op 17 allocs/op
|
||||
BenchmarkHTTPClient/Do-12 353349 664.5 ns/op 1296 B/op 17 allocs/op
|
||||
BenchmarkHTTPClient/Do-12 348849 665.8 ns/op 1296 B/op 17 allocs/op
|
||||
BenchmarkJSONSuccessStatus/false-12 203222 1233 ns/op 2345 B/op 22 allocs/op
|
||||
BenchmarkJSONSuccessStatus/false-12 201913 1213 ns/op 2345 B/op 22 allocs/op
|
||||
BenchmarkJSONSuccessStatus/false-12 201854 1224 ns/op 2345 B/op 22 allocs/op
|
||||
BenchmarkJSONSuccessStatus/true-12 199285 1249 ns/op 2393 B/op 23 allocs/op
|
||||
BenchmarkJSONSuccessStatus/true-12 184888 1254 ns/op 2393 B/op 23 allocs/op
|
||||
BenchmarkJSONSuccessStatus/true-12 194844 1222 ns/op 2393 B/op 23 allocs/op
|
||||
PASS
|
||||
ok git.yuntuo.hk/k2safe/go-omni/httpc 7.606s
|
||||
goos: darwin
|
||||
goarch: arm64
|
||||
pkg: git.yuntuo.hk/k2safe/go-omni/logx
|
||||
cpu: Apple M2 Max
|
||||
BenchmarkLoggerTimeZone/#00-12 256226 850.2 ns/op 112 B/op 3 allocs/op
|
||||
BenchmarkLoggerTimeZone/#00-12 277039 852.6 ns/op 112 B/op 3 allocs/op
|
||||
BenchmarkLoggerTimeZone/#00-12 285422 851.5 ns/op 112 B/op 3 allocs/op
|
||||
BenchmarkLoggerTimeZone/UTC-12 270704 885.0 ns/op 112 B/op 3 allocs/op
|
||||
BenchmarkLoggerTimeZone/UTC-12 277340 879.1 ns/op 112 B/op 3 allocs/op
|
||||
BenchmarkLoggerTimeZone/UTC-12 271767 890.3 ns/op 112 B/op 3 allocs/op
|
||||
BenchmarkLoggerTimeZone/Asia/Shanghai-12 273482 883.3 ns/op 112 B/op 3 allocs/op
|
||||
BenchmarkLoggerTimeZone/Asia/Shanghai-12 274610 888.7 ns/op 112 B/op 3 allocs/op
|
||||
BenchmarkLoggerTimeZone/Asia/Shanghai-12 270154 892.8 ns/op 112 B/op 3 allocs/op
|
||||
PASS
|
||||
ok git.yuntuo.hk/k2safe/go-omni/logx 2.665s
|
||||
Reference in New Issue
Block a user