Spring Velocity 支持项目教程

1. 项目介绍

Spring Velocity Support 是阿里巴巴贡献的一个开源项目，它基于 Spring Framework 提供了对旧版 Velocity 的支持。由于 Spring 从 5.0 版本起不再内置支持 Velocity 模板引擎，此项目旨在帮助那些仍然依赖于 Velocity 的项目平滑过渡。该项目也作为阿里巴巴 velocity-spring-boot-project 的基础。

2. 项目快速启动

要将 Spring Velocity Support 集成到你的项目中，首先确保你的 pom.xml 文件包含了以下依赖：

<dependencies>
    <!-- 引入 Spring Context Support -->
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-context-support</artifactId>
        <version>你的 Spring Framework 版本</version>
    </dependency>

    <!-- 引入 Spring Velocity Support -->
    <dependency>
        <groupId>com.alibaba.spring</groupId>
        <artifactId>spring-velocity-support</artifactId>
        <version>项目的具体版本（例如：1.0.0）</version>
    </dependency>
</dependencies>

接下来，你需要配置 VelocityEngine 和相应的模板路径。在 Spring 配置文件（如：applicationContext.xml 或使用 @Configuration 注解的类）中添加以下配置：

@Configuration
public class VelocityConfig {

    @Value("${velocityEngine.resource.loader.path:/templates/}")
    private String templatePath;

    @Bean(name = "velocityEngine")
    public VelocityEngine velocityEngine() {
        Properties props = new Properties();
        props.setProperty("resource.loader", "class");
        props.setProperty("class.resource.loader.class", "org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader");
        props.setProperty("input.encoding", "UTF-8");
        props.setProperty("output.encoding", "UTF-8");

        return new VelocityEngine(props);
    }

    @Bean
    public VelocityTemplateViewResolver viewResolver(VelocityEngine engine) {
        VelocityTemplateViewResolver resolver = new VelocityTemplateViewResolver();
        resolver.setEngine(engine);
        resolver.setPrefix(templatePath);
        resolver.setSuffix(".vm");
        resolver.setContentType("text/html;charset=UTF-8");
        resolver.setOrder(1);
        return resolver;
    }
}

现在，你可以创建一个 Velocity 模板（例如：/templates/home.vm），并用 Spring MVC 来处理视图渲染。创建一个控制器方法：

@Controller
public class HomeController {

    @RequestMapping("/home")
    public ModelAndView home() {
        Map<String, Object> model = new HashMap<>();
        model.put("title", "欢迎来到主页");
        return new ModelAndView("home", model);
    }
}

运行项目，访问 /home 将加载并渲染 home.vm 模板。

3. 应用案例和最佳实践

• 多语言支持：在 Velocity 模板中使用条件判断来选择不同语言的文本资源。
• 重用组件：创建可重用的 Velocity 非模态块（macro），并在多个模板中导入并使用。
• 数据预处理：在控制器中预处理模型数据，以减少模板中的业务逻辑。

4. 典型生态项目

• Spring Boot：虽然 Spring Boot 不再默认支持 Velocity，但通过以上配置，可以在 Spring Boot 项目中使用 Spring Velocity Support 实现 Velocity 功能。
• Freemarker 或 Thymeleaf：如果你的项目考虑迁移到其他模板引擎，Spring Boot 官方支持 Freemarker 和 Thymeleaf。

完成上述步骤后，你应该能够在你的 Spring 项目中成功地使用 Velocity 作为模板引擎。更多关于 Spring Velocity Support 的详细信息，请参考项目仓库的 Readme 和示例代码。