企业级props接口标准核心是统一、可维护、可验证、易协作，需遵循命名规范（组件名+props）、语义分组、类型精确化、默认值与运行时防护、文档及ci/storybook协同落地。
企业级项目中制定 Props 接口编写标准，核心是统一、可维护、可验证、易协作。不是堆砌类型，而是围绕“谁用、怎么传、出错在哪”建立闭环。
统一命名与结构规范
所有组件 Props 接口必须以 组件名 + Props 命名，且定义在独立类型文件中（如 BubbleProps 在 bubble-types.ts）。接口内部按语义分组排列：
- 必填基础字段（如
type、content）放在最前 - 可选配置字段（带
?）居中，优先提供默认值 - 事件回调统一以
on开头（如onReply、onError），参数和返回值类型明确 - 嵌套对象必须抽离为独立接口（如
user: UserInfo），禁止内联类型
类型定义的硬性规则
避免模糊类型，每种场景有唯一推荐方案：
- 有限枚举值 → 字符串字面量联合：
status: 'idle' | 'loading' | 'success' - 布尔属性 → 显式
boolean类型，不使用string模拟：disabled?: boolean - 数字范围控制 → TypeScript 字面量联合 + 运行时校验（如
size?: 12 | 14 | 16），并在组件内做 fallback 处理 - 函数类 props → 必须标注完整签名：
onChange?: (value: string, name: string) => void - 对象/数组默认值 → 必须用工厂函数：
items: () => []或config: () => ({ timeout: 5000 })
默认值与运行时防护机制
类型检查只在开发阶段起作用，企业级组件需叠加运行时保障：
- 每个可选 prop 都应有合理默认值（如
showAvatar = true），避免未定义行为 - 对关键字段（如
id、url）添加自定义 validator，校验非空、格式、长度等 - 在组件初始化时做一次 props 合法性快照（如日志警告缺失必填项），不中断渲染但暴露问题
- 对传入的函数 props 做存在性判断，防止
undefined is not a function
文档与协作落地方式
规范不能只写在 Wiki 里，要融入开发流：
- 编辑器自动补全靠接口定义驱动 —— 所有 props 接口必须导出，且注释用 JSDoc 标准（
/** 描述 */） - CI 流程中加入类型检查（
tsc --noEmit）和 props 使用合规扫描（如检测是否漏传 required 字段） - 组件 Storybook 示例页必须覆盖全部 props 组合，尤其是边界情况（空数据、错误状态、高并发回调）
- 新增组件时，PR 检查清单强制包含：接口定义、默认值、validator、JSDoc、Storybook 示例
