前端编码规范之工程师规范

• 项目结构

  • 一般项目结构。

    – Example –

    
    // 大型项目
    -projectName
    ---/html/
    |---- /index                       
    |---- /index/index.html         // 首页  
    |---- /user                     // 与用户相关的页面  
    |---- /user/login.html          // 登录页
    ---/css/
    |---- /base.css                 // 重置浏览器样式    
    |---- /page                     // 逻辑页面的css
    |---- /page/pagename.css        // 单独书写的css
    |---- /common.css               // css通用样式库
    ---/js/
    |---- /lib                      // 公用组件
    |---- /lib/jquery.2.2.3.min.js  // 调用jq库文件 
    |---- /page                     // 逻辑页面的js
    |---- /page/pagename.js         // 单独书写的js
    |---- /common.js                // 公用方法
    ---/img/
    |---- /page                     // 页面对应的图片
    |---- /page/wap                 // 手机端图片夹
    |---- /page/wap/wap_icon.png    // 手机端图标
    |---- /logo.png                 // 公用图片
    
    // 中小型项目
    -projectName
    ---/static/
    |---- /css/
    |------- /base.css                 // 重置浏览器样式
    |------- /common.css               // css通用样式
    |------- /index.css                // 首页样式
    |------- /login.css                // 登录页样式
    |---- /js/
    |------- /lib                      // 公用组件
    |------- /lib/jquery.2.2.3.min.js  // 调用jq库文件 
    |------- /common.js                // 通用js
    |------- /index.js                 // 首页js
    |------- /login.js                 // 登录页js
    |---- /img/
    |------- /page                     // 页面对应的图片
    |------- /page/wap                 // 手机端图片夹
    |------- /page/wap/wap_icon.png    // 手机端图标
    |------- /logo.png                 // 公用图片
    ---/index.html                     // 首页  
    ---/login.html                     // 登录页  
    

  • vueCli项目结构。

    • api 目录

      1.文件、变量命名要与后端保持一致。
      2.此目录对应后端 API 接口，按照后端一个 controller 一个 api js 文件。若项目较大时，可以按照业务划分子目录，并与后端保持一致。
      3.api 中的方法名字要与后端 api url 尽量保持语义高度一致性。
      4.对于 api 中的每个方法要添加注释，注释与后端 swagger 文档保持一致。

    • assets 目录

      assets 为静态资源，里面存放 images, styles, icons 等静态资源，静态资源命名格式为 kebab-case

    • components 目录

      此目录应按照组件进行目录划分，目录命名为 KebabCase，组件命名规则也为 KebabCase

    • constants 目录

      此目录存放项目所有常量，如果常量在 vue 中使用，请使用 vue-enum 插件

    • router 目录

      router 尽量按照 views 中的结构保持一致

    • store 目录

      store 按照业务进行拆分不同的 js 文件

    – Example –

    src                               // 源码目录
    |-- api                              // 所有api接口
    |-- assets                           // 静态资源，images, icons, styles等
    |-- components                       // 公用组件
    |-- config                           // 配置信息
    |-- constants                        // 常量信息，项目所有Enum, 全局常量等
    |-- directives                       // 自定义指令
    |-- filters                          // 过滤器，全局工具
    |-- datas                            // 模拟数据，临时存放
    |-- lib                              // 外部引用的插件存放及修改文件
    |-- mock                             // 模拟接口，临时存放
    |-- plugins                          // 插件，全局使用
    |-- router                           // 路由，统一管理
    |-- store                            // vuex, 统一管理
    |-- themes                           // 自定义样式主题
    |-- views                            // 视图目录
    |   |-- role                             // role模块名
    |   |-- |-- role-list.vue                    // role列表页面
    |   |-- |-- role-add.vue                     // role新建页面
    |   |-- |-- role-update.vue                  // role更新页面
    |   |-- |-- index.less                      // role模块样式
    |   |-- |-- components                      // role模块通用组件文件夹
    |   |-- employee                         // employee模块
    

  • nuxtJs项目结构。

    – Example –

    |-- .nuxt               // Nuxt自动生成，临时的用于编辑的文件，build
    |-- assets              // 用于组织未编译的静态资源入LESS、SASS 或 JavaScript
    |-- components          // 用于自己编写的Vue组件，比如滚动组件，日历组件，分页组件
    |-- layouts             // 布局目录，用于组织应用的布局组件，不可更改。
    |-- middleware          // 用于存放中间件
    |-- pages               // 用于存放写的页面，我们主要的工作区域
    |-- plugins             // 用于存放JavaScript插件的地方
    |-- static              // 用于存放静态资源文件，比如图片
    |-- store               // 用于组织应用的Vuex 状态管理。
    |-- .editorconfig       // 开发工具格式配置
    |-- .eslintrc.js        // ESLint的配置文件，用于检查代码格式
    |-- .gitignore          // 配置git不上传的文件
    |-- nuxt.config.json    // 用于组织Nuxt.js应用的个性化配置，已覆盖默认配置
    |-- package-lock.json   // npm自动生成，用于帮助package的统一性设置的，yarn也有相同的操作
    |-- package-lock.json   // npm自动生成，用于帮助package的统一性设置的，yarn也有相同的操作
    |-- package.json        // npm包管理配置文件
    

