SpringBoot中编写超长@Query原生SQL的优雅方案

当需要在JPA仓库方法中使用超长原生SQL时，直接把SQL写在@Query注解里会导致代码可读性差、维护困难，以下是几种实用的优雅实现方式：

1. 借助Spring SpEL表达式读取外部SQL文件 #

通过Spring的SpEL表达式调用自定义组件读取SQL文件内容，将其注入到@Query注解中。

步骤： #

• 编写一个SQL读取工具类，作为Spring组件：

@Component("sqlReader")
public class SqlReader {
    private final ResourceLoader resourceLoader;

    public SqlReader(ResourceLoader resourceLoader) {
        this.resourceLoader = resourceLoader;
    }

    public String readSql(String resourcePath) throws IOException {
        Resource resource = resourceLoader.getResource(resourcePath);
        return FileCopyUtils.copyToString(new InputStreamReader(resource.getInputStream(), StandardCharsets.UTF_8));
    }
}

• 在Repository方法的@Query中使用SpEL调用该工具类：

@Repository
public interface UserRepository extends JpaRepository<User, Long> {
    @Query(value = "#{@sqlReader.readSql('classpath:sql/complex_user_query.sql')}", nativeQuery = true)
    List<UserDto> findComplexUserInfo();
}

• 在resources/sql目录下创建complex_user_query.sql文件，写入完整的原生SQL：

SELECT u.id, u.username, r.role_name, d.department_name
FROM user u
JOIN user_role ur ON u.id = ur.user_id
JOIN role r ON ur.role_id = r.id
JOIN department d ON u.department_id = d.id
WHERE u.status = 1
ORDER BY u.create_time DESC

2. 自定义Repository实现类 #

如果SQL逻辑特别复杂，或者需要动态拼接SQL，直接自定义Repository的实现类，手动读取SQL文件并执行查询。

步骤： #

• 定义基础Repository接口：

public interface CustomUserRepository {
    List<UserDto> findComplexUserInfo();
}

• 编写实现类，使用JdbcTemplate或EntityManager执行读取的SQL：

@Repository
public class CustomUserRepositoryImpl implements CustomUserRepository {
    private final JdbcTemplate jdbcTemplate;
    private final SqlReader sqlReader;

    public CustomUserRepositoryImpl(JdbcTemplate jdbcTemplate, SqlReader sqlReader) {
        this.jdbcTemplate = jdbcTemplate;
        this.sqlReader = sqlReader;
    }

    @Override
    public List<UserDto> findComplexUserInfo() {
        try {
            String sql = sqlReader.readSql("classpath:sql/complex_user_query.sql");
            return jdbcTemplate.query(sql, (rs, rowNum) -> {
                UserDto dto = new UserDto();
                dto.setId(rs.getLong("id"));
                dto.setUsername(rs.getString("username"));
                dto.setRoleName(rs.getString("role_name"));
                dto.setDepartmentName(rs.getString("department_name"));
                return dto;
            });
        } catch (IOException e) {
            throw new RuntimeException("读取SQL文件失败", e);
        }
    }
}

• 让JPA继承这个自定义接口：

public interface UserRepository extends JpaRepository<User, Long>, CustomUserRepository {
}

3. 使用Hibernate命名原生查询（NamedNativeQuery） #

将SQL定义在外部XML文件中，通过Hibernate的命名查询机制引用，避免在代码中硬写SQL。

步骤： #

• 在resources/META-INF目录下创建orm.xml文件，定义命名原生查询：

<?xml version="1.0" encoding="UTF-8"?>
<entity-mappings xmlns="http://xmlns.jcp.org/xml/ns/persistence/orm"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence/orm http://xmlns.jcp.org/xml/ns/persistence/orm_2_2.xsd"
                 version="2.2">
    <named-native-query name="User.findComplexUserInfo" result-class="com.example.dto.UserDto">
        <query><![CDATA[
            SELECT u.id, u.username, r.role_name, d.department_name
            FROM user u
            JOIN user_role ur ON u.id = ur.user_id
            JOIN role r ON ur.role_id = r.id
            JOIN department d ON u.department_id = d.id
            WHERE u.status = 1
            ORDER BY u.create_time DESC
        ]]></query>
    </named-native-query>
</entity-mappings>

• 在Repository接口中使用@NamedNativeQuery的名称：

@Repository
public interface UserRepository extends JpaRepository<User, Long> {
    @Query(name = "User.findComplexUserInfo", nativeQuery = true)
    List<UserDto> findComplexUserInfo();
}

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