Ruoyi框架MyBatis-Plus代码生成格式优化实践

1. 项目背景与痛点分析

Ruoyi作为国内流行的快速开发框架，其前后端分离版本在企业级应用开发中广受欢迎。但在实际使用过程中，许多开发者（包括我自己）都遇到过代码生成脚本输出的格式问题——特别是使用MyBatis-Plus作为ORM层时。

核心痛点集中在以下几个方面：

• 默认生成的Mapper XML文件中SQL语句缩进混乱，团队协作时Git提交经常出现大量格式变更
• Entity类字段注释与数据库表字段的映射关系不够直观
• ServiceImpl模板中方法体的代码块大括号换行风格与团队规范冲突
• 动态SQL条件拼接的格式在复杂查询时难以维护

我在三个不同企业的Ruoyi项目落地过程中，发现这些格式问题平均会占用15%-20%的代码评审时间。更严重的是，当多人协作时，不同开发者本地IDE的格式化规则差异会导致相同的模板生成出风格迥异的代码。

2. MyBatis-Plus代码生成原理剖析

2.1 Ruoyi代码生成器的工作机制

Ruoyi的代码生成器本质是一个Velocity模板引擎的封装实现。当我们执行GenTable相关操作时，系统会：

1. 读取gen_table和gen_table_column表中的元数据
2. 根据配置的模板路径加载.vm模板文件
3. 将数据库表结构信息注入模板上下文
4. 通过Velocity引擎渲染生成Java/XML文件

关键文件位置：

code复制src/main/resources/templates/vm
├── java
│   ├── entity.java.vm
│   ├── mapper.java.vm
│   ├── service.java.vm
│   └── serviceImpl.java.vm
└── xml
    └── mapper.xml.vm

2.2 MyBatis-Plus的模板特殊性

与原生MyBatis不同，MyBatis-Plus在代码生成时需要特别注意：

1. BaseMapper继承：生成的Mapper接口需要继承BaseMapper<T>
2. @TableField注解：实体类字段需要正确处理下划线转驼峰
3. 逻辑删除标记：需要识别is_deleted等特殊字段
4. 分页插件兼容：XML中不应当出现原生limit语句

3. 关键模板优化实战

3.1 Mapper XML格式化改造

原始模板问题：动态SQL标签内的换行和缩进随机，导致diff难以阅读

优化方案（修改mapper.xml.vm）：

xml复制#if(${baseColumnList})
    <sql id="baseColumnList">
        ${baseColumnList}
    </sql>
#end

#if(${baseResultMap})
    <resultMap id="baseResultMap" type="${packageName}.entity.${ClassName}">
#foreach($column in $columns)
#if(${column.isPk()})
        <id column="${column.columnName}" property="${column.javaField}"/>
#else
        <result column="${column.columnName}" property="${column.javaField}"/>
#end
#end
    </resultMap>
#end

<select id="select${ClassName}List" parameterType="${packageName}.entity.${ClassName}" resultMap="baseResultMap">
    SELECT 
    <include refid="baseColumnList"/>
    FROM ${tableName}
    <where>
#foreach($column in $columns)
#set($queryType=$column.queryType)
#set($javaField=$column.javaField)
#set($javaType=$column.javaType)
#set($columnName=$column.columnName)
#if($column.query)
#if($column.queryType == "EQ")
        <if test="${javaField} != null #if($javaType == 'String' ) and ${javaField}.trim() != ''#end">
            AND ${columnName} = #{${javaField}}
        </if>
#elseif(...)
        <!-- 其他查询条件类型 -->
#end
#end
#end
    </where>
</select>

关键改进点：

1. 统一使用4空格缩进（非Tab）
2. SQL关键字右对齐
3. 动态条件标签内保持一致的缩进层级
4. 注释符号与内容间保留空格

3.2 Entity类字段注释优化

原始问题：字段注释直接使用列名，缺乏业务含义说明

优化方案（entity.java.vm）：

java复制/**
 * ${tableComment}
 */