• 工程师相关要求

  • 开发准备。

    • 了解产品/“故事需求”/设计

      在迭代计划会、开发之前，了解 产品/“故事需求”/设计是非常有必要的。
      1.了解产品设计（交互、视觉）和项目成员；
      2.了解产品面向的设备和平台；
      3.了解产品对兼容性的要求以及是否采用响应式设计等；
      4.了解产品要使用的技术（WEB技术、桌面技术、APP技术、模板语言、混合模式等）；
      5.了解“故事”的期望目标。

    • 在交互或视觉会议中结合技术要求，提出疑问和见解

      提出可能存在的问题（技术实现问题、性能问题等），协商解决方案（如优雅退化）并达成共识。
      提出已有新技术可能在产品中的应用场景，协助产品创新。

    • 在迭代计划会议之前结合“故事”和以往产品功能，提出疑问、可能造成的连带影响

      提出疑问，商讨确认最终需求和解决方案。

    • 预算人力和时间

      根据个人能力，合理预估“故事”开发时间
      预估时间与考虑开发、修改bug时间

  • 开发过程。

    • 关于调研的“故事”

      技术调研的内容可以先咨询经验丰富的前端工程师或前端技术组。
      进行技术调研，产出技术demo，展示demo 或者 在tapd中反馈调研结果。
      反馈调用结果格式尽量以：
      ---- 结果：能实现、能否完全符合期望、不能完全符合原因及相关资料、提出妥协建议方案、调研相关资料、
      ---- 结果：不能实现、阐述不能实现原因、调研相关资料

    • 关于和UI设计师的合作

      UI效果图、切图建议使用蓝湖工具，切勿由开发工程师自己使用psd图进行切图、查看样式。
      交互方式有特殊之处，设计师需提供交互原型图或者设计图标注说明。

    • 关于和后端工程师的合作

      接口对接，建议有api文档进行对接,切勿口头、私聊对接。工具有：wagger、ShowDoc
      api文档必须元素含：请求地址、请求方式、验签加密规则（不必须）、请求参数及参数说明、返回参数及参数说明、备注（特殊情况必须）
      双方协作，切勿在自己一方影响对方开发进度。建议开发之前约定好双方交付时间

    • 关于资源的合理利用

      图片资源建议使用压缩后图片（蓝湖下载切图可勾选压缩选项）
      字体资源合理使用，切勿使用太大、多种字体。因为字体文件一般较大，影响用户体验，尤其是APP开发
      资源文件切勿乱放，合理放置项目框架的合理文件夹下

    • 多人员并行开发

      在开发分支上并行开发,开发完成在由前端开发负责人合并到主分支上。切勿在主分支上开发
      建议每天下班进行代码提交。切勿等一个需求开发完再提交
      提交描述一定要体现出此次提交修改或者完成的功能。切勿使用‘asd’、‘…’、‘修改’

    • 不要为了完成“故事”，省事而开发

      为了完成“故事”而开发，可能会导致完成一个功能，出现其他bug；也可能导致代码冗余严重，后期难以维护
      为了省事而开发，可能会在不久的将来难以维护代码（俗称：技术负债）
      切勿“头痛医头脚痛医脚”方式开发和修改bug

    • 开发中的性能思考

      切勿为了快速完成“故事”，不管设备性能的消耗。
      比如：能用动画实现的效果，切勿使用gif图、图片

    • B端产品、C端产品的不公平对待

      不要因为是B端产品而说：这是B端产品，内部人员使用，功能实现，能用就行。
      B端产品用户体验确实可以不及C端产品，但是在时间充裕的情况下，尽可能简单优化下用户体验。

    • 注意提取剥离

      对可重复结构、元素、样式、功能（逻辑）进行最小化剥离封装

    • 关于临时“故事”

      临时插入的“故事”，对于公司或者团队来说一定是紧急（影响公司形象、造成公司利益损失、对客户造成形象/利益损失）。
      产品经理插入临时“故事”，一定先说明紧急原因。
      临时“故事”确认插入，开发工程师需耐心接受，并紧急解决。如果可能会造成计划“故事”的搁置，一定要当场跟产品经理说明临时故事插入的风险

  • 开发产出。

    • 自测联调。

      更新、合并、解决冲突、提交。
      对自己的代码进行全面的多或者单设备测试和兼容性测试。
      如果自测过程中发现别人写的代码有问题，及时反馈。
      视觉效果（包括UI、交互）还原度必须大于90%（主要：图片清晰、整体布局还原度、文字样式、适配多设备）

    • 提交验收。

      发布测试，提交给设计师，进行效果验收。
      发布测试，提交给测试工程师进行功能测试以及bug回归。
      发布测试，提交给产品经理进行整体验收。
      如有必要，提交代码给前端负责人进行code review（code review依据来源：兼容性、HTML规范和CSS规范、javascript规范、vue规范）。

    • BUG及时处理。

      bug的及时处理，是保障产品正常上线/发版的重要环节。
      测试工程师需给开发工程师预留处理bug时间。
      对于测试工程师提出的bug，按照优先级及时处理，给测试工程师回归bug时间。

    • 交接说明。

      如果开发模式不是前后端完全分离的，那么 交接说明 是非常有必要的。
      交代内容大致：需要后续开发工程师注意的地方、整体架构、代码的解释说明。

    • 变更维护

      如果未经过需求变更和设计变更，原则上不允许直接进行开发变更。
      如确实要变更，建议产品经理重新创建“故事”并说明变更原因。
      功能的后期维护也是会花费开发工程师的时间，开发人员应该主动索要维护“故事”。