一、工程规范
1.工程目录
./src
├── App.vue
├── api
│ ├── types
│ ├── sensor
│ ├── bizz
│ └── webview
├── assets
│ ├── css
│ └── images
├── components
│ ├── base
│ ├── layout
│ └── component-a
├── mixins
│ ├── mixins-a.ts
│ ├── mixins-b.ts
│ └── types
├── main.ts
├── router
│ └── index.ts
├── const
├── directives
├── store
│ ├── index.ts
│ └── modules
├── types
├── views
│ ├── About.vue
│ ├── Example.vue
│ └── Index.vue
├── vite-env.d.ts
└── vuex.d.ts
App.vue 页面入口文件
api 存放接口文档的目录
api --> types 存放一些接口请求类型和响应类型的 类型说明文件
api --> sensor 埋点的配置目录
api--> webview 存放一些接口请求类型和响应类型的 类型说明文件
assets 静态资源目录
assets --> css 存放一些全局的css文件
assets --> images 存放一些全局的静态图片
Components 页面组件的一些局部组件存放目录
Components --> base 布局的公共组件
Components --> layout 侧边栏公共组件
Mixins 全局注入的mixins目录
Mixins --> types mixins文件的说明文件目录
main.ts 程序入口文件
Router 路由目录
Router --> index.ts 路由配置的文件
Directives 指令文件 一些自定义指令的存放文件
Store vuex配置目录
Store --> index.ts vuex的入口文件 存放vuex配置
Store --> modules vuex模块化目录
Types 全局类型说明文件
Views 视图组件目录 存放一些视图组件
vite-env.d.ts vite的类型说明文件
vuex.d.ts vuex的类型说明文件
2.工程管理
- 【强制】 工程名,命名为ret_{工程分类}_[子业务名],说明:工程分类为子模块或组件 module/component,子业务名可选。
例如:ret_module_mine - 【强制】 版本号定义:主版本号.次版本号.修订版本号
A.主版本号:产品方向改变,或者大规模API不兼容,或者架构不兼容升级。
B.次版本号:保持相对兼容性,增加主要功能特性,影响范围极小的API不兼容修改。
C.修订号:保持完全兼容性,修复BUG、新增次要功能特性等。
二、编码规范
1. 变量定义规范
- 【强制】 目录命名 全部采用小写方式, 以中划线分隔,有复数结构时,要采用复数命名法, 缩写不用复数。
正例:scripts/styles/components/images/utils/layouts/demo-styles/demo-scripts/img/doc - 【强制】 JS、CSS、SCSS、HTML、PNG 文件命名,全部采用小写方式, 以中划线分隔。
- 【强制】 命名严谨性 代码中的命名严禁使用拼音与英文混合的方式,更不允许直接使用中文的方式。 说明:正确的 英文拼写和语法可以让阅读者易于理解,避免歧义。注意,即使纯拼音命名方式也要避免采用
- 【强制】 方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase 风 格,必须遵从驼峰形式,其中 method 方法命名必须是 动词 或者 动词+名词 形式,参考以下动词表
add / update / delete / detail / get
附: 函数方法常用的动词:
get 获取/set 设置,
add 增加/remove 删除,
create 创建/destory 销毁,
start 启动/stop 停止,
open 打开/close 关闭,
read 读取/write 写入,
load 载入/save 保存,
begin 开始/end 结束,
backup 备份/restore 恢复,
import 导入/export 导出,
split 分割/merge 合并,
inject 注入/extract 提取,
attach 附着/detach 脱离,
bind 绑定/separate 分离,
view 查看/browse 浏览,
edit 编辑/modify 修改,
select 选取/mark 标记,
copy 复制/paste 粘贴,
undo 撤销/redo 重做,
insert 插入/delete 移除,
add 加入/append 添加,
clean 清理/clear 清除,
index 索引/sort 排序,
find 查找/search 搜索,
increase 增加/decrease 减少,
play 播放/pause 暂停,
launch 启动/run 运行,
compile 编译/execute 执行,
debug 调试/trace 跟踪,
observe 观察/listen 监听,
build 构建/publish 发布,
input 输入/output 输出,
encode 编码/decode 解码,
encrypt 加密/decrypt 解密,
compress 压缩/decompress 解压缩,
pack 打包/unpack 解包,
parse 解析/emit 生成,
connect 连接/disconnect 断开,
send 发送/receive 接收,
download 下载/upload 上传,
refresh 刷新/synchronize 同步,
update 更新/revert 复原,
lock 锁定/unlock 解锁,
check out 签出/check in 签入,
submit 提交/commit 交付,
push 推/pull 拉,
expand 展开/collapse 折叠,
enter 进入/exit 退出,
abort 放弃/quit 离开,
obsolete 废弃/depreciate 废旧,
collect 收集/aggregate 聚集
- 【强制】 常量命名全部大写,单词间用下划线隔开,力求语义表达完整清楚, 不要嫌名字长
2. 埋点规范
- 【强制】 不允许导出addBuriedPoint方法直接使用
- 【强制】 定义指定埋点事件的一个方法进行导出使用,例如 Minepage_icon_click 应新建方法clickMineIcon,方法命名规范参考 1.iv
- 【强制】 生产环境不允许打开 show_log 开关
- 【强制】 埋点数据接收地址
神策数据接收地址(生产环境):
https协议地址:https://dmp.nesc.cn:1443/sa?project=production
http协议地址: http://dmp.nesc.cn:8106/sa?project=production
神策数据接收地址(测试环境):
https协议地址 https://dmptest.nesc.cn:1444/sa?project=production
http协议地址:http://dmptest.nesc.cn:8107/sa?project=production
3. 类型定义规范
- 【强制】 所有的 interface 起始为 I,而 types 起始为 T
- 【强制】 声明数组时使用 foos:Foo[] 而不是 foos:Array
,便于阅读 - 【强制】 interface 尽量进行 extends 而不是从零写
- 【强制】 使用?来替代 undefined 类型
4. Vue规范
【强制】 组件名为多个单词。组件名应该始终是多个单词组成(大于等于 2),且命名规范为KebabCase格式。这样做可以避免跟现有的以及未来的 HTML 元素相冲突,因为所有的 HTML 元素名称都是单个单词的。
【强制】 组件文件名为 pascal-case 格式
【强制】 基础组件文件名为 base 开头,使用完整单词而不是缩写。
【强制】 和父组件紧密耦合的子组件应该以父组件名作为前缀命名
【强制】 在 Template 模版中使用组件,应使用 PascalCase 模式,并且使用自闭合组件。
【强制】 script使用setup script,视图数据对象只返回一个对象,如同vue2的data
【强制】 Prop 定义应该尽量详细必须使用 camelCase 驼峰命名必须指定类型必须加上注释,表明其含义必须加上 required 或者 default,两者二选其一如果有业务需要,必须加上 validator 验证
【强制】 为组件样式设置作用域
【强制】 如果特性元素大于一屏,应该主动换行。
【强制】 模板中使用简单的表达式。组件模板应该只包含简单的表达式,复杂的表达式则应该重构为计算属性或方法。复杂表达式会让你的模板变得不那么声明式。我们应该尽量描述应该出现的是什么,而非如何计算那个值。而且计算属性和方法使得代码可以重用。
【强制】 指令都使用缩写形式。指令推荐都使用缩写形式,(用 : 表示 v-bind: 、用 @ 表示 v-on: 和用 # 表示 v-slot:)
【强制】 标签顺序保持一致。单文件组件应该总是让标签顺序保持为 template、script、style
【强制】 router 中的命名规范。path、childrenPoints 命名规范采用kebab-case命名规范(尽量vue文件的目录结构保持一致,因为目录、文件名都是kebab-case,这样很方便找到对应的文件)。name 命名规范采用KebabCase命名规范且和component组件名保持一致!(因为要保持keep-alive特性,keep-alive按照component的name进行缓存,所以两者必须高度保持一致)
【强制】 router 中的 path 命名规范。path除了采用kebab-case命名规范以外,必须以 / 开头,即使是children里的path也要以 / 开头。
【强制】 router 中的 path 命名规范。path除了采用kebab-case命名规范以外,必须以 / 开头,即使是children里的path也要以 / 开头。
5. 业务组件规范
1. 语法
【强制】 全部使用script+setup 语法糖
2. 属性顺序
【强制】 components --> props --> data --> computed --> watch --> filter --> 钩子函数 --> methods
3. 方法定义
【强制】 尽量不要手动操作 DOM。因使用 vue 框架,所以在项目开发中尽量使用 vue 的数据驱动更新 DOM,尽量(不到万不得已)不要手动操作 DOM,包括:增删改 dom 元素、以及更改样式、添加事件等。
6. CSS规范
- 【强制】 不允许代码中的命名严禁使用拼音与英文混合的方式,更不允许直接使用中文的方式。
- 【强制】 每个声明块的左花括号前添加空格
- 【强制】 声明块的右花括号必须单独成行
- 【强制】 每个声明语句:后应该添加一个空格,前面不需要
- 【强制】 所有语句都要以分号结尾
- 【强制】 选择器层级不要超过5级
- 【强制】 如果属性值为0,不加单位
- 【强制】 小数值小于1,别写.前面的0
7. CSS命名规范
- 【强制】 CSS类名使用BEM命名规范,Block(块)代表更高级别的抽象或组件,Element(元素) Block的后代,以及Modifier(修饰) 不同状态的修饰符。
- Block 由一个或多个单词组成,单词与单词之前使用“-”隔开。参考单词表如下
登录条:loginbar
标志:logo
广告:banner
页面主体:main
热点:hot
新闻:news
下载:download
子导航:subnav
菜单:menu
子菜单:submenu
搜索:search
友情链接:friendlink
页脚:footer
版权:copyright
滚动:scroll
内容:content
标签页:tab
文章列表:list
信息:msg
小技巧:tips
标题:title
加入:joinus
指南:guild
服务:service
注册:regsiter
状态:status
投票:vote
合作伙伴:partner
- Element 由一个单词构成,与Block使用“__”隔开。参考单词表如下
关于: about
账户: account
箭头图标: arrow
文章: article
边栏: aside
音频: audio
头像: avatar
栏: bar
按钮: btn
标题,说明: caption
分类: category
图表: chart
关闭: close
评论: comment
社区: community
容器: container
内容: content
版权: copyright
页脚: footer
论坛: forum
主页: home
图标: icon
链接: links
下一页: next
上一页: previous
- Modifier表示的是一个状态,是用双横杠分开的。参考单词表如下
正常的: normal
激活: active
完整的: full
大的: big
小的: small
默认的: default
不可用: disabled
错误的: error
失败: fail
高亮的: hightlight
第一个的: first
最后一个的: last
主要的: primary
8. 注释
- 【强制】 坚决删除无意义代码、对冗余注释零容忍、我个人觉得在我们有git版本管理的情况下,一段注释的代码很难再拿来使用,甚至不如再写一次的快,你可以在自己的项目当中大胆的尝试,勇敢的去删除,你会发现管理成本大大降低,阅读体验立马上来了,而且你很少回去找以前注释的代码,趋近于0。
- 方法使用方法注释,针对入参进行注释说明,枚举类说明格式(value1:label1;value2:label2;)