项目实战：用 NestJS 构建类型安全的后端服务

npm i -g @nestjs/cli
nest new tasks-api          # 选 npm 或 pnpm
cd tasks-api
nest g resource tasks       # 选 REST API，选 y 生成 CRUD 入口
npm run start:dev

src/
├── main.ts                      # 引导入口：创建应用、挂全局管道/过滤器、listen
├── app.module.ts                # 根模块：聚合所有功能模块
├── common/                      # 跨模块共享的切面
│   ├── filters/http-exception.filter.ts
│   ├── guards/jwt-auth.guard.ts
│   ├── interceptors/logging.interceptor.ts
│   └── interceptors/timeout.interceptor.ts
├── config/
│   └── configuration.ts         # 类型安全的配置
└── tasks/                       # 一个功能模块 = 一个目录
    ├── tasks.module.ts
    ├── tasks.controller.ts
    ├── tasks.service.ts
    ├── dto/create-task.dto.ts
    ├── dto/update-task.dto.ts
    ├── dto/query-task.dto.ts
    └── entities/task.entity.ts

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "ES2021",
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "strictNullChecks": true,
    "strict": true
  }
}

// src/tasks/tasks.module.ts
import { Module } from "@nestjs/common";
import { TypeOrmModule } from "@nestjs/typeorm";
import { TasksController } from "./tasks.controller";
import { TasksService } from "./tasks.service";
import { Task } from "./entities/task.entity";
 
@Module({
  imports: [TypeOrmModule.forFeature([Task])],
  controllers: [TasksController],
  providers: [TasksService],
  exports: [TasksService],
})
export class TasksModule {}

// src/tasks/tasks.service.ts（片段）
@Injectable()
export class TasksService {
  constructor(
    private readonly repo: Repository<Task>,
    private readonly logger: LoggerService,
  ) {}
}

// src/app.module.ts（片段）
@Module({
  providers: [
    // 1) useClass：最常见，token 就是类本身
    TasksService,
    { provide: MailerService, useClass: SmtpMailerService },
 
    // 2) useValue：注入常量、配置对象或测试替身
    { provide: "APP_NAME", useValue: "tasks-api" },
 
    // 3) useFactory：需要运行时计算，deps 声明工厂自己的依赖
    {
      provide: "DB_POOL",
      useFactory: (config: ConfigService) => createPool(config.get("db")),
      inject: [ConfigService],
    },
 
    // 4) useExisting：给已有 provider 起一个别名
    { provide: "LOGGER_ALIAS", useExisting: LoggerService },
  ],
})
export class AppModule {}

constructor(@Inject("APP_NAME") private readonly appName: string) {}

// ===== 这是 Nest IoC 容器的极简复刻 =====
type Token = string;
type Scope = "singleton" | "transient";
 
type Provider =
  | { readonly kind: "value"; readonly token: Token; readonly value: unknown }
  | {
      readonly kind: "factory";
      readonly token: Token;
      readonly scope: Scope;
      readonly deps: readonly Token[];
      readonly factory: (deps: readonly unknown[]) => unknown;
    };
 
// 依赖数组里的类型已被擦除，取出时由注册方负责标注（真实框架靠元数据自动完成）
function dep<T>(deps: readonly unknown[], i: number): T {
  return deps[i] as T;
}
 
class Container {
  private readonly providers = new Map<Token, Provider>();
  private readonly singletons = new Map<Token, unknown>();
 
  register(provider: Provider): this {
    this.providers.set(provider.token, provider);
    return this;
  }
 
  resolve<T>(token: Token, chain: readonly Token[] = []): T {
    if (chain.includes(token)) {
      throw new Error("检测到循环依赖: " + [...chain, token].join(" -> "));
    }
    const provider = this.providers.get(token);
    if (provider === undefined) {
      throw new Error("找不到 provider [" + token + "]，它在当前模块里注册了吗？");
    }
    if (provider.kind === "value") return provider.value as T;
 
    const cached = this.singletons.get(token);
    if (provider.scope === "singleton" && cached !== undefined) return cached as T;
 
    // 先递归解析每个依赖，再把它们按顺序传给工厂 —— 这就是构造器注入
    const args = provider.deps.map((d) => this.resolve<unknown>(d, [...chain, token]));
    const instance = provider.factory(args);
    if (provider.scope === "singleton") this.singletons.set(token, instance);
    return instance as T;
  }
}
 
// ===== 业务类：完全不知道容器的存在 =====
class Logger {
  private static created = 0;
  readonly serial: number;
  constructor() {
    Logger.created += 1;
    this.serial = Logger.created;
  }
  log(msg: string): void {
    console.log("  [Logger#" + this.serial + "] " + msg);
  }
}
 
type Task = { readonly id: number; readonly title: string; readonly done: boolean };
 
class TasksRepository {
  private readonly rows = new Map<number, Task>();
  private nextId = 1;
  constructor(private readonly logger: Logger) {}
 
