bulletproof-react-architecture

Bulletproof React 架构

来源：bulletproof-react，作者 Alan Alickovic，采用 MIT 许可证。上游仓库现已成为一个包含三个应用变体的 monorepo：apps/react-vite/、apps/nextjs-app/、apps/nextjs-pages/。本技能主要遵循 react-vite 版本。有关许可证和改编说明，请参阅 NOTICE.md。

术语

请准确使用以下术语。仓库指的是“功能”时，不要用“模块”“服务”或“组件”替代。

• 功能：src/features/ 下的独立文件夹，包含某项产品功能专属的所有内容：自己的 api/、components/、hooks/、stores/、types/。
• 共享代码：顶层 components/、hooks/、lib/、types/、utils/ 中的所有内容。任何功能或应用层都可以使用。绝不依赖某个功能。
• 应用层：src/app/，指路由、根组件、提供程序、路由器配置。唯一允许组合多个功能的层。

经验法则

便于快速浏览的摘要。下方链接的参考文件中会逐条展开说明。

规则	含义
不要跨功能导入	features/comments 从 features/discussions 导入内容，始终是错误做法。应提升为共享代码。
代码单向流动	共享代码 → 功能 → 应用层。绝不反向流动。共享代码中的任何内容都不能导入功能或应用层中的内容。
先根据类别匹配状态	组件状态、应用状态、服务器缓存状态、表单状态和 URL 状态是五类不同的问题，分别需要不同的工具。

应用前须知

当应用包含多个功能、多个贡献者，或项目周期超过几个月时，这种做法会带来好处。但对于只有五个文件的原型、一次性脚本或临时组件，则没有帮助。

在采用结构化组织之前，先检查项目规模：

• 只有一个功能和少量文件？ 保持 src/ 平铺结构。为一个组件和一次数据获取搭建完整的功能文件夹骨架，正是本技能旨在避免的失败模式，而不是目标。
• 代码库中已有可用的模式？ 遵循现有模式。两套相互竞争的约定，成本高于任何一套约定本身的不足。
• 不确定某条规则是否适用？ 想想不遵守会造成什么问题。如果不会造成问题，就跳过。

下方的参考文件不是检查清单。每个文件都解决一个问题。阅读与当前问题匹配的文件即可。

本技能不适用的情况

对于非结构性工作，例如修复错误、编写单个函数或为组件添加样式，请跳过本技能。如果问题不是“应该放在哪里”或“应该如何组织”，就不需要用到它。

本技能假定你会根据项目规模作出判断。如果你发现自己只是因为项目结构文件中列出了所有子文件夹，就打算逐一创建，请停下来想想这个功能是否真的需要它们。

常见问题

Agent 最常犯的错误：

1. 使用 react-router-dom。 上游仓库已迁移到 react-router v7（库模式）。请从 react-router 导入，而不是 react-router-dom。
2. 为只在一个组件内使用的状态创建 store。 这是组件状态，不是应用状态。先使用 useState。只有在其他组件确实需要同一个值时，才将其提升到 store。
3. 为小功能搭建完整的功能骨架。 只有一个组件和一次 fetch 调用的功能不需要 api/、components/、hooks/、stores/、types/。只用 api/ 和 components/ 就够了。等确有需要时再添加目录。
4. 把服务端缓存状态放进 Zustand、Redux 或任何通用 store。 服务端数据应放在 TanStack Query 的缓存中，而不是手写 store。查询客户端免费提供的缓存、失效和重新获取逻辑，正是它存在的全部意义。
5. Barrel 文件（重新导出所有内容的 index.ts）。 它们会破坏 Vite 的摇树优化。请直接从所需文件导入。
6. 跨功能导入。 值得再次强调：features/comments 引用 features/discussions 中的内容永远不是正确做法。如果两个功能共享逻辑，就将其提升为共享代码。
7. 把单个 api/ 文件判定为过度设计。 在 features/x/api/ 中放一个端点，是 API 层的起点，并不违规。过度设计检查针对的是空的 stores/、只使用一次的 hooks/、只有一个类型的 types/ 目录，或完全位于功能目录之外、真正只用一次的内联 fetch——而不是已经放在实际功能目录中的单个 api/ 文件。
8. 为了转换数据或处理用户事件而使用 useEffect。 如果可以根据现有 props 或状态计算某项内容，就在渲染时计算。如果逻辑是由用户操作触发的，就放在事件处理函数中。Effect 只用于与外部系统同步。请参阅 reference/effects.md。

这些资源可能会有帮助

每个文件都足够短，可以一次性完整阅读。请阅读与当前任务相关的文件。

• reference/project-structure.md：应用和功能文件夹布局，以及用于强制执行上述导入方向的 ESLint 规则。开始开发新功能或遇到任何“这个应该放在哪里”的问题时，请从这里入手。这是本技能中阅读次数最多的文件。

• reference/api-layer.md：请求声明结构：类型、fetcher、hook。编写或审查数据获取代码时阅读。

• reference/state-management.md：五种状态类别，以及每种类别推荐的库。添加 useState、context 或 store 之前请阅读。通常先选工具、再选类别，意味着选错了。

• reference/testing.md：测试类型、精力分配重点、工具（Vitest、Testing Library、Playwright、MSW）。

• reference/error-handling.md：API 错误拦截、错误边界放置、生产环境错误跟踪。篇幅较短，请完整阅读。

• reference/security.md：令牌存储、授权模型（RBAC、PBAC）。请完整阅读，不要挑选部分阅读。存储和清理方面的指导相互依赖；跳过其中某一部分可能导致实际安全漏洞，而不只是浪费时间。

• reference/performance.md：代码拆分、重新渲染的原因、children 模式、图片和预取优化。当性能经测量确实较慢时再阅读，不要提前阅读。

• reference/overengineering-check.md：针对本技能自身约定的一轮精简审查，检查这些约定是否被应用在不值得付出成本的地方。审查代码库是否存在不必要的结构时，或生成某个功能脚手架后进行自检时，请阅读。

• reference/effects.md：何时应避免使用 Effects，以及可采用哪些替代方案。涵盖派生状态、useMemo、使用 key 重置状态、计算链、带清理逻辑的数据获取等内容。使用 useEffect 之前请阅读。

• reference/quality-check.md：用于强制执行或扩展这些约定的配套工具（react-doctor、Vercel 性能规则、组合模式）。