Database on Bill.Lin's Notes

JPA Enum 型別處理完整指南：映射策略與最佳實踐

Thu, 05 Jan 2023 23:18:48 +0800

概述

在企業級應用程式開發中，Enum（列舉）是表示有限狀態集合的理想選擇，如訂單狀態、使用者角色、審核狀態等。本文深入探討如何在 JPA/Hibernate 中有效處理 Enum 型別，包含各種映射策略、效能考量和實際應用場景。

基本 Enum 映射

1. @Enumerated 註解

JPA 提供 @Enumerated 註解來處理 Enum 映射，支援兩種策略：

EnumType.ORDINAL（數字映射）

// 定義狀態列舉
public enum OrderStatus {
    PENDING,    // 0
    CONFIRMED,  // 1
    SHIPPED,    // 2
    DELIVERED,  // 3
    CANCELLED   // 4
}

// 實體類使用
@Entity
@Table(name = "orders")
public class Order {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Enumerated(EnumType.ORDINAL)
    @Column(name = "status", nullable = false)
    private OrderStatus status = OrderStatus.PENDING;
    
    // 其他屬性...
}

資料庫儲存：

Docker MySQL：容器化部署與設定

Tue, 18 Jan 2022 23:56:44 +0800

概述

在現代開發流程中，使用 Docker 部署資料庫已成為主流。將 MySQL 運行在 Docker 容器中，可以帶來許多好處：環境隔離、快速部署、版本控制、以及方便的遷移。這篇文章將引導您如何在 Docker 中設定和管理 MySQL 容器。

啟動 MySQL 容器

鏡像選擇：mysql/mysql-server 是 Oracle 的私有版本（不同於 Docker Hub 官方鏡像），現已標記為 deprecated。請使用官方 mysql 鏡像（docker.io/library/mysql）。

使用 docker run 指令可以快速啟動一個 MySQL 容器。以下是一個常用的範例，包含了密碼設定、埠映射和字元集設定。

docker run \
    --name mysql-server \
    -e MYSQL_ROOT_PASSWORD=your_strong_password \
    -p 3306:3306 \
    -d \
    mysql:8.0 \
    --character-set-server=utf8mb4 \
    --collation-server=utf8mb4_unicode_ci \
    --skip-character-set-client-handshake

指令參數說明

--name mysql-server: 為容器指定一個易於識別的名稱，這裡命名為 mysql-server。
-e MYSQL_ROOT_PASSWORD=your_strong_password: 設定 MySQL root 使用者的密碼。請務必將 your_strong_password 替換為您自己的強密碼。
-p 3306:3306: 將主機的 3306 埠映射到容器的 3306 埠。這樣您就可以從主機透過 3306 埠連接到容器內的 MySQL 服務。
-d: 以背景模式 (detached mode) 運行容器，讓容器在背景執行。
mysql:8.0: 指定要使用的 Docker 映像檔。使用 Docker Hub 官方 mysql 鏡像。
--character-set-server=utf8mb4: 設定 MySQL 伺服器的預設字元集為 utf8mb4，以支援更廣泛的字元，包括表情符號。
--collation-server=utf8mb4_unicode_ci: 設定伺服器的預設排序規則為 utf8mb4_unicode_ci，這是一種不區分大小寫和重音的排序規則。
--skip-character-set-client-handshake: 禁用客戶端字元集握手。這有助於確保客戶端和伺服器之間的字元集一致性，避免亂碼問題。

字元集設定的等效配置

上述字元集相關的 docker run 參數，在 MySQL 的配置檔 (my.cnf) 中，等效於以下設定：

QueryDSL 完整實戰指南：類型安全的動態查詢解決方案

Sun, 08 Aug 2021 13:07:45 +0800

維護狀態說明：QueryDSL 4.x 自 2018 年後長期缺乏維護；5.0.0（2022 年）雖遷移至 Jakarta namespace，但開發活躍度仍低。評估新專案時請考量以下替代方案：

方案	適用場景	維護狀態
QueryDSL 5.x	現有專案延續、需要複雜型別安全查詢	低度維護
Spring Data JPA Specification	簡單動態查詢，無需額外依賴	積極維護
jOOQ	複雜 SQL、需要完整 SQL 功能	積極維護
Blaze-Persistence	JPA 進階查詢、Entity View	積極維護

概述

QueryDSL 是一個強大的 Java 查詢框架，提供類型安全的 SQL 查詢建構功能。它通過代碼生成技術創建查詢類型，在編譯時期就能發現查詢錯誤，大幅提升開發效率和代碼質量。本文將深入介紹 QueryDSL 的各種用法和最佳實踐。

