本文是在项目开发中总结的一些前端编码规范,以及接口规范等。

工程规范:

  • 简单模块目录:在 views 目录下建立目录,并在目录下建立页面文件;
  • 复杂模块目录:在 页面目录下增加 components 子目录;
    ├── src
        ├── views
              ├── moduleA
                      └── index.vue
              ├── moduleB
                      ├── components
                            ├── a.vue
                            └── b.vue
                      └── index.vue
    
  • 跨模块的组件目录:

    • 无需使用公共组件的页面:在页面的同级目录增加 components 目录;
      ├── src
          ├── views
                ├── moduleA
                ├── moduleB
                        └── components
                              ├── a.vue
                              └── b.vue
      
  • 需使用公共组件的页面:在页面中直接导入npm组件;

命名规范:

  • 目录命名:页面/普通目录命名使用小驼峰,公共组件目录名使用大驼峰;

  • 文件命名:使用英文小写,小驼峰方式,例: dashboard, errorPage;

  • 特定功能的文件命名:如修改页面 xxxUpdate;

  • 原则:能描述清楚目录/文件的作用,若非专业简写词汇,尽量不使用简写。
    该原则同样适用于 CSS、JS 的命名。

HTML规范:

  • 引号:在标签属性上使用双引号;
  • 空格:缩进使用2个空格;
  • 换行:标签属性超过3个须换行;

CSS规范:

  • 缩进:使用2个空格;
  • 换行:每个属性占一行;
  • 分号:每个属性声明结尾都要加分号;
  • 媒体查询:尽量靠近规则,不要放底部;
  • 命名:
    • 类名使用小写字母并以 - 分隔;
    • id采用小驼峰式命名;
    • less/scss中的变量、函数、混合、placeholder采用小驼峰式命名;
  • 需要空格的情况:
    • 多个类名的 , 后及属性名的 : 后;
    • 选择器 > , + , ~ 前后;
      .element > .dialog {
        ...
      }
      
      .dialog {
        color: #f00 !important;
        background-color: rgba(0, 0, 0, .5);
      }
      
  • 需要空行的情况:不同的选择器之间需要空一行;
    .dialog {
      color: #f00;
      font-size: 16px;
    
      &:after {
        ...
      }
    }
    
  • 需要换行的情况:
    • { 后和 } 前需要换行;
    • 每个属性独占一行;
    • 多个规则的分隔符 , 后;
  • 杂项:
    • 属性值 0 后面不要加单位;
    • 尽量少用或不使用 !important;

