编辑“︁Spring命名查询”︁（章节）

= Spring命名查询 =

== 简介 ==
'''Spring命名查询'''（Named Queries）是Spring Data JPA提供的一种将JPQL（Java Persistence Query Language）或原生SQL查询语句预定义在实体类或ORM配置文件中的技术。通过为查询分配唯一的名称，开发者可以在代码中通过名称调用这些查询，避免将SQL/JPQL语句硬编码在业务逻辑中，从而提高代码的可维护性和复用性。

命名查询的主要优势包括：
* '''集中管理'''：所有查询语句集中在实体类或XML配置中，便于统一维护
* '''类型安全'''：编译时检查查询名称，减少运行时错误
* '''性能优化'''：应用启动时预编译查询，提升运行时效率

== 实现方式 ==
Spring命名查询可以通过以下两种主要方式实现：

=== 1. 使用JPA注解 ===
在实体类上使用<code>@NamedQuery</code>或<code>@NamedNativeQuery</code>注解：

<syntaxhighlight lang="java">
@Entity
@NamedQuery(
    name = "User.findByEmail",
    query = "SELECT u FROM User u WHERE u.email = :email"
)
@NamedNativeQuery(
    name = "User.countActiveUsers",
    query = "SELECT COUNT(*) FROM users WHERE active = 1",
    resultClass = Long.class
)
public class User {
    @Id
    private Long id;
    private String email;
    // 其他字段和方法...
}
</syntaxhighlight>

=== 2. 使用XML配置 ===
在<code>META-INF/orm.xml</code>文件中定义：

<syntaxhighlight lang="xml">
<entity-mappings>
    <entity class="com.example.User">
        <named-query name="User.findByEmail">
            <query>SELECT u FROM User u WHERE u.email = :email</query>
        </named-query>
        <named-native-query name="User.countActiveUsers" result-class="java.lang.Long">
            <query>SELECT COUNT(*) FROM users WHERE active = 1</query>
        </named-native-query>
    </entity>
</entity-mappings>
</syntaxhighlight>

== 使用方法 ==
定义命名查询后，可以通过Spring Data JPA的Repository接口调用：

<syntaxhighlight lang="java">
public interface UserRepository extends JpaRepository<User, Long> {
    // 自动映射到同名命名查询
    User findByEmail(@Param("email") String email);
    
    // 使用@Query注解显式引用命名查询
    @Query(name = "User.countActiveUsers")
    Long countActiveUsers();
}
</syntaxhighlight>

== 参数绑定 ==
命名查询支持两种参数绑定方式：

=== 位置参数 ===
<syntaxhighlight lang="java">
@NamedQuery(
    name = "User.findByStatus",
    query = "SELECT u FROM User u WHERE u.status = ?1"
)
</syntaxhighlight>

=== 命名参数 ===
<syntaxhighlight lang="java">
@NamedQuery(
    name = "User.findByStatusAndType",
    query = "SELECT u FROM User u WHERE u.status = :status AND u.type = :type"
)
</syntaxhighlight>

== 实际案例 ==
考虑一个电商系统中的订单查询场景：

<syntaxhighlight lang="java">
@Entity
@NamedQuery(
    name = "Order.findRecentOrders",
    query = "SELECT o FROM Order o WHERE o.customerId = :customerId AND o.createdDate > :date ORDER BY o.createdDate DESC"
)
public class Order {
    // 实体字段...
}

// 在Repository中使用
public interface OrderRepository extends JpaRepository<Order, Long> {
    List<Order> findRecentOrders(@Param("customerId") Long customerId, @Param("date") LocalDateTime date);
}

// 业务逻辑中调用
List<Order> recentOrders = orderRepository.findRecentOrders(customerId, LocalDateTime.now().minusDays(7));
</syntaxhighlight>

== 性能考虑 ==
命名查询在应用启动时会被预编译，这带来以下性能优势：
* 减少每次执行查询时的解析开销
* 提前发现语法错误
* 查询计划缓存优化

可以通过以下JPA属性控制预编译行为：
<pre>
spring.jpa.properties.hibernate.query.inline_parameter_handling=true
</pre>

== 最佳实践 ==
1. '''命名规范'''：使用"EntityName.queryPurpose"的命名约定（如<code>User.findByEmail</code>）
2. '''复杂查询'''：对于多表关联的复杂查询，优先使用命名查询
3. '''动态查询'''：简单条件查询使用方法名派生查询，复杂动态查询使用Criteria API
4. '''测试验证'''：为每个命名查询编写集成测试

== 与派生查询的比较 ==
<mermaid>
graph LR
    A[查询方式] --> B[命名查询]
    A --> C[派生查询]
    B --> D[预定义JPQL/SQL]
    B --> E[复杂查询]
    C --> F[根据方法名生成]
    C --> G[简单查询]
</mermaid>

== 常见问题 ==
=== 查询未找到错误 ===
确保：
* 查询名称拼写正确
* 实体类上有<code>@Entity</code>注解
* 包扫描配置正确

=== 参数绑定错误 ===
检查：
* 参数名称是否与查询中的命名参数匹配
* 参数类型是否兼容
* 是否缺少<code>@Param</code>注解

== 数学表示 ==
对于分页查询，命名查询可以与分页参数结合使用。给定页码<math>p</math>和每页大小<math>s</math>，偏移量计算为：

<math>
offset = (p - 1) \times s
</math>

== 总结 ==
Spring命名查询是管理复杂持久化查询的强大工具，特别适合：
* 需要重复使用的查询
* 复杂的JPQL/SQL语句
* 需要预编译优化的场景

通过合理使用命名查询，可以显著提高数据访问层的可维护性和性能。

[[Category:后端框架]]
[[Category:Spring]]
[[Category:Spring数据]]