核心優勢

類型安全：編譯時檢查，避免執行期錯誤
IDE 支援：完整的自動完成和重構功能
統一 API：支援 JPA、SQL、MongoDB 等多種數據源
動態查詢：靈活的條件組合和查詢建構
效能優化：生成高效的 SQL 查詢

支援的技術棧

JPA/Hibernate：最常用的 ORM 整合
Spring Data JPA：與 Spring 生態完美整合
SQL 數據庫：MySQL、PostgreSQL、Oracle 等
NoSQL 數據庫：MongoDB、Lucene 等

環境配置與設定

1. Maven 依賴配置

<properties>
    <querydsl.version>5.0.0</querydsl.version>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
</properties>

<dependencies>
    <!-- Spring Boot Starter Data JPA -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    
    <!-- QueryDSL JPA -->
    <dependency>
        <groupId>com.querydsl</groupId>
        <artifactId>querydsl-jpa</artifactId>
        <version>${querydsl.version}</version>
        <classifier>jakarta</classifier>
    </dependency>
    
    <!-- QueryDSL APT (Annotation Processing Tool) -->
    <dependency>
        <groupId>com.querydsl</groupId>
        <artifactId>querydsl-apt</artifactId>
        <version>${querydsl.version}</version>
        <classifier>jakarta</classifier>
        <scope>provided</scope>
    </dependency>
    
    <!-- Database Driver -->
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <scope>runtime</scope>
    </dependency>
    
    <!-- Validation -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
</dependencies>

<build>
    <plugins>
        <!-- Maven Compiler Plugin -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.11.0</version>
            <configuration>
                <source>17</source>
                <target>17</target>
                <annotationProcessorPaths>
                    <path>
                        <groupId>com.querydsl</groupId>
                        <artifactId>querydsl-apt</artifactId>
                        <version>${querydsl.version}</version>
                        <classifier>jakarta</classifier>
                    </path>
                    <path>
                        <groupId>jakarta.persistence</groupId>
                        <artifactId>jakarta.persistence-api</artifactId>
                        <version>3.1.0</version>
                    </path>
                    <path>
                        <groupId>jakarta.annotation</groupId>
                        <artifactId>jakarta.annotation-api</artifactId>
                        <version>2.1.1</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
        
        <!-- Generate Sources Plugin -->
        <plugin>
            <groupId>org.codehaus.mojo</groupId>
            <artifactId>build-helper-maven-plugin</artifactId>
            <version>3.4.0</version>
            <executions>
                <execution>
                    <phase>generate-sources</phase>
                    <goals>
                        <goal>add-source</goal>
                    </goals>
                    <configuration>
                        <sources>
                            <source>target/generated-sources/annotations</source>
                        </sources>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

2. Gradle 配置

