命名规则¶
九大命名规则¶
以下是 九大通用的良好命名规则，可用于 API 方法、函数或服务，确保清晰、可维护且易理解。
1. 清晰表达功能变化¶
当新方法基于旧方法但增加了功能时，常见的命名方式：
GetXWithY（如GetAccountWithCache） → 表达 在原功能上增加了新特性GetXIfY（如GetAccountIfCached） → 适合 条件式逻辑TryGetX（如TryGetAccount） → 适合 尝试获取，可能失败EnsureX（如EnsureAccountLoaded） → 适合 保证数据存在XOrY（如GetAccountOrNull）→ 明确返回可能类型XWithY→ 新增参数时可扩展（如GetAccountWithOptions）XAsync→ 明确异步方法（如GetAccountAsync）XIfY→ 可组合条件（如GetAccountIfActive）XNoY→ 显式声明功能剥离（如GetAccountNoValidation）AddYToGetX（如AddCacheToGetAccount）→ 表示在原功能基础上添加了 额外的功能，像是添加缓存机制。GetXPlusY（如GetAccountPlusBalance）→ 表示获取的数据是 多个相关信息的组合，例如账户信息和余额信息。GetXIncludingY（如GetAccountIncludingTransactions）→ 表示获取的数据 包含特定的附加信息或子集，如账户信息包含交易记录。
2. 以数据来源区分¶
适用于有多个获取途径的情况：
GetXFromCache/GetXFromDB（如GetAccountFromCache） → 明确来源LoadX（如LoadAccount） → 适合从缓存或数据库加载数据FetchX（如FetchAccount） → 适合表示 可能从远程/缓存获取RetrieveX（如RetrieveAccount） → 泛化的 数据检索 方法ReadX→ 强调无副作用读取（如ReadAccountConfig）StreamX→ 流式获取（如StreamAccountLogs）QueryX→ 强调复杂查询（如QueryActiveAccounts）PullX→ 主动拉取远程数据（如PullLatestAccount）SyncX→ 同步本地与远程状态（如SyncAccountToCloud）GetXFromRemote（如GetAccountFromRemoteServer）→ 用于表示从 远程服务器 获取数据，区别于本地缓存或其他本地存储的数据源。RefreshX（如RefreshAccountData）→ 表示 强制从源系统获取最新数据，而不是使用缓存版本。StreamX（如StreamAccountUpdates）→ 适用于从 数据流 中获取或推送数据。
3. 版本迭代¶
适用于 升级替换旧版本：
Xv2/XV2（如GetAccountV2） → 常见但不推荐 滥用XEnhanced（如GetAccountEnhanced） → 表达增强版本XOptimized（如GetAccountOptimized） → 适用于优化性能的版本XDeprecated→ 显式标记弃用（如GetAccountDeprecated）XLegacy→ 旧版兼容方案（如GetAccountLegacy）XBy[条件]→ 参数化版本（如GetAccountByTimestamp）- 语义化版本 → 适用于服务（如
AccountServiceV1_2_0） NextX（如NextGenerationGetAccount）→ 表示这是一个 新一代的实现，可能包含多方面的改进，如性能、功能等。LegacyX（如LegacyGetAccount）→ 用于标记 旧版本或即将被淘汰的版本，以便于后续的维护和升级。BetaX（如BetaGetAccount）→ 表示这是 测试版或预发布版，功能可能尚未完全稳定。
4. 动作+对象¶
清晰表达 行为 + 作用对象：
FindX（如FindAccount） → 适合搜索/查找CheckX（如CheckAccountExists） → 适合 验证 逻辑CreateX/UpdateX/DeleteX（如CreateAccount） → 经典 CRUD 方式ComputeX（如ComputeAccountBalance） → 适合 计算结果AddX/RemoveX→ 集合操作（如AddAccountPermission）BeginX/EndX→ 事务操作（如BeginAccountTransaction）LockX/UnlockX→ 资源控制（如LockAccountEditing）ExportX/ImportX→ 数据迁移（如ExportAccountData）ValidateX→ 校验逻辑（如ValidateAccountEmail）GenerateX（如GenerateAccountReport）→ 表示 生成某种数据或报告，一般可能涉及计算或查询。TransformX（如TransformAccountDataForDisplay）→ 表示对数据进行 转换，可能用于适配不同的格式或系统要求。FilterX（如FilterAccountByStatus）→ 表示 根据特定条件筛选数据。
5. 条件性逻辑¶
当方法 可能返回不同结果：
TryX（如TryGetAccount） → 适合 失败时不抛异常EnsureX（如EnsureAccountLoaded） → 确保某状态达成MaybeX（如MaybeGetAccount） → 可能会返回，也可能不会XOrElse→ 提供备选方案（如GetAccountOrElseCreate）XOrDefault→ 返回默认值（如GetAccountOrDefault）XUnchecked→ 跳过验证（如DeleteAccountUnchecked）XSafely→ 强调安全操作（如UpdateAccountSafely）IsX（如IsAccountActive）→ 用于 判断某个条件是否成立，布尔值返回类型。ShouldX（如ShouldAccountBeDenied）→ 表示逻辑目的是 判断是否应该执行某个操作。DefaultX（如DefaultGetAccount）→ 表示使用 默认策略或配置 来执行操作。
6. 性能特征标记¶
XFast→ 性能优化版本（如SearchAccountsFast）XLazy→ 延迟加载（如LoadAccountLazy）XBatch→ 批量操作（如UpdateAccountsBatch）XCached→ 明确缓存策略（如GetOrdersCached）
7. 领域驱动设计(DDD)风格¶
RegisterX→ 领域事件（如RegisterAccountCreatedEvent）ApplyX→ 状态变更（如ApplyAccountDiscount）CalculateX→ 领域计算（如CalculateAccountRisk）EstimateX→ 预测性计算（如EstimateAccountGrowth）
8. 错误处理模式¶
XOrError→ 显式错误返回（如GetAccountOrError）XWithFallback→ 故障回退（如GetConfigWithFallback）XWithRetry→ 自动重试策略（如SendEmailWithRetry）XUnsafe→ 需调用方处理异常（如SaveAccountUnsafe）
9. 状态变更通知¶
OnX→ 事件监听（如OnAccountUpdated）NotifyX→ 主动通知（如NotifyAccountExpired）ObserveX→ 观察者模式（如ObserveAccountChanges）SubscribeX→ 订阅机制（如SubscribeAccountAlerts）
示例¶
已知现有一个接口名称叫 GetAccount 用户获取用户账户信息, 现在提供一个新接口，核心逻辑跟 GetAccount 一样，但增加了缓存功能，这个新接口如何命名？
GetAccount 新接口命名 场景决策树 如下：
┌──────────────┐
│ 需要新增功能？ │
└──────┬───────┘
▼
┌─────────────────┬──────┴───────┬──────────────────┐
▼ ▼ ▼ ▼
带缓存? 异步操作? 条件获取? 性能优化?
GetAccountWithCache GetAccountAsync GetAccountIfActive GetAccountOptimized
可以考虑以下命名方式：
推荐命名：
GetAccountWithCache（✅ 清晰表达增加了缓存功能）GetCachedAccount（✅ 直观表达“从缓存获取账户信息”）FetchAccount（✅ 可以表示“可能来自缓存”）RetrieveAccount（✅ 更泛化，适用于不同的数据源）
不太推荐的命名：
GetAccountV2❌（除非是 API 版本升级，否则 v2 容易引起困惑）GetAccountCached❌（读起来不太自然）GetAccountFromCache❌（容易误解为只从缓存获取，不走原始逻辑）
最佳选择：
- 如果想保持与原有命名一致，建议
GetAccountWithCache或GetCachedAccount。 - 如果希望稍微泛化一点，可以使用
FetchAccount或RetrieveAccount。