uni-app 开发规范
章节介绍
开发规范是团队开发中的重要组成部分，它可以帮助开发者保持代码风格一致，提高代码可读性和可维护性，减少团队协作中的摩擦。对于 uni-app 这样的跨平台框架，开发规范尤为重要，因为需要确保代码在多个平台上都能正常运行。本章节将介绍 uni-app 应用的开发规范，包括代码规范、命名规范、目录结构规范等。
核心知识点
1. 代码规范
代码规范是开发规范的核心，它包括代码风格、缩进、注释等方面的规定。在 uni-app 开发中，建议采用以下代码规范：
1.1 基础代码规范
- 缩进：使用 2 个空格进行缩进
- 行宽：每行代码不超过 100 个字符
- 分号：语句结束后添加分号
- 引号：字符串使用单引号，模板字符串使用反引号
- 空格：在操作符前后、逗号后添加空格
1.2 Vue 代码规范
- 组件命名：使用 PascalCase 命名组件，例如
MyComponent - 属性命名：使用 kebab-case 命名组件属性，例如
:user-name - 指令缩写：使用指令缩写，例如
@click代替v-on:click - 模板表达式：模板中的表达式保持简洁，复杂逻辑应在计算属性或方法中处理
- 计算属性：将复杂的模板表达式提取为计算属性
1.3 JavaScript 代码规范
- 变量命名：使用 camelCase 命名变量和函数，例如
userName - 常量命名：使用 UPPER_CASE 命名常量，例如
MAX_COUNT - 函数声明：使用函数声明或箭头函数，避免使用函数表达式
- 解构赋值：优先使用解构赋值，例如
const { name, age } = user - 扩展运算符：使用扩展运算符进行对象和数组的浅拷贝，例如
const newObj = { ...oldObj }
2. 命名规范
命名规范是开发规范的重要组成部分，它包括文件命名、组件命名、变量命名等方面的规定。在 uni-app 开发中，建议采用以下命名规范：
2.1 文件命名
- 页面文件：使用 kebab-case 命名，例如
home-page.vue - 组件文件：使用 PascalCase 命名，例如
MyComponent.vue - 工具文件：使用 camelCase 命名，例如
utils.js - 样式文件：使用 kebab-case 命名，例如
home-page.scss
2.2 组件命名
- 组件名称：使用 PascalCase 命名，例如
MyComponent - 组件标签：使用 kebab-case 命名，例如
<my-component> - Props 命名：使用 camelCase 命名 Props，例如
userName - 事件命名：使用 kebab-case 命名事件，例如
@user-click
2.3 变量和函数命名
- 变量名：使用 camelCase 命名，例如
userName - 函数名：使用 camelCase 命名，例如
getUserInfo() - 类名：使用 PascalCase 命名，例如
UserService - 常量名：使用 UPPER_CASE 命名，例如
MAX_COUNT - 枚举名：使用 PascalCase 命名，例如
UserStatus
3. 目录结构规范
目录结构规范是开发规范的重要组成部分，它包括项目目录结构、文件组织等方面的规定。在 uni-app 开发中，建议采用以下目录结构规范：
3.1 基础目录结构
├── src/
│ ├── components/ # 公共组件
│ ├── pages/ # 页面
│ ├── static/ # 静态资源
│ ├── store/ # 状态管理
│ ├── services/ # 服务层
│ ├── utils/ # 工具函数
│ ├── config/ # 配置文件
│ ├── mixins/ # 混入
│ ├── filters/ # 过滤器
│ ├── directives/ # 指令
│ ├── router/ # 路由配置
│ ├── App.vue # 根组件
│ └── main.js # 入口文件
├── unpackage/ # 打包输出目录
├── package.json # 项目配置
├── project.config.json # 项目配置
├── vue.config.js # Vue 配置
└── .eslintrc.js # ESLint 配置3.2 页面目录结构
├── pages/
│ ├── home/
│ │ ├── home.vue # 页面组件
│ │ ├── components/ # 页面级组件
│ │ ├── utils/ # 页面级工具
│ │ └── styles/ # 页面级样式
│ └── detail/
│ ├── detail.vue # 页面组件
│ ├── components/ # 页面级组件
│ ├── utils/ # 页面级工具
│ └── styles/ # 页面级样式3.3 组件目录结构
├── components/
│ ├── MyComponent/
│ │ ├── MyComponent.vue # 组件文件
│ │ ├── index.js # 组件导出
│ │ ├── styles/ # 组件样式
│ │ └── utils/ # 组件工具
│ └── AnotherComponent/
│ ├── AnotherComponent.vue # 组件文件
│ ├── index.js # 组件导出
│ ├── styles/ # 组件样式
│ └── utils/ # 组件工具4. 注释规范
注释规范是开发规范的重要组成部分，它可以帮助开发者理解代码的功能和实现逻辑。在 uni-app 开发中，建议采用以下注释规范：
4.1 单行注释
- 使用
//进行单行注释 - 注释内容与
//之间添加一个空格 - 注释应放在被注释代码的上方或右侧
4.2 多行注释
- 使用
/* */进行多行注释 - 多行注释应包含注释内容、作者、日期等信息
- 多行注释应放在文件顶部或函数顶部
4.3 文档注释
- 使用 JSDoc 风格的文档注释
- 文档注释应包含函数说明、参数说明、返回值说明等信息
- 文档注释应放在函数或类的上方
5. 提交规范
提交规范是开发规范的重要组成部分，它可以帮助开发者保持提交信息一致，提高代码仓库的可读性。在 uni-app 开发中，建议采用以下提交规范：
5.1 提交信息格式
<type>(<scope>): <subject>
<body>
<footer>- type：提交类型，包括 feat（新功能）、fix（修复）、docs（文档）、style（样式）、refactor（重构）、test（测试）、chore（构建）等
- scope：提交范围，例如页面、组件、工具等
- subject：提交主题，简要描述提交内容
- body：提交正文，详细描述提交内容
- footer：提交脚注，包括 BREAKING CHANGE（破坏性变更）、Closes（关闭 issue）等
5.2 提交示例
feat(home): 添加首页轮播图功能
- 实现轮播图组件
- 添加轮播图数据接口
- 优化轮播图动画效果
Closes #123实用案例
案例：制定团队开发规范
1. 代码规范配置
使用 ESLint 和 Prettier 配置代码规范：
1.1 安装依赖
npm install --save-dev eslint prettier @vue/eslint-config-prettier @vue/eslint-config-standard eslint-plugin-vue1.2 配置 ESLint
创建 .eslintrc.js 文件：
// .eslintrc.js
module.exports = {
root: true,
env: {
node: true
},
extends: [
'plugin:vue/essential',
'@vue/standard',
'@vue/prettier'
],
parserOptions: {
parser: 'babel-eslint'
},
rules: {
'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
'no-debugger': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
'vue/max-attributes-per-line': ['error', {
singleline: 10,
multiline: {
max: 1,
allowFirstLine: false
}
}],
'vue/component-name-in-template-casing': ['error', 'PascalCase']
}
}1.3 配置 Prettier
创建 .prettierrc.js 文件：
// .prettierrc.js
module.exports = {
singleQuote: true,
semi: true,
trailingComma: 'es5',
printWidth: 100,
tabWidth: 2
}2. 目录结构规范
制定项目目录结构规范：
├── src/
│ ├── components/ # 公共组件
│ │ ├── base/ # 基础组件
│ │ └── business/ # 业务组件
│ ├── pages/ # 页面
│ │ ├── home/ # 首页
│ │ ├── detail/ # 详情页
│ │ └── user/ # 用户页
│ ├── static/ # 静态资源
│ │ ├── images/ # 图片
│ │ ├── icons/ # 图标
│ │ └── fonts/ # 字体
│ ├── store/ # 状态管理
│ │ ├── modules/ # 模块状态
│ │ └── index.js # 状态管理入口
│ ├── services/ # 服务层
│ │ ├── api/ # API 接口
│ │ └── utils/ # 服务工具
│ ├── utils/ # 工具函数
│ │ ├── common/ # 通用工具
│ │ └── platform/ # 平台工具
│ ├── config/ # 配置文件
│ │ ├── api.js # API 配置
│ │ └── app.js # 应用配置
│ ├── mixins/ # 混入
│ ├── filters/ # 过滤器
│ ├── directives/ # 指令
│ ├── App.vue # 根组件
│ └── main.js # 入口文件
├── unpackage/ # 打包输出目录
├── package.json # 项目配置
├── project.config.json # 项目配置
├── vue.config.js # Vue 配置
├── .eslintrc.js # ESLint 配置
└── .prettierrc.js # Prettier 配置3. 命名规范示例
制定具体的命名规范：
3.1 组件命名
- 基础组件：使用
Base前缀，例如BaseButton - 业务组件：使用业务名称，例如
UserCard - 页面组件：使用页面名称，例如
HomePage
3.2 文件命名
- 页面文件：使用 kebab-case，例如
home-page.vue - 组件文件：使用 PascalCase，例如
UserCard.vue - 工具文件：使用 camelCase，例如
apiUtils.js - 样式文件：使用 kebab-case，例如
home-page.scss
3.3 变量和函数命名
- 变量名：使用 camelCase，例如
userName - 函数名：使用 camelCase，例如
getUserInfo() - 常量名：使用 UPPER_CASE，例如
MAX_COUNT - 类名：使用 PascalCase，例如
UserService
4. 提交规范配置
使用 commitizen 和 husky 配置提交规范：
4.1 安装依赖
npm install --save-dev commitizen cz-conventional-changelog husky lint-staged4.2 配置 package.json
{
"scripts": {
"commit": "git-cz",
"lint": "eslint --ext .vue,.js,.jsx,.cjs,.mjs src/ --fix --ignore-path .gitignore"
},
"config": {
"commitizen": {
"path": "cz-conventional-changelog"
}
},
"husky": {
"hooks": {
"pre-commit": "lint-staged",
"commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
}
},
"lint-staged": {
"*.{vue,js,jsx,cjs,mjs}": [
"npm run lint",
"git add"
]
}
}学习目标
通过本章节的学习，你应该能够：
- 了解开发规范的重要性
- 掌握代码规范的制定方法
- 学会命名规范的应用
- 理解目录结构规范的设计原则
- 掌握提交规范的执行方法
- 学会制定和执行团队开发规范
章节总结
本章节介绍了 uni-app 应用的开发规范，包括代码规范、命名规范、目录结构规范、注释规范和提交规范等。开发规范是团队开发中的重要组成部分，它可以帮助开发者保持代码风格一致，提高代码可读性和可维护性，减少团队协作中的摩擦。
在实际开发中，建议开发者根据项目需求和团队特点制定适合的开发规范，并使用工具（如 ESLint、Prettier、husky 等）强制执行规范。通过开发规范，开发者可以提高代码质量和开发效率，减少团队协作中的摩擦，确保项目的顺利进行。