前言

在實務中，當 API 回傳的資料量很大（例如：上千筆使用者、幾萬筆商品），
我們不能一次把所有資料都丟回去，這會造成：

• 效能問題：伺服器與資料庫壓力過大
• 網路延遲：一次傳輸大量資料影響前端體驗
• 使用者體驗差：前端不需要一次顯示所有資料
  因此，API 設計上常用 分頁（Pagination） 與 排序（Sorting） 來解決。

1. 分頁設計（Pagination）

分頁的目標是： 一次只回傳使用者需要的部分資料。

常見的分頁方式

(1) Offset-based 分頁

使用 page 和 limit（或 offset 和 limit）。
GET /users?page=2&limit=10
代表：取第 2 頁，每頁 10 筆。

• 優點：簡單好理解
• 缺點：當資料很多時，OFFSET 會變慢

(2) Cursor-based 分頁

使用「游標（cursor）」記錄位置，例如某個 id。
GET /users?cursor=12&limit=10
代表：從 id = 12 之後取 10 筆資料。

• 優點：效能較好，適合即時資料流
• 缺點：比較難理解，實作也稍微複雜

2. 排序設計（Sorting）

排序的目標是： 讓使用者決定資料的呈現順序 。

常見做法

(1) 指定排序欄位

GET /users?sort=created_at -> 按照 created_at 遞增排序

(2) 支援排序方向

GET /users?sort=-created_at -> - 代表遞減排序
或用明確參數：
GET /users?sort=created_at&order=desc

3. 分頁 + 排序範例

一個實務 API 的範例：
GET /products?page=3&limit=20&sort=price&order=asc
回應範例：
{
"page": 3,
"limit": 20,
"total": 250,
"data": [
{ "id": 41, "name": "Keyboard", "price": 20 },
{ "id": 42, "name": "Mouse", "price": 22 }
]
}

4. 最佳實踐建議

• 預設值 ：建議設定 limit 預設值（例如 10 或 20），避免一次回傳全部。
• 最大值限制 ：避免用戶惡意要求過大 limit（例如 limit=10000）。
• 統一格式 ：所有分頁 API 建議維持一致的參數名稱（如 page、limit）。
• 回應中提供分頁資訊 ：回傳 total、next_page、prev_page，方便前端使用。

小結

• 分頁 用來控制資料量，常見方式有 Offset-based（簡單）、Cursor-based（效能佳）。
• 排序 提供彈性，常見參數設計是 sort 和 order。
• 最佳實踐 ：限制最大值、統一參數格式、在回應中附上分頁資訊。