Spring属性配置中如何正确解析含大括号的邮箱地址

API 探路者

2026-8-28

问题根因

该问题由两层校验逻辑的冲突导致：

框架内置的自定义URI转换器（com.im.commons.lang.converter.URIConverter）严格遵循RFC 3986规范做URI格式校验，{、}属于URI保留字符，直接拼接在mailto:协议头后会被判定为非法URI，触发字符串转URI的类型转换异常
手动将大括号替换为%7B、%7D做百分号编码后，URI语法校验可以通过，但框架内置的邮件路由组件没有对编码后的收件人地址做URL解码，直接将携带%7B/%7D的转义字符串传给SMTP服务，SMTP校验邮箱地址规则时判定%属于用户名非法字符，触发501投递错误

解决方案

按改造成本从低到高、稳定性从高到低排序，可选择以下方案：

方案1：提前替换占位符，从根源规避特殊字符
首先确认业务合理性：标准RFC 5321定义的SMTP邮箱地址规则中，@符号前的用户名部分本身就不推荐使用大括号这类特殊字符，绝大多数公网SMTP服务会直接拒收包含这类字符的地址。如果{xyz}是未替换的变量占位符，直接在传入路由参数前完成变量替换，把大括号占位符替换为实际的用户名，生成标准格式的邮箱地址再传入路由配置，是成本最低、无任何兼容问题的最优方案。
方案2：修复框架编解码逻辑（业务必须保留大括号邮箱时使用）
如果业务场景确实需要使用带大括号的邮箱地址，不要手动替换字符，修改两处框架逻辑：
1. 修改URIConverter的转换逻辑：在做字符串转URI时，识别mailto:协议头，仅对邮箱地址部分的非法URI字符做URL编码，注意保留@这类邮箱和mailto协议的合法字符不做编码，保证生成的URI符合语法规范
2. 修改邮件路由的投递逻辑：从mailto URI中提取收件人地址后，先做URL解码得到原始邮箱字符串，再传给SMTP客户端，禁止将带百分号转义的编码字符串直接透传给SMTP
  核心逻辑参考代码：
```
// 1. URI转换阶段逻辑
String dest = "mailto:{xyz}@abc.com";
if (dest.startsWith("mailto:")) {
    String emailPart = dest.substring(7);
    String encodedEmail = URLEncoder.encode(emailPart, StandardCharsets.UTF_8)
            .replace("+", "%20") // 适配URI空格编码规则
            .replace("%40", "@"); // @为mailto协议合法字符，不需要编码
    URI validMailtoUri = URI.create("mailto:" + encodedEmail);
}

// 2. SMTP投递阶段逻辑
URI mailtoUri = (URI) routeDestination;
String realRecipient = URLDecoder.decode(mailtoUri.getSchemeSpecificPart(), StandardCharsets.UTF_8);
// 将realRecipient作为收件人地址传入SMTP发送逻辑
```
方案3：临时关闭URI严格校验（应急场景使用）
如果短时间内无法修改框架编解码逻辑，可以调整URIConverter的配置，关闭RFC严格校验模式，允许大括号这类保留字符直接出现在URI中，跳过类型转换阶段的报错。该方案属于临时兼容方案，后续框架升级可能出现兼容问题，且如果使用的SMTP服务本身不支持带大括号的邮箱地址，依然会触发投递失败，不推荐长期使用。

避坑提示：所有针对mailto地址做的URI编码，仅用于满足URI语法校验要求，绝对不能把编码后的带%的字符串直接传给SMTP客户端，投递前必须解码为原始邮箱地址，否则必然触发SMTP地址校验错误。

内容的提问来源于stack exchange，提问作者siddhant