From 4653198bd5ddf414c3c43963c43e510d8f556dda Mon Sep 17 00:00:00 2001 From: tink Date: Thu, 27 Feb 2025 23:53:06 +0800 Subject: [PATCH] =?UTF-8?q?git=20add=20=E4=B9=9D=E5=A4=A7=E5=91=BD?= =?UTF-8?q?=E5=90=8D=E8=A7=84=E5=88=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/cheatsheet/九大命名规则.md | 151 ++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 152 insertions(+) create mode 100644 docs/cheatsheet/九大命名规则.md diff --git a/docs/cheatsheet/九大命名规则.md b/docs/cheatsheet/九大命名规则.md new file mode 100644 index 0000000..6a9bb15 --- /dev/null +++ b/docs/cheatsheet/九大命名规则.md @@ -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`**。 diff --git a/mkdocs.yml b/mkdocs.yml index 1c58ed4..0c00c10 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -247,6 +247,7 @@ nav: - CMake: cheatsheet/cmake.md - Katex: cheatsheet/KaTex常用公式编辑.ipynb - "PKG-CONFIG": cheatsheet/pkg-config.md + - 九大命名规则: cheatsheet/九大命名规则.md - QA: - redis: qa/redis.md - mysql: qa/mysql.md