Java 字符串模板撤回后已有预览代码怎么迁移

如果项目已经使用 JDK 21 或 JDK 22 的字符串模板预览功能，现在最稳妥的处理不是继续寻找某个隐藏开关，而是把模板表达式按用途迁回稳定 API。OpenJDK 的 JEP 465 页面已经标记为 Closed / Withdrawn；JDK 21 的 JEP 430 与 JDK 22 的 JEP 459 只是预览，预览语法并没有因此成为 Java SE 的永久能力。

迁移判断可以压缩成一句话：普通展示文本用拼接或 formatted，国际化消息用 MessageFormat，循环构建用 StringBuilder，SQL、JSON、HTML 等结构化内容回到对应领域 API；自定义处理器则改成显式方法。

官方状态可直接查看 https://openjdk.org/jeps/465，第二次预览说明位于 https://openjdk.org/jeps/459。下面只处理已有预览代码的迁移，不预测未来提案会采用什么语法。

撤回改变了什么，哪些代码真正受影响

受影响的是模板表达式语法，例如 STR."...\{value}..."，以及围绕 StringTemplate、StringTemplate.Processor 编写的代码。JEP 465 曾计划第三次预览，但最终撤回；因此不能把“曾经预览过”理解成“后续 JDK 仍保证接受”。

普通字符串字面量、文本块、String.format、String::formatted、MessageFormat、StringBuilder 并没有随它一起撤回。迁移的核心就是把预览语法承载的意图重新放回这些稳定工具，或者放回 JDBC、JSON 库、HTML 模板引擎等更合适的领域边界。

先在构建配置中定位 --enable-preview、--release 21、--release 22，再搜索 STR.、FMT.、StringTemplate 和 Processor。不要只删预览开关：删掉开关只能暴露编译错误，不能替你选择正确替代方案。

先把模板用法分成五类

同样一段 STR 代码，可能只是拼接一句日志，也可能在保护 SQL 参数。按语法做全局替换会把这些差异抹平。实际盘点时可以给每个调用点标记以下一种用途：

• 简单展示文本：少量值插入一句内部消息，不涉及本地化。
• 固定格式文本：数字宽度、精度、日期或对齐规则明确。
• 国际化消息：文案来自资源包，参数顺序会随语言变化。
• 增量构建：循环、条件分支或大量片段逐步追加。
• 领域结构化输出：SQL、JSON、HTML、XML 或其他需要转义、校验的内容。

这一步最重要的产物不是新代码，而是一张调用点清单：源文件、原处理器、输入值、输出用途、是否需要转义、现有测试。它能防止“看起来一样”的替换改变实际边界。

普通文本优先选择最小稳定写法

只有一两个值、没有格式要求时，字符串拼接最直接。括号用于明确复合表达式的求值范围：

String name = "Joan";
int unread = 3;

// 简单展示文本使用稳定的字符串拼接
String message = "用户 " + name + " 有 " + unread + " 条未读消息";

// 复合表达式先计算，再参与字符串拼接
String total = "合计：" + (unread + 2);

格式、精度或位置较多时，使用 formatted 能让模板保持集中。它从 Java 15 起可用，语义等价于以当前字符串调用 String.format：

String product = "SSD";
double price = 699.0;

// 固定格式文本明确保留两位小数
String line = "商品：%s，价格：%.2f 元".formatted(product, price);

迁移时要重新检查格式符与参数类型。模板表达式把表达式写在原位置，formatted 则把格式串和参数列表分开；参数顺序、数量或类型不一致会产生错误。Oracle 的稳定 API 说明入口是 https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/String.html。

国际化消息不要退化为硬编码文案

如果原模板用于用户可见文案，迁移成 + 往往会丢失本地化能力。保留资源包，把模式交给 MessageFormat 更合适：

ResourceBundle bundle = ResourceBundle.getBundle("messages", locale);
String pattern = bundle.getString("order.ready");

// 资源包中可保存“订单 {0} 将在 {1,date,short} 就绪”
String message = MessageFormat.format(pattern, orderId, readyDate);

MessageFormat 使用 {0}、{1} 这类参数索引，并可为数字和日期选择子格式。资源包让不同语言调整参数顺序，而不需要改 Java 源码。官方类说明可查看 https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/text/MessageFormat.html。

循环和条件片段使用 StringBuilder

模板表达式很容易把复杂分支藏进一行。若字符串由循环或多个条件片段组成，显式构建通常更容易审查：

StringBuilder text = new StringBuilder("已选标签：");

// 循环中逐个追加标签，避免反复创建中间字符串
for (String tag : tags) {
    text.append(' ').append(tag);
}

// 只在确有备注时追加可选片段
if (note != null && !note.isBlank()) {
    text.append("；备注：").append(note);
}

