智能组件 Props 设计：AI 生成接口前，先定义状态机

智能组件 Props 设计AI 生成接口前先定义状态机一、Props 不是字段越多越灵活AI 生成组件时常会倾向于把所有可能字段都放进 propstitle、subtitle、loading、disabled、error、variant、icon、actions。字段多看起来灵活但状态组合会爆炸。组件 Props 设计应先定义状态机。组件有哪些状态状态之间如何切换每个状态需要哪些数据。状态清楚后接口才不会变成一堆可选字段。在项目初期就把状态定义好后期迭代时新增状态只需要在联合类型中追加分支编译器会帮你找出所有遗漏的 case 处理。二、状态机先于 PropsstateDiagram-v2 [*] -- idle idle -- loading loading -- success loading -- error error -- loading例如一个数据卡片可能有 idle、loading、success、empty、error 五种状态。每种状态展示内容不同允许的操作也不同。用状态机描述比一堆布尔值更稳定。如果同时传loadingtrue和error...组件应该显示什么布尔字段过多时这类冲突很常见。状态枚举能减少非法组合。状态机的定义不是画完图就结束。更重要的是写出每个状态下的用户可执行动作。比如 idle 状态下用户只能触发获取数据loading 状态下用户可以看到取消按钮error 状态下用户能点重试但不能编辑数据。把这些动作也作为状态的一部分写进设计文档或类型里后续无论是人工实现还是 AI 生成都不会随意添加不符合当前状态的交互能力。这个过程本质上是在用状态限制行为空间让组件在不同上下文中只暴露合理的能力。三、类型要表达合法状态type CardProps | { state: loading } | { state: empty; actionLabel?: string } | { state: error; message: string; onRetry: () void } | { state: success; title: string; value: string }联合类型能让 TypeScript 帮忙约束状态。AI 生成组件时也应优先生成这种可检查接口而不是一堆 optional props。function MetricCard(props: CardProps) { switch (props.state) { case loading: return Skeleton / case error: return ErrorView message{props.message} onRetry{props.onRetry} / case success: return ValueView title{props.title} value{props.value} / } }switch 结构让状态覆盖更清楚也更容易测试。除了类型表达还要定义合法的状态过渡。不是所有状态都能互相跳转比如 success 不能直接变为 idleempty 不应该突然变成 loading 但没有数据刷新动作。这些过渡约束适合用状态机库或自定义 reducer 表达type CardEvent { type: FETCH } | { type: RETRY } | { type: CLEAR } function cardReducer(state: CardState, event: CardEvent): CardState { switch (state.tag) { case idle: return event.type FETCH ? { tag: loading } : state case loading: if (event.type success) return { tag: success, title: event.title, value: event.value } if (event.type error) return { tag: error, message: event.message, onRetry: event.onRetry } return state case error: return event.type RETRY ? { tag: loading } : state default: return state } }这个 reducer 的核心价值是拒绝非法状态跳转。比如在 error 状态下发 FETCH 事件不会生效必须先 RETRY。在真实项目里这种设计避免过这样的线上问题用户网络恢复了但旧的 FETCH 回调直接把 error 覆盖成 loading 然后又立刻回到 error页面在 error 和骨架屏之间反复闪烁。把过渡规则写进 reducer非法路径在代码层面就被拦住了。四、接口要考虑演进组件接口一旦被多个页面使用就不能随便改。新增状态要提供默认行为删除字段要有迁移路径。AI 生成接口时应同时生成使用示例和状态测试。还要控制 escape hatch。允许传 className 或 render prop 可以增加灵活性但也可能破坏设计系统一致性。给出口之前要明确边界。更稳的做法是给 Props 设计一份变更规则。哪些字段可以新增哪些字段必须走废弃周期哪些状态属于实验能力。组件库维护者可以在发布说明里明确迁移示例而不是只写“breaking change”。AI 参与生成时也要把这些规则作为上下文输入。props_change_policy: additive_fields: minor remove_fields: major rename_fields: deprecated_first experimental_states: require_prefix: true测试也要覆盖状态组合。每个合法状态至少有一个渲染用例每个曾经出现过的非法组合都要有类型或运行时校验。这样 AI 下次扩展组件时才不会因为追求“兼容更多场景”重新引入一堆互相冲突的可选字段。五、总结智能组件 Props 设计应先定义状态机再用类型表达合法状态减少布尔字段组合爆炸。AI 可以生成接口但接口是否长期好用取决于状态边界是否清楚。状态机的设计不是一锤子买卖需要随着产品场景的扩展持续演进。