AI 组件命名建议：命名不是美化，是降低维护成本
组件命名看起来是小事，但项目变大后，Card2、NewButton、UserPanelTemp这类名字会让维护成本越来越高。AI 可以帮忙给组件命名，但不能只追求好听。命名要表达职责、范围和复用边界。
好的组件名，不是让人觉得高级，而是让后来的人一眼知道它该放在哪里、能不能复用。
一、先区分组件类型
flowchart TD A[Component] --> B[Primitive] A --> C[Composite] A --> D[Feature] A --> E[Page]基础组件、组合组件、业务组件、页面组件，命名规则不应该一样。Button可以很通用，InvoiceStatusCard就应该带业务语义。
这四种类型的命名规则需要明确定义。基础组件是 UI 原子，命名应该描述视觉或交互功能：Button、Input、Modal、Tooltip、Spinner。它们通常存在于公共组件库中，不包含业务概念。
组合组件是用基础组件拼出来的可复用模块。比如SearchBar = Input + Button + Dropdown。这类组件命名要表达组合功能：DateRangePicker、FileUploader、PaginationBar。它们也应该是无业务域的。
业务组件是最容易命坏的类型。它们承载了具体的业务语义，命名必须包含领域信息。比如发票模块的状态卡片应该叫InvoiceStatusCard，而不是StatusCard或InfoPanel。
页面组件就是路由入口，通常以Page结尾：SettingsPage、DashboardPage。
我们团队在 Code Review 时经常问一个简单问题：通过组件名和目录，你能判断这个组件能不能用在另一个业务模块吗？如果答案是不确定，命名就有问题。例如OrderInfo如果放在shared/components下，应该是一个通用订单信息组件，任何模块都可以用；但如果它里面引用了orderService.createRefund，那它就不该在 shared 目录，名字也不能叫通用的OrderInfo，应该叫RefundActionPanel并放在features/refund/components下。
二、让 AI 基于职责命名
给模型输入组件 props、使用场景和目录位置，而不是只给截图。
component_context: props: [status, amount, dueDate, onPay] domain: billing usage: "dashboard payment reminder" reusable: false这种上下文下，PaymentReminderCard比InfoCard更有维护价值。
提供上下文的粒度决定了 AI 命名建议的质量。除了 props 和 domain，建议再补充：
component_context_extended: props: [status, amount, dueDate, onPay] domain: billing usage: "dashboard payment reminder" directory: "features/billing/components" data_dependencies: ["/api/billing/due-invoices"] similar_components_in_project: ["ExpiredPlanAlert"]similar_components_in_project尤其重要。如果项目中已经有了ExpiredPlanAlert，AI 可以参考命名风格，避免创建不一致的名字。同时告诉 AI 这个组件和已有组件的关系是并列还是替代，这会影响名字选择。
我们内部做了一个小工具，扫描组件文件提取 props 接口、import 语句和导出类型，自动生成上下文 JSON，然后喂给 AI。AI 输出三个命名候选加理由：
interface NamingInput { filePath: string; props: PropMeta[]; dependencies: string[]; domainHint?: string; } interface NamingSuggestion { generic: string; // e.g. StatusCard domain: string; // e.g. InvoiceStatusCard page: string; // e.g. BillingOverviewStatusCard reasoning: string; }开发者选一个，工具自动重命名文件并更新所有引用。这个流程比"想一个名字 -> 改文件 -> 手动更新引用"高效得多。
三、命名要配合目录结构
如果组件在features/billing/components下，名字可以少一点领域前缀；如果在公共组件库里，就必须更通用。
src/ components/Button.tsx features/billing/components/PaymentReminderCard.tsx pages/settings/SettingsPage.tsxAI 命名建议最好同时给出放置目录。名称和目录一起看，才知道边界是否合理。
目录和命名的关系像"契约双签"。名字表达了组件的职责，目录表达了组件的归属。两者一致时，边界自然清楚。
我们的项目规范里有一条：
组件名包含领域信息（如 Payment） → 目录必须是 features/{domain}/components 组件名不含领域信息（如 Button、Modal） → 目录必须是 shared/components 组件名和目录不一致 → Code Review 必须被提问这条规则可以人工检查，也可以通过 ESLint 自定义规则检查。例如一条规则：从shared/components目录导出的组件，文件名不能包含业务领域关键词（如Order、Payment、Invoice）。这种简单规则能防止大多数边界混淆。
// ESLint 自定义规则示例 const SHARED_DIR = "shared/components/"; const DOMAIN_KEYWORDS = ["Order", "Payment", "Invoice", "User", "Billing"]; module.exports = { create(context) { const filename = context.getFilename(); if (!filename.includes(SHARED_DIR)) return {}; const nameMatch = filename.match(/([A-Z][a-zA-Z]+)\.tsx$/); if (!nameMatch) return {}; const componentName = nameMatch[1]; if (DOMAIN_KEYWORDS.some(kw => componentName.includes(kw))) { context.report({ loc: { line: 1, column: 0 }, message: `shared/components 下的组件不应包含业务关键词 "${componentName}"`, }); } return {}; }, };四、避免临时词进入长期代码
New、Old、Temp、V2这类词可以短期迁移用，但不适合长期存在。它们表达的是时间，不是职责。
bad_names: NewUserCard ButtonV2 TempModal better: UserSummaryCard IconButton ConfirmDeleteDialog如果确实要迁移，应该有删除计划。否则V2会陪项目走很多年。
可以把 AI 命名建议接入代码评审，但只做提示，不做强制。比如发现Temp、New、Common这类模糊词时，提醒作者补充职责语义。
name_review_rule: warn_words: [New, Old, Temp, Common, Wrapper] require_domain_when_feature_component: true规则不是为了挑刺，而是让团队在命名时多想一步：这个组件到底表达什么边界？
Wrapper是一个特别常见但很糟的名字。一个组件叫ChartWrapper，半年后可能包了三层 unrelated 逻辑：数据格式化、主题切换、loading 状态。改名叫ChartWithLoadingAndTheme也太啰嗦。更好的做法是拆成ChartLoader（数据）+ThemedChart（主题）+ 页面层拼装。Wrapper 通常暗示了职责过重的设计。
还有一个容易被忽略的词是Common。CommonList、CommonCard、CommonModal这个名字太宽泛，会导致组件的 props 无限膨胀来适配所有场景。如果发现Common*组件的 props 超过 10 个，几乎可以确定它承担了太多职责。拆成更聚焦的命名，虽然要多写几个组件，但每个都比一个大杂烩好维护。
五、总结
AI 可以辅助组件命名，但输入要包含职责、props、使用场景、复用范围和目录位置。命名要表达边界，不只是好听。
组件名是代码里的路标。路标清楚，团队维护大型前端项目会轻松很多。
AI 可以给出候选名和理由，最终仍由团队选择。命名一旦进入公共组件库，就会被长期依赖，谨慎一点完全值得。
一个实用做法是让 AI 同时输出三个候选名：偏通用、偏业务、偏页面上下文。评审时比较它们的复用范围，比直接拍一个名字更稳。
naming_candidates: generic: StatusCard domain: InvoiceStatusCard page: BillingOverviewStatusCard候选名之间的差异，其实就是组件边界的差异。
