命名、常量与文案的批量统一

项目演进中常出现命名风格不一、字面量散落、重复提示文案等问题。批量统一看似简单，难点在于定位完整、区分可改与不可改、验证无遗漏无误伤。本节给出定位方法、统一原则与验证步骤。

一、先定位全部出现点，再决定改不改

任何批量修改前，先让代理列出目标符号、常量或字符串的所有出现位置，并按用途分类：定义处、内部调用、测试、注释文档、对外契约（接口字段、存储键、URL、消息格式）。对外契约一旦被外部依赖，随意改名会造成兼容问题，必须单独评估，不能与内部命名一起"顺手改掉"。

二、命名统一原则

原则	说明
风格一致	同一项目内函数、变量、文件、类型遵循统一命名习惯，不混用多种风格
见名知义	名称表达用途而非实现细节，避免含糊缩写与误导性命名
避开保留字与歧义	不使用语言保留名、容易混淆的近似名和过短的无意义标识
层级清晰	目录、文件、导出符号与内部辅助函数分层命名，关系可追溯
引用同步	改名后所有定义、声明、调用与测试保持一致，不残留旧名

三、常量统一：收敛重复字面量

• 把重复出现且语义固定的字面量（上限、超时时长、默认值、类别标识）收敛为具名常量，集中定义在合适位置。
• 保留常量语义与类型一致，避免同一含义出现多个值不同的"重复常量"。
• 区分真正的配置项（应放配置）与业务内固定常量（可放代码），不要把所有字面量都堆到常量区。
• 替换时以"调用同一常量"为目标，而不是简单复制字面量到多处。

四、文案与提示统一

• 用户可见的错误提示、按钮与说明应保持术语与语气一致，避免同一概念多种叫法。
• 区分对外文案与内部日志：前者面向用户需统一规范，后者面向调试可保留技术表述。
• 涉及外部显示的文案改动要确认不影响外部依赖的固定字符串匹配（如自动化测试、下游解析）。

五、批量修改验证步骤

1. 列清单：汇总所有待改出现点并分类，标记对外契约项。
2. 小批替换：按文件或模块分批修改，优先保证完整符号匹配，避免只改子串造成误伤。
3. 静态检查：运行类型检查/构建，捕获未定义引用与漏改调用点。
4. 测试回归：运行测试确认行为与输出不受影响。
5. 残留核对：确认旧符号在预期范围内零残留；同时确认没有把不该改的外部键、接口名、URL改掉。
6. 范围审查：核对 diff 是否仅限本次统一目标，没有夹带额外重写。

六、典型坑位

• 改了定义漏改测试与文档，导致"代码新、说明旧"。
• 按子串模糊替换，误伤包含该字符序列的无关标识。
• 重命名破坏了持久化键、接口字段或外部配置映射。
• 一次提交重命名上百处且无测试护航，出现问题难以定位。