基础、通用与业务组件边界:按知识和变化原因分层
层级边界由“谁知道什么”决定:基础层知道 HTML、ARIA 与令牌,组合层知道可复用交互模式,业务层知道订单、退款和权限。依赖只能由业务指向组合与基础,基础层不能通过回调名称或导入路径暗中理解领域规则。
前置知识与能力边界
- 单一职责与组合
- Controlled 与 Uncontrolled
- React State、Context、Effect 与 TypeScript 判别联合
- 浏览器事件、HTTP 和可访问性基础
本文处理组件分类、依赖方向、Props 契约和迁移判断;设计令牌的完整构建系统与视觉规范另行学习。
1. 定义、所有权与数据流
组件层级不是按代码行数划分,而是按它掌握的知识、依赖方向和变化原因划分。基础组件负责交互语义和设计令牌,通用组件组合跨业务模式,业务组件表达领域语言与用例。
flowchart LR
A0["设计令牌"] --> A1
A1["基础组件"] --> A2
A2["通用模式"] --> A3
A3["业务组件"] --> A4
A4["页面用例"]组件分层的判据是组件掌握的知识与变化原因:基础层认识浏览器语义和令牌,通用层认识跨业务交互模式,业务层认识订单、退款等领域规则,页面层负责一次用例的编排。
2. 关键机制
2.1 基础组件
Button、Input 等封装语义、焦点、状态与令牌,不认识订单和客户。
若边界缺失,基础层导入业务类型导致设计系统无法复用。
验证:包依赖图中基础层只依赖平台与令牌。
2.2 通用组件
DataTable、SearchField 等表达跨业务交互模式,通过列或回调接收数据。
若边界缺失,万能组件堆积几十个布尔 Props。
验证:用场景矩阵验证组合点而非开关数量。
2.3 业务组件
OrderStatusBadge、RefundPanel 直接使用领域术语和权限。
若边界缺失,把业务判断藏在通用层形成隐式规则。
验证:领域测试覆盖状态映射与权限分支。
2.4 页面组件
协调路由、数据请求、业务组件和错误边界。
若边界缺失,页面同时实现底层键盘交互。
验证:审查页面是否只做编排。
2.5 依赖方向
页面→业务→通用→基础,低层不反向导入高层。
若边界缺失,为复用而把业务 enum 下沉。
验证:静态规则检查跨层 import。
2.6 样式契约
低层用 variant、size、state 暴露有限语义,不开放任意内部选择器。
若边界缺失,调用方依赖 DOM 层级后升级即破坏。
验证:视觉回归覆盖公开 variant。
2.7 组合槽位
复杂结构用 children、slots 或 compound parts 扩展。
若边界缺失,cloneElement 注入隐式 Props 容易失效。
验证:无障碍树验证最终 DOM。
2.8 领域转换
业务层把领域状态映射为通用展示模型。
若边界缺失,通用表格理解退款状态。
验证:搜索低层代码不得出现领域枚举。
2.9 提取阈值
至少两个真实场景共享稳定行为再提取,外观相似不足以抽象。
若边界缺失,过早抽象造成条件分支增长。
验证:统计调用点差异和变更共振。
2.10 所有权
组件所在层负责对应测试、文档和版本策略。
若边界缺失,无人维护的 shared 目录成为杂物箱。
验证:CODEOWNERS 与变更记录覆盖公共层。
3. 用依赖和业务词汇判定层级
先检查 import:基础组件不得导入领域类型,通用组件不得请求某个业务接口。再检查 Props:tone="critical" 是视觉语义,refundRejected 是领域语义,后者应在业务组件映射。最后检查变化记录:两个组件只有外观相似但总因不同需求修改时,不应强行合并。
4. 从页面代码提取组件的顺序
保留页面中的请求和权限编排,先把原生按钮与输入替换为经过无障碍测试的基础组件。
把跨订单、用户、账单都一致的排序、分页和列布局提成 DataTable 协议,不把 URL 或 DTO 放进去。
把订单枚举、退款资格和操作组合留在订单领域组件。
用依赖规则禁止基础层和通用层导入业务目录。
分别运行基础交互测试、通用场景测试和业务用例测试,不能只靠页面快照。
5. 应用案例一:订单状态展示
列出 Badge 的 tone 契约和 OrderStatus 的映射,未知状态必须产生可观察错误。
验证订单新增状态时只修改业务映射;基础 Badge 的消费者测试不变。
注入无权限状态,业务组件不渲染操作,但服务端仍拒绝直接请求。
高对比度与读屏检查针对 Badge,领域文案检查针对 OrderStatusBadge。
搜索基础包源码,不能出现订单枚举或接口路径。
结果:基础 Badge 可供任意标签复用;订单状态变更只修改业务层。
失败分支:若基础组件出现 cancelledByMerchant 枚举,说明边界泄漏。
6. 应用案例二:企业表格
用三类真实列表归纳排序、分页、选择和空状态的稳定协议。
列定义接收值读取与渲染函数,DataTable 不读取订单 DTO。
远端分页事件只上报 page/sort,业务容器负责写 URL 和发查询。
注入 10,000 行并决定是否启用虚拟化,同时保留表头和键盘语义。
替换数据源为内存数组,通用表格无需修改。
结果:通用层可以用 Storybook 场景验证;服务端筛选契约仍在各领域。
失败分支:把请求 URL 放进 DataTable 会让离线数据和不同后端无法使用。
7. TypeScript 核心实现
下面代码用基础组件保留语义和焦点能力,由业务组件注入领域动作与文案。测试应分别验证基础层键盘契约和业务层权限分支,避免一条端到端测试承担全部定位。
type BadgeProps = {
tone: "neutral" | "positive" | "warning" | "critical";
children: React.ReactNode;
};
declare function Badge(props: BadgeProps): React.ReactElement;
type OrderStatus = "pending" | "paid" | "shipped" | "cancelled";
const presentation: Record<OrderStatus, { label: string; tone: BadgeProps["tone"] }> = {
pending: { label: "待支付", tone: "warning" },
paid: { label: "已支付", tone: "positive" },
shipped: { label: "已发货", tone: "positive" },
cancelled: { label: "已取消", tone: "neutral" },
};
export function OrderStatusBadge({ status }: { status: OrderStatus }) {
const item = presentation[status];
return <Badge tone={item.tone}>{item.label}</Badge>;
}Props 类型不能阻止业务层覆盖按钮语义或破坏焦点顺序;运行时测试要覆盖 DOM 角色、键盘操作和禁用状态。公共组件升级还需在消费者清单中运行视觉与交互回归。
8. 方案选择
| 方案 | 适用条件 | 成本与限制 |
|---|---|---|
| 复制局部组件 | 只有一个场景且变化方向未知 | 重复可见但不会形成错误抽象 |
| 提取业务组件 | 同领域多处共享规则 | 不能跨领域强行复用 |
| 提取通用组件 | 多个领域共享稳定交互协议 | 需要完整 API、无障碍和版本维护 |
只有交互语义和视觉约束能跨业务稳定复用时,组件才应下沉到基础层。携带退款状态、权限判断或领域文案的组件应留在业务层,即使多个页面暂时使用它。
9. 调试与失败注入
| 现象 | 检查 | 修正 |
|---|---|---|
| shared 目录持续膨胀 | 组件是否有明确知识边界 | 按层和领域重新归属 |
| 布尔 Props 爆炸 | 是否用开关模拟多个组件 | 拆分 variant 或复合部件 |
| 低层出现业务 import | 依赖方向是否反转 | 把映射提升到业务层 |
| 样式升级破页 | 调用方是否选择内部 DOM | 只公开 token 与 slot |
| 看似相同却一起难改 | 共享的是外观还是规则 | 复制后观察变化方向 |
| 表格无法换数据源 | 组件是否内置请求 | 注入数据与事件 |
| 键盘行为不一致 | 业务层是否重写基础交互 | 把语义收敛到基础层 |
| 发布后未知影响 | 公共组件是否有使用清单 | 建立消费者测试 |
先在 DOM 中确认错误来自基础交互还是业务组合,再检查业务层是否覆写角色、事件或禁用规则,最后用消费者测试定位受影响入口。失败信号包括键盘与鼠标行为不一致、同名组件语义不同和公共组件发布后未知破坏;通过独立 Story、无障碍测试和消费者矩阵验证。
10. 性能、安全与运维边界
- 基础组件必须覆盖键盘、焦点、禁用、加载和高对比度。
- 业务权限不能由隐藏按钮替代服务端授权。
- 主题令牌变化需做多品牌视觉回归。
- 公共组件 Props 变更按破坏性级别发布。
- 大列表组件明确虚拟化、稳定 key 和测量边界。
- 服务端组件与客户端组件边界避免把交互依赖扩散。
- 追踪公共组件包体积和重复样式。
- 废弃组件用 codemod 或调用扫描完成迁移。
生产验证至少记录一次正常路径和一次故障路径;对“基础、通用与业务组件边界”的结论必须能关联到日志、Profile、网络记录或自动化测试。
11. 与其他架构模块集成
- 与 Headless 组件结合:基础层持有行为,视觉通过令牌实现。
- 与依赖倒置结合:业务组件通过端口使用数据能力。
- 与领域组织结合:业务组件留在领域模块。
- 与测试策略结合:低层做交互契约,高层做用例测试。
集成时基础层只暴露交互状态和事件契约,业务层负责把领域命令映射为 Props。禁止基础组件反向导入业务模块,并用包出口限制和静态规则验证层级。
12. 综合练习
从一个包含请求、权限、表格和按钮样式的订单页面拆出四层组件,并证明订单枚举没有进入基础层。
验收标准
- [ ] 基础层不出现领域 import 或领域枚举。
- [ ] 通用表格不包含 URL、请求地址和权限判断。
- [ ] 两个案例分别有无障碍、业务和性能证据。
- [ ] 跨层 import 由 CI 拒绝。
- [ ] 公共 Props 的破坏性变化有迁移说明。
13. 抽象是否成立的变更测试
组件抽象是否正确,不能只看当前页面截图。需要构造会让各层以不同原因变化的需求:
12.1 新增订单状态
后端新增 partially_refunded。订单业务层增加标签、tone 与可用操作的映射;基础 Badge 不增加名为 partiallyRefunded 的 variant。若基础层必须发布新版本才能支持该业务状态,说明领域词汇已经泄漏。
12.2 更换品牌主题
品牌把 critical 色从红色改成符合对比度要求的另一组令牌。基础组件和所有消费者应统一变化,订单映射不修改。视觉回归需要覆盖 hover、focus-visible、disabled、高对比度和暗色主题,不能只截默认状态。
12.3 表格改用本地数据
把企业表格的数据源从远端分页替换成已加载的内存数组。DataTable 若只接受 rows、columns、sort state 和事件回调,可以复用;若内部拼接 API URL 或认识 totalPages 的某个后端 DTO,就需要把请求职责上移。
12.4 行操作权限变化
“只有财务管理员可退款”属于业务能力规则。业务容器根据服务端返回的 capability 决定是否提供 Refund action;通用表格只渲染收到的操作。隐藏操作改善体验,但直接请求仍必须由服务端授权拒绝。
14. 公共组件的消费者契约
公共层升级时至少检查以下契约:
| 契约 | 自动化证据 | 破坏示例 |
|---|---|---|
| DOM 语义 | role、name、state 的可访问树断言 | 把原生 button 换成无键盘语义的 div |
| 事件时序 | pointer、Enter、Space 与取消分支测试 | onChange 从提交后改为提交前 |
| 样式入口 | 公开 variant 与 token 的视觉回归 | 删除消费者依赖的 size |
| Ref | 焦点与测量测试 | 版本升级后 ref 指向包装层 |
| SSR | 服务端与 hydration 测试 | 首次渲染依赖 window |
消费者测试应选择真实代表场景,而不是复制组件自身的单元测试。基础 Dialog 的测试证明焦点陷阱正确;退款页面的消费者测试还要证明关闭后焦点回到退款按钮、权限变化时没有不可达焦点。
来源
- React:Sharing State Between Components(访问日期:2026-07-18)
- React:Passing Props to a Component(访问日期:2026-07-18)
- WAI-ARIA APG(访问日期:2026-07-18)
- Storybook:Component Story Format(访问日期:2026-07-18)