Go模块根目录必须含go.mod文件，否则无法被识别和导入；包与目录一一对应，main包不可被导入；internal/限本模块访问，资源需用embed.FS嵌入。
Go 包的根目录必须包含 go.mod 文件
没有 go.mod 的目录，即使有 .go 文件，go build 或 go test 也不会将其识别为一个模块（module），进而无法被其他包正确导入。Go 1.11+ 默认启用 module 模式，强制要求模块根目录存在 go.mod。
常见错误现象：cannot find module providing package xxx，往往是因为当前工作目录不在模块根下，或 go.mod 缺失/路径错误。
-
go mod init example.com/mylib是初始化模块的起点，模块路径应与未来导入路径一致 - 模块路径不强制对应真实域名，但需全局唯一；本地开发可用
local/myproject，但发布到 GitHub 应设为github.com/user/repo - 子目录不是子模块——除非该子目录自己也有
go.mod，否则它只是主模块内的普通包路径
每个 Go 包对应一个独立目录，且只含一个 package 声明
Go 不允许单个目录下混用多个 package 名（比如同时存在 package main 和 package utils 的文件）。目录名通常（但不强制）与 package 名一致，这是约定而非语法要求。
使用场景：当你想把一组功能拆成逻辑包时，就新建目录，放入 xxx.go 并统一声明 package xxx。
立即学习“go语言免费学习笔记（深入）”；
- 目录名
httpclient下所有文件都应以package httpclient开头 - 测试文件（
*_test.go）可属于同一包（同名package httpclient），也可定义为package httpclient_test（用于黑盒测试，仅能访问导出符号） - 避免目录名含短横线（
-）或大写字母——虽然文件系统允许，但会干扰go get解析和工具链识别
main 包必须放在模块根目录或其子目录中，且不能被其他包 import
main 包是可执行程序入口，Go 规定它不能被任何外部包导入。如果误将 main 包放在某个子目录（如 cmd/myapp），而其他包试图 import "example.com/mylib/cmd/myapp"，编译会报错：cannot import "example.com/mylib/cmd/myapp" because it is not a package（实际错误信息更接近 can't load package: package ... is not inside a module 或直接拒绝导入 main）。
- 推荐把可执行入口放在
cmd/xxx目录下，每个cmd/xxx是一个独立main包，对应一个二进制 -
internal/目录下的包只能被同一模块内顶层包导入，适合放私有共享逻辑；而main包本身不参与导入图，所以放哪都行，只要不被 import - 若项目只有一个命令，也建议仍用
cmd/app而非模块根目录放main.go，利于未来扩展多命令
测试、文档与构建辅助文件的存放位置有隐含惯例
Go 工具链（go test、go doc、go generate）依赖文件位置和命名推断意图。不按惯例组织，会导致命令失效或文档不可见。
-
_test.go文件必须与被测包同目录（白盒测试）或以${pkgname}_test包名放在同目录（黑盒测试） -
doc.go若存在，需放在包目录下，且含// Package xxx ...注释，才能被go doc正确提取包级说明 -
go:generate注释写在任意.go文件中均可，但生成的文件（如zz_generated.go）惯例放在同目录，并加// Code generated...头注释 -
配置文件（如
config.yaml）、静态资源（templates/）不属于 Go 包结构，应放在assets/或internal/assets/，并通过embed.FS加载，而非硬编码相对路径
最易被忽略的是 internal/ 和 embed.FS 的配合使用——很多人把模板直接放根目录，结果 go build -o bin/app 后运行时报 “file not found”，其实问题不在包结构，而在资源未嵌入二进制。
