一、TypeScript 简介​

什么是 TypeScript？​

TypeScript 是 JavaScript 的超集，核心是为代码增加 静态类型。它能在你运行之前就发现很多类型错误，从而提升代码可靠性与可维护性。

为什么需要 TypeScript？​

• 提高开发时的提示与可发现性（IDE 体验更好）
• 更早暴露类型相关 bug
• 更易重构和维护大型工程

二、环境与安装​

安装 TypeScript​

在项目目录中初始化：

mkdir my-ts-app
cd my-ts-app
npm init -y

安装 TypeScript：

npm i -D typescript
npx tsc --version

初始化 tsconfig.json​

npx tsc --init

tsconfig.json 用于配置编译选项（如 target、module、是否开启严格模式等）。

三、类型系统入门​

基本类型​

let name: string = 'Alice'
let age: number = 18
let isOk: boolean = true
let nothing: null = null
let undef: undefined = undefined

let anyValue: any = 123
let unknownValue: unknown = 'text'

其中：

• any：不做类型约束（慎用）
• unknown：未知类型，使用前需要判断

联合类型与类型收窄​

function formatId(id: number | string) {
  if (typeof id === 'number') return `#${id.toFixed(0)}`
  return `#${id}`
}

四、接口与类型别名​

接口（interface）​

interface User {
  id: string
  name: string
  email?: string
}

类型别名（type）​

type Point = {
  x: number
  y: number
}

它们都能描述对象结构，实际项目中可以按团队习惯选择使用。

五、泛型与高级类型​

泛型函数​

function wrap<T>(value: T) {
  return { value }
}

const res = wrap(123) // T = number

工具类型（内置）​

常见工具类型：

type PartialUser = Partial<User>
type ReadonlyUser = Readonly<User>
type PickUser = Pick<User, 'id' | 'name'>
type RecordMap = Record<string, number>

六、类与模块​

类（class）​

class Person {
  constructor(public name: string) {}

  sayHello() {
    return `hello, ${this.name}`
  }
}

模块（import / export）​

src/user.ts：

export interface User {
  id: string
  name: string
}

src/main.ts：

import type { User } from './user'

const u: User = { id: '1', name: 'Alice' }
console.log(u)

七、编译与 tsconfig​

基本编译命令​

npx tsc

常用的方式是在 package.json 配置脚本：

{
  "scripts": {
    "build": "tsc -p tsconfig.json"
  }
}

严格模式（建议逐步开启）​

tsconfig.json 中常见选项：

• strict：开启一组严格检查
• noImplicitAny：禁止隐式 any

新手建议不要一口气全开，但可以从最基础的开始。

八、与 Node.js 结合：Express 示例（TS）​

安装依赖​

npm i express
npm i -D @types/express ts-node nodemon

创建 src/server.ts：

import express from 'express'

const app = express()
app.use(express.json())

app.get('/health', (_req, res) => {
  res.json({ ok: true })
})

app.post('/echo', (req, res) => {
  res.json({ received: req.body })
})

app.listen(3000, () => {
  console.log('server running at http://localhost:3000')
})

启动（开发模式）：

nodemon --exec ts-node src/server.ts

九、常见工程化：lint/format​

工程化不是“越多越好”，但至少应做到：

• 统一格式（Prettier）
• 基于类型的检查与规则（ESLint + TypeScript）

你可以先从 prettier 开始，后续再加 ESLint。

十、测试与构建​

测试思路​

常用方案：

• 单元测试：Jest / Vitest
• 集成测试：supertest（Express）

这里建议你先跑通：

1. 把业务逻辑从路由中抽离成函数
2. 对函数进行单测

十一、最佳实践与小结​

最佳实践​

• 尽量使用明确的类型（至少在边界：入参出参）
• 使用泛型提升复用
• 开启 strict（或逐步开启相关严格选项）
• 把业务逻辑拆分成可测试的模块

小结​

• TypeScript 通过类型系统增强可靠性
• 接口、类型别名、联合类型与泛型是核心能力
• tsconfig 决定编译策略
• 与 Node.js 结合可直接构建 API（Express 示例）

十二、学习路径小结​

1. 跑通 tsc 编译流程，理解输出与模块形式
2. 掌握基础类型、联合类型与类型收窄
3. 学会接口、泛型与常见工具类型
4. 结合 Express 写一个最小 API
5. 从抽离业务逻辑开始加测试，逐步形成工程习惯