plugins {
    id 'org.springframework.boot' version '3.1.0'
    id 'io.spring.dependency-management' version '1.1.0'
    id 'java'
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-validation'
    
    // QueryDSL
    implementation 'com.querydsl:querydsl-jpa:5.0.0:jakarta'
    annotationProcessor 'com.querydsl:querydsl-apt:5.0.0:jakarta'
    annotationProcessor 'jakarta.persistence:jakarta.persistence-api'
    annotationProcessor 'jakarta.annotation:jakarta.annotation-api'
    
    runtimeOnly 'mysql:mysql-connector-java'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

// QueryDSL 配置
def queryDslDir = "$buildDir/generated/querydsl"

querydsl {
    jpa = true
    querydslSourcesDir = queryDslDir
}

sourceSets {
    main.java.srcDir queryDslDir
}

configurations {
    querydsl.extendsFrom compileClasspath
}

compileQuerydsl {
    options.annotationProcessorPath = configurations.querydsl
}

IntelliJ IDEA + Gradle APT 常見問題

QueryDSL 依賴 Annotation Processing（APT）在編譯時產生 Q 類別（如 QUser）。IntelliJ 與 Gradle APT 的整合不完美，常見錯誤及解法：

Spring Data JPA Pageable 分頁查詢：完整實作與效能優化指南

Tue, 07 Jan 2020 13:26:41 +0800

概述

在處理大量資料時，分頁查詢是必不可少的功能。Spring Data JPA 提供了強大的 Pageable 接口，配合 Specification 可以輕鬆實現靈活的分頁查詢功能。本文將深入介紹如何使用這些功能來構建高效的分頁系統。

核心概念

Pageable：分頁參數接口，定義頁面大小、頁碼和排序規則
Page：分頁結果接口，包含資料和分頁資訊
Specification：查詢規格接口，用於動態構建查詢條件
Criteria API：JPA 標準的類型安全查詢 API

架構優勢

類型安全：Criteria API 提供編譯時檢查
動態查詢：根據條件動態構建 SQL
自動計數：自動執行 COUNT 查詢計算總數
靈活排序：支援多欄位排序
效能優化：支援各種優化策略

基礎配置

1. 依賴設定

<!-- Spring Boot Starter Data JPA -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>

<!-- Spring Boot Starter Web -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

<!-- Database Driver (以 MySQL 為例) -->
<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <scope>runtime</scope>
</dependency>

<!-- Spring Boot Starter Validation -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

2. 實體類定義

package com.example.pagination.entity;

import jakarta.persistence.*;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Email;
import org.hibernate.annotations.CreationTimestamp;
import org.hibernate.annotations.UpdateTimestamp;

import java.time.LocalDateTime;

@Entity
@Table(name = "users", indexes = {
    @Index(name = "idx_username", columnList = "username"),
    @Index(name = "idx_email", columnList = "email"),
    @Index(name = "idx_status", columnList = "status"),
    @Index(name = "idx_created_at", columnList = "created_at")
})
public class User {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @NotBlank
    @Column(unique = true, nullable = false, length = 50)
    private String username;
    
    @NotBlank
    @Email
    @Column(unique = true, nullable = false, length = 100)
    private String email;
    
    @Column(name = "first_name", length = 50)
    private String firstName;
    
    @Column(name = "last_name", length = 50)
    private String lastName;
    
    @Enumerated(EnumType.STRING)
    @Column(nullable = false)
    private UserStatus status = UserStatus.ACTIVE;
    
    @Column(name = "age")
    private Integer age;
    
    @Column(name = "city", length = 100)
    private String city;
    
    @CreationTimestamp
    @Column(name = "created_at", nullable = false, updatable = false)
    private LocalDateTime createdAt;
    
    @UpdateTimestamp
    @Column(name = "updated_at", nullable = false)
    private LocalDateTime updatedAt;
    
    // 建構子
    public User() {}
    
    public User(String username, String email, String firstName, String lastName) {
        this.username = username;
        this.email = email;
        this.firstName = firstName;
        this.lastName = lastName;
    }
    
    // Getters and Setters
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    
    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }
    
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
    
    public String getFirstName() { return firstName; }
    public void setFirstName(String firstName) { this.firstName = firstName; }
    
    public String getLastName() { return lastName; }
    public void setLastName(String lastName) { this.lastName = lastName; }
    
    public UserStatus getStatus() { return status; }
    public void setStatus(UserStatus status) { this.status = status; }
    
    public Integer getAge() { return age; }
    public void setAge(Integer age) { this.age = age; }
    
    public String getCity() { return city; }
    public void setCity(String city) { this.city = city; }
    
    public LocalDateTime getCreatedAt() { return createdAt; }
    public LocalDateTime getUpdatedAt() { return updatedAt; }
}

enum UserStatus {
    ACTIVE, INACTIVE, SUSPENDED, DELETED
}

3. Repository 接口

package com.example.pagination.repository;

import com.example.pagination.entity.User;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.data.jpa.domain.Specification;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;
import org.springframework.stereotype.Repository;

import java.time.LocalDateTime;
import java.util.List;

@Repository
public interface UserRepository extends JpaRepository<User, Long>, JpaSpecificationExecutor<User> {
    
    // 基本分頁查詢
    Page<User> findByStatus(UserStatus status, Pageable pageable);
    
    // 複合條件分頁查詢
    Page<User> findByStatusAndAgeGreaterThan(UserStatus status, Integer age, Pageable pageable);
    
    // 模糊查詢分頁
    Page<User> findByUsernameContainingIgnoreCase(String username, Pageable pageable);
    
    // 時間範圍查詢
    Page<User> findByCreatedAtBetween(LocalDateTime start, LocalDateTime end, Pageable pageable);
    
    // 自訂查詢分頁
    @Query("SELECT u FROM User u WHERE u.city = :city AND u.age BETWEEN :minAge AND :maxAge")
    Page<User> findByCityAndAgeBetween(@Param("city") String city, 
                                       @Param("minAge") Integer minAge, 
                                       @Param("maxAge") Integer maxAge, 
                                       Pageable pageable);
    
