go mod init 必须在空目录下执行，模块名决定后续所有 import 路径；模块名不是项目文件夹名，而是他人 import 时的前缀，如 go mod init github.com/yourname/myapp，则 import 必须写 github.com/yourname/myapp/internal/handler，否则报错。
go mod init 必须在空目录下执行，模块名决定后续所有 import 路径
模块名不是项目文件夹名，而是别人将来 import 你代码时写的前缀。比如执行 go mod init github.com/yourname/myapp，那你在 internal/handler 里写 import "github.com/yourname/myapp/internal/handler" 才能被正确解析。
常见错误现象：go: cannot find main module 或 no required module provides package，基本都是因为当前目录已有残留的 go.mod、路径含空格、或模块名和实际 import 语句不一致。
- 模块名不能含大写字母、下划线或空格；推荐用小写字母 + 连字符，如
example.com/my-api - 别用
go mod init后直接删掉go.mod再重试——Go 不会自动清理缓存，容易卡在旧解析状态 - 如果只是本地练手，
go mod init myapp可行，但一旦要加子包（如pkg/utils），就必须用完整路径，否则import "myapp/pkg/utils"会被 Go 当作标准库外的未知路径处理
手动建目录比模板工具更可靠，关键结构就这四层
不需要 boilr 或 gox，90% 的项目靠 mkdir -p 一行搞定。真正影响协作效率的不是目录多深，而是哪层放什么、谁可以 import 谁。
-
cmd/：只放main.go，每个可执行文件一个子目录（如cmd/api、cmd/cli） -
internal/：业务逻辑全在这，外部无法 import —— Go 会报错，这是语言级封装 -
pkg/：放真正可复用的工具函数，比如pkg/httpclient、pkg/uuid，别人能import且不依赖你项目其他部分 -
configs/和api/：按需添加，不强制，但建议早建，避免后期重构时配置散落在main.go里
示例命令：mkdir -p cmd/myapp internal/handler internal/service pkg/utils configs
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
go mod tidy 不是“装依赖”，而是校验 import 与 go.mod 是否闭环
go mod tidy 的作用不是帮你“下载包”，而是检查：代码里 import 的每个路径，是否都在 go.mod 的 require 行里声明了；反过来，go.mod 里多余的 require 行，也会被删掉。
- 必须先写好
import语句，再跑go mod tidy—— 它不会猜你要用啥 - 如果
go mod tidy报require github.com/some/lib: version "v1.2.0" invalid，大概率是你代码里写了import "github.com/some/lib"，但该模块没发布 v1.2.0 版本，或你本地 GOPROXY 配置异常 -
go.sum必须提交 Git，删了会导致 CI 构建失败；它不是日志，是每个依赖包的 checksum 记录
验证项目结构是否真就绪，只看这三个命令输出
能 go run main.go 成功，不代表结构干净。真正的验证点很窄，但很硬：
-
go list ./...应列出所有子包，不含error或no Go files -
go list -m all输出第一行必须是你自己的模块路径，后面跟着标准库和显式依赖，不能有重复或路径错乱 -
go build ./cmd/myapp（假设你的主程序在cmd/myapp）成功生成二进制，且./myapp能运行 —— 这说明internal和pkg的 import 路径全通
最容易被忽略的是 internal 包的导入路径拼写：少一个斜杠、多一个点、大小写混用，都会导致编译失败，而错误信息往往只报 cannot find package，不提示具体哪一行 import 错了。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
