核心用法
component-api-design 是一套组件工程化设计规范，用于指导开发者创建高内聚、低耦合的 React/Vue 组件。核心流程包括：明确单一职责 → 设计 Props API（遵循受控/非受控模式、联合类型替代布尔开关） → 规划扩展点（children/slots/render props + 透传 HTML 属性） → 规范事件命名与参数顺序 → 输出标准化文件结构。
显著优点
- API 一致性：强制对齐
value/onChange、open/onOpenChange等社区约定，降低认知成本 - TypeScript 友好：强调显式类型定义、联合类型优于布尔 prop，编译期即可拦截误用
- 可扩展架构：通过 slots、render props、className 透传实现无侵入定制，避免过度封装
- 生态兼容：主动适配 Radix/shadcn、Tailwind、react-hook-form 等主流方案
- 文件组织清晰：提供目录结构模板（index/实现/types/样式分离），便于团队协作与代码审查
潜在局限
- 学习成本：对新手需要理解受控组件、render props 等抽象概念
- 灵活性边界：过度强调单一职责可能导致组件碎片化，需开发者自行把握拆分粒度
- 框架倾向：示例以 React/TypeScript 为主，Vue 开发者需做心智映射（slots 对应、v-model 对应）
- 无自动化工具：纯规范文档，不提供 CLI 或代码生成，依赖人工执行
适合人群
- 中高级前端工程师设计基础组件或业务组件库
- 团队建立组件规范、Code Review 标准时使用
- 重构遗留组件、统一多项目 API 风格的场景
常规风险
- 规范漂移：若团队未配套 lint 规则或模板，易出现 "文档写一套，代码另一套"
- 过度设计：严格遵循所有原则可能导致简单组件 API 臃肿，建议按需裁剪
- 版本兼容：API 升级时需评估 breaking change，文档未提供迁移策略指引