react-boundaries

React 边界

在最低的合理边界拥有状态、数据和副作用。父组件负责组合结构；不要让它们变成数据枢纽。

**原则：**组件应拥有渲染和执行操作所需的内容——除非确实需要另一个边界来协调、控制访问或并行加载。

硬性默认规则

1. **下推。**状态和数据获取应与使用方放在一起。只有符合例外清单时才上提。
2. **传递标识，而非载荷。**向子组件提供 id（或稳定句柄），让它们自行订阅或查询。不要通过从不使用实体的包装组件逐层传递实体。
3. **组合 UI，而不是传递属性。**优先使用 children / 插槽 / 命名部件，而不是通过布局外壳逐层传递 data、isLoading 和处理函数。
4. **客户端共享，钩子本地化。**使用一个 API 或 QueryClient，以及多个叶子钩子。不要在五层之上的位置集中处理“调用 API”。
5. **重视结构，而非备忘化表演。**先修正所有权和树结构，再到处使用 memo / useCallback / useMemo。优先采用兼容 React Compiler 的模式。
6. 每次上提都要用一句话说明理由，包括上提状态或在路由层获取数据（“SEO”、“挂载前拦截”、“兄弟组件同步”、“避免瀑布式请求”）。

何时适合上提

仅在以下情况下上提状态或数据所有权：

例外	所有权归属
路由 / SSR / SEO 需要在绘制前获取数据或用于元信息	路由加载器、Start 服务端函数或 RSC 预取
身份验证、权限，或“满足 X 前不要挂载”	路由或父级拦截层
两个或更多兄弟组件必须共享一个交互式真实数据源	最近的共同父组件或范围狭窄的 store
父组件必须先知道有哪些子组件，子组件才能获取数据	父组件 / 加载器（避免瀑布式请求）
缓存已对相同键去重	叶子组件仍应订阅；父组件可以只预取

其他情况一律下放。详情：ownership.md。

工作流

1. 界定范围——用户指定的功能、路由或组件树。
2. 梳理所有权——针对每项状态和每个查询 / 修改操作，明确所有者，以及变化时哪些组件会重新渲染。
3. 应用默认规则——下移所有权；用标识 + 叶子订阅替代逐层传递载荷；用组合替代属性传递链。
4. 应用 TanStack 模式——tanstack-patterns.md。
5. 检查组合方式——composition.md。
6. 消除反模式——anti-patterns.md。
7. 验证——针对变更涉及的范围运行类型检查 / lint / 测试；确认高频变化的状态不再位于页面 / 路由外壳中。

位置检查清单

完成变更前，请回答：

• 如果此状态或查询更新，哪些组件会重新渲染？
• 谁实际使用这些数据或状态？
• 叶子组件能否自行拥有查询 / 修改操作（或订阅共享键）？
• 中间组件是在组合 UI，还是只转发属性？
• 如果已上提：适用哪项例外（一句话说明理由）？
• Context / Store 是否承载了应在本地管理的稳定依赖或高频变化值？

非目标

• 不是“绝不使用 Context”“绝不使用路由加载器”或“绝不传递属性”。
• 不涉及重新设计样式、无障碍原语设计或通用 React API 文档。
• 不用临时的父组件 useEffect 数据获取替代 TanStack Query。

完成报告

简要说明：

• 所有权调整（哪些内容下移或保留在上层，以及原因）。
• 移除的属性逐层传递或数据枢纽。
• 预取与订阅的分工（如有）。
• 保留在上层的内容及其例外依据。