2026-07-10

今日主题

• go build 参数解析与产出规则
• Go 语义化版本导入（v2+）
• git rebase 起点语义
• 代码骨架清理与文档定位
• go 命令族远程寻址与仓库组织
• ingress 层次与工作负载身份
• ingress 扩展：annotation vs CRD
• 分布式配置自保护模式
• Go Vanity Import 与 Cloudflare 中转
• Elm 的无运行时异常保障机制

新增认知

go build 参数解析与产出规则

• Go 参数只有两类，产出取决于是否 main 包：go build 只接受两种参数形式——import path（含目录路径，
  如 ./cmd、./...）和具体 .go 文件列表（如 main.go util.go）。是否产出二进制文件，
  唯一判定标准是解析出的包是否为 package main 且含 func main()；文件列表形式下即使是非 main 包也不会报错，
  只是不产出文件（真正报错的场景是文件列表混入了不同 package）。

• 产出文件命名 = import path 最后一段，非目录名：
  源码 cmd/go/internal/load/pkg.go 的 exeFromImportPath() 显示，
  import path 形式的默认命名取的是完整 import path（module 名 + 相对路径）的最后一段，不是磁盘目录名；
  两者通常一致只是约定俗成的巧合（可实测验证：目录名与 go.mod 里 module 名故意不同时，产物按 module 名生成）。
  文件列表形式则取命令行参数中第一个 .go 文件名（按传参顺序，非字典序）。

• 排错时不要被 GOROOT/src 路径迷惑：
  go build 报错信息里出现的 .../go/x.y.z/src/ 路径只是 Go 兜底列出的候选查找路径之一，
  不代表工具链退化成了 GOPATH 模式；实际 module 解析可能完全正确，
  真正原因需要用 go list 直接验证目录是否存在，避免被报错格式误导为版本/模式配置问题。

• module 解析靠向上遍历 go.mod，非当前目录硬绑定：go build 会从当前工作目录开始逐级向上查找 go.mod，
  找到的第一个即为 module 根；之后所有 import path 都基于这个 module 名解析，
  因此仓库内任意子目录执行 go build 都能正确工作，无需 cd 到根目录。

Go 语义化版本导入（v2+）

• v2+ 版本必须改 import path，不只是改 tag：Go 用语义化版本管理依赖，规定主版本升到 v2 及以上时，
  module path 本身必须带 /v2、/v3 后缀（如 example.com/mymodule/v2），前提是 v1/v0 不需要后缀。
  这是 Go 特有的设计——目的是让不同主版本在 Go 看来是完全不同的包（import path 不同），从而允许同一项目里共存新旧版本，
  且升级必须显式修改 import 语句，避免破坏性变更被隐式引入。

• v2 目录是约定而非强制，仓库地址由 go.mod 内容决定：很多 v2 库仓库地址不变，只改 go.mod 里的 module 声明这一行字符串，
  磁盘上并不存在真实的 v2/ 子目录；只有当项目需要在同一仓库里同时维护 v1、v2 两套可用代码时，
  才会用真实的 v2/ 子目录物理隔离（Go 官方文档明确推荐前者，避免用目录路径承载版本号）。

• go get 定位 v2 包靠 tag 匹配 + 读 go.mod 二次确认，不猜目录：
  go get 解析 github.com/user/repo/v2 时，
  先反复剥离末尾段尝试匹配真实存在的仓库地址（如剥掉 /v2 后能定位到 github.com/user/repo），
  再去该仓库的 Git tag 里找匹配版本号的 tag，下载后读取那个版本快照里的 go.mod 的 module 声明字符串，
  确认是否与 import 路径完全一致——是否存在 v2/ 子目录只是这个确认过程顺带识别的结果，不是判断依据本身。

• 可执行文件默认命名会跳过纯版本号段：exeFromImportPath() 对纯版本号格式的最后一段（v2、v3...）做了特殊处理，
  会跳过它改用倒数第二段命名，避免产出叫 v2 这种无意义的可执行文件名；
  但 v1 不算版本号后缀（因为 v1 允许不写、只是恰好目录/包名叫 v1 的普通名字），所以 mycmd/v1 产出的默认命名反而是 v1 本身。

git rebase 起点语义

