v1.35.0 请求管线性能优化报告

Cosy v1.35.0 重构了 Create、Update、Custom 和 BatchUpdate 共用的请求解码与校验管线。新实现将重复的反射、规则解析和转换器分派前移到编译阶段，再把生成的计划缓存并复用于后续请求。

核心结果

在 Apple M5 Pro、Go 1.27.0、darwin/arm64、单 CPU 基准环境中，典型写请求的框架侧开销由 82,627 ns/op 降至 3,888 ns/op，约快 21.3 倍；分配次数由 276 降至 34，减少 87.7%。

请求管线变化

v1.34.x 的主要开销来自每次请求都重复执行的通用反射逻辑：

JSON bytes
  -> encoding/json v1 -> gin.H
  -> validator.ValidateMap
  -> BeforeDecode hooks
  -> mapstructure.WeakDecode
  -> GORM

v1.35.0 的管线改为：

JSON bytes
  -> encoding/json/v2 -> gin.H
  -> internal/rulecheck 执行已编译规则
  -> BeforeDecode hooks
  -> map2struct.WeakDecode -> internal/structcodec 执行已编译类型计划
  -> GORM

cosy/map2struct 仍然是公开兼容门面；移除的是第三方 github.com/mitchellh/mapstructure 引擎。

基准方法

新实现数据于 2026-09-01 测得：

• Apple M5 Pro，darwin/arm64。
• Go 1.27.0。
• -cpu=1 -count=5，表格取五轮中位数。
• 典型模型包含 10 个字段，其中包括 time.Time、decimal.Decimal、null.String 和 slice。
• 旧实现使用相同负载在 v1.34.x 请求管线上测量。

请求管线分段结果：

阶段	v1.34.x	v1.35.0	提升
JSON bytes -> map	2,477 ns / 54 allocs	2,076 ns / 24 allocs	1.19x
规则校验	53,737 ns / 139 allocs	466.2 ns / 0 allocs	115.3x
map -> struct	23,376 ns / 83 allocs	886.7 ns / 10 allocs	26.4x
端到端	82,627 ns / 276 allocs	3,888 ns / 34 allocs	21.3x

v1.35.0 当前内存数据：

阶段	B/op	allocs/op
JSON bytes -> map	1,304	24
规则校验	0	0
map -> struct	496	10
端到端	1,800	34

规则校验的 115.3 倍包含两个收益来源：编译式规则引擎，以及旧 safety_text 每次校验都重新编译正则的问题修复。只比较相同的预编译规则时，rulecheck.ValidateMap 五轮中位数为 124.6 ns/op、0 alloc，validator.ValidateMap 为 444.8 ns/op、5 allocs，规则引擎本身约快 3.6 倍。

map2struct 包内的完整模型包含更多特殊类型，因此不能与上面的请求管线模型混用。其当前 WeakDecode 中位数为 969.8 ns/op、536 B/op、13 allocs/op；旧 mapstructure 完整模型为 29,582 ns/op、8,160 B/op、102 allocs/op，约快 30.5 倍。原始五轮数据记录在 map2struct/BENCHMARKS.md。

编译式规则校验

internal/rulecheck 以完整规则字符串作为缓存键：

"required,safety_text,max=100"
  -> [requiredCheck, safetyTextCheck, maxCheck(100)]

首次遇到规则时完成拆分、参数解析和执行函数选择；后续请求直接遍历闭包数组。常用规则使用类型 switch 和直接比较，不构造 validator 的反射上下文：

• required、omitempty、omitzero、omitnil。
• email、url、date、safety_text、hostname_port。
• min、max、oneof、dive。

min、max 和 oneof 的参数只解析一次。email、hostname 和 Unicode safety_text 正则只在进程启动时编译一次；常见 ASCII safety_text 输入使用字节循环，不进入正则引擎。成功路径不会创建错误 map，因此常用规则可以做到 0 alloc。

为了维持 validator 兼容性，以下情况仍回退到 validator.Var：

• 未内置的 tag。
• 快路径不支持的值类型。
• 包含 |、0x2C 或 0x7C 的复杂语法。
• 通过 cosy.RegisterValidation 覆盖的内置 tag。

注册覆盖规则时会清空规则缓存，使已见过的规则重新编译并正确路由到 validator。

编译式 map 到 struct

