开发规划
命名规范
文件
命名方法：小驼峰式命名法。( 部分特殊说明文件可以使用大写字母，比如 README、LICENSE。 )
命名规范：文件名应当是名词，尽量使用全称，不要使用缩写。
常量
命名方法 : 全部大写 命名规范 : 使用大写字母和下划线来组合命名，下划线用以分割单词。
const MAX_COUNT = 10;
变量
命名方法：小驼峰式命名法。 命名规范：前缀应当是名词。（函数的名字前缀为动词，以此区分变量和函数）
尽量在变量名字中体现所有类型
- 如：length，count 等表示数字类型；
- 而包含 name，title 等表示字符串类型；
- boolean 类型的建议是用 is 或 has 等开头；
- Promise 对象 建议使用动宾短语的进行时表达；
- 判断是否显示可使用变量：show、visible、hide、hidden 等明确性单词
- res 统一规定为 response 的缩写，result 或 resource 建议使用全单词
- table 组件数据源建议使用 dataSource，与 antd 组件保持一致，清晰明了，一般一个页面组件只有一个 table 组件
- 校验类单词建议使用 validated，避免使用 check 与 选中 相冲突
- 避免使用 常用关键字命名变量
- 接口参数类型声明可添加 params 表示，返回类型可添加 DTO 或者首字母大写 I 开头 等区分
- 表示状态或类型是建议使用 status、state、type 等单词
- 枚举时，文案短或者好描述建议使用小写单词或全大写单词，使用下划线_连接，文案长或不易描述的可使用中文，但禁止在代码中使用数字判断
- 枚举值 非连续递增关系时，需列举写出每个枚举的值
const count = 10;
const tableDataSource = [];
const isShow = true;
const isDisabled = false;
const isShowModal = false;
函数
命名方法：小驼峰式命名法。 命名规范：前缀应当是动词。可使用常见动词约定
| 动词 | 含义 | 返回值 |
|---|---|---|
| can | 判断是否可执行某个动作（权限） | 布尔值，true：可执行；false：不可执行 |
| has | 判断是否含有某个值 | 布尔值，true：含有；false：不含有 |
| is | 判断是否为某个值 | 布尔值，true：为某个值；false：不为某个值 |
| get | 获取某个值 | 任何值 |
| set | 设置某个值 | 无返回值 |
| load | 加载某些数据 | 视场景定 |
| search | 搜索某些数据 | 视场景定 |
| validate | 校验、验证某些规则 | 无返回值 |
| query | 查询某些数据 | 视场景定 |
| add | 增加、添加数据 | 无返回值 |
| create | 创建数据 | 无返回值 |
| update | 更新某个数据 | 无返回值 |
| modify | 变更某个数据 | 无返回值 |
| edit | 编辑某个数据 | 无返回值 |
| delete | 删除某个数据 | 无返回值 |
| initialize | 初始化某个数据 | 无返回值 |
| select | 选择某个数据 | 视场景定 |
| cancel | 取消某个操作 | 无返回值 |
| confirm | 确认某个操作 | 无返回值 |
| click | 点击某个元素 | 视场景定 |
| submit | 提交某个数据 | 无返回值 |
// can
function canEdit() {}
// has
function hasData() {}
// is
function isShow() {}
类
命名方法：大驼峰式命名法。 命名规范：使用名词
class Table {}
class TableData {}
css
className 命名
命名方法：短划线命名法 小写字母，单词之间使用-连接。 命名规范：使用名词
- 不能使用 ad、banner、gg、ad、adver、adv 等广告相关的单词,浏览器广告拦截插件会屏蔽这些单词的 class
<div class="list">
<div class="list-item">
<div class="list-item-head"></div>
<div class="listi-tem-body"></div>
<div class="list-item-footer"></div>
</div>
</div>
- 变量维护文件统一命名为：variable.scss，维护色值和 font-size，以及常用的 px 规范。
// variable.scss
$primary-color: #1890ff;
$success-color: #52c41a;
$warning-color: #faad14;
$error-color: #f5222d;
$font-size-base: 14px;
$font-size-lg: 16px;
$font-size-sm: 12px;
注释规范
单行注释
- 单行注释使用 //，注释内容与 // 之间保留一个空格
// 这是一个单行注释
多行注释
- 多行注释使用 /* /，注释内容与 / 之间保留一个空格，注释内容与 */ 之间保留一个空格
/*
* 这是一个多行注释
* 这是一个多行注释
* 这是一个多行注释
*/
函数注释
| 注释名 | 语法 | 含义 | 示例 |
|---|---|---|---|
| @param | @param 参数名 {参数类型} 描述信息 | 描述参数的信息 | @param name {String} 传入名称 |
| @return | @param 参数名 {参数类型} 描述信息 | 描述返回值的信息 | @param name {String} 传入名称 |
| @author | @author 作者信息 [附属信息：如邮箱] | 描述作者的信息 | @author 李四 2022/12/16 |
| @version | @version XX.XX.XX | 描述此函数的版本号 | @version 1.1.1 |
| @example | @example 示例代码 | 描述示例代码 |
/**
* @description: 这是一个函数注释示例
* @param {String} name 传入名称
* @param {Number} age 传入年龄
* @return {String} 返回值
* @version 1.1.1
* @example
*/
function test(name, age) {
return name + age;
}
编程规范
使用 eslint prettier stylelint 等工具进行代码规范检查，保证项目代码质量风格统一。
ESLint 是一个 JavaScript 代码风格检查工具，它可以帮助您查找 JavaScript 代码中的语法错误和潜在问题。
stylelint 是一个 CSS 代码风格检查工具，它可以帮助您查找 CSS 代码中的语法错误和潜在问题。它可以与 Prettier 配合使用，更好地统一团队的代码风格。
Prettier
Prettier 是一个代码格式化工具，可以帮助您格式化 JavaScript、CSS、JSON、HTML 和其他语言的代码。它可以统一团队的代码风格，提高代码的可读性。
// .prettierrc.js
module.exports = {
printWidth: 100,
semi: true,
vueIndentScriptAndStyle: true,
singleQuote: true,
trailingComma: "all",
proseWrap: "never",
htmlWhitespaceSensitivity: "strict",
endOfLine: "auto",
};
- printWidth 表示代码换行的最大长度，超过这个长度的代码将被换行；
- semi 表示是否在语句的末尾加分号；
- vueIndentScriptAndStyle 表示是否缩进 vue 组件中的 script 和 style 标签内的* 代码；
- singleQuote 表示是否使用单引号；
- trailingComma 表示是否在对象和数组的末尾加逗号；
- proseWrap 表示是否在段落内换行；
- htmlWhitespaceSensitivity 表示在 html 代码中空格敏感性；
- endOfLine 表示换行符，如果是 ‘auto’ 则表示根据当前系统的换行符设置。
git 规范
Git Commit Message 规范
使用约定式提交规范（Conventional Commits），它受到了 Angular 提交准则的启发，并在很大程度上以其为依据。约定式提交规范是一种基于提交消息的轻量级约定。 它提供了一组用于创建清晰的提交历史的简单规则；这使得编写基于规范的自动化工具变得更容易。这个约定与 SemVer 相吻合，在提交信息中描述新特性、bug 修复和破坏性变更。它的 message 格式如下:
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
type
type 用于说明 commit 的类别，使用下列之一。
- feat：新功能（feature）
- fix：修补 bug
- docs：文档（documentation）
- style： 格式（不影响代码运行的变动）
- revert：回滚到上一个版本
- refactor：重构（即不是新增功能，也不是修改 bug 的代码变动）
- test：增加测试
- chore：构建过程或辅助工具的变动
- perf：性能优化
- ci：持续集成
scope
scope 用于说明 commit 影响的范围，比如数据层、控制层、视图层、配置文件等等。如果 commit 影响的范围比较小，可以不写 scope。如果 commit 影响的范围比较大，可以写成*。
subject
subject 是 commit 目的的简短描述，不超过 50 个字符。结尾不加句号。
body
body 是对本次 commit 的详细描述，可以分成多行。
footer
footer 用于不兼容变动或关闭 issue。不兼容变动是指在当前代码库中存在用户代码与之前版本不兼容时，footer 部分以 BREAKING CHANGE 开头，后面是对变动的描述、以及变动理由和迁移方法。
规范化提交工具(commitizen)
使用 commitizen 等工具，可以规范化提交，避免手动输入错误。
Git 分支管理规范
Git 分支管理规范，主要是为了保证项目的稳定性，避免项目的代码出现混乱，同时也为了方便多人协作开发。
分支管理
- master/main 分支：主分支保护分支，用于发布正式版本，只允许从 develop 分支合并，禁止直接在 master 分支上开发。
- develop 分支：开发分支，用于日常开发，只允许从 feature 分支合并，禁止直接在 develop 分支上开发。
- feature 分支：功能分支，用于开发新功能，从 develop 分支上创建，开发完成后合并到 develop 分支，合并完成后删除该分支。
- release 分支：发布分支，用于发布新版本，从 develop 分支上创建，发布完成后合并到 develop 分支和 master 分支，合并完成后删除该分支。
- hotfix 分支：修复分支，用于修复线上 bug，从 master 分支上创建，修复完成后合并到 develop 分支和 master 分支，合并完成后删除该分支。
分支命名规范
- master/main 分支：master/main
- develop 分支：develop
- feature 分支：feature/xxx
- release 分支：release/xxx
- hotfix 分支：hotfix/xxx
技术选型
语言
- Typescript ✅
- Javascript 需要使用 jsdoc 进行注释, 推荐渐进式迁移到 Typescript. 在无法运行 Typescript 的环境也推荐该注释方式
框架
- Vue3 ✅
- uniapp (小程序开发)
状态管理
- pinia
UI 框架
- element-ui
异步处理
- rxjs
图表
- Echarts
图标
- svg ✅
- iconfont
样式
- scss ✅
开发工具
- vscode
文档生成
- docz
- storybook ✅