Go strings.Cut 怎样保留错误信息

解析配置项、路由片段或命令行参数时，最怕的不是返回一个错误，而是错误只剩下“格式不正确”，看不出到底是哪一段输入出了问题。strings.Cut 的价值正在这里：它返回 before、after 和 found 三个结果，调用方可以在分隔符缺失时保留原始字符串，再把具体输入放进错误上下文。

直接做法：始终接住第三个返回值 found；如果它是 false，不要继续把 after 当成有效字段，而是用原始输入构造错误。字段本身非法时，再用 fmt.Errorf 的 %w 包装底层原因。这样既能读到“哪条输入失败”，也不会丢掉可供 errors.Is 判断的错误链。

官方地址：https://pkg.go.dev/strings#Cut

先把 found 当成结构信号

strings.Cut(s, sep) 只围绕第一个分隔符切开字符串。找到分隔符时，before 是左侧内容，after 是右侧内容，found 为 true；找不到时，返回值是原字符串、空字符串和 false。因此，前三个值不是三个可以随便忽略的结果，而是“切分结果 + 结构是否成立”的组合。

package main

import (
	"fmt"
	"strings"
)

func main() {
	input := "region=cn"
	key, value, found := strings.Cut(input, "=")

	// found 表示分隔符是否真的存在，不能只凭 value 是否为空来判断。
	if !found {
		fmt.Printf("无法解析 %q：缺少 =\n", input)
		return
	}

	// 左右字段都可能为空，结构判断和业务校验要分开处理。
	fmt.Printf("key=%q value=%q\n", key, value)
}

例如输入 regioncn 时，value 同样会是空字符串，但真正的问题是分隔符不存在；输入 region= 时，结构已经切开，只是右侧字段为空。把这两种情况混成“value 为空”，后面就很难给出准确提示。

缺少分隔符时，把原始输入放回错误

一个常见的错误写法是直接返回 errors.New("invalid format")。它虽然能让调用方知道失败了，却没有告诉调用方是哪一条数据失败。更实用的错误至少应包含原始输入和缺少的结构标记：

package config

import (
	"fmt"
	"strings"
)

func splitSetting(raw string) (string, string, error) {
	key, value, found := strings.Cut(raw, "=")
	if !found {
		// 保留 raw，调用方无需重新猜测是哪条配置触发了错误。
		return "", "", fmt.Errorf("配置项 %q 缺少分隔符 =", raw)
	}

	// 结构已成立，空字段是否允许交给更具体的业务规则判断。
	return key, value, nil
}

这里不要用 strings.Split 后只取下标 0 和 1 来代替判断。除了容易越界，还会把多个分隔符的处理规则藏起来。Cut 明确表达“只切第一处”，而 found 让缺少分隔符成为一个可命名的分支。

空字段和非法字段要分开报错

解析逻辑通常有三层判断：先判断结构，再判断字段是否为空，最后判断字段内容是否符合业务格式。三层都使用同一个原始输入，错误信息才会连贯：

package config

import (
	"fmt"
	"strconv"
	"strings"
)

type Setting struct {
	Name  string
	Number int
}

func parseSetting(raw string) (Setting, error) {
	name, numberText, found := strings.Cut(raw, "=")
	if !found {
		// 结构错误优先返回原始文本，避免误报为数值错误。
		return Setting{}, fmt.Errorf("解析配置 %q 失败：缺少 =", raw)
	}
	if name == "" || numberText == "" {
		// 空字段是结构完整但内容不完整，单独给出原因。
		return Setting{}, fmt.Errorf("解析配置 %q 失败：名称和值都不能为空", raw)
	}

	number, err := strconv.Atoi(numberText)
	if err != nil {
		// %w 保留 strconv 的底层错误，raw 则提供业务上下文。
		return Setting{}, fmt.Errorf("解析配置 %q 失败：值 %q 不是整数：%w", raw, numberText, err)
	}
	return Setting{Name: name, Number: number}, nil
}

上例中的 raw 与 numberText 都保留在错误中：前者回答“哪一条配置有问题”，后者回答“哪一段值有问题”。如果你还需要让调用方判断错误类别，就不要只拼接字符串，应当把底层错误作为 %w 的参数传入。

用 %w 保留可判断的底层原因

“保留错误信息”有两层含义：面向人的消息要包含输入上下文，面向程序的错误链要能继续判断。两者可以同时做到。下面把转换错误包在业务错误外面，并用 errors.Is 检查它：

package main