遇到问题可查阅 TypeScript 官方文档。

一、Next.js 简介​

什么是 Next.js？​

Next.js 是一个基于 React 的 Web 框架，提供了路由、渲染与构建能力，让你更容易构建：

• SSR / SSG / 混合渲染应用
• 全栈 Web（配合 API / Route Handler）
• 类型友好的工程化开发体验

适合做什么？​

• 个人博客 / 技术文章站
• 产品官网与落地页
• 带用户登录、后台管理的 Web 应用（配合你选择的认证方案）
• API 与前后端一体化项目

二、环境准备与创建项目​

环境要求​

• Node.js：建议使用 18.x 及以上（推荐 20 LTS）
• 了解基础的 npm/pnpm/yarn 使用

创建项目​

使用官方推荐的脚手架 create-next-app：

npx create-next-app@latest my-next-app

初始化安装完成后进入目录并启动：

cd my-next-app
npm run dev

浏览器打开 http://localhost:3000 即可。

三、App Router（推荐）与基础目录结构​

Next.js（新版本）通常使用 App Router。常见目录结构如下：

my-next-app/
├── app/
│   ├── layout.tsx
│   ├── page.tsx
│   └── api/
│       └── health/route.ts
├── public/
├── src/ (可选：把组件/业务逻辑放这里)
├── package.json
└── next.config.js

关键约定：

• app/layout.tsx：全站的根布局（所有页面都会套在里面）
• app/page.tsx：/ 路由对应的页面
• app/**/page.tsx：app 下的每个文件夹可对应一个路由

四、路由与页面（Page / Layout）​

页面：page.tsx​

创建一个路由 app/about/page.tsx：

// app/about/page.tsx
export default function AboutPage() {
  return (
    <main>
      <h1>About</h1>
      <p>这是一个 /about 页面。</p>
    </main>
  )
}

链接：Link​

使用 Next.js 的 Link 进行跳转（推荐）：

import Link from 'next/link'

export default function Home() {
  return (
    <main>
      <h1>Home</h1>
      <Link href="/about">去 About</Link>
    </main>
  )
}

五、组件与样式（CSS Modules / 全局样式）​

CSS Modules​

假设你有 app/components/Hello.module.css：

.title {
  color: #2e8555;
}

然后在组件中使用：

import styles from './Hello.module.css'

export default function Hello() {
  return <h1 className={styles.title}>Hello Next.js</h1>
}

全局样式​

通常在 app/globals.css 引入全站样式，并在根布局 layout.tsx 中导入。

六、数据获取（Data Fetching）​

在 App Router 下，你常见会遇到几种数据获取方式：

1. Server Components 里直接 fetch（最常见的新手路径）
2. 使用 Route Handler 提供 API，再在客户端请求
3. 需要更复杂缓存策略时，显式配置 Next.js 的缓存行为

服务端 fetch 示例​

app/posts/page.tsx：

export default async function PostsPage() {
  const res = await fetch('https://jsonplaceholder.typicode.com/posts', {
    // 新手先用默认策略即可；需要时再研究缓存/重验证
    cache: 'no-store',
  })
  const posts = await res.json()

  return (
    <main>
      <h1>Posts</h1>
      <ul>
        {posts.slice(0, 5).map((p: any) => (
          <li key={p.id}>{p.title}</li>
        ))}
      </ul>
    </main>
  )
}

七、Route Handler（类似 API 路由）​

在 App Router 中，你可以在 app/api/.../route.ts 里写接口。

例如 app/api/health/route.ts：

import { NextResponse } from 'next/server'

export async function GET() {
  return NextResponse.json({ ok: true })
}

访问：/api/health

你也可以扩展为 POST / PUT / DELETE 等方法。

八、构建与部署​

构建​

npm run build

本地预览​

npm run start

部署到 Vercel（新手最省事）​

Next.js 官方在 Vercel 上体验最佳。一般步骤：

• 把项目推到 GitHub
• 在 Vercel 创建新项目并导入仓库
• 使用 Vercel 默认构建命令（通常就是 npm run build）

九、常见问题与小结​

常见问题​

• 为什么我写的页面路由不生效？
  • 确认 app 目录下的 page.tsx 是否放对路径（例如 app/about/page.tsx 对应 /about）
