Go time.ParseDuration 遇到中文或复合单位输入怎么给出明确错误

我在把超时配置从整数秒改成可读字符串时，最先踩到的坑不是 Go 代码本身，而是用户会自然地写出“30秒”“1小时30分”这样的输入。time.ParseDuration 并不会把这些中文单位当成别名，它只识别固定的 ASCII 或微秒单位。处理这类输入时，关键是保留原始字段和值，把“未知单位”和“组合格式错误”说清楚，再让业务层只接收已经解析好的 time.Duration。

官方文档：https://pkg.go.dev/time#ParseDuration

直接接受 1h30m、250ms 这类标准写法；遇到中文单位、d（天）或缺少单位的字符串，不要静默改成零值，应在配置边界返回包含字段名和原始输入的明确错误。

先划清 time.ParseDuration 的单位边界

time.ParseDuration 解析的是一个带单位的时长字符串。可用单位包括 ns、us、µs、ms、s、m 和 h；多个数字和单位可以连续组合，例如 1h30m。中文“秒”、中文“分钟”、d 和 day 都不在这张单位表里。

这里最容易误判的是“复合单位”。1h30m 是合法复合值，但 1小时30分 不是“同一个意思的另一种写法”，而是包含了解析器不认识的单位。不要在业务代码里把错误的自然语言输入悄悄替换成另一套规则，否则配置文件看起来成功，实际含义却可能已经变化。

我会先保留原始输入，再把错误包上字段名

解析函数本身只知道收到了一段字符串，不知道它来自哪个配置字段。工程代码可以在配置加载边界补充字段名和原始输入，这样调用方看到的不是孤立的 unknown unit，而是“请求超时时间使用了不支持的值”这类可以直接修改配置的提示。

package config

import (
	"fmt"
	"time"
)

// parseDurationField 只负责把外部字符串转换成标准库 Duration。
// 保留字段名和值，便于配置文件或命令行报错时快速定位来源。
func parseDurationField(field, raw string) (time.Duration, error) {
	d, err := time.ParseDuration(raw)
	if err != nil {
		// 用 %q 保留中文、空格和原始大小写，避免错误提示失真。
		return 0, fmt.Errorf("配置字段 %s 的时长 %q 无效：%w", field, raw, err)
	}
	return d, nil
}

这个封装没有新增自定义单位，也没有把错误改写成模糊的“解析失败”。%w 保留了标准库错误，日志或上层调用仍能继续使用错误链；%q 则让空字符串、中文输入和带空格输入在日志里保持可见。

合法复合单位要写成 1h30m 这样的连续片段

复合时长的每一段都由数字和一个合法单位组成，段与段之间不放自然语言连接词，也不要插入空格。下面的示例把几个常见输入放在表格里，方便决定哪些值可以直接进入配置。

如果产品文档面向中文用户，建议在示例中同时展示“配置写法”和“不能这样写”的对照，而不是只说支持复合单位。这样用户能马上把“1小时30分”改成“1h30m”，也不会误以为 time.Duration 自带天、周或中文单位。

把未知单位、缺少单位和格式错误分开提示

解析失败后不必依赖字符串匹配去重建整套语法，但可以根据标准库错误中出现的边界信息给出下一步建议。未知单位适合提示可用单位；缺少单位适合指出应补上 ms、s 等后缀；数字或组合本身不合法时，则提示按“数字+单位”连续书写。

package config

import (
	"fmt"
	"strings"
	"time"
)

// explainDurationError 把标准库错误转成面向配置使用者的建议。
// 它不修改输入，也不尝试猜测用户想表达的单位。
func explainDurationError(field, raw string, err error) error {
	message := err.Error()
	switch {
	case strings.Contains(message, "unknown unit"):
		return fmt.Errorf("配置字段 %s 的值 %q 使用了不支持的单位，请改成 ns/us/µs/ms/s/m/h", field, raw)
	case strings.Contains(message, "missing unit"):
		return fmt.Errorf("配置字段 %s 的值 %q 缺少时间单位，例如 500ms 或 2s", field, raw)
	default:
		return fmt.Errorf("配置字段 %s 的值 %q 不是合法时长，请使用数字加单位的连续写法", field, raw)
	}
}

// loadTimeout 在配置边界完成解析，成功后下游不再接触原始字符串。
func loadTimeout(raw string) (time.Duration, error) {
	d, err := time.ParseDuration(raw)
	if err != nil {
		return 0, explainDurationError("request_timeout", raw, err)
	}
	return d, nil
}

这段代码只把错误分成使用者真正关心的三类。生产代码如果需要国际化或稳定错误码，可以在这里映射自己的错误类型；不要让业务层通过“把中文秒替换成 s”来掩盖输入契约。

把解析放在配置加载边界

我更倾向于在读取环境变量、命令行或配置文件的地方立刻完成解析。这样服务启动后只携带 time.Duration，重试、HTTP 客户端或定时器代码不需要各自猜测字符串规则。

package config

import (
	"fmt"
	"os"
	"time"
)

type Config struct {
	RequestTimeout time.Duration
}

// Load 从环境变量读取超时；未设置时使用显式默认值。
// 解析失败直接返回，避免服务带着零值继续启动。
func Load() (Config, error) {
	raw := os.Getenv("REQUEST_TIMEOUT")
	if raw == "" {
		raw = "5s"
	}

	d, err := loadTimeout(raw)
	if err != nil {
		return Config{}, fmt.Errorf("加载配置失败：%w", err)
	}
	return Config{RequestTimeout: d}, nil
}

默认值要和配置契约一起写清楚；如果业务允许零时长，也应显式说明它的含义，而不是把“解析失败返回零值”和“用户确实配置了 0s”混为一谈。解析成功后，下游可以直接把 RequestTimeout 传给接受 time.Duration 的 API。

常见问题

time.ParseDuration 能直接解析“30秒”吗？

不能。中文单位不在内置单位表中，应要求配置写成 30s，或者在产品边界明确实现另一套转换规则；不要暗中把自然语言替换后再解析。

为什么 1h30m 可以，而 1h 30m 不建议？

标准写法是数字与单位片段连续组合，1h30m 的契约最清晰。带空格的输入不应被当作可移植配置格式，遇到它时直接返回错误更容易保持一致。

能不能用 d 表示天？

time.ParseDuration 没有内置 d 单位。可以把天换算成小时后写入配置，或在业务层另行定义明确的转换规则，但那已经超出这个函数的输入契约。

解析失败后直接使用 0 是否可以？

通常不应该。零值可能代表一个真实配置，也可能让请求立即超时或关闭定时器。更稳妥的做法是在配置加载阶段返回错误，阻止带着不确定超时的服务继续运行。

这次处理的核心经验很简单：让 time.ParseDuration 负责标准单位解析，让配置层负责字段上下文和用户提示。1h30m 这类复合写法可以直接接受；中文单位、未知单位和缺少单位则应该被明确拒绝，并告诉用户该怎样改。