    // 原生 SQL 分頁查詢
    @Query(value = "SELECT * FROM users u WHERE u.email LIKE %:emailDomain%", 
           countQuery = "SELECT COUNT(*) FROM users u WHERE u.email LIKE %:emailDomain%",
           nativeQuery = true)
    Page<User> findByEmailDomain(@Param("emailDomain") String emailDomain, Pageable pageable);
    
    // 投影查詢（只查詢部分欄位）
    @Query("SELECT new com.example.pagination.dto.UserSummaryDto(u.id, u.username, u.email, u.status) " +
           "FROM User u WHERE u.status = :status")
    Page<UserSummaryDto> findUserSummariesByStatus(@Param("status") UserStatus status, Pageable pageable);
}

Specification 動態查詢

1. 基礎 Specification

package com.example.pagination.specification;

import com.example.pagination.entity.User;
import com.example.pagination.entity.UserStatus;
import org.springframework.data.jpa.domain.Specification;

import jakarta.persistence.criteria.*;
import java.time.LocalDateTime;
import java.util.ArrayList;
import java.util.List;

public class UserSpecification {
    
    /**
     * 根據使用者名稱模糊查詢
     */
    public static Specification<User> usernameContains(String username) {
        return (root, query, criteriaBuilder) -> {
            if (username == null || username.trim().isEmpty()) {
                return criteriaBuilder.conjunction();
            }
            return criteriaBuilder.like(
                criteriaBuilder.lower(root.get("username")), 
                "%" + username.toLowerCase() + "%"
            );
        };
    }
    
    /**
     * 根據郵箱模糊查詢
     */
    public static Specification<User> emailContains(String email) {
        return (root, query, criteriaBuilder) -> {
            if (email == null || email.trim().isEmpty()) {
                return criteriaBuilder.conjunction();
            }
            return criteriaBuilder.like(
                criteriaBuilder.lower(root.get("email")), 
                "%" + email.toLowerCase() + "%"
            );
        };
    }
    
    /**
     * 根據狀態查詢
     */
    public static Specification<User> statusEquals(UserStatus status) {
        return (root, query, criteriaBuilder) -> {
            if (status == null) {
                return criteriaBuilder.conjunction();
            }
            return criteriaBuilder.equal(root.get("status"), status);
        };
    }
    
    /**
     * 根據年齡範圍查詢
     */
    public static Specification<User> ageBetween(Integer minAge, Integer maxAge) {
        return (root, query, criteriaBuilder) -> {
            List<Predicate> predicates = new ArrayList<>();
            
            if (minAge != null) {
                predicates.add(criteriaBuilder.greaterThanOrEqualTo(root.get("age"), minAge));
            }
            if (maxAge != null) {
                predicates.add(criteriaBuilder.lessThanOrEqualTo(root.get("age"), maxAge));
            }
            
            return criteriaBuilder.and(predicates.toArray(new Predicate[0]));
        };
    }
    
    /**
     * 根據城市查詢
     */
    public static Specification<User> cityEquals(String city) {
        return (root, query, criteriaBuilder) -> {
            if (city == null || city.trim().isEmpty()) {
                return criteriaBuilder.conjunction();
            }
            return criteriaBuilder.equal(root.get("city"), city);
        };
    }
    
    /**
     * 根據創建時間範圍查詢
     */
    public static Specification<User> createdAtBetween(LocalDateTime startDate, LocalDateTime endDate) {
        return (root, query, criteriaBuilder) -> {
            List<Predicate> predicates = new ArrayList<>();
            
            if (startDate != null) {
                predicates.add(criteriaBuilder.greaterThanOrEqualTo(root.get("createdAt"), startDate));
            }
            if (endDate != null) {
                predicates.add(criteriaBuilder.lessThanOrEqualTo(root.get("createdAt"), endDate));
            }
            
            return criteriaBuilder.and(predicates.toArray(new Predicate[0]));
        };
    }
    
    /**
     * 複合查詢 - 根據多個條件
     */
    public static Specification<User> withFilters(String username, String email, 
                                                  UserStatus status, Integer minAge, 
                                                  Integer maxAge, String city) {
        return Specification.where(usernameContains(username))
                .and(emailContains(email))
                .and(statusEquals(status))
                .and(ageBetween(minAge, maxAge))
                .and(cityEquals(city));
    }
    