• 为什么数据没有更新？
  • App Router 下 fetch 的缓存策略可能不同；新手阶段可先用 cache: 'no-store'

小结​

• 用 app/ 组织路由：layout.tsx + page.tsx
• 用 Link 做跳转
• 用 CSS Modules 管理样式
• 在 Server Components 中 fetch 获取数据
• 用 app/api/.../route.ts 提供接口
• 用 npm run build / npm run start 完成构建与预览

十、学习路径小结​

1. 新建 Next.js 项目并跑通 npm run dev
2. 写 layout.tsx 和一个 about/page.tsx
3. 用 Link 做页面跳转
4. 写一个 fetch 示例页面并观察加载行为
5. 写 app/api/health/route.ts 测试接口
6. 完成 npm run build 与本地 npm run start 预览

遇到问题可查阅 Next.js 官方文档。

一、NestJS 简介​

什么是 NestJS？​

NestJS 是一个基于 Node.js 的 服务端框架，使用 TypeScript 编写，架构风格借鉴了 Angular。特点包括：

• 分层清晰：控制器、服务、模块等概念明确，适合中大型项目
• 依赖注入（DI）：内置 IoC 容器，便于测试与解耦
• TypeScript 优先：类型安全、装饰器驱动
• 可扩展：支持 REST、GraphQL、WebSocket、微服务等
• 生态丰富：与 TypeORM、Prisma、Passport、class-validator 等无缝集成

适合做什么？​

• RESTful API / BFF（Backend for Frontend）
• GraphQL 服务
• 微服务（配合 Kafka、RabbitMQ 等）
• 实时应用（WebSocket、SSE）
• 需要严格架构与可维护性的 Node 后端

前置知识​

• JavaScript/TypeScript 基础
• Node.js 与 npm 基本使用
• 了解 HTTP、REST 概念更佳

二、环境准备与创建项目​

环境要求​

• Node.js：18.x 及以上（建议 20 LTS）
• 包管理器：npm / yarn / pnpm

使用 CLI 创建项目​

安装 Nest CLI（可选，也可用 npx 不全局安装）：

npm i -g @nestjs/cli
nest new my-app

或直接用 npx：

npx @nestjs/cli new my-app

按提示选择包管理器（npm / yarn / pnpm），完成后进入项目并启动：

cd my-app
npm run start

浏览器访问 http://localhost:3000 应看到 Hello World!。

常用脚本​

三、项目目录结构​

my-app/
├── src/
│   ├── app.module.ts      # 根模块
│   ├── app.controller.ts  # 根控制器
│   ├── app.service.ts     # 根服务
│   └── main.ts            # 入口文件，引导 Nest 应用
├── test/                  # 测试
├── nest-cli.json          # Nest CLI 配置
├── tsconfig.json
└── package.json

• main.ts：创建 NestFactory.create(AppModule)、监听端口、可配置全局管道/前缀等
• app.module.ts：根模块，通过 imports 聚合其他模块
• app.controller.ts / app.service.ts：根控制器与根服务，演示最基础的请求处理与业务逻辑

后续会按功能拆成多个模块（如 users、posts），每个模块可有自己的 *.module.ts、*.controller.ts、*.service.ts。

四、核心概念：模块、控制器、服务​

4.1 模块（Module）​

模块是组织代码的单元，把控制器、服务、其他模块组织在一起。

// app.module.ts
import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';

@Module({
  imports: [],      // 其他模块
  controllers: [AppController],
  providers: [AppService],
  exports: [AppService],  // 导出后，其他模块可注入 AppService
})
export class AppModule {}

• imports：引入其他模块（使用其 exports）
• controllers：该模块下的控制器（处理 HTTP 等）
• providers：该模块下的可注入服务
• exports：把 providers 暴露给其他模块

4.2 控制器（Controller）​

控制器负责处理入站请求并返回响应，对应路由与 HTTP 方法。

// app.controller.ts
import { Controller, Get, Post, Body, Param } from '@nestjs/common';
import { AppService } from './app.service';

@Controller()  // 路由前缀为空，即根
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get()
  getHello(): string {
    return this.appService.getHello();
  }

  @Get('info')
  getInfo() {
    return { name: 'My App', version: '1.0' };
  }
}

