首次发表在个人博客
总结一下个人在开发及review同事代码的过程中遇到的因为一些项目规范带来的问题及认为比较好的解决方法;
由于个人经验和认知水平有限,下面仅代表我的个人观念,欢迎各位大佬多给我提建议;
以本人最近写的一个项目(技术栈为Meteor + React + MongoDB)为例
readme的使用
因为一个项目往往需要很多人一起协助开发,还有可能会不断有新手接手项目,所以readme里面一定要仅可能多的信息
- 项目启动命令
- 代码规范
- Commit Message 编写规范
- 命名: class命名,变量命名,函数命名,组件命名等
- 组件
- 目录结构
- 常遇到的问题及解决方案
也可以加一些项目中遇到的设计到的文档链接
代码规范
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 判断是否有某个值
以下规则是此项目中使用的,主要看团队代码习惯:
- 组件名和组件所在文件名使用大驼峰式
- css类名使用小写单词并用横线(-)分割
- dom节点以$开头
组件
- 每个组件占一个文件
- 组件不包含状态则应写为 stateless 组件
- 非 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 编写指南
