package 名必须全小写且不含特殊字符
Go 语言强制要求 package 声明中的名称只能由 ASCII 小写字母、数字和下划线组成，不能有大写字母、连字符（-）、点号（.）或空格。这是编译器硬性限制，不是风格建议。
常见错误包括：
- 用
my-package（含连字符）—— 编译报错：syntax Error: unexpected - - 用
MyUtils（含大写）—— 编译通过但违反约定，且可能被工具链（如go list、gopls）误判为非标准包 - 用
v2作包名（如package v2）—— 合法但极不推荐：它无法表达语义，且与模块版本路径（如github.com/x/y/v2）混淆
正确做法是选一个简短、可读、能体现职责的纯小写名，例如：httpclient、store、cli、metrics。
main 包名必须是 main，且仅用于可执行程序
package main 是 Go 的入口标识，只有包含该声明且定义了 func main() 的目录才能被 go build 编译成二进制。它不是“主逻辑包”的代称，而是一个严格语义标记。
立即学习“go语言免费学习笔记（深入）”；
容易踩的坑：
- 在库项目中误建
cmd/xxx/main.go以外的package main文件—— 导致go list ./...报错或测试失败 - 把通用工具函数放在
main包里，结果其他包无法导入—— 正确做法是将可复用逻辑拆到独立包（如pkg/utils），只在main中做调度 - 多个
main包共存于同一模块根目录——go build默认构建第一个找到的main，行为不可控
典型结构应为：
myapp/ ├── cmd/myapp/ │ └── main.go // package main ├── internal/server/ // package server └── pkg/config/ // package config避免使用 go、nil、true 等预声明标识符作包名
虽然 Go 不禁止你写 package nil 或 package type，但会导致后续代码无法正常使用这些关键字，编译器会报类似 nil is not a type 或 cannot use type as value 的错误。
这类命名冲突往往在跨包引用时才暴露，排查成本高。已被明确列入 Go 规范文档 的预声明标识符包括：
- 关键字：
func、var、const、type、if、for等 - 内置常量：
true、false、nil - 内置类型：
int、String、error、any、comparable - 内置函数：
len、cap、append、copy、panic等
哪怕只是临时测试，也别用 package map 或 package make —— 它们会让 import "map" 后所有对 map 类型的使用失效。
包名 ≠ 目录名，但强烈建议保持一致
Go 允许 package 声明与所在目录名不同，比如目录叫 http_handlers 却写 package handler。但这会破坏工具链直觉，造成几个实际问题：
-
go doc和 ide 跳转可能失效或指向错误位置 -
go list -f '{{.Name}}' ./http_handlers返回handler，但开发者预期是http_handlers - 团队新人看到目录名
db却发现里面是package storage，需要额外认知负担
唯一合理例外是 main 包：目录名通常反映二进制名（如 cmd/apid），但包名固定为 main。除此之外，坚持「目录名即包名」是最省心的选择。
特别注意：包名不体现路径层级。不要因为路径是 github.com/org/proj/internal/auth/jwt 就取包名 auth_jwt —— 只要该目录下所有文件都声明 package jwt，就足够清晰。