Go regexp.Compile 怎样把配置错误返回给调用方

当正则表达式写死在源码里时，regexp.MustCompile 可以让初始化代码很短；但规则来自配置、数据库或管理后台时，编译失败应该作为普通错误返回给调用方，而不是让进程直接 panic。这个场景的答案很明确：调用 regexp.Compile，同时保留规则名称和原始错误，再由上层决定拒绝配置、记录日志还是提示用户。

官方文档地址：https://pkg.go.dev/regexp#Compile

regexp.Compile 负责把字符串解析成可匹配的 *regexp.Regexp；返回的 error 负责说明表达式为什么不能编译。编译成功后，文本匹配不到只是一个布尔结果，不应再当成配置错误。

先区分正则编译失败和匹配失败

运行时配置通常有两个完全不同的失败位置。第一种是规则本身无法解析，例如括号没有闭合，这时 regexp.Compile 返回错误，程序还没有得到可用的 Regexp。第二种是规则已经编译成功，但输入文本不满足规则，此时调用 MatchString 只得到 false，它不是编译错误。

如果把这两类情况都写成“正则校验失败”，调用方就无法判断应该修配置，还是仅仅提示当前文本不匹配。错误模型先分清，后面的日志、接口响应和重试策略才不会混在一起。

用 regexp.Compile 返回可诊断错误

regexp.Compile 成功时返回一个可用于匹配的 *regexp.Regexp；失败时返回非 nil 错误。配置边界最适合在这里做一次编译，并用 %w 包上规则名，让上层既能看到业务上下文，也能继续用 errors.As 读取底层错误类型。

package main

import (
    "fmt"
    "regexp"
    "strings"
)

func compileRule(name, raw string) (*regexp.Regexp, error) {
    // 去掉配置文件常见的首尾空白，但不改动表达式内部语义。
    raw = strings.TrimSpace(raw)
    if raw == "" {
        return nil, fmt.Errorf("规则 %q 不能为空", name)
    }

    re, err := regexp.Compile(raw)
    if err != nil {
        // %w 保留原始解析错误，调用方仍可用 errors.As 深入判断。
        return nil, fmt.Errorf("规则 %q 编译失败: %w", name, err)
    }
    return re, nil
}

这里的关键不是把错误字符串重新拼一遍，而是保留原始错误链。规则名是调用方最需要的上下文；%w 则避免把底层类型压扁成普通文本。空字符串是否允许要由业务决定，示例把它当成配置缺失处理，避免把“空规则”误认为合法兜底规则。

在配置加载阶段统一编译规则

如果配置包含多条规则，建议在启动或热更新的加载阶段逐条编译。这样运行态只保存已经编译好的对象，真正处理文本时不用每次重新解析，也不会把配置错误拖到请求链路中才暴露。

package main

import (
    "fmt"
    "regexp"
)

type RuleConfig struct {
    Name    string
    Pattern string
}

func loadRules(configs []RuleConfig) (map[string]*regexp.Regexp, error) {
    // 预分配 map，加载成功后由请求路径直接按名称取已编译规则。
    rules := make(map[string]*regexp.Regexp, len(configs))
    for _, cfg := range configs {
        if _, exists := rules[cfg.Name]; exists {
            return nil, fmt.Errorf("规则名称 %q 重复", cfg.Name)
        }

        re, err := compileRule(cfg.Name, cfg.Pattern)
        if err != nil {
            // 在加载阶段返回第一条错误，避免部分规则悄悄进入运行态。
            return nil, err
        }
        rules[cfg.Name] = re
    }
    return rules, nil
}

上面的代码需要补上 regexp 导入，实际文件可以把 compileRule 和 loadRules 放在同一个包中。失败时返回 nil map，调用方不会拿到“半成功”的规则集合；如果业务需要一次报告所有错误，也可以先收集每条带名称的错误再统一返回，但要明确部分结果不能被当成已生效配置。

编译成功后，匹配不到只是业务结果

拿到 *regexp.Regexp 后，MatchString 的职责只是判断文本是否命中。它返回 bool，没有把“未命中”包装成 error。调用方可以把 false 映射成表单提示、过滤结果或业务分支，但不要再次尝试编译同一条规则。

func checkText(rules map[string]*regexp.Regexp, name, text string) (bool, error) {
    // 规则必须来自加载阶段，运行时只负责查找并匹配。
    re, ok := rules[name]
    if !ok {
        return false, fmt.Errorf("规则 %q 未加载", name)
    }

    // false 表示文本没有命中，不代表正则表达式语法错误。
    return re.MatchString(text), nil
}

因此可以把错误分成两层：规则未加载 或 配置编译失败 是系统配置问题；matched == false 是当前输入的业务结果。这样的分层也让监控更有意义：配置错误需要告警或回滚，未命中通常只需要记录业务指标。

需要细分时读取 regexp/syntax.Error

大多数调用方只要返回带规则名称的错误即可。如果管理后台需要显示“缺少右括号”“非法转义”这类稳定分类，可以使用 errors.As 把编译错误取成 *syntax.Error。它提供 Code 和 Expr 字段，适合转换成结构化提示；不要依赖整段英文错误文本做业务判断。

package main

import (
    "errors"
    "regexp/syntax"
)

func syntaxHint(err error) (string, bool) {
    var parseErr *syntax.Error
    if !errors.As(err, &parseErr) {
        return "", false
    }

    // ErrorCode 比完整错误文本稳定，适合记录结构化诊断字段。
    return parseErr.Code.String(), true
}

如果错误已经被多层 fmt.Errorf("...: %w", err) 包装，errors.As 仍然可以沿错误链寻找底层类型。这里的诊断函数只负责提取信息，不负责决定是否继续使用该规则；编译失败的规则应在加载阶段被拒绝。

用边界表复查 API 职责

最容易踩的坑有三个：把 MustCompile 用在外部配置上；用字符串比较完整错误文本；以及编译成功后仍把每一次未命中当成系统错误。把编译放在配置加载边界、把错误用 %w 保留下来，通常就能解决大部分排查困难。

常见问题

为什么不能直接用 regexp.MustCompile？

它在表达式无法解析时会 panic，适合源码中确定正确的常量规则。配置来自用户或外部系统时，应使用 regexp.Compile，让调用方决定如何提示、回滚或拒绝配置。

MatchString 返回 false 时要不要返回 error？

通常不需要。false 表示文本没有命中；只有规则未加载、配置本身编译失败或读取配置失败时，才应该返回 error。业务层可以把 false 转换成自己的校验结果。

错误包装后还能判断语法错误吗？

可以。使用 fmt.Errorf("...: %w", err) 保留错误链，再用 errors.As 尝试取出 *syntax.Error。这样规则名称和底层解析类型可以同时保留。

小结

运行时正则配置的稳定流程是：先用 regexp.Compile 解析，失败时用 %w 包上规则名称；在配置加载阶段一次性保存已编译规则；处理文本时只把 MatchString 的 false 当成未命中；需要结构化诊断时，再通过 errors.As 读取 *syntax.Error。这样配置错误能回到调用方，匹配结果也不会被误报成系统故障。