第 6 章：Node.js 后端开发¶

// src/app.ts — Fastify 应用主文件
import Fastify from "fastify";
import { serializerCompiler, validatorCompiler, ZodTypeProvider } from "@fastify/type-provider-zod";
import cors from "@fastify/cors";
import helmet from "@fastify/helmet";
import jwt from "@fastify/jwt";

export function buildApp() {
  const app = Fastify({
    logger: {
      level: process.env.NODE_ENV === "production" ? "info" : "debug",
      // 生产环境用 pino-pretty 格式化日志
    },
  }).withTypeProvider<ZodTypeProvider>(); // 开启 Zod 类型提供器

  // 注册编译器（Zod 作为验证器）
  app.setValidatorCompiler(validatorCompiler);
  app.setSerializerCompiler(serializerCompiler);

  // 插件：安全头、CORS、JWT
  app.register(helmet);
  app.register(cors, {
    origin: process.env.ALLOWED_ORIGINS?.split(",") ?? ["http://localhost:3000"],
    credentials: true,
  });
  app.register(jwt, {
    secret: process.env.JWT_SECRET!,
    sign: { expiresIn: "7d" },
  });

  // 注册路由（模块化）
  app.register(import("./routes/users"), { prefix: "/api/users" });
  app.register(import("./routes/auth"),  { prefix: "/api/auth" });
  app.register(import("./routes/posts"), { prefix: "/api/posts" });

  // 健康检查
  app.get("/health", () => ({ status: "ok", timestamp: new Date().toISOString() }));

  return app;
}

// src/server.ts — 启动入口
import { buildApp } from "./app";

const app = buildApp();

app.listen({ port: Number(process.env.PORT ?? 3000), host: "0.0.0.0" }, (err) => {
  if (err) {
    app.log.error(err);
    process.exit(1);
  }
});

// src/schemas/user.schema.ts
import { z } from "zod";

// 定义 Schema（运行时验证规则）
export const CreateUserSchema = z.object({
  name:     z.string().min(2).max(50),
  email:    z.string().email("Invalid email format"),
  password: z.string().min(8).regex(/(?=.*[A-Z])(?=.*[0-9])/, "Must include uppercase and digit"),
  role:     z.enum(["admin", "user"]).default("user"),
});

export const UpdateUserSchema = CreateUserSchema.partial().omit({ password: true });

export const UserIdSchema = z.object({
  id: z.string().uuid("Invalid user ID format"),
});

export const QueryUsersSchema = z.object({
  page:    z.coerce.number().int().positive().default(1),
  limit:   z.coerce.number().int().positive().max(100).default(20),
  search:  z.string().optional(),
  role:    z.enum(["admin", "user"]).optional(),
});

// 从 Schema 提取 TypeScript 类型（无需重复定义！）
export type CreateUserDto  = z.infer<typeof CreateUserSchema>;
export type UpdateUserDto  = z.infer<typeof UpdateUserSchema>;
export type QueryUsersDto  = z.infer<typeof QueryUsersSchema>;

// src/routes/users.ts
import type { FastifyPluginAsyncZod } from "@fastify/type-provider-zod";
import { z } from "zod";
import { CreateUserSchema, UpdateUserSchema, UserIdSchema, QueryUsersSchema } from "../schemas/user.schema";
import { UserService } from "../services/user.service";

const userService = new UserService();

