-
Go build 报头文件找不到时，不要先盲目改路径。按 CGO_ENABLED、CC/CXX、头文件搜索路径和 pkg-config 四层检查，通常可以快速定位 cgo 构建边界。
-
Go io.Pipe 适合把边生成的数据直接接到 HTTP 上传请求。本文用 multipart 示例说明读写两端、Close 与 CloseWithError、请求取消和 goroutine 收尾，并列出 Content-Length、重试与可重复读取的边界。
-
Go 遇到 import cycle not allowed 时，关键不是搬文件，而是拆开包依赖环。本文用 checkout、payment 和 PaymentGateway 示例说明接口归属、隐式实现、组合根注入及 go list 排查方法。
-
用 Go io.MultiWriter 将同一份输入同时写入文件和 SHA-256 摘要，理解顺序写入、短写、错误中断与临时文件提交，避免文件和校验值不一致。
-
Go 中目录名与 package 名不一致通常不会直接导致 import 失败：import path 负责定位目录，package 声明决定默认调用前缀。本文用最小结构拆解 undefined、路径错误和同目录多包名问题，并给出显式别名与 go list 排查方法。
-
io.LimitReader 限制的是包装 Reader 在整个读取过程中的最大字节数，不是每次 Read 的缓冲区大小。本文用原创 Go 示例说明如何设置上限、正确处理 n 与 io.EOF，以及如何用 limit+1 判断源内容是否超限。
-
Go 项目已经生成 vendor，编译却仍访问模块代理，通常不是 vendor 目录失效，而是 -mod 参数、GOFLAGS、go.mod 版本门槛或 vendor/modules.txt 不一致。本文按检查顺序给出定位和修复方法。
-
Go mod tidy 移除本地 replace 依赖，通常不是本地模块不支持，而是 replace 没有对应 require、模块路径不匹配或代码已不再导入。本文用模块图、go.mod 边界和 tidy -diff 给出排查与修复方法。
-
Go strings.Builder 的 String 方法返回当前累计内容，后续 Write 是继续修改 Builder，而不是直接修改已经得到的 string。文章解释 Builder 缓冲区与字符串值的边界，并给出单一所有者、禁止复制非零 Builder、并发隔离和按需 strings.Clone 的处理方式。
-
Go mod tidy 后出现 // indirect 不一定是多余依赖。本文从传递依赖、测试与构建条件三个入口排查来源，并用 go mod why、go mod graph 和 -diff 安全确认是否应该保留。
-
用 Go 的 bytes.Buffer 拼接多段二进制数据时，可以预留容量、连续 Write，并在结果消费或复制后 Reset 复用。本文重点说明 Bytes 的别名生命周期和安全边界。
-
Go 的 json.UnmarshalJSON 只负责输入解析，不能改变 omitempty 的输出规则。默认 encoding/json 中，零值结构体仍是可编码对象；要隐藏可选嵌套对象，应使用 nil 指针，并按接口契约区分缺失、空对象和显式零值。
-
Go 处理事件 JSON 时，json.RawMessage 适合保留结构可变或低频使用的 payload，先读取 kind，再按分支解码到具体结构体，避免 map[string]any 带来的类型丢失。
-
讲清 Go time.Timer Reset 返回值的真实含义，比较 Go 1.23 前后的通道语义，并给出单 goroutine、旧版本排空和发布检查的实用写法。
-
Go 实现 UnmarshalJSON 时直接调用 json.Unmarshal 会递归。本文用定义类型切断方法集，再补上错误处理、业务校验和嵌套字段边界。
