Web前端模块化构建规范

Web前端模块化构建规范一、总则规范（一）适用范围。本规范适用于公司所有Web前端项目，涵盖模块化设计、组件开发、代码组织、构建流程等全生命周期管理，确保前端代码质量与开发效率。（二）核心原则。坚持高内聚、低耦合、可复用、易维护的原则，通过标准化模块化构建实现技术资产沉淀与跨团队协作。二、模块划分标准（一）功能模块划分。依据业务边界划分模块，单个模块应聚焦单一职责，模块间通过接口交互，禁止跨模块直接调用。模块命名需符合"模块类型-业务领域-功能描述"格式，如"UI-用户管理-登录组件"。（二）组件层级规范。基础组件（如按钮、输入框）独立为一级模块；业务组件（如表单、列表）为二级模块；功能单元（如筛选器）为三级模块，层级关系需在文档中明确展示。（三）模块粒度控制。基础模块粒度不小于20行代码，业务模块不超过500行，超过1000行需拆分为子模块，通过抽象工厂统一管理。三、代码组织规范（一）目录结构标准。模块根目录必须包含：/src（源码）、/test（测试）、/docs（文档）、/config（配置）四个一级目录，采用分层递归结构。（二）文件命名规范。组件文件名必须使用驼峰式命名法（如UserForm.vue），工具类文件以功能描述+工具后缀（如FormatUtil.js），配置文件统一为config.js。（三）代码格式统一。必须使用ESLint+Prettier组合，配置文件定义如下：```json{"rules":{"semi":"error","quotes":["error","single"],"no-console":"warn"}}```四、组件开发标准（一）Props设计规范。必须使用具名Props，类型声明采用联合类型，默认值设置在类型声明后，如：```jsxconstButton={props:{type:{type:Stringas（）=>'primary'|'ghost'|'default',default:'default'}}}```（二）状态管理要求。组件内部状态必须封装在this.$store中，禁止使用window或全局变量，跨组件状态传递需通过Vuex模块化管理。（三）响应式设计。所有依赖DOM的变量必须使用Vue.set进行响应式绑定，避免this.$nextTick外挂使用，如：```jsVue.set（this.list,index,{name:'newname'}）```五、构建流程规范（一）依赖管理要求。必须使用npm7+版本，包管理文件采用语义化版本，禁用devDependencies安装生产环境依赖。（二）自动化构建。必须配置Webpack5+，核心插件配置要求：```json{"module":{"rules":[{test:/\.vue$/,loader:"vue-loader",options:{loaders:{scss:"sass-loader"}}}]}}```（三）构建发布流程。必须实现CI/CD流水线，包含单元测试、代码覆盖率、静态检查三个必经阶段，发布流程需经过CodeReview。六、文档管理规范（一）组件文档标准。每个组件必须提供JSON格式文档，包含：```json{"title":"用户表单","description":"标准用户信息收集表单","props":[{"name":"model","type":"Object","required":true},{"name":"rules","type":"Array"}]}```（二）版本控制要求。文档与代码必须同步更新，版本号采用MAJOR.MINOR.PATCH格式，每次变更需关联JIRA任务号。（三）文档生成工具。必须使用Storybook6+自动生成组件文档，生成路径配置在package.json中：```json"scripts":{"docs":"sbbuild"}```七、团队协作规范（一）代码评审要求。所有模块化提交必须通过至少两名成员评审，评审重点包括：接口定义一致性、命名规范符合度、测试覆盖率达标。（二）冲突解决机制。模块化开发必须遵循"先开发后合并"原则，使用Gitrebase解决冲突，禁止直接commit到主干分支。（三）知识沉淀要求。每个模块开发完成后必须输出技术文档，包含接口说明、使用示例、注意事项，存档在GitLabWiki中。八、附则说明（一）实施时间。本规范自发布之日起30日内完成全面落地，