  insert(title: string): Task {
    const task: Task = { id: this.nextId, title, done: false };
    this.nextId += 1;
    this.rows.set(task.id, task);
    this.logger.log("INSERT task #" + task.id);
    return task;
  }
 
  findAll(): readonly Task[] {
    return [...this.rows.values()];
  }
}
 
class TasksService {
  constructor(
    private readonly repo: TasksRepository,
    private readonly logger: Logger,
    private readonly appName: string,
  ) {}
 
  create(title: string): Task {
    this.logger.log(this.appName + " 创建任务: " + title);
    return this.repo.insert(title);
  }
 
  list(): readonly Task[] {
    return this.repo.findAll();
  }
}
 
// ===== 注册：等价于 @Module 的 providers 数组 =====
let requestSeq = 0;
const container = new Container();
 
container
  .register({ kind: "value", token: "APP_NAME", value: "tasks-api" })
  .register({
    kind: "factory", token: "Logger", scope: "singleton", deps: [],
    factory: () => new Logger(),
  })
  .register({
    kind: "factory", token: "TasksRepository", scope: "singleton", deps: ["Logger"],
    factory: (d) => new TasksRepository(dep<Logger>(d, 0)),
  })
  .register({
    kind: "factory", token: "TasksService", scope: "singleton",
    deps: ["TasksRepository", "Logger", "APP_NAME"],
    factory: (d) =>
      new TasksService(dep<TasksRepository>(d, 0), dep<Logger>(d, 1), dep<string>(d, 2)),
  })
  .register({
    kind: "factory", token: "RequestContext", scope: "transient", deps: [],
    factory: () => {
      requestSeq += 1;
      return { requestId: "req-" + requestSeq };
    },
  });
 
// ===== 解析并使用 =====
const svc1 = container.resolve<TasksService>("TasksService");
const svc2 = container.resolve<TasksService>("TasksService");
console.log("两次解析拿到同一个单例吗?", svc1 === svc2);
 
svc1.create("把 CLI 内核搬上 HTTP");
svc1.create("给 Tasks API 加上鉴权");
console.log("任务列表:", svc2.list().map((t) => "#" + t.id + " " + t.title).join(" / "));
 
const ctxA = container.resolve<{ requestId: string }>("RequestContext");
const ctxB = container.resolve<{ requestId: string }>("RequestContext");
console.log("transient 每次都是新的:", ctxA.requestId, "vs", ctxB.requestId);
 
// ===== 两种典型启动期报错 =====
container.register({
  kind: "factory", token: "A", scope: "singleton", deps: ["B"],
  factory: (d) => ({ b: d[0] }),
});
container.register({
  kind: "factory", token: "B", scope: "singleton", deps: ["A"],
  factory: (d) => ({ a: d[0] }),
});
 
for (const bad of ["A", "MailerService"]) {
  try {
    container.resolve(bad);
  } catch (e) {
    console.log("启动失败 ->", e instanceof Error ? e.message : String(e));
  }
}
console.log("容器演示结束");

// src/tasks/tasks.controller.ts
import {
  Body, Controller, Delete, Get, HttpCode, HttpStatus,
  Param, ParseIntPipe, Patch, Post, Query,
} from "@nestjs/common";
import { TasksService } from "./tasks.service";
import { CreateTaskDto } from "./dto/create-task.dto";
import { UpdateTaskDto } from "./dto/update-task.dto";
import { QueryTaskDto } from "./dto/query-task.dto";
import { Task } from "./entities/task.entity";
 
@Controller("tasks")
export class TasksController {
  constructor(private readonly tasksService: TasksService) {}
 
  @Get()
  findAll(@Query() query: QueryTaskDto): Promise<Task[]> {
    return this.tasksService.findAll(query);
  }
 
  @Get(":id")
  findOne(@Param("id", ParseIntPipe) id: number): Promise<Task> {
    return this.tasksService.findOne(id);
  }
 
  @Post()
  @HttpCode(HttpStatus.CREATED)
  create(@Body() dto: CreateTaskDto): Promise<Task> {
    return this.tasksService.create(dto);
  }
 
  @Patch(":id")
  update(
    @Param("id", ParseIntPipe) id: number,
    @Body() dto: UpdateTaskDto,
  ): Promise<Task> {
    return this.tasksService.update(id, dto);
  }
 
  @Delete(":id")
  @HttpCode(HttpStatus.NO_CONTENT)
  remove(@Param("id", ParseIntPipe) id: number): Promise<void> {
    return this.tasksService.remove(id);
  }
}

type HttpMethod = "GET" | "POST" | "PATCH" | "DELETE";
// 用 string | undefined 建模缺失的键，等价于开启 noUncheckedIndexedAccess 的效果
type Dict = Record<string, string | undefined>;
 
type RequestCtx = {
  readonly params: Dict;
  readonly query: Dict;
  readonly body: unknown;
};
 
type RouteHandler = (ctx: RequestCtx) => unknown;
 
type Route = {
  readonly method: HttpMethod;
  readonly path: string;
  readonly status: number;
  readonly handler: RouteHandler;
};
 
