go-naming

Go 命名约定

资源路由

• scripts/check-naming.sh - 检查 SCREAMING_SNAKE_CASE 常量、以 Get 开头的 getter、通用包名，或名为 this/self 的接收者时运行。
• references/IDENTIFIERS.md - 选择首字母缩写词、导出标识符或包级符号的名称时阅读。
• references/REPETITION.md - 名称与包、接收者、类型或局部上下文重复时阅读。
• references/VARIABLES.md - 选择局部变量名、接收者名或循环标识符时阅读。

核心原则

命名应当：

• 在使用时不显得重复
• 考虑上下文
• 不重复已经明确的概念

命名更像艺术而非科学——Go 中的名称往往比其他语言中的更短。

---

命名决策流程

What are you naming?
├─ Package       → Short, lowercase, singular noun (no underscores, no mixedCaps)
├─ Interface     → Method name + "-er" suffix when single-method (Reader, Writer)
├─ Receiver      → 1-2 letter abbreviation of type (c for Client); consistent across methods
├─ Constant      → MixedCaps; use iota for enums; no ALL_CAPS
├─ Exported func → Verb or verb-phrase in MixedCaps; no Get prefix for getters
├─ Variable      → Length proportional to scope distance
│                  ├─ Tiny scope (1-7 lines) → single letter (i, n, r)
│                  ├─ Medium scope           → short word (count, buf)
│                  └─ Package-level / wide   → descriptive (userAccountCount)
└─ Any name      → Check: does it repeat package name or context? If yes, shorten it

---

MixedCaps（必需）

规范性要求：所有 Go 标识符都必须使用 MixedCaps。

仅允许在以下情况使用下划线：测试函数（TestFoo_InvalidInput）、生成的代码，以及 OS/cgo 互操作。

---

包名

规范性要求：包名必须全部小写，且不含下划线。

使用简短、小写的单数名词。避免使用 util、common、helper 等通用名称——应优先使用具体名称：stringutil、httpauth、configloader。

// Good: user, oauth2, tabwriter
// Bad:  user_service, UserService, count (shadows var)

---

接口名称

建议：单方法接口使用“-er”后缀。

单方法接口以方法名加上 -er 命名：Reader、Writer、Formatter。遵循规范的方法名（Read、Write、Close、String）及其签名。

---

接收者名称

规范性要求：接收者必须使用简短的缩写，并保持一致。

使用一个或两个字母缩写类型，并在所有方法中保持一致： func (c *Client) Connect()、func (c *Client) Send()。 切勿使用 this 或 self。

---

常量名称

规范性要求：常量使用 MixedCaps，绝不使用全大写或 K 前缀。

根据常量的作用而非值命名：使用 MaxRetries，而不是 Three；使用 DefaultPort，而不是 Port8080。

const MaxPacketSize = 512
const defaultTimeout = 30 * time.Second

---

首字母缩写词和首字母缩略词

规范性要求：首字母缩写词的大小写必须保持一致。

首字母缩写词（URL、ID、HTTP、API）必须全部大写或全部小写： HTTPClient、userID、ParseURL()，而不是 HttpClient、orderId、ParseUrl()。

---

函数和方法名称

建议：简单访问器不要使用 Get 前缀；操作应使用动词式名称。

字段 owner 的 getter 应命名为 Owner()，而不是 GetOwner()。setter 应命名为 SetOwner()。对于开销较大的操作，使用 Compute 或 Fetch。

函数仅类型不同时，在名称末尾注明类型： ParseInt()、ParseInt64()。

---

变量名称

变量命名需要兼顾简洁与清晰。关键原则：

• 根据作用域确定长度：小作用域使用短名称（i、v）；大作用域使用更长、更具描述性的名称
• 单字母命名惯例：采用常见模式（索引使用 i，reader/writer 使用 r/w）
• 避免在名称中包含类型：使用 users 而不是 userSlice，使用 name 而不是 nameString
• 为未导出的全局变量添加前缀：包级未导出变量/常量使用 _ 前缀，以避免遮蔽

for i, v := range items { ... }           // small scope
pendingOrders := filterPending(orders)    // larger scope
const _defaultPort = 8080                 // unexported global

---

避免重复

Go 名称在使用时不应显得重复。请考虑完整上下文：

• 包 + 符号：使用 widget.New()，而不是 widget.NewWidget()
• 接收者 + 方法：使用 p.Name()，而不是 p.ProjectName()
• 上下文 + 类型：在包 sqldb 中使用 Connection，而不是 DBConnection

---

避免使用内置名称

绝不要将 Go 的预声明标识符（error、string、len、cap、 append、copy、new、make 等）用作变量名、参数名或类型名。

详细指南：请参阅 go-declarations 中的“避免使用内置名称”部分。

---

快速参考

元素	规则	示例
包	使用小写字母，不含下划线	package httputil
导出标识符	使用混合大小写，以大写字母开头	func ParseURL()
未导出标识符	使用混合大小写，以小写字母开头	func parseURL()
接收者	使用 1-2 个字母的缩写	func (c *Client)
常量	使用混合大小写，绝不使用全大写	const MaxSize = 100
首字母缩写	大小写保持一致	userID、XMLAPI
变量	长度与作用域大小大致相称	i（作用域小）、userCount（作用域大）
内置名称	绝不遮蔽预声明标识符	参见 go-declarations

验证：重命名标识符后，运行 bash scripts/check-naming.sh，确认不再存在命名反模式。然后运行 go build ./...，确认重命名没有造成问题。

相关技能

• 接口命名：为接口添加 -er 后缀或选择接收者类型时，请参见 go-interfaces
• 包命名：为包命名、避免使用 util/common 或解决导入冲突时，请参见 go-packages
• 错误命名：为哨兵错误（ErrFoo）或自定义错误类型命名时，请参见 go-error-handling
• 声明作用域：变量名长度取决于作用域，或需要避免遮蔽内置名称时，请参见 go-declarations
• 风格原则：在标识符名称的清晰度与简洁性之间取得平衡时，请参见 go-style-core