internal/structcodec 按目标 reflect.Type 编译解码计划。反射用于首次扫描 JSON tag、字段偏移、embedded 字段和目标类型；请求热路径执行缓存后的闭包，不再创建 mapstructure decoder，也不再对每个字段运行一组反射 hook。

主要优化包括：

• 按输入字段直接查找计划项，避免每次复制字段索引 map。
• 在编译时为字符串、布尔、整数、浮点和嵌套 struct 选择特化解码器。
• 在编译时解析特殊类型转换器和嵌套计划。
• 转换器注册表使用 copy-on-write 快照，读取路径只需一次原子加载。
• RFC 3339 时间字符串使用快速路径。
• slice 和 map 逐元素复制，避免结果引用请求 payload。
• 先解码到目标副本，全部成功后再提交，错误不会留下半写对象。

map2struct.RegisterTypeDecoder 提供自定义类型扩展入口；注册新转换器时会使相关缓存失效。

JSON 与请求体保护

JSON bytes 到 map 使用标准库 encoding/json/v2，并叠加 v1 兼容选项。v1.35.0 有意收紧以下输入：

• 重复 JSON 键返回 406，不再静默接受。
• 非法 UTF-8 返回 406，不再替换为 U+FFFD。
• 原始控制字符和超过标准库嵌套深度上限的输入返回错误。

所有路由默认限制请求体为 10 MiB。settings.Server.PayloadMaxBytes 为 0 时使用默认值，正数指定字节数，负数关闭限制。CRUD 保留现有 406 错误契约；BindAndValid 超限返回 413。

上下文与并发安全

Gin 会复用 *gin.Context。直接把它交给 GORM，可能使数据库异步清理 goroutine 在请求结束后读到已经被复用的对象。

v1.35.0 的 model.RequestContext 创建独立上下文，并保留调用方 deadline 与 c.Set 快照。模型初始化阶段还会预热所有已注册类型的 structcodec 计划，减少首个业务请求的冷启动成本。

兼容性与迁移

升级 v1.35.0 前需要检查：

1. Go 工具链最低版本为 1.27.0。
2. 客户端是否发送重复 JSON 键或非法 UTF-8。
3. 超过 10 MiB 的合法请求是否需要调整 PayloadMaxBytes。
4. 覆盖内置校验 tag 时是否使用 cosy.RegisterValidation，而不是直接调用 GetValidator().RegisterValidation。
5. 是否使用已经移除的 legacy decode hook API；自定义类型应迁移到 map2struct.RegisterTypeDecoder。
6. 是否依赖 BindAndValid 过去对超限或畸形 JSON 返回 500 的行为。

安全与持续验证

自研解码器直接处理不可信请求，并使用 unsafe.Pointer 写入已验证的字段偏移，因此安全回归测试是发布门槛：

• 只有同时存在于 rules 和模型中的字段允许写入，防止 mass assignment。
• 类型混淆、数值边界、递归嵌入和畸形规则不得 panic。
• 解码结果不得引用请求缓冲区或跨请求共享容器。
• 转换失败不得产生半解码对象。
• validator fallback 必须通过差分测试保持原有语义。

CI 在 push、pull request 和每周定时任务中运行完整测试与 govulncheck。每周还会对 FuzzWeakDecodeNeverPanics 和 FuzzValidateMapNeverPanics 分别执行 10 分钟 fuzz。

复现命令

# 请求管线分段与端到端
go test . -run '^$' \
  -bench '^(BenchmarkStdJSONToMap|BenchmarkPipelineJSONToMap|BenchmarkPipelineValidate|BenchmarkPipelineDecode|BenchmarkPipelineEndToEnd)$' \
  -benchmem -count=5 -cpu=1

# 规则引擎与 validator 成对比较
go test ./internal/rulecheck -run '^$' \
  -bench '^(BenchmarkRulecheckValidateMap|BenchmarkValidatorValidateMap)$' \
  -benchmem -count=5 -cpu=1

# map2struct 完整模型
go test ./map2struct -run '^$' \
  -bench '^BenchmarkWeakDecode' \
  -benchmem -count=5 -cpu=1

基准结果会受到 CPU 频率、温度、后台任务和 Go 工具链影响。比较前后版本时必须使用相同机器、工具链、负载、GOMAXPROCS 和轮数。