分页

本课属于 Coddy Node.js 学习旅程的“REST API”单元。第 17 课，共 25 课。

包含一万个任务的列表太长，无法一次性全部返回。请分成多页发送：客户端请求 ?page=2&limit=20，就会收到对应的数据片段，以及绘制“第 2 页，共 5 页”所需的信息：

{ "items": [ ...books 21 to 40... ], "page": 2, "total": 95, "pages": 5 }

const start = (page - 1) * limit;    // 第 1 页从 0 开始
const items = list.slice(start, start + limit);
const pages = Math.ceil(list.length / limit);

在应用筛选条件后再计算 total，因为它描述的是客户端请求的列表。如果查询字符串中没有 page，就在转换之前将其设为 1，并将 limit 设为 10，因为 Number(undefined) 的结果是 NaN。然后拒绝任何不在范围内的非整数，并返回 400。为 limit 设置上限，可以防止客户端一次请求所有内容。

挑战

简单

一万个任务的列表太长，无法一次性返回。请分页发送列表，并提供客户端显示“第 1 页，共 2 页”所需的信息。

在 routes/tasks.js 中，修改列表路由的返回内容：返回对象而不是数组。对于初始任务，GET /api/tasks?limit=2 会返回：

{
  "items": [
    { "id": 1, "title": "Write the project brief", "done": true, "createdAt": "2026-03-02T09:00:00.000Z" },
    { "id": 2, "title": "Book the meeting room", "done": false, "createdAt": "2026-03-03T10:30:00.000Z" }
  ],
  "page": 1,
  "total": 3,
  "pages": 2
}

items 保存本页的任务，page 是页码，total 是符合筛选条件的任务数，pages 是总页数。

从查询字符串中读取 page 和 limit：
- page 是从 1 开始的整数。未提供时，使用 1。
- limit 是 1 到 50 之间的整数。未提供时，使用 10。
先设置默认值，再进行转换，因为 Number(undefined) 的结果是 NaN。任何其他值（page=0、page=abc、page=1.5、limit=0、limit=51）都会返回状态码 400。如果 limit 无效，错误消息为 limit must be a whole number from 1 to 50：
```
{ "error": { "code": "invalid_query", "message": "page must be a whole number from 1" } }
```
最后再分页：先筛选和排序，然后取出对应的页面。total 统计筛选后剩余的任务数，所以 ?done=false&limit=1 会返回 "total": 2 和 "pages": 2。

这会改变响应的结构，因此，原本预期收到数组的客户端也必须修改。版本控制课会介绍如何处理这种情况。

试试看： GET /api/tasks?limit=2 会返回任务 1 和 2，并包含 "page": 1、"total": 3 和 "pages": 2。GET /api/tasks?page=2&limit=2 只会返回任务 3。普通的 GET /api/tasks 会返回全部 3 个任务，并包含 "page": 1 和 "pages": 1。GET /api/tasks?page=0 会返回状态码 400，错误码为 invalid_query。

亲手试试

import { Router } from 'express';
import { z } from 'zod';
import { sendError, sendInvalid } from '../errors.js';
import { nextId, tasks } from '../store.js';

const router = Router();

// 完整的任务，与 PUT 发送的内容一致。.strict() 会拒绝未列出的字段。
const Task = z
    .object({
        title: z.string().trim().min(1).max(100),
        done: z.boolean(),
    })
    .strict();
const NewTask = Task.partial({ done: true });
const TaskChanges = Task.partial();
const SORT_FIELDS = ['title', 'createdAt'];

// 如果另一个任务已有相同标题，则为 true，不区分大小写。
const titleTaken = (title, exceptId) =>
    tasks.some((t) => t.id !== exceptId && t.title.toLowerCase() === title.toLowerCase());

router.get('/', (req, res) => {
    const { done, q, sort } = req.query;
    let list = tasks;
    if (done !== undefined) {
        if (done !== 'true' && done !== 'false') {
            return sendError(res, 400, 'invalid_query', 'done must be true or false');
        }
        list = list.filter((t) => t.done === (done === 'true'));
    }
    if (q !== undefined) {
        const words = String(q).toLowerCase();
        list = list.filter((t) => t.title.toLowerCase().includes(words));
    }
    if (sort !== undefined) {
        const field = String(sort).startsWith('-') ? String(sort).slice(1) : String(sort);
        if (!SORT_FIELDS.includes(field)) {
            return sendError(
                res,
                400,
                'invalid_query',
                'sort must be title or createdAt, with - in front to reverse',
            );
        }
        const direction = String(sort).startsWith('-') ? -1 : 1;
        list = list.toSorted((a, b) => a[field].localeCompare(b[field]) * direction);
    }
    res.json(list);
});

router.get('/:id', (req, res) => {
    const task = tasks.find((t) => t.id === Number(req.params.id));
    if (!task) {
        return sendError(res, 404, 'not_found', 'Task not found');
    }
    res.json(task);
});

router.post('/', (req, res) => {
    const result = NewTask.safeParse(req.body);
    if (!result.success) {
        return sendInvalid(res, result.error);
    }
    const { title, done = false } = result.data;
    if (titleTaken(title)) {
        return sendError(res, 409, 'conflict', 'A task with this title already exists');
    }
    const task = { id: nextId(), title, done, createdAt: new Date().toISOString() };
    tasks.push(task);
    res.status(201).location(`/api/tasks/${task.id}`).json(task);
});

router.patch('/:id', (req, res) => {
    const task = tasks.find((t) => t.id === Number(req.params.id));
    if (!task) {
        return sendError(res, 404, 'not_found', 'Task not found');
    }
    const result = TaskChanges.safeParse(req.body);
    if (!result.success) {
        return sendInvalid(res, result.error);
    }
    if (result.data.title !== undefined && titleTaken(result.data.title, task.id)) {
        return sendError(res, 409, 'conflict', 'A task with this title already exists');
    }
    Object.assign(task, result.data);
    res.json(task);
});

router.put('/:id', (req, res) => {
    const index = tasks.findIndex((t) => t.id === Number(req.params.id));
    if (index === -1) {
        return sendError(res, 404, 'not_found', 'Task not found');
    }
    const result = Task.safeParse(req.body);
    if (!result.success) {
        return sendInvalid(res, result.error);
    }
    const { id, createdAt } = tasks[index];
    if (titleTaken(result.data.title, id)) {
        return sendError(res, 409, 'conflict', 'A task with this title already exists');
    }
    tasks[index] = { id, ...result.data, createdAt };
    res.json(tasks[index]);
});

router.delete('/:id', (req, res) => {
    const index = tasks.findIndex((t) => t.id === Number(req.params.id));
    if (index === -1) {
        return sendError(res, 404, 'not_found', 'Task not found');
    }
    tasks.splice(index, 1);
    res.status(204).end();
});

export default router;