• @Controller('prefix')：该控制器下所有路由共用的前缀，如 @Controller('users') 则路由为 /users/...
• @Get()、@Post()、@Put()、@Patch()、@Delete()：对应 HTTP 方法
• constructor 中注入 AppService：由 Nest 的依赖注入提供实例

4.3 服务（Provider / Service）​

服务承载业务逻辑，被控制器注入并调用，避免在控制器里写复杂逻辑。

// app.service.ts
import { Injectable } from '@nestjs/common';

@Injectable()
export class AppService {
  getHello(): string {
    return 'Hello World!';
  }
}

• @Injectable()：表示该类可由 Nest 的 DI 容器管理，并注入到其他类中

关系小结：请求 → 控制器（路由）→ 调用服务（业务）→ 返回响应。

五、依赖注入（DI）​

Nest 内置 IoC 容器：你只声明「需要什么类」，容器负责创建实例并注入。

@Controller()
export class AppController {
  constructor(private readonly appService: AppService) {}
  //     ↑ 私有只读    ↑ 类型声明即可，Nest 自动注入实例
}

• Provider：在某个模块的 providers 里声明（如 AppService）
• 注入：在控制器或其它服务的 constructor 中写上类型，Nest 会注入该模块或已导入模块的 exports 中的对应实例
• 作用域：默认单例；可按需使用 Scope.REQUEST 等实现请求级实例

六、路由与请求处理​

6.1 路径与参数​

@Controller('users')
export class UsersController {
  @Get()                      // GET /users
  findAll() { return []; }

  @Get(':id')                 // GET /users/123
  findOne(@Param('id') id: string) {
    return { id };
  }

  @Post()
  create(@Body() body: CreateUserDto) {
    return body;
  }

  @Put(':id')
  update(@Param('id') id: string, @Body() body: UpdateUserDto) {
    return { id, ...body };
  }

  @Delete(':id')
  remove(@Param('id') id: string) {
    return { deleted: id };
  }
}

常用参数装饰器：

6.2 全局路由前缀​

在 main.ts 中可为所有路由加前缀：

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.setGlobalPrefix('api');  // 所有路由变为 /api/...
  await app.listen(3000);
}

七、DTO 与验证（Validation）​

7.1 为什么用 DTO​

• 定义请求体的形状，便于类型提示和文档
• 配合 class-validator 做自动校验，非法请求在进入控制器前被拦截

7.2 安装与启用​

npm i class-validator class-transformer

在 main.ts 中启用全局验证管道：

import { ValidationPipe } from '@nestjs/common';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalPipes(new ValidationPipe({
    whitelist: true,   // 自动去掉 DTO 中未声明的属性
    forbidNonWhitelisted: true,  // 若带未声明属性则直接 400
    transform: true,   // 按类型自动转换（如 string → number）
  }));
  await app.listen(3000);
}

7.3 定义 DTO​

// create-user.dto.ts
import { IsString, IsEmail, MinLength, IsOptional } from 'class-validator';

export class CreateUserDto {
  @IsString()
  @MinLength(2)
  name: string;

  @IsEmail()
  email: string;

  @IsString()
  @MinLength(6)
  password: string;

  @IsOptional()
  @IsString()
  avatar?: string;
}

控制器中直接使用即可，校验失败时 Nest 自动返回 400 与错误信息：

@Post()
create(@Body() dto: CreateUserDto) {
  return this.usersService.create(dto);
}

八、管道（Pipe）​

管道用于转换或校验输入数据，在到达控制器方法之前执行。

8.1 内置管道示例​

• ValidationPipe：上面已用，配合 class-validator
• ParseIntPipe：将参数转为整数，否则 400

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

8.2 自定义管道​

实现 PipeTransform 接口即可：

// parse-bool.pipe.ts
import { PipeTransform, Injectable, BadRequestException } from '@nestjs/common';

@Injectable()
export class ParseBoolPipe implements PipeTransform<string, boolean> {
  transform(value: string): boolean {
    if (value === 'true') return true;
    if (value === 'false') return false;
    throw new BadRequestException('Expected "true" or "false"');
  }
}

在参数或控制器上使用：@Query('active', ParseBoolPipe) active: boolean。

九、守卫（Guard）​

守卫决定是否允许请求继续，常用于权限、角色校验。

9.1 使用方式​

