bulletproof-react-patterns

Bulletproof React 模式

用于构建可扩展、易维护的 React 应用的架构模式。基于 bulletproof-react。

核心参考

主题	描述	参考
项目结构	基于功能组织、单向架构、ESLint 强制检查	项目结构
组件与样式	组件层级、封装第三方库、无头库与样式化库	组件与样式
API 层	API 客户端、请求声明、查询/变更钩子模式	API 层
状态管理	组件、应用、服务端缓存、表单和 URL 状态类别	状态管理
错误处理	错误边界、API 错误、使用 Sentry 跟踪错误	错误处理
测试	使用 Vitest、Testing Library、Playwright、MSW 进行单元、集成、端到端测试的策略	测试
项目规范	ESLint、Prettier、TypeScript、Husky、绝对导入、文件命名	项目规范
安全	身份验证、令牌存储、XSS 防护、RBAC/PBAC 授权	安全
性能	代码拆分、数据预取、状态优化、children 模式	性能

项目结构

按功能组织，而不是按文件类型：

src/
├── app/                # Application shell (routes, providers, router)
├── assets/             # Static files (images, fonts)
├── components/         # Shared, reusable UI components
├── config/             # Environment variables, constants
├── features/           # Feature-based modules
├── hooks/              # Shared custom hooks
├── lib/                # Pre-configured library wrappers
├── stores/             # Global client state
├── testing/            # Test utilities, MSW handlers, factories
├── types/              # Shared TypeScript types
└── utils/              # Pure utility functions

功能模块

features/users/
├── api/            # API functions and query hooks
├── components/     # Feature-specific components
├── hooks/          # Feature-specific hooks
├── types/          # Feature-specific types
└── utils/          # Feature-specific utilities

规则：

• 功能模块不应从其他功能模块导入内容。在应用层进行组合。
• 代码按单一方向流动：共享 → 功能模块 → 应用。
• 仅当有 2 个或更多功能模块复用时，才提升至共享目录。
• 优先使用直接导入，而不是 barrel 重新导出，以便 Vite 进行树摇优化。

组件层级

Page Components          → route-level, compose features, handle layout
  └── Feature Components → feature-specific, business logic
        └── UI Components      → shared primitives, no business logic

API 层模式

// Pure API function
function getUsers(params?: GetUsersParams): Promise<UsersResponse> {
    return api.get("/users", { params });
}

// Query hook wrapping the API function
function useUsers(params?: GetUsersParams) {
    return useQuery({
        queryKey: ["users", params],
        queryFn: () => getUsers(params),
    });
}

状态管理边界

状态类型	解决方案	示例
服务端状态	TanStack Query	用户数据、帖子、API 响应
客户端状态（全局）	Zustand / Jotai	主题、侧边栏展开状态、用户偏好设置
客户端状态（本地）	useState / useReducer	表单输入、切换项、模态框展开状态
URL 状态	URL 搜索参数 / 路由器	筛选条件、分页、当前标签页
表单状态	React Hook Form	多步骤表单、验证

不要混用服务端状态和客户端状态。 永远不要将查询数据复制到 useState 中。

错误层级

App Error Boundary          → catches unrecoverable crashes
  └── Route Error Boundary     → catches route-level failures, shows retry
        └── Feature Error Boundary   → catches feature-specific errors

测试策略

层	工具	测试内容
组件	Testing Library	渲染输出、用户交互、a11y
Hooks	renderHook	状态变化、副作用
API	MSW	请求/响应处理、错误状态
集成	Testing Library + MSW	完整功能流程（渲染 → 交互 → 验证）
E2E	Playwright	关键用户旅程

约定

项目	约定	示例
组件	PascalCase	UserCard.tsx
Hooks	camelCase，使用 use 前缀	useUsers.ts
工具函数	camelCase	formatDate.ts
类型	PascalCase	User、CreateUserInput
常量	UPPER_SNAKE_CASE	MAX_RETRIES
目录	kebab-case	user-settings/
文件	kebab-case	user-card.tsx

导入

使用路径别名，避免使用过深的相对导入：

import { Button } from "@/components/ui/button";
import { useUsers } from "@/features/users/api";

在 tsconfig.json 中将 @/ 配置为 src/ 的别名。