菜鸟教程
教程 fastify tutorial

构建一个简易 API 项目

在本教程中，我们将使用 Fastify 构建一个简单的 API 项目，展示如何创建基本的 RESTful API 路由、处理请求、返回响应，并进行简单的错误处理。我们将从安装 Fastify 开始，然后逐步构建完整的 API 项目。

1. 初始化项目

首先，我们需要创建一个新的项目文件夹，并初始化一个 Node.js 项目。

bash 
mkdir fastify-api
cd fastify-api
npm init -y

安装 Fastify：

bash 
npm install fastify

2. 创建 Fastify 应用

在项目根目录下，创建一个 app.ts 文件，并写入基本的 Fastify 配置和路由。

typescript 
import fastify from 'fastify';

const app = fastify();

// 创建根路由
app.get('/', async (request, reply) => {
  return { message: 'Welcome to the Fastify API' };
});

// 创建获取用户的 API 路由
app.get('/users', async (request, reply) => {
  return [
    { id: 1, name: 'John Doe' },
    { id: 2, name: 'Jane Smith' }
  ];
});

// 创建获取单个用户的 API 路由
app.get('/users/:id', async (request, reply) => {
  const userId = request.params.id;
  // 简单的错误处理
  if (userId === '1') {
    return { id: 1, name: 'John Doe' };
  } else if (userId === '2') {
    return { id: 2, name: 'Jane Smith' };
  } else {
    return reply.status(404).send({ error: 'User not found' });
  }
});

// 启动 Fastify 服务器
const start = async () => {
  try {
    await app.listen(3000);
    console.log('Server listening on http://localhost:3000');
  } catch (err) {
    app.log.error(err);
    process.exit(1);
  }
};

start();

代码解释

  • 我们使用 fastify() 创建了一个 Fastify 实例。
  • 在 app.get() 中定义了三个路由：
    • 根路由 / 返回一个简单的欢迎消息。
    • /users 返回一个简单的用户列表。
    • /users/:id 返回指定 ID 的用户信息。如果用户 ID 不存在，则返回 404 错误。

3. 启动项目

接下来，运行以下命令启动 Fastify 服务器：

bash 
ts-node app.ts

如果你没有安装 ts-node，可以先执行：

bash 
npm install -g ts-node typescript

服务器成功启动后，你可以通过浏览器访问 http://localhost:3000/，看到返回的欢迎消息。访问 http://localhost:3000/users 会返回用户列表，而访问 http://localhost:3000/users/1 或 http://localhost:3000/users/2 将返回对应的用户信息。如果访问不存在的用户 ID（如 http://localhost:3000/users/3），将返回 404 错误。

4. 添加请求体处理

接下来，我们添加一个处理 POST 请求的路由，来接收数据并保存。我们将通过 JSON 格式的请求体来创建一个新的用户。

添加用户的路由

typescript 
app.post('/users', async (request, reply) => {
  const { name } = request.body as { name: string };
  if (!name) {
    return reply.status(400).send({ error: 'Name is required' });
  }
  // 模拟创建用户
  const newUser = { id: Date.now(), name };
  return reply.status(201).send(newUser);
});

代码解释

  • 这个路由会接收一个包含用户姓名的请求体（JSON 格式）。
  • 如果请求体中没有提供 name 字段，我们会返回 400 错误。
  • 否则，创建一个新的用户并返回其信息，使用 201 状态码表示成功创建。

测试 POST 请求

你可以使用 Postman 或 curl 测试这个 POST 路由：

bash 
curl -X POST http://localhost:3000/users -H "Content-Type: application/json" -d '{"name": "Alice"}'

响应将类似：

json 
{
  "id": 1630424343235,
  "name": "Alice"
}

5. 错误处理

在 Fastify 中，处理错误是非常重要的。我们可以通过 Fastify 提供的错误处理机制来定制化响应错误。

错误处理中间件

typescript 
app.setErrorHandler((error, request, reply) => {
  console.error(error);
  reply.status(500).send({ error: 'Internal Server Error' });
});

在上面的代码中，我们设置了一个全局的错误处理器，当发生任何未捕获的错误时，都会返回一个 500 状态码和错误信息。

6. 完整的代码

以下是包含所有内容的完整项目代码：

typescript 
import fastify from 'fastify';

const app = fastify();

// 根路由
app.get('/', async (request, reply) => {
  return { message: 'Welcome to the Fastify API' };
});

// 获取用户列表
app.get('/users', async (request, reply) => {
  return [
    { id: 1, name: 'John Doe' },
    { id: 2, name: 'Jane Smith' }
  ];
});

// 获取单个用户
app.get('/users/:id', async (request, reply) => {
  const userId = request.params.id;
  if (userId === '1') {
    return { id: 1, name: 'John Doe' };
  } else if (userId === '2') {
    return { id: 2, name: 'Jane Smith' };
  } else {
    return reply.status(404).send({ error: 'User not found' });
  }
});

// 添加新用户
app.post('/users', async (request, reply) => {
  const { name } = request.body as { name: string };
  if (!name) {
    return reply.status(400).send({ error: 'Name is required' });
  }
  const newUser = { id: Date.now(), name };
  return reply.status(201).send(newUser);
});

// 错误处理
app.setErrorHandler((error, request, reply) => {
  console.error(error);
  reply.status(500).send({ error: 'Internal Server Error' });
});

// 启动服务器
const start = async () => {
  try {
    await app.listen(3000);
    console.log('Server listening on http://localhost:3000');
  } catch (err) {
    app.log.error(err);
    process.exit(1);
  }
};

start();

7. 总结

你已经构建了一个简易的 API 项目，包含基本的 GET 和 POST 路由，并且通过错误处理确保项目更加健壮。通过 Fastify，我们能够快速构建高效且易于维护的 API 服务。

相关内容