String result = text.toString();

这里的判断标准不是“拼接一定慢”，而是结构是否清楚。少量常量拼接通常可读性更好；只有存在循环、分支或较多片段时，StringBuilder 才明显减少噪声。

结构化文本不能退化成普通拼接

字符串模板最值得保留的设计意图，是处理器可以同时看到静态片段与动态值，并在生成结果前校验或转换。撤回模板语法不代表这些安全要求消失。尤其是 SQL，不能把原处理器机械替换成字符串拼接。

String sql = "SELECT id, name FROM customer WHERE email = ?";

// SQL 结构与用户输入分离，动态值通过参数绑定传入
try (PreparedStatement statement = connection.prepareStatement(sql)) {
    statement.setString(1, email);

    // 查询结果仍由 JDBC 类型负责，不把输入拼进 SQL 文本
    try (ResultSet rows = statement.executeQuery()) {
        while (rows.next()) {
            consume(rows.getLong("id"), rows.getString("name"));
        }
    }
}

JSON 应交给对象映射或生成器 API，HTML 应交给具备默认转义策略的模板引擎，XML 应使用相应构建器。迁移成功的标准不是“输出肉眼相同”，而是动态值仍然经过原来需要的编码、校验和类型处理。

自定义 Processor 改成显式领域方法

自定义 StringTemplate.Processor 往往同时承担三件事：读取静态片段、接收动态值、返回领域对象。稳定替代方案是把这三件事变成普通方法契约，并让参数类型直接表达限制。

record AuditEvent(String action, long userId, Instant occurredAt) {}

final class AuditEvents {
    private AuditEvents() {}

    // 显式参数代替模板片段解析，调用边界可由类型系统检查
    static AuditEvent userAction(String action, long userId, Clock clock) {
        Objects.requireNonNull(action, "action");
        Objects.requireNonNull(clock, "clock");
        return new AuditEvent(action, userId, clock.instant());
    }
}

// 调用方直接传递领域值，不依赖预览模板处理器
AuditEvent event = AuditEvents.userAction("login", userId, clock);

如果原处理器支持任意模板片段，就先统计实际模板形状，再为高频、稳定的形状提供命名方法。只有确实需要用户自定义模板时，才保留显式的“模式字符串 + 参数集合”接口，并在入口处做白名单、转义或解析。

采用路径：先兼容迁移，再删除预览开关

1. 冻结基线：记录现有测试、关键输出样例和构建所用 JDK。
2. 按用途分批：先迁移简单展示文本，再处理格式化和国际化，最后处理自定义处理器与结构化输出。
3. 双重核对：比较输出内容，同时检查 SQL 参数化、HTML 转义、JSON 类型等非文本边界。
4. 清理配置：所有模板语法移除后，再删除编译、测试和运行参数中的 --enable-preview。
5. 固定目标版本：明确 Maven 或 Gradle 的 toolchain、release 与 CI JDK，避免开发机仍偷偷使用旧预览环境。

回归检查至少覆盖空值、特殊字符、区域设置、日期时区、数字精度和多语言资源。自定义处理器还应检查异常类型是否变化，因为调用方可能依赖原来的失败方式。

后续应该观察什么

OpenJDK 撤回 JEP 465，说明原方案没有按当时形态继续推进，并不等于 Java 永远不会再讨论字符串模板。团队可以关注新的正式 JEP、JDK release notes 和 Java Language Specification，但不要为了等待未知设计而保留无法在目标 JDK 编译的预览源代码。

更实用的观察指标有三个：项目是否还需要 --enable-preview；领域输出是否仍由类型化 API 保护；迁移后的格式化与国际化测试是否覆盖原行为。只要这三项已经稳定，当前迁移就不必依赖未来语法。

常见问题

JDK 21 或 JDK 22 还能继续运行旧代码吗？

在对应版本、正确启用预览功能的条件下，原预览代码可能继续编译和运行；但它会把项目锁定在特定预览版本。升级目标 JDK 时，应按本文用途分类迁移，而不是把旧预览字节码当长期方案。

可以把所有 STR 模板统一换成 formatted 吗？

不建议。formatted 适合固定格式文本，却不能自动替代国际化资源、循环构建、自定义处理器，也不能为 SQL 或 HTML 提供领域安全。

字符串拼接是否一定比模板或 formatted 慢？

不能脱离场景下结论。少量普通拼接通常应先看可读性；循环和多分支构建更适合 StringBuilder。如果性能确实关键，应针对真实路径做基准，而不是只凭语法外观判断。

删除 --enable-preview 就算迁移完成了吗？

不算。删除开关只是配置结果。迁移完成还要求预览语法和 API 已清除，输出行为通过回归，结构化内容的参数化、转义与类型边界没有退化。