• git rebase 起点是开区间：git rebase -i <起点> 重放的是起点之后（不含起点）的提交。这意味着根提交没有父提交，
  HEAD~N 无法到达根提交之前，必须用 --root 让 Git 从第一个提交开始。同理，
  git rebase -i HEAD~3 只重放最近 3 个提交，不包含 HEAD~3 自身。

代码骨架清理与文档定位

• 骨架清理先删被依赖方：从旧项目 CV 过来的代码库，清理业务痕迹时，必须先删被依赖的核心包（chunker/rrf/models/auth），
  再删上层 Service/Handler/路由，最后改配置和文档。如果反过来删，上层代码引用已删除的包会导致编译失败，中间态不可验证。
  步骤 1-7 允许合并为 1-2 个原子提交。

• PRD 是唯一事实源，文档不应降级：代码可以处于骨架搭建阶段用 Foo 示例占位，
  但 README/AGENTS.md 的定位描述应始终指向 PRD 描述的产品终态（如源码侦察兵），而不是写成业务无关全栈骨架。
  上一轮清理时误把 PRD 文档标了废弃，导致文档与代码骨架互指对方为真相，需要修正回来。

go 命令族远程寻址与仓库组织

• 脉络：四个命令共享寻址逻辑，分工在于产物去向：
  go get/build/run/install 在远程 module 场景下都用同一套 import path 寻址机制定位代码，区别只在拿到代码后做什么——
  get 只改 go.mod/go.sum 版本记录不产出文件，build 编译验证/产出到当前目录，run 编译执行后自动清理不留痕迹，
  install 编译后安装到 $GOBIN 长期可用。理解这一点后，四个命令的选择就变成纯粹的'我要不要产物、产物放哪'的决策，而非需要分别记忆的四套规则。

• go get 职责在 1.17 收窄，不再产出可执行文件：Go 1.17 之前 go get 身兼下载依赖与编译安装可执行文件两职，
  等价于今天的 go install；1.17 起官方将其拆分，go get 现在只负责修改 go.mod/go.sum 里的版本号声明，不再产出任何二进制。
  若看到教程用 go get 安装 CLI 工具，那是过时用法，现在必须用 go install。

• import path 寻址是逐段回溯匹配仓库地址：
  Go 工具链解析远程 import path（如 github.com/user/repo/cmd/tool）时，从整体开始反复剥离末尾路径段，
  尝试匹配一个真实存在的版本控制仓库地址；匹配到仓库后，剩余路径段就是仓库内的相对目录。GitHub/GitLab/Bitbucket 等知名域名有内置识别规则，
  自定义域名（如公司内部 pkg.xxx.com/...）则靠请求 URL 加 ?go-get=1 参数、从返回 HTML 的 meta 标签里读取真实 VCS 地址（即 vanity import path 机制）。

• 默认经代理下载，不直连源仓库：
  go get/install 默认通过 GOPROXY（默认 proxy.golang.org）拉取已缓存的模块 zip 包，
  而非直接 git clone 源仓库，好处是加速下载并避免源仓库被删除后本地彻底失去访问；私有内部包通常会配置私有代理或 direct 模式跳过公共代理。

• 单仓库多 CLI 用 cmd/ 目录约定，非多 module：
  常见 CLI 仓库组织是一个 go.mod（一个 module）配合 cmd/prog1、cmd/prog2 等多个子目录各自放一个 package main，
  逐一 go install 会产出多个独立可执行文件。这样设计是为了让仓库根目录能留给可被外部当库导入的包（若根目录本身是 package main，
  其他项目 import 该仓库根路径会缺乏意义）。

• 多 module 仓库与多主版本共存是两个独立维度：
  多 module 仓库（每个子目录各自独立 go.mod、独立发版、Git tag 需带路径前缀）与同一 module 的多主版本共存（v2/v3 后缀，
  见此前 v2 相关认知）是正交的两个概念，可以叠加出现在同一仓库里；前者是横向拆分多个独立组件，后者是纵向的版本演进。
  Go 官方明确不推荐多 module 仓库模式，认为会显著增加维护复杂度，只在各组件版本节奏差异很大时才值得使用。