class HttpError extends Error {
  constructor(public readonly status: number, message: string) {
    super(message);
    this.name = "HttpError";
  }
}
 
class Router {
  private readonly routes: Route[] = [];
 
  // 等价于 @Get(path) / @Post(path) 在类定义时做的登记动作
  add(method: HttpMethod, path: string, status: number, handler: RouteHandler): this {
    this.routes.push({ method, path, status, handler });
    return this;
  }
 
  private static match(pattern: string, path: string): Dict | null {
    const pSeg = pattern.split("/").filter((s) => s !== "");
    const aSeg = path.split("/").filter((s) => s !== "");
    if (pSeg.length !== aSeg.length) return null;
    const params: Dict = {};
    for (let i = 0; i < pSeg.length; i += 1) {
      const p = pSeg[i] as string;
      const a = aSeg[i] as string;
      if (p.startsWith(":")) params[p.slice(1)] = a;
      else if (p !== a) return null;
    }
    return params;
  }
 
  private static parseQuery(raw: string): Dict {
    const query: Dict = {};
    for (const pair of raw.split("&")) {
      if (pair === "") continue;
      const eq = pair.indexOf("=");
      if (eq < 0) query[pair] = "";
      else query[pair.slice(0, eq)] = pair.slice(eq + 1);
    }
    return query;
  }
 
  dispatch(method: HttpMethod, url: string, body: unknown): { status: number; body: unknown } {
    const qi = url.indexOf("?");
    const path = qi < 0 ? url : url.slice(0, qi);
    const query = qi < 0 ? {} : Router.parseQuery(url.slice(qi + 1));
 
    for (const route of this.routes) {
      if (route.method !== method) continue;
      const params = Router.match(route.path, path);
      if (params === null) continue;
      try {
        return { status: route.status, body: route.handler({ params, query, body }) };
      } catch (e) {
        // 这一段就是全局异常过滤器干的事
        const status = e instanceof HttpError ? e.status : 500;
        const message = e instanceof Error ? e.message : "Internal server error";
        return { status, body: { statusCode: status, message } };
      }
    }
    return { status: 404, body: { statusCode: 404, message: "Cannot " + method + " " + path } };
  }
}
 
// ===== Controller：注意它只解析入参、调用逻辑、返回数据 =====
type Task = { readonly id: number; readonly title: string; readonly done: boolean };
 
class TasksController {
  private readonly rows = new Map<number, Task>();
  private nextId = 1;
 
  findAll(ctx: RequestCtx): readonly Task[] {
    const all = [...this.rows.values()];
    const done = ctx.query["done"];
    if (done === undefined) return all;
    return all.filter((t) => t.done === (done === "true"));
  }
 
  findOne(ctx: RequestCtx): Task {
    const id = this.parseId(ctx);
    const task = this.rows.get(id);
    if (task === undefined) throw new HttpError(404, "任务 " + id + " 不存在");
    return task;
  }
 
  create(ctx: RequestCtx): Task {
    const body = ctx.body;
    if (typeof body !== "object" || body === null || !("title" in body)) {
      throw new HttpError(400, "请求体缺少 title 字段");
    }
    const title = String((body as { title: unknown }).title);
    const task: Task = { id: this.nextId, title, done: false };
    this.nextId += 1;
    this.rows.set(task.id, task);
    return task;
  }
 
  remove(ctx: RequestCtx): null {
    const id = this.parseId(ctx);
    if (!this.rows.delete(id)) throw new HttpError(404, "任务 " + id + " 不存在");
    return null;
  }
 
  // 等价于 @Param("id", ParseIntPipe)
  private parseId(ctx: RequestCtx): number {
    const raw = ctx.params["id"] ?? "";
    const id = Number(raw);
    if (!Number.isInteger(id)) throw new HttpError(400, "id 必须是整数，收到 " + raw);
    return id;
  }
}
 
const controller = new TasksController();
const router = new Router();
 
router
  .add("GET", "/tasks", 200, (ctx) => controller.findAll(ctx))
  .add("GET", "/tasks/:id", 200, (ctx) => controller.findOne(ctx))
  .add("POST", "/tasks", 201, (ctx) => controller.create(ctx))
  .add("DELETE", "/tasks/:id", 204, (ctx) => controller.remove(ctx));
 
type Call = { readonly method: HttpMethod; readonly url: string; readonly body: unknown };
 
const calls: readonly Call[] = [
  { method: "POST", url: "/tasks", body: { title: "写 NestJS 章节" } },
  { method: "POST", url: "/tasks", body: { title: "接入 TypeORM" } },
  { method: "POST", url: "/tasks", body: { note: "忘了写 title" } },
  { method: "GET", url: "/tasks", body: null },
  { method: "GET", url: "/tasks/1", body: null },
  { method: "GET", url: "/tasks/99", body: null },
  { method: "GET", url: "/tasks/abc", body: null },
  { method: "GET", url: "/tasks?done=false", body: null },
  { method: "DELETE", url: "/tasks/2", body: null },
  { method: "PATCH", url: "/tasks/1", body: null },
];
 