• 控制器级：@UseGuards(RolesGuard)
• 方法级：同上
• 全局：app.useGlobalGuards(new RolesGuard())

9.2 简单示例​

// roles.guard.ts
import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Reflector } from '@nestjs/core';

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const requiredRoles = this.reflector.get<string[]>('roles', context.getHandler());
    if (!requiredRoles) return true;
    const { user } = context.switchToHttp().getRequest();
    return requiredRoles.some((role) => user?.roles?.includes(role));
  }
}

通过 Reflector 读取元数据（如自定义装饰器 @Roles('admin')），再根据 user 判断。若返回 false，Nest 默认返回 403。

十、拦截器（Interceptor）​

拦截器可在请求前/后统一处理逻辑，如日志、超时、响应格式封装等。

10.1 响应映射示例​

// transform.interceptor.ts
import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable } from 'rxjs';
import { map } from 'rxjs/operators';

export interface Response<T> {
  data: T;
  timestamp: string;
}

@Injectable()
export class TransformInterceptor<T> implements NestInterceptor<T, Response<T>> {
  intercept(context: ExecutionContext, next: CallHandler): Observable<Response<T>> {
    return next.handle().pipe(
      map((data) => ({
        data,
        timestamp: new Date().toISOString(),
      })),
    );
  }
}

在 main.ts 中全局注册：app.useGlobalInterceptors(new TransformInterceptor());，则所有控制器返回的数据会被包成 { data, timestamp }。

10.2 典型用途​

• 统一包装 { code, data, message }
• 日志、耗时统计
• 超时控制（timeout RxJS 操作符）

十一、异常与异常过滤器​

11.1 内置 HTTP 异常​

在服务或控制器中直接抛出，Nest 会转为对应状态码的 JSON：

import { NotFoundException, BadRequestException } from '@nestjs/common';

throw new NotFoundException('用户不存在');
throw new BadRequestException('参数错误');

常用：BadRequestException(400)、UnauthorizedException(401)、ForbiddenException(403)、NotFoundException(404) 等。

11.2 异常过滤器（Exception Filter）​

若希望统一格式或对特定异常做特殊处理，可写异常过滤器：

@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
    const status = exception.getStatus();
    const result = exception.getResponse();
    response.status(status).json({
      statusCode: status,
      message: typeof result === 'object' ? (result as any).message : result,
      timestamp: new Date().toISOString(),
    });
  }
}

使用：@UseFilters(HttpExceptionFilter) 或 app.useGlobalFilters(new HttpExceptionFilter())。

十二、中间件（Middleware）​

中间件在路由处理器之前执行，可做日志、解析、限流等。

12.1 定义与注册​

// logger.middleware.ts
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();
  }
}

在模块中挂到指定路由：

export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(LoggerMiddleware).forRoutes('*');
  }
}

12.2 函数式中间件​

若无需依赖注入，可写为普通函数，在 consumer.apply(LoggerMiddleware) 处传入即可。

十三、配置（ConfigModule）​

13.1 使用 @nestjs/config​

npm i @nestjs/config

根模块中引入：

import { ConfigModule } from '@nestjs/config';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      envFilePath: ['.env.local', '.env'],
    }),
  ],
})
export class AppModule {}

13.2 读取配置​

在服务或控制器中注入 ConfigService：

constructor(private config: ConfigService) {}

someMethod() {
  const port = this.config.get<number>('PORT', 3000);
  const dbUrl = this.config.get<string>('DATABASE_URL');
}

推荐配合 .env 文件，不要提交敏感信息。

十四、数据库（TypeORM 简介）​

Nest 与 TypeORM、Prisma 等都能很好集成，这里以 TypeORM 为例说明「模块 + 实体」的用法。

14.1 安装​

npm i @nestjs/typeorm typeorm mysql2

14.2 注册与实体​

// app.module.ts
import { TypeOrmModule } from '@nestjs/typeorm';
import { User } from './users/user.entity';

@Module({
  imports: [
    TypeOrmModule.forRoot({
      type: 'mysql',
      host: 'localhost',
      port: 3306,
      username: 'root',
      password: 'xxx',
      database: 'mydb',
      entities: [User],
      synchronize: true,  // 开发时可 true，生产建议 false + 迁移
    }),
    TypeOrmModule.forFeature([User]),  // 在 UsersModule 中
  ],
})
export class AppModule {}

