Fastify 实战：搭建一个带 JWT 鉴权的用户管理 API

fastify-user-api/
├── package.json
├── src/
│   ├── app.js                # 组装应用入口
│   ├── server.js             # 启动 + 优雅关闭
│   ├── config.js             # 环境配置
│   ├── plugins/
│   │   ├── support.js        # 公共工具（fastify-plugin）
│   │   ├── jwt.js            # JWT 鉴权插件
│   │   └── db.js             # 内存数据库插件（演示）
│   ├── routes/
│   │   ├── auth.js           # 登录/注册
│   │   ├── users.js          # 用户 CRUD（需鉴权）
│   │   └── root.js           # 健康检查
│   └── services/
│       └── userService.js    # 业务逻辑

export default {
  PORT: process.env.PORT || 3000,
  JWT_SECRET: process.env.JWT_SECRET || 'dev-secret',
  JWT_EXPIRES_IN: process.env.JWT_EXPIRES_IN || '1d',
  LOG_LEVEL: process.env.LOG_LEVEL || 'info',
};

// src/plugins/support.js
import fp from 'fastify-plugin';

export default fp(async function supportPlugin(app, opts) {
  // 给 reply 增加统一业务错误方法
  app.decorateReply('fail', function (code, message, statusCode = 400) {
    return this.code(statusCode).send({ ok: false, code, message });
  });
  // 给 req 增加成功包装读法（序列化阶段再加，见 onSend）
}, { name: 'support' });

import fp from 'fastify-plugin';

export default fp(async function dbPlugin(app) {
  const users = new Map();
  let seq = 0;

  app.decorate('db', {
    async createUser({ name, password }) {
      const id = String(++seq);
      const user = { id, name, password, createdAt: Date.now() };
      users.set(id, user);
      return user;
    },
    async findUserById(id) {
      return users.get(id);
    },
    async findUserByName(name) {
      return [...users.values()].find(u => u.name === name);
    },
    async deleteUser(id) {
      return users.delete(id);
    },
  });

  app.addHook('onClose', async () => {
    app.log.info('db closed');
  });
}, { name: 'db' });

import fp from 'fastify-plugin';
import jwt from '@fastify/jwt';

export default fp(async function jwtPlugin(app, opts) {
  await app.register(jwt, { secret: app.config.JWT_SECRET });

  // 解析 Bearer token 并注入 req.user
  app.decorate('authenticate', async (req, reply) => {
    try {
      await req.jwtVerify();
    } catch (err) {
      if (err.code === 'FST_JWT_NO_AUTHORIZATION_IN_HEADER') {
        return reply.fail('AUTH_MISSING', '缺少登录凭证', 401);
      }
      return reply.fail('AUTH_INVALID', '登录已失效，请重新登录', 401);
    }
  });
}, { name: 'jwt' });

export class UserService {
  constructor(db) {
    this.db = db;
  }

  async register({ name, password }) {
    if (await this.db.findUserByName(name)) {
      const err = new Error(`用户名 ${name} 已存在`);
      err.code = 'USER_EXISTS';
      err.statusCode = 409;
      throw err;
    }
    // 演示：生产请用 bcrypt 哈希后存储
    return this.db.createUser({ name, password });
  }

  async login({ name, password }) {
    const user = await this.db.findUserByName(name);
    if (!user || user.password !== password) {
      const err = new Error('用户名或密码错误');
      err.code = 'BAD_CREDENTIALS';
      err.statusCode = 401;
      throw err;
    }
    return user;
  }
}

export default async function rootRoutes(app) {
  app.get('/', async () => ({
    name: 'fastify-user-api',
    version: '1.0.0',
    status: 'ok',
    uptime: process.uptime(),
  }));
}