for (const call of calls) {
  const res = router.dispatch(call.method, call.url, call.body);
  console.log(call.method + " " + call.url + "  ->  " + res.status + " " + JSON.stringify(res.body));
}

// src/tasks/dto/create-task.dto.ts
import {
  IsArray, IsInt, IsOptional, IsString, Max, Min, MaxLength, MinLength,
} from "class-validator";
import { Type } from "class-transformer";
 
export class CreateTaskDto {
  @IsString()
  @MinLength(1, { message: "标题不能为空" })
  @MaxLength(60)
  title!: string;
 
  @Type(() => Number)
  @IsInt()
  @Min(1)
  @Max(5)
  priority!: number;
 
  @IsOptional()
  @IsArray()
  @IsString({ each: true })
  tags?: string[];
}

// src/tasks/dto/update-task.dto.ts
import { PartialType } from "@nestjs/mapped-types";
import { CreateTaskDto } from "./create-task.dto";
 
export class UpdateTaskDto extends PartialType(CreateTaskDto) {}

// src/main.ts
import { NestFactory } from "@nestjs/core";
import { ValidationPipe } from "@nestjs/common";
import { AppModule } from "./app.module";
import { HttpExceptionFilter } from "./common/filters/http-exception.filter";
 
async function bootstrap(): Promise<void> {
  const app = await NestFactory.create(AppModule);
 
  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true,             // 剥离 DTO 未声明的字段
      forbidNonWhitelisted: true,  // 出现未声明字段直接 400
      transform: true,             // 把 plain object 转成 DTO 实例
      transformOptions: { enableImplicitConversion: true },
    }),
  );
  app.useGlobalFilters(new HttpExceptionFilter());
  app.enableShutdownHooks();
 
  await app.listen(Number(process.env.PORT ?? 3000));
}
void bootstrap();

type FieldError = {
  readonly field: string;
  readonly constraint: string;
  readonly message: string;
};
 
type Ok<T> = { readonly ok: true; readonly value: T };
type Fail = { readonly ok: false; readonly status: number; readonly errors: readonly FieldError[] };
type Validated<T> = Ok<T> | Fail;
 
// 一条约束 = class-validator 里的一个 @IsXxx 装饰器
type Check = {
  readonly constraint: string;
  readonly message: string;
  readonly test: (value: unknown) => boolean;
};
 
type FieldRule = {
  readonly field: string;
  readonly optional: boolean;
  readonly coerce: (raw: unknown) => unknown;   // 对应 @Type(() => Number)
  readonly checks: readonly Check[];
};
 
type Schema<T> = {
  readonly name: string;
  readonly rules: readonly FieldRule[];
  readonly guard: (candidate: unknown) => candidate is T;
};
 
type PipeOptions = { readonly whitelist: boolean; readonly transform: boolean };
 
// ---- 转换器 ----
const asIs = (raw: unknown): unknown => raw;
 
const toNumber = (raw: unknown): unknown => {
  if (typeof raw === "string" && raw.trim() !== "" && Number.isFinite(Number(raw))) {
    return Number(raw);
  }
  return raw;
};
 
const toStringArray = (raw: unknown): unknown => {
  if (typeof raw === "string") {
    return raw.split(",").map((s) => s.trim()).filter((s) => s !== "");
  }
  return raw;
};
 
// ---- 约束工厂 ----
function isString(): Check {
  return { constraint: "isString", message: "必须是字符串", test: (v) => typeof v === "string" };
}
function minLength(n: number): Check {
  return {
    constraint: "minLength",
    message: "长度不能少于 " + n,
    test: (v) => typeof v === "string" && v.length >= n,
  };
}
function maxLength(n: number): Check {
  return {
    constraint: "maxLength",
    message: "长度不能超过 " + n,
    test: (v) => typeof v === "string" && v.length <= n,
  };
}
function isInt(): Check {
  return {
    constraint: "isInt",
    message: "必须是整数",
    test: (v) => typeof v === "number" && Number.isInteger(v),
  };
}
function inRange(min: number, max: number): Check {
  return {
    constraint: "min/max",
    message: "必须在 " + min + " 到 " + max + " 之间",
    test: (v) => typeof v === "number" && v >= min && v <= max,
  };
}
function isStringArray(): Check {
  return {
    constraint: "isArray",
    message: "必须是字符串数组",
    test: (v) => Array.isArray(v) && v.every((x) => typeof x === "string"),
  };
}
 
class ValidationPipe<T> {
  constructor(
    private readonly schema: Schema<T>,
    private readonly options: PipeOptions,
  ) {}
 
  run(raw: unknown): Validated<T> {
    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
      return {
        ok: false,
        status: 400,
        errors: [{ field: "(body)", constraint: "isObject", message: "请求体必须是 JSON 对象" }],
      };
    }
 
    const input = raw as Record<string, unknown>;
    const errors: FieldError[] = [];
    const output: Record<string, unknown> = {};
 
