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