Node.js 后端开发完全指南：Express、Koa、NestJS 深度对比

// 📁 express-app.js
import express from 'express';

const app = express();
const PORT = 3000;

// 内置中间件
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

// 路由定义
app.get('/api/users', (req, res) => {
  res.json([{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]);
});

app.get('/api/users/:id', (req, res) => {
  const { id } = req.params;
  res.json({ id: Number(id), name: `User ${id}` });
});

app.post('/api/users', (req, res) => {
  const { name } = req.body;
  res.status(201).json({ id: Date.now(), name });
});

// 中间件链示例（多个中间件处理同一个路由）
const validateUser = (req, res, next) => {
  const { name } = req.body;
  if (!name || name.trim().length < 2) {
    return res.status(400).json({ error: '用户名至少2个字符' });
  }
  next();  // 传递给下一个中间件
};

const logRequest = (req, res, next) => {
  console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
  next();
};

app.post('/api/users/validate',
  logRequest,        // 中间件 1：日志
  validateUser,      // 中间件 2：验证
  (req, res) => {    // 中间件 3：实际处理器
    res.json({ message: '验证通过', body: req.body });
  }
);

// 全局错误处理
app.use((err, req, res, next) => {
  console.error('Unhandled Error:', err);
  res.status(500).json({
    error: '内部服务器错误',
    ...(process.env.NODE_ENV === 'development' && { detail: err.message }),
  });
});

app.listen(PORT, () => {
  console.log(`Express 服务已启动: http://localhost:${PORT}`);
});

// 📁 koa-app.js
import Koa from 'koa';
import Router from '@koa/router';
import bodyParser from 'koa-bodyparser';

const app = new Koa();
const router = new Router();

// 日志中间件 —— 演示洋葱模型
app.use(async (ctx, next) => {
  const start = Date.now();
  console.log(`⏳ 请求进入: ${ctx.method} ${ctx.url}`);

  await next();  // ⭐ 等待下游中间件执行

  const ms = Date.now() - start;
  console.log(`✅ 响应完成: ${ctx.method} ${ctx.url} — ${ms}ms`);
  ctx.set('X-Response-Time', `${ms}ms`);
});

// body 解析
app.use(bodyParser());

// 错误处理中间件
app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    ctx.status = err.status || 500;
    ctx.body = {
      error: err.message || '内部服务器错误',
    };
    ctx.app.emit('error', err, ctx);
  }
});

// 路由
router.get('/api/users', (ctx) => {
  ctx.body = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
});

router.get('/api/users/:id', (ctx) => {
  const { id } = ctx.params;
  ctx.body = { id: Number(id), name: `User ${id}` };
});

router.post('/api/users', (ctx) => {
  const { name } = ctx.request.body;
  ctx.status = 201;
  ctx.body = { id: Date.now(), name };
});

app.use(router.routes());
app.use(router.allowedMethods());

app.listen(3000, () => {
  console.log('Koa 服务已启动: http://localhost:3000');
});

// 📁 nest-app/src/users/users.controller.ts
import {
  Controller,
  Get,
  Post,
  Param,
  Body,
  HttpCode,
  HttpStatus,
  ParseIntPipe,
} from '@nestjs/common';
import { UsersService } from './users.service';
import { CreateUserDto } from './dto/create-user.dto';

@Controller('api/users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Get()
  findAll() {
    return this.usersService.findAll();
  }

  @Get(':id')
  findOne(@Param('id', ParseIntPipe) id: number) {
    return this.usersService.findOne(id);
  }

  @Post()
  @HttpCode(HttpStatus.CREATED)
  create(@Body() createUserDto: CreateUserDto) {
    return this.usersService.create(createUserDto);
  }
}

// 📁 fastify-app.js
import Fastify from 'fastify';

const app = Fastify({ logger: true });

// 使用 JSON Schema 验证请求
const createUserSchema = {
  body: {
    type: 'object',
    required: ['name'],
    properties: {
      name: { type: 'string', minLength: 2 },
    },
  },
  response: {
    201: {
      type: 'object',
      properties: {
        id: { type: 'number' },
        name: { type: 'string' },
      },
    },
  },
};

