后端开发 on acye's blog

7.配置与部署-环境变量与Docker

Thu, 28 May 2026 01:00:00 +0000

上一篇：06 异步任务与判题队列 | 回到：00 序言

本篇学习入口

类型	内容
官方概念	Configuration：`ConfigModule` 读取环境变量；Modules：全局模块提供配置能力
小满知识点	环境变量、配置模块、连接数据库、Docker 部署
本项目代码入口	`src/app.module.ts`、`src/config`、`Dockerfile`、`docker-compose.yml`

配置与代码分离

数据库密码、Redis 地址不能写死在代码里 — 换环境（本地 / Docker / 生产）只改配置。

NestJS 用 @nestjs/config 读 .env：

`1`	`ConfigModule.forRoot({ isGlobal: true, envFilePath: '.env' })`

isGlobal: true — 任何模块都能注入 ConfigService 读环境变量。

这叫 12-Factor App 里的「配置存在环境中」。

知识点：配置模块把环境变量变成可注入的 ConfigService，业务代码不用硬编码密码、端口、外部服务地址。

前端类比：Vite 用 .env 和 import.meta.env 区分本地、测试、生产接口地址。

本项目落点：AppModule 全局注册 ConfigModule，数据库、Redis、Bull、Judge0 配置都从环境变量读取。

主要环境变量

变量	用途	docker-compose 示例值
`PORT`	服务端口	8080
`DB_HOST`	MySQL 主机	mysql
`DB_PORT`	MySQL 端口	3306
`DB_USERNAME`	数据库用户	root
`DB_PASSWORD`	数据库密码	123456
`DB_DATABASE`	库名	oj
`DB_POOL_SIZE`	连接池大小	20
`REDIS_HOST`	Redis 主机	redis
`REDIS_PORT`	Redis 端口	6379
`REDIS_PASSWORD`	Redis 密码	123456
`REDIS_DB`	Redis 库号	0
`JUDGE0_BASE_URL`	Judge0 地址	http://judge0-…:2358
`TOKEN_TTL`	Token 过期秒数	3600
`JUDGE_QUEUE_CONCURRENCY`	队列并发	5
`JUDGE_TESTPOINT_CONCURRENCY`	测试点并发	4
`JUDGE_POLL_INTERVAL_MS`	轮询间隔	500
`JUDGE_POLL_MAX_RETRIES`	轮询次数	20

本地开发 .env 示例：

PORT=8080
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=123456
DB_DATABASE=oj
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=123456
JUDGE0_BASE_URL=http://localhost:2358
TOKEN_TTL=3600

配置模块一览

flowchart TB
  Env[.env文件] --> CM[ConfigModule]
  CM --> DB[database.config.ts]
  CM --> RD[redis.config.ts]
  CM --> J0[judge0.config.ts]
  CM --> JQ[judge-queue.config.ts]
  DB --> TypeORM[TypeOrmModule]
  RD --> RedisMod[RedisModule]
  JQ --> BullMod[BullModule]

知识点：源码只描述“需要哪些配置”，具体值由运行环境提供。

前端类比：同一套前端构建产物可以部署到不同环境，只要 API 地址配置不同。

本项目落点：本地可以用 localhost，Docker 内部用服务名 mysql、redis，代码不需要改。

配置文件怎么读

本项目里有两层配置：

层级	位置	作用
环境值	`.env`、`docker-compose.yml` 的 `environment`	放不同环境会变的值，比如端口、密码、主机名
配置转换	`src/config/*.ts`	把字符串环境变量整理成框架模块需要的配置对象

flowchart LR
  EnvValue[环境变量] --> ConfigFile[src_config配置文件]
  ConfigFile --> ModuleOption[模块配置对象]
  ModuleOption --> Runtime[运行时连接]

知识点：.env 只负责提供原始值，配置文件负责把这些值变成 TypeORM、Redis、Bull、Judge0 能直接使用的选项。

前端类比：.env 里写 VITE_API_BASE_URL，真正发请求时会在 request 封装里拼成完整 axios 配置。

本项目落点：database.config.ts、redis.config.ts、judge-queue.config.ts 都是在做“把环境变量翻译成模块配置”。

配置文件不要写业务逻辑，只做三件事：

读取环境变量
设置默认值
组装第三方模块需要的配置对象

文件	读取内容	输出给谁	重点
`database.config.ts`	`DB_HOST`、`DB_PORT`、账号、密码、库名	`TypeOrmModule`	注册 Entity、连接池、关闭 `synchronize`
`redis.config.ts`	`REDIS_HOST`、`REDIS_PORT`、密码、库号	`RedisModule`	拼 Redis URL
`judge0.config.ts`	`JUDGE0_BASE_URL`	`JudgeProcessor` / 判题逻辑	保存 Judge0 地址，维护语言 ID 映射
`judge-queue.config.ts`	`JUDGE_*` 并发和轮询参数	`BullModule` / `JudgeProcessor`	队列名、重试策略、并发限制

新增配置时按这个判断：

需求	放哪里
本地、Docker、生产环境值不同	`.env` / compose environment
第三方模块连接参数	`src/config/*.ts`
业务规则、业务开关	对应业务模块的 Service 或常量文件
密码、密钥、外部服务地址	只放环境变量，不写死进源码

database.config.ts

MySQL 连接 + 注册 7 个 Entity + synchronize: false。

redis.config.ts

拼 Redis URL：redis://:password@host:port/db

judge0.config.ts

语言名映射 Judge0 language_id：

const RAW_LANGUAGE_MAP = {
  C: 50, 'C++': 54, Java: 62, Python: 71, JavaScript: 63, Go: 60, ...
};

export function getLanguageId(name: string): number | undefined {
  return LANGUAGE_NAME_TO_ID[name.toLowerCase()];
}

judge-queue.config.ts

队列名、并发数、重试策略，部分读 process.env。

docker-compose 三容器

文件：backend/oj-nest/docker-compose.yml

flowchart LR
  subgraph compose [docker-compose]
    MySQL[mysql_3306]
    Redis[redis_6379]
    Nest[oj-nest_8080]
  end
  Nest --> MySQL
  Nest --> Redis
  Nest -.->|需外部网络| J0[Judge0]

服务	镜像	端口	说明
mysql	mysql:8.0	3306	库名 oj，健康检查
redis	redis:7-alpine	6379	requirepass 123456
oj-nest	本地 build	8080	依赖 mysql healthy + redis started

注意：Judge0 不在 compose 里。compose 写死 JUDGE0_BASE_URL=http://judge0-v1131-extra-server-1:2358，需你本地另有 Judge0 容器且网络互通。

知识点：Docker Compose 提供的是运行环境编排，容器之间通过服务名互相访问。

前端类比：前端 dev server、mock server、后端 API 可以同时跑，但它们是不同进程；Compose 把这些进程声明成服务。

本项目落点：oj-nest 容器通过 mysql:3306 访问数据库，通过 redis:6379 访问 Redis，对外暴露 8080 给前端调用。

Dockerfile 多阶段构建

文件：backend/oj-nest/Dockerfile

FROM node:22-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=builder /app/dist ./dist
COPY .env .env
EXPOSE 8080
CMD ["node", "dist/main"]

builder 阶段 — 装全量依赖、编译 TS → dist/
运行阶段 — 只装 production 依赖 + 拷贝 dist，镜像更小

类比前端：build 出 dist 静态资源，生产只 serve 产物。

知识点：运行环境和源码开发环境要分离。生产容器只需要编译产物和生产依赖。

前端类比：上线不需要把 src 和 dev server 都放到服务器，只需要构建后的静态产物。

本项目落点：Nest 生产启动命令是 node dist/main，不是 npm run start:dev。

本地开发启动步骤

方式 A：Docker 全家桶（不含 Judge0）

cd backend/oj-nest
docker compose up -d mysql redis
# 导入数据库
mysql -h 127.0.0.1 -u root -p123456 oj < database/本地构建数据库.sql
# 本地跑 Nest（方便调试）
npm install
npm run start:dev

方式 B：compose 连 Nest 一起起

1
2

docker compose up -d
# 仍需先导入 SQL 到 mysql 容器

Judge0

单独部署 Judge0（官方 docker 或 RapidAPI），确保 JUDGE0_BASE_URL 可达。不启 Judge0 时：登录、题目 CRUD 正常，提交代码会一直 Pending。

