xbb-utils开发规范
为什么选择开发utils包?
方便代码的快速维护
方便一套代码部署多个项目以及新项目的快速启动
为后期需求踩坑
为什么选择ts?
有更加安全的静态类型检查,而静态类型检查更有利于构建大型项目
增加了代码可读性
更有好的IDE代码提示
版本规范
主版本号.子版本号.修正版本号
修复bug:修正版本号+1
新增方法:子版本号+1,修正版本号复位为 0
整体影响:重大修改或局部修正累积较多,而导致项目整体发生全局变化时,主版本号加 1,其余版本号复位为0
版本号 | 备注 |
---|---|
v0.0.1 | 基础搭建 |
v0.1.0 | 新增vue2.x调试页面 |
v0.1.1 | 修复bug,完善单测 |
v0.1.2 | 修复bug,维护更新 |
v1.1.0 | 优化math方法,新增thumbnail, formatToNumber, dealNumber, getGuid方法 |
项目结构
每个文件夹都有各自的职责,项目配置文件单独列出来方便修改配置。核心模块也就只有src
文件,其余都是辅助。
1 | . |
src
- 所有功能模块需要开发到
src/core/**
下,此文件为核心代码块; - 具体功能目前划分了几大类别
math
url
is
method
verify
…等等,后期按需添加; core
下的方法都需要导出,且需要添加注释,注释参考下图(图1),此描述不生成文档,故可以写的更加详细;core/is.ts
为类型判断文件,推荐大家项目中需要进行类型判断时候使用此文件,而不是书写新的判断代码。types
文件夹放interface接口声明,interface
有几个大类对应core
下的文件命(图2),作为开发中的代码提示文案,interface的备注需要书写的清晰,传入的参数以及返回的参数类型一定要正确,文案也要相对简练。- 类型超过3个(包含3个)推荐使用类型别名,例如:
1
2
3
4
5
6
7
8
9
10// bad
export function checkType(val: Date | string | number): Date {
// TODO...
}
// good
type dateType = Date | string | number
export function checkType(val: dateType): Date {
// TODO...
}
备注:因为使用了自动文档生成工具,所以为了避免文档输出混乱,备注需要统一的规则。除types
文件下的方法,其余的都需要添加@ignore
阻止文档的自动生成,
单测
unit/index.spec.ts
文件用来测试实例是否挂载了对应的方法(/src/core/**.ts
),每次在core
下新增方法后,都需要到这个文件下的对应单测模块中添加测试实例,用于确保实例有此方法,相当于双重保险;unit/core/**.spec.ts
为对应的core
下的核心单测文件,每个单测方法都有一个大的describe
包裹数个it
,方便单测报错时,定位具体哪个文件下的哪个方法报错,错误日志会输出describe
和it
的描述文案;
- 单测文件需要把要测试的代码中的每一个分支,每一行代码,每一个判断都要覆盖,需要完成方法覆盖100%,分支覆盖98%,行数覆盖100%的条件,推荐全部100%;
- 单测结果可以在控制台或者
coverage/lcov-report/index.html
查看详情。
- 第一行10x 代表当前行走了10次
- 黄色img[0]表示单测这行代码没有覆盖到
if
前的E标识,说明此if
判断的else
条件没有覆盖- 红色则表示整行(大段代码)没有覆盖到,考虑是否漏写该方法的单测
调试
本项目为了方便调试,已集成vue2.x,可以通过npm run serve
启动vue项目。
vue项目目录为home/*
。
使用
需要用到的项目,使用npm i -S xbb-utils
来安装最新版本,之后再需要用到的页面import xbb from 'xbb-utils'
功能开发
- 首先需要基于远端master拉取最新代码分支
- 新建开发分支,一般为feature/开发分支名的格式
git checkout -b feature/xxxxx
- 推送开发分支到远端并追踪关系
git push --set-upstream origin feature/xxxxx
- enjoy your coding…
ps: 如果有好的点子但是没有时间开发,可以再gitlab提交issues
开发完成
- 开发完成后需要再跑一遍单测,确保通过率为100%
- 检查无误,没有问题之后,去gitlab提交MR(merge request)
- 待管理员审核无误后发布,会在群里通知最新版本号,及时更新到最近版本即可