📚 课程目录第1章 API基础概念

1. 环境搭建与工具链准备

在构建企业级 API 接入与离线缓存系统之前，必须先建立一个标准化、可复用的开发工具链。本章将带领你从零搭建 Node.js 运行时、包管理器、TypeScript 编译系统、ESLint 静态检查与 Prettier 格式化工具，并确保所有组件能够协同工作。一套稳固的工具链可以减少 60% 以上的环境相关问题，让后续的 API 对接与缓存策略实现聚焦在业务逻辑本身。

1.1 开发工具链全景

整个工具链分为三层：基础环境层提供运行时与包管理能力；代码规范与编译层保证类型安全与代码质量；构建输出层生成可在目标环境运行的产物。下面这张架构图展示了从安装到产物的完整流程以及各工具之间的依赖关系。

1.2 Node.js 运行时安装

Node.js 是整套工具链的运行基石。推荐使用 LTS（长期支持）版本，目前最新 LTS 为 v20.x / v22.x。生产环境建议锁定偶数主版本，避免使用奇数实验版本。版本管理工具 nvm（Node Version Manager）可以让你在同一台机器上随时切换 Node.js 版本，是团队协作的首选方案。

# 安装 nvm（macOS / Linux）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 安装并切换到 Node.js LTS 版本
nvm install 20.11.0
nvm alias default 20.11.0
nvm use 20.11.0

# 验证版本
node --version
# 输出: v20.11.0
npm --version
# 输出: 10.2.4

💡 建议：Windows 用户推荐使用 nvm-windows（github.com/coreybutler/nvm-windows），安装后同样支持 nvm install / nvm use 命令。避免直接从官网下载 .msi 安装包，否则后续切换版本需要手动卸载重装。

1.3 包管理器：npm 与 yarn

npm 随 Node.js 内置，是生态最广的包管理器；Yarn 由 Facebook 推出，在安装速度、离线缓存和确定性依赖方面有优势。由于本课程涉及离线缓存策略设计，Yarn 的 Offline Cache 特性与课程主题高度相关，但两种工具均可完成后续实验。下表从项目实战角度对比二者的关键差异：

对比维度	npm	Yarn
安装速度	串行下载，相对较慢	并行下载 + 缓存加速，快 2~3 倍
离线缓存能力	基础缓存（`npm cache`）	强离线缓存（`yarn cache`，支持 `--offline` 标志）
锁文件	`package-lock.json`	`yarn.lock`
工作空间（Monorepo）	支持（`workspaces`）	支持（`workspaces`，更成熟）
命令风格	标准 Verbose 风格	简洁（`yarn add` / `yarn dev`）

初始化项目时，任选其一执行：

# 使用 npm 初始化
npm init -y

# 或使用 Yarn 初始化
yarn init -y

⚠️ 版本一致性：团队协作时，所有成员必须使用 相同版本 的包管理器。建议在项目根目录的 .nvmrc 中锁定 Node.js 版本，并在 package.json 的 engines 字段声明包管理器版本要求。

1.4 TypeScript 编译配置

TypeScript 为 JavaScript 添加了静态类型系统，能够在编译阶段捕获类型错误，是 API 接入与缓存策略代码的第一道质量防线。安装 TypeScript 及其 Node.js 类型声明：

npm install -D typescript @types/node

# 验证安装
npx tsc --version
# 输出: Version 5.4.5

在项目根目录创建 tsconfig.json，以下配置适用于 Node.js 后端项目：

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "lib": ["ES2022"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true,
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

💡 关键参数说明：
strict: true 启用所有严格类型检查选项，包括 noImplicitAny、strictNullChecks 等，建议生产项目始终开启。
sourceMap: true 生成 .map 文件，方便调试时定位原始 TypeScript 源码。
outDir: ./dist 编译产物输出目录，与 rootDir: ./src 保持对应。

1.5 ESLint 与 Prettier 规范集成

ESLint 负责代码逻辑质量（未使用变量、空值判断、async/await 规范等），Prettier 负责代码格式统一（缩进、分号、引号、换行等）。二者配合使用可以避免大量风格争议。安装步骤：

# 安装 ESLint 及 TypeScript 插件
npm install -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

# 安装 Prettier
npm install -D prettier

ESLint 配置文件 .eslintrc.json：

{
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaVersion": 2022,
    "sourceType": "module"
  },
  "plugins": ["@typescript-eslint"],
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended"
  ],
  "rules": {
    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
    "@typescript-eslint/explicit-function-return-type": "warn",
    "no-console": "warn",
    "eqeqeq": ["error", "always"]
  },
  "ignorePatterns": ["dist", "node_modules"]
}

Prettier 配置文件 .prettierrc：

{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "all",
  "printWidth": 100,
  "arrowParens": "always"
}

  🔧 集成技巧：为了避免 ESLint 与 Prettier 的规则冲突，安装 eslint-config-prettier 并在 ESLint 的 extends 数组末尾加入 "prettier"，即可关闭 ESLint 中与 Prettier 重复的格式规则。

1.6 全链路验证

完成以上所有安装与配置后，运行下面的命令逐一确认每个工具均已就绪：

# 1. Node.js 与 npm
node --version && npm --version

# 2. TypeScript 编译器
npx tsc --version

# 3. ESLint 检查（如果 src 目录下已有 .ts 文件）
npx eslint src/ --ext .ts

# 4. Prettier 格式化检查
npx prettier --check src/

# 5. 全量编译测试
npx tsc --noEmit

若所有命令均无报错，说明你的开发工具链已经搭建完成，可以进入后续章节的 API 接入与缓存策略实战开发。

⚠️ 常见错误排查：
• tsc: command not found → 未成功安装 typescript，重新执行 npm install -D typescript。
• ESLint 报 Parsing error: "parserOptions.project" has been set for @typescript-eslint/parser → 在 .eslintrc.json 中添加 "parserOptions.project": "./tsconfig.json" 并重启编辑器。
• Prettier 不生效 → 确认已在 VS Code 中安装 Prettier 扩展，并将 editor.defaultFormatter 设置为 esbenp.prettier-vscode。

工具	最低版本要求	核心作用	安装命令	验证命令
Node.js	≥ 18 LTS	JavaScript 运行时	nvm install 20.11.0	`node --version`
npm	≥ 9	包管理器（内置）	随 Node.js 安装	`npm --version`
Yarn	≥ 1.22	包管理器（可选）	`npm i -g yarn`	`yarn --version`
TypeScript	≥ 5.0	静态类型编译	`npm i -D typescript`	`npx tsc --version`
ESLint	≥ 8.0	代码质量检查	`npm i -D eslint`	`npx eslint --version`
Prettier	≥ 3.0	代码格式化	`npm i -D prettier`	`npx prettier --version`

至此，你已拥有一套生产级 Node.js + TypeScript + ESLint + Prettier 开发环境。这套工具链将贯穿本课程所有章节，为后续的 API 接入、离线缓存策略设计与实现提供稳定、可维护的工程基础。