API 查詢 參數是附加到 API 請求 URL 的鍵值對，用於傳送附加資訊至伺服器。它們允許用戶端（例如 Web 瀏覽器或應用程式）在向伺服器發出請求時指定某些條件或傳遞資料。

查詢參數加入到 URL 末端問號 (?) 後。每個參數都是鍵值對，鍵和值之間以等號 (=) 分隔。如果有多個查詢參數，則以「&」分隔。

查詢參數如何使用：
過濾資料：客戶端可以使用查詢參數來過濾他們想要的資料。例如， ?category=books 可能會告訴伺服器僅傳回「書籍」類別中的項目。

分頁：查詢參數通常用於 API 請求中的分頁，允許客戶端指定要取得哪一頁結果以及每頁有多少個項目。範例：?page=2&limit=10.

排序與順序：查詢參數可用來指定資料應如何排序。例如，?sort=price&order=asc 可以指示伺服器傳回按價格升序排序的項目。

傳遞搜尋字詞：API 通常使用查詢參數來允許客戶端搜尋資料。例如，?search=laptop 可用於尋找與術語「laptop」相符的所有產品。

查詢參數非常靈活，可以透過多種方式使用，具體取決於 API 的設計方式。它們允許客戶端和伺服器之間進行動態交互，從而更容易請求自訂資料。

1. 基本查詢參數處理 此 API 處理程序示範如何擷取和使用查詢參數來傳回個人化問候語。

// pages/api/greet.js

export default function handler(req, res) {
  const { name } = req.query; // Get the 'name' query parameter
  const greeting = name ? `Hello, ${name}!` : 'Hello, stranger!';

  res.status(200).json({ message: greeting });
}

用法範例：
/api/greet?name=John 將回傳 { "message": "你好，約翰！" }
/api/greet 將會回傳 { "message": "你好，陌生人！" }

1. 多個查詢參數 在此範例中，API 處理程序會提取多個查詢參數以根據使用者輸入返回格式化回應。

// pages/api/user.js

export default function handler(req, res) {
  const { name, age } = req.query; // Get 'name' and 'age' query parameters

  if (!name || !age) {
    res.status(400).json({ error: 'Name and age are required' });
    return;
  }

  res.status(200).json({ message: `User ${name} is ${age} years old.` });
}

用法範例：
/api/user?name=Jane&age=28 將回傳 { "message": "使用者 Jane 28 歲。" }
/api/user?name=Jane 將回傳 { "error": "姓名和年齡為必填項" }

1. 帶有預設值的可選查詢參數 此範例示範如何透過在參數遺失時提供預設值來處理可選查詢參數。

// pages/api/score.js

export default function handler(req, res) {
  const { player = 'Anonymous', score = '0' } = req.query; // Default values if missing

  res.status(200).json({ message: `${player} scored ${score} points!` });
}

用法範例：
/api/score?player=Alex&score=100 將回傳 { "message": "Alex 得分 100 分！" }
/api/score 將回傳 { "message": "匿名者得分為 0 分！" }

1. 處理查詢參數中的陣列 Next.js 允許查詢參數作為陣列傳遞。此範例示範如何處理值數組。

// pages/api/tags.js

export default function handler(req, res) {
  const { tags } = req.query; // Get 'tags' query parameter (array)

  if (!tags) {
    res.status(400).json({ error: 'Tags are required' });
    return;
  }

  res.status(200).json({ message: `You have selected these tags: ${tags.join(', ')}` });
}

用法範例：
/api/tags?tags=javascript&tags=react 將回傳 { "message": "您已選擇這些標籤：javascript、react" }
/api/tags 將會回傳 { "error": "Tags are required" }

1. 附查詢參數的分頁 此處理程序示範如何使用頁面和限制的查詢參數來實現分頁。

// pages/api/items.js

export default function handler(req, res) {
  const { page = 1, limit = 10 } = req.query; // Default values for page and limit
  const startIndex = (page - 1) * limit;
  const endIndex = startIndex   Number(limit);

  // Dummy data for demonstration
  const items = Array.from({ length: 100 }, (_, i) => `Item ${i   1}`);
  const paginatedItems = items.slice(startIndex, endIndex);

  res.status(200).json({
    currentPage: page,
    perPage: limit,
    items: paginatedItems,
  });
}

用法範例：
/api/items?page=2&limit=5 將會傳回接下來的5 個項目，例如{ "items": ["Item 6", "Item 7", "Item 8", "Item 9", "Item 10" ] }
/api/items（預設值）將傳回前 10 個項目，例如 { "items": ["Item 1", "Item 2", ..., "Item 10"] }

這些範例示範了在 Next.js API 路由中使用查詢參數的靈活性，涵蓋單一或多個參數、可選值、陣列和分頁等常見模式。