example函数必须以example开头、无参数、无返回值且不以下划线结尾；末尾需有与实际输出完全一致的output:注释；须与被测代码同包；运行用go test -run ^example$，查看文档用go doc。
Example 函数必须以 Example 开头且无参数
Go 的 go test 只识别形如 func ExampleXXX() 的函数作为文档示例——不能带参数，不能返回值，末尾也不能加下划线（比如 ExampleXXX_test 是无效的）。常见错误是照搬单元测试写法，加了 *testing.T 参数或用了 Test 前缀，结果 go doc 和 go test -v 都不显示它。
- 正确写法：
func ExampleParseURL() { ... } - 错误写法：
func ExampleParseURL(t *testing.T) { ... }（带参数） - 错误写法：
func TestExampleParseURL() { ... }（前缀错） - 错误写法：
func ExampleParseURL_() { ... }（结尾下划线会忽略）
示例里必须有 Output: 注释块
Go 要求每个 Example 函数体末尾紧跟一段以 Output: 开头的注释，内容需与实际打印输出**完全一致**（包括空行、缩进、换行符），否则 go test 运行时会报 output mismatch 错误。
- 输出含换行？
Output:后面就得跟空行 - 用
fmt.Println打印字符串？注释里得包含那个隐式换行 - 用
fmt.Print？注释里就不能多换一行 - 建议在示例末尾加
// Output: ...之前先跑一遍，复制真实输出粘贴过去
func ExampleParseURL() {
u := ParseURL("https://example.com/path")
fmt.Printf("%s %s", u.Scheme, u.Host)
// Output: https example.com
}
Example 文件要和被测包在同一个 .go 文件或同目录 _test.go
Example 函数必须和它演示的类型/函数处在同一包内。如果你的包叫 urlparse，那么 ExampleParseURL 必须定义在 urlparse/urlparse.go 或 urlparse/urlparse_example_test.go 中，不能放在其他包路径下——否则 go doc 找不到，go test 也不执行。
- 推荐拆到单独文件：命名如
urlparse_example_test.go，开头仍是package urlparse - 别写成
package urlparse_test（那是外部测试包，Example 不生效） - 如果函数依赖私有字段或方法，就只能放在主包文件里，不能挪去外部测试包
运行和验证：用 go test -run ^Example + go doc
写完别只信编辑器高亮——得真跑起来。默认 go test 不执行 Example，必须显式指定；而文档是否挂载，得靠 go doc 实时看。
立即学习“go语言免费学习笔记（深入）”；
- 运行示例测试：
go test -run ^Example$（^Example$确保只匹配函数名，避免误触ExampleXXXHelper） - 查看文档效果：
go doc urlparse.ParseURL，底下会出现Examples:小节 - Web 查看：
godoc -http=:6060启服务后浏览器打开，效果更直观 - 注意：修改 Example 后，
go doc不自动刷新，需重启 godoc 或清缓存（实际中常被忽略）
go test 就失败，go doc 就不展示。这点和普通测试完全不同，也最容易在 CI 里突然爆出来。 