    /**
     * 進階查詢 - 支援 OR 條件
     */
    public static Specification<User> searchByKeyword(String keyword) {
        return (root, query, criteriaBuilder) -> {
            if (keyword == null || keyword.trim().isEmpty()) {
                return criteriaBuilder.conjunction();
            }
            
            String likePattern = "%" + keyword.toLowerCase() + "%";
            
            return criteriaBuilder.or(
                criteriaBuilder.like(criteriaBuilder.lower(root.get("username")), likePattern),
                criteriaBuilder.like(criteriaBuilder.lower(root.get("email")), likePattern),
                criteriaBuilder.like(criteriaBuilder.lower(root.get("firstName")), likePattern),
                criteriaBuilder.like(criteriaBuilder.lower(root.get("lastName")), likePattern),
                criteriaBuilder.like(criteriaBuilder.lower(root.get("city")), likePattern)
            );
        };
    }
}

2. 動態 Specification 建構器

package com.example.pagination.specification;

import org.springframework.data.jpa.domain.Specification;

import jakarta.persistence.criteria.CriteriaBuilder;
import jakarta.persistence.criteria.Predicate;
import jakarta.persistence.criteria.Root;
import java.util.ArrayList;
import java.util.List;

public class DynamicSpecificationBuilder<T> {
    
    private List<Specification<T>> specifications = new ArrayList<>();
    
    public DynamicSpecificationBuilder<T> with(String field, String operation, Object value) {
        if (value != null) {
            specifications.add(createSpecification(field, operation, value));
        }
        return this;
    }
    
    public DynamicSpecificationBuilder<T> with(Specification<T> specification) {
        if (specification != null) {
            specifications.add(specification);
        }
        return this;
    }
    
    public Specification<T> build() {
        if (specifications.isEmpty()) {
            return null;
        }
        
        Specification<T> result = specifications.get(0);
        for (int i = 1; i < specifications.size(); i++) {
            result = Specification.where(result).and(specifications.get(i));
        }
        return result;
    }
    
    private Specification<T> createSpecification(String field, String operation, Object value) {
        return (root, query, criteriaBuilder) -> {
            switch (operation.toLowerCase()) {
                case "eq":
                case "equals":
                    return criteriaBuilder.equal(root.get(field), value);
                    
                case "ne":
                case "not_equals":
                    return criteriaBuilder.notEqual(root.get(field), value);
                    
                case "gt":
                case "greater_than":
                    return criteriaBuilder.greaterThan(root.get(field), (Comparable) value);
                    
                case "gte":
                case "greater_than_or_equal":
                    return criteriaBuilder.greaterThanOrEqualTo(root.get(field), (Comparable) value);
                    
                case "lt":
                case "less_than":
                    return criteriaBuilder.lessThan(root.get(field), (Comparable) value);
                    
                case "lte":
                case "less_than_or_equal":
                    return criteriaBuilder.lessThanOrEqualTo(root.get(field), (Comparable) value);
                    
                case "like":
                case "contains":
                    return criteriaBuilder.like(
                        criteriaBuilder.lower(root.get(field)), 
                        "%" + value.toString().toLowerCase() + "%"
                    );
                    
                case "starts_with":
                    return criteriaBuilder.like(
                        criteriaBuilder.lower(root.get(field)), 
                        value.toString().toLowerCase() + "%"
                    );
                    
                case "ends_with":
                    return criteriaBuilder.like(
                        criteriaBuilder.lower(root.get(field)), 
                        "%" + value.toString().toLowerCase()
                    );
                    
                case "in":
                    if (value instanceof List) {
                        return root.get(field).in((List<?>) value);
                    }
                    return criteriaBuilder.equal(root.get(field), value);
                    
                case "is_null":
                    return criteriaBuilder.isNull(root.get(field));
                    
                case "is_not_null":
                    return criteriaBuilder.isNotNull(root.get(field));
                    
                default:
                    throw new IllegalArgumentException("不支援的操作: " + operation);
            }
        };
    }
}

DTO 和分頁請求處理

1. 分頁請求 DTO

package com.example.pagination.dto;

import com.example.pagination.entity.UserStatus;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.Max;
import org.springframework.data.domain.PageRequest;
import org.springframework.data.domain.Pageable;
import org.springframework.data.domain.Sort;

import java.time.LocalDateTime;

public class UserPageRequest {
    
    @Min(value = 0, message = "頁碼不能小於 0")
    private int page = 0;
    
    @Min(value = 1, message = "每頁大小不能小於 1")
    @Max(value = 100, message = "每頁大小不能超過 100")
    private int size = 20;
    
    private String sortBy = "id";
    private String sortDirection = "DESC";
    
    // 查詢條件
    private String username;
    private String email;
    private UserStatus status;
    private Integer minAge;
    private Integer maxAge;
    private String city;
    private String keyword; // 關鍵字搜索
    private LocalDateTime startDate;
    private LocalDateTime endDate;
    
