301 lines
6.4 KiB
Markdown
301 lines
6.4 KiB
Markdown
|
# 开发规范文档
|
|||
|
|
|
|||
|
|
## 一、命名规范
|
|||
|
|
|
|||
|
|
### 1.1 文件命名
|
|||
|
|
- **页面文件**：使用小写字母，多个单词用短横线连接，如 `user-profile.vue`
|
|||
|
|
- **组件文件**：使用大驼峰命名，如 `UserCard.vue`、`LoadingView.vue`
|
|||
|
|
- **工具类文件**：使用小写字母，多个单词用短横线连接，如 `request.js`、`storage.js`
|
|||
|
|
- **常量文件**：使用小写字母，如 `constants.js`、`env.js`
|
|||
|
|
|
|||
|
|
### 1.2 变量命名
|
|||
|
|
- **普通变量**：使用小驼峰命名，如 `userName`、`userInfo`
|
|||
|
|
- **常量**：使用全大写字母，单词间用下划线连接，如 `API_BASE_URL`、`MAX_RETRY_COUNT`
|
|||
|
|
- **私有变量**：以下划线开头，如 `_privateMethod`
|
|||
|
|
- **布尔值**：以 `is`、`has`、`can` 等开头，如 `isLogin`、`hasPermission`
|
|||
|
|
|
|||
|
|
### 1.3 函数命名
|
|||
|
|
- **普通函数**：使用小驼峰命名，动词开头，如 `getUserInfo`、`handleClick`
|
|||
|
|
- **事件处理函数**：以 `handle` 或 `on` 开头，如 `handleSubmit`、`onLoad`
|
|||
|
|
- **工具函数**：使用动词开头，如 `formatDate`、`validatePhone`
|
|||
|
|
|
|||
|
|
### 1.4 组件命名
|
|||
|
|
- **全局组件**：使用大驼峰命名，至少两个单词，如 `LoadingView`、`EmptyView`
|
|||
|
|
- **页面组件**：使用大驼峰命名，如 `LoginPage`、`UserProfile`
|
|||
|
|
- **业务组件**：使用大驼峰命名，体现业务含义，如 `UserCard`、`OrderList`
|
|||
|
|
|
|||
|
|
## 二、代码注释规范
|
|||
|
|
|
|||
|
|
### 2.1 文件注释
|
|||
|
|
每个文件开头必须包含文件说明注释：
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
/**
|
|||
|
|
* 用户相关接口
|
|||
|
|
* @author 张三
|
|||
|
|
* @date 2024-01-01
|
|||
|
|
*/
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2.2 函数注释
|
|||
|
|
关键函数必须添加注释，说明功能、参数、返回值：
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
/**
|
|||
|
|
* 用户登录
|
|||
|
|
* @param {object} data 登录数据
|
|||
|
|
* @param {string} data.phone 手机号
|
|||
|
|
* @param {string} data.password 密码
|
|||
|
|
* @returns {Promise<object>} 登录结果
|
|||
|
|
*/
|
|||
|
|
export const login = (data) => {
|
|||
|
|
return request.post('/auth/login', data)
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2.3 复杂逻辑注释
|
|||
|
|
对于复杂的业务逻辑，必须添加行内注释：
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
// 检查Token是否过期
|
|||
|
|
if (tokenExpireTime < Date.now()) {
|
|||
|
|
// Token已过期，刷新Token
|
|||
|
|
await refreshToken()
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2.4 TODO注释
|
|||
|
|
待完成的功能使用 TODO 标记：
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
// TODO: 添加图片压缩功能
|
|||
|
|
// FIXME: 修复在iOS端的兼容性问题
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 三、代码风格规范
|
|||
|
|
|
|||
|
|
### 3.1 缩进与空格
|
|||
|
|
- 使用 2 个空格缩进
|
|||
|
|
- 运算符前后加空格
|
|||
|
|
- 逗号后加空格
|
|||
|
|
- 对象属性冒号后加空格
|
|||
|
|
|
|||
|
|
### 3.2 引号使用
|
|||
|
|
- JavaScript 统一使用单引号
|
|||
|
|
- HTML 属性统一使用双引号
|
|||
|
|
|
|||
|
|
### 3.3 分号使用
|
|||
|
|
- 语句结尾不使用分号（根据 Prettier 配置）
|
|||
|
|
|
|||
|
|
### 3.4 代码长度
|
|||
|
|
- 单行代码不超过 100 个字符
|
|||
|
|
- 函数代码行数不超过 50 行
|
|||
|
|
- 文件代码行数不超过 500 行
|
|||
|
|
|
|||
|
|
## 四、Vue 组件规范
|
|||
|
|
|
|||
|
|
### 4.1 组件结构顺序
|
|||
|
|
```vue
|
|||
|
|
<template>
|
|||
|
|
<!-- 模板内容 -->
|
|||
|
|
</template>
|
|||
|
|
|
|||
|
|
<script>
|
|||
|
|
// 1. 导入
|
|||
|
|
import { ref } from 'vue'
|
|||
|
|
|
|||
|
|
// 2. 组件定义
|
|||
|
|
export default {
|
|||
|
|
name: 'ComponentName',
|
|||
|
|
components: {},
|
|||
|
|
props: {},
|
|||
|
|
emits: [],
|
|||
|
|
setup() {
|
|||
|
|
// 3. 响应式数据
|
|||
|
|
// 4. 计算属性
|
|||
|
|
// 5. 方法
|
|||
|
|
// 6. 生命周期
|
|||
|
|
// 7. 返回
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
</script>
|
|||
|
|
|
|||
|
|
<style lang="scss" scoped>
|
|||
|
|
/* 样式内容 */
|
|||
|
|
</style>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 4.2 Props 定义
|
|||
|
|
Props 必须定义类型、默认值和校验：
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
props: {
|
|||
|
|
title: {
|
|||
|
|
type: String,
|
|||
|
|
required: true
|
|||
|
|
},
|
|||
|
|
count: {
|
|||
|
|
type: Number,
|
|||
|
|
default: 0,
|
|||
|
|
validator: (value) => value >= 0
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 4.3 事件命名
|
|||
|
|
- 使用短横线命名：`@update-value`
|
|||
|
|
- 使用动词开头：`@click`、`@change`、`@submit`
|
|||
|
|
|
|||
|
|
## 五、Git 提交规范
|
|||
|
|
|
|||
|
|
### 5.1 提交信息格式
|
|||
|
|
```
|
|||
|
|
<type>(<scope>): <subject>
|
|||
|
|
|
|||
|
|
<body>
|
|||
|
|
|
|||
|
|
<footer>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 5.2 Type 类型
|
|||
|
|
- `feat`: 新功能
|
|||
|
|
- `fix`: 修复 Bug
|
|||
|
|
- `docs`: 文档更新
|
|||
|
|
- `style`: 代码格式调整
|
|||
|
|
- `refactor`: 重构代码
|
|||
|
|
- `perf`: 性能优化
|
|||
|
|
- `test`: 测试相关
|
|||
|
|
- `chore`: 构建/工具链相关
|
|||
|
|
|
|||
|
|
### 5.3 提交示例
|
|||
|
|
```
|
|||
|
|
feat(login): 添加手机号验证码登录功能
|
|||
|
|
|
|||
|
|
- 实现验证码发送接口
|
|||
|
|
- 添加验证码输入组件
|
|||
|
|
- 完成登录逻辑
|
|||
|
|
|
|||
|
|
Closes #123
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 六、API 接口规范
|
|||
|
|
|
|||
|
|
### 6.1 接口文件组织
|
|||
|
|
按业务模块划分接口文件：
|
|||
|
|
```
|
|||
|
|
api/
|
|||
|
|
├── modules/
|
|||
|
|
│ ├── auth.js # 认证相关
|
|||
|
|
│ ├── user.js # 用户相关
|
|||
|
|
│ └── order.js # 订单相关
|
|||
|
|
└── index.js # 统一导出
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 6.2 接口命名
|
|||
|
|
- 使用动词开头：`getUserInfo`、`updateUserInfo`
|
|||
|
|
- RESTful 风格：`getList`、`getDetail`、`create`、`update`、`delete`
|
|||
|
|
|
|||
|
|
### 6.3 接口注释
|
|||
|
|
每个接口必须添加注释说明：
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
/**
|
|||
|
|
* 获取用户信息
|
|||
|
|
* @param {string} userId 用户ID
|
|||
|
|
* @returns {Promise<object>} 用户信息
|
|||
|
|
*/
|
|||
|
|
export const getUserInfo = (userId) => {
|
|||
|
|
return request.get(`/user/${userId}`)
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 七、样式规范
|
|||
|
|
|
|||
|
|
### 7.1 选择器命名
|
|||
|
|
- 使用短横线命名：`.user-card`、`.login-form`
|
|||
|
|
- 避免使用 ID 选择器
|
|||
|
|
- 避免使用标签选择器
|
|||
|
|
|
|||
|
|
### 7.2 样式组织
|
|||
|
|
```scss
|
|||
|
|
.component-name {
|
|||
|
|
// 1. 定位属性
|
|||
|
|
position: relative;
|
|||
|
|
|
|||
|
|
// 2. 盒模型属性
|
|||
|
|
display: flex;
|
|||
|
|
width: 100%;
|
|||
|
|
padding: 20rpx;
|
|||
|
|
|
|||
|
|
// 3. 文本属性
|
|||
|
|
font-size: 28rpx;
|
|||
|
|
color: #333;
|
|||
|
|
|
|||
|
|
// 4. 其他属性
|
|||
|
|
background-color: #fff;
|
|||
|
|
|
|||
|
|
// 5. 嵌套选择器
|
|||
|
|
.child-element {
|
|||
|
|
// ...
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 7.3 单位使用
|
|||
|
|
- 小程序端：使用 `rpx`
|
|||
|
|
- H5 端：使用 `rem` 或 `vw`
|
|||
|
|
- 固定尺寸：使用 `px`
|
|||
|
|
|
|||
|
|
## 八、性能优化规范
|
|||
|
|
|
|||
|
|
### 8.1 图片优化
|
|||
|
|
- 使用合适的图片格式（WebP、JPEG、PNG）
|
|||
|
|
- 压缩图片大小
|
|||
|
|
- 使用图片懒加载
|
|||
|
|
- 使用雪碧图合并小图标
|
|||
|
|
|
|||
|
|
### 8.2 代码优化
|
|||
|
|
- 避免在循环中进行复杂计算
|
|||
|
|
- 使用防抖和节流
|
|||
|
|
- 合理使用计算属性和侦听器
|
|||
|
|
- 及时清理定时器和事件监听
|
|||
|
|
|
|||
|
|
### 8.3 网络优化
|
|||
|
|
- 合并接口请求
|
|||
|
|
- 使用请求缓存
|
|||
|
|
- 实现请求重试机制
|
|||
|
|
- 避免重复请求
|
|||
|
|
|
|||
|
|
## 九、安全规范
|
|||
|
|
|
|||
|
|
### 9.1 数据安全
|
|||
|
|
- 敏感信息加密存储
|
|||
|
|
- Token 定期刷新
|
|||
|
|
- 防止 XSS 攻击
|
|||
|
|
- 防止 CSRF 攻击
|
|||
|
|
|
|||
|
|
### 9.2 权限控制
|
|||
|
|
- 实现路由权限控制
|
|||
|
|
- 实现接口权限控制
|
|||
|
|
- 实现按钮级权限控制
|
|||
|
|
|
|||
|
|
## 十、测试规范
|
|||
|
|
|
|||
|
|
### 10.1 单元测试
|
|||
|
|
- 工具函数必须编写单元测试
|
|||
|
|
- 测试覆盖率不低于 80%
|
|||
|
|
- 使用 Jest 测试框架
|
|||
|
|
|
|||
|
|
### 10.2 集成测试
|
|||
|
|
- 关键业务流程必须编写集成测试
|
|||
|
|
- 使用 uni-automator 进行自动化测试
|
|||
|
|
|
|||
|
|
### 10.3 测试命名
|
|||
|
|
```javascript
|
|||
|
|
describe('工具函数测试', () => {
|
|||
|
|
test('应该正确验证手机号', () => {
|
|||
|
|
expect(isPhone('13800138000')).toBe(true)
|
|||
|
|
})
|
|||
|
|
})
|
|||
|
|
```
|