import (
	"errors"
	"fmt"
)

var ErrInvalidSetting = errors.New("配置值无效")

func load(raw string) error {
	// 这里模拟解析函数返回的、已经带有 raw 上下文的错误。
	return fmt.Errorf("读取 %q 失败：%w", raw, ErrInvalidSetting)
}

func main() {
	err := load("timeout=fast")
	if errors.Is(err, ErrInvalidSetting) {
		// 错误消息可展示给人，Is 则给程序稳定的分支条件。
		fmt.Println("发现不可用的配置值：", err)
	}
}

不要用 %v 替代 %w 后再期待 errors.Is 工作。%v 只负责把错误文本格式化进新消息，错误链不会因此被保留；%w 才是“增加上下文但仍可追溯原因”的选择。

把解析规则收进一个小函数

如果多个入口都要解析同一种 name=value 格式，建议把 Cut、空字段判断和错误包装放进一个小函数。调用方只处理结构化结果或展示错误，不再各自复制一套分支：

package config

import (
	"fmt"
	"strconv"
	"strings"
)

type Setting struct {
	Name   string
	Number int
}

func Parse(raw string) (Setting, error) {
	name, text, found := strings.Cut(raw, "=")
	if !found {
		// 统一入口的错误格式，便于日志和上层提示保持一致。
		return Setting{}, fmt.Errorf("%q 不是 name=value 格式", raw)
	}
	if strings.TrimSpace(name) == "" || strings.TrimSpace(text) == "" {
		// 保留原始 raw，同时用字段名说明哪类内容缺失。
		return Setting{}, fmt.Errorf("%q 含有空的名称或值", raw)
	}

	number, err := strconv.Atoi(text)
	if err != nil {
		// 通过 %w 让上层仍能识别数字转换失败的底层原因。
		return Setting{}, fmt.Errorf("%q 的值无法转换为整数：%w", raw, err)
	}
	return Setting{Name: name, Number: number}, nil
}

注意，这种函数不应该悄悄修改原始输入后再报错。例如可以用 strings.TrimSpace 做校验，但错误里仍保留原始 raw，这样日志中的内容与用户实际提交的内容一致。至于是否允许值中再次出现 =，要在函数说明中固定下来：Cut 只处理第一处，剩余内容会完整留在 text 中。

什么时候换用 CutPrefix 或 CutLast

strings.Cut 适合“围绕第一个分隔符拆成左右两段”。如果需求变成“只有存在固定前缀才继续”，CutPrefix 表达得更直接；如果要从最后一个分隔符切开路径或版本号，才考虑 CutLast。不要为了复用一个函数，把不同的输入规则硬塞进同一个解析器。

最后检查这几个容易丢信息的地方

• 忽略 found：把找不到分隔符的输入当成合法空值，后续错误会变得模糊。
• 只返回固定错误文本：不带 raw 时，批量解析失败后无法定位具体数据。
• 用 %v 包装底层错误：人能看到文本，但程序不能再通过 errors.Is 判断原因。
• 先 TrimSpace 再丢掉原文：校验可以使用清洗后的字段，错误上下文仍应保留原始输入。
• 把空字段和缺分隔符混为一谈：前者是结构存在但内容不完整，后者是输入形状不成立。

所以，strings.Cut 的关键不是少写几行切片代码，而是把“分隔符是否存在”变成一个明确的结构信号。接住 found，保留 raw，再用 %w 包装真正的底层原因，错误消息就能同时服务排查和程序分支。

相关问题

strings.Cut 找不到分隔符时会返回什么？

它返回原字符串、空字符串和 false。因此不要仅凭第二个返回值为空来判断切分失败，应该检查 found。

为什么不直接用 strings.Split？

如果只需要第一处分隔符两侧的结果，Cut 更直接，也能把“是否找到分隔符”作为独立返回值。需要全部字段时再用 Split 或 SplitN。

错误中一定要放完整原始输入吗？

是否完整保留取决于输入是否包含敏感信息。对普通配置和批处理数据，完整 raw 有助于定位；若输入可能含密钥或个人数据，应在错误上下文中使用脱敏后的标识。

%w 和 %v 的区别是什么？

%w 会保留可供 errors.Is 或 errors.As 继续检查的错误链，%v 只格式化错误文本。需要增加上下文并保留原因时使用 %w。

资料入口：https://pkg.go.dev/strings#Cut；Go 1.18 发布说明：https://go.dev/doc/go1.18；错误格式化说明：https://pkg.go.dev/fmt#errorf。