背景

作为一名后端开发攻城狮，您是否碰到过无法正确模糊查询到含有反斜杠\、百分号%、下划线_等关键字的内容? 比如想模糊查询一下文件信息表中，文件名称包含了下划线的文件信息都有哪些，却返回了表中所有的文件信息或包含了明显不匹配的文件信息。在实际的项目开发中，这种情况很普遍，开发的时候如果没有处理好，到了测试阶段，往往会被测试的同学提BUG单。

在SpringBoot应用中，遇到这种问题，大部分攻城狮们第一时间想到的可能就是写个工具类，然后在接口的代码中，对用户输入的关键字进行特殊符号的转义后，再提交到数据库去查询，这也不失为一种方法。但这种方式需要修改接口的代码，包括测试用例代码，稍显麻烦，那么，有没有更优雅、更省事的实现模糊查询含有特殊符号的内容的方式呢? 答案当然是有的，就是MyBatis提供的扩展接口：TypeHandler类型处理器。

1、创建特殊符号转义类型转换器类

实现TypeHandler接口，在setParameter方法（如果是继承BaseTypeHandler，则是在setNonNullParameter方法）中对特殊符号进行转义处理。

/*
 * Copyright (c) Bruce.CH 2022-2025. All rights reserved.
 */

import org.apache.ibatis.type.BaseTypeHandler;
import org.apache.ibatis.type.JdbcType;
import org.apache.ibatis.type.MappedJdbcTypes;
import org.apache.ibatis.type.MappedTypes;

import java.sql.CallableStatement;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;

/**
 * 模糊查询字段特殊符号转义处理器
 *
 * @author Bruce.CH
 * @since 2025年02月27日
 */
@MappedJdbcTypes(JdbcType.VARCHAR)
@MappedTypes(String.class)
public class EscapeTypeHandler extends BaseTypeHandler<String> {
    @Override
    public void setNonNullParameter(PreparedStatement ps, int i, String parameter, JdbcType jdbcType) throws SQLException {
        // 对查询关键字中的特殊符号进行转义
        String escapedParameter = parameter
                .replace("\\", "\\\\") // 转义反斜杠
                .replace("%", "\\%") // 转义百分号
                .replace("_", "\\_"); // 转义下划线
        ps.setString(i, escapedParameter);
    }

    @Override
    public String getNullableResult(ResultSet rs, String columnName) throws SQLException {
        // 查询结果不需要处理，原样返回即可
        return rs.getString(columnName);
    }

    @Override
    public String getNullableResult(ResultSet rs, int columnIndex) throws SQLException {
        // 查询结果不需要处理，原样返回即可
        return rs.getString(columnIndex);
    }

    @Override
    public String getNullableResult(CallableStatement cs, int columnIndex) throws SQLException {
        // 查询结果不需要处理，原样返回即可
        return cs.getString(columnIndex);
    }
}

在上述代码中：

• @MappedJdbcTypes(JdbcType.VARCHAR) 和 @MappedTypes(String.class) 注解表示该类型处理器应用于 VARCHAR 类型的 JDBC 参数和 Java 的 String 类型。
• setNonNullParameter 方法中对传入的字符串参数中的 \、% 和 _ 进行转义，即在这些字符前加上 \。

2、在 Mapper XML 中使用

在 Mapper XML 文件的 查询SQL 语句中，使用特殊符号转义类型转换器类。

    <select id="query" resultType="com.example.demo.vo.FileInfoVo">
        SELECT id,file_name,file_type,file_size FROM tb_file
        WHERE file_name LIKE concat('%', #{fileName, typeHandler=com.example.demo.typehandler.EscapeTypeHandler}, '%')
        LIMIT 10
    </select>

在上述 SQL 语句中，fileName参数使用了自定义的 EscapeTypeHandler类型处理器，这样在设置参数时，特殊符号如反斜杠、百分号、下划线等会被自动转义，这样就非常简单、优雅、正确的实现根据文件名称模糊查询符合条件的文件信息。

3、测试

输入下划线：查询文件名称带有下划线的文件信息

输入下百分号：查询文件名称带有百分号的文件信息

均能正确返回符合条件的文件信息。

4、总结

通过以上步骤，就可以在 Spring Boot 应用中使用 MyBatis 的类型转换器对查询关键字中的特殊符号进行转义处理。