Go maps.Clone 怎样处理空值和异常分支

maps.Clone 可以接收 nil map，并会保留 nil；非 nil 空 map 则复制为空映射。它只返回副本，不返回 error，所以“空值是允许、忽略还是拒绝”“复制后是否需要可写”“业务错误如何返回”都要由外围接口定义。不要把 Clone 包进 recover，就声称处理了所有异常。

一个常见需求是预览配置变更：用户可以保留某字段、删除某字段，也可以把字段设为空字符串。本文设计一个 Apply 函数，先建立副本再应用补丁；参数不合法时返回明确错误，调用者继续持有原配置。这里的接口和示例代码均为独立编写。

官方文档：https://pkg.go.dev/maps#Clone

nil 行为源码：https://go.dev/src/maps/maps.go

map 语言规则：https://go.dev/ref/spec#Map_types

1. 接口目标：业务失败不留下半份配置

Apply 接收基础配置和一组改动，成功时返回新的可写 map，失败时返回 nil 与非 nil error。基础配置没有被写入或删除。此设计适合在提交前展示修改结果，调用方只有拿到成功结果后才决定是否替换自己的配置引用。

这不是数据库事务，也不保证并发环境下的原子发布。它只保证本函数不修改传入的基础 map。若外部代码在复制期间改写 base、patch 或补丁指向的字符串变量，仍需所有权约束或统一同步方案，不能靠 Clone 提供保护。

2. 调用方需求：先区分三种字段状态

nil patch 与非 nil 空 patch 在此都表示“没有改动”，返回的是基础配置的副本，而不是原 map 的别名。nil base 表示没有基础条目，成功结果仍会初始化为可写 map。nil 指针的删除语义是本文接口约定，并非 maps.Clone 对 map 值的特殊解释。

3. 参数设计：结果里不继续保留补丁指针

基础 map 的类型是字符串到字符串，补丁则是字符串到字符串指针。这样可以用键是否存在和指针是否为 nil 表达不同意图，同时把最终字符串值写入结果。Apply 不把补丁指针保存在输出中，调用结束后再修改补丁变量，不会让已写入的结果字符串自动改变。

为什么不用空字符串表示删除？因为空字符串本身可能是有效值。若一个字段是否存在具有业务意义，读取时应该用两项赋值取存在标志；只比较读取出的值是否为空，会把缺失和空值混为一谈。

这个函数没有实现 JSON 接口或外部协议。以后接入网络请求时，应该确保解码层确实保留缺失与显式空值的区别，并规定未知字段处理方式，而不是把本地指针设计直接当成完整的请求协议。

4. 错误处理：只给可恢复问题建立错误分支

示例只允许补丁修改 label 和 region。遇到其他键时，用 ErrPatchKey 表达不支持的参数，并附上具体键名；调用方可以用 errors.Is 分类，而不必解析错误文案。先完成字段检查，再创建和修改副本，参数错误不会产生一个被误用的成功结果。

如果有多个非法键，由于 map 遍历顺序没有稳定保证，首次返回的键也不应成为接口承诺。若产品要求稳定的多字段错误列表，应先收集并排序，再返回结构化错误。本文只承诺错误类别，不承诺多错误的呈现顺序。

资源耗尽和未同步并发访问不属于这个业务错误分支。不要承诺所有运行时问题都能被转换成 error。对于外部来源的大补丁，接收入口还应限制请求体积与条目规模；示例处理的是调用方已经持有的内存配置，不是资源保护框架。

5. 兼容策略：不要静默改变旧接口的 nil 意义

有些旧接口把 nil 返回值解释成“不更新”，有些则规定成功返回值始终可写。本例选择后者，因此必须在 Clone 返回 nil 后主动 make。直接将旧函数替换成 Clone，可能改变调用方的空值合同；迁移前应把这个决定写清楚。

本例的外层副本已经足够，因为基础配置的键和值都是字符串。若以后把值改成切片、指针或嵌套 map，必须重新讨论可变对象共享；浅复制不会自动变成深复制。此时别只改函数签名，让错误分支保持原样就算迁移完成。

6. 完整示例：正常结果和参数错误都能看懂

以下程序使用 Go 1.21 或以上版本的标准库 maps 包，可保存为 main.go。正文未执行该程序，也没有把预期值包装为测试通过记录。

package main

import (
    "errors"
    "fmt"
    "maps"
)

var ErrPatchKey = errors.New("补丁包含不支持的字段")

func allowed(key string) bool {
    return key == "label" || key == "region"
}

func Apply(base map[string]string, patch map[string]*string) (map[string]string, error) {
    // 仅检查本接口支持的补丁字段，不改写已有基础配置。
    for key := range patch {
        if !allowed(key) {
            return nil, fmt.Errorf("%w: %q", ErrPatchKey, key)
        }
    }
    result := maps.Clone(base)
    if result == nil {
        // 成功分支统一返回可写 map；这是接口选择。
        result = make(map[string]string)
    }
    for key, value := range patch {
        if value == nil {
            delete(result, key)
            continue
        }
        // 指针非 nil 时，空字符串也属于显式设置值。
        result[key] = *value
    }
    return result, nil
}

func main() {
    base := map[string]string{"label": "north", "region": "zone-a"}
    empty := ""
    patch := map[string]*string{"label": &empty, "region": nil}
    next, err := Apply(base, patch)
    if err != nil {
        fmt.Println(err)
        return
    }
    // 用存在标志区别“字段不存在”和“字段存在但为空”。
    label, hasLabel := next["label"]
    _, hasRegion := next["region"]
    fmt.Printf("label=%q exists=%t regionExists=%t\n", label, hasLabel, hasRegion)
    fmt.Println("原配置仍为:", base["label"], base["region"])

    _, err = Apply(base, map[string]*string{"unknown": &empty})
    if errors.Is(err, ErrPatchKey) {
        fmt.Println("补丁字段不受支持，保留原配置")
    }
}

按固定输入推导，label 应存在且值为空字符串，region 应不存在；base 仍保留 north 与 zone-a。传入 unknown 补丁键时，应进入 ErrPatchKey 分支，返回结果不能作为候选配置使用。这些是接口与代码推导的预期行为。

删除一个本来就不存在的键会报错吗？

本接口将删除不存在的受支持字段视为成功，便于重复应用同一个删除请求。这是当前业务选择；如果产品要求“必须原先存在”，应使用存在标志单独判断并定义新的错误类别。

空 patch 的结果与原配置是同一个 map 吗？

不是。非 nil 基础 map 会经 Clone 建立外层副本；nil 基础 map 则被本接口初始化为空 map。调用者修改成功返回值，不会修改这里的字符串基础配置。

错误返回后还需要恢复 base 吗？

本函数没有修改 base，不需要反向恢复。调用方应该在 err 为 nil 时才发布 next，并为并发读取者另行设计同步机制。清楚区分参数失败、未修改原配置和真正的并发提交，才能让“异常处理”变成可依赖的接口合同。