14.3 实体与在服务中注入 Repository​

// user.entity.ts
import { Entity, Column, PrimaryGeneratedColumn } from 'typeorm';

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

  @Column()
  name: string;

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

// users.service.ts
@Injectable()
export class UsersService {
  constructor(
    @InjectRepository(User)
    private userRepo: Repository<User>,
  ) {}

  async findAll(): Promise<User[]> {
    return this.userRepo.find();
  }
}

更多（关系、迁移、事务）请查阅 TypeORM 文档。

十五、认证（JWT 示例）​

认证涉及「登录签发 token」和「请求时校验 token」，常用 Passport + JWT。

15.1 安装​

npm i @nestjs/passport @nestjs/jwt passport passport-jwt passport-local
npm i -D @types/passport-jwt @types/passport-local

15.2 思路简述​

• 登录：用 LocalStrategy 校验用户名密码，通过后用 JwtService.sign() 签发 token，返回给前端。
• 受保护路由：用 JwtStrategy 从 Header 的 Bearer token 中解析出用户信息，挂到 request.user；再用 Guard 在需要登录的接口上使用 JwtAuthGuard。

15.3 配置与使用​

在模块中注册：

JwtModule.register({
  secret: process.env.JWT_SECRET || 'your-secret',
  signOptions: { expiresIn: '7d' },
}),
PassportModule,

在需要登录的控制器或方法上添加：

@UseGuards(JwtAuthGuard)
@Get('profile')
getProfile(@Request() req) {
  return req.user;
}

具体实现可参考官方文档 NestJS 认证。

十六、测试​

16.1 单元测试（服务）​

使用 Jest，对服务类进行隔离测试，依赖用 mock：

describe('AppService', () => {
  let service: AppService;

  beforeEach(async () => {
    const module = await Test.createTestingModule({
      providers: [AppService],
    }).compile();
    service = module.get<AppService>(AppService);
  });

  it('getHello', () => {
    expect(service.getHello()).toBe('Hello World!');
  });
});

16.2 E2E 测试​

对完整 HTTP 请求做测试：

describe('AppController (e2e)', () => {
  it('/ (GET)', () => {
    return request(app.getHttpServer())
      .get('/')
      .expect(200)
      .expect('Hello World!');
  });
});

运行：npm run test（单元）、npm run test:e2e（E2E）。

十七、构建与部署​

17.1 构建​

npm run build

产物在 dist/，为编译后的 JavaScript。

17.2 生产运行​

npm run start:prod

会执行 node dist/main（或你配置的入口）。生产环境建议用 PM2、Docker 或云平台的 Node 运行时，并设置好环境变量（如 NODE_ENV=production、数据库与 JWT 的配置）。

17.3 部署注意点​

• 使用 环境变量 管理配置，不要写死敏感信息
• 数据库用 迁移 管理表结构，不要依赖 synchronize: true
• 可配合 Nginx 做反向代理与静态资源
• 健康检查可暴露一个 /health 接口供负载均衡使用

十八、学习路径小结​

1. 入门：创建项目 → 理解 Module / Controller / Service → 改根路由看效果
2. 请求：路由、@Param / @Query / @Body、DTO + ValidationPipe
3. 结构：按功能拆模块（如 UsersModule）、依赖注入与 exports
4. 增强：管道、守卫、拦截器、异常过滤器、中间件
5. 数据：ConfigModule、TypeORM/Prisma、实体与 Repository
6. 安全：JWT 认证、角色守卫
7. 质量：单元测试、E2E 测试
8. 上线：build、环境变量、进程管理、健康检查

遇到问题可查阅 NestJS 官方文档。

一、Node.js 简介​

Node.js 是什么？​

Node.js 是一个让 JavaScript 在服务器端运行的运行时环境。它解决了浏览器只能运行 JS 的限制，让你可以用 JS 写：

• HTTP 接口服务
• 命令行工具
• 数据处理脚本

Node 与浏览器的主要区别​

• API 不一样（浏览器有 DOM，Node 有文件系统/网络等）
• 运行模型不同（Node 是服务器侧环境）
• 模块系统不同（CommonJS / ESM）

二、环境准备与 npm​

安装 Node.js​

• 建议使用 LTS 版本
• 可使用 nvm 管理多个版本（可选）

