72 lines
6.3 KiB
Markdown
72 lines
6.3 KiB
Markdown
# 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 的时区数据库。
|
||
- 本轮未修改接入项目业务代码，未连接业务数据库或使用远程服务器压测。仍需项目升级后的业务验收。
|
||
|
||
## 远程版本验收
|
||
|
||
`v0.23.0-preview` 标签固定在 `3bbc6f60d76cb9eae6f01fa6ca122eb1fbf481af`，空 module 缓存安装、固定版本消费者和 checksum 核对通过，无本地 replace。验收耗时 57.06 秒，共 66 项检查。
|
||
|
||
- 下载模块里的 config/httpc/copyx/logx 全包 race 通过，含本轮新增回归。
|
||
- 8 组实际生成消费者使用远程框架执行 race，启动/监听失败清理、后台收尾和业务文件保留通过。
|
||
- 根目录运行/构建、nethttp/native 信号与端口释放、404/405、上传下载、错误目录和两服务 workspace 通过。
|
||
- 生成检查与 `-check-config` 使用同一配置入口，无手写加载补丁。
|
||
|
||
完整版本、checksum、检查清单及源码哈希见 [developerToolsRemote.json](developerToolsRemote.json)。标签不随验收文档提交移动。
|