    // 建構子
    public UserPageRequest() {}
    
    public UserPageRequest(int page, int size) {
        this.page = page;
        this.size = size;
    }
    
    /**
     * 轉換為 Pageable 物件
     */
    public Pageable toPageable() {
        Sort.Direction direction = Sort.Direction.fromString(sortDirection);
        Sort sort = Sort.by(direction, sortBy);
        return PageRequest.of(page, size, sort);
    }
    
    /**
     * 檢查是否有查詢條件
     */
    public boolean hasFilters() {
        return username != null || email != null || status != null ||
               minAge != null || maxAge != null || city != null ||
               keyword != null || startDate != null || endDate != null;
    }
    
    // Getters and Setters
    public int getPage() { return page; }
    public void setPage(int page) { this.page = page; }
    
    public int getSize() { return size; }
    public void setSize(int size) { this.size = size; }
    
    public String getSortBy() { return sortBy; }
    public void setSortBy(String sortBy) { this.sortBy = sortBy; }
    
    public String getSortDirection() { return sortDirection; }
    public void setSortDirection(String sortDirection) { this.sortDirection = sortDirection; }
    
    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }
    
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
    
    public UserStatus getStatus() { return status; }
    public void setStatus(UserStatus status) { this.status = status; }
    
    public Integer getMinAge() { return minAge; }
    public void setMinAge(Integer minAge) { this.minAge = minAge; }
    
    public Integer getMaxAge() { return maxAge; }
    public void setMaxAge(Integer maxAge) { this.maxAge = maxAge; }
    
    public String getCity() { return city; }
    public void setCity(String city) { this.city = city; }
    
    public String getKeyword() { return keyword; }
    public void setKeyword(String keyword) { this.keyword = keyword; }
    
    public LocalDateTime getStartDate() { return startDate; }
    public void setStartDate(LocalDateTime startDate) { this.startDate = startDate; }
    
    public LocalDateTime getEndDate() { return endDate; }
    public void setEndDate(LocalDateTime endDate) { this.endDate = endDate; }
}

2. 分頁回應 DTO

package com.example.pagination.dto;

import org.springframework.data.domain.Page;

import java.util.List;

public class PageResponse<T> {
    
    private List<T> content;
    private int page;
    private int size;
    private long totalElements;
    private int totalPages;
    private boolean first;
    private boolean last;
    private boolean hasNext;
    private boolean hasPrevious;
    private int numberOfElements;
    
    // 建構子
    public PageResponse() {}
    
    public PageResponse(Page<T> page) {
        this.content = page.getContent();
        this.page = page.getNumber();
        this.size = page.getSize();
        this.totalElements = page.getTotalElements();
        this.totalPages = page.getTotalPages();
        this.first = page.isFirst();
        this.last = page.isLast();
        this.hasNext = page.hasNext();
        this.hasPrevious = page.hasPrevious();
        this.numberOfElements = page.getNumberOfElements();
    }
    
    public static <T> PageResponse<T> of(Page<T> page) {
        return new PageResponse<>(page);
    }
    
    // Getters and Setters
    public List<T> getContent() { return content; }
    public void setContent(List<T> content) { this.content = content; }
    
    public int getPage() { return page; }
    public void setPage(int page) { this.page = page; }
    
    public int getSize() { return size; }
    public void setSize(int size) { this.size = size; }
    
    public long getTotalElements() { return totalElements; }
    public void setTotalElements(long totalElements) { this.totalElements = totalElements; }
    
    public int getTotalPages() { return totalPages; }
    public void setTotalPages(int totalPages) { this.totalPages = totalPages; }
    
    public boolean isFirst() { return first; }
    public void setFirst(boolean first) { this.first = first; }
    
    public boolean isLast() { return last; }
    public void setLast(boolean last) { this.last = last; }
    
    public boolean isHasNext() { return hasNext; }
    public void setHasNext(boolean hasNext) { this.hasNext = hasNext; }
    
    public boolean isHasPrevious() { return hasPrevious; }
    public void setHasPrevious(boolean hasPrevious) { this.hasPrevious = hasPrevious; }
    
    public int getNumberOfElements() { return numberOfElements; }
    public void setNumberOfElements(int numberOfElements) { this.numberOfElements = numberOfElements; }
}

3. 使用者摘要 DTO

package com.example.pagination.dto;

import com.example.pagination.entity.UserStatus;

public class UserSummaryDto {
    
    private Long id;
    private String username;
    private String email;
    private UserStatus status;
    
    // 建構子
    public UserSummaryDto() {}
    
