go module tag必须严格为vx.y.z格式，如v1.2.3；v开头、点分三段数字，预发布用v1.2.3-beta.1；非标准命名如1.0.0或foo-v1.2.3将不被go list或go get识别。

Go module 的 tag 命名必须严格遵循 vX.Y.Z 格式

Go 的 go get 和 go list -m -versions 依赖语义化版本字符串解析，任何偏差都会导致模块不可见或版本排序错乱。比如 v1.0.0-rc1、1.0.0、ver1.0.0 都不会被识别为有效版本。

• 正确写法只有：v0.1.0、v1.2.3、v2.0.0（注意 v 开头 + 点分三段）
• 预发布版本需用连字符加标识符，如：v1.2.3-beta.1，但必须仍以 vX.Y.Z 开头
• 如果用了 git tag foo-v1.2.3 这类非标准命名，go list -m -versions 就查不到它

提交前必须运行 go mod tidy 并提交 go.mod 和 go.sum

模块消费者依赖 go.mod 中的 module 路径和 require 声明来解析依赖图；go.sum 则用于校验下载内容完整性。漏掉任一文件，下游 go build 可能失败或引入不一致依赖。

Golang Samber Hot

在 Golang 中使用 samber/hot 进行内存缓存，支持 LRU、LFU、TinyLFU、W‑TinyLFU、S3FIFO、ARC、TwoQueue、SIEVE、FIFO 等淘汰算法，提供 TTL、缓存加载器及分片功能。

下载

• go mod tidy 后检查：所有 require 行是否都带版本号（无 // indirect 污染主依赖）、replace 是否已清理（发布版严禁本地替换）
• go.sum 必须与 go.mod 一起提交，否则 CI 或他人构建时会因校验失败退出
• 若模块含 //go:embed 或 cgo，还需确认 go.mod 中 go 版本声明（如 go 1.21）与实际兼容

发布日志应直接写在 Git tag 的 annotated message 里，而非仅靠 GitHub Release

go list -m -versions -json 和 go doc 不读 GitHub API，只认 Git 元数据。用户执行 go get example.com/foo@v1.2.3 时，Go 工具链完全不访问 GitHub 页面——它只 clone 仓库、检出 tag、读 go.mod。

• 用 git tag -a v1.2.3 -m "feat: add JSON marshal option\n\nBREAKING: Default output format changed" 写入结构化变更说明
• 避免空 message 或只写 release v1.2.3——这会让 go list -m -versions -json 返回的 Time 字段有值，但 Version 对应的描述为空
• GitHub Release 是补充，不是替代；自动同步工具（如 goreleaser）也应配置为将 tag message 作为 release body

通知协作者时，重点标注 go.mod 路径变更与 major version bump

Go 模块路径即导入路径，一旦修改（如从 github.com/a/foo 改为 example.com/foo/v2），所有调用方必须同步更新 import 语句。major 版本升级（v1 → v2）还强制要求路径末尾加 /v2，这是 Go 的硬性约定。

• 路径变更必须同步更新 go.mod 第一行 module 声明，并确保所有内部 import 引用新路径
• v2+ 版本发布后，旧路径（如 github.com/a/foo）仍可被 go get，但不会自动升级到 v2 —— 它被视为完全独立模块
• 邮件/群通知里，第一行就该写清：⚠️ Breaking: module path changed to <code>example.com/foo/v2 — update imports and go.mod

真正的麻烦往往藏在 go.mod 路径和 tag 名字的细微拼写里，而不是日志写多长。

golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！