Go url.URL.Redacted 怎样安全输出带凭据的地址

在服务日志里记录请求目标时，最容易忽略的是 URL 可能把用户名和密码放在 userinfo 中。Go 的 url.URL.Redacted() 适合解决“需要看见地址结构，但不能把密码写进日志”的场景：它按照 URL.String() 的方式重组地址，只把 u.User 中的密码替换成 xxxxx。

官方资料：https://pkg.go.dev/net/url

如果 URL 只是要出现在日志、错误信息或诊断页面，优先输出 u.Redacted()；如果要真正发起请求，继续使用原始的 *url.URL 对象。两者解决的不是同一个问题。

先明确 URL.Redacted 处理的范围

一个 URL 可以拆成协议、userinfo、主机、路径、查询参数和片段。Redacted 只关心 userinfo 中的密码，不会把整个 URL 变成不可读的星号串，也不是通用的敏感信息清洗器。

用 url.Parse 接住带凭据的地址

不要先把原始地址拼进错误字符串，再尝试事后替换密码。更稳妥的顺序是先解析成 *url.URL，检查错误后，在需要展示时调用 Redacted。

package main

import (
	"fmt"
	"log"
	"net/url"
)

func main() {
	// 示例使用占位凭据，只演示 userinfo 的解析与展示边界。
	raw := "https://reporter:demo-password@example.com/export?format=csv"
	u, err := url.Parse(raw)
	if err != nil {
		// 解析失败时只记录原因，不继续使用不完整的 URL 对象。
		log.Fatal(err)
	}

	// String 会保留密码；Redacted 只在返回展示字符串时遮蔽密码。
	fmt.Println("完整地址：", u.String())
	fmt.Println("脱敏地址：", u.Redacted())
}

根据官方 net/url 文档，两个输出的主要差异在 userinfo：

完整地址： https://reporter:demo-password@example.com/export?format=csv
脱敏地址： https://reporter:xxxxx@example.com/export?format=csv

这里的密码只是演示用占位值。生产代码不应把真实密码写在源码、测试输出或提交记录中。

把脱敏输出集中到日志 helper

如果多个请求入口都各自决定调用 String 还是 Redacted，迟早会出现一处漏写。可以把“解析 + 脱敏展示”收拢成一个小函数，让调用点只拿到安全展示文本。

package main

import (
	"fmt"
	"net/url"
)

// safeURLForLog 只返回适合写入日志的 URL 文本，不返回原始凭据。
func safeURLForLog(raw string) (string, error) {
	u, err := url.Parse(raw)
	if err != nil {
		return "", fmt.Errorf("parse target URL: %w", err)
	}

	// Redacted 保留地址结构，且只替换 u.User 中的 password。
	return u.Redacted(), nil
}

func main() {
	// 真实项目可把返回值交给结构化日志字段，而不是记录 raw。
	display, err := safeURLForLog("https://worker:placeholder@example.com/jobs?id=42")
	if err != nil {
		fmt.Println("目标地址无效：", err)
		return
	}
	fmt.Println("请求目标：", display)
}

这个 helper 的价值不是“自动保护所有秘密”，而是固定一个明确的展示契约：解析失败就返回错误，解析成功就只返回 Redacted 结果。调用方不要再把 raw、u.String() 或包含原始 URL 的错误串混入日志。

不要把 Redacted 当成完整的秘密扫描器

Redacted 的官方定义非常窄：只替换 u.User 中的密码。如果敏感值放在查询参数、片段或应用自定义字段中，它不会自动替换。例如下面的地址即使调用了 Redacted，查询参数里的 token 仍会保留。

package main

import (
	"fmt"
	"net/url"
)

func main() {
	u, err := url.Parse("https://user:placeholder@example.com/callback?token=demo-token#profile")
	if err != nil {
		return
	}

	// Redacted 只遮蔽 userinfo 密码；token 与 fragment 需要业务侧另行处理。
	fmt.Println(u.Redacted())
}

因此可以按字段类型分别处理：

• userinfo 密码：使用 u.Redacted()。
• 查询参数中的 token：先解析 u.Query()，按业务允许的键删除或替换，再重新编码；不要假定 Redacted 会替你完成。
• 片段和自定义日志字段：根据实际协议定义单独的展示规则。

日志展示和真正发请求要分开

Redacted 返回的是字符串，定位是“给人看”。它不会复制或修改原来的 URL 对象，也不应该被拿来代替 HTTP 请求目标。需要发请求时，把原始 URL 对象交给客户端；需要记录时，再单独生成脱敏字符串。

package main

import (
	"fmt"
	"net/http"
	"net/url"
)

func main() {
	u, err := url.Parse("https://worker:placeholder@example.com/jobs")
	if err != nil {
		return
	}

	// 日志只接收脱敏字符串；请求仍使用 URL 对象表达真实目标。
	fmt.Println("准备请求：", u.Redacted())
	req, err := http.NewRequest(http.MethodGet, u.String(), nil)
	if err != nil {
		return
	}
	_ = req
}

示例只展示边界，不代表应该把凭据长期放进 URL。很多系统更适合把认证信息放在受控的请求头或专用凭据对象中，并为日志单独设计字段级脱敏。

常见问题速答

没有密码时调用 Redacted 会怎样？

它仍会返回一个重组后的 URL；没有可替换的 userinfo 密码时，通常与该地址的字符串表示一致。

Redacted 会遮蔽用户名吗？

不会。官方说明是只替换 u.User 中的密码，用户名和地址结构仍保留。

查询参数中的 token 会被处理吗？

不会。查询参数不属于该方法的自动脱敏范围，应该先按业务规则处理参数，再生成展示文本。

可以用 Redacted 生成请求地址吗？

不建议。它的目标是安全展示；真正请求应使用原始的 *url.URL 或明确的请求构造流程。

小结

Go 的 url.URL.Redacted 适合放在“需要看懂 URL、又不能显示 userinfo 密码”的展示边界。记住三点即可：先用 url.Parse 处理输入错误；日志和错误上下文调用 Redacted；查询参数、片段和其他秘密仍要由业务规则单独处理。这样既能保留排障所需的地址结构，也不会把最直接的 URL 密码泄露到日志中。