6.4 KiB
6.4 KiB
开发规范文档
一、命名规范
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 文件注释
每个文件开头必须包含文件说明注释：
/**
* 用户相关接口
* @author 张三
* @date 2024-01-01
*/
2.2 函数注释
关键函数必须添加注释，说明功能、参数、返回值：
/**
* 用户登录
* @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 复杂逻辑注释
对于复杂的业务逻辑，必须添加行内注释：
// 检查Token是否过期
if (tokenExpireTime < Date.now()) {
// Token已过期，刷新Token
await refreshToken()
}
2.4 TODO注释
待完成的功能使用 TODO 标记：
// TODO: 添加图片压缩功能
// FIXME: 修复在iOS端的兼容性问题
三、代码风格规范
3.1 缩进与空格
- 使用 2 个空格缩进
- 运算符前后加空格
- 逗号后加空格
- 对象属性冒号后加空格
3.2 引号使用
- JavaScript 统一使用单引号
- HTML 属性统一使用双引号
3.3 分号使用
- 语句结尾不使用分号（根据 Prettier 配置）
3.4 代码长度
- 单行代码不超过 100 个字符
- 函数代码行数不超过 50 行
- 文件代码行数不超过 500 行
四、Vue 组件规范
4.1 组件结构顺序
<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 必须定义类型、默认值和校验：
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: 修复 Bugdocs: 文档更新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 接口注释
每个接口必须添加注释说明：
/**
* 获取用户信息
* @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 样式组织
.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 测试命名
describe('工具函数测试', () => {
test('应该正确验证手机号', () => {
expect(isPhone('13800138000')).toBe(true)
})
})