答题玩家——β冲刺代码规范

答题玩家团队账号 2025-11-22 20:10:57

这个作业属于哪个课程	2501_CS_SE_FZU
这个作业要求在哪里	团队作业β冲刺
这个作业的目标	阐述团队的β冲刺代码规范
其他参考文献	Java开发手册（黄山版），微信官方文档

后端
1. 命名规范 (参考《阿里手册》第一章)
2. 编码与异常处理 (参考《阿里手册》第三、四章)
3. DTO 与层级规范 (团队核心规范)
4. 修改要求
4. 数据库与 ORM 规范
5. 接口设计原则
前端
1. 总体原则
2. 页面目录结构规范
2.1 目录层级
3. 各文件内容规范
3.1 .wxml 文件（页面结构）
3.2 .wxss 文件（页面样式）
3.3 .js 文件（页面逻辑）
3.4 .json 文件（页面配置）
4.其他建议
Git 提交规范

为保证代码质量、可读性和一致性，我们参考《阿里巴巴Java开发手册 v1.3.0》和华为内部代码规范以及微信小程序开发代码规范（前端）的核心思想，制定了本次β冲刺必须遵守的核心规范：

后端

1. 命名规范 (参考《阿里手册》第一章)

【强制】 类名使用 UpperCamelCase (大驼峰)。
【强制】 方法名、参数名、成员变量使用 lowerCamelCase (小驼峰)。
【强制】 常量名全部大写，单词间用下划线隔开 (UPPER_SNAKE_CASE)。
【强制】 包名统一使用小写，点分隔符之间只有一个单词 (如 com.example.exam.controller)。
【推荐】 DTO类名使用 ...DTO (如UserLoginDTO) 结尾。
【强制】不允许使用任何缩写，如result缩写成ret，因为可能造成误解

2. 编码与异常处理 (参考《阿里手册》第三、四章)

【强制】 禁止使用魔法值。 代码中不允许出现未经定义的字面量（如 if (status == 1)）。必须定义为常量（如 private static final int STATUS_SUCCESS = 1;）。
【强制】 空指针处理 (NPE)。 必须对可能为 null 的对象（尤其是方法入参、RPC/DB查询结果）进行校验。优先使用 spring-boot-starter-validation（如 @NotNull）在 Controller 层进行参数校验。
【强制】 分层异常处理。
- Service 层捕获具体异常（如 SQLException），处理后向上抛出自定义的业务异常（如 ExamNotFoundException）。
- Controller 层禁止 try-catch 业务逻辑。
- 由全局异常处理器 (@RestControllerAdvice) 统一捕获业务异常，并返回统一错误码：{ "code": 1001, "message": "考试不存在" }。

3. DTO 与层级规范 (团队核心规范)

【强制】 严格的 DTO 隔离。
- Controller 层的所有请求（入参）和响应（出参）必须使用 dto 包下的专用类。
- domain（实体类，如Question）严禁出现在 Controller 层，防止数据库字段变更导致API变更。

4. 修改要求

改他人负责的模块时务必谨慎。如确有必要改动，应先与对应负责人沟通，修改完成后还需完整测试相关功能，确保不会引入回归问题。
严禁将未完成或未经测试的代码推送到共享仓库

4. 数据库与 ORM 规范

【强制】 实体类（Entity）必须使用 JPA 注解（如 @Entity, @Table, @Column），字段名与数据库列名保持一致或通过 @Column(name = "...") 显式映射。
【推荐】 查询逻辑优先使用 Spring Data JPA 的方法命名规范（如 findByUserIdAndStatus），复杂查询再考虑 @Query。
【强制】 禁止在 Service 层直接拼接 SQL 字符串，防止 SQL 注入。所有动态查询必须通过参数化方式实现（如 ?1 或命名参数）。

5. 接口设计原则

【强制】 所有对外 API 必须返回统一的响应结构，例如：
```
json
{
  "code": 200,
  "message": "success",
  "data": { ... }
}
```
其中 code=200 表示成功，非 200 表示业务或系统错误（由全局异常处理器统一处理）。

前端

1. 总体原则

模块化组织：每个页面独立成目录，避免文件混杂。
命名一致性：页面文件夹名与内部四个文件的主文件名必须完全一致。
职责分离：结构（WXML）、样式（WXSS）、逻辑（JS）、配置（JSON）各司其职。
可维护性优先：代码清晰、注释完整、格式统一。

2. 页面目录结构规范

2.1 目录层级

所有页面必须位于 pages/ 目录下（或自定义但需在 app.json 中注册），每个页面对应一个独立文件夹。

 /pages
    /home              # 页面文件夹（建议小写，单词间用连字符）
      home.wxml        # 页面结构
      home.wxss        # 页面样式
      home.js          # 页面逻辑
      home.json        # 页面配置
    /user-profile
      user-profile.wxml
      user-profile.wxss
      user-profile.js
      user-profile.json

3. 各文件内容规范

3.1 `.wxml` 文件（页面结构）

遵循 WXML 语法，禁止直接写 HTML 标签。
使用语义化组件（如 <view>、<text>、<button> 等）。
数据绑定使用双大括号 {{ }}。
事件绑定使用 bind:xxx 或 catch:xxx。
注释使用 。

示例（home.wxml）

<!-- 首页结构 -->
<view class="container">
  <text class="title">{{ greeting }}</text>
  <button bindtap="onButtonClick">点击我</button>
</view>

3.2 `.wxss` 文件（页面样式）

使用 WXSS 语法，支持 rpx 单位、Flex 布局等。
类名采用 BEM 风格 或 语义化命名（如 .container, .btn-primary）。
避免使用 ID 选择器（小程序不支持 #id）。
全局样式写在 app.wxss，页面私有样式写在本文件。
注释使用 /* 注释内容 */。

3.3 `.js` 文件（页面逻辑）

必须调用 Page({}) 注册页面。
生命周期函数按顺序书写（onLoad, onShow, onReady 等）。
方法命名采用小驼峰（如 handleClick）。
异步操作使用 async/await 或 Promise。
全局数据通过 getApp() 获取，避免硬编码。
添加必要 JSDoc 注释。

3.4 `.json` 文件（页面配置）

必须为合法 JSON 格式（无注释、无尾逗号）。
仅包含页面级配置项（如导航栏、窗口背景色等）。
若无需特殊配置，可留空 {} 或省略（但建议保留以保持结构统一）。

4.其他建议

由于代码规范编写人员是后端小组，未参与前端代码编写，如果对前端代码规范的规定有错误或者出入，以前端小组商讨的结果为准。

Git 提交规范

【强制】 提交信息 (Message) 必须有意义，采用 类型: 描述 格式。
- feat: (新功能), fix: (修复Bug), docs: (文档), refactor: (重构), style: (代码格式), test: (测试)。这个可以用中文，要求描述简洁，可以一下子就看出了提交作了哪些修改
- 示例： feat: 实现提交考试评分逻辑，也可以用中文，如新功能：实现提交考试评分逻辑
介于α冲刺的经验，如果大量删除代码，务必做出详细说明，并且告知组内其他成员。