Go net/url 新增 MustParse：用一行代码安全初始化 URL 常量

本篇基于 Go 标准库 release note doc/next/6-stdlib/99-minor/net/url/79946.md 展开，介绍 net/url 包新增的 MustParse 函数：它调用 Parse 解析 URL，出错时直接 panic，从而把“解析 + 错误检查”的两步流程压缩成一行。读完后你会掌握这个新 API 的签名与语义、它相对于 Parse 的取舍、推荐的使用场景（用合法 URL 字符串常量初始化变量），以及标准库如何通过测试用例保证它的 panic 行为符合预期。

文档背景：一条面向标准库小变更的发布说明

doc/next/6-stdlib/99-minor/ 目录用于收录标准库中 API 变更及其他小型变更的发布说明，见 目录说明（内容为 “API changes and other small changes to the standard library go here.”），章节标题定义在 0-heading.md（“Minor changes to the library”）。

本次关联文档对应 issue 79946，原文只有一段：

The new [MustParse] function returns the parsed [URL] or panics on error. It can simplify some common uses of [Parse]. For instance, initializing variables with valid URL string constants.

即：新增 MustParse 函数，返回解析后的 URL，出错则 panic；它可以简化 Parse 的一些常见用法，例如用合法的 URL 字符串常量初始化变量。

该变更在 API 清单中的登记条目为 api/next/79946.txt：

pkg net/url, func MustParse(string) *URL #79946

签名非常明确：接收一个 string，返回 *URL，不返回 error。下面结合源码看它具体如何落地。

MustParse 的实现：Parse 之上的极薄封装

MustParse 的完整实现位于 src/net/url/url.go：

// MustParse calls Parse and panics on error.
// It is intended for use with hard-coded strings representing valid urls.
func MustParse(rawURL string) *URL {
	url, err := Parse(rawURL)
	if err != nil {
		panic(err)
	}
	return url
}

从源码结构看，它的实现就是标准的 “Must 前缀” 模式：

1. 内部直接委托给 Parse(rawURL)，本身不实现任何解析逻辑，因此两者的解析语义完全一致；
2. 解析失败时 panic(err)，把 Parse 返回的错误对象（*url.Error）原样作为 panic 值抛出，调用方若在更上层 recover，拿到的仍是带 Op == "parse" 信息的标准错误；
3. 文档注释明确界定了适用前提——“intended for use with hard-coded strings representing valid urls”，即只面向硬编码的、程序员已确认合法的 URL 字符串。

与 Parse 的关系：错误处理方式的差异

紧挨着 MustParse 上方的 Parse 是传统入口：

// Parse parses a raw url into a [URL] structure.
//
// The url may be relative (a path, without a host) or absolute
// (starting with a scheme). ...
func Parse(rawURL string) (*URL, error) {
	// Cut off #frag
	u, frag, _ := strings.Cut(rawURL, "#")
	url, err := parse(u, false)
	if err != nil {
		return nil, &Error{"parse", u, err}
	}
	...
}

Parse 会把底层 parse 返回的错误包装成 &Error{"parse", ...}。这意味着 MustParse 的 panic 值也是 *url.Error，测试代码正是依赖这一点来做断言（见下文）。两者的取舍可以概括为：

场景	推荐 API	理由
常量、配置字面量等编译期已知的合法 URL	MustParse	一行完成初始化，无需重复写 if err != nil 样板
来自用户输入、网络响应等不可信来源的 URL	Parse	错误可恢复，程序可以降级处理而不是崩溃

典型用法：用 URL 字符串常量初始化变量

发布说明给出的核心场景是 “initializing variables with valid URL string constants”。在使用 MustParse 之前，包级 URL 变量通常需要配合一个小的 panic 包装，或推迟到 init/运行时解析；现在可以直接写成一行：

package main

import (
	"log"
	"net/url"
)

// 用合法 URL 字符串常量初始化包级变量，无需处理 error。
var (
	apiBase   = url.MustParse("https://api.example.com/v1")
	homePage  = url.MustParse("https://example.com/?lang=zh#overview")
	relative  = url.MustParse("/path/to/resource")
)

func main() {
	// 解析结果可直接使用 URL 结构体字段，无需再判空。
	log.Printf("scheme=%q host=%q path=%q frag=%q",
		apiBase.Scheme, apiBase.Host, homePage.Path, homePage.Fragment)
	log.Printf("relative path=%q", relative.Path)
}

几个要点：

