|
|
|
|
@ -0,0 +1,151 @@
|
|
|
|
|
# 命名规则
|
|
|
|
|
|
|
|
|
|
## 九大命名规则
|
|
|
|
|
|
|
|
|
|
以下是 **九大通用的良好命名规则**，可用于 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`**。
|
