前端编码规范最佳实践指南

前端编码规范最佳实践指南一、命名规范（一）变量命名。变量命名应遵循驼峰命名法，首字母小写，单词首字母大写，如userName、totalCount。禁止使用拼音、中文或特殊字符命名变量。数据类型名称应使用首字母大写形式，如Date、Array。（二）函数命名。函数命名应使用动宾结构，如calculateTotal、fetchData。禁止使用缩写，如log、init等。函数名应清晰表达其功能，如getUserProfile而非getUser。（三）类命名。类命名应使用帕斯卡命名法，首字母大写，如UserInfo、ProductManager。类名应使用名词或名词短语，如ButtonGroup、ShoppingCartService。（四）常量命名。常量命名应使用全大写字母，单词间用下划线分隔，如MAX_TIMEOUT、DEFAULT_API_URL。常量名应具有描述性，如MAX_PAGE_SIZE而非PSIZE。二、代码结构（一）文件组织。每个功能模块应独立成文件，文件名应与模块名称一致，如用户管理模块命名为userManagement.js。禁止在一个文件中包含不相关的代码。（二）模块划分。大型应用应按功能模块划分，如路由模块、状态管理模块、API调用模块。每个模块应包含独立的入口文件和导出语句。（三）代码分层。前端代码应遵循分层结构，自上而下依次为：页面层、组件层、业务逻辑层、工具层。各层之间应严格分离，页面层只负责展示，业务逻辑层只处理数据。（四）组件设计。组件命名应使用名词，如Button、Modal、Table。组件文件应包含三个部分：样式、脚本、模板。样式使用CSS模块化，脚本包含逻辑和生命周期，模板使用Vue或React语法。（五）目录规范。项目目录结构应清晰，遵循层级关系，如src/components/atoms/Button.vue。原子组件放在atoms目录，分子组件放在molecules目录，组织组件放在organisms目录。三、代码质量（一）代码复用。通用功能应封装为工具函数或组件，如日期格式化、表单校验。工具函数应放在utils目录，组件应按功能分类存放。（二）性能优化。关键渲染路径应优化，如避免内联JS、使用虚拟滚动、延迟加载。使用ChromeDevTools分析性能瓶颈，优先解决首屏加载问题。（三）错误处理。所有API调用应包含错误处理，前端捕获异常后应显示友好提示。使用try-catch结构，统一处理异常，避免白屏问题。（四）代码检查。使用ESLint和Prettier进行代码格式化，配置统一风格。提交前必须通过所有检查，禁止提交未检查的代码。（五）代码评审。所有代码变更必须经过至少两人评审，评审重点包括：是否符合规范、是否可读、是否有性能问题。评审通过后方可合并。四、组件开发（一）原子组件。原子组件应最小化功能，如Button、Input、Icon。每个原子组件只实现单一功能，避免过度设计。（二）分子组件。分子组件由原子组件组合而成，如SearchBar（包含Input和Button）、Card（包含Title和Content）。（三）组织组件。组织组件由多个分子组件构成，如Dashboard（包含多个Card）、Form（包含多个Input）。（四）组件状态。组件状态分为本地状态和全局状态，本地状态使用useState或ReactContext，全局状态使用Redux或Vuex。（五）组件通信。组件间通信遵循以下原则：父传子使用props，子传父使用事件，兄弟组件使用Context或状态管理库。五、API交互（一）请求规范。所有API请求必须使用统一的请求库，如axios或fetch。请求参数应使用JSON格式，响应数据使用统一的JSON结构。（二）错误码。API错误码应遵循HTTP标准，自定义错误码以E开头，如E1001表示参数错误。前端根据错误码显示不同提示。（三）缓存策略。关键数据应使用前端缓存，如用户信息、配置项。使用localStorage或sessionStorage存储，设置合理的过期时间。（四）请求合并。连续的相同请求应合并，如用户连续点击两次保存按钮。使用防抖或节流机制避免重复请求。（五）安全防护。所有敏感数据必须加密传输，如使用HTTPS。API请求必须验证token，防止未授权访问。六、样式规范（一）CSS模块化。使用CSS模块化避免样式冲突，如Button_buttonPrimary_.css。文件名使用模块名_样式名_后缀。（二）响应式设计。使用媒体查询实现响应式布局，如@media（max-width:768px）。断点设置应遵循移动优先原则。（三）颜色系统。定义全局颜色变量，如primaryColor、secondaryColor。使用CSS变量统一管理，如--color-primary。（四）字体系统。定义全局字体变量，如primaryFont、secondaryFont。使用CSS变量控制，如--font-primary。（五）布局规范。使用Flexbox或Grid实现布局，避免使用绝对定位。布局文件应包含断点说明，如Mobile、Tablet、Desktop。七、测试规范（一）单元测试。每个组件必须编写单元测试，使用Jest或Mocha。测试覆盖核心功能，如事件处理、状态变更。（二）集成测试。关键流程必须编写集成测试，如用户注册流程。使用Cypress或Selenium模拟用户操作。（三）端到端测试。核心功能必须编写端到端测试，使用Cypress或Selenium。测试覆盖完整业务流程，如登录-浏览-下单。（四）测试覆盖率。单元测试覆盖率应达到80%以上，集成测试覆盖率应达到60%以上。低于标准的项目不得提交。（五）测试环境。所有测试必须在隔离环境执行，避免污染生产环境。测试报告应定期审查，如每周五下午。八、文档规范（一）组件文档。每个组件必须编写文档，说明功能、props、使用示例。文档使用Storybook或组件文档工具。（二）API文档。所有API必须编写文档，说明请求参数、响应结构、错误码。使用Swagger或API文档工具。（三）设计文档。核心设计必须编写文档，说明设计思路、实现方案、优缺点。文档应包含流程图和时序图。（四）更新日志。每次变更必须记录在更新日志，说明变更内容、原因、影响。日志按版本号组织，如v1.0.1。（五）知识库。团队知识库应包含常见问题、解决方案、最佳实践。新成员必须阅读知识库，如入职第一天。九、团队协作（一）分支策略。使用GitFlow分支策略，主分支为master，开发分支为develop，功能分支为feature/模块名。（二）代码合并。所有代码合并必须通过CodeReview，禁止直接合并。合并前必须确保所有测试通过。（三）冲突解决。分支冲突必须由创建者解决，禁止推力解决。冲突解决后必须自测，确保功能正常。（四）版本控制。所有变更必须提交到版本库，提交信息必须清晰，如"Fix:用户列表加载缓慢"。提交信息使用动词开头，如Fix、Optimize、Add。（五）团队沟通。每日站会必须讨论进度和问题，如"今天完成用户列表优化，明天开始开发订单模块"。会议记录必须存档。十、附则（一）规范更新。本规范每季度审查一次，如3月、6月、9月、12月。重大变更必须发布新版本，如v2.0.0。（二）规范培训。新成员必须接受规范培训，考核合格后方可参与开发。培训内容包括命名