    // 1) whitelist：只保留 schema 声明过的字段
    const known = new Set(this.schema.rules.map((r) => r.field));
    for (const key of Object.keys(input)) {
      if (known.has(key)) continue;
      if (this.options.whitelist) console.log("    · whitelist 剥离了未声明字段: " + key);
      else output[key] = input[key];
    }
 
    // 2) 逐字段：转换 -> 校验
    for (const rule of this.schema.rules) {
      const original = input[rule.field];
      if (original === undefined) {
        if (!rule.optional) {
          errors.push({ field: rule.field, constraint: "isDefined", message: "字段必填" });
        }
        continue;
      }
      const value = this.options.transform ? rule.coerce(original) : original;
      let passed = true;
      for (const check of rule.checks) {
        if (check.test(value)) continue;
        errors.push({ field: rule.field, constraint: check.constraint, message: check.message });
        passed = false;
      }
      if (passed) output[rule.field] = value;
    }
 
    if (errors.length > 0) return { ok: false, status: 400, errors };
 
    // 3) 类型守卫：unknown -> T 的唯一合法通道
    if (!this.schema.guard(output)) {
      return {
        ok: false,
        status: 500,
        errors: [{ field: "(body)", constraint: "guard", message: "规则与 DTO 类型不同步" }],
      };
    }
    return { ok: true, value: output };
  }
}
 
// ===== 对应真实项目里的 CreateTaskDto =====
type CreateTaskDto = {
  readonly title: string;
  readonly priority: number;
  readonly tags?: readonly string[];
};
 
function isCreateTaskDto(v: unknown): v is CreateTaskDto {
  if (typeof v !== "object" || v === null) return false;
  const o = v as Record<string, unknown>;
  if (typeof o["title"] !== "string") return false;
  if (typeof o["priority"] !== "number") return false;
  const tags = o["tags"];
  if (tags === undefined) return true;
  return Array.isArray(tags) && tags.every((x) => typeof x === "string");
}
 
const createTaskSchema: Schema<CreateTaskDto> = {
  name: "CreateTaskDto",
  rules: [
    { field: "title", optional: false, coerce: asIs, checks: [isString(), minLength(1), maxLength(60)] },
    { field: "priority", optional: false, coerce: toNumber, checks: [isInt(), inRange(1, 5)] },
    { field: "tags", optional: true, coerce: toStringArray, checks: [isStringArray()] },
  ],
  guard: isCreateTaskDto,
};
 
const pipe = new ValidationPipe(createTaskSchema, { whitelist: true, transform: true });
 
const payloads: readonly unknown[] = [
  { title: "把 CLI 内核搬上 HTTP", priority: "2", tags: "docs, nest" },
  { title: "", priority: 9 },
  { title: "偷偷提权", priority: 1, isAdmin: true },
  { priority: 3 },
  "not-an-object",
];
 
for (const payload of payloads) {
  console.log("POST /tasks  " + JSON.stringify(payload));
  const result = pipe.run(payload);
  if (result.ok) {
    // 这里 result.value 的类型已经是 CreateTaskDto，不是 unknown
    console.log("  201 通过 -> " + JSON.stringify(result.value));
  } else {
    console.log("  " + result.status + " 校验失败:");
    for (const e of result.errors) {
      console.log("    " + e.field + " [" + e.constraint + "] " + e.message);
    }
  }
}

// src/tasks/tasks.service.ts
import { Injectable, NotFoundException, ConflictException, Logger } from "@nestjs/common";
import { InjectRepository } from "@nestjs/typeorm";
import { Repository } from "typeorm";
import { Task } from "./entities/task.entity";
import { CreateTaskDto } from "./dto/create-task.dto";
import { UpdateTaskDto } from "./dto/update-task.dto";
import { QueryTaskDto } from "./dto/query-task.dto";
 
@Injectable()
export class TasksService {
  private readonly logger = new Logger(TasksService.name);
 
  constructor(
    @InjectRepository(Task)
    private readonly repo: Repository<Task>,
  ) {}
 
  async findAll(query: QueryTaskDto): Promise<Task[]> {
    const qb = this.repo.createQueryBuilder("task");
    if (query.done !== undefined) {
      qb.andWhere("task.done = :done", { done: query.done });
    }
    if (query.keyword !== undefined) {
      qb.andWhere("task.title LIKE :kw", { kw: "%" + query.keyword + "%" });
    }
    return qb.orderBy("task.priority", "DESC").take(query.limit ?? 20).getMany();
  }
 
  async findOne(id: number): Promise<Task> {
    const task = await this.repo.findOne({ where: { id } });
    if (task === null) {
      throw new NotFoundException("任务 " + id + " 不存在");
    }
    return task;
  }
 
  async create(dto: CreateTaskDto): Promise<Task> {
    const exists = await this.repo.findOne({ where: { title: dto.title } });
    if (exists !== null) {
      throw new ConflictException("已存在同名任务: " + dto.title);
    }
    const task = this.repo.create({ ...dto, done: false });
    const saved = await this.repo.save(task);
    this.logger.log("created task #" + saved.id);
    return saved;
  }
 
