Skip to content

基础、通用与业务组件边界:按知识和变化原因分层 ​

层级边界由“谁知道什么”决定:基础层知道 HTML、ARIA 与令牌,组合层知道可复用交互模式,业务层知道订单、退款和权限。依赖只能由业务指向组合与基础,基础层不能通过回调名称或导入路径暗中理解领域规则。

前置知识与能力边界 ​

本文处理组件分类、依赖方向、Props 契约和迁移判断;设计令牌的完整构建系统与视觉规范另行学习。

1. 定义、所有权与数据流 ​

组件层级不是按代码行数划分,而是按它掌握的知识、依赖方向和变化原因划分。基础组件负责交互语义和设计令牌,通用组件组合跨业务模式,业务组件表达领域语言与用例。

mermaid
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. 从页面代码提取组件的顺序 ​

  1. 保留页面中的请求和权限编排,先把原生按钮与输入替换为经过无障碍测试的基础组件。

  2. 把跨订单、用户、账单都一致的排序、分页和列布局提成 DataTable 协议,不把 URL 或 DTO 放进去。

  3. 把订单枚举、退款资格和操作组合留在订单领域组件。

  4. 用依赖规则禁止基础层和通用层导入业务目录。

  5. 分别运行基础交互测试、通用场景测试和业务用例测试,不能只靠页面快照。

5. 应用案例一:订单状态展示 ​

  1. 列出 Badge 的 tone 契约和 OrderStatus 的映射,未知状态必须产生可观察错误。

  2. 验证订单新增状态时只修改业务映射;基础 Badge 的消费者测试不变。

  3. 注入无权限状态,业务组件不渲染操作,但服务端仍拒绝直接请求。

  4. 高对比度与读屏检查针对 Badge,领域文案检查针对 OrderStatusBadge。

  5. 搜索基础包源码,不能出现订单枚举或接口路径。

结果:基础 Badge 可供任意标签复用;订单状态变更只修改业务层。

失败分支:若基础组件出现 cancelledByMerchant 枚举,说明边界泄漏。

6. 应用案例二:企业表格 ​

  1. 用三类真实列表归纳排序、分页、选择和空状态的稳定协议。

  2. 列定义接收值读取与渲染函数,DataTable 不读取订单 DTO。

  3. 远端分页事件只上报 page/sort,业务容器负责写 URL 和发查询。

  4. 注入 10,000 行并决定是否启用虚拟化,同时保留表头和键盘语义。

  5. 替换数据源为内存数组,通用表格无需修改。

结果:通用层可以用 Storybook 场景验证;服务端筛选契约仍在各领域。

失败分支:把请求 URL 放进 DataTable 会让离线数据和不同后端无法使用。

7. TypeScript 核心实现 ​

下面代码用基础组件保留语义和焦点能力,由业务组件注入领域动作与文案。测试应分别验证基础层键盘契约和业务层权限分支,避免一条端到端测试承担全部定位。

tsx
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 的测试证明焦点陷阱正确;退款页面的消费者测试还要证明关闭后焦点回到退款按钮、权限变化时没有不可达焦点。

来源 ​

从前端走向软件产品工程的长期路线图。