确认版本：

node -v
npm -v

初始化项目​

mkdir my-node-app
cd my-node-app
npm init -y

package.json 基本字段​

• name / version
• main（入口）
• scripts（一键执行脚本）

例如加入开发脚本：

{
  "scripts": {
    "dev": "node src/server.js"
  }
}

三、模块系统（CommonJS / ESM）​

CommonJS：require​

// src/math.cjs
function add(a, b) {
  return a + b
}

module.exports = { add }

// src/main.cjs
const { add } = require('./math.cjs')
console.log(add(1, 2))

ESM：import​

// src/math.mjs
export function add(a, b) {
  return a + b
}

// src/main.mjs
import { add } from './math.mjs'
console.log(add(1, 2))

建议你在新项目中统一一种模块方式（ESM 更现代），并结合团队约定。

四、异步与事件循环​

Promise / async-await​

async function main() {
  const res = await Promise.resolve({ ok: true })
  console.log(res.ok)
}

main()

错误处理​

async function run() {
  try {
    throw new Error('boom')
  } catch (e) {
    console.error('捕获错误：', e.message)
  }
}

五、HTTP 服务示例（原生）​

创建 src/server.js：

const http = require('http')

const server = http.createServer((req, res) => {
  if (req.url === '/health') {
    res.setHeader('Content-Type', 'application/json; charset=utf-8')
    res.end(JSON.stringify({ ok: true }))
    return
  }

  res.statusCode = 404
  res.end('Not Found')
})

server.listen(3000, () => {
  console.log('server running at http://localhost:3000')
})

启动：

node src/server.js

访问：http://localhost:3000/health

六、使用 Express 构建 API​

安装​

npm i express

简单路由​

创建 src/app.js：

const express = require('express')

const app = express()
app.use(express.json())

app.get('/health', (_req, res) => {
  res.json({ ok: true })
})

app.post('/echo', (req, res) => {
  res.json({ received: req.body })
})

app.listen(3000, () => {
  console.log('express running at http://localhost:3000')
})

启动：

node src/app.js

七、数据访问（入门思路）​

新手建议先把“接口层”和“数据层”分开。你可以从简单存储开始，例如：

• 内存对象（原型期）
• JSON 文件（演示用）

等接口逻辑稳定后再替换为数据库（如 PostgreSQL / MySQL）。

八、日志与错误处理​

统一错误返回​

Express 可以通过中间件做统一处理：

app.use((err, _req, res, _next) => {
  console.error(err)
  res.status(500).json({ message: 'internal error' })
})

日志建议​

• 开发期：console.log 够用
• 生产期：用成熟日志库（如 pino/winston）更可观测

九、测试与调试​

Jest 示例（单元测试）​

npm i -D jest

在 package.json 添加：

{
  "scripts": {
    "test": "jest"
  }
}

写测试：

function add(a, b) {
  return a + b
}

test('add', () => {
  expect(add(1, 2)).toBe(3)
})

调试​

• 使用断点调试（IDE）
• 关键函数先写日志，再逐步定位问题

十、部署与小结​

部署常见方式​

• 静态站点不适用后端部署
• 后端服务通常使用：
  • 进程管理：PM2
  • 容器：Docker
  • 平台：Vercel/Render/Fly.io 等（取决于你的项目形态）

小结​

• Node：用 JS 写后端服务
• npm：管理依赖与脚本
• 模块：CommonJS / ESM 二选一并统一
• 异步：Promise 与 async/await
• API：原生 http 与 Express 入门
• 质量：Jest 测试与统一错误处理

十一、学习路径小结​

1. 安装 Node 并完成 npm 项目初始化
2. 理解模块系统（require/import）
3. 写几个 async/await 的函数并练习错误捕获
4. 用原生 http 实现 /health
5. 用 Express 做一个最小 API（health + echo）
6. 加上至少 1-2 个 Jest 单测，再考虑部署

遇到问题可查阅 Node.js 官方文档 与社区示例。

一、Python 简介​

什么是 Python？​

Python 是一种 解释型、面向对象且以 可读性强 著称的编程语言。它的生态非常成熟，常见用途包括：

• 脚本自动化（写小工具、处理文件、跑任务）
• 数据分析与数据工程（Pandas、NumPy 等）
• Web 后端与接口服务（FastAPI、Flask 等）
• AI / 机器学习（生态强，社区资源多）