  async update(id: number, dto: UpdateTaskDto): Promise<Task> {
    const task = await this.findOne(id);
    Object.assign(task, dto);
    return this.repo.save(task);
  }
 
  async remove(id: number): Promise<void> {
    const result = await this.repo.delete(id);
    if (result.affected === 0) {
      throw new NotFoundException("任务 " + id + " 不存在");
    }
  }
}

// src/common/exceptions/business.exception.ts
import { HttpException, HttpStatus } from "@nestjs/common";
 
export class BusinessException extends HttpException {
  constructor(
    public readonly code: string,
    message: string,
    status: HttpStatus = HttpStatus.BAD_REQUEST,
  ) {
    super({ code, message }, status);
  }
}

// src/common/filters/http-exception.filter.ts
import {
  ArgumentsHost, Catch, ExceptionFilter, HttpException, HttpStatus, Logger,
} from "@nestjs/common";
import { Request, Response } from "express";
 
@Catch()
export class HttpExceptionFilter implements ExceptionFilter {
  private readonly logger = new Logger(HttpExceptionFilter.name);
 
  catch(exception: unknown, host: ArgumentsHost): void {
    const ctx = host.switchToHttp();
    const res = ctx.getResponse<Response>();
    const req = ctx.getRequest<Request>();
 
    const status =
      exception instanceof HttpException
        ? exception.getStatus()
        : HttpStatus.INTERNAL_SERVER_ERROR;
 
    const payload =
      exception instanceof HttpException
        ? exception.getResponse()
        : { message: "Internal server error" };
 
    if (status >= 500) {
      this.logger.error(req.method + " " + req.url, (exception as Error).stack);
    }
 
    res.status(status).json({
      statusCode: status,
      path: req.url,
      timestamp: new Date().toISOString(),
      error: payload,
    });
  }
}

请求 → 中间件 → 守卫 → 拦截器(前) → 管道 → 处理器
                              ↓
响应 ← 异常过滤器 ← 拦截器(后) ← ────┘

// src/common/guards/jwt-auth.guard.ts
import {
  CanActivate, ExecutionContext, Injectable, UnauthorizedException,
} from "@nestjs/common";
import { Reflector } from "@nestjs/core";
import { JwtService } from "@nestjs/jwt";
import { Request } from "express";
import { IS_PUBLIC_KEY } from "../decorators/public.decorator";
 
@Injectable()
export class JwtAuthGuard implements CanActivate {
  constructor(
    private readonly jwt: JwtService,
    private readonly reflector: Reflector,
  ) {}
 
  async canActivate(context: ExecutionContext): Promise<boolean> {
    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
      context.getHandler(),
      context.getClass(),
    ]);
    if (isPublic === true) return true;
 
    const req = context.switchToHttp().getRequest<Request>();
    const auth = req.headers.authorization ?? "";
    if (!auth.startsWith("Bearer ")) {
      throw new UnauthorizedException("缺少 Bearer token");
    }
    try {
      const payload = await this.jwt.verifyAsync<{ sub: number; role: string }>(auth.slice(7));
      Object.assign(req, { user: payload });
      return true;
    } catch {
      throw new UnauthorizedException("token 无效或已过期");
    }
  }
}

// src/common/decorators/public.decorator.ts
import { SetMetadata } from "@nestjs/common";
 
export const IS_PUBLIC_KEY = "isPublic";
export const Public = (): MethodDecorator & ClassDecorator => SetMetadata(IS_PUBLIC_KEY, true);

// src/common/interceptors/logging.interceptor.ts
import {
  CallHandler, ExecutionContext, Injectable, Logger, NestInterceptor,
} from "@nestjs/common";
import { Observable, tap } from "rxjs";
import { Request } from "express";
 
@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  private readonly logger = new Logger("HTTP");
 
  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
    const req = context.switchToHttp().getRequest<Request>();
    const started = Date.now();
    return next.handle().pipe(
      tap(() => {
        this.logger.log(req.method + " " + req.url + " " + (Date.now() - started) + "ms");
      }),
    );
  }
}

// src/common/interceptors/timeout.interceptor.ts
import {
  CallHandler, ExecutionContext, Injectable, NestInterceptor,
  RequestTimeoutException,
} from "@nestjs/common";
import { Observable, TimeoutError, catchError, throwError, timeout } from "rxjs";
 
@Injectable()
export class TimeoutInterceptor implements NestInterceptor {
  constructor(private readonly ms = 5000) {}
 
  intercept(_context: ExecutionContext, next: CallHandler): Observable<unknown> {
    return next.handle().pipe(
      timeout(this.ms),
      catchError((err: unknown) =>
        err instanceof TimeoutError
          ? throwError(() => new RequestTimeoutException())
          : throwError(() => err),
      ),
    );
  }
}

type Req = {
  readonly method: string;
  readonly url: string;
  readonly token: string | null;
};
type Res = { readonly status: number; readonly data: unknown };
 
type Handler<Q, R> = (req: Q) => Promise<R>;
type Next<R> = () => Promise<R>;
type Interceptor<Q, R> = (req: Q, next: Next<R>) => Promise<R>;
 
