代码规范文档

1. 概述

本文档描述了 CRMEB 项目的代码规范，包括 PHP、Vue、JavaScript 等语言的编码标准，旨在统一代码风格，提高代码质量和可维护性。

2. PHP 代码规范

2.1 命名规范

类名：使用 PascalCase 命名风格，如 UserController
方法名：使用 camelCase 命名风格，如 getUserList
变量名：使用 camelCase 命名风格，如 $userName
常量：使用全大写字母和下划线分隔，如 MAX_PAGE_SIZE
属性名：使用 camelCase 命名风格，如 $userId
文件名：与类名一致，使用 PascalCase 命名风格，如 UserController.php
目录名：使用小写字母，单词之间用下划线分隔，如 user_service

2.2 代码格式

缩进：使用 4 个空格进行缩进，禁止使用制表符
行宽：每行代码不超过 120 个字符
空行：在类、方法、逻辑块之间使用空行分隔
空格：
- 在操作符两边使用空格，如 $a = $b + $c
- 在逗号后使用空格，如 function($a, $b, $c)
- 在括号内不使用空格，如 if($condition)

2.3 注释规范

类注释：使用 DocBlock 注释类的功能、作者和版本
方法注释：使用 DocBlock 注释方法的功能、参数、返回值和异常
代码注释：对复杂的代码逻辑添加注释
TODO 注释：使用 // TODO: 标记待完成的任务

2.4 代码结构

类结构：
- 类的声明
- 属性声明
- 构造方法
- 其他方法
方法结构：
- 参数声明
- 变量声明
- 业务逻辑
- 返回语句

2.5 最佳实践

单一职责：每个类和方法只负责一个功能
代码复用：抽取公共代码为方法或类
异常处理：使用 try-catch 处理异常
类型提示：使用类型提示增强代码可读性
魔术方法：谨慎使用魔术方法

3. Vue 代码规范

3.1 命名规范

组件名：使用 PascalCase 命名风格，如 UserList
props：使用 camelCase 命名风格，如 userName
data 属性：使用 camelCase 命名风格，如 userList
methods：使用 camelCase 命名风格，如 getUserList
事件名：使用 kebab-case 命名风格，如 user-clicked
插槽名：使用 kebab-case 命名风格，如 header-content

3.2 代码格式

缩进：使用 2 个空格进行缩进
行宽：每行代码不超过 120 个字符
空行：在不同逻辑块之间使用空行分隔
空格：
- 在操作符两边使用空格
- 在逗号后使用空格
- 在括号内不使用空格

3.3 模板规范

标签名：使用 kebab-case 命名风格，如 <user-list>
属性名：使用 kebab-case 命名风格，如 :user-name="userName"
指令缩写：使用 : 代替 v-bind:，使用 @ 代替 v-on:
模板表达式：保持模板表达式简洁，复杂逻辑应在计算属性或方法中处理

3.4 组件结构

template：模板部分
script：脚本部分
style：样式部分

3.5 最佳实践

组件拆分：将复杂组件拆分为多个子组件
计算属性：使用计算属性处理复杂的响应式数据
监听器：使用监听器监听数据变化
混入：使用混入复用组件逻辑
指令：使用自定义指令封装 DOM 操作

4. JavaScript 代码规范

4.1 命名规范

变量名：使用 camelCase 命名风格，如 userName
函数名：使用 camelCase 命名风格，如 getUserList
常量：使用全大写字母和下划线分隔，如 MAX_PAGE_SIZE
对象属性：使用 camelCase 命名风格，如 userName
类名：使用 PascalCase 命名风格，如 UserService

4.2 代码格式

缩进：使用 2 个空格进行缩进
行宽：每行代码不超过 120 个字符
空行：在不同逻辑块之间使用空行分隔
空格：
- 在操作符两边使用空格
- 在逗号后使用空格
- 在括号内不使用空格

4.3 代码结构