• 常量必须是确定合法的。若某个常量包含控制字符、非法转义、非法端口等（见下文测试用例），程序会直接 panic 并在启动或变量初始化阶段崩溃——这正是该函数想要“快速失败”的地方；
• MustParse 支持相对 URL（如 /path/to/resource），因为内部委托的 Parse 允许 path 形式的相对 URL，这也是 Parse 文档 中明确说明的行为；
• 由于不再返回 error，调用点少一次空值/错误分支，包级、全局变量初始化代码明显更简洁。

panic 语义与边界情况：测试如何固化行为

标准库对 MustParse 的契约做了两层测试验证，均位于 src/net/url/url_test.go。

第一层：正常路径。TestParse 在遍历 urltests 用例表时，对每个输入既断言 Parse 的结果，又断言 MustParse 的结果与之等价：

u = MustParse(tt.in)
if !reflect.DeepEqual(u, tt.out) {
	t.Errorf("MustParse(%q):\n\tgot  %v\n\twant %v\n", tt.in, ufmt(u), ufmt(tt.out))
}

这保证了 MustParse 不会“绕过” Parse 引入行为分叉。

第二层：异常路径。TestInvalidParse 构造了一批必然解析失败的输入，验证 Parse 返回错误、MustParse panic，且 panic 值必须是 Op == "parse" 的 *url.Error：

cases := []struct{ name, in string }{
	{name: "null-character",      in: "http://example.com/\x00"},
	{name: "control-character",   in: "http://example.com/\t"},
	{name: "invalid-escape",      in: "http://example.com/%zz"},
	{name: "invalid-port",        in: "http://example.com:port"},
	{name: "malformed-ipv6",      in: "http://[::1/"},
	{name: "ambiguous",           in: ":"},
}

for _, tt := range cases {
	t.Run(tt.name, func(t *testing.T) {
		defer func() {
			err := recover()
			if err == nil {
				t.Fatalf("MustParse(%q): should panic", tt.in)
			}
			if e, ok := err.(*Error); !ok || e.Op != "parse" {
				t.Fatalf("MustParse(%q): unexpected panic: %#v", tt.in, err)
			}
		}()
		if _, err := Parse(tt.in); err == nil {
			t.Errorf("Parse(%q): should error", tt.in)
		}
		_ = MustParse(tt.in)
	})
}

从这组用例可以读出几条实用结论：

• 以下输入都会触发 panic：路径中的 NUL/控制字符、非法百分号转义（%zz）、非数字端口、未闭合的 IPv6 方括号、以及歧义的 :；
• panic 值不是裸的 error，而是 *url.Error（Op 字段为 "parse"），因此上层若有 recover 逻辑，仍能用 errors.As 风格的方式识别错误类型；
• 该测试同时锁死了“Parse 报错 ⇔ MustParse panic”的等价关系，二者不会出现一边成功一边失败的不一致。

设计背景：标准库的 Must 系列解析函数

MustParse 并非孤例，而是标准库长期沿用的命名惯例：把“解析不可信字符串可能失败”的操作，再提供一个面向合法常量的、panic 式的便捷入口。在当前仓库的 API 历史清单中可以找到同族函数：

• api/go1.18.txt：net/netip 包的 MustParseAddr(string) Addr、MustParseAddrPort(string) AddrPort、MustParsePrefix(string) Prefix；
• api/go1.27.txt：uuid 包的 MustParse(string) UUID。

它们的共同模式是：内部委托给返回 error 的同名解析函数，失败即 panic，文档注释都强调面向 hard-coded/constant 字符串。理解 net/url.MustParse 时，可以直接套用对 netip.MustParseAddr 等的既有认知——它补全的是 URL 这一常见类型的同类缺口。

小结

围绕 doc/next/6-stdlib/99-minor/net/url/79946.md 这条发布说明，可以把本次变更归纳为三点：

1. net/url 新增 func MustParse(string) *URL（登记于 api/next/79946.txt），实现是 Parse 的一行薄封装，失败时 panic 原始 *url.Error，见 src/net/url/url.go#L415-L423；
2. 它的定位是简化合法 URL 字符串常量的初始化，让包级 URL 变量省去错误处理样板；对不可信输入仍应使用返回 error 的 Parse；
3. 标准库测试 src/net/url/url_test.go#L705-L773 同时覆盖了正常路径与六类非法输入的 panic 断言，锁死了 MustParse 与 Parse 的行为一致性和 panic 值类型，为使用者提供了可验证的契约边界。