Go url.UserPassword 怎样构造带认证信息的 URL

我第一次把用户名和密码拼进一个 Go URL 时，直觉是手写 https://user:pass@example.com。这在字符简单时看不出问题，遇到特殊字符、需要重新读取字段，或者要把地址写进日志，手拼字符串就很容易把结构和安全边界混在一起。更稳妥的做法是让 net/url 管理用户信息：url.UserPassword 创建 *url.Userinfo，再挂到 url.URL.User。

官方地址：https://pkg.go.dev/net/url#UserPassword

把认证信息放进 URL 结构字段

url.UserPassword(username, password) 的返回值是不可变的 *url.Userinfo。它只表示 URL 中的用户信息，真正的主机、路径和查询参数仍由 url.URL 的其他字段负责。这样拆开后，用户名密码、主机和路径各自有明确位置，后续读取或脱敏时不用再次解析整条字符串。

package main

import (
	"fmt"
	"net/url"
)

func main() {
	u := &url.URL{
		Scheme: "https", // 协议独立放在 URL 结构中。
		Host:   "legacy.example.test", // 主机不要混进用户名字段。
		User:   url.UserPassword("demo", "p@ss word"), // 让 net/url 负责 userinfo 编码。
		Path:   "/reports/today", // 路径仍然是 URL 的独立组成部分。
	}

	fmt.Println(u.String()) // 只展示构造结果；真实日志不要直接输出含密码的 URL。
}

这里的 User 字段接收的是 *url.Userinfo，不是普通字符串。输出时，String 会按 URL 的标准形式重新组合各字段，密码中的特殊字符也会以 userinfo 允许的编码形式出现。图中的 url.UserPassword、url.Userinfo、URL.User 和 URL.String 是结构关系，不代表某个真实运行截图。

区分 String、Username 和 Password

把 Userinfo 当成一段已经拼好的文本，会错过它提供的三个读取边界。Username() 返回用户名；Password() 返回密码以及“密码是否设置”的布尔值；Userinfo.String() 返回编码后的 username[:password] 形式。尤其是第二个返回值，能区分“没有密码”和“密码恰好是空字符串”。

func inspectUserinfo(u *url.URL) {
	if u.User == nil {
		return // 没有 Userinfo 时不能直接调用 Username 或 Password。
	}

	name := u.User.Username() // 读取用户名，不需要手动切分 @ 前的文本。
	password, hasPassword := u.User.Password() // 同时保留密码存在性。
	fmt.Println("username:", name)
	fmt.Println("password-set:", hasPassword)

	_ = password // 业务确实需要时再使用；不要把它写入普通日志。
	fmt.Println("userinfo:", u.User.String()) // 这是编码后的 userinfo，不是脱敏文本。
}

解析外部输入时，先用 url.Parse 得到 URL，再通过 u.User 读取字段。解析成功只说明字符串符合 URL 语法，不代表其中的凭据适合继续传播；“能解析”和“能安全记录”是两件事。

为日志和配置设置脱敏边界

我觉得这个 API 最容易被低估的代价不是编码，而是地址太像普通字符串。调用 u.String()、fmt.Println(u) 或把 URL 直接放进错误上下文，都可能让密码进入日志、追踪标签、异常消息或复制粘贴记录。URL.Redacted() 会把 User 中的密码替换为 xxxxx，更适合作为诊断输出。

func logSafeURL(raw string) error {
	u, err := url.Parse(raw)
	if err != nil {
		return fmt.Errorf("parse service URL: %w", err) // 保留解析错误，但不回显未经处理的凭据。
	}

	if u.User != nil {
		_, _ = u.User.Password() // 需要判断是否有认证信息时，只读取存在性即可。
	}
	fmt.Println("request target:", u.Redacted()) // 日志使用脱敏 URL，避免记录真实密码。
	return nil
}

这里没有把密码重新写入另一个变量，也没有把原始输入附加到错误文本。图中的 URL.String 是普通 URL 输出，URL.Redacted 是日志出口；它们都能描述地址，但用途不同。

什么时候不该使用 UserPassword

Go 官方文档明确提醒，URL userinfo 的认证信息可能以明文 URI 形式传播，因此只建议用于遗留网站兼容。它不是 HTTPS 的替代品，也不是一个通用的凭据存储方案：HTTPS 能加密传输，不会自动阻止 URL 被访问日志、代理、监控标签或错误信息记录。

如果服务支持更现代的认证方式，优先把凭据放在请求头、专用认证对象或受控的客户端配置中，并让日志层只记录主机、路径和认证类型。只有对方协议明确要求 username:password@host 这种 URL 形态时，才使用 UserPassword，并在进入日志、缓存键和错误链之前调用 Redacted。

常见问题

url.UserPassword 会返回完整 URL 吗？

不会。它只返回 *url.Userinfo，还需要把它赋给 url.URL.User，并自行设置 scheme、host、path 等字段。

密码为空时，Password() 的第二个返回值是什么？

第二个返回值表示密码是否被设置，而不是密码字符串是否为空。使用它可以区分没有密码和设置了空密码。

u.String() 和 u.Redacted() 该怎么选？

构造真正需要携带 userinfo 的请求地址时才使用 String()；日志、错误、追踪和诊断输出优先使用 Redacted()。

最终可以把规则记成一句话：用结构字段构造，用 Username 和 Password 读取，用 Redacted 记录；只有在遗留协议确实要求 URL userinfo 时，才让密码进入 URL。