列名与模型属性不一致导致Spring原生查询与Hibernate混用报错

我之前踩过一模一样的坑！核心问题就是你实体里的属性名（比如id）和数据库实际列名（user_id）不一致，而Spring Data的分页排序默认是基于实体属性名的，但原生查询直接操作数据库列名，两者对接不上就会触发报错。下面给你几个实用的解决方案：

1. 优先用HQL查询（最简单省心） #

HQL是基于实体属性的查询语言，Hibernate会自动帮你把实体属性转换成对应的数据库列名，完全不用手动处理映射，分页排序直接用实体属性名就行。

比如把你的仓库查询改成HQL版本：

@Repository
public interface UserRepository extends JpaRepository<User, Integer> {
    // 这里用实体属性u.email，而非数据库列名
    @Query("SELECT u FROM User u WHERE u.email LIKE %:email%")
    Page<User> findUsersByEmail(@Param("email") String email, Pageable pageable);
}

调用时直接传Pageable即可，比如按id（实体属性）排序：

PageRequest pageable = PageRequest.of(0, 10, Sort.by("id").ascending());
userRepository.findUsersByEmail("test@example.com", pageable);

Hibernate会自动把ORDER BY id转换成ORDER BY user_id，完美适配数据库列名。

2. 原生查询手动处理属性-列名映射 #

如果必须用原生SQL（比如涉及数据库特定语法），那就要手动把Pageable里的排序属性转换成数据库列名。

步骤1：服务层转换排序规则 #

写一个属性到列名的映射方法，再把传入的Pageable排序转换成数据库能识别的列名：

@Service
public class UserService {
    @Autowired
    private UserRepository userRepository;

    public Page<User> getUsers(String email, Pageable pageable) {
        // 转换排序：将实体属性映射为数据库列名
        Sort convertedSort = pageable.getSort().map(order -> {
            String columnName = mapPropertyToColumn(order.getProperty());
            return new Order(order.getDirection(), columnName);
        });
        // 创建包含转换后排序的新Pageable
        PageRequest adjustedPageable = PageRequest.of(
                pageable.getPageNumber(),
                pageable.getPageSize(),
                convertedSort
        );
        // 调用仓库的原生查询
        return userRepository.findUsersByEmail(email, adjustedPageable);
    }

    // 属性-列名映射逻辑
    private String mapPropertyToColumn(String property) {
        return switch (property) {
            case "id" -> "user_id";
            case "email" -> "email";
            // 其他实体属性对应的数据库列名
            default -> property; // 默认返回原属性名（适用于属性与列名一致的场景）
        };
    }
}

步骤2：仓库层的原生查询 #

注意原生查询必须配套正确的countQuery（分页需要计算总条数）：

@Repository
public interface UserRepository extends JpaRepository<User, Integer> {
    @Query(
            value = "SELECT * FROM User u WHERE u.email LIKE %:email%",
            countQuery = "SELECT COUNT(*) FROM User u WHERE u.email LIKE %:email%",
            nativeQuery = true
    )
    Page<User> findUsersByEmail(@Param("email") String email, Pageable pageable);
}

3. 自定义Sort转换器（优雅全局方案） #

如果有大量原生查询需要处理属性-列名映射，可以写一个全局排序转换器，不用每次在服务层手动处理。

步骤1：实现Sort.Converter接口 #

@Component
public class UserSortConverter implements Sort.Converter {
    // 定义属性到列名的映射表
    private static final Map<String, String> PROPERTY_COLUMN_MAP = Map.of(
            "id", "user_id",
            "email", "email"
            // 其他属性映射
    );

    @Override
    public String convert(String property) {
        // 找不到映射时，默认返回原属性名
        return PROPERTY_COLUMN_MAP.getOrDefault(property, property);
    }
}

步骤2：仓库方法上绑定转换器 #

在原生查询的方法上加上@SortConverter注解，指定我们写的转换器：

@Repository
public interface UserRepository extends JpaRepository<User, Integer> {
    @Query(
            value = "SELECT * FROM User u WHERE u.email LIKE %:email%",
            countQuery = "SELECT COUNT(*) FROM User u WHERE u.email LIKE %:email%",
            nativeQuery = true
    )
    @SortConverter(converter = UserSortConverter.class)
    Page<User> findUsersByEmail(@Param("email") String email, Pageable pageable);
}

这样每次调用该方法时，Spring Data会自动帮你把排序属性转换成数据库列名，非常省心！

额外注意点 #

• 确保实体类的@Column注解配置正确，比如你代码里@Column(name = "user_id")对应id属性，这个是正确的，Hibernate的基础映射必须准确。
• 原生查询的countQuery必须和主查询的过滤条件一致，否则分页的总页数会计算错误。

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