• 脉络：身份/地址/核验三层自洽闭环：Go module 寻址本质是三层分离的模型——import path 是身份（identity），
  go-import meta 第3段仓库 URL 是物理地址（location，可与身份不同），
  go.mod 的 module 声明是身份证核验（verification）。三层各司其职：身份声明我要什么包，meta 把身份映射到物理地址，
  go.mod 核验下载到的包自报身份是否与声明一致。这套分层让"包叫什么"和"包住哪"彻底解耦，是整个寻址链路自洽的根基。

• go-import 前缀与仓库地址可不同：go-import meta 三字段为 ，
  第1段（身份前缀）与第3段（真实仓库URL）允许不一致——
  这正是 vanity import path 的原理（自定义域名如 gorm.io/pkg.poizon.com 指向 GitHub 或自建 GitLab 等实际托管地）。
  前缀匹配是"包含"关系而非"完全相等"：gorm.io/gorm 的 prefix 能覆盖 gorm.io/gorm 及其子路径，
  这也解释了为何 gorm.io/driver/mysql 和 gorm.io/gorm 是同前缀下两个独立 module。

• go.mod module 声明须与 import path 严格一致：下载代码后 Go 会读 go.mod 第一行 module 声明，
  与 import path 做严格相等比较，
  不一致直接报错 module declares its path as X but was expected to be Y 终止。这是闭环的核验环节，
  防止仓库伪装成别的 module；方向是双向的——import 路径、go.mod 自报身份、go-import prefix 三者必须自洽，
  唯一可游离的是 go-import 第3段的物理仓库地址。

• 代理替做探测，直连与 GOPRIVATE 才自探测：走 GOPROXY 时代理已缓存模块 zip 并替你做了 ?go-get=1 探测，
  Go 直接下 zip、无需 git clone 也无需解析 meta，既快又防源仓库删除后失联；只有 direct 回退或 GOPRIVATE 命中时，
  Go 才自己做 vanity import path 探测并 git clone 真实仓库地址。GOPRIVATE 还会绕过代理与校验和检查，
  避免内部代码泄露给公共代理、也避免公共代理拿不到私有包而报错。

• go-source 标签仅供文档跳转：
  go-import 之外的第二个 meta 标签 go-source 声明的是目录/单行代码跳转 URL 模板（含 {/dir}{/file}#L{line} 占位符），
  供 IDE 和 go doc 工具点击 import 跳转到源码网页，不影响代码能否拉取；HTML body 里的 go get ... 文字也是给人看的提示，
  工具链完全忽略，解析时只读 head 里两个 meta 标签。

ingress 层次与工作负载身份

• 两层身份与 ordinal 复用：
  ingress 兼具声明数据（etcd 里的 CRD）和数据面工作负载（跑着的 controller Pod）两层身份，名字重用易混。
  Tengine-Ingress 把这两层绑在同一个 StatefulSet 上——配置灰度批次直接挂在 Pod ordinal（0..N-1）上，
  复用工作负载自身的有序性而非另起编排，回滚就是调小 index-id。精妙与局限同源：每个 Pod 都 watch 同一份 ingress 资源，
  配置 fan-out 随副本数线性增长，规模上限被这层耦合卡住。

• 声明走 svc 转发走 pod 直连：ingress controller 可绕过 svc 的 kube-proxy 转发，
  直接 watch 后端 pod 列表转发，省一跳 iptables/IPVS 且支持 Pod 级灰度切流。
  声明层（ingress YAML 写 svc name）保留 svc 抽象，数据面虚化 svc——这是 nginx-ingress 也有的常见优化，
  非 Tengine 独有。前置：ingress 规则后端必填 svc name，ingress 与 svc 是叠加非互斥，
  ingress 是站在 svc 肩上再加 L7 域名/TLS/路由。

ingress 扩展：annotation vs CRD

• annotation 扩张期赢精耕期输：Ingress-nginx 用 annotation 扩展，
  扩张期靠零迁移成本、零 CRD 管理、契合 nginx 配置心智模型，低门槛打赢 CRD 严谨；
  精耕期要做 per-path 限流+灰度+重写组合时三重代价暴露——
  类型全字符串无校验（kubectl apply 不拒非法值）、粒度挂 ingress 级撑不住 per-path 配置、前缀当伪命名空间多实现语义冲突靠隐式优先级。
  最后只能靠 configuration-snippet 塞裸 nginx.conf 逃出声明式体系。Gateway API 用 CRD 接班正是因此。

