考试系统项目规范

规则1：接口设计规则

HTTP方法规范

操作	HTTP方法	说明
新增	POST	创建资源
更新	PUT	更新已有资源
查询	GET	获取资源
删除	DELETE	删除资源

API命名后缀

操作	后缀	示例
新增	save	/api/user/save
更新	edit	/api/user/edit
查询（列表）	list	/api/user/list
删除	delete	/api/user/delete
分页	page	/api/user/page
批量添加	batch	/api/user/batch
导出	export	/api/user/export
导入	import	/api/user/import

参数传递规范

4. 禁止使用@PathVariable，统一使用@RequestParam传递参数
   • 反例：/api/user/delete/{id} + @DeleteMapping("/delete/{id}") + @PathVariable Long id
   • 正例：/api/user/delete + @DeleteMapping("/delete") + @RequestParam Long id

规则2：方法命名规则

Service层返回类型

• 新增、更新、删除操作：返回 boolean 表示操作是否成功

Controller层响应规则

根据Service层返回结果，构造对应的SaResult响应：

操作	Service返回	Controller返回
新增	true	SaResult.data("保存成功") 或 SaResult.ok("保存成功")
新增	false	SaResult.error("保存失败")
更新	true	SaResult.data("更新成功") 或 SaResult.ok("更新成功")
更新	false	SaResult.error("更新失败")
删除	true	SaResult.data("删除成功") 或 SaResult.ok("删除成功")
删除	false	SaResult.error("删除失败")
查询	数据	SaResult.data(数据)
分页	数据	SaResult.data(数据)

规则3：实体类规范

序列化要求

所有实体类必须实现 Serializable 接口，并定义 serialVersionUID。

示例代码

package com.exam.system.entity;

import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import java.io.Serializable;
import java.util.Date;

@TableName("sys_user")
public class SysUser implements Serializable {
    
    @Serial
    private static final long serialVersionUID = 1L;
    
    @TableId(type = IdType.AUTO)
    private Long id;
    
    private String username;
    private String password;
    private String nickname;
    private Integer status;
    private Date createTime;
    private Date updateTime;
    
    // getter/setter 方法...
}

规则4：代码规范

4.1 禁止使用魔法值

代码中不允许出现魔法值（直接硬编码的数字、字符串等），必须统一定义常量或枚举。

反例

// 禁止使用魔法值
if (user.getStatus() == 1) {
    // 1 表示什么？
}

// 禁止使用魔法值
user.setStatus(0);  // 0 表示什么？

正例

// 使用枚举
if (user.getStatus() == UserStatus.ENABLE.getCode()) {
    // 清晰明确
}

// 使用常量
user.setStatus(UserStatus.DISABLE.getCode());

// 或者
public class UserStatus {
    public static final int ENABLE = 1;
    public static final int DISABLE = 0;
}

枚举定义示例

package com.exam.common.enums;

public enum UserStatus {
    ENABLE(1, "启用"),
    DISABLE(0, "禁用");
    
    private final int code;
    private final String desc;
    
    UserStatus(int code, String desc) {
        this.code = code;
        this.desc = desc;
    }
    
    public int getCode() {
        return code;
    }
    
    public String getDesc() {
        return desc;
    }
}

4.2 Service层返回类型规范

• 新增、更新、删除操作：Service层必须返回 boolean 类型
• Controller层根据Service层返回结果，构造对应的 SaResult 响应

4.3 Controller层职责规范

• Controller层只做数据校验，不做任何业务逻辑
• 所有业务逻辑必须放在Service层
• Controller层只负责：
  1. 接收参数并校验（@Valid、@RequestParam必填校验等）
  2. 调用Service层方法
  3. 根据Service返回结果构造SaResult响应
• 禁止在Controller层写业务逻辑（如计算、判断、数据库操作等）

Service层示例

public interface SysUserService {
    boolean saveUser(SysUser user);
    boolean updateUser(SysUser user);
    boolean deleteUserById(Long id);
    SysUser getUserById(Long id);
    IPage<SysUser> pageUser(Page<SysUser> page, SysUser user);
}

Controller层示例

@RestController
@RequestMapping("/api/user")
public class SysUserController {
    
    @Autowired
    private SysUserService userService;
    
    @PostMapping("/save")
    public SaResult save(@RequestBody SysUser user) {
        boolean result = userService.saveUser(user);
        return result ? SaResult.data("保存成功") : SaResult.error("保存失败");
    }
    
    @PutMapping("/edit")
    public SaResult edit(@RequestBody SysUser user) {
        boolean result = userService.updateUser(user);
        return result ? SaResult.data("更新成功") : SaResult.error("更新失败");
    }
    
    @DeleteMapping("/delete/{id}")
    public SaResult delete(@PathVariable Long id) {
        boolean result = userService.deleteUserById(id);
        return result ? SaResult.data("删除成功") : SaResult.error("删除失败");
    }
    
    @GetMapping("/list")
    public SaResult list(SysUser user) {
        List<SysUser> list = userService.listUser(user);
        return SaResult.data(list);
    }
    
    @GetMapping("/page")
    public SaResult page(Page<SysUser> page, SysUser user) {
        IPage<SysUser> result = userService.pageUser(page, user);
        return SaResult.data(result);
    }
}

附录：常见状态码枚举示例

package com.exam.common.enums;

public enum QuestionType {
    SINGLE_CHOICE(1, "单选题"),
    MULTIPLE_CHOICE(2, "多选题"),
    JUDGE(3, "判断题"),
    FILL_BLANK(4, "填空题"),
    ESSAY(5, "问答题");
    
    private final int code;
    private final String desc;
    
    QuestionType(int code, String desc) {
        this.code = code;
        this.desc = desc;
    }
    
    public int getCode() {
        return code;
    }
    
    public String getDesc() {
        return desc;
    }
}

package com.exam.common.enums;

public enum ExamStatus {
    NOT_START(0, "未开始"),
    ONGOING(1, "进行中"),
    FINISHED(2, "已结束"),
    CANCELLED(3, "已取消");
    
    private final int code;
    private final String desc;
    
    ExamStatus(int code, String desc) {
        this.code = code;
        this.desc = desc;
    }
    
    public int getCode() {
        return code;
    }
    
    public String getDesc() {
        return desc;
    }
}

规范检查

• 所有实体类必须添加 implements Serializable 和 serialVersionUID
• 所有状态、类型字段必须使用枚举或常量，禁止魔法值
• 接口URL必须遵循后缀规范
• Service层增删改操作必须返回boolean
• Controller层必须根据Service返回结果构造SaResult响应