编码规范

数据库表要求

重要程度 ★★★★★

• 新建数据库表时，所有的表须添加 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删除',

控制器编码规范

控制器类名规范

• 添加 @Tag 注解，用于在接口文档中显示
• 添加 @ApiSupport order，表示该接口在文档中的显示位置
• @RequestMapping("/auth/project") 接口名称命名：首字母建议用微服务名（auth），后面是功能名称，多个单词用/分隔

@RestController
@RequestMapping("/auth/project")
@Tag(name = "项目相关接口")
@ApiSupport(author = "lipeng", order = 28)
public class ProjectController {

控制器规范

• @PreAuthorize 权限控制注解 hasPermission：第一个参数表示完整的域名，第二个表示方法权限（需要配置在鉴权系统中），在注解介绍里面会有详细介绍
• @Operation 接口文档描述，必须添加。同时也是日志记录接口名称取值的地方，description 是给使用文档的人看调用这个接口需要哪个权限，方便前端人员配置权限
• @KPVerifyNote 开启注解校验，会在注解介绍章节详细描述
• 所有的接口返回内容都需要返回 KPResult 对象，建议最好不要返回自定义的方法

@PreAuthorize("hasPermission('/auth/project/page/list', 'auth:project:page:list')")
@Operation(summary = "查询项目分页列表", description = "权限 auth:project:page:list")
@PostMapping("/page/list")
@KPVerifyNote
public KPResult<ProjectPO> queryPageList(@RequestBody ProjectListParamPO projectListParamPO) {
    return projectService.queryPageList(projectListParamPO);
}

service层编码规范

重要程度 ★★★★

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

• 查询方法没有事务，但建议以query开头，保持整个项目风格一致，如 queryPageList
• 新增方法须以 add或save 开头，如 saveUser
• 修改方法须以 update 开头，如 updateUser
• 删除方法须以 remove或delete 开头，如 removeUser
• 批量操作且需要事务的以 batch 开头，如 batchRemove
• 其他功能且需要事务的以 do 开头，如 doCancel
• 最高隔离级别事务以 secure 开头，如 secureSave

/**
 * 根据用户Id查询详情。
 * @author lipeng
 * 2025-04-21
 * @param parameter 查询参数
 * @return com.kp.framework.modules.user.po.customer.UserDetailsCustomerPO
 */
@Cacheable(value = "userCache", keyGenerator = "pageKeyGenerator", unless = "T(com.kp.framework.utils.kptool.KPStringUtil).isEmpty(#result)")
public ProjectPO queryDetailsById(JSONObject parameter) {
}

/**
 * 新增用户信息。
 * @author lipeng
 * 2025-04-21
 * @param userEditParamPO 新增参数
 */
@CacheEvict(value = "userCache", allEntries = true)
public void saveUser(UserEditParamPO userEditParamPO) {
}

/**
 * 修改用户信息。
 * @author lipeng
 * 2025-04-21
 * @param userEditParamPO 修改参数
 */
@CacheEvict(value = "userCache", allEntries = true)
public void updateUser(UserEditParamPO userEditParamPO) {
}

/**
 * 批量删除用户信息。
 * @author lipeng
 * 2025-04-21
 * @param ids 删除id集合
 * @return java.lang.String
 */
@CacheEvict(value = "userCache", allEntries = true)
public String batchRemove(List<String> ids) {
}

/**
 * 管理员密码重置。
 * @author lipeng
 * 2025/5/8
 * @param parameter 密码参数
 */
@CacheEvict(value = "userCache", allEntries = true)
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 开头