JS规范:

  • 引号:字符使用单引号;
  • 缩进:使用2个空格;
  • 变量命名:
    • 标准变量命名使用驼峰结构;
    • 常量全大写,用下划线连接;
    • 构造函数,大写第一个字母;
    • 属性行、数组结尾加逗号;
  • 函数:
    • 无论是函数声明还是函数表达式,( 前不要空格,但 { 前要有空格;
    • 参数之间用 , 分隔,注意逗号后有一个空格;
    • 匿名函数不要空格;
    doSomething(item);
    
    const doSomething = (a, b, c) => {
      // ...
    };
    
  • 对象:属性名不要加引号;
  • undefined:使用typeof和字符串 undefined 对变量进行判断;
  • 杂项:
    • 对上下文this的引用使用 _this, _self, that其中一个来命名;
    • 括号:if, else, for, while, do, switch, try, catch, finally, with 这些关键字后的小括号前后都有1个空格,且必须有大括号(即使代码块的内容只有一行)
    • 路径:超过2层使用别名 @/ ,不要使用多个 ../
  • JSLint:
    • debugger不要出现在提交的代码里;
    • 模板字符串使用 ,而不是 ‘’ 和 + 拼接;
    • 三元运算符有空格,且最多两层结构;
    • 单行注释语句后有且只有一个空格,例: // something
    • 多行注释使用 /** */ ,且加上 @description @params @return 信息;
      /**
        * @description 描述信息
        * @params Object item
        * @return Array data
        */
      
  • IDE相关:
    • 使用VS Code;
    • VS Code 须安装的基础插件:ESLint、Vetur、Prettier Code formatter、Vue Peek;

接口规范:

  • 业务接口规范:

    {
      "code": 1, //接口状态 1:成功 2:参数错误、系统问题 -1:未登录
      "bizCode": 20001, //业务状态 当code为1时,须有 bizCode、bizMsg
      "bizMsg": "成功",
      "errorCode": 50001, // 错误编码 当code为2时,须有 errorCode、errorMsg
      "errorMsg": "服务端异常, 请稍后再试",
      "data": {
        "integralAmount": "11", 
        "shopCode": "DDDDD",
        "wxShopStatus": 1, 
        "surveyStatus": 1   
      }
    }
    
  • code:接口状态 [Int]

  • 状态1时,bizCode: 20000, bizMsg: '成功' 号段规则:2号段 eg: 20001

  • 状态2时,errorCode: 50001, errorMsg: 'xxxx错误' 号段规则:5号段 服务端错误 eg:50001、 6号段 参数错误 eg:60001

  • 状态-1时,除字段code外皆不返回

  • bizCode,bizMsg 与 errorCode、errorMsg 是互斥的

  • code、bizCode、errorCode 必须为Int型

  • 【编号全局统一】

  • 举例:

  • 20000 成功

  • 20001 优惠券已领完

  • 20002 积分不足

  • 20003 已经领取过了

  • 50001 服务端异常, 请稍后再试

  • 50002 服务端异常,问题xxx

  • 60001 参数错误

  • 无分页的数据结构,直接列出属性和值:

    "data": {
      "title": "标题",
      "content": "内容",
    }
    
  • 有分页的数据结构,data里有list和pagination属性,分别是列表和分页数据:

    "data": {
      "list": [
          {"id": 1, "title": "1"},
          {"id": 2, "title": "2"}
     ],
      "pagination": {
          "total": 300,
          "current": 1,
          "pageSize": 20,
      }
    }
    
  • YApi相关:

    • 添加的字段要有备注;
    • 后端开发完接口后,需将接口状态更新为“已完成”,前端切换到完成的接口;
  • 接口中的数据字段:

  • 后端须按前端实际需要的字段给,不要给一些多余的字段;

  • 前端先行的情况下,前端提供汉字版数据结构定义;

  • 接口中的数据格式化、计算等操作需后端处理好,前端不处;考虑到多端的情况;
    原则:前端只做数据渲染,不处理数据;

  • 权限和会话超时(失效):

    • 默认超时时间30分钟;
    • 后端返回的接口带有超时的编码和信息;
    • 前端弹出超时的提示,点击后跳转到登录页;
  • 登录:

    • 前端向后端提交登录需要的数据字段;
    • 后端将用户名等信息写入到session里;
    • 前端通过cookie获取到用户名信息;
  • 跨域处理:

    • 后端需要在Nginx服务器配置跨域,需要按域名设置,不要设置为*;

      Access-Control-Allow-Origin: http://dev.yougou.com
      Access-Control-Allow-Methods: GET,PUT,POST,DELETE,OPTIONS
      
    • 允许前端携带Cookie请求:

      Access-Control-Allow-Credentials: true
      

国际化:

  • 项目工程中的多语言:
    • 使用i18N组件;
    • 不同的语言使用对应的语言文件;
  • 组件中的多语言:
    • 语言标识使用系统里传过来的语言;
    • 每个组件使用到的语言,按语言建立文件放在每个组件里;
  • 语言包中的数据结构按照功能或页面名称来定义;

上下游协作规范:

  • 前端与产品及UI设计师的交互:
    • 前端按照UI设计师提供的 sketch 或 ps 文件进行开发;
  • 前端与后端开发协作:
    • 前端在完成界面布局交互开发后,再给到后端进行开发;