本综合指南概述了使用现代网页技术（包括 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 格式
– 使用正确的代码块
– 使用正确的链接
– 使用正确的标题
– 使用正确的列表
This comprehensive guide outlines best practices, conventions, and standards for development with modern web technologies including ReactJS, NextJS, Redux, TypeScript, JavaScript, HTML, CSS, and UI frameworks.
Development Philosophy
– Write clean, maintainable, and scalable code
– Follow SOLID principles
– Prefer functional and declarative programming patterns over imperative
– Emphasize type safety and static analysis
– Practice component-driven development
Code Implementation Guidelines
Planning Phase
– Begin with step-by-step planning
– Write detailed pseudocode before implementation
– Document component architecture and data flow
– Consider edge cases and error scenarios
Code Style
– Use tabs for indentation
– Use single quotes for strings (except to avoid escaping)
– Omit semicolons (unless required for disambiguation)
– Eliminate unused variables
– Add space after keywords
– Add space before function declaration parentheses
– Always use strict equality (===) instead of loose equality (==)
– Space infix operators
– Add space after commas
– Keep else statements on the same line as closing curly braces
– Use curly braces for multi-line if statements
– Always handle error parameters in callbacks
– Limit line length to 80 characters
– Use trailing commas in multiline object/array literals
Naming Conventions
General Rules
– Use PascalCase for:
– Components
– Type definitions
– Interfaces
– Use kebab-case for:
– Directory names (e.g., components/auth-wizard)
– File names (e.g., user-profile.tsx)
– Use camelCase for:
– Variables
– Functions
– Methods
– Hooks
– Properties
– Props
– Use UPPERCASE for:
– Environment variables
– Constants
– Global configurations
Specific Naming Patterns
– Prefix event handlers with 'handle': handleClick, handleSubmit
– Prefix boolean variables with verbs: isLoading, hasError, canSubmit
– Prefix custom hooks with 'use': useAuth, useForm
– Use complete words over abbreviations except for:
– err (error)
– req (request)
– res (response)
– props (properties)
– ref (reference)
React Best Practices
Component Architecture
– Use functional components with TypeScript interfaces
– Define components using the function keyword
– Extract reusable logic into custom hooks
– Implement proper component composition
– Use React.memo() strategically for performance
– Implement proper cleanup in useEffect hooks
React Performance Optimization
– Use useCallback for memoizing callback functions
– Implement useMemo for expensive computations
– Avoid inline function definitions in JSX
– Implement code splitting using dynamic imports
– Implement proper key props in lists (avoid using index as key)
Next.js Best Practices
Core Concepts
– Utilize App Router for routing
– Implement proper metadata management
– Use proper caching strategies
– Implement proper error boundaries
Components and Features
– Use Next.js built-in components:
– Image component for optimized images
– Link component for client-side navigation
– Script component for external scripts
– Head component for metadata
– Implement proper loading states
– Use proper data fetching methods
Server Components
– Default to Server Components
– Use URL query parameters for data fetching and server state management
– Use 'use client' directive only when necessary:
– Event listeners
– Browser APIs
– State management
– Client-side-only libraries
TypeScript Implementation
– Enable strict mode
– Define clear interfaces for component props, state, and Redux state structure.
– Use type guards to handle potential undefined or null values safely.
– Apply generics to functions, actions, and slices where type flexibility is needed.
– Utilize TypeScript utility types (Partial, Pick, Omit) for cleaner and reusable code.
– Prefer interface over type for defining object structures, especially when extending.
– Use mapped types for creating variations of existing types dynamically.
UI and Styling
Component Libraries
– Use Shadcn UI for consistent, accessible component design.
– Integrate Radix UI primitives for customizable, accessible UI elements.
– Apply composition patterns to create modular, reusable components.
Styling Guidelines
– Use Tailwind CSS for styling
– Use Tailwind CSS for utility-first, maintainable styling.
– Design with mobile-first, responsive principles for flexibility across devices.
– Implement dark mode using CSS variables or Tailwind’s dark mode features.
– Ensure color contrast ratios meet accessibility standards for readability.
– Maintain consistent spacing values to establish visual harmony.
– Define CSS variables for theme colors and spacing to support easy theming and maintainability.
State Management
Local State
– Use useState for component-level state
– Implement useReducer for complex state
– Use useContext for shared state
– Implement proper state initialization
Global State
– Use Redux Toolkit for global state
– Use createSlice to define state, reducers, and actions together.
– Avoid using createReducer and createAction unless necessary.
– Normalize state structure to avoid deeply nested data.
– Use selectors to encapsulate state access.
– Avoid large, all-encompassing slices; separate concerns by feature.
Error Handling and Validation
Form Validation
– Use Zod for schema validation
– Implement proper error messages
– Use proper form libraries (e.g., React Hook Form)
Error Boundaries
– Use error boundaries to catch and handle errors in React component trees gracefully.
– Log caught errors to an external service (e.g., Sentry) for tracking and debugging.
– Design user-friendly fallback UIs to display when errors occur, keeping users informed without breaking the app.
Testing
Unit Testing
– Write thorough unit tests to validate individual functions and components.
– Use Jest and React Testing Library for reliable and efficient testing of React components.
– Follow patterns like Arrange-Act-Assert to ensure clarity and consistency in tests.
– Mock external dependencies and API calls to isolate unit tests.
Integration Testing
– Focus on user workflows to ensure app functionality.
– Set up and tear down test environments properly to maintain test independence.
– Use snapshot testing selectively to catch unintended UI changes without over-relying on it.
– Leverage testing utilities (e.g., screen in RTL) for cleaner and more readable tests.
Accessibility (a11y)
Core Requirements
– Use semantic HTML for meaningful structure.
– Apply accurate ARIA attributes where needed.
– Ensure full keyboard navigation support.
– Manage focus order and visibility effectively.
– Maintain accessible color contrast ratios.
– Follow a logical heading hierarchy.
– Make all interactive elements accessible.
– Provide clear and accessible error feedback.
Security
– Implement input sanitization to prevent XSS attacks.
– Use DOMPurify for sanitizing HTML content.
– Use proper authentication methods.
Internationalization (i18n)
– Use next-i18next for translations
– Implement proper locale detection
– Use proper number and date formatting
– Implement proper RTL support
– Use proper currency formatting
Documentation
– Use JSDoc for documentation
– Document all public functions, classes, methods, and interfaces
– Add examples when appropriate
– Use complete sentences with proper punctuation
– Keep descriptions clear and concise
– Use proper markdown formatting
– Use proper code blocks
– Use proper links
– Use proper headings
– Use proper lists
