javascript项目开发规范实例

首次发表在我的博客

总结一下我的在开发及review同事代码的过程当中遇到的由于一些项目规范带来的问题及认为比较好的解决方法; 因为我的经验和认知水平有限,下面仅表明个人我的观念,欢迎各位大佬多给我提建议;

以本人最近写的一个项目(技术栈为Meteor + React + MongoDB)为例

readme的使用

由于一个项目每每须要不少人一块儿协助开发,还有可能会不断有新手接手项目,因此readme里面必定要仅可能多的信息

• 项目启动命令
• 代码规范
• Commit Message 编写规范
• 命名: class命名,变量命名,函数命名,组件命名等
• 组件
• 目录结构
• 常遇到的问题及解决方案

也能够加一些项目中遇到的设计到的文档连接

代码规范

eslint

使用eslint来约束团队统一的代码规则

eslint规则在.eslintrc.js中定义,以为不合理的能够跟团队成员商量禁掉某条规则,或者有好的建议的也能够添加; 主要注意一下几条:

• 代码缩进用4空格
• 语句必须默认后加分号
• 使用单引号
• 提交代码前将console.log语句删掉或注释掉(否则影响其余开发人员调试)
• 禁止使用var,使用es6的let,const声明变量

还有一些状况是不须要检测的,例如第3方的库, 框架、组件、ui库等等,能够将这些文件放在.eslintignore文件中,能够忽略eslint的检测

在文件顶部加上下面这行,能够禁掉整个文件的eslint规则

/* eslint-disable */
复制代码

pre-commit 的使用

使用方法 1.在命令行安装

npm  i --save-dev pre-commit
复制代码

2.在package.json中配置

{
    "scripts": {
        "eslint": "eslint ./ --ext js,vue --ignore-pattern .eslintignore --cache --fix",
        "lint-message": "echo '开始 eslint 检查, 存在 error 则会拒绝提交'"
    },
    "pre-commit": [
        "lint-message",
        "eslint" // 进行eslint检查并自动修复一些简单的格式错误
    ],
}
复制代码

代码提交以前会强制code-review,不符合规范的不容许提交代码

若是项目实在没时间去改的话，能够git commit -m 'XXX' --no-verify 或 git commit -n 'xxx'强制提交

小技巧-vscode能够配置保存自动修复eslint错误

vscode安装eslint插件,在配置中配置以下

{
     "eslint.autoFixOnSave": true,
     "eslint.enable": true,
     "eslint.options": {
        "extensions": [".js", ".vue", ".jsx"]
     },
     "eslint.validate": [
          {

              "language": "vue",
              "autoFix": true
          },
          {
              "language": "javascript",
              "autoFix": true
          },
          {
              "language": "javascriptreact",
              "autoFix": true
          }
      ],
}
复制代码

Commit Message 编写规范

编写Commit Message须要遵循必定的范式，内容应该清晰明了，指明本次提交的目的，便于往后追踪问题。

feat: 新功能
fix: 修补bug
docs: 文档
style: 格式(不影响代码运行的变更)
refactor: 重构
test: 添加测试
chore: 构建过程或辅助工具的变更

复制代码

命名

命名的语义化真的特别特别重要,哪怕不知道要命名的这个词的英文是什么,也要去查一下;千万不要以a,b,c等没有任何语义的词去命名;以前我也老是注意不到这一点,可是最近在看同事的代码还有重构本身以前写的部分代码,命名压根看不明白这个变量的意思,总之,看这样的代码怎一个痛苦了得

常见class命名关键词： 布局类：header, footer, container, main, content, aside, page, section 包裹类：wrap, inner 区块类：region, block, box 结构类：hd, bd, ft, top, bottom, left, right, middle, col, row, grid, span 列表类：list, item, field 主次类：primary, secondary, sub, minor 大小类：s, m, l, xl, large, small 状态类：active, current, checked, hover, fail, success, warn, error, on, off 导航类：nav, prev, next, breadcrumb, forward, back, indicator, paging, first, last 交互类：tips, alert, modal, pop, panel, tabs, accordion, slide, scroll, overlay, 星级类：rate, star 分割类：group, seperate, divider 等分类：full, half, third, quarter 表格类：table, tr, td, cell, row 图片类：img, thumbnail, original, album, gallery 语言类：cn, en 论坛类：forum, bbs, topic, post 方向类：up, down, left, right 其余语义类：btn, close, ok, cancel, switch; link, title, info, intro, more, icon; form, label, search, contact, phone, date, email, user; view, loading...

