数据库表要求

重要程度 ★★★★★

  • 新建数据库表时, 所有的表须添加7个必要字段（create_date、create_user_id、create_user_name、update_date、update_user_id、update_user_name、delete_flag）
  • 这7个字段程序员写代码无需进行操作（赋值和修改） 框架会自动在执行sql的时候维护这几个字段
  • 用户查询数据时也不需要在where条件后面加 delete_flag = 0。在执行查询操作时 框架会自动在要执行的sql后面拼接delete_flag = 0
  • 也就是只需要再每个表中添加以下字段、无需维护
  • 数据库表名如果是多个单词 建议使用_分隔
  • 所有字段必须设置备注 （COMMENT'创建时间'）因为代码生成后接口文档的字段介绍文字就是取数据库备注
  • 数据库表如果是多个单词 建议使用_分隔 备注如果是枚举 建议用 性别 1 男 0 女 2 未知 格式命名，后续自定义注解记录修改记录会用到 如不使用可忽略
`create_date` datetime DEFAULT NULL COMMENT '创建时间',
`create_user_id` varchar(36) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci DEFAULT NULL COMMENT '创建用户id',
`create_user_name` varchar(36) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci DEFAULT NULL COMMENT '创建用户名称',
`update_date` datetime DEFAULT NULL COMMENT '修改时间',
`update_user_id` varchar(36) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci DEFAULT NULL COMMENT '修改用户id',
`update_user_name` varchar(36) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci DEFAULT NULL COMMENT '修改用户名称',
`delete_flag` tinyint DEFAULT NULL COMMENT '删除状态 0正常 1删除',
图片

控制器编码规范

控制器类名规范

  • 添加@Api注解 用于在接口文档中显示
  • 添加@ApiSupport order 表示改接口在文档中显示位置
  • @RequestMapping("/auth/project") 接口名称命名首字母建议用微服务名（auth） 后面是功能名称 多个单词用/分隔
@RestController
@RequestMapping("/auth/project")
@Api(tags = "项目相关接口", value = "项目相关接口")
@ApiSupport(order = 6)
public class ProjectController {

控制器规范

  • @PreAuthorize 权限控制注解 hasPermission 第一个参数表示完整的域名 第二个表示方法权限（需要配置在鉴权系统中）在注解介绍里面会有详细介绍
  • @ApiOperation 接口文档描述，必须加。同时也是日志记录接口名称取值的地方 notes 是给使用文档的人看 调用这个接口需要那个权限 方便前端人员配置权限
  • @KPVerifyNote 开启注解校验 会在注解介绍章节详细描述
  • 所有的接口返回内容都需要返回KPResult对象 建议最好别返回自定义的方法
@PreAuthorize("hasPermission('/auth/project/page/list', 'auth:project:page:list')")
@ApiOperation(value = "查询项目分页列表", notes = "权限 auth:project:page:list")
@PostMapping("/page/list")
@KPVerifyNote
public KPResult<ProjectPO> queryPageList(@RequestBody ProjectListParamPO projectListParamPO){
    return KPResult.list(projectService.queryPageList(projectListParamPO));
}`
图片

service层编码规范

重要程度 ★★★★

Service层命名要符合规范、框架在符合规范的service层自动加事务，不需要程序员额外手动加注解

  • 查询方法没有事务, 但建议以query开头，保持整个项目风格一致 如 queryPageList
  • 新增方法须以 add或save 开头 如 saveUser
  • 修改方法须以 update 开头 如 updateUser
  • 修改方法须以 remove或delete 开头 如 removeUser
  • 批量操作且需要事务的以 batch 开头 如 batchRemove
  • 其他功能且需要事务的以 do 开头 如 doCancel
  • 最高隔离级别事务以 secure 开头 如 secureSave
/**
 * @Author lipeng
 * @Description 根据用户Id查询详情
 * @Date 2025-04-21 20:00:54
 * @param parameter
 * @return UserDetailsCustomerPO
 **/
public UserDetailsCustomerPO queryDetailsById(JSONObject parameter) {
}

/**
 * @Author lipeng
 * @Description 新增用户信息
 * @Date 2025-04-21 20:00:58
 * @param userEditParamPO
 * @return void
 **/
public void saveUser(UserEditParamPO userEditParamPO) {
}
/**
 * @Author lipeng
 * @Description 修改用户信息
 * @Date 2025-04-21 20:00:58
 * @param userEditParamPO
 * @return void
 **/
public void updateUser(UserEditParamPO userEditParamPO) {
}

/**
 * @Author lipeng
 * @Description 批量删除用户信息
 * @Date 2025-04-21 20:00:59
 * @param ids
 * @return String
 **/
public String batchRemove(List<String> ids) {
}

/**
 * @Author lipeng
 * @Description 管理员密码重置
 * @Date 2025/5/8 20:37
 * @param parameter
 * @return void
 **/
public void doReset(JSONObject parameter) {
}

mapper层和XML编码规范

重要程度 ★★★★

  • mapper层代码使用代码生成器会自动生成、禁止在生成的文件里面添加代码
  • 如果需要新增，请在mapper包下新建customer包名 在创建自定义mapper类 例如 代码生成器生成的代码是 UserMapper 需要在 customer 下新建 UserCustomerMapper extends UserMapper 并添加@Primary 注解
  • xml 文件默认保存在 resources下的mapper 文件夹下
  • 规格和mapper一样 不允许在生成的代码里面写代码, 如果需要自定义sql、在xml 目录下新建customer文件夹 在customer 新增自己的xml
  • 在写自己的sql时 查询的字段需要继承自动生成的字段，不允许自己写 这样可以后期一键重新生成
  • 总结： 这样做的好处是当数据库表字段改变时，只想要点击代码生成器重新生成代码即可、现有的所有接口都不需要改动。自动会在接口里面新增或删除改动的字段 极大的提示系统可维护性

示例代码 图片

xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.jfzh.rht.modules.user.mapper.customer.UserCustomerMapper">

    <select id="selectUserList" parameterType="com.jfzh.rht.modules.user.po.param.UserListParamPO" resultType="com.jfzh.rht.modules.user.po.customer.UserListCustomerPO">
        SELECT
          ### 查询的字段继承 生成代码的里面的字段 
          ### 如果后期字段有变化，一键重新生成。所有代码都不需要改动 提高系统可维护性
            <include refid="com.jfzh.rht.modules.user.mapper.UserMapper.Base_Column_List"/>,
            <include refid="com.jfzh.rht.modules.user.mapper.UserMapper.Base_Column_Common_List"/>,
        FROM auth_user
            LEFT JOIN auth_user_dept ON(auth_user.user_id = auth_user_dept.user_id AND auth_user_dept.delete_flag = 0)
            LEFT JOIN auth_dept ON ( auth_dept.dept_id = auth_user_dept.dept_id AND auth_dept.delete_flag = 0)
        <where>
            <if test="jobNumber != null and jobNumber != ''">
                AND auth_user.job_number LIKE CONCAT('%',#{jobNumber},'%')
            </if>
        </where>
    </select>
</mapper>

实体类编码规范

重要程度 ★★★★

  • 与mapper和xml一样，自动生成的代码原文件禁止修改
  • 用户的入参实体类在po包下新建param包名 入参类后缀建议 ParamPO结尾
  • 用户的出参实体类在po包下新建customer包名 出参类后缀建议 CustomerPO结尾
图片

接口规范要求

  • 所有需要白名单的接口以 open 开头
  • 所有对外接口必须以 api 开头