Golang package命名规范与常见误区

Go包名须全小写、无特殊字符，main包仅用于可执行程序，禁用预声明标识符，推荐目录名与包名一致。

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，就足够清晰。