map[string]interface{} 适合承载原始数据，但清洗模块输入需为可变结构；应先校验扁平化（如用gjson转点号路径），再交由统一签名的清洗函数链处理，避免panic。
用 map[string]interface{} 承载原始数据，但别直接传给清洗函数
清洗模块的输入必须是可变结构，但 Go 的强类型特性会让硬编码 struct 很难适配不同来源（CSV、JSON、API 响应）。用 map[string]interface{} 接收原始数据没问题，但清洗逻辑不能直接操作它——否则字段缺失、类型错位、嵌套空值都会导致 panic。实际做法是：先用 json.Unmarshal 或第三方库（如 gjson）做一次轻量校验和扁平化，把路径转成点号分隔键（例如 "user.profile.age"），再喂给过滤器链。
- 避免在清洗函数里写
if v, ok := data["field"]; !ok { ... }—— 这种检查要前置到配置解析阶段 - 字段路径支持通配符（如
"items.*.price"）时，用github.com/tidwall/gjson比原生json包更稳 - 如果上游数据含
null，map[string]interface{}会变成nil，清洗前务必用reflect.ValueOf(v).Kind() == reflect.Ptr && !reflect.ValueOf(v).IsNil()判空
清洗规则必须用 func(map[string]interface{}) (map[string]interface{}, error) 统一签名
动态配置的核心是让规则可插拔。所有清洗函数（比如去空格、日期格式标准化、枚举映射）必须遵守同一签名，否则无法被统一调度。不要用闭包捕获配置参数，而是把配置项作为函数工厂的输入，返回符合签名的清洗函数：
func NewTrimFilter(fields []string) func(map[string]interface{}) (map[string]interface{}, error) {
return func(data map[string]interface{}) (map[string]interface{}, error) {
for _, f := range fields {
if v, ok := data[f]; ok {
if s, ok := v.(string); ok {
data[f] = strings.TrimSpace(s)
}
}
}
return data, nil
}
}- 每个清洗函数只处理自己负责的字段，不删、不增、不改其他键 —— 否则多个规则串联时行为不可控
- 错误必须返回具体字段名和原因（如
fmt.Errorf("invalid date format in field %q: %v", field, err)），方便下游定位 - 别在清洗函数里做 I/O（如查数据库），这会让模块失去纯函数特性，也破坏并发安全
配置文件用 YAML 而非 JSON，且字段路径必须带类型提示
YAML 对注释、多行字符串、锚点支持更好，适合人工维护清洗规则。但光写 trim: ["name", "email"] 不够 —— 你得告诉模块这些字段预期是字符串，否则遇到 nil 或数字会出错。推荐配置格式：
filters:
- type: trim
fields:
- path: "user.name"
type: string
- path: "user.bio"
type: string
- type: date_normalize
field: "order.created_at"
input_format: "2006-01-02T15:04:05Z"
output_format: "2006-01-02"-
type字段对应注册的清洗器名，启动时用map[string]func(...)查找，未注册就 panic 并报错具体type值 - 所有
path必须经过gjson.Get(dataJSON, path).Value()提取，避免手写递归取值引入 bug - 配置加载后立即校验字段路径是否存在（用样例数据跑一次 dry-run），而不是等到第一条真实数据进来才崩
并发清洗时，sync.Pool 复用中间 map 和 bytes.Buffer
高吞吐场景下，每条数据都 make(map[string]interface{}) 和反复 json.Marshal 会触发大量 GC。用 sync.Pool 缓存清洗过程中的临时结构体能降 20%+ CPU 占用：
立即学习“go语言免费学习笔记（深入）”；
var mapPool = sync.Pool{
New: func() interface{} {
return make(map[string]interface{})
},
}
// 使用时：
m := mapPool.Get().(map[string]interface{})
defer func() { clear(m); mapPool.Put(m) }()- 复用的
map必须在每次使用前clear()（Go 1.21+），旧版本用for k := range m { delete(m, k) } -
bytes.Buffer适合缓存序列化后的 JSON 字节，尤其当你需要多次解析同一份原始数据时 - 别池化清洗函数本身或配置对象 —— 它们是只读的，复用没意义，反而增加 GC 压力
最易被忽略的一点：清洗规则的执行顺序不是配置出现顺序，而是由依赖关系隐式决定的 —— 比如 date_normalize 必须在 string_to_upper 之后（否则把日期字符串转大写就废了）。配置里得显式加 depends_on 字段，运行时构建 DAG，否则上线后数据错乱很难排查。
