Next.js 全栈开发基础：在 pages/api/*.ts 中创建接口的艺术

在 Web 开发的世界里，前端与后端就像一对需要默契配合的舞者。前端负责优雅地展示数据，后端则默默在幕后准备数据，而接口就是它们之间传递信号的乐谱。在 Next.js 的舞台上，pages/api/*.ts就是谱写这份乐谱的最佳创作室。今天，我们就来揭开在 Next.js 中创建接口的神秘面纱，用 TypeScript 为你的全栈应用搭建起高效的数据桥梁。

接口的本质：数据交换的高速公路

在深入技术细节之前，让我们先理解接口的本质。想象你在餐厅点餐，你（前端）告诉服务员（接口）想要什么，服务员把需求传达给厨房（数据库 / 业务逻辑），然后把做好的食物（数据）端给你。这个过程中，服务员就是接口，负责规范请求格式、处理业务逻辑并返回结果。

在计算机科学中，接口本质上是客户端与服务器之间约定的数据交换格式和规则。Next.js 的 API 路由之所以强大，是因为它允许我们在同一个项目中同时编写前端页面和后端接口，就像在同一个屋檐下同时拥有餐厅大堂和厨房，大大提高了开发效率。

初探 pages/api：Next.js 的接口魔法

Next.js 的 API 路由基于一个简单而强大的约定：在pages/api目录下创建的文件会自动成为 API 接口。这个机制背后其实是 Next.js 的文件系统路由在起作用，当服务器启动时，它会扫描pages/api目录下的所有文件，为每个文件创建对应的路由端点。

比如我们创建pages/api/hello.ts文件，访问http://localhost:3000/api/hello就能调用这个接口。这种设计就像给每个接口分配了独立的办公室，它们互不干扰又能协同工作。

第一个接口：Hello World 的进阶版

让我们从经典的 Hello World 开始，创建一个能返回个性化问候的接口。在pages/api目录下新建greet.ts文件，输入以下代码：

javascript 复制代码

export default function handler(req, res) {
  // 从请求中获取查询参数name
  const { name = "World" } = req.query;
  
  // 设置响应状态码为200（成功）
  res.status(200).json({ 
    message: `Hello, ${name}!`,
    timestamp: new Date().toISOString()
  });
}

这个接口做了三件事：

从请求的查询参数中获取 name，如果没有提供则默认使用 "World"

设置 HTTP 响应状态码为 200，表示请求成功

返回一个 JSON 对象，包含问候消息和当前时间戳

运行你的 Next.js 应用，访问http://localhost:3000/api/greet?name=Next.js，你会看到类似这样的响应：

json 复制代码

{
  "message": "Hello, Next.js!",
  "timestamp": "2025-08-17T12:34:56.789Z"
}

处理不同的 HTTP 方法：接口的多面手

一个健壮的接口应该能处理不同的 HTTP 方法，就像一个多才多艺的演员能胜任不同的角色。常见的 HTTP 方法有 GET（获取数据）、POST（创建数据）、PUT（更新数据）和 DELETE（删除数据）。

让我们创建一个简单的任务管理接口，支持 GET 和 POST 方法：

javascript 复制代码

// pages/api/tasks.ts
let tasks = [
  { id: 1, title: "学习Next.js", completed: false },
  { id: 2, title: "创建API接口", completed: true }
];
export default function handler(req, res) {
  // 获取请求方法
  const { method } = req;
  switch (method) {
    case 'GET':
      // 处理GET请求：返回所有任务
      res.status(200).json(tasks);
      break;
    case 'POST':
      // 处理POST请求：创建新任务
      const { title } = req.body;
      
      // 验证请求数据
      if (!title) {
        return res.status(400).json({ error: "任务标题不能为空" });
      }
      
      // 创建新任务
      const newTask = {
        id: tasks.length + 1,
        title,
        completed: false
      };
      
      // 添加到任务列表
      tasks.push(newTask);
      
      // 返回创建的任务，状态码201表示资源创建成功
      res.status(201).json(newTask);
      break;
    default:
      // 处理不支持的方法
      res.setHeader('Allow', ['GET', 'POST']);
      res.status(405).end(`方法 ${method} 不被允许`);
  }
}

这个接口展示了如何根据不同的 HTTP 方法执行不同的操作：

当使用 GET 方法访问时，它返回所有任务列表

当使用 POST 方法并发送包含 title 的 JSON 数据时，它创建一个新任务

当使用不支持的方法（如 PUT 或 DELETE）时，它返回 405 错误

你可以使用工具如 Postman 或 curl 来测试这个接口：

bash 复制代码

# 测试GET请求
curl http://localhost:3000/api/tasks
# 测试POST请求
curl -X POST -H "Content-Type: application/json" -d '{"title":"新任务"}' http://localhost:3000/api/tasks

接口参数处理：精准获取请求数据

在实际开发中，我们经常需要从不同位置获取请求数据。Next.js 的 API 路由提供了多种方式来获取这些数据，就像有多个入口可以进入一个建筑：

查询参数（Query Parameters） ：位于 URL 中?后面的键值对，通过req.query获取

路径参数（Path Parameters） ：URL 路径中的动态部分，通过文件名中的[param]定义

请求体（Request Body） ：POST、PUT 等方法发送的数据，通过req.body获取

让我们创建一个支持路径参数的接口，用于获取单个任务：

javascript 复制代码

// pages/api/tasks/[id].ts
// 假设tasks数组与前面的例子相同
let tasks = [
  { id: 1, title: "学习Next.js", completed: false },
  { id: 2, title: "创建API接口", completed: true }
];
export default function handler(req, res) {
  const { id } = req.query;
  // 将id转换为数字
  const taskId = parseInt(id, 10);
  
  // 验证id是否有效
  if (isNaN(taskId)) {
    return res.status(400).json({ error: "无效的任务ID" });
  }
  
  // 查找任务
  const task = tasks.find(t => t.id === taskId);
  
  if (task) {
    res.status(200).json(task);
  } else {
    res.status(404).json({ error: "任务不存在" });
  }
}

现在，访问http://localhost:3000/api/tasks/1会返回 ID 为 1 的任务，而访问http://localhost:3000/api/tasks/99会返回 404 错误。

错误处理：接口的安全网

就像现实生活中需要应急预案一样，接口也需要完善的错误处理机制。一个好的错误处理策略应该：

返回适当的 HTTP 状态码

提供清晰的错误信息

避免暴露敏感信息

让我们改进前面的任务接口，添加更完善的错误处理：

javascript 复制代码

// pages/api/tasks/[id].ts（改进版）
let tasks = [
  { id: 1, title: "学习Next.js", completed: false },
  { id: 2, title: "创建API接口", completed: true }
];
export default function handler(req, res) {
  try {
    const { id } = req.query;
    const taskId = parseInt(id, 10);
    
    if (isNaN(taskId)) {
      // 400 Bad Request：请求参数无效
      return res.status(400).json({ 
        error: "无效的任务ID",
        details: "ID必须是数字"
      });
    }
    
    const task = tasks.find(t => t.id === taskId);
    
    if (task) {
      // 200 OK：请求成功
      res.status(200).json(task);
    } else {
      // 404 Not Found：资源不存在
      res.status(404).json({ 
        error: "任务不存在",
        details: `没有ID为${taskId}的任务`
      });
    }
  } catch (error) {
    // 500 Internal Server Error：服务器内部错误
    console.error("处理请求时出错：", error);
    res.status(500).json({ 
      error: "服务器内部错误",
      details: "请稍后再试"
    });
  }
}

这个改进版接口使用 try-catch 块捕获可能的错误，并为不同类型的错误返回相应的状态码和详细信息，同时避免将内部错误直接暴露给客户端。

接口的性能考量：让数据流动更快

随着应用规模的增长，接口的性能变得越来越重要。以下是一些提高 API 路由性能的小贴士：

数据缓存：对于不经常变化的数据，可以使用缓存减少重复计算

请求验证：尽早验证请求数据，避免不必要的处理

分页处理：对于大量数据，使用分页减少数据传输量

异步处理：对于耗时操作，考虑使用异步处理避免阻塞

让我们实现一个带分页功能的任务列表接口：

javascript 复制代码

// pages/api/tasks/paginated.ts
let tasks = [
  // 假设这里有很多任务...
  { id: 1, title: "任务1", completed: false },
  { id: 2, title: "任务2", completed: true },
  // ...更多任务
];
export default function handler(req, res) {
  try {
    // 获取分页参数，默认页码为1，每页10条
    const { page = 1, limit = 10 } = req.query;
    const pageNum = parseInt(page, 10);
    const limitNum = parseInt(limit, 10);
    
    // 验证分页参数
    if (isNaN(pageNum) || isNaN(limitNum) || pageNum < 1 || limitNum < 1) {
      return res.status(400).json({ 
        error: "无效的分页参数",
        details: "页码和每页数量必须是正整数"
      });
    }
    
    // 计算总页数
    const totalPages = Math.ceil(tasks.length / limitNum);
    
    // 计算起始索引
    const startIndex = (pageNum - 1) * limitNum;
    
    // 获取当前页的任务
    const paginatedTasks = tasks.slice(startIndex, startIndex + limitNum);
    
    res.status(200).json({
      data: paginatedTasks,
      pagination: {
        total: tasks.length,
        page: pageNum,
        limit: limitNum,
        totalPages
      }
    });
  } catch (error) {
    console.error("分页查询出错：", error);
    res.status(500).json({ error: "服务器内部错误" });
  }
}

这个接口支持通过page和limit参数控制返回的数据量，减轻了服务器和网络的负担。

部署与注意事项：让接口飞向生产环境

当你的接口准备好部署到生产环境时，有几个重要的注意事项：

环境变量：敏感信息如数据库连接字符串应该使用环境变量，而不是硬编码在代码中

CORS 设置：如果你的前端和后端不在同一个域名下，需要配置跨域资源共享（CORS）

速率限制：为了防止滥用，考虑添加速率限制功能

日志记录：添加适当的日志记录以便调试和监控

在 Next.js 中配置 CORS 非常简单，你可以使用cors中间件：

javascript 复制代码

// pages/api/with-cors.ts
import cors from 'cors';
// 初始化cors中间件
const corsMiddleware = cors({
  origin: process.env.NEXT_PUBLIC_FRONTEND_URL || '*',
  methods: ['GET', 'POST', 'PUT', 'DELETE']
});
// 辅助函数：将中间件转换为Promise
function runMiddleware(req, res, fn) {
  return new Promise((resolve, reject) => {
    fn(req, res, (result) => {
      if (result instanceof Error) {
        return reject(result);
      }
      return resolve(result);
    });
  });
}
export default async function handler(req, res) {
  // 应用CORS中间件
  await runMiddleware(req, res, corsMiddleware);
  
  // 处理请求
  res.status(200).json({ message: "这个接口支持跨域请求！" });
}

总结：接口开发的艺术与科学

在 Next.js 中创建 API 接口就像在构建一座连接前端和后端的桥梁，它需要扎实的技术基础，也需要对用户需求的深刻理解。通过pages/api/*.ts文件，我们可以快速创建功能完善的接口，处理各种 HTTP 方法，获取不同来源的请求数据，并返回结构化的响应。

记住，一个好的接口应该是清晰、健壮、高效且安全的。它不仅要能正确处理正常情况，还要能优雅地应对错误；不仅要能满足当前需求，还要为未来的扩展留有余地。

随着你对 Next.js API 路由的深入了解，你可以尝试更高级的功能，如数据库集成、身份验证、文件上传等。全栈开发的世界充满了可能性，而接口就是打开这个世界的钥匙。现在，拿起这把钥匙，开始构建你的全栈应用吧！