RuoYi-Vue代码生成器模板：Velocity与Freemarker

在前后端分离的开发模式中，重复编写基础CRUD代码不仅耗时，还容易引入人为错误。RuoYi-Vue框架提供了强大的代码生成器功能，通过Velocity模板引擎实现代码的自动化生成，显著提升开发效率。本文将深入解析其模板系统的实现原理与使用方法。

模板引擎架构解析

RuoYi-Vue的代码生成模块采用Velocity作为核心模板引擎，通过工厂模式初始化引擎配置，并提供上下文数据绑定功能。核心实现类位于：

• Velocity引擎初始化：ruoyi-generator/src/main/java/com/ruoyi/generator/util/VelocityInitializer.java
• 模板上下文工具：ruoyi-generator/src/main/java/com/ruoyi/generator/util/VelocityUtils.java

引擎初始化流程通过设置字符编码、资源加载路径等参数，确保模板解析的正确性：

Properties p = new Properties();
p.setProperty(Velocity.INPUT_ENCODING, Constants.UTF8);
p.setProperty(Velocity.RESOURCE_LOADER, "class");
p.setProperty("class.resource.loader.class", ClasspathResourceLoader.class.getName());
Velocity.init(p);

模板文件组织结构

模板文件采用模块化设计，按生成目标语言和框架版本分类存储在vm目录下：

ruoyi-generator/src/main/resources/vm/

vm/
├── java/           # Java后端模板
│   ├── controller.java.vm    # 控制器模板
│   ├── service.java.vm       # 服务接口模板
│   └── domain.java.vm        # 实体类模板
├── vue/            # 前端页面模板
│   ├── index.vue.vm          # 列表页模板
│   └── index-tree.vue.vm     # 树形结构页面模板
├── js/             # JavaScript模板
│   └── api.js.vm             # API请求模板
└── xml/            # MyBatis映射模板
    └── mapper.xml.vm         # Mapper文件模板

核心模板类型详解

1. Java后端模板

以控制器模板为例，通过Velocity语法实现动态代码生成：

ruoyi-generator/src/main/resources/vm/java/controller.java.vm

@RestController
@RequestMapping("/${moduleName}/${businessName}")
public class ${className}Controller extends BaseController
{
    @Autowired
    private I${className}Service ${className?uncap_first}Service;

    // 分页查询方法
    @PreAuthorize("@ss.hasPermi('${moduleName}:${businessName}:list')")
    @GetMapping("/list")
    public TableDataInfo list(${className} ${className?uncap_first})
    {
        startPage();
        List<${className}> list = ${className?uncap_first}Service.select${className}List(${className?uncap_first});
        return getDataTable(list);
    }
}

2. Vue前端模板

列表页模板通过条件判断支持普通表格与树形表格的动态生成：

ruoyi-generator/src/main/resources/vm/vue/index.vue.vm

<template>
  <div class="app-container">
    <el-table v-loading="loading" :data="tableData" <#if hasTree>row-key="id" :tree-props="{children: 'children', hasChildren: 'hasChildren'}"</#if>>
      <el-table-column type="selection" width="55" align="center" />
      <#list columns as column>
      <el-table-column 
        prop="${column.javaField}" 
        label="${column.columnComment}" 
        <#if column.queryType??>v-if="showSearch"</#if>
      />
      </#list>
    </el-table>
  </div>
</template>

3. API请求模板

统一生成符合框架规范的前端API调用代码：

ruoyi-generator/src/main/resources/vm/js/api.js.vm

import request from '@/utils/request'

// 查询列表
export function list${className}(query) {
  return request({
    url: '/${moduleName}/${businessName}/list',
    method: 'get',
    params: query
  })
}

// 新增数据
export function add${className}(data) {
  return request({
    url: '/${moduleName}/${businessName}',
    method: 'post',
    data: data
  })
}

模板使用流程

代码生成器的工作流程主要包含以下步骤：

1. 数据表配置：在系统管理→代码生成→生成配置中设置表信息
2. 模板选择：通过前端界面选择需要生成的代码类型
3. 参数绑定：GenTableServiceImpl.java将表结构数据转换为Velocity上下文
4. 模板渲染：调用Velocity引擎解析模板生成代码文件
5. 打包下载：将生成的文件压缩为ZIP包提供下载

自定义模板扩展

如需扩展模板功能，可按以下步骤进行：

1. 新增模板文件：在对应模块目录下创建自定义.vm文件
2. 配置模板路径：修改generator.yml添加新模板的引用
3. 调整上下文数据：扩展VelocityUtils类添加自定义变量
4. 重新编译部署：执行mvn clean package打包更新生成器模块

与Freemarker的对比分析

虽然RuoYi-Vue当前版本未集成Freemarker，但可从以下维度对比两种模板引擎：

特性	Velocity	Freemarker
语法复杂度	简单直观	相对复杂
性能	较高	中等
社区支持	成熟稳定	活跃
功能丰富度	基础功能完善	高级特性多
学习曲线	平缓	较陡

若需集成Freemarker，可参考Velocity的实现方式，添加对应的引擎初始化器和模板处理器。

最佳实践与优化建议

1. 模板复用：将通用代码片段抽取为宏定义，如：

#macro(defineMethod $name $params)
public void ${name}(${params}) {
    // 方法体
}
#end

2. 版本控制：对自定义模板进行Git版本管理，避免升级框架时丢失修改

3. 性能优化：通过VelocityInitializer.java配置缓存策略，减少模板解析开销

4. 安全检查：生成代码前通过GenTableServiceImpl.java的校验逻辑过滤危险字符

通过合理利用RuoYi-Vue的代码生成器，开发团队可将重复编码工作减少70%以上，专注于业务逻辑实现。官方文档提供了更多高级配置说明：若依环境使用手册.docx