app.get('/api/users', async (request, reply) => {
  return [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
});

app.get('/api/users/:id', async (request, reply) => {
  const { id } = request.params;
  return { id: Number(id), name: `User ${id}` };
});

app.post('/api/users', { schema: createUserSchema }, async (request, reply) => {
  const { name } = request.body;
  reply.code(201);
  return { id: Date.now(), name };
});

const start = async () => {
  try {
    await app.listen({ port: 3000 });
    console.log('Fastify 服务已启动');
  } catch (err) {
    app.log.error(err);
    process.exit(1);
  }
};
start();

// Express 中间件链的详细示例
const express = require('express');
const app = express();

// 中间件 1：全局日志
app.use((req, res, next) => {
  console.log(`[1] 日志中间件: ${req.method} ${req.url}`);
  next();
});

// 中间件 2：请求计时
app.use((req, res, next) => {
  const start = Date.now();
  // 猴子补丁（Monkey Patch）res.end 来记录响应时间
  const originalEnd = res.end;
  res.end = function (...args) {
    console.log(`[2] 耗时: ${Date.now() - start}ms`);
    originalEnd.apply(res, args);
  };
  next();
});

// 中间件 3：路径特定的中间件
app.use('/api', (req, res, next) => {
  console.log(`[3] API 中间件: 路径前缀 /api`);
  next();
});

// 错误处理中间件（4 个参数）
app.use((err, req, res, next) => {
  console.error(`[错误处理] ${err.message}`);
  res.status(500).json({ error: '服务器错误' });
});

// 注：如果某个中间件调用了 res.send() 或 res.json()，
// 后续中间件将不再执行（除非手动调用 next() 不发送响应）

// Koa 洋葱模型可视化
const Koa = require('koa');
const app = new Koa();

app.use(async (ctx, next) => {
  console.log('➡️ 外层中间件 — 进入');
  ctx.state.user = 'Alice';  // 在上下文中传递数据

  await next();  // 🔄 进入下一个中间件

  console.log('⬅️ 外层中间件 — 返回');
  // 此时可以修改响应头等后处理操作
});

app.use(async (ctx, next) => {
  console.log('  ➡️ 中层中间件 — 进入');
  const start = Date.now();

  await next();  // 🔄 进入路由处理

  const ms = Date.now() - start;
  console.log(`  ⬅️ 中层中间件 — 返回 (${ms}ms)`);
  ctx.set('X-Response-Time', `${ms}ms`);
});

app.use(async (ctx) => {
  console.log('    ➡️ 内层中间件 — 路由处理');
  ctx.body = `Hello, ${ctx.state.user}!`;
  console.log('    ⬅️ 内层中间件 — 路由完成');
});

// 请求 / 时的输出：
// ➡️ 外层中间件 — 进入
//   ➡️ 中层中间件 — 进入
//     ➡️ 内层中间件 — 路由处理
//     ⬅️ 内层中间件 — 路由完成
//   ⬅️ 中层中间件 — 返回 (2ms)
// ⬅️ 外层中间件 — 返回

// 1. 函数式中间件
import { Injectable, NestMiddleware } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';

@Injectable()
export class LoggerMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    console.log(`[${req.method}] ${req.url}`);
    next();
  }
}

// 2. 守卫（Guard）—— 鉴权逻辑
import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Observable } from 'rxjs';

@Injectable()
export class AuthGuard implements CanActivate {
  canActivate(
    context: ExecutionContext,
  ): boolean | Promise<boolean> | Observable<boolean> {
    const request = context.switchToHttp().getRequest();
    return request.headers.authorization?.startsWith('Bearer ') ?? false;
  }
}

// 3. 拦截器（Interceptor）—— 请求/响应转换
import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable } from 'rxjs';
import { map, tap } from 'rxjs/operators';

@Injectable()
export class ResponseTimeInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const start = Date.now();
    return next.handle().pipe(
      tap(() => {
        const response = context.switchToHttp().getResponse();
        response.setHeader('X-Response-Time', `${Date.now() - start}ms`);
      }),
    );
  }
}