// 泛型 compose：Q 与 R 把请求/响应类型贯穿整条链
function compose<Q, R>(chain: readonly Interceptor<Q, R>[], handler: Handler<Q, R>): Handler<Q, R> {
  return chain.reduceRight<Handler<Q, R>>(
    (next, interceptor) => (req) => interceptor(req, () => next(req)),
    handler,
  );
}
 
class HttpError extends Error {
  constructor(public readonly status: number, message: string) {
    super(message);
    this.name = "HttpError";
  }
}
 
function delay(ms: number): Promise<void> {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve();
    }, ms);
  });
}
 
// 1) 异常过滤器：站在最外层，把任何异常翻译成响应
const exceptionFilter: Interceptor<Req, Res> = async (_req, next) => {
  try {
    return await next();
  } catch (e) {
    const status = e instanceof HttpError ? e.status : 500;
    const message = e instanceof Error ? e.message : String(e);
    console.log("  <- [filter]   捕获异常 " + status + " " + message);
    return { status, data: { statusCode: status, message } };
  }
};
 
// 2) 日志拦截器：前后都执行，典型的洋葱
const logging: Interceptor<Req, Res> = async (req, next) => {
  console.log("  -> [logging]  " + req.method + " " + req.url);
  const started = Date.now();
  const res = await next();
  const cost = Date.now() - started;
  console.log("  <- [logging]  " + res.status + " 用时 " + (cost < 100 ? "小于 100ms" : "超过 100ms"));
  return res;
};
 
// 3) 守卫：只有前置逻辑，不满足就直接抛
const authGuard: Interceptor<Req, Res> = async (req, next) => {
  console.log("  -> [guard]    校验 token");
  if (req.token !== "valid-token") throw new HttpError(401, "Unauthorized");
  return next();
};
 
// 4) 超时拦截器：用 Promise.race 给下游设上限
function timeoutAfter(ms: number): Interceptor<Req, Res> {
  return async (_req, next) => {
    let timer: ReturnType<typeof setTimeout> | null = null;
    const alarm = new Promise<never>((_resolve, reject) => {
      timer = setTimeout(() => {
        reject(new HttpError(504, "请求超过 " + ms + "ms 未完成"));
      }, ms);
    });
    try {
      return await Promise.race([next(), alarm]);
    } finally {
      if (timer !== null) clearTimeout(timer);
    }
  };
}
 
// 5) 响应包装：只有后置逻辑
const wrapResponse: Interceptor<Req, Res> = async (_req, next) => {
  const res = await next();
  return { status: res.status, data: { success: res.status < 400, result: res.data } };
};
 
// 处理器：真正的业务逻辑
const handler: Handler<Req, Res> = async (req) => {
  console.log("     [handler]  执行业务逻辑");
  if (req.url === "/tasks/slow") {
    await delay(200);
    return { status: 200, data: { note: "这个接口很慢" } };
  }
  if (req.url === "/tasks/boom") throw new Error("数据库连接断了");
  await delay(5);
  return { status: 200, data: { tasks: ["写文档", "写测试"] } };
};
 
const pipeline = compose(
  [exceptionFilter, logging, authGuard, timeoutAfter(80), wrapResponse],
  handler,
);
 
const requests: readonly Req[] = [
  { method: "GET", url: "/tasks", token: "valid-token" },
  { method: "GET", url: "/tasks", token: null },
  { method: "GET", url: "/tasks/slow", token: "valid-token" },
  { method: "GET", url: "/tasks/boom", token: "valid-token" },
];
 
for (const req of requests) {
  console.log("=== " + req.method + " " + req.url + "  token=" + (req.token ?? "(无)"));
  const res = await pipeline(req);
  console.log("最终响应 " + res.status + " " + JSON.stringify(res.data) + "\\n");
}
console.log("洋葱模型演示结束");

npm i @nestjs/typeorm typeorm pg

// src/app.module.ts
import { Module } from "@nestjs/common";
import { ConfigModule, ConfigService } from "@nestjs/config";
import { TypeOrmModule } from "@nestjs/typeorm";
import { TasksModule } from "./tasks/tasks.module";
import configuration from "./config/configuration";
 
@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true, load: [configuration] }),
    TypeOrmModule.forRootAsync({
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        type: "postgres" as const,
        url: config.getOrThrow<string>("database.url"),
        autoLoadEntities: true,
        synchronize: false,       // 生产环境必须 false
        migrationsRun: true,
        migrations: ["dist/migrations/*.js"],
      }),
    }),
    TasksModule,
  ],
})
export class AppModule {}

// src/tasks/entities/task.entity.ts
import {
  Column, CreateDateColumn, Entity, Index, PrimaryGeneratedColumn, UpdateDateColumn,
} from "typeorm";
 
@Entity("tasks")
export class Task {
  @PrimaryGeneratedColumn()
  id!: number;
 
  @Index({ unique: true })
  @Column({ type: "varchar", length: 60 })
  title!: string;
 