const usersRoutes: FastifyPluginAsyncZod = async (app) => {
  // GET /api/users — 查询用户列表
  app.get("/", {
    schema: {
      querystring: QueryUsersSchema,
      response: {
        200: z.object({
          users: z.array(z.object({
            id:    z.string(),
            name:  z.string(),
            email: z.string(),
            role:  z.enum(["admin", "user"]),
          })),
          total: z.number(),
          page:  z.number(),
        }),
      },
      tags: ["users"],
      summary: "List users with pagination",
    },
  }, async (request) => {
    // request.query 类型完全推断自 QueryUsersSchema！
    const { page, limit, search, role } = request.query;
    return userService.findAll({ page, limit, search, role });
  });

  // GET /api/users/:id — 获取单个用户
  app.get("/:id", {
    schema: {
      params: UserIdSchema,
    },
  }, async (request, reply) => {
    const user = await userService.findById(request.params.id);
    if (!user) {
      return reply.status(404).send({ error: "User not found" });
    }
    return user;
  });

  // POST /api/users — 创建用户（需要 admin 权限）
  app.post("/", {
    onRequest: [app.authenticate, app.requireAdmin], // 认证中间件
    schema: {
      body: CreateUserSchema,
      response: { 201: z.object({ id: z.string(), message: z.string() }) },
    },
  }, async (request, reply) => {
    // request.body 类型完全推断：CreateUserDto
    const newUser = await userService.create(request.body);
    return reply.status(201).send({ id: newUser.id, message: "User created" });
  });

  // PATCH /api/users/:id — 更新用户
  app.patch("/:id", {
    onRequest: [app.authenticate],
    schema: {
      params: UserIdSchema,
      body: UpdateUserSchema,
    },
  }, async (request, reply) => {
    const updated = await userService.update(request.params.id, request.body);
    if (!updated) return reply.status(404).send({ error: "User not found" });
    return updated;
  });

  // DELETE /api/users/:id
  app.delete("/:id", {
    onRequest: [app.authenticate, app.requireAdmin],
    schema: { params: UserIdSchema },
  }, async (request, reply) => {
    await userService.delete(request.params.id);
    return reply.status(204).send();
  });
};

export default usersRoutes;

// src/lib/prisma.ts — 单例 Prisma 客户端
import { PrismaClient } from "@prisma/client";

// 防止开发环境热重载时创建多个连接
const globalForPrisma = globalThis as unknown as { prisma: PrismaClient };

export const prisma = globalForPrisma.prisma ?? new PrismaClient({
  log: process.env.NODE_ENV === "development" ? ["query", "error"] : ["error"],
});

if (process.env.NODE_ENV !== "production") {
  globalForPrisma.prisma = prisma;
}

// src/services/user.service.ts
import { prisma } from "../lib/prisma";
import { type CreateUserDto, type UpdateUserDto, type QueryUsersDto } from "../schemas/user.schema";
import bcrypt from "bcryptjs";

export class UserService {
  async findAll({ page, limit, search, role }: QueryUsersDto) {
    const where = {
      ...(search ? {
        OR: [
          { name:  { contains: search, mode: "insensitive" as const } },
          { email: { contains: search, mode: "insensitive" as const } },
        ],
      } : {}),
      ...(role ? { role: role.toUpperCase() as "ADMIN" | "USER" } : {}),
    };

    const [users, total] = await Promise.all([
      prisma.user.findMany({
        where,
        skip: (page - 1) * limit,
        take: limit,
        select: { id: true, name: true, email: true, role: true, createdAt: true },
        orderBy: { createdAt: "desc" },
      }),
      prisma.user.count({ where }),
    ]);

    return { users, total, page };
  }

  async findById(id: string) {
    return prisma.user.findUnique({
      where: { id },
      select: { id: true, name: true, email: true, role: true, createdAt: true },
    });
  }

  async create(data: CreateUserDto) {
    const hashedPassword = await bcrypt.hash(data.password, 12);
    return prisma.user.create({
      data: {
        ...data,
        password: hashedPassword,
        role: data.role.toUpperCase() as "ADMIN" | "USER",
      },
    });
  }

  async update(id: string, data: UpdateUserDto) {
    return prisma.user.update({
      where: { id },
      data,
    }).catch(() => null); // 如果不存在返回 null
  }

  async delete(id: string) {
    return prisma.user.delete({ where: { id } });
  }
}

// src/plugins/auth.ts
import type { FastifyPluginAsync, FastifyRequest, FastifyReply } from "fastify";
import fp from "fastify-plugin";

// 扩展 Fastify 的类型声明
declare module "fastify" {
  interface FastifyInstance {
    authenticate:  (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
    requireAdmin:  (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
  }
  interface FastifyRequest {
    user: { id: string; email: string; role: "ADMIN" | "USER" };
  }
}

const authPlugin: FastifyPluginAsync = async (app) => {
  // 验证 JWT
  app.decorate("authenticate", async (request: FastifyRequest, reply: FastifyReply) => {
    try {
      await request.jwtVerify();
    } catch {
      reply.status(401).send({ error: "Unauthorized" });
    }
  });

  // 要求管理员角色
  app.decorate("requireAdmin", async (request: FastifyRequest, reply: FastifyReply) => {
    if (request.user.role !== "ADMIN") {
      reply.status(403).send({ error: "Forbidden: Admin role required" });
    }
  });
};

export default fp(authPlugin);