// 4. 管道（Pipe）—— 输入验证与转换
import { PipeTransform, Injectable, ArgumentMetadata, BadRequestException } from '@nestjs/common';

@Injectable()
export class ParseIdPipe implements PipeTransform {
  transform(value: any, metadata: ArgumentMetadata) {
    const id = parseInt(value, 10);
    if (isNaN(id)) {
      throw new BadRequestException('ID 必须是数字');
    }
    return id;
  }
}

// 📁 prisma/schema.prisma
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model User {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  name      String
  role      Role     @default(USER)
  posts     Post[]
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

model Post {
  id        Int      @id @default(autoincrement())
  title     String
  content   String?
  published Boolean  @default(false)
  author    User     @relation(fields: [authorId], references: [id])
  authorId  Int
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

enum Role {
  USER
  ADMIN
}

// 📁 Prisma 查询示例
import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

// 创建用户并关联文章
async function createUserWithPost() {
  const user = await prisma.user.create({
    data: {
      email: 'alice@example.com',
      name: 'Alice',
      posts: {
        create: { title: 'Hello Prisma', content: '这是我的第一篇文章' },
      },
    },
    include: { posts: true },
  });
  return user;
}

// 复杂查询：查询用户及其文章，并按条件筛选
async function getUsersWithPublishedPosts() {
  const users = await prisma.user.findMany({
    where: {
      posts: {
        some: { published: true },
      },
    },
    include: {
      posts: {
        where: { published: true },
        orderBy: { createdAt: 'desc' },
        take: 5,
      },
    },
  });
  return users;
}

// 分页查询
async function getPaginatedPosts(page: number, pageSize: number) {
  const [posts, total] = await Promise.all([
    prisma.post.findMany({
      skip: (page - 1) * pageSize,
      take: pageSize,
      orderBy: { createdAt: 'desc' },
      include: { author: { select: { name: true, email: true } } },
    }),
    prisma.post.count(),
  ]);
  return { data: posts, total, page, pageSize, totalPages: Math.ceil(total / pageSize) };
}

// 事务操作
async function transferPoints(fromUserId: number, toUserId: number, points: number) {
  await prisma.$transaction([
    prisma.user.update({
      where: { id: fromUserId },
      data: { points: { decrement: points } },
    }),
    prisma.user.update({
      where: { id: toUserId },
      data: { points: { increment: points } },
    }),
  ]);
}

// 📁 TypeORM 实体定义
import {
  Entity,
  PrimaryGeneratedColumn,
  Column,
  CreateDateColumn,
  UpdateDateColumn,
  OneToMany,
  ManyToOne,
  JoinColumn,
} from 'typeorm';

@Entity('users')
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({ unique: true })
  email: string;

  @Column()
  name: string;

  @Column({ type: 'enum', enum: ['USER', 'ADMIN'], default: 'USER' })
  role: string;

  @OneToMany(() => Post, (post) => post.author)
  posts: Post[];

  @CreateDateColumn()
  createdAt: Date;

  @UpdateDateColumn()
  updatedAt: Date;
}

@Entity('posts')
export class Post {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  title: string;

  @Column({ type: 'text', nullable: true })
  content: string;

  @Column({ default: false })
  published: boolean;

  @ManyToOne(() => User, (user) => user.posts)
  @JoinColumn({ name: 'author_id' })
  author: User;

  @Column({ name: 'author_id' })
  authorId: number;

  @CreateDateColumn()
  createdAt: Date;

  @UpdateDateColumn()
  updatedAt: Date;
}

// 📁 TypeORM 查询示例
import { DataSource, Repository } from 'typeorm';
import { User } from './entities/User';
import { Post } from './entities/Post';

const AppDataSource = new DataSource({
  type: 'postgres',
  url: process.env.DATABASE_URL,
  entities: [User, Post],
  synchronize: false, // 生产环境务必设为 false
});

// 使用 Repository 模式
const userRepo: Repository<User> = AppDataSource.getRepository(User);
const postRepo: Repository<Post> = AppDataSource.getRepository(Post);

// 创建用户
async function createUser() {
  const user = userRepo.create({ email: 'bob@example.com', name: 'Bob' });
  return await userRepo.save(user);
}

// 使用 QueryBuilder 构建复杂查询
async function findUsersWithPublishedPosts() {
  return await userRepo
    .createQueryBuilder('user')
    .leftJoinAndSelect('user.posts', 'post')
    .where('post.published = :published', { published: true })
    .andWhere('user.role = :role', { role: 'USER' })
    .orderBy('user.createdAt', 'DESC')
    .skip(0)
    .take(10)
    .getManyAndCount();
}

// 事务
async function updateInTransaction() {
  await AppDataSource.transaction(async (manager) => {
    await manager.update(User, { id: 1 }, { name: 'Alice Updated' });
    await manager.update(Post, { authorId: 1 }, { published: true });
  });
}

// 类型安全的 Express Request Handler
import { Request, Response, NextFunction, RequestHandler } from 'express';

// 定义泛型处理函数
type AsyncHandler = <T = any>(
  fn: (req: Request, res: Response, next: NextFunction) => Promise<T>
) => RequestHandler;

const asyncHandler: AsyncHandler = (fn) => (req, res, next) => {
  Promise.resolve(fn(req, res, next)).catch(next);
};

// 自定义 Request 类型（扩展）
declare global {
  namespace Express {
    interface Request {
      user?: {
        id: number;
        email: string;
        role: 'USER' | 'ADMIN';
      };
    }
  }
}

// 使用
app.get(
  '/api/users/:id',
  authenticate,  // 中间件设置 req.user
  asyncHandler(async (req, res) => {
    const user = req.user!;  // 类型安全
    res.json(user);
  }),
);

// 泛型 API 响应类型
interface ApiResponse<T> {
  success: boolean;
  data: T;
  message?: string;
  timestamp: number;
}

function success<T>(data: T, message?: string): ApiResponse<T> {
  return { success: true, data, message, timestamp: Date.now() };
}

function error(message: string): ApiResponse<null> {
  return { success: false, data: null, message, timestamp: Date.now() };
}

// 使用
app.get('/api/users', (req, res) => {
  const users = [{ id: 1, name: 'Alice' }];
  res.json(success(users, '获取用户列表成功'));
});

# 📁 Dockerfile
# === 多阶段构建 ===

# 阶段 1：依赖安装和构建
FROM node:20-alpine AS builder

WORKDIR /app

# 优先复制依赖配置，利用 Docker 缓存
COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile

# 复制源码并构建
COPY tsconfig.json ./
COPY src/ ./src/
RUN pnpm run build

# 阶段 2：生产镜像（最小化）
FROM node:20-alpine AS runner

WORKDIR /app

# 安全：使用非 root 用户
RUN addgroup --system --gid 1001 nodejs && \
    adduser --system --uid 1001 appuser

# 只复制生产依赖和构建产物
COPY package.json pnpm-lock.yaml ./
RUN corepack enable && \
    pnpm install --frozen-lockfile --prod && \
    pnpm store prune

COPY --from=builder /app/dist ./dist

USER appuser

EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

CMD ["node", "dist/index.js"]

# 📁 docker-compose.yml
version: '3.8'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - DATABASE_URL=postgresql://user:password@db:5432/myapp
      - REDIS_URL=redis://redis:6379
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    restart: unless-stopped
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

  db:
    image: postgres:16-alpine
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
      POSTGRES_DB: myapp
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d myapp"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    volumes:
      - redisdata:/data
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - app
    restart: unless-stopped

volumes:
  pgdata:
  redisdata:

# 📁 nginx.conf（反向代理到 Node.js）
events {}

http {
  upstream node_app {
    server app:3000;
  }

  server {
    listen 80;

    location / {
      proxy_pass http://node_app;
      proxy_http_version 1.1;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection 'upgrade';
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_cache_bypass $http_upgrade;

      # WebSocket 支持
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection "upgrade";

      # 超时设置
      proxy_connect_timeout 60s;
      proxy_read_timeout 60s;
      proxy_send_timeout 60s;
    }

    # 静态资源缓存
    location /static/ {
      proxy_pass http://node_app;
      expires 7d;
      add_header Cache-Control "public, immutable";
    }
  }
}