Code帮帮队——β冲刺代码规范

[Code帮帮队]

这个作业属于哪个课程	202501福大-软件工程实践-W班
这个作业要求在哪里	团队作业—bate冲刺
这个作业的目标	制定并统一团队前后端代码规范
其他参考文献	无

目录

• 一、前端代码规范
• 1. 命名规范
• 通用规则
• 文件与文件夹命名
• 变量与函数命名
• 2. HTML 规范
• 结构与语义
• 缩进与排版
• 属性书写顺序（推荐）
• 3. CSS 规范
• 样式组织
• 命名：BEM 风格
• 格式要求
• 推荐写法
• 4. JavaScript 规范
• 语法
• 函数与模块
• 异步与错误处理
• 5. 注释规范
• 文件头
• 函数注释（JSDoc）
• 逻辑注释
• 6. 提交规范
• 提交信息格式
• 常用类型
• 分支命名
• 7. 代码审查与提交要求
• 二、后端代码规范（Java）
• （一）命名风格
• 【强制】
• 【推荐】
• 各层命名规约
• 领域模型命名
• （二）常量定义
• （三）代码格式
• （四）OOP 规约
• （五）集合处理
• （六）并发处理
• （七）控制语句
• （八）注释规约
• （九）其他
• 三、异常与日志
• 异常处理
• 日志规范
• 四、安全规约
• 五、MySQL 数据库规范
• 建表
• 索引
• SQL
• ORM（MyBatis）

---

一、前端代码规范

1. 命名规范

通用规则

• 使用英文单词，禁止拼音或中英混用。
• 全小写，单词间用 - 或 _ 分隔（如 user-profile）。
• 命名需语义明确，禁止无意义名称（如 a1, temp2）。

文件与文件夹命名

类型	命名示例	说明
页面文件	index.html, login.html	与功能对应
样式文件	main.css, user-profile.css	与页面/组件对应
JS 文件	main.js, api-helper.js	模块化命名
图片文件	logo.png, user-avatar.jpg	语义化命名

变量与函数命名

• 变量/函数：camelCase（如 userName, getUserInfo()）
• 常量：全大写 + 下划线（如 API_BASE_URL）
• 类/构造函数：首字母大写（如 UserCard, FormValidator）

---

2. HTML 规范

结构与语义

• 使用语义化标签：<header>, <nav>, <main>, <article>, <footer>
• 禁止滥用 <div>；标题层级按逻辑递增（<h1> → <h6>）
• 所有标签必须闭合，属性值加双引号

缩进与排版

• 统一使用 2 空格 缩进
• 每个标签独占一行，嵌套清晰

<div class="user-card">
  <h2 class="user-name">张三</h2>
  <p class="user-desc">软件工程专业</p>
</div>

属性书写顺序（推荐）

1. id
2. class
3. name
4. data-*
5. src / href
6. alt / title
7. aria-*

---

3. CSS 规范

样式组织

• 模块化：一个组件 = 一个样式文件
• 公共样式（颜色、间距等）放入 common.css
• 选择器层级 ≤ 3 层

命名：BEM 风格

.card {}
.card__title {}
.card--highlight {}

格式要求

• 每条样式独占一行
• 冒号后加空格
• 颜色用小写十六进制或 rgb()
• 使用简写（如 margin: 10px 20px;）

推荐写法

.button {
  display: inline-block;
  background-color: #2b7cff;
  color: #fff;
  border-radius: 8px;
  transition: 0.3s;
}
.button:hover {
  background-color: #1a5fd9;
}

---

4. JavaScript 规范

语法

• 使用 ES6+，优先 const / let，避免 var
• 每行结尾加分号 ;
• 严格使用 ===，避免 ==

函数与模块

• 单文件单职责
• 函数简短、单一职责
• 必须添加 JSDoc 注释

异步与错误处理

// 获取用户信息
async function getUserInfo(id) {
  const response = await fetch(`/api/user/${id}`);
  return await response.json();
}

// 错误捕获
try {
  await fetchData();
} catch (error) {
  console.error('获取数据失败：', error);
}

---

5. 注释规范

文件头

/**
 * 文件名: user.js
 * 功能: 用户信息获取与处理
 * 作者: 张三
 * 日期: 2025-10-29
 */

函数注释（JSDoc）

/**
 * 获取用户数据
 * @param {number} id - 用户 ID
 * @returns {Object} 用户数据对象
 */

逻辑注释

• 复杂逻辑必须说明
• 禁止无意义或与代码不符的注释

---

6. 提交规范

提交信息格式

[类型] 简要说明（≤20字）

示例：

• [feat] 新增用户登录页面
• [fix] 修复按钮点击无响应
• [refactor] 优化表单验证逻辑

常用类型

类型	说明
feat	新增功能
fix	修复 bug
refactor	代码重构
style	样式调整
docs	文档修改
test	测试相关

分支命名

• 功能分支：feature/login-page
• 修复分支：fix/bug-001
• 发布分支：release/v1.0

---

7. 代码审查与提交要求

• 提交前自测 + 格式化
• 禁止提交：
  • console.log 调试语句
  • 无用代码
  • 敏感信息（密钥、密码等）
• 提交后需进行一次代码审查，发现问题及时修正

---

二、后端代码规范（Java）

遵循《阿里巴巴 Java 开发手册》核心原则，结合项目实际调整。

（一）命名风格

