SQL LIKE 模糊搜索特殊字符转义实战指南

-- 搜索包含"张三"的记录
SELECT * FROM employee WHERE name LIKE '%张三%';
-- 正确匹配：张三、张三丰、大张三

-- 用户输入 "100%" 搜索，期望搜索包含"100%"字面量的记录
-- 实际 SQL：
SELECT * FROM employee WHERE name LIKE '%100%%';
-- 等价于 LIKE '%100%'（最后的 % 被当作通配符），匹配所有包含"100"的记录
-- 用户输入 "___" 搜索
-- 实际 SQL：
SELECT * FROM employee WHERE name LIKE '%___%';
-- _ 是通配符，匹配任意3个字符，等价于搜索长度≥3的所有记录
-- 用户输入 "%%%" 搜索
-- 实际 SQL：
SELECT * FROM employee WHERE name LIKE '%%%%%';
-- 等价于 LIKE '%'，匹配所有记录，搜索条件完全失效

/**
 * 转义LIKE查询中的特殊字符.
 *
 * @param param 用户原始输入
 * @return 转义后的安全字符串
 */
private String escapeLikeParam(String param) {
    if (param == null) {
        return null;
    }
    return param
        .replace("\\", "\\\\")  // 先转义反斜杠本身
        .replace("%", "\\%")    // 再转义 %
        .replace("_", "\\_");   // 再转义 _
}

@Override
public PageInfo<EmployeeDto> listEmployee(QueryParamsDto paramsDto) {
    // 在查询前转义模糊搜索参数
    if (StringUtils.isNotBlank(paramsDto.getName())) {
        paramsDto.setName(escapeLikeParam(paramsDto.getName()));
    }
    if (StringUtils.isNotBlank(paramsDto.getCode())) {
        paramsDto.setCode(escapeLikeParam(paramsDto.getCode()));
    }
    return employeeMapper.listEmployee(paramsDto);
}

<if test="param.name != null and param.name != ''">
    AND e.name LIKE CONCAT('%', #{param.name}, '%')
</if>

<if test="param.name != null and param.name != ''">
    AND e.name LIKE CONCAT('%',
        REPLACE(REPLACE(REPLACE(#{param.name}, '\\', '\\\\'), '%', '\\%'), '_', '\\_'),
        '%')
</if>

<if test="param.name != null and param.name != ''">
    AND e.name LIKE CONCAT('%', #{param.name}, '%') ESCAPE '/'
</if>

private String escapeLikeParam(String param) {
    if (param == null) return null;
    return param
        .replace("/", "//")
        .replace("%", "/%")
        .replace("_", "/_");
}

@Slf4j
@Service
public class EmployeeServiceImpl implements EmployeeService {
    @Resource
    private EmployeeMapper employeeMapper;
    @Override
    public PageInfo<EmployeeDto> listEmployee(EmployeeQueryDto queryDto) {
        // 模糊搜索参数转义
        if (StringUtils.isNotBlank(queryDto.getName())) {
            queryDto.setName(escapeLikeParam(queryDto.getName()));
        }
        if (StringUtils.isNotBlank(queryDto.getPhone())) {
            queryDto.setPhone(escapeLikeParam(queryDto.getPhone()));
        }
        if (StringUtils.isNotBlank(queryDto.getEmail())) {
            queryDto.setEmail(escapeLikeParam(queryDto.getEmail()));
        }
        List<EmployeeDto> list = employeeMapper.listEmployee(queryDto);
        return new PageInfo<>(list);
    }
    /**
     * 转义LIKE查询中的特殊字符.
     */
    private String escapeLikeParam(String param) {
        if (param == null) {
            return null;
        }
        return param
            .replace("\\", "\\\\")
            .replace("%", "\\%")
            .replace("_", "\\_");
    }
}

<select id="listEmployee" resultType="com.example.dto.EmployeeDto">
    SELECT id, name, phone, email, dept_code
    FROM employee
    <where>
        <if test="param.name != null and param.name != ''">
            AND name LIKE CONCAT('%', #{param.name}, '%')
        </if>
        <if test="param.phone != null and param.phone != ''">
            AND phone LIKE CONCAT('%', #{param.phone}, '%')
        </if>
        <if test="param.email != null and param.email != ''">
            AND email LIKE CONCAT('%', #{param.email}, '%')
        </if>
    </where>
    ORDER BY id DESC
</select>

// 正确顺序：先转义反斜杠，再转义 % 和 _
param.replace("\\", "\\\\")  // 第一步
    .replace("%", "\\%")      // 第二步
    .replace("_", "\\_");     // 第三步
// 错误顺序：如果先转义 %，后转义 \
// "100%" → "100\%" → "100\\%" （反斜杠被二次转义，结果错误）

<!-- 安全：#{} 使用预编译，防止 SQL 注入 -->
AND name LIKE CONCAT('%', #{param.name}, '%')
<!-- 危险：${} 直接拼接，存在 SQL 注入风险 -->
AND name LIKE '%${param.name}%'

// 转义前先判空，空字符串不需要转义
if (StringUtils.isNotBlank(queryDto.getName())) {
    queryDto.setName(escapeLikeParam(queryDto.getName()));
}

public final class SqlLikeUtil {
    private SqlLikeUtil() {
    }
    /**
     * 转义 SQL LIKE 查询中的特殊字符（%、_、\）.
     *
     * @param param 原始输入
     * @return 转义后的字符串，null 输入返回 null
     */
    public static String escape(String param) {
        if (param == null) {
            return null;
        }
        return param
            .replace("\\", "\\\\")
            .replace("%", "\\%")
            .replace("_", "\\_");
    }
    /**
     * 判断字符串是否包含 LIKE 特殊字符.
     */
    public static boolean containsSpecialChar(String param) {
        if (param == null) {
            return false;
        }
        return param.contains("%") || param.contains("_") || param.contains("\\");
    }
}

if (StringUtils.isNotBlank(queryDto.getName())) {
    queryDto.setName(SqlLikeUtil.escape(queryDto.getName()));
}