• Tengine-Ingress 是过渡期混合体：保留 annotation 兼容存量吃 Ingress-nginx 份额，
  同时新增 IngressCheckSum/SecretCheckSum 等 CRD 补强类型和跨对象聚合——
  踩在 annotation 低迁移成本上伸手够 CRD 表达力。这是兼容存量包袱下最务实的解，也最累：维护两套配置表达。
  今天重做 Gateway API 几乎肯定更干净。

分布式配置自保护模式

• 全局一致性校验+自保护：分布式环境 etcd/API server 不可用时会误触删除事件致客户端清空配置。
  Tengine-Ingress 用 MD5 对比 CRD IngressCheckSum 做全局一致性校验，校验失败进自保护——不更新本地缓存，
  继续用存量配置对外服务，保证存储态挂了运行态仍可服务。取舍是宁可旧配置也不信脏数据，代价是配置可能短暂滞后。适用任何控制面/配置中心高可用场景。

Go Vanity Import 与 Cloudflare 中转

• 脉络：从“能否用 Cloudflare 做 go-import 中转”出发，
  核心认知是 Go vanity import 本质上是 HTTP GET + HTML <meta name="go-import"> 解析——
  go get 对域名发请求，从返回的 HTML head 中提取 prefix vcs repo-root，然后 clone 真实仓库。
  Cloudflare Worker 恰好是这一机制的最小化实现：一个 fetch handler 返回带 meta 标签的 HTML 即可，
  零服务器、全球边缘、免费层级足够。

• go-import 是 HTTP 层面机制：Go vanity import 不依赖 DNS 或任何特殊协议，
  仅靠标准 HTTP GET + HTML head 中的 <meta name="go-import" content="prefix vcs repo-root"> 解析。
  这意味着任何能返回 HTML 的 HTTP 服务（Cloudflare Workers、GitHub Pages、Netlify redirect、甚至 Nginx 静态文件）都能充当 import 中转，
  且 HTML 中 meta 标签必须放在 head 靠前位置——Go 的受限解析器遇到 JS/CSS 可能提前终止。

• go-source 仅用于文档链接：<meta name="go-source"> 是独立的可选标签，
  告诉 pkg.go.dev 如何生成源码跳转链接，
  格式为 prefix repo-url {/dir}-template {/file}-{line}-template。
  不加它不影响 go get 功能，但在线文档页的“跳转到源码”链接会失效。

• Go 1.25 monorepo 子目录支持：
  go-import content 字段末尾可追加 subdirectory 路径（如 go.yourdomain.com/mod1 git github.com/you/mono go/mod1），
  Go 1.25+ 支持。这让 monorepo 中不同子目录的模块共享同一个 vanity domain + 同一个 repo root，
  由 subdirectory 区分实际路径。旧版 Go 会忽略该 meta 标签导致解析失败。

Elm 的无运行时异常保障机制

• 编译时证明替代运行时检查：Elm 消除运行时异常的核心设计哲学是把"可能出错的事"从运行时挪到编译时——编译器不通过，代码就跑不起来。
  这不是一个具体语法特性，而是 Maybe + Result + 穷尽模式匹配三个机制共同构成的类型安全体系。三者的因果关系是：
  Maybe/Result 定义了可能的值域，穷尽模式匹配强制执行所有值域都被覆盖的证明，合在一起编译器就能从类型上证明代码没有未处理的异常路径。

• Maybe 类型消除 null 引用错误：Elm 中不存在 null/undefined，
  任何可能缺失的值类型都是 Maybe a（Just a | Nothing）。编译器强制调用方必须同时处理有值和无值两种情况，
  使 NullPointerException 这类错误在编译期就被消除。与 Java Optional 原理相通但更彻底——
  Elm 里没有"绕过 Optional 直接取 null"的可能，因为语言层面根本不存在 null。

• 穷尽模式匹配提供编译期证明：对联合类型做 case 匹配时，编译器检查是否覆盖了所有可能分支，遗漏任何一个都会编译报错。这意味着只要代码编译通过，
  从类型上就能证明该处逻辑没有遗漏——不是"测试覆盖了"，而是"不可能遗漏"。这是 Maybe/Result 得以生效的技术基础：没有穷尽检查，
  Maybe 就只是建议性的包装，无法保证安全。