MyBatis 3 中处理包含方括号的列名导致NumberFormatException问题解析

问题背景

在使用MyBatis 3进行数据库操作时，当查询结果列名包含方括号"[]"且结果类型为Map时，可能会遇到NumberFormatException异常。这是一个典型的框架与特殊字符兼容性问题，特别是在处理动态结果集时尤为常见。

问题现象

当执行类似以下SQL查询时：

SELECT (CASE WHEN subject_name='aaa[张三]' THEN subject_name ELSE NULL END) AS subject_name FROM als_core_p

如果使用Map作为结果接收类型，MyBatis会抛出NumberFormatException异常，提示"对于输入字符串'张三'无法转换为数字"。

根本原因分析

这个问题源于MyBatis内部对属性名的解析机制。MyBatis使用PropertyTokenizer类来处理属性路径，该类会将方括号"[]"中的内容解析为数组或集合的索引。具体流程如下：

1. 当列名包含方括号时，PropertyTokenizer会尝试将其分割
2. 方括号内的内容被解析为"index"属性
3. 后续处理中，框架会尝试将这个"index"转换为整数
4. 当方括号内是非数字内容时(如中文)，就会抛出NumberFormatException

核心代码路径：

• DefaultResultSetHandler.applyAutomaticMappings()
• MetaObject.setValue()
• PropertyTokenizer构造函数
• BaseWrapper.setCollectionValue()

解决方案

官方推荐方案

MyBatis核心开发团队确认这是设计行为，并提供了以下解决方案：

1. 修改SQL查询中的列别名：避免在列名中使用方括号

   SELECT (CASE WHEN subject_name='aaa[张三]' THEN subject_name ELSE NULL END) AS subjectNameWithoutBrackets FROM als_core_p
   

2. 使用自定义ObjectWrapper：通过扩展MapWrapper类来改变默认行为

自定义ObjectWrapper实现

如果需要保留原始列名，可以创建自定义包装器：

public class CustomMapWrapper extends MapWrapper {
    public CustomMapWrapper(MetaObject metaObject, Map<String, Object> map) {
        super(metaObject, map);
    }

    @Override
    public void set(PropertyTokenizer prop, Object value) {
        // 自定义处理逻辑，避免将方括号内容解析为索引
        if (prop.getIndex() != null && !prop.getIndex().matches("^\\d+$")) {
            map.put(prop.getName(), value);
            return;
        }
        super.set(prop, value);
    }
}

然后注册自定义包装器工厂：

public class CustomObjectWrapperFactory implements ObjectWrapperFactory {
    @Override
    public boolean hasWrapperFor(Object object) {
        return object instanceof Map;
    }

    @Override
    public ObjectWrapper getWrapperFor(MetaObject metaObject, Object object) {
        return new CustomMapWrapper(metaObject, (Map<String, Object>) object);
    }
}

在MyBatis配置中注册：

<objectWrapperFactory type="com.example.CustomObjectWrapperFactory"/>

版本更新情况

MyBatis 3.5.16版本将包含相关改进，使MapWrapper类的map字段从private改为protected，方便开发者扩展自定义包装器。这一改动不会影响现有应用，但为处理特殊列名提供了更多灵活性。

最佳实践建议

1. 在设计数据库和查询时，尽量避免在列名中使用特殊字符
2. 对于必须使用特殊字符的场景，考虑使用列别名进行转换
3. 对于动态结果集，优先考虑使用自定义ObjectWrapper方案
4. 在升级到MyBatis 3.5.16+后，可以更简单地扩展MapWrapper

总结

MyBatis对列名中方括号的特殊处理机制虽然符合大多数场景，但在处理包含非数字方括号内容时会导致异常。通过理解框架内部机制，开发者可以选择合适的解决方案，无论是修改SQL还是扩展框架功能，都能有效解决这一问题。随着MyBatis版本的更新，处理这类特殊情况的灵活性也在不断提高。