npm scripts

命令	作用
`npm run start:dev`	开发热重载
`npm run build`	编译到 dist
`npm run start:prod`	`node dist/main`
`npm run test:e2e`	E2E 测试

API 路由速查

前缀	模块	需登录
`POST /api/user/login`	User	否
`POST /api/user/register`	User	否
`GET /api/user/status`	User	带 token
`api/testQuestion/*`	Question 管理	是
`api/user/testQuestion/*`	Question 用户	是
`api/comment/*`	Comment	是

系列回顾

flowchart TB
  A[00_全局地图] --> B[01_main启动]
  B --> C[02_模块DI]
  C --> D[03_请求生命周期]
  D --> E[04_数据库ORM]
  E --> F[05_Token鉴权]
  F --> G[06_异步判题]
  G --> H[07_配置部署]

你从「会调接口的前端」到「能读能改 Nest 后端」，按这 8 篇走完，应该能：

找到任意 API 对应的 Controller → Service → Entity
加一个新接口（DTO + Controller + Service）
理解判题为什么异步、结果写哪张表
用 docker-compose 起 MySQL/Redis 并配 .env

6.异步任务与消息队列-Bull判题系统

Wed, 27 May 2026 01:00:00 +0000

上一篇：02 模块与依赖注入 | 下一篇：04 数据库与 ORM

本篇学习入口

类型	内容
官方概念	Controllers：路由和参数装饰器；Pipes、Guards、Interceptors、Exception filters：请求生命周期
小满知识点	Controller、DTO、Pipe、Guard、Interceptor、Filter 的请求顺序
本项目代码入口	`src/modules/user/user.controller.ts`、`src/modules/user/user.service.ts`、`src/common/guards`、`src/common/interceptors`、`src/common/filters`

案例：用户登录

前端发：

POST /api/user/login
Content-Type: application/json

{ "username": "alice", "password": "123456" }

后端返回：

{
  "code": 1,
  "message": "success",
  "data": {
    "message": "登录成功",
    "id": "uuid-xxx",
    "username": "alice",
    "token": "a1b2c3...",
    "roles": "user"
  }
}

全链路时序

sequenceDiagram
  participant FE as 前端
  participant Pipe as ValidationPipe
  participant Ctrl as UserController
  participant Svc as UserService
  participant DB as MySQL
  participant RD as Redis
  participant Int as ResponseInterceptor

  FE->>Pipe: POST /api/user/login
  Pipe->>Pipe: LoginDto 校验
  Pipe->>Ctrl: 通过
  Ctrl->>Svc: login(dto)
  Svc->>DB: findOne username
  DB-->>Svc: user 记录
  Svc->>Svc: MD5 比对密码
  Svc->>RD: SET token username EX 3600
  Svc-->>Ctrl: 返回 user+token
  Ctrl->>Int: 包装响应
  Int-->>FE: code=1 data=...

Controller 接路由

文件：backend/oj-nest/src/modules/user/user.controller.ts

@Controller('api/user')
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Post('login')
  login(@Body() dto: LoginDto) {
    return this.userService.login(dto);
  }
}

@Post('login') 匹配 POST + /api/user/login
@Body() dto: LoginDto — body 自动映射到 DTO 类

知识点：Controller 是请求进入业务代码的第一层，它把 URL、HTTP 方法和方法参数绑定起来。

前端类比：Vue Router 负责匹配页面；Nest Controller 负责匹配接口。

本项目落点：UserController.login 只负责接收 LoginDto 并调用 UserService.login。

DTO 校验

文件：backend/oj-nest/src/modules/user/dto/user.dto.ts

export class LoginDto {
  @IsString()
  @IsNotEmpty()
  username: string;

  @IsString()
  @IsNotEmpty()
  password: string;
}

全局 ValidationPipe 会检查：

username 必须是字符串且非空
多余字段会被 whitelist 剥掉

校验失败自动返回 400，进不了 Service。

类比 Element Plus / Ant Design 表单 rules，但在服务端强制执行 — 前端可以绕过，后端不能信前端。

知识点：DTO 定义接口输入结构，Pipe 按 DTO 上的校验装饰器执行校验。

前端类比：前端表单 rules 提升体验，后端 DTO + Pipe 保证接口边界可靠。

本项目落点：全局 ValidationPipe 会处理 LoginDto、RegisterDto、SubmitTestQuestionDto 等输入对象。

Service 执行业务

文件：backend/oj-nest/src/modules/user/user.service.ts

async login(dto: LoginDto) {
  const user = await this.userRepo.findOne({ where: { username: dto.username } });
  if (!user) throw new NotFoundException('用户不存在');

  const md5Pass = CryptoJS.MD5(dto.password).toString();
  if (user.password !== md5Pass) throw new UnauthorizedException('密码错误');

  const token = CryptoJS.MD5(dto.username + dto.password).toString();
  await this.redis.set(token, user.username, 'EX', this.tokenTtl);

  return { message: '登录成功', id: user.id, username: user.username, token, roles: user.roles };
}

流程：查用户 → 验密码 → 生成 token 写 Redis → 返回。

throw new NotFoundException(...) 会被全局 Filter 捕获，转成 { code: 404, message: '...', data: null }。

知识点：Service 是业务层，不关心 HTTP 路由怎么匹配，只关心业务规则和数据读写。

前端类比：把页面事件里的请求、状态计算、错误处理抽到 store action 或 composable。

本项目落点：登录流程里的查用户、比对密码、写 Redis token 都在 UserService.login。

参数装饰器一览

装饰器	来源	示例
`@Body()`	POST JSON body	`login(@Body() dto)`
`@Query('id')`	URL `?id=xxx`	`getById(@Query('id') id)`
`@Headers('authorization')`	请求头	`getUserStatus(@Headers('authorization') auth)`
`@Param('id')`	路径 `/user/:id`	本项目较少用

Query 参数默认是字符串，ValidationPipe 的 transform: true 可配合 DTO 里的 @Type(() => Number) 做类型转换。

ResponseInterceptor 包装

文件：backend/oj-nest/src/common/interceptors/response.interceptor.ts

intercept(_ctx: ExecutionContext, next: CallHandler<T>): Observable<any> {
  return next.handle().pipe(
    map((data) => ({ code: 1, message: 'success', data: data ?? null })),
  );
}

Service 返回 { message: '登录成功', token: '...' }，拦截器包一层：

`1`	`{ "code": 1, "message": "success", "data": { "message": "登录成功", "token": "..." } }`

前端 axios 可以统一：

1
2

if (res.data.code === 1) { /* 成功 */ }
else { /* 业务/HTTP 错误 */ }

知识点：Interceptor 处理成功返回链路，可以统一改写响应结构、记录耗时、做缓存等。

前端类比：axios response interceptor 统一拆包；Nest response interceptor 统一装包。

本项目落点：ResponseInterceptor 固定输出 { code, message, data }，前端只需要按一种结构取数据。

异常 Filter

文件：backend/oj-nest/src/common/filters/http-exception.filter.ts

@Catch()
export class AllExceptionsFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    if (exception instanceof HttpException) {
      const status = exception.getStatus();
      const message = ...;
      response.status(status).json({ code: status, message, data: null });
    } else {
      response.status(500).json({ code: 500, message: '服务器内部错误', data: null });
    }
  }
}

异常类型	HTTP 状态	前端看到的 code
NotFoundException	404	404
UnauthorizedException	401	401
BadRequestException	400	400
未捕获错误	500	500

知识点：Filter 处理异常链路，和 Interceptor 的成功包装分开，避免每个 Controller 自己写 try/catch。

前端类比：axios error handler 统一弹错误提示；Nest Filter 统一返回错误 JSON。

本项目落点：AllExceptionsFilter 让 NotFoundException、UnauthorizedException 等异常都变成前端可读的 { code, message, data: null }。

LoggingInterceptor

文件：backend/oj-nest/src/common/interceptors/logging.interceptor.ts

每个请求打一行日志：

`1`	`[HTTP] POST /api/user/login 200 45ms [127.0.0.1]`

排错时先看这行 — 比在前端 console 猜快。

带 Guard 的请求

需要登录的接口（如提交代码）多一步：

flowchart LR
  Req[请求] --> Guard[TokenGuard]
  Guard -->|token有效| Pipe[ValidationPipe]
  Guard -->|无效| Err401[401]
  Pipe --> Ctrl[Controller]