  @Column({ type: "boolean", default: false })
  done!: boolean;
 
  @Column({ type: "int", default: 1 })
  priority!: number;
 
  @Column({ type: "simple-array", default: "" })
  tags!: string[];
 
  @CreateDateColumn()
  createdAt!: Date;
 
  @UpdateDateColumn()
  updatedAt!: Date;
}

# package.json scripts
# "typeorm": "typeorm-ts-node-commonjs -d src/data-source.ts"
npm run typeorm migration:generate src/migrations/AddPriority
npm run typeorm migration:run

// src/config/configuration.ts
import { z } from "zod";
 
const schema = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
  PORT: z.coerce.number().int().positive().default(3000),
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(16),
});
 
export type AppConfig = {
  env: string;
  port: number;
  database: { url: string };
  jwt: { secret: string };
};
 
export default (): AppConfig => {
  const parsed = schema.safeParse(process.env);
  if (!parsed.success) {
    throw new Error("环境变量校验失败: " + JSON.stringify(parsed.error.flatten().fieldErrors));
  }
  const env = parsed.data;
  return {
    env: env.NODE_ENV,
    port: env.PORT,
    database: { url: env.DATABASE_URL },
    jwt: { secret: env.JWT_SECRET },
  };
};

// src/tasks/tasks.service.spec.ts
import { Test, TestingModule } from "@nestjs/testing";
import { getRepositoryToken } from "@nestjs/typeorm";
import { NotFoundException } from "@nestjs/common";
import { Repository } from "typeorm";
import { TasksService } from "./tasks.service";
import { Task } from "./entities/task.entity";
 
describe("TasksService", () => {
  let service: TasksService;
  let repo: jest.Mocked<Pick<Repository<Task>, "findOne" | "save" | "create" | "delete">>;
 
  beforeEach(async () => {
    repo = {
      findOne: jest.fn(),
      save: jest.fn(),
      create: jest.fn(),
      delete: jest.fn(),
    } as unknown as typeof repo;
 
    const moduleRef: TestingModule = await Test.createTestingModule({
      providers: [
        TasksService,
        { provide: getRepositoryToken(Task), useValue: repo },
      ],
    }).compile();
 
    service = moduleRef.get(TasksService);
  });
 
  it("findOne 找不到时抛 NotFoundException", async () => {
    repo.findOne.mockResolvedValue(null);
    await expect(service.findOne(42)).rejects.toBeInstanceOf(NotFoundException);
  });
 
  it("create 会写库并返回实体", async () => {
    repo.findOne.mockResolvedValue(null);
    repo.create.mockReturnValue({ id: 1, title: "写测试" } as Task);
    repo.save.mockResolvedValue({ id: 1, title: "写测试" } as Task);
 
    const task = await service.create({ title: "写测试", priority: 1 });
    expect(task.id).toBe(1);
    expect(repo.save).toHaveBeenCalledTimes(1);
  });
});

// test/tasks.e2e-spec.ts
import { INestApplication, ValidationPipe } from "@nestjs/common";
import { Test } from "@nestjs/testing";
import request from "supertest";
import { AppModule } from "../src/app.module";
 
describe("Tasks (e2e)", () => {
  let app: INestApplication;
 
  beforeAll(async () => {
    const moduleRef = await Test.createTestingModule({
      imports: [AppModule],
    }).compile();
 
    app = moduleRef.createNestApplication();
    app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));
    await app.init();
  });
 
  afterAll(async () => {
    await app.close();
  });
 
  it("POST /tasks 校验失败返回 400", () =>
    request(app.getHttpServer())
      .post("/tasks")
      .send({ title: "", priority: 99 })
      .expect(400));
 
  it("POST /tasks 成功返回 201", async () => {
    const res = await request(app.getHttpServer())
      .post("/tasks")
      .send({ title: "e2e 任务", priority: 3 })
      .expect(201);
    expect(res.body.id).toBeGreaterThan(0);
  });
});

// src/main.ts（片段）
import { DocumentBuilder, SwaggerModule } from "@nestjs/swagger";
 
const config = new DocumentBuilder()
  .setTitle("Tasks API")
  .setDescription("任务管理服务")
  .setVersion("1.0")
  .addBearerAuth()
  .build();
SwaggerModule.setup("docs", app, SwaggerModule.createDocument(app, config));

// src/health/health.controller.ts
import { Controller, Get } from "@nestjs/common";
import { HealthCheck, HealthCheckService, TypeOrmHealthIndicator } from "@nestjs/terminus";
import { Public } from "../common/decorators/public.decorator";
 
@Controller("health")
export class HealthController {
  constructor(
    private readonly health: HealthCheckService,
    private readonly db: TypeOrmHealthIndicator,
  ) {}
 
  @Public()
  @Get()
  @HealthCheck()
  check() {
    return this.health.check([() => this.db.pingCheck("database", { timeout: 1500 })]);
  }
}

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
 
FROM node:20-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force
COPY --from=builder /app/dist ./dist
EXPOSE 3000
CMD ["node", "dist/main.js"]