适合做什么？​

• 想用更少代码快速完成一个功能
• 想做 API、脚本、爬虫或数据处理
• 希望语言本身对新手友好，并且拥有大量开源库

二、环境准备与运行方式​

安装 Python​

• 到官方站下载安装包（推荐 3.x 最新稳定版）
• 如果你在 Linux/WSL 下，也可以使用系统包管理器或版本管理工具（如 pyenv）

创建虚拟环境（强烈建议）​

避免把依赖装到全局 Python，造成版本冲突：

python -m venv .venv

激活虚拟环境：

# macOS / Linux
source .venv/bin/activate

# Windows（PowerShell）
.\.venv\Scripts\Activate.ps1

升级 pip 并安装依赖：

python -m pip install -U pip

提示：创建虚拟环境可以让每个项目的依赖互相独立，更容易复现和部署。

运行脚本​

python main.py

也可以直接用模块方式运行：

python -m pip --version

三、基本语法与数据类型​

变量与常量​

Python 不需要写类型声明：

name = "Alice"
age = 18
is_student = True

常用数据类型​

• int：整数
• float：浮点数
• str：字符串
• bool：布尔值
• list：列表（可变）
• tuple：元组（不可变，推荐当作“固定结构”使用）
• dict：字典（键值对）
• set：集合（去重）

字符串拼接：f-string​

user = "Bob"
score = 95.5
print(f"{user} 的得分是 {score}")

四、条件与循环​

条件分支​

age = 20
if age >= 18:
    print("adult")
else:
    print("teen")

循环​

for i in range(5):
    print(i)

items = ["a", "b", "c"]
for item in items:
    print(item)

while 循环：

count = 0
while count < 3:
    count += 1
    print(count)

五、函数与模块​

函数定义与返回值​

def add(a: int, b: int) -> int:
    return a + b

其中：

• a: int / b: int 是类型标注（运行时不强制）
• -> int 表示返回类型

模块与导入​

假设有 utils.py：

# utils.py
def hello(name: str) -> str:
    return f"hello, {name}"

在 main.py：

from utils import hello

print(hello("world"))

六、面向对象与异常处理​

类与对象​

class User:
    def __init__(self, name: str):
        self.name = name

    def greet(self) -> str:
        return f"hi, {self.name}"

u = User("Tom")
print(u.greet())

异常（try / except）​

try:
    n = int("123")
except ValueError as e:
    print("转换失败：", e)

也可以在捕获后重新抛出：

try:
    n = int("abc")
except ValueError as e:
    raise RuntimeError("输入不是数字") from e

七、文件与数据格式​

读写文件​

with open("data.txt", "w", encoding="utf-8") as f:
    f.write("Hello\n")

with open("data.txt", "r", encoding="utf-8") as f:
    content = f.read()
print(content)

JSON​

import json

obj = {"name": "Alice", "age": 18}

with open("data.json", "w", encoding="utf-8") as f:
    json.dump(obj, f, ensure_ascii=False, indent=2)

with open("data.json", "r", encoding="utf-8") as f:
    data = json.load(f)
print(data["name"])

八、类型标注与项目结构​

当项目变大时，类型标注可以提升可维护性。一个常见结构：

my-project/
├── src/
│   └── app/
│       ├── main.py
│       └── services/
├── tests/
├── pyproject.toml  (或 requirements.txt)
└── README.md

类型检查工具常见包括 mypy（可按需启用）。

九、第三方库与包管理​

requirements.txt​

安装依赖：

pip install requests

生成依赖清单：

pip freeze > requirements.txt

在新环境安装：

pip install -r requirements.txt

常用库举例​

• requests：发 HTTP 请求
• pydantic：数据校验与结构化（FastAPI 经常用）
• httpx：现代 HTTP 客户端（异步友好）

十、Web 入门（FastAPI）​

安装​

pip install fastapi uvicorn

最小服务​

创建 main.py：

from fastapi import FastAPI

app = FastAPI()

@app.get("/health")
def health():
    return {"ok": True}

启动服务：

uvicorn main:app --reload --port 8000

访问：http://localhost:8000/health

十一、测试与调试​

安装 pytest​

pip install -U pytest

写测试示例：tests/test_main.py

def test_add():
    assert 1 + 1 == 2