Java StringSubstitutor遇到变量循环引用怎么处理

配置模板里出现 ${a}，而 a 的值又引用了 b，b 最后回到了 a，这就是 StringSubstitutor 的变量循环引用。它不是“替换次数不够”，而是递归替换图里出现了闭环。处理时要先判断闭环发生在变量值还是变量名，再决定关闭递归、拆开配置，或者在边界捕获异常。

官方地址：https://commons.apache.org/proper/commons-text/apidocs/org/apache/commons/text/StringSubstitutor.html

最稳妥的做法是：默认不打开变量名递归；如果业务只需要一次展开，就调用 setDisableSubstitutionInValues(true)；如果必须递归，就把变量配置当成有向图，在进入替换前限制来源和层级，并捕获循环异常记录变量链。

先把“循环引用”还原成一张小图

排查时先不要盯着异常堆栈里的长模板。把每个变量当成一个节点，把变量值中的引用当成一条边。比如下面的配置只有 3 个变量，节点数是 3，最大遍历深度为 3，但闭环长度是 2：

a -> b
b -> a
message -> a

message 只是入口，真正的循环是 a -> b -> a。这三个数——变量节点数、入口深度、闭环长度——比单纯记录“替换失败”更适合做基线。它们也是后面复查配置修改是否有效的固定指标。

StringSubstitutor 为什么会抛出循环异常

StringSubstitutor 用 ${变量名} 表示占位符。变量值里再次出现占位符时，替换会继续向下解析；官方文档明确说明，循环替换会被检测并抛出异常。这个行为的价值在于阻止无限展开，但它不会替你决定配置应该怎样改。

变量值递归和变量名递归是两件事。变量值递归类似 ${a} 展开为 ${b}；变量名递归则类似 ${prefix-${env}}，先计算变量名，再查找最终变量。后者必须显式启用，排查时不能把两个开关混为一谈。

import java.util.Map;
import org.apache.commons.text.StringSubstitutor;

public class CycleExample {
    public static void main(String[] args) {
        Map values = Map.of(
                "a", "${b}",
                "b", "${a}",
                "message", "任务：${a}"
        );

        // 默认允许变量值继续展开；a 和 b 形成闭环时会抛出异常。
        StringSubstitutor substitutor = new StringSubstitutor(values);
        try {
            System.out.println(substitutor.replace("${message}"));
        } catch (IllegalArgumentException ex) {
            // 生产代码应把模板标识和配置来源一起记录，便于定位闭环。
            System.err.println("模板变量存在循环引用：" + ex.getMessage());
        }
    }
}

这里没有必要用重试掩盖异常。重试只会再次进入同一张图，正确动作是回到变量来源，确认是否真的需要递归。

只需要一层展开时，直接关闭变量值递归

很多配置模板只是想把第一层变量替换出来，后续的 ${...} 要交给下一层系统处理。这时关闭变量值递归比人为修改每个字符串更清晰：

Map values = Map.of(
        "name", "${surname}",
        "surname", "Crockford"
);

// 关闭值递归：name 的结果保留 ${surname}，不再继续追到 surname。
StringSubstitutor substitutor = new StringSubstitutor(values)
        .setDisableSubstitutionInValues(true);

String result = substitutor.replace("Hi ${name}");
System.out.println(result); // 结果保留未展开的 ${surname}

这类方案的基线很明确：入口变量仍然替换，递归层数从“可能继续增长”降为 1。代价是输出中可能保留占位符，所以接收方必须把它当成协议的一部分，而不是误认为替换失败。

必须递归时，先拆环再限制变量名递归

如果业务确实需要多层变量组合，就不要把互相引用的配置散落在多个来源。把公共片段改成单向依赖，例如让 a 引用基础变量 base，让 b 引用 a，但不再让 base 或 a 回指 b。

Map values = Map.of(
        "base", "订单",
        "prefix", "${base}",
        "message", "${prefix}处理失败"
);

// 只启用值递归；变量名递归默认保持关闭，减少动态查找边界。
StringSubstitutor substitutor = new StringSubstitutor(values)
        .setEnableUndefinedVariableException(true);

try {
    String result = substitutor.replace("${message}");
    System.out.println(result);
} catch (IllegalArgumentException ex) {
    // 未定义变量与循环变量都在替换边界失败，统一交给配置校验层处理。
    throw new IllegalStateException("模板配置不可解析", ex);
}

只有在变量名本身确实由其他变量组成时，才考虑 setEnableSubstitutionInVariables(true)。打开后，配置图的边数和可能的查找路径都会增加，应把它限制在可信、可控的变量集合中。

用三个指标复查修复有没有偏

不需要先做大规模压测，也能对这类配置问题建立可复现的检查表。固定一组包含正常链、未定义变量和循环链的样例，记录以下指标：

这里的“结果”不是把异常吞掉后返回空字符串，而是让调用方得到可解释的状态：正常模板得到文本；未定义变量得到明确异常；循环模板得到变量来源和模板标识。这样才能把配置问题从偶发故障变成可维护的输入约束。

几个容易误判的边界

• 转义不是拆环。默认转义字符可以让某个占位符不参与替换，适合输出字面量模板；它不会修复变量之间的真实依赖关系。
• 关闭变量值递归会保留占位符。如果下游没有第二次解析能力，就不能把这个开关当成通用修复。
• StringSubstitutor 非线程安全。不要把一个可变配置实例无保护地放到多个线程共享；模板和开关确定后再按调用边界管理实例。
• 别用变量名递归解决所有动态键问题。动态变量名让配置更灵活，也让依赖图更难追踪，应该先评估是否能改成显式键。

总结

Java StringSubstitutor 遇到变量循环引用时，核心不是增加重试次数，而是识别递归图。只需一层展开就用 setDisableSubstitutionInValues(true)；需要多层展开就拆成单向依赖，并保留异常边界；只有变量名确实动态时才显式打开变量名递归。最后用变量节点数、最大展开深度和循环异常率复查，既能定位问题，也能避免把合法的嵌套配置一并禁掉。

相关问题

StringSubstitutor 默认会递归替换变量值吗？

会。变量值中继续出现占位符时，默认会递归解析；如果不希望这样，可以关闭变量值递归。

循环引用一定要改成空值吗？

不建议。循环通常表示配置图不合法，应在模板边界抛出可定位异常，而不是静默改成空字符串。