【强制】

• 禁止以下划线 _ 或 $ 开头/结尾（如 _name, Object$）
• 禁止拼音/中文命名（DaZhePromotion ❌）
• 类名：UpperCamelCase（UserDO, TcpUdpDeal）
• 方法/变量：lowerCamelCase（getHttpMessage, inputUserId）
• 常量：全大写 + 下划线（MAX_STOCK_COUNT）
• 包名：全小写，单数（com.example.util）

【推荐】

• 自解释命名：PullCodeFromRemoteRepository
• 设计模式体现在命名中：OrderFactory, LoginProxy
• 接口方法不加 public 修饰符

各层命名规约

层级	方法前缀	示例
查询单个	get	getUserById()
查询多个	list	listUsersByRole()
统计	count	countOrders()
插入	save / insert	saveUser()
删除	remove / delete	removeUser()
更新	update	updateUserName()

领域模型命名

• xxxDO：数据对象（对应数据库表）
• xxxDTO：数据传输对象
• xxxVO：视图对象
• ❌ 禁止命名为 xxxPOJO

---

（二）常量定义

• 禁止魔法值（如 "Id#taobao_" + tradeId）
• long 初始化用大写 L（Long a = 2L;）
• 常量按功能分类维护（CacheConsts, ConfigConsts）
• 枚举类建议带 Enum 后缀（ProcessStatusEnum）

---

（三）代码格式

• 大括号：非空块换行，else 不换行
• 运算符两侧加空格：a = b + c
• 缩进：4 空格，禁用 Tab
• 单行 ≤ 120 字符，超长换行
• 方法参数逗号后加空格：method("a", "b")
• IDE 编码：UTF-8，换行符：Unix (\n)

---

（四）OOP 规约

• 静态成员用类名调用：UserService.getUserName()
• 覆写方法加 @Override
• equals 用常量调用："test".equals(obj)
• 包装类比较用 equals（避免 == 缓存陷阱）
• POJO 不设默认值，必须重写 toString()
• 循环拼接字符串用 StringBuilder

---

（五）集合处理

• 重写 equals 必须重写 hashCode
• subList() 不能强转为 ArrayList
• 转数组用 toArray(T[])
• Arrays.asList() 返回不可变列表
• 遍历 Map 用 entrySet()
• foreach 中禁止 remove/add，改用 Iterator

---

（六）并发处理

• 线程池用 ThreadPoolExecutor，禁用 Executors
• SimpleDateFormat 非线程安全，改用 DateTimeFormatter 或 ThreadLocal
• 高并发用 AtomicInteger，缩小锁范围
• 多资源加锁保持顺序一致，防死锁
• 定时任务用 ScheduledExecutorService，不用 Timer

---

（七）控制语句

• switch 必须含 default，每个 case 显式终止
• if/for/while 必须加大括号 {}，即使单行
• 多层 if-else 改用“卫语句”提前返回
• 循环体外移重复操作（如 DB 连接）

---

（八）注释规约

• 类/方法用 Javadoc（/** */）
• 所有类标注 @author 和 @date
• 枚举字段必须注释
• 用中文注释，专有名词保留英文
• 特殊标记：
  • // TODO: 张三 2025-10-29 补充权限校验
  • // FIXME: 李四 2025-10-29 修复空指针

---

（九）其他

• 正则预编译：Pattern.compile() 放方法外
• 页面变量输出用 $!{var} 防 null 显示
• 获取当前时间：System.currentTimeMillis()
• 视图模板中禁止复杂逻辑

---

三、异常与日志

异常处理

• 避免用 catch 处理 NullPointerException，应预检查
• 禁止用异常做流程控制
• finally 中关闭资源（推荐 try-with-resources）
• 自定义业务异常（如 ServiceException）

日志规范

• 使用 SLF4J 门面
• 日志文件保存 ≥15 天
• 输出用占位符：logger.debug("id: {}, name: {}", id, name);
• 异常日志包含参数 + 堆栈：logger.error("订单失败: {}", orderId, e);

---

四、安全规约

• 用户数据必须权限校验（防水平越权）
• 敏感信息脱敏（手机号 158****9119）
• SQL 参数绑定（MyBatis #{}），禁用字符串拼接
• 用户输入严格校验（防 SQL 注入、XSS、ReDoS）
• 表单提交需 CSRF 防护
• 短信/支付等资源需防重放（频率限制 + 验证码）

---

五、MySQL 数据库规范

建表

• 布尔字段：is_deleted，类型 TINYINT(1)
• 表名/字段名：小写 + 数字，禁用保留字
• 必备字段：id（BIGINT）、gmt_create、gmt_modified
• 小数用 DECIMAL，字符串用 VARCHAR（≤5000）

索引

• 唯一字段建唯一索引（uk_phone）
• JOIN ≤3 表，关联字段必须有索引
• 禁止左模糊查询（LIKE '%xx'）
• 超分页用子查询优化

SQL

• 用 COUNT(*)，不用 COUNT(col)
• 分页前先查总数，为 0 则跳过
• 禁用外键、存储过程、TRUNCATE
• 更新必须带 gmt_modified = NOW()

ORM（MyBatis）

• 禁用 select *
• POJO 布尔属性不加 is（deleted），DB 字段加 is_（is_deleted）
• 必须定义 resultMap
• 参数绑定用 #{}，禁用 ${}

---