哈基米队——代码规范

哈基米队 2025-11-25 21:25:58

这个作业属于哪个课程	2501_CS_SE_FZU
这个作业要求在哪里	团队作业—Beta冲刺
团队名称	哈基米队
这个作业的目标	Beta冲刺代码规范

1.后端
1. 包结构规范
2. 命名规范
2.1 类命名
2.2 方法命名
2.3 变量命名
2.4 常量命名
3. 接口与实现规范
4. 注释规范
4.1 类注释
4.2 方法注释
5. 数据库操作规范
5.1 Mapper 接口规范
5.2 MyBatis 映射文件规范
6. 业务逻辑规范
6.1 分页处理
6.2 事务管理
6.3 并发控制
7. 异常处理
8. 配置规范
9. Vue 组件规范
2.前端
1. 样式规范
2. JavaScript 代码规范
3. 路由规范
4. 第三方库使用规范

1.后端

1. 包结构规范

项目采用清晰的分层包结构，符合 Java Web 开发的常见模式：
service：存放业务服务接口
service.impl：存放业务服务实现类
mapper：存放数据访问接口
entity：存放实体类
vo：存放视图对象（如 PageVo、R）
utils：存放工具类

2. 命名规范

2.1 类命名

采用 PascalCase 命名法（首字母大写）
实体类：与数据库表对应，如IdleItem、Order、User
接口类：以业务名称 + Service/Mapper 结尾，如IdleItemService、OrderMapper
实现类：以接口名 + Impl 结尾，如IdleItemServiceImpl、OrderServiceImpl

2.2 方法命名

采用 camelCase 命名法（首字母小写）
遵循 "动词 + 名词" 的命名模式：
添加操作：addIdleItem、insert
查询操作：getIdleItem、findIdleItem
更新操作：updateIdleItem
删除操作：deleteByPrimaryKey

2.3 变量命名

采用 camelCase 命名法
成员变量：如idleItemMapper、userId
方法参数：如id、page、nums

2.4 常量命名

采用 UPPER_SNAKE_CASE 命名法（全大写，下划线分隔）
如lockMap中使用的锁机制相关常量

3. 接口与实现规范

接口定义业务方法，不包含实现
实现类通过@Service注解标识，并实现对应接口
实现类中通过@Resource注解注入依赖，如：

@Resource
private IdleItemMapper idleItemMapper;

4. 注释规范

4.1 类注释

每个类都包含类注释，说明类的功能、作者和日期
格式统一，如：

/**
 * 闲置物品 服务层
 *
 * @author: ShanZhu
 * @date: 2024-01-05
 */

4.2 方法注释

每个方法都包含方法注释，说明方法功能、参数含义和返回值
如：

/**
 * 搜索闲置商品
 *
 * @param findValue 值
 * @param page      分页大小
 * @param nums      页数
 * @return 结果
 */
PageVo<IdleItem> findIdleItem(String findValue, int page, int nums);

5. 数据库操作规范

5.1 Mapper 接口规范

Mapper 接口使用@Mapper注解标识
方法名与 SQL 操作对应，如selectByPrimaryKey、insertSelective
分页查询统一使用begin和nums参数控制分页

5.2 MyBatis 映射文件规范

XML 文件名与 Mapper 接口名保持一致
使用定义结果映射
使用标签抽取公共字段列表，如：

<sql id="Base_Column_List">
  id, idle_name, idle_details, picture_list, idle_price, idle_place, idle_label, release_time, 
  idle_status, user_id
</sql>

动态 SQL 使用、等标签实现

6. 业务逻辑规范

6.1 分页处理

统一使用PageVo类封装分页结果，包含数据列表和总条数
分页参数统一为page（页码）和nums（每页条数）
计算分页起始位置：(page - 1) * nums

6.2 事务管理

关键业务操作使用@Transactional注解保证事务一致性
如订单创建和状态更新：

@Transactional(rollbackFor = Exception.class)
public boolean addOrderHelp(IdleItem idleItem, Order order) {
    // 业务逻辑
}

6.3 并发控制

采用锁机制处理并发问题，如订单创建时的商品状态控制：

private static HashMap<Integer, ReentrantLock> lockMap = new HashMap<>();

// 使用锁保证并发安全

7. 异常处理

业务异常通过RuntimeException抛出，配合事务回滚
接口返回统一使用R类封装，包含状态码、消息和数据：

public static R success() {
    R r = new R();
    r.setStatus_code(1);
    return r;
}

8. 配置规范

使用application.yml统一管理配置信息
数据库配置、文件上传限制、路径配置等集中管理
配置项命名清晰，如max-file-size、userFilePath

9. Vue 组件规范

模板结构：组件模板使用template标签包裹，结构清晰，合理使用 div 等标签进行布局嵌套，如IdleGoods.vue中通过多层 div 和 el-table 等元素构建页面结构。
组件命名：组件名称采用帕斯卡命名法（如AppHeader、IdleGoods）或短横线分隔命名，符合 Vue 组件命名习惯。
组件注册：在组件的components选项中注册需要使用的子组件，如platform-admin.vue中注册了AppFoot、IdleGoods等组件。

2.前端

1. 样式规范

采用 scoped 属性隔离组件样式，避免样式冲突，如每个组件的style scoped标签。
类名命名多采用小写字母加短横线分隔的形式（如foot-container、idle-card），语义清晰，便于理解样式对应的功能模块。
合理使用 Flex 布局进行页面元素的排列，如foot-container中使用display: flex; justify-content: center;实现内容居中。

2. JavaScript 代码规范

数据管理：组件的数据放在data函数返回的对象中，便于组件内部管理和使用，如IdleGoods.vue中定义了mode、nowPage等数据。
方法定义：组件的方法放在methods选项中，函数命名采用驼峰命名法（如handleCurrentChange、getOnlineGoods），功能明确。
生命周期钩子：合理使用 Vue 的生命周期钩子函数，如created钩子用于组件创建时获取数据，如IdleGoods.vue在created中调用getOnlineGoods方法。
API 调用：通过this.$api调用后端接口，统一管理接口调用，如idle-details.vue中调用this.$api.updateIdleItem更新商品状态。