TokenGuard 检查 Redis 里 token 是否存在，详见 05 认证与会话。

知识点：Guard 运行在业务方法前，适合做登录、权限、角色判断。

前端类比：router.beforeEach 能拦页面跳转；Guard 能拦接口请求。

本项目落点：TokenGuard 会在提交题目、评论等接口前检查 Redis 中 token 是否存在。

前端对接要点

BaseURL — http://localhost:8080
成功 — code === 1，业务数据在 data
失败 — code !== 1 或 HTTP 4xx/5xx，message 可读
鉴权 — Header 带 Authorization: Bearer <token> 或 token: <token>
登录接口无 Guard — login/register 不需要 token

本篇小结

一次请求 = 路由匹配 → 可选 Guard → Pipe 校验 → Controller → Service → Interceptor 包装 → JSON。

异常走 Filter 旁路，不经过 Interceptor 的成功包装。

Controller 薄、Service 厚 — 这是 NestJS 社区惯例，也是你写后端时要养成的习惯。

5.认证与会话-Token和Redis

Tue, 26 May 2026 01:00:00 +0000

上一篇：04 数据库与 ORM | 下一篇：06 异步任务与判题队列

本篇学习入口

类型	内容
官方概念	Controllers：Header 参数读取；Guards：请求前鉴权
小满知识点	HTTP 无状态、Guard、Redis 会话、依赖注入
本项目代码入口	`src/modules/user/user.service.ts`、`src/common/guards/token.guard.ts`、`src/common/decorators/current-token.decorator.ts`、`src/config/redis.config.ts`

HTTP 是无状态的

每个请求互相独立，服务器默认「不认识」上一个请求是谁。

前端登录后要知道「我是谁」，常见方案：

方案	原理	特点
Cookie Session	服务端存 session，浏览器带 cookie id	传统，跨域麻烦
JWT	token 自带签名信息，服务端只验签	无状态，难主动失效
Redis Token	token 作 key 存 Redis，查 key 知用户	本项目方案，可 TTL、可 logout 删 key

知识点：HTTP 无状态意味着后端不会天然记住“刚才登录的是谁”，每次请求都必须带身份凭证。

前端类比：刷新页面后内存状态丢失，需要从 localStorage 或接口重新恢复登录态。

本项目落点：前端保存 token，后续接口把 token 放到 Header；后端用 Redis 判断 token 是否有效。

本项目登录流程

sequenceDiagram
  participant FE as 前端
  participant Svc as UserService
  participant DB as MySQL
  participant RD as Redis

  FE->>Svc: login username password
  Svc->>DB: 查用户
  Svc->>Svc: MD5 密码比对
  Svc->>Svc: token = MD5 username+password
  Svc->>RD: SET token username EX 3600
  Svc-->>FE: 返回 token

  Note over FE,RD: 后续请求带 token

  FE->>Svc: 带 Authorization Bearer token
  Svc->>RD: EXISTS token
  RD-->>Svc: 1 存在
  Svc-->>FE: 业务数据

核心代码：

1
2

const token = CryptoJS.MD5(dto.username + dto.password).toString();
await this.redis.set(token, user.username, 'EX', this.tokenTtl);

key = token 字符串
value = username
EX 3600 = 3600 秒后自动过期（TOKEN_TTL 环境变量）

知识点：Redis Token 是有状态会话，服务端保存 token 和用户的对应关系，因此可以主动删除、设置过期时间。

前端类比：localStorage 只是在浏览器保存凭证；真正的登录态是否有效，由服务端 Redis 决定。

本项目落点：UserService.login 生成 token 后执行 redis.set(token, username, 'EX', this.tokenTtl)。

TokenGuard：路由守卫

文件：backend/oj-nest/src/common/guards/token.guard.ts

@Injectable()
export class TokenGuard implements CanActivate {
  constructor(@InjectRedis() private readonly redis: Redis) {}

  async canActivate(context: ExecutionContext): Promise<boolean> {
    const request = context.switchToHttp().getRequest<Request>();
    const token = this.extractToken(request);
    if (!token) throw new UnauthorizedException('未携带Token，请先登录');

    const exists = await this.redis.exists(token);
    if (!exists) throw new UnauthorizedException('Token无效或已过期，请重新登录');

    request['token'] = token;
    return true;
  }

  private extractToken(request: Request): string | null {
    const authHeader = request.headers['authorization'];
    if (authHeader?.startsWith('Bearer ')) return authHeader.substring(7).trim();
    const tokenHeader = request.headers['token'] as string;
    if (tokenHeader) return tokenHeader.trim();
    return null;
  }
}

类比 Vue Router：

router.beforeEach((to, from, next) => {
  if (!token) next('/login');
  else next();
});

用法 — 挂在 Controller 或单个方法上：

1
2
3

@UseGuards(TokenGuard)
@Controller('api/user/testQuestion')
export class UserQuestionController { ... }

知识点：Guard 的返回值决定请求能不能继续进入 Controller；抛出异常会直接走全局 Filter。

前端类比：Vue Router 守卫决定能不能进入某个页面；Nest Guard 决定能不能进入某个接口。

本项目落点：TokenGuard 支持 Authorization: Bearer <token> 和自定义 token Header，两种前端写法都能识别。

哪些接口要 Guard

路由	Guard	说明
`POST /api/user/login`	无	登录本身不需要 token
`POST /api/user/register`	无	注册
`GET /api/user/status`	无（自行解析 header）	用 authorization 查状态
`api/testQuestion/*`	有	管理员题目
`api/user/testQuestion/*`	有	用户题目/提交
`api/comment/*`	有	评论

User 模块部分接口没用 Guard，而是在方法里手动从 header 取 token — 风格不统一，读代码时注意。

登出：删 Redis key

async logout(token: string) {
  await this.redis.del(token);
  return { message: '已退出登录' };
}

token 删掉后，Guard 里 exists 返回 0，后续请求 401。

知识点：服务端会话的优势是可控，登出、改密、封禁都可以通过删除 Redis key 立即生效。

前端类比：只删 localStorage 只能让当前浏览器退出；删 Redis key 才能让这个 token 对所有客户端失效。

本项目落点：logout 和 changePassword 都会 redis.del(token)，让旧 token 失效。

改密码：强制重新登录

async changePassword(token: string, dto: ChangePasswordDto) {
  const username = await this.redis.get(token);
  // ... 验证旧密码、更新 DB ...
  await this.redis.del(token);
  return { message: '密码修改成功，请重新登录' };
}

密码变了，旧 token 对应的 MD5(username+password) 也对不上了，删 key 最安全。

CurrentToken 装饰器

Guard 通过后 token 挂在 request['token']：

export const CurrentToken = createParamDecorator(
  (_data: unknown, ctx: ExecutionContext): string => {
    return ctx.switchToHttp().getRequest()['token'];
  },
);

Controller 可写 @CurrentToken() token: string，避免重复解析 header（本项目部分 Controller 仍手动解析，可统一改进）。

前端怎么带 Token

两种方式任选（Guard 都支持）：

// 方式 1：标准 Bearer
axios.defaults.headers.common['Authorization'] = `Bearer ${token}`;

// 方式 2：自定义 header
axios.defaults.headers.common['token'] = token;

Redis 在本项目的两个用途

flowchart TB
  Redis[(Redis)]
  Redis --> Auth[Token会话_EXISTS_GET_DEL]
  Redis --> Bull[Bull判题队列]

同一 Redis 实例，不同 key 空间 — 别和队列数据混为一谈。

配置：backend/oj-nest/src/config/redis.config.ts

export const redisConfig = (cs: ConfigService): RedisModuleOptions => ({
  type: 'single',
  url: `redis://:${cs.get('REDIS_PASSWORD')}@${cs.get('REDIS_HOST')}:${cs.get('REDIS_PORT')}/${cs.get('DB') ?? 0}`,
});

安全提醒（了解即可）

当前实现适合学习，生产需加强：

密码 MD5 — 应换 bcrypt/argon2 + salt
token = MD5(username+password) — 改密后 token 理论上会变，但逻辑耦合；更常见用随机 UUID 或 JWT
**CORS origin: *** — 生产应限制域名
roles 未在 Guard 校验 — 管理员接口和普通用户共用 TokenGuard，未区分 role