函数声明：使用函数表达式或箭头函数
对象字面量：使用简洁的对象字面量语法
数组字面量：使用简洁的数组字面量语法
条件语句：使用简洁的条件语句语法
循环语句：使用简洁的循环语句语法

4.4 最佳实践

变量声明：使用 let 和 const 声明变量，避免使用 var
箭头函数：在适当的场景使用箭头函数
模板字符串：使用模板字符串代替字符串拼接
解构赋值：使用解构赋值简化代码
展开运算符：使用展开运算符简化代码
异步编程：使用 async/await 处理异步操作

5. HTML/CSS 代码规范

5.1 HTML 规范

标签名：使用小写字母，如 <div>
属性名：使用小写字母，如 class="container"
属性值：使用双引号包围，如 class="container"
缩进：使用 2 个空格进行缩进
嵌套：保持标签嵌套层次清晰
注释：对复杂的 HTML 结构添加注释

5.2 CSS 规范

选择器：使用小写字母和连字符分隔，如 .user-list
属性名：使用小写字母，如 font-size
属性值：使用小写字母，如 color: #333
缩进：使用 2 个空格进行缩进
分号：每个属性声明后添加分号
空行：在不同选择器之间使用空行分隔
注释：对复杂的 CSS 规则添加注释

5.3 最佳实践

语义化标签：使用语义化的 HTML 标签
CSS 预处理器：使用 SCSS 或 Less 等 CSS 预处理器
BEM 命名：使用 BEM 命名规范组织 CSS 类名
响应式设计：使用媒体查询实现响应式设计
CSS 变量：使用 CSS 变量管理样式值

6. 数据库规范

6.1 命名规范

数据库名：使用小写字母和下划线分隔，如 crmeb_db
表名：使用小写字母和下划线分隔，如 user
字段名：使用小写字母和下划线分隔，如 user_name
索引名：使用小写字母和下划线分隔，如 idx_user_name

6.2 设计规范

主键：使用 id 作为主键，自增整数类型
外键：使用 表名_id 作为外键，如 user_id
时间字段：使用 create_time 和 update_time 作为时间字段
状态字段：使用 status 作为状态字段，默认值为 0
软删除：使用 delete_time 作为软删除字段

6.3 最佳实践

范式设计：遵循数据库设计范式
索引优化：为经常查询的字段添加索引
分区表：对大表进行分区
事务处理：使用事务保证数据一致性
备份策略：定期备份数据库

7. 代码审查

7.1 审查内容

代码风格：是否符合代码规范
代码质量：是否存在代码异味
安全性：是否存在安全漏洞
性能：是否存在性能问题
功能：是否实现了需求功能

7.2 审查流程

提交代码：开发者提交代码到版本控制系统
代码审查：审查者审查代码
反馈修改：审查者提供反馈，开发者修改代码
合并代码：代码审查通过后合并代码

7.3 审查工具

ESLint：JavaScript 代码审查工具
PHP CodeSniffer：PHP 代码审查工具
Prettier：代码格式化工具
SonarQube：代码质量分析工具

8. 版本控制规范

8.1 Git 规范

分支命名：使用小写字母和连字符分隔，如 feature/user-auth
提交信息：使用中文描述，格式为 [模块名] 操作描述，如 [用户] 添加用户登录功能
提交频率：每个功能或 bug 修复单独提交
代码冲突：及时解决代码冲突

8.2 版本号规范

使用语义化版本号，格式为 主版本号.次版本号.修订号，如 5.6.4：

主版本号：不兼容的 API 变更
次版本号：向下兼容的功能新增
修订号：向下兼容的问题修正

9. 最佳实践

代码可读性：编写易于理解的代码
代码可维护性：编写易于维护的代码
代码可测试性：编写易于测试的代码
代码可扩展性：编写易于扩展的代码
代码安全性：编写安全的代码
代码性能：编写高性能的代码

10. 参考资源