Go包名须小写且与目录名、import路径严格一致；导出符号靠首字母大写但需按需暴露；优先用窄接口解耦，结构体不导出，构造函数用NewXXX+选项模式。
包名必须小写且与目录名一致
Go 语言强制要求包名是合法的标识符，且惯例全部小写；更重要的是，go build 和 go test 会默认将当前目录名作为包名。如果目录叫 utils，但包声明写成 package helper，会导致编译失败或导入路径错乱。
常见错误现象：cannot load utils: malformed module path "utils": missing dot in first path element（实际多因 go.mod 路径或 import 路径不匹配引发）。
- 包声明语句
package utils必须出现在每个.go文件顶部 - 目录名、
package声明、import路径三者要对齐：比如github.com/you/project/utils目录下只能有package utils - 避免使用
util这种易冲突的通用名，优先选语义明确的如httpx、strx、timeutil
导出符号靠首字母大写，但别盲目全大写
Go 没有 public/private 关键字，是否可被外部包访问，只取决于标识符首字母是否为大写。但「可导出」不等于「应导出」——结构体字段、函数、常量都得按需暴露。
典型误用：把一个内部配置结构体的所有字段都大写，导致调用方直接修改 Config.Timeout，破坏封装性。
立即学习“go语言免费学习笔记（深入）”；
- 结构体字段想只读？用小写字段 + 大写 Getter 方法：
timeout int配Timeout() time.Duration - 工具函数若只在包内复用，一律小写命名，如
parseURL、isValidEmail - 常量若仅本包使用，也小写：
defaultRetries = 3；对外提供才用DefaultRetries
用接口解耦依赖，避免结构体暴露过多细节
封装公共方法时，与其让外部直接操作某个结构体实例，不如定义窄接口，只暴露必要行为。这样既控制了调用方式，又便于后期替换实现（比如从内存缓存换成 Redis）。
例如，你写了 Cache 结构体，但不应让使用者 new 出来并调用 c.Set(...) 和 c.mux.Lock() —— 后者明显破坏封装。
type Cache interface {
Get(key string) (interface{}, bool)
Set(key string, value interface{}, ttl time.Duration)
}
// 内部实现可隐藏 sync.RWMutex、map 等细节
type memoryCache struct {
mu sync.RWMutex
data map[string]cacheItem
}
func NewCache() Cache {
return &memoryCache{data: make(map[string]cacheItem)}
}
- 接口定义放在使用者所在的包更合理（即调用方定义
Cache），或至少和使用者强相关；不要把所有接口堆在utils包里 - 避免定义过宽接口（如
type Service interface { Do() error; Undo() error; Reset() error }），按场景拆分 - 结构体本身尽量不导出（小写类型名），只导出构造函数和接口
init() 不适合做包级初始化，用 NewXXX() 显式构造
很多新手喜欢在 utils 包里写 func init() { defaultClient = &http.Client{...} }，看似方便，实则埋雷：无法定制参数、难以 mock 测试、并发初始化风险、违反依赖显式传递原则。
真正安全的做法是把状态封装进结构体，用工厂函数返回实例。
type HTTPClient struct {
client *http.Client
baseURL string
}
func NewHTTPClient(opts ...HTTPClientOption) *HTTPClient {
c := &HTTPClient{
client: &http.Client{},
}
for _, opt := range opts {
opt(c)
}
return c
}
type HTTPClientOption func(*HTTPClient)
func WithBaseURL(url string) HTTPClientOption {
return func(c *HTTPClient) {
c.baseURL = url
}
}
- 永远不要在公共包里用
init()初始化可变状态（如全局 client、logger、DB 连接） - 构造函数名统一用
NewXXX，避免Create、Build等不一致命名 - 需要可选配置时，用函数式选项模式（Functional Options），比 struct 参数更向前兼容