这些不影响理解架构，是后续迭代方向。

本篇小结

环节	实现
登录发 token	`redis.set(token, username, 'EX', ttl)`
鉴权	`TokenGuard` → `redis.exists(token)`
登出	`redis.del(token)`
过期	Redis TTL 自动删 key

下一篇进入 OJ 核心：提交代码后为什么不阻塞等待，而是丢进队列。

4.数据库与 ORM：TypeORM 实战

Mon, 25 May 2026 01:00:00 +0000

上一篇：03 一个请求的完整生命周期 | 下一篇：05 认证与会话

本篇学习入口

类型	内容
官方概念	Providers：Repository 作为可注入依赖进入 Service；Modules：数据库能力由模块注册
小满知识点	NestJS 连接数据库、ORM、Entity、Repository
本项目代码入口	`src/config/database.config.ts`、`src/entities`、`src/modules/question/question.module.ts`、`src/modules/question/question.service.ts`

为什么需要数据库

前端 state 刷新就没了。后端要把用户、题目、提交记录持久化 — 关机重启数据还在。

本项目用 MySQL 8 关系型数据库 + TypeORM 做 ORM（Object-Relational Mapping）。

ORM 是什么

把数据库表映射成 TypeScript 类，用对象操作代替写 SQL：

数据库	TypeORM
表 `questions`	类 `Questions`
列 `title`	属性 `title`
行	类实例
`SELECT * WHERE id=?`	`repo.findOne({ where: { id } })`

知识点：ORM 把表、列、查询封装成对象 API，但底层仍然是 SQL 和数据库连接。

前端类比：像用数组对象操作列表数据，但这些操作最终会变成数据库查询。

本项目落点：QuestionService 大量使用 Repository 完成题目分页、提交记录创建、判题结果更新。

Entity：表 ↔ 类

文件：backend/oj-nest/src/entities/questions.entity.ts

@Entity('questions')
export class Questions {
  @PrimaryColumn({ type: 'varchar', length: 36 })
  id: string;

  @Column({ type: 'varchar' })
  title: string;

  @Column({ name: 'limited_time', type: 'bigint', nullable: true })
  limitedTime: number;

  @CreateDateColumn({ name: 'create_time' })
  createTime: Date;

  @UpdateDateColumn({ name: 'update_time' })
  updateTime: Date;
}

常用装饰器：

装饰器	含义
`@Entity('表名')`	绑定表
`@PrimaryColumn`	主键（本项目多用 UUID 字符串）
`@Column`	普通列，`name` 映射蛇形命名
`@CreateDateColumn`	插入时自动填时间
`@UpdateDateColumn`	更新时自动改时间

知识点：Entity 是数据库表结构在 TypeScript 里的映射，不等于业务返回 DTO。

前端类比：Entity 更像后端的数据模型；DTO 更像接口入参或出参类型。

本项目落点：Questions 对应 questions 表，limitedTime 通过 name: 'limited_time' 映射数据库蛇形列名。

七张表关系