    public UserSummaryDto(Long id, String username, String email, UserStatus status) {
        this.id = id;
        this.username = username;
        this.email = email;
        this.status = status;
    }
    
    // Getters and Setters
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    
    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }
    
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
    
    public UserStatus getStatus() { return status; }
    public void setStatus(UserStatus status) { this.status = status; }
}

Service 層實作

1. 使用者服務介面

package com.example.pagination.service;

import com.example.pagination.dto.PageResponse;
import com.example.pagination.dto.UserPageRequest;
import com.example.pagination.dto.UserSummaryDto;
import com.example.pagination.entity.User;
import com.example.pagination.entity.UserStatus;
import org.springframework.data.domain.Page;

public interface UserService {
    
    /**
     * 分頁查詢使用者
     */
    PageResponse<User> findUsers(UserPageRequest request);
    
    /**
     * 關鍵字搜索使用者
     */
    PageResponse<User> searchUsers(String keyword, UserPageRequest request);
    
    /**
     * 根據狀態分頁查詢使用者摘要
     */
    PageResponse<UserSummaryDto> findUserSummariesByStatus(UserStatus status, UserPageRequest request);
    
    /**
     * 高級搜索
     */
    PageResponse<User> advancedSearch(UserPageRequest request);
}

2. 使用者服務實作

package com.example.pagination.service.impl;

import com.example.pagination.dto.PageResponse;
import com.example.pagination.dto.UserPageRequest;
import com.example.pagination.dto.UserSummaryDto;
import com.example.pagination.entity.User;
import com.example.pagination.entity.UserStatus;
import com.example.pagination.repository.UserRepository;
import com.example.pagination.service.UserService;
import com.example.pagination.specification.DynamicSpecificationBuilder;
import com.example.pagination.specification.UserSpecification;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.data.jpa.domain.Specification;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
@Transactional(readOnly = true)
public class UserServiceImpl implements UserService {
    
    @Autowired
    private UserRepository userRepository;
    
    @Override
    public PageResponse<User> findUsers(UserPageRequest request) {
        Pageable pageable = request.toPageable();
        
        if (!request.hasFilters()) {
            // 沒有過濾條件，直接分頁查詢
            Page<User> page = userRepository.findAll(pageable);
            return PageResponse.of(page);
        }
        
        // 有過濾條件，使用 Specification
        Specification<User> spec = UserSpecification.withFilters(
            request.getUsername(),
            request.getEmail(),
            request.getStatus(),
            request.getMinAge(),
            request.getMaxAge(),
            request.getCity()
        );
        
        Page<User> page = userRepository.findAll(spec, pageable);
        return PageResponse.of(page);
    }
    
    @Override
    public PageResponse<User> searchUsers(String keyword, UserPageRequest request) {
        Pageable pageable = request.toPageable();
        Specification<User> spec = UserSpecification.searchByKeyword(keyword);
        
        Page<User> page = userRepository.findAll(spec, pageable);
        return PageResponse.of(page);
    }
    
    @Override
    public PageResponse<UserSummaryDto> findUserSummariesByStatus(UserStatus status, UserPageRequest request) {
        Pageable pageable = request.toPageable();
        Page<UserSummaryDto> page = userRepository.findUserSummariesByStatus(status, pageable);
        return PageResponse.of(page);
    }
    
    @Override
    public PageResponse<User> advancedSearch(UserPageRequest request) {
        Pageable pageable = request.toPageable();
        
        // 使用動態 Specification 建構器
        DynamicSpecificationBuilder<User> builder = new DynamicSpecificationBuilder<>();
        
        builder.with("username", "contains", request.getUsername())
               .with("email", "contains", request.getEmail())
               .with("status", "equals", request.getStatus())
               .with("age", "gte", request.getMinAge())
               .with("age", "lte", request.getMaxAge())
               .with("city", "equals", request.getCity())
               .with("createdAt", "gte", request.getStartDate())
               .with("createdAt", "lte", request.getEndDate());
        
        // 如果有關鍵字，添加關鍵字搜索
        if (request.getKeyword() != null && !request.getKeyword().trim().isEmpty()) {
            builder.with(UserSpecification.searchByKeyword(request.getKeyword()));
        }
        
        Specification<User> spec = builder.build();
        Page<User> page = userRepository.findAll(spec, pageable);
        return PageResponse.of(page);
    }
}

Controller 層實作

1. 使用者控制器

package com.example.pagination.controller;