@TableName("${tableName}")
public class ${ClassName} extends BaseEntity {
    private static final long serialVersionUID = 1L;

#foreach ($column in $columns)
#if(!$table.isSuperColumn($column.javaField))
    /**
     * ${column.columnComment} 
     * 数据库字段: ${column.columnName} 
     * 字段类型: ${column.columnType}
     */
    @TableField(value = "${column.columnName}"#if($column.fill != ""), fill = FieldFill.${column.fill}#end)
    private ${column.javaType} ${column.javaField};
    
#end
#end

改进效果示例：

java复制/**
 * 用户信息表
 */
@TableName("sys_user")
public class SysUser extends BaseEntity {
    /**
     * 用户昵称 
     * 数据库字段: nick_name 
     * 字段类型: varchar(30)
     */
    @TableField("nick_name")
    private String nickName;
}

3.3 ServiceImpl方法体规范

常见问题：自动生成的CRUD方法大括号换行风格不一致

解决方案（serviceImpl.java.vm）：

java复制@Override
public ${ClassName} select${ClassName}ById(${pkColumn.javaType} ${pkColumn.javaField}) {
    return baseMapper.selectById(${pkColumn.javaField});
}

@Override
public int insert${ClassName}(${ClassName} ${className}) {
    return baseMapper.insert(${className});
}

@Override
public int update${ClassName}(${ClassName} ${className}) {
    return baseMapper.updateById(${className});
} 

@Override
public int delete${ClassName}ByIds(${pkColumn.javaType}[] ${pkColumn.javaField}s) {
    return baseMapper.deleteBatchIds(Arrays.asList(${pkColumn.javaField}s));
}

强制规范：

1. 方法左大括号不换行
2. 单行方法体保持紧凑
3. 参数列表超过120字符时换行对齐

4. 高级定制技巧

4.1 动态模板切换方案

针对不同业务模块可能需要不同的代码风格，可以通过：

1. 在application.yml添加配置：

yaml复制gen: 
  template-mode: 
    default: classic
    modules:
      finance: strict
      report: loose

2. 修改GenServiceImpl：

java复制String getTemplatePath(String module) {
    String mode = config.getTemplateMode().getOrDefault(module, 
               config.getTemplateMode().get("default"));
    return "templates/vm/" + mode + "/java/";
}

4.2 IDE格式化兼容方案

确保团队统一：

1. 在项目根目录添加.editorconfig：

code复制[*.{java,xml}]
indent_style = space
indent_size = 4
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

2. 提交预定义的Eclipse/IntelliJ代码风格文件

4.3 自定义类型处理器

对于特殊字段类型（如JSON字段），可以扩展模板：

xml复制<!-- 在mapper.xml.vm中添加 -->
#if($column.javaType == "JsonObject")
    <result column="${column.columnName}" property="${column.javaField}" 
            typeHandler="com.alibaba.fastjson2.TypeReferenceHandler"/>
#end

5. 实测效果对比

优化前后指标对比：

典型场景示例 - 用户管理模块生成：

diff复制- <if test="nickName != null and nickName.trim() != ''">AND nick_name like concat('%', #{nickName}, '%')</if>
+ <if test="nickName != null and nickName.trim() != ''">
+     AND nick_name LIKE CONCAT('%', #{nickName}, '%')
+ </if>

6. 持续维护建议

1. 版本控制：将修改后的.vm文件纳入版本管理，建议存放在：

   code复制/src/main/resources/templates/vm/custom/
   

2. 变更检测：在CI流程中添加模板校验：

   bash复制# 校验模板文件格式
   find src/main/resources/templates/vm -name "*.vm" | xargs grep -l "TAB" && exit 1
   

3. 文档沉淀：建立团队内部的《代码生成规范》文档，包含：

   • 字段注释编写规范
   • XML缩进规则
   • 异常处理模板示例

经过三个项目的实际验证，这套优化方案能使生成的代码更符合现代Java开发规范，减少不必要的格式争议，让团队更专注于业务逻辑实现。特别是在大型项目多人协作场景下，格式一致性带来的维护成本降低效果尤为明显。