AI 辅助：前端工程规范：从代码洁癖到团队可执行约束-洪萨配资

AI 辅助：前端工程规范：从代码洁癖到团队可执行约束

一、规范不是审美争论，而是协作成本控制

前端团队讨论规范时，很容易滑向审美争论。单引号还是双引号，文件名用 kebab 还是 camel，CSS 类名怎么写。讨论本身没问题，但如果规范只停留在偏好，就很难长期执行。真正有价值的工程规范，应该降低协作成本、减少线上风险、提升交付一致性。

代码洁癖不是把代码写得像艺术品，而是让代码在半年后还能被人安全修改。规范的目标也不是让每个人写出完全一样的代码，而是让关键决策有统一底线。比如组件边界、状态管理、错误处理、性能预算、目录结构、测试要求，这些比空格风格更重要。

规范必须能自动执行。靠口头提醒维护规范，最后一定会失效。能交给 Prettier 的，不要拿到 Review 里吵。能交给 ESLint 的，不要靠人肉检查。Review 应该留给架构、边界和业务风险。

二、规范落地链路：从文档到 CI 阻断

flowchart TD A[团队规范文档] --> B[ESLint/Stylelint/Prettier] B --> C[本地 Git Hooks] C --> D[CI 检查] D --> E{是否通过} E -- 否 --> F[阻断合并] E -- 是 --> G[进入 Code Review] G --> H[架构与业务风险审查]

这条链路强调分层。格式化问题在本地解决，静态规则在 CI 解决，架构问题在 Review 解决。不要把所有问题都塞进 Review。否则 Reviewer 会被低级噪声淹没，真正重要的问题反而看不到。

规范文档也要短。太长没人看。建议分成三层：必须遵守、推荐实践、解释说明。必须遵守的内容要能被工具检查。推荐实践可以在 Review 中讨论。解释说明用于新成员理解背景。

三、规则配置：把底线写进工具

下面是一组基础工程约束示例。

{ "scripts": { "lint": "eslint src --max-warnings=0", "stylelint": "stylelint \"src/**/*.{css,scss}\"", "typecheck": "tsc --noEmit", "test": "vitest run" }, "lint-staged": { "*.{ts,tsx}": ["eslint --fix", "prettier --write"], "*.{css,scss}": ["stylelint --fix", "prettier --write"] } }

--max-warnings=0看起来严格，但对长期项目有价值。warning 如果不处理，很快会变成背景噪声。类型检查也必须进入 CI。TypeScript 如果只在编辑器里报错，却不阻断构建，就失去了工程约束的一半价值。

组件规范也可以写成规则。比如禁止跨模块深层导入，禁止业务页面直接引用组件内部文件，禁止在渲染函数里创建复杂对象。部分规则可以用 ESLint 自定义插件实现。

四、权衡分析：规范太硬会降低局部效率

严格规范会让某些临时改动变慢。比如一个紧急需求，因为测试不全被 CI 阻断，看起来很烦。但规范的价值就在于让风险显性化。可以有应急通道，但应急通道必须记录原因，并在事后补齐。

规范也要分阶段推进。老项目一次性开启所有规则，会产生大量历史问题，团队很容易放弃。更好的方式是新代码严格，旧代码逐步清理。可以先只检查变更文件，再设定每周清理目标。

不要把规范变成权力工具。规范服务工程质量，不服务个人偏好。凡是不能解释收益的规则，都应该谨慎加入。每条规则都应该回答：它减少了哪类风险，节省了哪类成本。

生产落地补充：从能跑到可维护

从生产落地角度看，这类方案不能只停留在主流程。更关键的是把输入校验、失败分支、资源上限和回滚路径提前写清楚。主流程通常容易在演示环境里跑通，真正暴露问题的是异常输入、依赖抖动、并发放大和权限边界。一篇技术方案如果没有解释这些约束，读者很难判断它能否放进真实系统。

评估时建议先定义三类指标：正确性指标、稳定性指标和成本指标。正确性指标回答结果是否可信，稳定性指标回答失败时是否可控，成本指标回答持续运行是否划算。三类指标要同时进入验收清单，不能只用平均耗时或单次成功率证明方案有效。

异常路径补充：把失败当成接口契约

下面的补充片段强调一个原则：调用方必须得到稳定、可解释的错误，而不是在超时、空输入或依赖失败时收到模糊结果。代码不追求覆盖所有业务细节，而是展示输入校验、超时控制和错误封装这三个生产系统最容易遗漏的环节。

type GuardedResult<T> = { ok: true; data: T } | { ok: false; error: string }; async function runWithGuard<T>(task: () => Promise<T>, timeoutMs = 3000): Promise<GuardedResult<T>> { const controller = new AbortController(); const timer = setTimeout(() => controller.abort(), timeoutMs); try { const data = await task(); return { ok: true, data }; } catch (error) { const message = error instanceof Error ? error.message : "unknown error"; return { ok: false, error: message }; } finally { clearTimeout(timer); } }