变量命名: 名字要能准确的描述出该变量所表明的事物 好比表示user的id就叫userId,而不要只叫user

函数命名建议：可以使用常见动词约定

动词       含义      
 get       获取某个值            
 set       设置某个值             
 is        判断是否为某个值    
 has       判断是否有某个值  
复制代码

如下规则是此项目中使用的,主要看团队代码习惯:

1. 组件名和组件所在文件名使用大驼峰式
2. css类名使用小写单词并用横线(-)分割
3. dom节点以$开头

组件

1. 每一个组件占一个文件
2. 组件不包含状态则应写为 stateless 组件
3. 非 stateless 组件使用 pure-render-decorator 优化

目录结构

├── client  
│   ├── main.html                       客户端页面模板
│   └── main.js                         客户端入口  
├── imports  
│   ├── client  
│   │   ├── App.jsx                     顶层组件  
│   │   ├── components                  公共组件  
│   │   ├── routers                     前端路由  
│   │   ├── styles                      样式  
│   │   └── views                       视图  
│   │       ├── header                  公共头  
│   │       ├── login                   登陆注册  
│   ├── schema                          模型  
│   └── util                            工具函数  
├── packages                            自定义 meteor 包  
├── public                              客户端资源  
└── server   
    ├── main.js                         服务端入口  
    └── user                            用户接口  
复制代码

issues的使用

项目中总会遇到不少奇奇怪怪的问题,当时印象深入,过了一段时间,就忘了具体的问题及解决办法,虽然每次能够经过查commit为fix的记录,可是这样查找起来很麻烦,咱们项目是用gitlab来托管,能够合理的理由issues,每次遇到很棘手的问题的时候,能够提一个issues,等后期把这个问题解决了再把这个issues给关闭,并写上问题缘由及解决办法分析

下面补充的是项目中针对Meteor后端开发的一些规范

数据库

Collection 定义

全部 Collection 定义放在 imports/schema 目录, 每一个 Collection 务一定义 Schema 来约束字段

Schema 定义

Schema 定义使用 SimpleSchema, 数据插入数据库前必须经过 schema 校验, 调用校验语句为 表名.schema.validate(要插入的数据);

过滤 Collection 字段

默认状况下, 数据查询语句会返回全部字段, 好比 Memete.users.find({}) 会将用户的密码和 token 一并返回, 这样是不安全不正确的, find / findOne 的第二个参数是查询选项, fields 字段能够控制返回字段, 例如:

Meteor.users.find(
    { },
    {
        fields: {
            username: 1,
            profile: 1,
        },
    },
);
复制代码

该查询会返回 _id, username, profile 字段, 其中 _id 是默认返回的

本身定义populate方法(取出关联数据)

在作邀请新的好友入群的时候,添加新的好友,利用reywood:publish-composite并不会自动更新数据,因此之后直接本身在客户端定义方法 这样作的好处是解决了取关联数据不会自动更新的bug,可是有点麻烦的是每次须要关联数据的时候必须在客户端调用一次方法,正在考虑有没有更好的解决方法

import { Meteor } from 'meteor/meteor';

const PopulateUtil = {
    group(group) {
        if (group) {
            group.members = Meteor.users.find({ _id: { $in: group.members } }).fetch();
            group.admin = Meteor.users.findOne({ _id: group.admin });
        }
    },
    groups(groups) {
        groups.forEach(group => PopulateUtil.group(group));
    },
};

export default PopulateUtil;
复制代码

由于此次项目须要本身设计数据库,还有本身定义后端方法,以前没有任何经验,作到如今也总结出一点心得:

• 数据库设计必定要根据具体的业务逻辑(开始设计以前必定要和产品沟通清楚产品逻辑)
• 能在后端取到的数据,在接口定义的时候不要让前端去传

最后感受后端的逻辑真的很复杂,须要各类判断,各类状况都得想到

推荐看一下这本代码大全(第二版),等看完这本书再好好的完善一下这篇文章

参考

• class如何命名更规范
• 代码大全(第二版)
• Commit Message 编写指南

About

github blog