# 命名规则

## 九大命名规则

以下是 **九大通用的良好命名规则**，可用于 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
```

可以考虑以下命名方式：

推荐命名：

1. **`GetAccountWithCache`** （✅ 清晰表达增加了缓存功能）
2. **`GetCachedAccount`** （✅ 直观表达“从缓存获取账户信息”）
3. **`FetchAccount`** （✅ 可以表示“可能来自缓存”）
4. **`RetrieveAccount`** （✅ 更泛化，适用于不同的数据源）

不太推荐的命名：

- `GetAccountV2` ❌（除非是 API 版本升级，否则 v2 容易引起困惑）
- `GetAccountCached` ❌（读起来不太自然）
- `GetAccountFromCache` ❌（容易误解为**只从缓存获取**，不走原始逻辑）

最佳选择：

- 如果想保持与原有命名一致，建议 **`GetAccountWithCache`** 或 **`GetCachedAccount`**。
- 如果希望稍微泛化一点，可以使用 **`FetchAccount`** 或 **`RetrieveAccount`**。