前端框架组件通信约定规范

前端框架组件通信约定规范一、总则（一）目的明确。为规范前端框架组件间通信行为，提升系统稳定性与可维护性，特制定本约定规范。（一）适用范围。本规范适用于公司所有采用React、Vue、Angular等主流框架开发的前端项目，涵盖组件层级、跨组件、全局状态等所有通信场景。（一）基本原则。通信设计应遵循最小权限、高内聚、低耦合、可观测四大原则，确保各组件职责清晰、交互可控。二、组件通信层级划分（一）自顶向下。组件通信按层级分为组件内、组件间、全局三大维度，各维度通信方式需严格按优先级使用。1.组件内通信。通过props向下传递数据，事件向上反馈状态，实现单一职责组件内部自洽。禁止通过ref直接访问兄弟组件内部状态。2.组件间通信。优先使用事件总线（如Redux、Vuex、MobX），次选Props穿透，最后考虑状态共享库。严禁跨层级直接通信。3.全局状态通信。核心数据必须通过状态管理工具统一调度，禁止通过window、localStorage等原生API进行全局污染。（二）场景适配。不同通信场景需匹配对应方式：父子组件用Props/Events，兄弟组件用事件总线，多级组件用全局状态，工具类组件用事件委托。三、跨组件通信协议（一）Props传递规范。父组件向子组件传递数据时，必须使用具名Props，禁止动态key访问。数据结构应遵循扁平化设计，避免嵌套传递。1.数据验证。所有传入Props必须添加类型校验，复杂对象需使用函数式传递避免状态劫持。2.更新策略。状态更新必须使用shouldComponentUpdate或React.memo优化，避免不必要的渲染。（二）事件触发规范。事件命名必须使用动词形式，如"onSave"、"onChange"，事件参数必须使用标准结构。1.事件冒泡。禁止不必要的事件冒泡，特殊场景需明确标注stopPropagation。2.事件防抖。高频操作事件必须配合防抖处理，防抖阈值按设备性能动态调整。（三）状态管理约定。全局状态变更必须遵循单向流原则，状态更新需附带时间戳和变更日志。1.状态命名。全局状态必须使用中划线命名法，如"user-profile"，避免大写字母。2.读写分离。状态读取使用Selector函数，状态更新使用ActionCreator，禁止直接修改原始状态。四、组件边界设计（一）职责隔离。每个组件必须实现单一职责，组件边界通过props/events清晰界定，禁止通过ref访问兄弟组件内部实现。（二）接口契约。组件对外暴露的接口必须使用TypeScript定义类型，接口文档需同步更新。1.输入验证。所有外部输入必须进行XSS过滤，特殊字符需转义处理。2.输出校验。组件输出数据必须附带完整元数据，包括来源、更新时间、变更类型。（三）边界测试。组件边界必须通过单元测试覆盖，测试用例需包含异常输入场景。五、性能优化要求（一）渲染优化。组件通信必须使用React.memo、Vue的keep-alive等缓存机制，避免无用渲染。1.虚拟DOM。禁止直接操作DOM，所有DOM变更必须通过框架API完成。2.性能监控。关键通信链路必须接入性能监控，超时阈值设置为200ms。（二）内存管理。组件卸载时必须清理所有订阅和定时器，避免内存泄漏。1.事件解绑。所有注册的事件必须在组件卸载时解除，使用useEffect或Vue的watch卸载钩子。2.状态清理。全局状态订阅必须在组件卸载时取消，避免残留状态污染。六、版本兼容策略（一）向后兼容。组件通信接口变更必须遵循语义化版本控制，重大变更需提供迁移方案。（二）向前兼容。新版本组件必须支持旧版本通信协议，通过适配层处理差异。1.兼容模式。组件加载时自动检测环境，按需启用兼容模式。2.版本检查。通信协议变更必须通过编译时检查，防止隐式兼容问题。七、附则说明（一）文档更新。本规范随框架版本迭代同步更新，每次更新需发布版本说明。（二）责任主体。各项目组技术负责人为本规范执行第一责任人，需定期组织培训。（三）违规处理。违反本规范导致系统问题，将按《技术