Java StringSubstitutor怎样为缺失变量提供默认值

Java 模板里遇到没有提供的变量时，StringSubstitutor 可以直接用 ${变量名:-默认值} 语法给出回退文本。例如模板写成 地区：${region:-未设置}，而 Map 中没有 region，替换结果就是“地区：未设置”。这比在业务代码中到处写空值判断更集中。

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

关键点是：默认值只在变量没有解析到可用值时参与替换；默认分隔符是 :-，如果项目使用另一套模板语法，可以显式配置分隔符。

• 缺失变量：使用占位符中的默认文本。
• 已提供变量：优先使用 Map 或解析器中的值。
• 严格配置：需要把未解析变量当成异常时，再打开严格选项。

StringSubstitutor 的默认值语法是什么

Apache Commons Text 的变量默认写法接近 Shell 参数展开：变量名后接 :-，再写回退文本。例如 ${user:-访客} 表示优先读取 user，找不到时使用“访客”。Map 中存在变量时，变量值会覆盖占位符中的默认文本。

org.apache.commonscommons-text

下面的示例只演示替换关系。代码中的注释说明了 Map、占位符和默认值各自承担的职责：

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

public class DefaultValueExample {
    public static void main(String[] args) {
        Map values = new HashMap();
        // 只提供已知变量，故意不放入 region，观察默认文本如何生效
        values.put("user", "小林");

        String template = "用户：${user}，地区：${region:-未设置}";
        // StringSubstitutor 优先取 Map 值，缺失变量才读取 :- 后的默认文本
        String result = new StringSubstitutor(values).replace(template);
        System.out.println(result);
    }
}

按这个模板，结果示意为“用户：小林，地区：未设置”。如果随后加入 values.put("region", "华东")，同一个占位符会得到“华东”，无需修改模板。

用 :- 给缺失变量提供默认值

最小规则可以记成“变量名 + 默认值分隔符 + 回退文本”。默认分隔符是 :-，因此这些占位符分别表示不同意图：

不要把默认值当成数据校验。比如端口号、超时时间等配置仍应在替换之后做格式和范围检查；StringSubstitutor 负责文本插值，不负责确认“30s”是否符合你的业务规则。

空字符串、自定义分隔符和严格模式怎么选

实际排查时最容易混淆的是“变量存在但为空”和“变量根本不存在”。一个空字符串通常仍是 Map 中的值，是否回退取决于解析器和使用方式；如果业务上空字符串也应回退，建议在放入 Map 前先完成归一化，而不是把模板默认值当作通用空值处理器。

如果模板系统不喜欢 :-，可以显式设置其他值分隔符。这样做的重点是让模板约定和配置保持一致：

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

public class CustomDelimiterExample {
    public static String render(Map values) {
        // 把默认值分隔符改为 |，模板就使用 ${name|访客}
        StringSubstitutor substitutor = new StringSubstitutor(values);
        substitutor.setValueDelimiter('|');
        // 返回替换后的文本；变量仍由传入的 Map 提供
        return substitutor.replace("欢迎 ${name|访客}");
    }
}

如果漏填变量应该立刻暴露，而不是悄悄保留占位符，则可以开启未定义变量异常：

StringSubstitutor substitutor = new StringSubstitutor(values);
// 严格模式用于配置缺项必须失败的场景
substitutor.setEnableUndefinedVariableException(true);
String result = substitutor.replace("${requiredValue}");

严格模式和默认值是两种不同策略：前者让缺项成为错误，后者让缺项有可读回退。不要在同一类模板中无规则混用，否则调用方很难判断“未替换”是合法状态还是配置事故。

项目里怎样选择更稳妥的写法

面向用户的提示语、邮件标题和日志附加信息，优先使用明确的默认值，例如 ${region:-未知地区}。面向数据库连接、服务地址、鉴权参数等关键配置，通常更适合严格模式或在进入替换前完成配置校验，避免默认文本掩盖部署问题。

还要注意 StringSubstitutor 实例不是线程安全对象。若模板替换发生在并发请求中，不要把一个会被持续修改配置的实例当作全局可变单例；可以按请求创建实例，或确保共享实例只读且生命周期清晰。

最后，把模板约定写进配置文档：默认分隔符是什么、缺失变量是否允许、空字符串是否算缺失、哪些字段必须严格失败。规则明确后，:- 才会成为可维护的兜底机制，而不是隐藏错误的开关。

常见问题

Map 中没有变量时一定会自动使用默认值吗？

只有占位符写出了默认值分隔符和回退文本，例如 ${name:-访客}，才有明确的默认值语义。只写 ${name} 时，不应把未解析状态理解成业务默认值。

可以把默认分隔符改成单个字符吗？

可以通过 setValueDelimiter 配置分隔符，示例中使用了 |。模板和代码必须同时采用新约定，已有模板不会自动改写。

StringSubstitutor 能替代配置校验吗？

不能。它解决的是字符串插值；关键配置仍应在替换后检查类型、范围、格式和必填约束，必要时开启严格未定义变量异常。