本综合指南概述了使用现代网页技术（包括 ReactJS、NextJS、Redux、TypeScript、JavaScript、HTML、CSS 和 UI 框架）进行开发的最佳实践、约定和标准。 开发哲学 – 编写干净、可维护和可扩展的代码 – 遵循 SOLID 原则 – 优先选择函数式和声明式编程模式，而非命令式 – 强调类型安全和静态分析 – 采用组件驱动开发 代码实施指南 规划阶段 – 从逐步规划开始 – 在实现之前编写详细的伪代码 – 记录组件架构和数据流 – 考虑边缘案例和错误场景 代码风格 – 使用制表符进行缩进 – 字符串使用单引号（除非需要避免转义） – 省略分号（除非需要消歧义） – 消除未使用的变量 – 关键字后加空格 – 函数声明的括号前加空格 – 始终使用严格相等（===），而非宽松相等（==） – 对中缀运算符添加空格 – 逗号后加空格 – 将 else 语句保持在闭合大括号同一行 – 多行 if 语句使用大括号 – 始终在回调中处理错误参数 – 行长度限制为 80 个字符 – 在多行对象/数组字面量中使用尾随逗号 命名约定 一般规则 – 组件、类型定义和接口使用 PascalCase – 目录名（例如：components/auth-wizard）使用 kebab-case – 文件名（例如：user-profile.tsx）使用 kebab-case – 变量、函数、方法、Hook、属性和 props 使用 camelCase – 环境变量、常量和全局配置使用大写字母（UPPERCASE） 具体命名模式 – 事件处理函数前缀使用 ‘handle’：handleClick、handleSubmit – 布尔变量前缀使用动词：isLoading、hasError、canSubmit – 自定义 Hook 前缀使用 ‘use’：useAuth、useForm – 使用完整单词而非缩写，除非是： – err（error） – req（request） – res（response） – props（properties） – ref（reference） React 最佳实践 组件架构 – 使用 TypeScript 接口的函数组件 – 使用 function 关键字定义组件 – 将可重用逻辑提取到自定义 Hook 中 – 实现适当的组件组合 – 战略性地使用 React.memo() 来提升性能 – 在 useEffect Hook 中实现适当的清理 React 性能优化 – 使用 useCallback 来记忆回调函数 – 使用 useMemo 来处理开销大的计算 – 避免在 JSX 中定义内联函数 – 通过动态导入实现代码分割 – 在列表中实现适当的 key 属性（避免使用索引作为 key） Next.js 最佳实践 核心概念 – 利用 App Router 进行路由 – 实现适当的元数据管理 – 使用适当的缓存策略 – 实现合适的错误边界 组件和功能 – 使用 Next.js 内置组件： – 图像组件用于优化图像 – 链接组件用于客户端导航 – 脚本组件用于外部脚本 – 头部组件用于元数据 – 实现适当的加载状态 – 使用适当的数据获取方法 服务器组件 – 默认使用服务器组件 – 使用 URL 查询参数进行数据获取和服务器状态管理 – 仅在必要时使用 ‘use client’ 指令： – 事件监听器 – 浏览器 API – 状态管理 – 仅限客户端的库 TypeScript 实施 – 启用严格模式 – 为组件的 props、状态和 Redux 状态结构定义清晰的接口 – 使用类型守卫安全地处理潜在的未定义或 null 值 – 在需要灵活类型的函数、动作和切片中应用泛型 – 利用 TypeScript 实用类型（Partial、Pick、Omit）编写更清晰和可重用的代码 – 定义对象结构时优先使用接口而非类型，特别是在扩展时 – 使用映射类型动态创建现有类型的变体 UI 和样式 组件库 – 使用 Shadcn UI 进行一致且可访问的组件设计 – 集成 Radix UI 原件以实现可定制和可访问的 UI 元素 – 应用组合模式以创建模块化和可重用组件 样式指南 – 使用 Tailwind CSS 进行样式设计 – 使用 Tailwind CSS 实现以实用为主的可维护样式 – 根据移动优先和响应式原则进行设计，以提高跨设备的灵活性 – 使用 CSS 变量或 Tailwind 的暗黑模式特性实现暗黑模式 – 确保颜色对比度符合可访问性标准，以保证可读性 – 维护一致的间距值，以建立视觉和谐 – 定义主题颜色和间距的 CSS 变量，以支持轻松的主题更改和可维护性 状态管理 局部状态 – 使用 useState 管理组件级状态 – 对于复杂状态，使用 useReducer – 使用 useContext 管理共享状态 – 实现适当的状态初始化 全局状态 – 使用 Redux Toolkit 管理全局状态 – 使用 createSlice 定义状态、减速器和动作 – 除非必要，避免使用 createReducer 和 createAction – 规范化状态结构，避免深嵌套数据 – 使用选择器封装状态访问 – 避免大的、包罗万象的切片；按功能分离关注点 错误处理与验证 表单验证 – 使用 Zod 进行模式验证 – 实现适当的错误信息 – 使用合适的表单库（例如：React Hook Form） 错误边界 – 使用错误边界优雅地捕获和处理 React 组件树中的错误 – 将捕获的错误记录到外部服务（例如：Sentry）以便跟踪和调试 – 设计用户友好的回退 UI，当发生错误时显示，使用户保持知情而不影响应用运行 测试 单元测试 – 编写全面的单元测试以验证单个函数和组件 – 使用 Jest 和 React Testing Library 可靠高效地测试 React 组件 – 遵循 Arrange-Act-Assert 等模式，以确保测试的清晰性和一致性 – 模拟外部依赖和 API 调用，以隔离单元测试 集成测试 – 专注于用户工作流，以确保应用功能 – 正确设置和拆除测试环境，以保持测试的独立性 – 有选择地使用快照测试，以捕获意外的 UI 变化，而不依赖于它 – 借助测试工具（例如：RTL 中的 screen）编写更清晰和可读的测试 可访问性（a11y） 核心要求 – 使用语义化 HTML 创建有意义的结构 – 在需要的地方应用准确的 ARIA 属性 – 确保完整的键盘导航支持 – 有效管理焦点顺序和可见性 – 维护可访问的颜色对比度 – 遵循合乎逻辑的标题层级 – 使所有交互元素可访问 – 提供清晰且可访问的错误反馈 安全性 – 实施输入清理以防止 XSS 攻击 – 使用 DOMPurify 清理 HTML 内容 – 使用适当的身份验证方法 国际化（i18n） – 使用 next-i18next 进行翻译 – 实现适当的区域识别 – 使用适当的数字和日期格式化 – 实现适当的 RTL 支持 – 使用适当的货币格式化 文档 – 使用 JSDoc 进行文档编写 – 文档化所有公共函数、类、方法和接口 – 在适当时添加示例 – 使用完整的句子和适当的标点符号 – 保持描述清晰简练 – 使用正确的 Markdown 格式 – 使用正确的代码块 – 使用正确的链接 – 使用正确的标题 – 使用正确的列表