本文介绍通过自定义 VelocityContext 子类实现运行时检测未被模板使用的上下文变量，确保模板与数据契约一致，避免因冗余变量导致的逻辑隐患。
本文介绍通过自定义 `velocitycontext` 子类实现运行时检测未被模板使用的上下文变量，确保模板与数据契约一致，避免因冗余变量导致的逻辑隐患。
在 Apache Velocity（如 1.7 版本）中，模板引擎默认不会校验上下文（VelocityContext）中是否存在“未被模板引用”的变量——即：即使你向上下文中放入了 cardNumber，而模板 card.vm 中从未使用 ${cardNumber}，Velocity 也会静默忽略该键，不报错、不警告。这种“宽松行为”虽提高容错性，但在强契约场景（如配置驱动渲染、自动化测试、模板合规审计）下易埋下隐患：冗余变量可能掩盖数据建模错误，或导致后期维护者误以为某字段已被消费。
为解决此问题，推荐采用引用计数式上下文增强方案：继承 VelocityContext，重写 put() 和 get() 方法，分别记录“已注入的键”和“实际被模板访问的键”，并在模板渲染完成后调用校验方法，主动发现未被引用的变量。
以下是一个轻量、线程安全（单次渲染场景下）的参考实现：
Apache Superset Dashboard and SQL Exploration Skill
下载
Apache Superset 是一个广泛采用的开源 BI 平台，用于 SQL 探索、图表构建和仪表板交付。当代理需要查询仓库数据、组装仪表板或使用成熟的分析界面解释指标而不是临时笔记本代码时，此技能非常有用。
import org.apache.velocity.context.InternalContextAdapter;
import org.apache.velocity.context.VelocityContext;
import java.util.*;
public static class ReferenceCountingVelocityContext extends VelocityContext {
private final Set<String> keysToCheck = new HashSet<>();
private final Set<String> keysUsed = new HashSet<>();
@Override
public Object put(String key, Object value) {
if (key != null) {
keysToCheck.add(key);
}
return super.put(key, value);
}
@Override
public Object get(String key) {
if (key != null) {
keysUsed.add(key);
}
return super.get(key);
}
/**
* 检查是否存在被 put 但未被 get 的键（即未被模板引用的冗余变量）
* 若存在，抛出异常提示具体键名
*/
public void checkForUnreferencedValues() throws UnusedVelocityContextKeyException {
Set<String> unreferenced = new HashSet<>(keysToCheck);
unreferenced.removeAll(keysUsed);
if (!unreferenced.isEmpty()) {
throw new UnusedVelocityContextKeyException(
"Unused context keys detected: " + unreferenced);
}
}
}
// 自定义异常便于捕获与处理
public static class UnusedVelocityContextKeyException extends RuntimeException {
public UnusedVelocityContextKeyException(String message) {
super(message);
}
}使用方式如下：
ReferenceCountingVelocityContext context = new ReferenceCountingVelocityContext();
context.put("firstName", "tuk");
context.put("lastName", "man");
context.put("cardNumber", "1234"); // ← 此键未在 card.vm 中出现
Template t = ve.getTemplate("card.vm");
StringWriter writer = new StringWriter();
try {
t.merge(context, writer);
context.checkForUnreferencedValues(); // ← 关键校验点：此处将抛出异常
} catch (UnusedVelocityContextKeyException e) {
System.err.println("模板校验失败：" + e.getMessage());
// 输出：模板校验失败：Unused context keys detected: [cardNumber]
}⚠️ 注意事项：
- 该方案适用于单次模板渲染生命周期；若复用同一 ReferenceCountingVelocityContext 渲染多个模板，需在每次渲染前手动清空 keysToCheck/keysUsed，或改用 ThreadLocal 封装；
- Velocity 内部可能通过 InternalContextAdapter 访问上下文，某些高级特性（如 #include 中嵌套上下文）可能绕过 get() 调用，建议结合单元测试覆盖典型模板结构；
- 若项目已升级至 Velocity 2.x，可考虑配合 EventCartridge 的 ReferenceInsertionEventHandler 进行更细粒度的引用追踪，但原理仍基于拦截变量访问。
总结而言，通过轻量级上下文增强，开发者可在不修改模板语法、不引入外部依赖的前提下，将“变量契约一致性”纳入运行时质量门禁，显著提升 Velocity 模板系统的可维护性与可靠性。
