易鹏官方文档

Appearance

编码规范 ​

数据库表要求 ​

重要程度 ★★★★★

  • 新建数据库表时，所有的表须添加 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 未知'格式命名，后续自定义注解记录修改记录会用到，如不使用可忽略
mysql
`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），后面是功能名称，多个单词用/分隔
java
@RestController
@RequestMapping("/auth/project")
@Api(tags = "项目相关接口", value = "项目相关接口")
@ApiSupport(order = 6)
public class ProjectController {

控制器规范

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