erDiagram
  User ||--o{ UserSubmissionCode : submits
  User ||--o{ UserSubmissionRecord : has
  User ||--o{ Comment : writes
  User ||--o{ CommentLike : likes
  Questions ||--o{ TestPoint : contains
  Questions ||--o{ UserSubmissionCode : receives
  Questions ||--o{ UserSubmissionRecord : tracks
  UserSubmissionCode ||--o{ UserSubmissionRecord : generates
  Comment ||--o{ Comment : replies
  Comment ||--o{ CommentLike : liked_by

  User {
    varchar id PK
    varchar username
    varchar password
    varchar roles
  }
  Questions {
    varchar id PK
    varchar title
    bigint limited_time
  }
  TestPoint {
    int id PK
    varchar question_id FK
    text input
    text output
  }
  UserSubmissionRecord {
    varchar id PK
    varchar result
    varchar language
  }

Schema 定义在 backend/oj-nest/database/本地构建数据库.sql，以 SQL 为准，不用 ORM 自动建表。

数据库配置

文件：backend/oj-nest/src/config/database.config.ts

export const databaseConfig = (cs: ConfigService): TypeOrmModuleOptions => ({
  type: 'mysql',
  host: cs.get('DB_HOST'),
  port: cs.get<number>('DB_PORT'),
  username: cs.get('DB_USERNAME'),
  password: cs.get('DB_PASSWORD'),
  database: cs.get('DB_DATABASE'),
  entities: [User, Questions, TestPoint, ...],
  synchronize: false,
  extra: { connectionLimit: cs.get<number>('DB_POOL_SIZE') ?? 20 },
});

关键：

synchronize: false — 生产必关。不让 TypeORM 自动改表结构，避免误删数据
connectionLimit: 20 — 连接池，复用 DB 连接，避免每个请求新建连接

知识点：synchronize 会让 ORM 根据 Entity 自动同步表结构，学习阶段方便，生产环境风险很高。

前端类比：像工具自动改你的线上配置文件，一旦推断错就会影响真实数据。

本项目落点：数据库结构以 database/本地构建数据库.sql 为准，TypeORM 只负责映射和查询，所以 synchronize: false。

TypeOrmModule.forFeature

`1`	`TypeOrmModule.forFeature([Questions, TestPoint, UserSubmissionCode, UserSubmissionRecord])`

forFeature 把指定 Entity 对应的 Repository 注册到当前模块。注册后，Service 才能这样注入：

`1`	`@InjectRepository(Questions) private readonly questionRepo: Repository<Questions>`

知识点：Repository 是操作某张表的入口，属于可以被 Nest 注入的依赖。

前端类比：在一个业务模块里显式引入要用的 store，然后只操作这个模块需要的数据。

本项目落点：QuestionModule 注册四个 Entity，QuestionService 因此能同时读题目、测试点、提交代码和提交记录。

Repository 常用 API

Service 里注入：

`1`	`@InjectRepository(Questions) private readonly questionRepo: Repository<Questions>`

查询

// 单条
await this.questionRepo.findOne({ where: { id } });

// 列表 + 分页 + 总数
const [list, total] = await this.questionRepo.findAndCount({
  where: keyword ? { title: Like(`%${keyword}%`) } : {},
  skip: (pageNum - 1) * size,
  take: size,
  order: { createTime: 'DESC' },
});

// 计数
await this.questionRepo.count({ where: { questionId: id } });

新增

1
2

const question = this.questionRepo.create({ id: uuidv4(), title: dto.title, ... });
await this.questionRepo.save(question);

create 只是内存对象，save 才真正 INSERT。

更新

Object.assign(question, { title: dto.title });
await this.questionRepo.save(question);

// 或按 id 局部更新
await this.recordRepo.update(recordIds[i], { result: 'AC', time: '12' });

删除

1
2

await this.testPointRepo.delete({ questionId: id });
await this.questionRepo.delete({ id });

业务示例：题目分页

文件：question.service.ts

async getByPage(pageNum: number, size: number, keyword: string) {
  const [list, total] = await this.questionRepo.findAndCount({
    where: keyword ? { title: Like(`%${keyword}%`) } : {},
    skip: (pageNum - 1) * size,
    take: size,
    order: { createTime: 'DESC' },
  });
  return { list, total, pageNum, size };
}

前端分页组件需要的 list + total 一次查齐。

业务示例：评论点赞原子 +1

文件：comment.service.ts

await this.commentRepo
  .createQueryBuilder()
  .update(Comment)
  .set({ likeCount: () => 'like_count + 1' })
  .where('id = :id', { id: dto.commentId })
  .execute();

为什么不用 comment.likeCount++ 再 save？

并发下两个请求同时读 likeCount=5，都写成 6，丢一次点赞。SQL 层 like_count + 1 是原子的。

取消点赞用 GREATEST(like_count - 1, 0) 防止负数。

业务示例：嵌套评论

const [rootList, total] = await this.commentRepo.findAndCount({
  where: { questionId, parentCommentId: IsNull() },
  skip: (pageNum - 1) * pageSize,
  take: pageSize,
  order: { createTime: 'DESC' },
});

// 每条根评论再查 childComments
const children = await this.commentRepo.find({
  where: { parentCommentId: c.id },
  order: { createTime: 'ASC' },
});

两层结构：根评论 parentCommentId IS NULL，回复挂在根评论 id 下。

提交记录模型

一次代码提交产生：

一条 user_submission_code — 代码快照
N 条 user_submission_record — 每个测试点一条，初始 result: 'Pending'

const records = testPoints.map((tp, i) =>
  this.submissionRecordRepo.create({
    id: recordIds[i],
    userId: dto.userId,
    questionId: dto.id,
    codeId: codeRecord.id,
    language: dto.language,
    result: 'Pending',
  }),
);
await this.submissionRecordRepo.save(records);

判题完成后 Worker 逐条 update 为 AC/WA/TLE/RE。

题目 ID 用 UUID

questions.id 是 varchar(36) UUID，不是自增 int。迁移脚本见 database/fix-questions-id-to-varchar36.sql。

好处：分布式生成不冲突；前端可直接用字符串 id。

本篇小结

操作	TypeORM 写法
定义表结构	Entity 装饰器
注入	`@InjectRepository(Entity)`
查	`findOne` / `find` / `findAndCount`
增	`create` + `save`
改	`save` / `update`
删	`delete`
复杂 SQL	`createQueryBuilder()`

下一篇讲 Token 怎么存 Redis、Guard 怎么拦请求。

3.一个请求的完整生命周期

Sun, 24 May 2026 01:00:00 +0000

上一篇：02 模块与依赖注入 | 下一篇：04 数据库与 ORM

本篇学习入口

类型	内容
官方概念	Controllers：路由和参数装饰器；Pipes、Guards、Interceptors、Exception filters：请求生命周期
小满知识点	Controller、DTO、Pipe、Guard、Interceptor、Filter 的请求顺序
本项目代码入口	`src/modules/user/user.controller.ts`、`src/modules/user/user.service.ts`、`src/common/guards`、`src/common/interceptors`、`src/common/filters`

案例：用户登录

前端发：

POST /api/user/login
Content-Type: application/json

{ "username": "alice", "password": "123456" }

后端返回：

{
  "code": 1,
  "message": "success",
  "data": {
    "message": "登录成功",
    "id": "uuid-xxx",
    "username": "alice",
    "token": "a1b2c3...",
    "roles": "user"
  }
}

全链路时序

sequenceDiagram
  participant FE as 前端
  participant Pipe as ValidationPipe
  participant Ctrl as UserController
  participant Svc as UserService
  participant DB as MySQL
  participant RD as Redis
  participant Int as ResponseInterceptor

  FE->>Pipe: POST /api/user/login
  Pipe->>Pipe: LoginDto 校验
  Pipe->>Ctrl: 通过
  Ctrl->>Svc: login(dto)
  Svc->>DB: findOne username
  DB-->>Svc: user 记录
  Svc->>Svc: MD5 比对密码
  Svc->>RD: SET token username EX 3600
  Svc-->>Ctrl: 返回 user+token
  Ctrl->>Int: 包装响应
  Int-->>FE: code=1 data=...

Controller 接路由

文件：backend/oj-nest/src/modules/user/user.controller.ts

@Controller('api/user')
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Post('login')
  login(@Body() dto: LoginDto) {
    return this.userService.login(dto);
  }
}

@Post('login') 匹配 POST + /api/user/login
@Body() dto: LoginDto — body 自动映射到 DTO 类

知识点：Controller 是请求进入业务代码的第一层，它把 URL、HTTP 方法和方法参数绑定起来。

前端类比：Vue Router 负责匹配页面；Nest Controller 负责匹配接口。

本项目落点：UserController.login 只负责接收 LoginDto 并调用 UserService.login。

DTO 校验

文件：backend/oj-nest/src/modules/user/dto/user.dto.ts

export class LoginDto {
  @IsString()
  @IsNotEmpty()
  username: string;

  @IsString()
  @IsNotEmpty()
  password: string;
}

全局 ValidationPipe 会检查：

username 必须是字符串且非空
多余字段会被 whitelist 剥掉

校验失败自动返回 400，进不了 Service。

类比 Element Plus / Ant Design 表单 rules，但在服务端强制执行 — 前端可以绕过，后端不能信前端。

知识点：DTO 定义接口输入结构，Pipe 按 DTO 上的校验装饰器执行校验。

前端类比：前端表单 rules 提升体验，后端 DTO + Pipe 保证接口边界可靠。

本项目落点：全局 ValidationPipe 会处理 LoginDto、RegisterDto、SubmitTestQuestionDto 等输入对象。

Service 执行业务

文件：backend/oj-nest/src/modules/user/user.service.ts

async login(dto: LoginDto) {
  const user = await this.userRepo.findOne({ where: { username: dto.username } });
  if (!user) throw new NotFoundException('用户不存在');

  const md5Pass = CryptoJS.MD5(dto.password).toString();
  if (user.password !== md5Pass) throw new UnauthorizedException('密码错误');

  const token = CryptoJS.MD5(dto.username + dto.password).toString();
  await this.redis.set(token, user.username, 'EX', this.tokenTtl);

  return { message: '登录成功', id: user.id, username: user.username, token, roles: user.roles };
}

流程：查用户 → 验密码 → 生成 token 写 Redis → 返回。

throw new NotFoundException(...) 会被全局 Filter 捕获，转成 { code: 404, message: '...', data: null }。

知识点：Service 是业务层，不关心 HTTP 路由怎么匹配，只关心业务规则和数据读写。

前端类比：把页面事件里的请求、状态计算、错误处理抽到 store action 或 composable。

本项目落点：登录流程里的查用户、比对密码、写 Redis token 都在 UserService.login。

参数装饰器一览

装饰器	来源	示例
`@Body()`	POST JSON body	`login(@Body() dto)`
`@Query('id')`	URL `?id=xxx`	`getById(@Query('id') id)`
`@Headers('authorization')`	请求头	`getUserStatus(@Headers('authorization') auth)`
`@Param('id')`	路径 `/user/:id`	本项目较少用

Query 参数默认是字符串，ValidationPipe 的 transform: true 可配合 DTO 里的 @Type(() => Number) 做类型转换。

ResponseInterceptor 包装

文件：backend/oj-nest/src/common/interceptors/response.interceptor.ts

intercept(_ctx: ExecutionContext, next: CallHandler<T>): Observable<any> {
  return next.handle().pipe(
    map((data) => ({ code: 1, message: 'success', data: data ?? null })),
  );
}

Service 返回 { message: '登录成功', token: '...' }，拦截器包一层：

`1`	`{ "code": 1, "message": "success", "data": { "message": "登录成功", "token": "..." } }`

前端 axios 可以统一：

1
2

if (res.data.code === 1) { /* 成功 */ }
else { /* 业务/HTTP 错误 */ }

知识点：Interceptor 处理成功返回链路，可以统一改写响应结构、记录耗时、做缓存等。

前端类比：axios response interceptor 统一拆包；Nest response interceptor 统一装包。

本项目落点：ResponseInterceptor 固定输出 { code, message, data }，前端只需要按一种结构取数据。

异常 Filter

文件：backend/oj-nest/src/common/filters/http-exception.filter.ts

@Catch()
export class AllExceptionsFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    if (exception instanceof HttpException) {
      const status = exception.getStatus();
      const message = ...;
      response.status(status).json({ code: status, message, data: null });
    } else {
      response.status(500).json({ code: 500, message: '服务器内部错误', data: null });
    }
  }
}

异常类型	HTTP 状态	前端看到的 code
NotFoundException	404	404
UnauthorizedException	401	401
BadRequestException	400	400
未捕获错误	500	500

知识点：Filter 处理异常链路，和 Interceptor 的成功包装分开，避免每个 Controller 自己写 try/catch。

前端类比：axios error handler 统一弹错误提示；Nest Filter 统一返回错误 JSON。

本项目落点：AllExceptionsFilter 让 NotFoundException、UnauthorizedException 等异常都变成前端可读的 { code, message, data: null }。

LoggingInterceptor

文件：backend/oj-nest/src/common/interceptors/logging.interceptor.ts

每个请求打一行日志：

`1`	`[HTTP] POST /api/user/login 200 45ms [127.0.0.1]`

排错时先看这行 — 比在前端 console 猜快。

带 Guard 的请求

需要登录的接口（如提交代码）多一步：

flowchart LR
  Req[请求] --> Guard[TokenGuard]
  Guard -->|token有效| Pipe[ValidationPipe]
  Guard -->|无效| Err401[401]
  Pipe --> Ctrl[Controller]

TokenGuard 检查 Redis 里 token 是否存在，详见 05 认证与会话。

知识点：Guard 运行在业务方法前，适合做登录、权限、角色判断。

前端类比：router.beforeEach 能拦页面跳转；Guard 能拦接口请求。

本项目落点：TokenGuard 会在提交题目、评论等接口前检查 Redis 中 token 是否存在。

前端对接要点

BaseURL — http://localhost:8080
成功 — code === 1，业务数据在 data
失败 — code !== 1 或 HTTP 4xx/5xx，message 可读
鉴权 — Header 带 Authorization: Bearer <token> 或 token: <token>
登录接口无 Guard — login/register 不需要 token

本篇小结

一次请求 = 路由匹配 → 可选 Guard → Pipe 校验 → Controller → Service → Interceptor 包装 → JSON。

异常走 Filter 旁路，不经过 Interceptor 的成功包装。

Controller 薄、Service 厚 — 这是 NestJS 社区惯例，也是你写后端时要养成的习惯。

2.模块与依赖注入：NestJS 的心智模型

Sat, 23 May 2026 02:00:00 +0000

上一篇：01 从 main.ts 看服务如何启动 | 下一篇：03 一个请求的完整生命周期

本篇学习入口

类型	内容
官方概念	Modules、Providers：模块组织依赖，Provider 被容器创建和注入
小满知识点	IOC、DI、Provider、Module 的 `imports/providers/controllers`
本项目代码入口	`backend/oj-nest/src/app.module.ts`、`src/modules/question/question.module.ts`、`src/modules/question/question.service.ts`

四件套

NestJS 业务代码围绕四个角色组织：

flowchart TB
  Mod[Module模块] --> Ctrl[Controller控制器]
  Mod --> Svc[Service服务]
  Mod --> Prov[Provider提供者]
  Ctrl -->|调用| Svc
  Svc -->|注入| Repo[Repository等]

角色	职责	前端类比
Module	把相关功能打包、声明依赖	Vue 子组件 + `defineOptions`
Controller	定义 HTTP 路由，接收请求	Vue Router 的 route + 页面只负责接参
Service	业务逻辑、调数据库/Redis	composable / pinia action
Provider	可被注入的类（Service 也是 Provider）	可复用的逻辑单元

知识点：IOC 是“对象由框架容器管理”，DI 是“依赖由容器注入进来”。在 Nest 里，Service、Repository、Queue 这类对象通常都交给容器管理。

前端类比：组件里直接 import composable 是手动拿依赖；Nest 通过 constructor 声明依赖，由框架传入实例。

本项目落点：QuestionService 不自己创建 Repository 和 Queue，而是在构造函数里声明，由 QuestionModule 配好后自动注入。

以 QuestionModule 为例

文件：backend/oj-nest/src/modules/question/question.module.ts

@Module({
  imports: [
    TypeOrmModule.forFeature([Questions, TestPoint, UserSubmissionCode, UserSubmissionRecord]),
    BullModule.registerQueue(judgeQueueRegister()),
  ],
  controllers: [AdminQuestionController, UserQuestionController],
  providers: [QuestionService],
})
export class QuestionModule {}

解读：

imports — 这个模块需要的外部能力（数据库表、Bull 队列）
controllers — 对外暴露的 HTTP 接口（管理员 + 用户两套路由）
providers — 内部业务逻辑类，Nest 容器会实例化并管理

知识点：Module 是依赖边界。imports 让当前模块获得外部能力，controllers 注册路由入口，providers 注册可注入对象。

前端类比：一个业务模块同时声明自己要用哪些 store、有哪些页面入口、有哪些可复用逻辑。

本项目落点：QuestionModule 声明了题目相关 Entity、判题队列、管理员 Controller、用户 Controller 和 QuestionService。

Controller：路由层

文件：backend/oj-nest/src/modules/question/user-question.controller.ts

@UseGuards(TokenGuard)
@Controller('api/user/testQuestion')
export class UserQuestionController {
  constructor(private readonly questionService: QuestionService) {}

  @Get('getTestQuestionById')
  getById(@Query('id') id: string) {
    return this.questionService.getById(id);
  }

  @Post('submitTestQuestion')
  submit(@Body() dto: SubmitTestQuestionDto) {
    return this.questionService.submitTestQuestion(dto);
  }
}

@Controller('api/user/testQuestion') — 路由前缀
@Get('getTestQuestionById') — 完整路径 GET /api/user/testQuestion/getTestQuestionById
@Query('id') — 取 URL 查询参数 ?id=xxx
@Body() — 取 POST JSON body
@UseGuards(TokenGuard) — 整个 Controller 都要登录

Controller 不写业务逻辑，只做三件事：接参、调 Service、返回 Promise。

知识点：Controller 负责把 HTTP 世界转换成函数调用，例如从 query、body、header 取参数。

前端类比：页面组件不应该塞满请求和业务细节，而是把复杂逻辑交给 composable 或 store。

本项目落点：UserQuestionController 只接收题目查询和提交请求，真正的题目读取、提交记录保存、队列投递都在 QuestionService。

Service：业务层

文件：backend/oj-nest/src/modules/question/question.service.ts

@Injectable()
export class QuestionService {
  constructor(
    @InjectRepository(Questions) private readonly questionRepo: Repository<Questions>,
    @InjectRepository(TestPoint) private readonly testPointRepo: Repository<TestPoint>,
    @InjectQueue('judge') private readonly judgeQueue: Queue,
  ) {}

  async getById(id: string) {
    const q = await this.questionRepo.findOne({ where: { id } });
    if (!q) throw new NotFoundException('题目不存在');
    return q;
  }
}

@Injectable() — 告诉 Nest「这个类可以被注入」
构造函数里声明依赖 — Nest 自动帮你 new 好传进来

知识点：Provider 是 Nest 容器能管理的对象，@Injectable() 是最常见的 Provider 声明方式。

前端类比：Service 像一个可复用业务模块，但它的依赖不是自己 import 后 new，而是由容器注入。

本项目落点：QuestionService 同时依赖多个 Repository 和 Bull Queue，依赖关系清楚写在 constructor 里。

依赖注入（DI）原理

前端常见写法：

1
2

// 手动 new，耦合紧
const service = new QuestionService(repo, queue);

NestJS 写法：

1
2

constructor(private readonly questionService: QuestionService) {}
// Nest 容器：QuestionModule 注册了 QuestionService → 自动注入

flowchart LR
  Nest[Nest容器] -->|实例化| QS[QuestionService]
  Nest -->|注入| QC[UserQuestionController]
  QC -->|constructor| QS

好处：

不用自己 new — 生命周期由框架管
单例默认 — 同一 Module 内 Service 共享一个实例
易测试 — 测试时可 mock 注入的依赖
模块边界清晰 — imports 声明「我用谁」

知识点：DI 的核心不是“少写 new”，而是让依赖关系显式、可替换、由框架统一管理生命周期。

前端类比：把全局单例散落在各处 import 会越来越难替换；DI 把依赖集中在模块和构造函数里。

本项目落点：Redis、TypeORM Repository、Bull Queue 都通过模块注册后注入，业务类不用关心底层连接怎么创建。

项目模块划分

flowchart TB
  App[AppModule] --> User[UserModule]
  App --> Question[QuestionModule]
  App --> Comment[CommentModule]
  App --> Judge[JudgeModule]

  Question -->|投递任务| Judge
  Judge -->|消费队列| J0[Judge0]

模块	Controller	Service	特殊
UserModule	user.controller	user.service	Redis 存 token
QuestionModule	admin + user 两个 controller	question.service	注册 Bull 队列
CommentModule	comment.controller	comment.service	嵌套评论
JudgeModule	无	judge.processor	纯后台 Worker

JudgeModule 没有 Controller — 它不对外提供 HTTP，只消费 Redis 里的 Bull 队列任务。

TypeOrmModule.forFeature

`1`	`TypeOrmModule.forFeature([Questions, TestPoint, ...])`

在 Module 里注册「这个模块要用哪些表」，之后 Service 里才能 @InjectRepository(Questions)。

类比：在组件里 import 某个 store，才能 useXxxStore()。

知识点：forFeature 是 TypeORM 和 Nest 模块系统的连接点，它把指定 Entity 的 Repository 注册到当前模块。

前端类比：只在当前业务域里引入需要的 store，避免所有模块都拿到所有状态。

本项目落点：QuestionModule 注册题目、测试点、提交代码、提交记录四类 Entity，所以 QuestionService 能注入这些 Repository。

两个 Controller 共用一个 Service

QuestionModule 有：

AdminQuestionController → api/testQuestion — 增删改
UserQuestionController → api/user/testQuestion — 查 + 提交

两者注入同一个 QuestionService，逻辑复用、路由分离。类似 admin 路由和普通用户路由共用一套 API 层。

自定义装饰器

文件：backend/oj-nest/src/common/decorators/current-token.decorator.ts

export const CurrentToken = createParamDecorator(
  (_data: unknown, ctx: ExecutionContext): string => {
    const request = ctx.switchToHttp().getRequest();
    return request['token'] as string;
  },
);

Guard 校验通过后把 token 挂到 request['token']，Controller 用 @CurrentToken() 直接取 — 不用每个方法重复解析 header。

本篇小结

你要写的	放哪里	装饰器
路由	Controller	`@Controller` `@Get` `@Post`
业务	Service	`@Injectable()`
打包	Module	`@Module({ imports, controllers, providers })`
鉴权	Guard 挂 Controller	`@UseGuards(TokenGuard)`
取参	Controller 方法参数	`@Body` `@Query` `@Headers`

下一篇跟踪一个真实请求：从 axios 发 login 到拿到 JSON 的全链路。

1.从 main.ts 看一个后端服务如何启动

Fri, 22 May 2026 01:00:00 +0000

上一篇：00 序言 | 下一篇：02 模块与依赖注入

本篇学习入口

类型	内容
官方概念	First steps：`NestFactory` 创建应用，`app.listen` 监听端口；Pipes、Exception filters、Interceptors：全局管线
小满知识点	NestJS 介绍、项目入口、应用启动流程
本项目代码入口	`backend/oj-nest/src/main.ts`、`backend/oj-nest/src/app.module.ts`、`src/common/filters`、`src/common/interceptors`

前端 vs 后端：运行方式

	前端 (Vite dev)	后端 (NestJS)
启动命令	`npm run dev`	`npm run start:dev`
进程	开发服务器 + 浏览器	一个 Node 进程一直跑
触发	用户操作页面	HTTP 请求打进来
端口	5173（举例）	8080

后端不是「有人访问才启动」，而是启动后一直等着请求。

main.ts 做了什么

文件路径：backend/oj-nest/src/main.ts

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.enableCors({ origin: '*' });
  app.useGlobalPipes(new ValidationPipe({ transform: true, whitelist: true }));
  app.useGlobalFilters(new AllExceptionsFilter());
  app.useGlobalInterceptors(new LoggingInterceptor(), new ResponseInterceptor());
  const port = process.env.PORT ?? 8080;
  await app.listen(port);
}
bootstrap();

逐步拆解：

NestFactory.create(AppModule)

创建 Nest 应用实例，加载根模块 AppModule。类比 Vue 的 createApp(App) —— 从这里开始组装整个应用。

知识点：NestFactory 是 Nest 应用的启动工厂，默认创建基于 Express 的 HTTP 应用，也可以切换 Fastify 等 HTTP adapter。

前端类比：createApp(App) 只创建前端应用实例；NestFactory.create(AppModule) 创建的是一个长期监听端口的服务端应用实例。

本项目落点：main.ts 把 AppModule 作为根模块传入，后续所有 Controller、Service、数据库、Redis、队列都从这里被装配进应用。

enableCors

允许跨域。前端 localhost:5173 调后端 localhost:8080 属于跨域，不加 CORS 浏览器会拦。

origin: '*' 表示允许任意来源（生产环境应收紧）。

知识点：CORS 是浏览器安全策略，不是后端业务鉴权。后端允许跨域后，浏览器才会放行前端页面发出的跨源请求。

前端类比：本地 Vite 代理可以绕开跨域；生产环境通常由后端 CORS 或网关统一处理。

本项目落点：app.enableCors({ origin: '*' }) 让前端开发环境可以直接请求 8080 端口。

useGlobalPipes(ValidationPipe)

管道（Pipe）：请求进 Controller 之前，对入参做转换和校验。

transform: true — 把 query 字符串 "1" 转成数字 1
whitelist: true — 去掉 DTO 里没声明的字段，防注入

类比：前端表单提交前的 rules 校验，但在服务端强制执行。

知识点：Pipe 运行在 Controller 方法参数绑定阶段，适合做 DTO 校验、类型转换、参数清洗。

前端类比：前端 rules 是用户体验；后端 Pipe 是安全边界，因为请求可以绕过页面直接打接口。

本项目落点：登录、注册、提交题目等 DTO 都会先过全局 ValidationPipe，不合法参数不会进入 Service。

useGlobalFilters(AllExceptionsFilter)

过滤器（Filter）：任何地方抛异常，统一 catch 成 JSON 返回。

成功和失败格式不同，前端可以统一处理：

// 成功
{ "code": 1, "message": "success", "data": { ... } }

// 失败
{ "code": 401, "message": "Token无效或已过期", "data": null }

useGlobalInterceptors

拦截器（Interceptor）：包裹 Controller 返回值，做日志、格式包装。

LoggingInterceptor — 打日志：GET /api/user/status 200 12ms
ResponseInterceptor — 把返回值包成 { code: 1, message: 'success', data }

类比 axios 的 request/response interceptor。

知识点：Interceptor 可以在 Controller 执行前后插入逻辑；Filter 专门处理异常分支。

前端类比：axios interceptor 统一处理请求和响应；Nest Interceptor 统一包装服务端返回值。

本项目落点：LoggingInterceptor 记录请求耗时，ResponseInterceptor 把成功结果包装成统一 JSON，AllExceptionsFilter 把异常包装成统一错误 JSON。

app.listen(8080)

开始监听端口。此后每个 HTTP 请求都会走 Nest 的路由分发。

知识点：listen 之后 Node 进程不会退出，而是进入事件循环，持续等待新请求。

前端类比：Vite dev server 也会常驻监听端口；区别是 Nest 监听的是业务 API 请求。

本项目落点：服务启动后输出 Server running on http://localhost:8080，前端所有 API 都打到这个进程。

请求经过的全局管线

flowchart LR
  Req[HTTP请求] --> CORS[CORS]
  CORS --> Guard[Guard可选]
  Guard --> Pipe[ValidationPipe]
  Pipe --> Ctrl[Controller]
  Ctrl --> Svc[Service]
  Svc --> Ctrl
  Ctrl --> LogInt[LoggingInterceptor]
  LogInt --> RespInt[ResponseInterceptor]
  RespInt --> Res[JSON响应]

  Ctrl -.->|抛异常| Filter[AllExceptionsFilter]
  Filter --> ErrRes[错误JSON]

顺序要点：

Pipe 在 Controller 之前 — 先校验参数
Interceptor 在 Controller 之后 — 包装返回值
Filter 捕获 整个链路 的异常

Guard（如 TokenGuard）不是全局的，在 Controller 上用 @UseGuards(TokenGuard) 按需加。

AppModule：根模块

main.ts 只负责「壳」，业务模块在 app.module.ts 注册：

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true, envFilePath: '.env' }),
    TypeOrmModule.forRootAsync({ ... }),   // MySQL
    RedisModule.forRootAsync({ ... }),      // Redis
    BullModule.forRootAsync({ ... }),       // 消息队列
    UserModule,
    QuestionModule,
    CommentModule,
    JudgeModule,
  ],
})
export class AppModule {}

类比 Vue 根组件 import 子组件 + 注册 pinia/vue-router。

本地启动

cd backend/oj-nest
npm install
npm run start:dev   # 热重载开发
# 或
npm run start:prod  # node dist/main

看到 Server running on http://localhost:8080 即成功。

本篇小结

概念	作用	文件
bootstrap	启动入口	`main.ts`
AppModule	模块组装	`app.module.ts`
ValidationPipe	入参校验	全局
AllExceptionsFilter	统一错误格式	`http-exception.filter.ts`
ResponseInterceptor	统一成功格式	`response.interceptor.ts`
LoggingInterceptor	请求日志	`logging.interceptor.ts`

下一篇进入 NestJS 核心：Module、Controller、Service 和依赖注入。

前端如何快进后端

Thu, 21 May 2026 01:00:00 +0000

本系列基于 Campus-OJ 项目的真实后端代码 backend/oj-nest，用前端熟悉的概念帮你建立服务端开发心智模型。项目代码

讲什么

oj-nest 是一个 NestJS 11 写的在线判题（OJ）后端。本文档不是单纯讲项目代码，而是把这个项目当成练习场，帮有 Vue / TypeScript 基础的前端开发者补齐后端核心能力：

用户注册 / 登录 / 会话
题目 CRUD、测试点管理
代码提交与异步判题
题目评论与点赞

技术栈：NestJS + TypeORM + MySQL + Redis + Bull 队列 + Judge0

为什么本项目选 NestJS

NestJS 对前端开发者友好，原因很直接：

NestJS 特性	对前端开发者的价值	本项目对应
TypeScript 优先	不需要从动态类型切换到全新语言	DTO、Entity、Service 都是 TS 类
装饰器语法	路由、校验、注入都能声明式表达	`@Controller`、`@Post`、`@Injectable`
模块化	像拆 Vue 模块一样拆业务边界	`UserModule`、`QuestionModule`、`JudgeModule`
Controller / Service 分层	路由接参和业务逻辑分开	Controller 薄，Service 厚
IOC / DI	依赖由框架创建和注入	Repository、Redis、Queue 自动注入
生态集成	数据库、缓存、队列都有成熟接法	TypeORM、ioredis、Bull

Nest 官方文档把核心模型拆成 First steps、Controllers、Providers、Modules：main.ts 用 NestFactory 创建应用并监听请求，Controller 处理 HTTP 请求，Provider / Service 承载复杂逻辑，Module 组织依赖关系。后面的 01 到 07 会按这个顺序落到项目代码里。

阅读本文档前推荐先看什么

资料	建议阅读内容	用途
Nest 官方文档 First steps	`NestFactory`、应用启动	知道后端进程怎么跑起来
Nest 官方文档 Controllers	路由、参数装饰器	知道请求怎么进 Controller
Nest 官方文档 Providers	Service、依赖注入	知道业务类怎么被创建
Nest 官方文档 Modules	`imports/providers/controllers`	知道模块怎么组织
小满 Nest.js 专栏	NestJS 介绍、IOC/DI、连接数据库	中文预习，先建立直觉

推荐顺序：先用小满专栏做中文预习，再用官方文档校准概念，最后回到本项目看真实代码。

前端进阶全栈路线

flowchart LR
  A[会调接口] --> B[理解HTTP生命周期]
  B --> C[写Controller]
  C --> D[写Service]
  D --> E[连接MySQL_Redis_队列]
  E --> F[配置部署]

这 8 篇文档对应的目标是：

会调接口：知道前端请求在后端落到哪个 Controller
理解 HTTP 生命周期：知道 Guard、Pipe、Interceptor、Filter 各在什么位置
写 Controller：能新增一个路由并正确接收参数
写 Service：能把业务逻辑放到可注入的服务类里
连数据库 / Redis / 队列：能读写持久化数据，处理异步任务
部署：能用环境变量和 Docker 把服务跑起来

阅读顺序

序号	文章	你会学到
00	本篇	全局地图、前后端概念对照
01	从 main.ts 看服务如何启动	进程常驻、全局中间件管线
02	模块与依赖注入	Module / Controller / Service
03	一个请求的完整生命周期	DTO 校验、拦截器、异常处理
04	数据库与 ORM	Entity、Repository、分页
05	认证与会话	Token、Guard、Redis
06	异步任务与判题队列	Bull、Judge0、并发控制
07	配置与部署	.env、docker-compose

建议按顺序读。每篇独立成文，但后面的概念会引用前面的。

全局架构

flowchart TB
  subgraph client [客户端]
    FE[Frontend_Vue]
  end

  subgraph ojNest [oj-nest_8080]
    Ctrl[Controllers]
    Svc[Services]
    Worker[JudgeProcessor]
    Ctrl --> Svc
    Svc --> Worker
  end

  subgraph storage [存储层]
    MySQL[(MySQL)]
    Redis[(Redis)]
  end

  subgraph external [外部服务]
    J0[Judge0_2358]
  end

  FE -->|HTTP_REST| Ctrl
  Svc --> MySQL
  Svc -->|Token会话| Redis
  Svc -->|Bull队列| Redis
  Worker -->|提交与轮询| J0
  Worker -->|写回AC_WA_TLE_RE| MySQL

前端概念 ↔ 后端概念

前端你熟悉的	后端对应（NestJS）	在本项目里
Vue 根组件 `App.vue`	根模块 `AppModule`	注册 DB、Redis、业务模块
路由 `router`	Controller + 装饰器 `@Get/@Post`	`user.controller.ts`
composable / store 逻辑	Service `@Injectable()`	`user.service.ts`
axios 请求拦截器	Nest Interceptor	`ResponseInterceptor`
axios 响应错误处理	Exception Filter	`AllExceptionsFilter`
表单校验 rules	DTO + class-validator	`LoginDto`
路由守卫 beforeEach	Guard	`TokenGuard`
localStorage 存 token	Redis 存 token	登录时 `redis.set`
组件 props 类型	DTO 类型定义	`SubmitTestQuestionDto`
npm run dev 热更新	进程常驻 `app.listen`	8080 端口一直监听
Web Worker 干重活	Bull Queue + Processor	判题异步执行

目录结构速览

backend/oj-nest/
├── src/
│   ├── main.ts              # 入口：启动 + 全局配置
│   ├── app.module.ts        # 根模块：组装一切
│   ├── config/              # DB / Redis / Judge0 / 队列配置
│   ├── entities/            # 数据库表 ↔ TypeScript 类
│   ├── modules/
│   │   ├── user/            # 用户
│   │   ├── question/        # 题目 + 提交
│   │   ├── comment/         # 评论
│   │   └── judge/           # 判题 Worker（无 HTTP 接口）
│   └── common/              # Guard、拦截器、工具函数
├── database/                # 建表 SQL
└── docker-compose.yml       # MySQL + Redis + oj-nest

和前端的根本区别

前端：浏览器里跑，用户打开页面才执行，关 tab 进程就没了。

后端：Node 进程 7×24 常驻，监听端口等请求进来。一次请求 = 一次完整的「接收 → 处理 → 返回」流水线。

下一篇从 main.ts 开始，看这条流水线是怎么搭起来的。

后端开发 on acye's blog

7.配置与部署-环境变量与Docker

本篇学习入口

配置与代码分离

主要环境变量

配置模块一览

配置文件怎么读

database.config.ts

redis.config.ts

judge0.config.ts

judge-queue.config.ts

docker-compose 三容器

Dockerfile 多阶段构建

本地开发启动步骤

方式 A：Docker 全家桶（不含 Judge0）

方式 B：compose 连 Nest 一起起

Judge0

npm scripts

API 路由速查

系列回顾

推荐阅读的源码顺序

6.异步任务与消息队列-Bull判题系统

本篇学习入口

案例：用户登录

全链路时序

Controller 接路由

DTO 校验

Service 执行业务

参数装饰器一览

ResponseInterceptor 包装

异常 Filter

LoggingInterceptor

带 Guard 的请求

前端对接要点

本篇小结

5.认证与会话-Token和Redis

本篇学习入口

HTTP 是无状态的

本项目登录流程

TokenGuard：路由守卫

哪些接口要 Guard

登出：删 Redis key

改密码：强制重新登录

CurrentToken 装饰器

前端怎么带 Token

Redis 在本项目的两个用途

安全提醒（了解即可）

本篇小结

4.数据库与 ORM：TypeORM 实战

本篇学习入口

为什么需要数据库

ORM 是什么

Entity：表 ↔ 类

七张表关系

数据库配置

TypeOrmModule.forFeature

Repository 常用 API

查询

新增

更新

删除

业务示例：题目分页

业务示例：评论点赞原子 +1

业务示例：嵌套评论

提交记录模型

题目 ID 用 UUID

本篇小结

3.一个请求的完整生命周期

本篇学习入口

案例：用户登录

全链路时序

Controller 接路由

DTO 校验

Service 执行业务

参数装饰器一览

ResponseInterceptor 包装

异常 Filter

LoggingInterceptor

带 Guard 的请求

前端对接要点