export default async function authRoutes(app) {
  const svc = new UserService(app.db);

  const replySchema = {
    type: 'object',
    properties: {
      ok: { type: 'boolean' },
      token: { type: 'string' },
      user: {
        type: 'object',
        properties: { id: { type: 'string' }, name: { type: 'string' } },
      },
    },
  };

  app.post('/register', {
    schema: {
      body: {
        type: 'object',
        required: ['name', 'password'],
        properties: {
          name: { type: 'string', minLength: 2, maxLength: 20 },
          password: { type: 'string', minLength: 6 },
        },
      },
      response: { '2xx': replySchema },
    },
    handler: async (req) => {
      const user = await svc.register(req.body);
      const token = app.jwt.sign({ sub: user.id, name: user.name });
      return { ok: true, token, user: { id: user.id, name: user.name } };
    },
  });

  app.post('/login', {
    schema: {
      body: {
        type: 'object',
        required: ['name', 'password'],
        properties: { name: { type: 'string' }, password: { type: 'string' } },
      },
      response: { '2xx': replySchema },
    },
    handler: async (req) => {
      const user = await svc.login(req.body);
      const token = app.jwt.sign({ sub: user.id, name: user.name });
      return { ok: true, token, user: { id: user.id, name: user.name } };
    },
  });
}

export default async function userRoutes(app) {
  const svc = new UserService(app.db);

  // 本路由下所有接口都需鉴权
  app.addHook('preHandler', app.authenticate);

  app.get('/me', {
    schema: {
      response: {
        200: {
          type: 'object',
          properties: {
            id: { type: 'string' },
            name: { type: 'string' },
            createdAt: { type: 'number' },
          },
        },
      },
    },
    handler: async (req) => {
      const user = await app.db.findUserById(req.user.sub);
      if (!user) throw Object.assign(new Error('用户不存在'), { statusCode: 404 });
      return user;
    },
  });

  app.delete('/me', {
    schema: {
      response: {
        200: { type: 'object', properties: { ok: { type: 'boolean' } } },
      },
    },
    handler: async (req) => {
      await app.db.deleteUser(req.user.sub);
      return { ok: true };
    },
  });
}

import Fastify from 'fastify';
import cors from '@fastify/cors';
import config from './config.js';

export async function buildApp(opts = {}) {
  const app = Fastify({ logger: { level: config.LOG_LEVEL }, ...opts });
  app.decorate('config', config);

  // 全局错误处理
  app.setErrorHandler((err, req, reply) => {
    const statusCode = err.statusCode || 500;
    req.log.error({ err }, 'error');
    if (statusCode >= 500) {
      return reply.code(statusCode).send({
        ok: false,
        code: 'INTERNAL_ERROR',
        message: process.env.NODE_ENV === 'development' ? err.message : '服务器内部错误',
      });
    }
    return reply.code(statusCode).send({
      ok: false,
      code: err.code || 'ERROR',
      message: err.message,
    });
  });

  // 插件（顺序依赖：support → db → jwt）
  await app.register(import('./plugins/support.js'));
  await app.register(import('./plugins/db.js'));
  await app.register(import('./plugins/jwt.js'));

  // 路由
  await app.register(import('./routes/root.js'));
  await app.register(import('./routes/auth.js'), { prefix: '/api/auth' });
  await app.register(import('./routes/users.js'), { prefix: '/api/users' });

  return app;
}

import { buildApp } from './app.js';

const app = await buildApp();

await app.listen({ port: app.config.PORT, host: '0.0.0.0' });
app.log.info(`listening on ${app.config.PORT}`);

async function shutdown(signal) {
  app.log.info({ signal }, 'shutting down');
  await app.close();
  process.exit(0);
}
process.on('SIGINT', () => shutdown('SIGINT'));
process.on('SIGTERM', () => shutdown('SIGTERM'));

node src/server.js

# 注册
curl -X POST localhost:3000/api/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"name":"alice","password":"123456"}'

# 登录获取 token
curl -X POST localhost:3000/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"name":"alice","password":"123456"}'

# 带 token 访问受保护接口
curl localhost:3000/api/users/me \
  -H 'Authorization: Bearer <token>'

# 不带 token → 401 AUTH_MISSING
curl localhost:3000/api/users/me