# 开发规范文档 ## 一、命名规范 ### 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} 登录结果 */ 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 ``` ### 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 提交信息格式 ``` ():