import com.example.pagination.dto.PageResponse;
import com.example.pagination.dto.UserPageRequest;
import com.example.pagination.dto.UserSummaryDto;
import com.example.pagination.entity.User;
import com.example.pagination.entity.UserStatus;
import com.example.pagination.service.UserService;
import jakarta.validation.Valid;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/users")
@CrossOrigin(origins = "*", maxAge = 3600)
public class UserController {
    
    @Autowired
    private UserService userService;
    
    /**
     * 分頁查詢使用者
     */
    @GetMapping
    public ResponseEntity<PageResponse<User>> getUsers(@Valid UserPageRequest request) {
        PageResponse<User> response = userService.findUsers(request);
        return ResponseEntity.ok(response);
    }
    
    /**
     * 關鍵字搜索使用者
     */
    @GetMapping("/search")
    public ResponseEntity<PageResponse<User>> searchUsers(
            @RequestParam String keyword,
            @Valid UserPageRequest request) {
        
        PageResponse<User> response = userService.searchUsers(keyword, request);
        return ResponseEntity.ok(response);
    }
    
    /**
     * 高級搜索
     */
    @PostMapping("/advanced-search")
    public ResponseEntity<PageResponse<User>> advancedSearch(@Valid @RequestBody UserPageRequest request) {
        PageResponse<User> response = userService.advancedSearch(request);
        return ResponseEntity.ok(response);
    }
    
    /**
     * 根據狀態查詢使用者摘要
     */
    @GetMapping("/summaries")
    public ResponseEntity<PageResponse<UserSummaryDto>> getUserSummaries(
            @RequestParam UserStatus status,
            @Valid UserPageRequest request) {
        
        PageResponse<UserSummaryDto> response = userService.findUserSummariesByStatus(status, request);
        return ResponseEntity.ok(response);
    }
    
    /**
     * 使用路徑參數的分頁查詢
     */
    @GetMapping("/page/{page}/size/{size}")
    public ResponseEntity<PageResponse<User>> getUsersWithPathParams(
            @PathVariable int page,
            @PathVariable int size,
            @RequestParam(required = false) String sortBy,
            @RequestParam(required = false) String sortDirection) {
        
        UserPageRequest request = new UserPageRequest(page, size);
        if (sortBy != null) request.setSortBy(sortBy);
        if (sortDirection != null) request.setSortDirection(sortDirection);
        
        PageResponse<User> response = userService.findUsers(request);
        return ResponseEntity.ok(response);
    }
}

2. 分頁配置控制器

package com.example.pagination.controller;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.domain.PageRequest;
import org.springframework.data.domain.Pageable;
import org.springframework.data.domain.Sort;
import org.springframework.data.web.PageableDefault;
import org.springframework.data.web.SortDefault;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.HashMap;
import java.util.Map;

@RestController
@RequestMapping("/api/config")
public class PageConfigController {
    
    /**
     * 使用 Spring 自動解析的 Pageable 參數
     */
    @GetMapping("/users")
    public ResponseEntity<Map<String, Object>> getUsersWithSpringPageable(
            @PageableDefault(page = 0, size = 20) 
            @SortDefault(sort = "id", direction = Sort.Direction.DESC) 
            Pageable pageable) {
        
        Map<String, Object> result = new HashMap<>();
        result.put("page", pageable.getPageNumber());
        result.put("size", pageable.getPageSize());
        result.put("sort", pageable.getSort().toString());
        
        return ResponseEntity.ok(result);
    }
    
    /**
     * 動態排序欄位驗證
     */
    @GetMapping("/users/validated")
    public ResponseEntity<Pageable> getValidatedPageable(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") int size,
            @RequestParam(defaultValue = "id") String sortBy,
            @RequestParam(defaultValue = "DESC") String sortDirection) {
        
        // 驗證排序欄位
        String[] allowedSortFields = {"id", "username", "email", "createdAt", "updatedAt"};
        boolean isValidSortField = false;
        for (String field : allowedSortFields) {
            if (field.equals(sortBy)) {
                isValidSortField = true;
                break;
            }
        }
        
        if (!isValidSortField) {
            sortBy = "id"; // 預設排序欄位
        }
        
        Sort.Direction direction = Sort.Direction.fromString(sortDirection);
        Sort sort = Sort.by(direction, sortBy);
        Pageable pageable = PageRequest.of(page, size, sort);
        
        return ResponseEntity.ok(pageable);
    }
}

OFFSET 分頁效能問題與替代方案

Page<T> 預設使用 LIMIT ? OFFSET ? 實作，OFFSET 越大效能越差（MySQL 需掃描並丟棄前 N 筆資料）。