组件开发规范：让代码更稳定、协作更高效

在数码工场做数据备份系统的过程中，我们发现一个看似不起眼却影响深远的问题：不同人写的组件风格各异，接口混乱，维护起来像拆炸弹——谁也不知道下一行代码会触发什么。

为什么需要组件开发规范？

上周小李提交了一个新的备份状态展示组件，样式漂亮，交互流畅。但上线前合并代码时，前端团队花了整整一天去适配他的 props 结构，因为他用了 statusText 表示状态文本，而团队其他组件统一用的是 label。这种细节差异，积少成多，就成了技术债。

组件开发规范不是写给新人看的说明书，而是团队协作的“交通规则”。红灯停绿灯行，大家都遵守，才不会撞车。

命名统一是第一步

我们在项目中约定：所有展示类组件以 Display 结尾，比如 BackupStatusDisplay、RecoveryProgressDisplay；操作类组件则用 Action 结尾。这样光看名字就知道这个组件是干啥的。

props 的命名也做了限制。状态相关字段必须用语义化名称，比如 status 只能是枚举值（'success', 'failed', 'pending'），对应显示文本由组件内部通过映射表处理，避免每个调用方重复写 switch 判断。

接口设计要克制

有次为了实现一个临时需求，有人给组件加了三个布尔型 prop：showIcon、hideLabel、disableAnimation。后来另一个页面要用这个组件，结果发现没法同时关闭 icon 和动画，因为逻辑没覆盖到。

现在我们规定：组件对外暴露的 prop 不得超过 7 个。超过就得考虑拆分或封装配置对象。比如：

<BackupIndicator config="{&#123;
  appearance: 'compact',
  behaviors: [&#x27;autoRefresh&#x27;, &#x27;toastOnFailure&#x27;]
&#125;}" />

样式隔离靠约定

曾经有个按钮组件，在某个页面突然变宽了。排查发现是全局样式里一条 .btn { width: 100% } 被引入了。后来我们统一采用 BEM 命名法，并要求所有组件样式包裹在唯一根类名下：

.backup-status-display {
  display: flex;
  align-items: center;
}

.backup-status-display__icon {
  margin-right: 8px;
}

.backup-status-display__text {
  font-size: 14px;
}

构建时通过工具检查是否出现全局选择器，一旦发现就报错。

文档和例子一起交

现在提交组件，除了代码还得附一个 demo 示例文件。我们用 Storybook 搭了个本地预览环境，每次提 PR 都能自动跑出可视化的使用案例。产品经理也能点开看效果，提前发现问题。

比如备份进度条组件，demo 里展示了四种状态：0%、50%、99%、完成。设计师发现 99% 时文字重叠了，开发立刻调整，没等到测试阶段才暴露。

自动化来兜底

光靠人守规矩不行。我们在 CI 流程中加入了 lint 规则：组件文件名必须和导出默认类名一致；禁止直接引用 ../../styles/global 这类路径；props 必须有 TypeScript 类型定义。

有一次新同事忘了写类型，CI 直接挂掉，他才知道：“原来这项目真查这个。”

规范不是束缚，而是让每个人都能放心踩油门的安全带。当大家都按同一套规则写组件，重构时才敢动代码，交接时才能快速上手。在数据备份这种容错率低的场景里，稳定的组件体系，就是系统可靠的第一道防线。