HelloWorld 团队模板命名规范怎么定

团队模板命名规范应坚持一致性与可读性原则，建议模板名包含模块、类型、用途、环境、版本、作者与创建日期七项信息，字段用短横线分隔，全部小写且仅用字母数字和短横，版本采用语义化版本号并附状态标签，配套正则校验与自动化脚本，便于检索审核与历史追溯。同时明确命名变更流程、回滚与迁移工具，定期评审并写入文档。

为什么需要统一模板命名规范（像在解释给朋友听）

想象你翻一堆文件夹，里面有几十个“login_template_final_v2”、”Login-Template-copy”、”login_template_jack”——你会抓狂。命名规范像路标，让每个人在几秒内知道某个模板是什么、给谁用、哪个环境、哪个版本。对 HelloWorld 团队来说，模版是经常变更、需要审计和回滚的资产，规范化命名能减少沟通成本、提升自动化率、降低人为错误。

费曼式拆解：命名规范的核心要素（简单明了）

用最少的词把复杂问题拆开，分成容易理解的几个部分：

• 可读性：任何同事能读懂，不靠记忆。
• 一致性：格式固定，便于程序校验。
• 可追溯：包含版本、作者、日期等信息，利于审计。
• 兼容性：能和 CI、检索、备份脚本无缝配合。
• 迁移友好：命名变更有流程与回滚策略。

推荐的模板命名结构（核心规范）

把信息按固定顺序写入文件名，字段用短横线（-）分隔，全部小写，仅允许 a–z、0–9、短横。字段顺序建议固定为：

• 模块（module）
• 类型（type）
• 用途/子类型（purpose）
• 环境（env）
• 版本（version，语义化但用短横隔开）
• 状态（status，stable/beta/draft）
• 作者（author，用户名）
• 日期（date，YYYYMMDD）

格式示例（直观）

整体结构（字段之间以短横分隔）：

module-type-purpose-env-vMAJOR-MINOR-PATCH-status-author-YYYYMMDD

具体例子：

• account-login-web-prod-v1-2-0-stable-jliang-20260210
• billing-invoice-pdf-stag-v0-9-4-beta-asmith-20251201

字段说明（每项为什么要、怎么填）

为什么版本号用短横而不是点

点号在某些工具或路径处理上可能被当成扩展名或被转义，短横更安全、也便于文件名索引。我们仍然保留语义化含义：v1-2-3 对应 1.2.3。

强制校验与正则示例（便于在 CI 中使用）

下面给出一个可直接用于校验的正则表达式（注意：在不同工具中可能需要加上分隔符或转义）：

^[a-z0-9]+(-[a-z0-9]+){0,3}-(dev|stag|prod)-v[0-9]+(-[0-9]+){2}-(stable|beta|draft)-[a-z0-9]+-[0-9]{8}$

说明：

• 模块+类型+用途最多允许四段可变前缀（可按团队需要调整 {0,3}）
• 环境限定为 dev/stag/prod（可扩展）
• 版本以 v 开头，后面三段数字用短横连接
• 状态受限于固定集合
• 作者用户名小写字母数字
• 日期为 8 位数字

在 Git 与 CI 中如何执行（实践建议）

• 提交钩子（pre-commit / pre-push）：在本地用简单脚本校验文件名，拒绝不合规范的提交。
• CI 校验：在流水线第一步对新增或修改的模板文件名运行正则，失败则报告并阻断。
• 代码审查规范：PR 模板里加入检查项“模板命名是否符合规范”，让人工和自动化双重保障。

示例钩子思路（伪代码说明）

在 pre-commit 中遍历待提交的文件，匹配正则，不通过则打印不合格的文件名并退出。脚本可以是 bash、python 或 node，根据团队习惯选用。

迁移与历史兼容（老模板怎么办）

如果已有大量不合规文件，直接强制会很痛苦。建议分步迁移：

• 阶段1：建立映射表（旧名 → 新名），并在仓库根目录维护一个 mappings.csv。
• 阶段2：为映射关系增加自动化脚本，支持批量重命名与替换引用（模板引用、文档、自动化管道等）。
• 阶段3：在 CI 中允许读取 mappings.csv，临时接受旧名一段时间（比如 3 个月），并定期报告剩余旧名。
• 阶段4：期限到后强制只允许新名。

治理与演进（谁来维护规范）

命名规范不是一次性产品，需要治理：

• 指定一位或数位规范负责人（owner），负责维护文档与答疑。
• 建立 RFC 流程：当有人提议修改规范（例如新增状态标签或环境），通过轻量投票或评审流转。
• 定期（例如半年）回顾一次规范及工具链，记录变更并通知全团队。

常见问题（FAQ 风格，快速解惑）

• Q：文件名太长怎么办？

  尽量使用缩写且保持字段必要性，module 与 type 使用团队约定的短名表（例如 acct→account）。必要时，可以允许两级目录组织（module/type/filename）。

• Q：模板属于多个模块怎么办？

  优先选择主责任模块；或采用复合模块名（moduleA_moduleB），但需将下划线替换为短横并在文档中说明。

• Q：谁来写正则和钩子？

  建议由负责规范的工程师提供参考实现，大家可按需调整并提交到仓库统一维护。

检查清单（实践时逐项核对）

• 是否包含必要字段（模块、类型、环境、版本、状态、作者、日期）？
• 是否全部小写并仅包含允许字符？
• 版本是否按 vMAJOR-MINOR-PATCH 格式？
• CI 中是否有正则校验？
• 是否存在迁移计划与映射表？
• 规范是否记录在团队文档，并指定负责人？

附录：示例映射表格式（CSV）

写到这里，脑子里还在想着怎么把这套规范落地：先做一版可执行的正则和 pre-commit 钩子，把示例和映射工具放到仓库根目录，然后慢慢把大家拉进来。别忘了——规范是用来服务人的，不是枷锁。遇到反复出现的边界情况，就把它写进 RFC，二次演进。好了，这篇规范草案够用来启动项目前期的统一工作，接下来就是代码把它变成自动化。