一、技术选型背景与核心价值

在申报类系统开发中，动态生成格式规范的文档是核心需求。传统方案多采用字符串拼接或JSP模板，存在维护成本高、可读性差等问题。Velocity模板引擎凭借其简洁的语法、高效的渲染性能及与Java生态的无缝集成，成为此类场景的理想选择。

核心优势：

语法简洁：采用${variable}和#if/#foreach等指令，降低学习成本
性能卓越：编译后的模板缓存机制提升渲染效率
生态兼容：完美适配SpringBoot的依赖注入体系
维护便捷：模板文件与业务逻辑分离，便于非技术人员修改

二、环境准备与基础配置

1. 依赖管理

在pom.xml中添加核心依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-velocity</artifactId>
    <version>2.7.0</version> <!-- 使用最新稳定版本 -->
</dependency>
<!-- 若使用独立Velocity引擎（非SpringBoot集成） -->
<dependency>
    <groupId>org.apache.velocity</groupId>
    <artifactId>velocity-engine-core</artifactId>
    <version>2.3</version>
</dependency>

2. 配置文件优化

在application.properties中配置模板路径与编码：

# 模板文件存放目录
spring.velocity.resource-loader-path=classpath:/templates/
# 模板编码格式
spring.velocity.charset=UTF-8
# 是否启用热加载（开发环境推荐开启）
spring.velocity.cache=false
# 自定义工具类配置（可选）
spring.velocity.toolbox-config-location=classpath:/velocity-toolbox.xml

三、核心功能实现

1. 模板文件设计

创建student_application.vm模板文件，示例结构：

<!DOCTYPE html>
<html>
<head>
    <title>省三好学生申报表</title>
    <style>
        .header { font-size: 20px; text-align: center; }
        .table-border { border-collapse: collapse; width: 100%; }
        .table-border td, th { border: 1px solid #000; padding: 8px; }
    </style>
</head>
<body>
    <div class="header">省三好学生申报表</div>
    <table class="table-border">
        <tr>
            <th>姓名</th>
            <td>${student.name}</td>
            <th>学号</th>
            <td>${student.id}</td>
        </tr>
        #foreach($award in ${student.awards})
        <tr>
            <td colspan="4">
                ${award.year}年获得${award.name}（${award.level}）
            </td>
        </tr>
        #end
    </table>
</body>
</html>

2. 数据模型构建

创建Java实体类：

@Data
public class Student {
    private String name;
    private String id;
    private List<Award> awards;
}
@Data
public class Award {
    private String year;
    private String name;
    private String level;
}

3. 控制器实现

@Controller
@RequestMapping("/application")
public class ApplicationController {
    @Autowired
    private VelocityEngine velocityEngine; // 手动注入方式
    // 或使用SpringBoot自动配置的VelocityTemplateEngine
    @Autowired
    private VelocityTemplateEngine templateEngine;
    @GetMapping("/generate")
    public void generateReport(HttpServletResponse response) throws IOException {
        // 1. 准备数据
        Student student = buildSampleData();
        // 2. 配置响应头
        response.setContentType("application/pdf");
        response.setHeader("Content-Disposition", "attachment;filename=application.pdf");
        // 3. 渲染模板（方式一：直接使用VelocityEngine）
        VelocityContext context = new VelocityContext();
        context.put("student", student);
        StringWriter writer = new StringWriter();
        velocityEngine.mergeTemplate("student_application.vm", "UTF-8", context, writer);
        // 4. 转换为PDF（实际项目中可集成iText等库）
        // 此处简化为输出HTML内容
        response.getWriter().write(writer.toString());
    }
    // 使用SpringBoot集成方式（推荐）
    @GetMapping("/generate2")
    public void generateReport2(Model model, HttpServletResponse response) throws IOException {
        model.addAttribute("student", buildSampleData());
        // 渲染结果可通过Thymeleaf等视图解析器处理
        // 或直接获取模板内容（需自定义ViewResolver）
    }
    private Student buildSampleData() {
        Student student = new Student();
        student.setName("张三");
        student.setId("20200001");
        List<Award> awards = new ArrayList<>();
        awards.add(new Award("2022", "数学竞赛", "省级"));
        awards.add(new Award("2021", "优秀学生干部", "校级"));
        student.setAwards(awards);
        return student;
    }
}

四、高级功能扩展

1. 工具类集成

创建velocity-toolbox.xml配置文件：

<toolbox>
    <tool>
        <key>dateTool</key>
        <scope>application</scope>
        <class>org.apache.velocity.tools.generic.DateTool</class>
    </tool>
    <tool>
        <key>mathTool</key>
        <scope>request</scope>
        <class>org.apache.velocity.tools.generic.MathTool</class>
    </tool>
</toolbox>

在模板中调用：

当前日期：${dateTool.format('yyyy-MM-dd', $date)}
计算结果：${mathTool.add(1,2)}

2. 国际化支持

配置多语言属性文件：

messages_zh_CN.properties
```
title=省三好学生申报表
```

messages_en_US.properties

title=Provincial Top Student Application

在模板中使用：

<title>${messages.get('title')}</title>

3. 异常处理机制

创建自定义VelocityViewResolver处理渲染异常：

public class CustomVelocityViewResolver extends VelocityViewResolver {
    @Override
    protected View createView(String viewName, Locale locale) throws Exception {
        try {
            return super.createView(viewName, locale);
        } catch (Exception e) {
            // 记录错误日志
            log.error("Velocity模板渲染失败: {}", viewName, e);
            // 返回错误视图或抛出自定义异常
            throw new TemplateRenderingException("模板渲染异常", e);
        }
    }
}

五、性能优化建议

模板缓存：生产环境务必开启spring.velocity.cache=true
异步渲染：对于复杂模板，考虑使用CompletableFuture进行异步处理
资源预加载：在应用启动时预加载常用模板

连接池配置：若使用独立Velocity引擎，配置适当的资源池参数

# 资源池配置示例
resource.manager.defaultcache.size=128
resource.loader=file, classpath
file.resource.loader.cache=true

六、部署注意事项

模板文件打包：确保resources/templates/目录下的文件被正确打包到最终产物
环境差异处理：通过spring.profiles.active区分开发/生产环境的配置
监控告警：集成日志服务监控模板渲染错误率

通过以上技术方案，开发者可快速构建出稳定、高效的申报系统模板模块。实际项目中，建议结合PDF生成库（如iText）、工作流引擎等组件，构建完整的数字化申报解决方案。对于高并发场景，可考虑将模板渲染服务拆分为独立微服务，通过消息队列实现异步处理。

SpringBoot集成Velocity模板引擎实现申报系统开发