荼丛的博客

用 GitHub Gist 做博客后端：零成本的说说与笔记方案

Fri, 12 Jun 2026 00:00:00 GMT

什么是 GitHub Gist？#

GitHub Gist 是 GitHub 提供的一个轻量级代码和文本分享服务。每个 Gist 本质上是一个 Git 仓库，可以包含一个或多个文件，支持版本控制、克隆和 Fork。

Gist 分为两种类型：

Public Gist：公开可见，任何人都能搜索和访问
Secret Gist：不会出现在搜索结果中，但知道 URL 的人仍可访问

注意：Secret Gist 并不是真正的”私有”，它只是不被搜索引擎索引。如果你需要真正的私有存储，请使用 Private 仓库。

Gist 非常适合存储小规模的结构化数据，比如 JSON 格式的配置、笔记、日志等。而且它完全免费，没有存储空间限制（单文件建议 1MB 以内），API 调用频率限制为每小时 5000 次（认证后）。

为什么选择 Gist 做后端？#

作为一个静态博客（Astro），我没有传统的服务器和数据库。但我需要两个动态功能：

说说（类似朋友圈/微博）— 随时发布短文和图片
笔记（类似日记本）— 记录每日所思所想

这些内容需要频繁更新，但我不希望每次都修改代码仓库、重新部署。

对比了几种方案：

方案	成本	复杂度	适合场景
自建数据库	服务器费用	高	大型项目
Supabase/Firebase	免费 tier 有限	中	需要实时数据库
Cloudflare KV	免费 tier 够用	中	需要边缘存储
GitHub Gist	完全免费	低	小规模结构化数据

最终选择了 Gist，因为：

完全免费，无任何限制
与 GitHub 生态无缝集成
支持版本历史，天然备份
API 简单易用
无需注册新服务

说说后端的实现#

数据结构#

每条说说存储为 JSON 数组中的一个对象：

1
[
2
  {
3
    "id": "ext-1718000000",
4
    "content": "今天的天气真好 ☀️",
5
    "published": "2026-06-12T10:00:00Z",
6
    "images": ["https://example.com/photo.jpg"],
7
    "tags": ["日常", "开心"],
8
    "location": "河南-郑州",
9
    "pinned": false
10
  }
11
]

所有说说存在一个 Gist 的单个 JSON 文件中。

配置文件#

src/config/externalMomentsConfig.ts

1
export const externalMomentsConfig = {
2
  enable: true,
3
  gistId: "你的GistID",        // Gist URL 中的 ID
4
  fileName: "moments.json",     // Gist 中的文件名
5
  adminPasswordHash: "SHA-256哈希",  // 登录密码
6
  githubToken: process.env.GITHUB_TOKEN || "",
7
};

Admin 管理页面#

创建了 /admin/moments/ 管理页面，功能包括：

GitHub Token 认证（存储在浏览器 localStorage）
发布新说说（支持图片、标签、位置）
编辑已有说说
删除说说
自定义发布时间

核心流程：

1
Admin 页面 → 输入 GitHub Token → 连接 Gist API
2
  → 读取 moments.json → 渲染列表
3
  → 编辑/发布 → PATCH 更新 Gist

前端展示#

前端页面通过客户端 JavaScript 从 Gist 读取数据：

1
// 使用 Raw URL（不需要 API 认证，Secret Gist 也能访问）
2
fetch("https://gist.githubusercontent.com/raw/" + gistId)
3
  .then(r => r.json())
4
  .then(moments => {
5
    // 渲染说说列表
6
  });

关键点：使用 gist.githubusercontent.com/raw/ 而不是 GitHub API，这样即使 Gist 是 Secret 的，前端也能匿名读取。

笔记后端的实现#

为什么需要独立 Gist？#

说说的数据量小（几十条），一个 Gist 足够。但笔记可能有几百篇，每篇包含完整的 Markdown 内容，单个 Gist 可能超过 1MB 限制。

解决方案：每个笔记本对应一个独立的 Gist。

1
Gist A: "每日总结" → notebooks-entries.json（所有"每日总结"的笔记）
2
Gist B: "日记本"   → notebooks-entries.json（所有"日记本"的笔记）
3
Gist C: "读书笔记" → notebooks-entries.json（所有"读书笔记"的笔记）

配置文件#

src/config/externalNotebooksConfig.ts显示更多显示更少

1
export const externalNotebooksConfig = {
2
  enable: true,
3
  notebookGists: {
4
    "每日总结": "GistID_1",
5
    "日记本": "GistID_2",
6
    "日常随笔": "GistID_3",
7
    "喜马拉雅": "GistID_4",
8
    "我和宝宝的日常": "GistID_5",
9
    "记录100件事": "GistID_6",
10
  },
11
  templates: [
12
    {
13
      id: "daily",
14
      icon: "📅",
15
      name: "每日总结",
16
      title: "{name} 每日总结",
17
      content: "✅️今天做了：  \n🤔今日感悟：  \n⏰明天计划：",
18
    },
19
    // ... 更多模板
20
  ],
21
};

显示更多显示更少

数据结构#

每个笔记本的 Gist 包含：

1
{
2
  "entries": [
3
    {
4
      "id": "entry-1718000000",
5
      "notebook": "每日总结",
6
      "title": "2026年6月12日",
7
      "date": "2026-06-12",
8
      "content": "## 今天做了什么\n\n...",
9
      "createdAt": "2026-06-12T10:00:00Z",
10
      "updatedAt": "2026-06-12T10:00:00Z"
11
    }
12
  ],
13
  "metadata": {
14
    "name": "每日总结",
15
    "summary": "记录每天的所思所想"
16
  }
17
}

显示更多显示更少

Admin 管理页面#

/admin/notebooks/ 页面功能：

选择笔记本（显示 ✅ 已配置 / ⚠️ 未配置）
快速模板（每日总结、日记、读书笔记、灵感、待办、空白）
Markdown 编辑器 + 实时预览
创建/编辑/删除笔记
首次保存自动创建 Gist

前端合并展示#

前端笔记本页面同时显示本地笔记和远程笔记：

1
<!-- 本地笔记（构建时渲染） -->
2
<div class="diary-entries-list">
3
  {localEntries.map(entry => ...)}
4
</div>
5

6
<!-- 远程笔记容器（客户端填充） -->
7
<div id="remote-entries-container" style="display:none;">
8
  <div id="remote-entries-list"></div>
9
</div>

客户端脚本从 Gist 获取远程笔记，合并到列表中：

1
fetch("https://gist.githubusercontent.com/raw/" + gistId)
2
  .then(r => r.json())
3
  .then(data => {
4
    const entries = data.entries
5
      .filter(e => e.notebook === currentNotebook)
6
      .sort((a, b) => new Date(b.date) - new Date(a.date));
7

8
    // 渲染到页面，样式与本地笔记完全一致
9
    entries.forEach(entry => {
10
      const card = document.createElement("a");
11
      card.href = `/life/notebooks/remote-entry/?nb=${notebook}&id=${entry.id}`;
12
      card.className = "diary-entry-card group";
13
      card.innerHTML = `...`;
14
      list.appendChild(card);
15
    });
16
  });

显示更多显示更少

认证与安全#

GitHub Token#

读写 Gist 需要 GitHub Token。Token 只在以下场景使用：

Admin 页面：输入后存储在浏览器 localStorage
构建时：通过 process.env.GITHUB_TOKEN 注入（用于 SSR）

Token 需要 gist 权限，可以在 GitHub Settings → Developer settings → Personal access tokens 创建。

密码保护#

Admin 页面使用 SHA-256 哈希验证密码：

1
// 密码哈希存储在配置文件中（不是明文）
2
adminPasswordHash: "284d9a101beeb8fbf979d029b25fa49f859739904bfc3a918ecba1c00001b0af"

用户输入密码后，前端计算 SHA-256 哈希并与配置中的值比对。验证通过后在 sessionStorage 中标记登录状态。

数据流总结#

1
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
2
│  Admin 页面  │────→│ GitHub API  │────→│  Gist (JSON) │
3
│  (写入数据)  │     │  (Token认证) │     │  (数据存储)  │
4
└─────────────┘     └─────────────┘     └─────────────┘
5
                                               │
6
                                               ▼
7
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
8
│  前端页面    │←────│ Raw URL     │←────│  Gist 内容   │
9
│  (展示数据)  │     │ (无需认证)   │     │  (JSON数据)  │
10
└─────────────┘     └─────────────┘     └─────────────┘

注意事项#

Gist 默认公开：创建时选 Secret Gist，但知道 URL 的人仍可访问
单文件大小限制：建议 1MB 以内，普通笔记可存 200-300 篇
API 频率限制：5000 次/小时，个人博客完全够用
图片不存 Gist：图片使用外部 CDN，Gist 只存 Markdown 文本和图片 URL
备份：Gist 本质是 Git 仓库，有完整版本历史

总结#

GitHub Gist 作为一个免费、可靠的轻量级存储服务，非常适合作为静态博客的动态内容后端。通过合理的架构设计（Raw URL 读取、Token 认证写入、按笔记本拆分 Gist），我们实现了：

零服务器成本
零额外依赖
完整的 CRUD 操作
Markdown 编辑器 + 实时预览
本地 + 远程数据合并展示

如果你也有一个静态博客，想要添加动态内容功能，不妨试试这个方案。

claude code

Tue, 09 Jun 2026 00:00:00 GMT

命令#

恢复上次对话的命令：/resume

skill#

AI摘要实现原理解析

Fri, 05 Jun 2026 00:00:00 GMT

AI摘要实现原理解析#

这篇文章会把我博客里「AI 摘要」功能的完整实现拆开来讲。整个功能由两部分组成：一个构建时脚本负责调用 AI 生成摘要写入文章 frontmatter，一个前端组件负责把摘要以打字机动画的形式展示给读者。

整体架构#

1
┌─────────────────────────────────────────────────────┐
2
│                   构建时 (Build Time)                 │
3
│                                                     │
4
│  scripts/fill-descriptions.ts                       │
5
│  ├── 扫描 src/content/posts/ 下所有 .md/.mdx         │
6
│  ├── 跳过已有 description 的文章                      │
7
│  ├── 调用千问 API 生成摘要                            │
8
│  └── 写回 frontmatter (description + descriptionSource) │
9
└─────────────────────────────────────────────────────┘
10
                         ↓
11
┌─────────────────────────────────────────────────────┐
12
│                   运行时 (Runtime)                    │
13
│                                                     │
14
│  src/components/widget/AiSummary.astro               │
15
│  ├── 读取 description 和 descriptionSource            │
16
│  ├── IntersectionObserver 监听滚动进入视口             │
17
│  └── 逐字打字机动画，标点处自动停顿                    │
18
└─────────────────────────────────────────────────────┘

显示更多显示更少

第一部分：构建时摘要生成脚本#

脚本入口与配置#

脚本位于 scripts/fill-descriptions.ts，使用 npx tsx 直接运行：

Terminal window

1
npx tsx scripts/fill-descriptions.ts

核心配置：

1
// 千问 API 配置（DashScope 兼容 OpenAI 格式）
2
const QWEN_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1";
3
const QWEN_MODEL = "qwen-plus";
4

5
// 每篇文章最多取前 2600 字作为上下文
6
const MAX_CONTEXT_CHARS = 2600;
7

8
// API 失败最多重试 2 次
9
const MAX_RETRIES = 2;

API 密钥直接写在脚本里，但这个文件已加入 .gitignore，不会被推送到 GitHub。

扫描与过滤逻辑#

脚本会递归扫描 src/content/posts/ 目录下所有 .md 和 .mdx 文件，然后用 gray-matter 解析 frontmatter：

1
const POSTS_DIR = path.resolve("src/content/posts");
2

3
async function main() {
4
  const mdFiles = collectMarkdownFiles(POSTS_DIR);
5
  const missing: MissingItem[] = [];
6
  let skipped = 0;
7

8
  for (const filePath of mdFiles) {
9
    const raw = fs.readFileSync(filePath, "utf-8");
10
    const gm = matter(raw);
11
    if (gm.data.description) {
12
      skipped++;  // 已有 description，跳过
13
      continue;
14
    }
15
    missing.push({
16
      filePath,
17
      title: gm.data.title || path.basename(filePath, path.extname(filePath)),
18
      raw,
19
    });
20
  }
21
}

显示更多显示更少

关键设计：只处理没有 description 字段的文章，已经写了 description 的文章（不管是手动写的还是之前生成的）完全不动，不会覆盖。

上下文提取#

在发送给 AI 之前，需要把 Markdown 正文清理成纯文本：

1
function extractContext(body: string, maxChars: number): string {
2
  const cleaned = body
3
    .replace(/^---[\s\S]*?---\n?/, "")       // 去掉 frontmatter
4
    .replace(/#{1,6}\s+/g, "")                // 去掉标题标记
5
    .replace(/```[\s\S]*?```/g, "[代码块]")    // 代码块替换为占位符
6
    .replace(/`[^`]+`/g, "[代码]")             // 行内代码替换
7
    .replace(/!\[.*?\]\(.*?\)/g, "")           // 去掉图片
8
    .replace(/\[([^\]]*)\]\(.*?\)/g, "$1")    // 保留链接文字，去掉 URL
9
    .replace(/\n{3,}/g, "\n\n")               // 压缩多余空行
10
    .trim();
11

12
  return cleaned.length > maxChars
13
    ? `${cleaned.slice(0, maxChars)}...`       // 截断到 2600 字
14
    : cleaned;
15
}

显示更多显示更少

为什么要截断？因为摘要只需要理解文章大意，没必要把整篇长文都发给 API，2600 字足够捕捉核心内容，同时节省 token 开销。

提示词设计#

这是整个功能里最值得讲的部分。提示词的目标是让 AI 生成的摘要像人写的，而不是像机器总结的：

1
const SYSTEM_PROMPT = `你是一个以第一视角写作的个人博客作者。你的博客记录技术学习、日常生活和真实感悟。
2

3
你的任务是：读完一篇博客文章后，为它写一段友好、自然、像博客导语一样的"文章摘要"。
4

5
核心规则：
6
1. 输出只要一段摘要文字，不要标题、不要列表、不要"本文""这篇文章""总之"之类的套话。
7
2. 表达要自然、口语化，像一个真实的博主在跟读者打招呼或做开场铺垫，有一点"人味"。
8
3. 不要堆砌概念、不要写得像说明书或提纲总结。
9
4. 贴近原文真实内容，保留原作者的情绪和语气。
10
5. 技术文章保持清晰但不要生硬，生活/感悟类文章语气柔和一些。
11
6. 字数控制在 60～120 字左右，越短、越准越好，不要啰嗦。
12
7. 纯正文内容输出（不带任何前缀或说明）。`;

效果对比：

AI 生成（优化后）	AI 生成（未优化）
折腾了两天终于把Nginx反代配通了，中间踩了三个莫名其妙的坑，趁热记下来免得下次再掉进去 😤	本文主要介绍了Nginx反向代理的配置方法，包括常见的错误排查和解决方案。

API 调用与重试#

1
async function generateDescription(title: string, content: string): Promise<string | null> {
2
  const context = extractContext(content, MAX_CONTEXT_CHARS);
3
  const userMsg = `文章标题：${title}\n\n文章内容（节选）：\n${context}`;
4

5
  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
6
    try {
7
      const resp = await fetch(`${QWEN_BASE_URL}/chat/completions`, {
8
        method: "POST",
9
        headers: {
10
          "Content-Type": "application/json",
11
          Authorization: `Bearer ${QWEN_API_KEY}`,
12
        },
13
        body: JSON.stringify({
14
          model: QWEN_MODEL,
15
          messages: [
16
            { role: "system", content: SYSTEM_PROMPT },
17
            { role: "user", content: userMsg },
18
          ],
19
          temperature: 0.75,
20
          max_tokens: 256,
21
        }),
22
      });
23

24
      if (!resp.ok) {
25
        // 失败时递增等待后重试
26
        if (attempt < MAX_RETRIES) {
27
          await sleep(1500 * (attempt + 1));
28
          continue;
29
        }
30
        return null;
31
      }
32

33
      const json = await resp.json();
34
      const text = json?.choices?.[0]?.message?.content?.trim() ?? "";
35

36
      // 清理 AI 可能加上的前缀
37
      const cleaned = text
38
        .replace(/^(摘要|简介|内容简介|文章摘要|本文|这篇文章|总的来说|总之|概括).{0,8}[：:]\s*/i, "")
39
        .replace(/\s*---\s*$/, "")
40
        .trim();
41

42
      return cleaned || null;
43
    } catch (err) {
44
      if (attempt < MAX_RETRIES) {
45
        await sleep(1500 * (attempt + 1));
46
        continue;
47
      }
48
      return null;
49
    }
50
  }
51
  return null;
52
}

显示更多显示更少

几个设计细节：

temperature: 0.75 — 略高于默认值，让生成的摘要更有个性，不会太死板
max_tokens: 256 — 摘要本身不长，256 token 绑绑有余
重试间隔递增 — 1500ms * (attempt + 1)，避免频繁请求触发限流
前缀清理 — AI 有时候会自作主张加上”摘要：“之类的前缀，用正则干掉

写回 Frontmatter#

生成的摘要需要写入文章的 YAML frontmatter：

1
function writeFrontmatter(filePath: string, raw: string, description: string, source: "ai" | "manual"): void {
2
  let fm = raw;
3
  const hasDesc = /^description\s*:\s*/m.test(fm);
4
  const hasSource = /^descriptionSource\s*:\s*/m.test(fm);
5

6
  if (!hasDesc) {
7
    // 找到 frontmatter 的结束标记 ---，在它前面插入 description
8
    const closingIdx = fm.indexOf("---", 4);
9
    const beforeClose = fm.slice(0, closingIdx);
10
    const afterClose = fm.slice(closingIdx);
11

12
    const safeDesc = description.includes('"')
13
      ? `"${description.replace(/"/g, '\\"')}"`
14
      : `"${description}"`;
15

16
    fm = `${beforeClose.trimEnd()}\ndescription: ${safeDesc}\n\n${afterClose.trimStart()}`;
17
  }
18

19
  if (!hasSource) {
20
    // 同样方式插入 descriptionSource
21
    const closingIdx = fm.indexOf("---", 4);
22
    const beforeClose = fm.slice(0, closingIdx);
23
    const afterClose = fm.slice(closingIdx);
24
    fm = `${beforeClose.trimEnd()}\ndescriptionSource: ${source}\n\n${afterClose.trimStart()}`;
25
  }
26

27
  fs.writeFileSync(filePath, fm, "utf-8");
28
}

显示更多显示更少

写入后，文章的 frontmatter 会变成这样：

1
---
2
title: 折腾Nginx反代记录
3
published: 2026-04-15
4
description: "折腾了两天终于把Nginx反代配通了，中间踩了三个莫名其妙的坑……"
5
descriptionSource: ai
6
---

主流程与限流#

1
for (const item of missing) {
2
  const desc = await generateDescription(item.title, item.raw);
3
  if (!desc) {
4
    failed++;
5
    continue;
6
  }
7

8
  writeFrontmatter(item.filePath, item.raw, desc, "ai");
9
  success++;
10

11
  await sleep(600);  // 每次请求间隔 600ms，避免限流
12
}

每篇文章处理完后等待 600ms，对千问 API 表示友好。

第二部分：前端打字机组件#

组件位于 src/components/widget/AiSummary.astro，是一个纯 Astro 组件，没有框架运行时开销。

Props 定义#

1
interface Props {
2
  description: string;
3
  descriptionSource?: "manual" | "ai" | string;
4
}

description — 摘要文本
descriptionSource — 来源标记，"manual" 显示「人工编写」，其他值（包括 "ai"）显示「AI 摘要」

模板结构#

1
<div id="ai-summary" class="ai-summary card-base rounded-xl mb-6 onload-animation">
2
  <div class="ai-summary-inner">
3
    <div class="ai-summary-header">
4
      <div class="ai-summary-icon">
5
        <Icon name={iconName} class="text-lg" />
6
      </div>
7
      <span class="ai-summary-label">{sourceLabel}</span>
8
    </div>
9
    <p id="ai-summary-text" class="ai-summary-text" data-full-text={description}>
10
    </p>
11
  </div>
12
</div>

注意 <p> 标签本身是空的，摘要文本通过 data-full-text 属性传递给 JavaScript，由打字机动画逐字填充。

打字机动画核心#

这是整个组件最精华的部分：

1
(function typewriter() {
2
  const el = document.getElementById("ai-summary-text");
3
  if (!el) return;
4

5
  const fullText = el.getAttribute("data-full-text") || "";
6
  if (!fullText) return;
7

8
  // 无障碍：尊重"减少动态效果"设置
9
  const prefersReducedMotion = window.matchMedia(
10
    "(prefers-reduced-motion: reduce)"
11
  ).matches;
12
  if (prefersReducedMotion) {
13
    el.textContent = fullText;  // 直接显示全文
14
    return;
15
  }
16

17
  let hasRun = false;
18
  const speed = 45; // 每个字符 45ms
19

20
  // IntersectionObserver：只在元素进入视口时触发一次
21
  const observer = new IntersectionObserver(
22
    (entries) => {
23
      for (const entry of entries) {
24
        if (entry.isIntersecting && !hasRun) {
25
          hasRun = true;
26
          observer.unobserve(el);
27
          startTyping();
28
        }
29
      }
30
    },
31
    { threshold: 0.3 }
32
  );
33

34
  observer.observe(el);
35

36
  function startTyping() {
37
    let i = 0;
38
    el.textContent = "";
39

40
    function tick() {
41
      if (i < fullText.length) {
42
        el.textContent += fullText.charAt(i);
43
        i++;
44

45
        // 根据标点符号调整停顿时间
46
        const char = fullText.charAt(i - 1);
47
        const delay =
48
          char === "。" || char === "！" || char === "？" || char === "…"
49
            ? speed * 3    // 句末标点：135ms
50
            : char === "，" || char === "、"
51
              ? speed * 2  // 逗号、顿号：90ms
52
              : speed;     // 普通字符：45ms
53

54
        setTimeout(tick, delay);
55
      }
56
    }
57

58
    tick();
59
  }
60
})();

显示更多显示更少

这段代码有几个值得注意的设计：

1. IntersectionObserver 懒触发

不是页面一加载就开始打字，而是等用户滚动到摘要区域才开始。threshold: 0.3 表示元素有 30% 可见时才触发。hasRun 标志确保只播放一次。

2. 标点停顿节奏

普通字符间隔 45ms，逗号/顿号 90ms（2倍），句号/感叹号/问号/省略号 135ms（3倍）。这个细节让打字效果更像真人在打字——人在打完一句话后会自然地停顿一下。

3. 无障碍支持

prefers-reduced-motion 是一个 CSS 媒体查询，用户在系统设置中开启「减少动态效果」后，动画会跳过，直接显示全文。

样式#

1
.ai-summary {
2
  border: 1px solid color-mix(in srgb, var(--line-divider) 86%, transparent);
3
  background: color-mix(in srgb, var(--card-bg) 94%, transparent);
4
  overflow: hidden;
5
}
6

7
.ai-summary-icon {
8
  width: 1.75rem;
9
  height: 1.75rem;
10
  border-radius: 0.5rem;
11
  background: color-mix(in srgb, var(--primary) 14%, transparent);
12
  color: var(--primary);
13
}
14

15
.ai-summary-text {
16
  font-size: 0.925rem;
17
  line-height: 1.75;
18
  color: var(--deep-text);
19
  min-height: 1.75em;  /* 预留空间，避免打字时布局跳动 */
20
}

显示更多显示更少

min-height: 1.75em 是个小细节——在打字动画开始前，摘要区域已经占好了空间，不会因为文字逐渐出现而导致页面布局抖动。

在文章页集成#

在 src/pages/posts/[...slug].astro 中：

1
{
2
  entry.data.description && (
3
    <AiSummary
4
      description={entry.data.description}
5
      descriptionSource={entry.data.descriptionSource}
6
    />
7
  )
8
}

只有当文章有 description 字段时才渲染摘要组件。没有 description 的文章不会显示摘要区域，不影响正常页面。

第三部分：数据流与字段约定#

Frontmatter 字段#

字段	类型	必填	说明
`description`	string	否	文章摘要，60~120字
`descriptionSource`	`"manual"` \| `"ai"`	否	标记摘要来源

内容集合 Schema#

在 src/content.config.ts 中，description 已纳入 Zod schema 验证：

1
const postsCollection = defineCollection({
2
  schema: z.object({
3
    title: z.string(),
4
    published: z.date(),
5
    description: z.string().optional().default(""),
6
    // ... 其他字段
7
  }),
8
});

descriptionSource 没有在 schema 中定义，但 Astro 会把 frontmatter 中的所有字段都传递给页面，所以 entry.data.descriptionSource 在模板中仍然可以正常访问。

完整数据流#

1
1. 作者写文章 → frontmatter 中不写 description
2
2. 运行 fill-descriptions.ts → 千问 API 生成摘要 → 写入 description + descriptionSource: ai
3
3. pnpm build → Astro 构建 → 文章页读取 description
4
4. 用户访问文章页 → AiSummary 组件渲染 → IntersectionObserver 监听
5
5. 用户滚动到摘要区域 → 打字机动画开始 → 逐字显示摘要

总结#

整个 AI 摘要功能只涉及两个文件，没有引入额外的 npm 依赖（脚本用原生 fetch 调用 API），没有运行时的 AI 调用（摘要在构建时就生成好了），前端组件也是纯 Astro + 原生 JS，没有框架运行时开销。

如果你也想在自己的博客里实现类似功能，核心步骤就是：

写一个脚本，用你喜欢的 LLM API 生成摘要，写入 frontmatter
写一个前端组件，读取摘要并用打字机动画展示
在文章页面条件渲染这个组件

提示词的质量决定了摘要的「人味」程度，这是最值得花时间打磨的地方。

博客导航栏模块完整构建方案

Fri, 29 May 2026 00:00:00 GMT

概述#

本文详细介绍博客导航栏模块的完整构建方案。导航栏是整个博客最关键的用户交互入口，它承载了：

品牌标识：Logo + 标题
页面导航：多级下拉菜单
全局搜索：基于 Pagefind 的全文搜索
主题切换：亮色/暗色/跟随系统
音乐播放：导航栏内嵌音乐播放器
显示设置：壁纸模式、布局切换等
移动端适配：侧滑抽屉菜单

整个导航栏系统由 类型层 → 配置层 → 常量层 → 组件层 → 样式层 五层架构组成。

一、类型定义层#

所有导航相关的 TypeScript 类型定义在 config.ts 中：

1
// 预设链接枚举 —— 将常用的页面链接定义为枚举，避免各处硬编码
2
export enum LinkPreset {
3
  Home = 0,
4
  Archive = 1,
5
  About = 2,
6
  Friends = 3,
7
  Sponsor = 4,
8
  Guestbook = 5,
9
  Bangumi = 6,
10
  Books = 7,
11
  MoviesGames = 8,
12
  MusicPage = 9,
13
  Changelog = 10,
14
}
15

16
// 单个导航链接类型
17
export type NavBarLink = {
18
  name: string;                           // 显示名称
19
  url: string;                            // 跳转地址
20
  external?: boolean;                     // 是否外部链接
21
  icon?: string;                          // Iconify 图标名
22
  children?: (NavBarLink | LinkPreset)[]; // 子菜单，嵌套结构
23
};
24

25
// 搜索方式枚举
26
export enum NavBarSearchMethod {
27
  PageFind = 0,
28
}
29

30
export type NavBarSearchConfig = {
31
  method: NavBarSearchMethod;
32
};
33

34
// 导航栏整体配置
35
export type NavBarConfig = {
36
  links: (NavBarLink | LinkPreset)[];
37
};

显示更多显示更少

设计亮点：

LinkPreset 枚举作为预设链接的”快捷方式”，在配置中用数字代替完整对象，减少冗余
children 字段使用 (NavBarLink | LinkPreset)[]，子菜单同样支持预设，支持无限层级嵌套
external 字段区分内部路由和外部跳转，外部链接会在渲染时添加 _blank 和小箭头图标

二、常量层：LinkPresets 映射表#

link-presets.ts 将 LinkPreset 枚举值解析为完整的 NavBarLink 对象，同时集成 i18n 国际化：

1
import I18nKey from "@i18n/i18nKey";
2
import { i18n } from "@i18n/translation";
3
import { LinkPreset, type NavBarLink } from "@/types/config";
4

5
export const LinkPresets: { [key in LinkPreset]: NavBarLink } = {
6
  [LinkPreset.Home]: {
7
    name: i18n(I18nKey.home),
8
    url: "/",
9
    icon: "material-symbols:home",
10
  },
11
  [LinkPreset.About]: {
12
    name: i18n(I18nKey.about),
13
    url: "/about/",
14
    icon: "material-symbols:person",
15
  },
16
  [LinkPreset.Archive]: {
17
    name: i18n(I18nKey.archive),
18
    url: "/archive/",
19
    icon: "material-symbols:archive",
20
  },
21
  [LinkPreset.Friends]: {
22
    name: i18n(I18nKey.friends),
23
    url: "/friends/",
24
    icon: "material-symbols:group",
25
  },
26
  [LinkPreset.Sponsor]: {
27
    name: i18n(I18nKey.sponsor),
28
    url: "/sponsor/",
29
    icon: "material-symbols:favorite",
30
  },
31
  [LinkPreset.Guestbook]: {
32
    name: i18n(I18nKey.guestbook),
33
    url: "/guestbook/",
34
    icon: "material-symbols:chat",
35
  },
36
  [LinkPreset.Bangumi]: {
37
    name: i18n(I18nKey.bangumi),
38
    url: "/bangumi/",
39
    icon: "material-symbols:camera-outdoor",
40
  },
41
  [LinkPreset.Books]: {
42
    name: i18n(I18nKey.books),
43
    url: "/books/",
44
    icon: "material-symbols:book-5",
45
  },
46
  [LinkPreset.MoviesGames]: {
47
    name: i18n(I18nKey.moviesGames),
48
    url: "/movies-games/",
49
    icon: "material-symbols:movie",
50
  },
51
  [LinkPreset.MusicPage]: {
52
    name: i18n(I18nKey.musicPage),
53
    url: "/music/",
54
    icon: "material-symbols:music-note",
55
  },
56
  [LinkPreset.Changelog]: {
57
    name: i18n(I18nKey.changelog),
58
    url: "/changelog/",
59
    icon: "material-symbols:history",
60
  },
61
};

显示更多显示更少

设计亮点：

{ [key in LinkPreset]: NavBarLink } 使用 TypeScript 映射类型，确保所有枚举值都被覆盖，不会遗漏
调用 i18n() 函数时读取运行时语言配置，切换语言后所有导航栏文本自动更新

三、配置层#

3.1 导航栏核心配置#

navBarConfig.ts 是导航栏菜单配置的核心：

1
import {
2
  LinkPreset,
3
  type NavBarConfig,
4
  type NavBarLink,
5
  type NavBarSearchConfig,
6
  NavBarSearchMethod,
7
} from "../types/config";
8
import { siteConfig } from "./siteConfig";
9

10
const getDynamicNavBarConfig = (): NavBarConfig => {
11
  const links: (NavBarLink | LinkPreset)[] = [
12
    LinkPreset.Home,
13
    {
14
      name: "分类",
15
      url: "/categories/",
16
      icon: "material-symbols:folder-open",
17
    },
18
    LinkPreset.Archive,
19
    {
20
      name: "网站导航",
21
      url: "/projects/",
22
      icon: "material-symbols:public",
23
    },
24
  ];
25

26
  // 动态（带下拉子菜单）
27
  links.push({
28
    name: "动态",
29
    url: "/moments/",
30
    icon: "material-symbols:local-cafe",
31
    children: [
32
      {
33
        name: "说说",
34
        url: "/moments/",
35
        icon: "material-symbols:chat-bubble-outline",
36
      },
37
      {
38
        name: "相册",
39
        url: "/album/",
40
        icon: "material-symbols:photo-album-outline",
41
      },
42
      {
43
        name: "留言板",
44
        url: "/guestbook/",
45
        icon: "material-symbols:edit-outline",
46
      },
47
    ],
48
  });
49

50
  // 记录入口 - 根据页面开关动态生成子菜单
51
  const recordChildren: (NavBarLink | LinkPreset)[] = [];
52
  if (siteConfig.pages.books) recordChildren.push(LinkPreset.Books);
53
  if (siteConfig.pages.moviesGames) recordChildren.push(LinkPreset.MoviesGames);
54
  if (siteConfig.pages.musicPage) recordChildren.push(LinkPreset.MusicPage);
55
  if (siteConfig.pages.changelog) recordChildren.push(LinkPreset.Changelog);
56
  recordChildren.push({
57
    name: "规划",
58
    url: "/life/routines/",
59
    icon: "material-symbols:list-alt",
60
  });
61
  recordChildren.push({
62
    name: "足迹",
63
    url: "/life/places/",
64
    icon: "material-symbols:location-on",
65
  });
66

67
  if (recordChildren.length > 0) {
68
    links.push({
69
      name: "记录",
70
      url: "/books/",
71
      icon: "material-symbols:camera-outdoor",
72
      children: recordChildren,
73
    });
74
  }
75

76
  // 关于及其子菜单
77
  links.push({
78
    name: "关于",
79
    url: "/about/",
80
    icon: "material-symbols:info",
81
    children: [
82
      LinkPreset.About,
83
      LinkPreset.Friends,
84
      ...(siteConfig.pages.sponsor ? [LinkPreset.Sponsor] : []),
85
    ],
86
  });
87

88
  return { links } as NavBarConfig;
89
};
90

91
export const navBarSearchConfig: NavBarSearchConfig = {
92
  method: NavBarSearchMethod.PageFind,
93
};
94

95
export const navBarConfig: NavBarConfig = getDynamicNavBarConfig();

显示更多显示更少

设计亮点：

动态生成：根据 siteConfig.pages 中的开关动态增删菜单项，关闭书架页面则”记录”下拉中不显示”书架”
混合使用：既可以用 LinkPreset 枚举快捷引用预设链接，也可以直接写 NavBarLink 对象实现自定义
展开运算符：...(condition ? [item] : []) 模式优雅地实现条件渲染子菜单

3.2 站点配置中的导航栏设置#

siteConfig.ts 中的 navbar 字段：

1
navbar: {
2
  // Logo 支持四种类型：icon、image(src目录)、image(public目录)、url
3
  logo: {
4
    type: "image",
5
    value: "assets/images/firefly.png",
6
    alt: "🍀",
7
  },
8
  title: "团子和蛋糕",
9
  hoverTitle: "w(ﾟДﾟ)w 不要走！再看看嘛！",  // 离开页面时标题变化
10
  widthFull: false,   // 是否全宽导航栏
11
  followTheme: false, // Logo和标题是否跟随主题色
12
},

3.3 壁纸配置中的导航栏透明模式#

backgroundWallpaper.ts 中的 banner.navbar：

1
navbar: {
2
  // "semi" 半透明 | "full" 完全透明 | "semifull" 动态透明（滚动时变化）
3
  transparentMode: "semifull",
4
  enableBlur: true,  // 毛玻璃模糊效果开关
5
  blur: 3,           // 模糊度(px)
6
},

四、组件层#

4.1 导航栏布局嵌套关系#

导航栏的实际渲染入口在 MainGridLayout.astro 中：

1
<div id="navbar-wrapper" class="pointer-events-auto transition-all"
2
     data-full-width={String(navbarWidthFull)}>
3
    <Navbar></Navbar>
4
</div>

组件树结构如下：

1
Navbar.astro                      ← 主容器
2
├── Logo区域 (a标签)
3
│   ├── Icon (icon类型)
4
│   ├── Picture/Image (image/url类型)
5
│   └── 标题文字
6
├── 桌面端导航链接列表 (.hidden.lg:flex)
7
│   └── DropdownMenu.astro × N   ← 每个链接一个
8
│       ├── 有子菜单 → button + DropdownPanel → DropdownItem
9
│       └── 无子菜单 → a标签
10
├── 右侧工具栏 (.flex.items-center)
11
│   ├── Search.svelte            ← 搜索组件
12
│   ├── 音乐按钮 (条件渲染)
13
│   ├── 显示设置按钮 (条件渲染)
14
│   ├── LightDarkSwitch.svelte   ← 亮暗切换
15
│   └── 汉堡菜单按钮 (移动端) .lg:hidden
16
├── 音乐播放面板 (浮动)
17
│   └── MusicPlayer.astro
18
├── NavMenuPanel.astro           ← 移动端侧滑菜单
19
└── DisplaySettingsIntegrated.svelte ← 显示设置面板

显示更多显示更少

4.2 Navbar.astro — 主组件#

Navbar.astro 是导航栏的核心组件，完整代码如下：

1
---
2
import { Picture } from "astro:assets";
3
import * as path from "node:path";
4
import type { ImageMetadata } from "astro";
5
import { Icon } from "astro-icon/components";
6
import DisplaySettings from "@/components/controls/DisplaySettingsIntegrated.svelte";
7
import LightDarkSwitch from "@/components/controls/LightDarkSwitch.svelte";
8
import Search from "@/components/controls/Search.svelte";
9
import MusicPlayer from "@/components/features/MusicPlayer.astro";
10
import { backgroundWallpaper, navBarConfig, siteConfig } from "@/config";
11
import { musicPlayerConfig } from "@/config/musicConfig";
12
import { LinkPresets } from "@/constants/link-presets";
13
import I18nKey from "@/i18n/i18nKey";
14
import { i18n } from "@/i18n/translation";
15
import { LinkPreset, type NavBarLink } from "@/types/config";
16
import { getFallbackFormat, getImageFormats } from "@/utils/image-utils";
17
import { isHomePage } from "@/utils/layout-utils";
18
import { url } from "@/utils/url-utils";
19
import DropdownMenu from "./DropdownMenu.astro";
20
import NavMenuPanel from "./NavMenuPanel.astro";
21

22
const className = Astro.props.class;
23

24
// 获取导航栏透明模式配置
25
const navbarTransparentMode =
26
  backgroundWallpaper.mode === "banner"
27
    ? backgroundWallpaper.banner?.navbar?.transparentMode || "semi"
28
    : "semi";
29

30
// 获取毛玻璃效果配置
31
const navbarEnableBlur =
32
  backgroundWallpaper.mode === "banner"
33
    ? (backgroundWallpaper.banner?.navbar?.enableBlur ?? true)
34
    : false;
35

36
const navbarBlur =
37
  backgroundWallpaper.mode === "banner"
38
    ? (backgroundWallpaper.banner?.navbar?.blur ?? 20)
39
    : 0;
40

41
const navbarTitle = siteConfig.navbar.title || siteConfig.title;
42
const navbarWidthFull = siteConfig.navbar.widthFull ?? false;
43
const isHomePageCheck = isHomePage(Astro.url.pathname);
44

45
// 显示设置可用性判断
46
const showThemeColor = !siteConfig.themeColor.fixed;
47
const isWallpaperSwitchable = backgroundWallpaper.switchable ?? true;
48
const allowLayoutSwitch = siteConfig.postListLayout.allowSwitch;
49
const hasDisplaySettings =
50
  showThemeColor || isWallpaperSwitchable || allowLayoutSwitch;
51

52
// 将预设链接解析为真实链接
53
let links: NavBarLink[] = navBarConfig.links.map(
54
  (item: NavBarLink | LinkPreset): NavBarLink => {
55
    if (typeof item === "number") {
56
      return LinkPresets[item];
57
    }
58
    return item;
59
  },
60
);
61

62
// 智能处理Logo：区分src目录图片（Astro优化）和public/远程图片
63
const logoValue = siteConfig.navbar.logo?.value || "";
64
const isLocalSrcLogo =
65
  siteConfig.navbar.logo?.type === "image" &&
66
  logoValue &&
67
  !logoValue.startsWith("/") &&
68
  !logoValue.startsWith("http");
69
let logoImg: ImageMetadata | null = null;
70

71
if (isLocalSrcLogo) {
72
  const files = import.meta.glob<ImageMetadata>(
73
    "../../**/*.{png,jpg,jpeg,webp,avif,gif,svg}",
74
    { import: "default" },
75
  );
76
  const normalizedPath = path
77
    .normalize(path.join("../../", logoValue))
78
    .replace(/\\/g, "/");
79
  const file = files[normalizedPath];
80
  if (file) {
81
    logoImg = await file();
82
  }
83
}
84
---
85

86
<div id="navbar" class="z-50"
87
     style={`--navbar-glass-blur: ${navbarBlur}px;`}
88
     data-transparent-mode={navbarTransparentMode}
89
     data-enable-blur={String(navbarEnableBlur)}
90
     data-is-home={isHomePageCheck}
91
     data-full-width={navbarWidthFull}>
92

93
  <div class:list={[
94
    className,
95
    "overflow-visible! h-18 mx-auto flex items-center px-4",
96
    navbarWidthFull ? "" : "justify-between max-w-(--page-width)"
97
  ]}>
98

99
    <!-- ========== Logo + 标题 ========== -->
100
    <a href={url('/')}
101
       class="btn-plain scale-animation rounded-lg h-13 px-5 font-bold active:scale-95 navbar-logo-link">
102
      <div class:list={[
103
        "flex flex-row items-center text-md navbar-logo-content",
104
        siteConfig.navbar.followTheme ? "text-(--primary)" : "dark:text-white text-black"
105
      ]}>
106
        {siteConfig.navbar.logo?.type === "icon" ? (
107
          <Icon name={siteConfig.navbar.logo.value || "material-symbols:home-pin-outline"}
108
                class="text-[1.75rem] mb-1 mr-2 navbar-logo-icon" />
109
        ) : siteConfig.navbar.logo?.type === "image" && logoImg ? (
110
          <Picture src={logoImg} alt={siteConfig.navbar.logo.alt || siteConfig.title}
111
                   class="h-7 w-7 mb-1 mr-2 object-contain navbar-logo-img"
112
                   formats={getImageFormats()}
113
                   fallbackFormat={getFallbackFormat()}
114
                   widths={[28, 56]} loading="eager" fetchpriority="high" />
115
        ) : siteConfig.navbar.logo?.type === "image" ? (
116
          <img src={url(siteConfig.navbar.logo.value)}
117
               alt={siteConfig.navbar.logo.alt || siteConfig.title}
118
               class="h-7 w-7 mb-1 mr-2 object-contain navbar-logo-img"
119
               fetchpriority="high" />
120
        ) : siteConfig.navbar.logo?.type === "url" ? (
121
          <img src={siteConfig.navbar.logo.value}
122
               alt={siteConfig.navbar.logo.alt || siteConfig.title}
123
               class="h-7 w-7 mb-1 mr-2 object-contain navbar-logo-img"
124
               fetchpriority="high" />
125
        ) : (
126
          <Icon name="material-symbols:home-pin-outline"
127
                class="text-[1.75rem] mb-1 mr-2 navbar-logo-icon" />
128
        )}
129
        <span class="navbar-logo-text">{navbarTitle}</span>
130
      </div>
131
    </a>
132

133
    <!-- ========== 桌面端导航链接 ========== -->
134
    <div class="hidden lg:flex items-center space-x-1">
135
      {links.map((l) => {
136
        return <DropdownMenu link={l} />;
137
      })}
138
    </div>
139

140
    <!-- ========== 右侧工具栏 ========== -->
141
    <div class:list={["flex items-center", navbarWidthFull ? "ml-auto" : ""]}>
142
      <!-- 搜索 -->
143
      <Search client:load />
144
      <!-- 音乐播放器开关 -->
145
      {musicPlayerConfig.showInNavbar && (
146
        <button id="music-player-switch"
147
                class="btn-plain rounded-lg h-11 w-11 navbar-icon-btn active:scale-90">
148
          <Icon name="material-symbols:music-note-rounded" class="text-[1.25rem]" />
149
        </button>
150
      )}
151
      <!-- 显示设置开关 -->
152
      {hasDisplaySettings && (
153
        <button id="display-settings-switch"
154
                class="btn-plain rounded-lg h-11 w-11 navbar-icon-btn active:scale-90">
155
          <Icon name="material-symbols:palette-outline" class="text-[1.25rem]" />
156
        </button>
157
      )}
158
      <!-- 亮暗切换 -->
159
      <LightDarkSwitch client:load />
160
      <!-- 汉堡菜单 (移动端) -->
161
      <button id="nav-menu-switch"
162
              class="btn-plain rounded-lg w-11 h-11 lg:hidden! nav-hamburger-btn">
163
        <Icon name="material-symbols:menu-rounded" class="text-[1.5rem] hamburger-icon-menu" />
164
        <Icon name="material-symbols:close-rounded"
165
              class="text-[1.5rem] hamburger-icon-close hidden" />
166
      </button>
167
    </div>
168

169
    <!-- 音乐面板（浮动） -->
170
    {musicPlayerConfig.showInNavbar && (
171
      <div id="music-nav-panel"
172
           class="float-panel float-panel-closed absolute transition-all right-16 p-2 pt-4.5 w-80 z-50">
173
        <MusicPlayer />
174
      </div>
175
    )}
176

177
    <!-- 移动端菜单面板 -->
178
    <NavMenuPanel links={links} siteTitle={navbarTitle} />
179

180
    <!-- 显示设置面板 -->
181
    <DisplaySettings client:load />
182
  </div>
183
</div>

显示更多显示更少

关键技术细节：

Logo 智能加载：通过 import.meta.glob 扫描 src 目录下的所有图片，匹配到本地图片后交给 Astro 的 <Picture> 组件进行自动优化（格式转换、压缩、响应式），而 public 和远程图片则使用原生 <img>
条件渲染：音乐、显示设置、搜索等模块都是条件渲染的，可以通过配置文件一键开关
数据属性传递：透明模式、毛玻璃开关、全宽模式等通过 data-* 属性传递给 CSS，实现纯 CSS 驱动样式变化

4.3 DropdownMenu.astro — 桌面端下拉菜单#

DropdownMenu.astro 处理每个导航链接，自动判断是否有子菜单：

1
---
2
import { Icon } from "astro-icon/components";
3
import DropdownItem from "@/components/common/DropdownItem.astro";
4
import DropdownPanel from "@/components/common/DropdownPanel.astro";
5
import { LinkPresets } from "@/constants/link-presets";
6
import { LinkPreset, type NavBarLink } from "@/types/config";
7
import { url } from "@/utils/url-utils";
8

9
interface Props {
10
  link: NavBarLink;
11
  class?: string;
12
}
13

14
const { link, class: className } = Astro.props;
15

16
if (!link) return null;
17

18
// 将子菜单中的 LinkPreset 枚举转为真实的 NavBarLink 对象
19
const processedLink = {
20
  ...link,
21
  children: link.children
22
    ?.map((child: NavBarLink | LinkPreset): NavBarLink | null => {
23
      if (typeof child === "number") {
24
        if (child in LinkPresets) return LinkPresets[child as LinkPreset];
25
        return null;
26
      }
27
      return child;
28
    })
29
    .filter((child): child is NavBarLink => child !== null),
30
};
31

32
const hasChildren = processedLink.children && processedLink.children.length > 0;
33
---
34

35
<div class:list={["dropdown-container", className]} data-dropdown>
36
  {hasChildren ? (
37
    <>
38
      <!-- 有子菜单：渲染为 button，点击展开下拉 -->
39
      <button
40
        class="btn-plain scale-animation rounded-lg h-11 font-bold px-5
41
               active:scale-95 dropdown-trigger-link navbar-link-item"
42
        data-dropdown-trigger
43
        aria-haspopup="true"
44
        aria-expanded="false"
45
      >
46
        <div class="flex items-center">
47
          {processedLink.icon && (
48
            <Icon name={processedLink.icon} class="text-[1.1rem] mr-2 navbar-icon" />
49
          )}
50
          <span class="navbar-link-text">{processedLink.name}</span>
51
          <Icon name="material-symbols:keyboard-arrow-down-rounded"
52
                class="text-[1.25rem] transition-transform duration-200 dropdown-arrow ml-1" />
53
        </div>
54
      </button>
55
      <!-- 下拉面板 -->
56
      <div class="dropdown-menu" data-dropdown-menu>
57
        <DropdownPanel class="dropdown-content">
58
          {processedLink.children?.map((child, index) => (
59
            <DropdownItem
60
              href={child.external ? child.url : url(child.url)}
61
              target={child.external ? "_blank" : undefined}
62
              isLast={index === (processedLink.children?.length || 0) - 1}
63
              class="dropdown-item"
64
            >
65
              {child.icon && (
66
                <Icon name={child.icon} class="text-[1.25rem] mr-3 navbar-icon" />
67
              )}
68
              <span>{child.name}</span>
69
              {child.external && (
70
                <Icon name="fa7-solid:arrow-up-right-from-square"
71
                      class="text-[0.75rem] text-black/25 dark:text-white/25 ml-auto" />
72
              )}
73
            </DropdownItem>
74
          ))}
75
        </DropdownPanel>
76
      </div>
77
    </>
78
  ) : (
79
    <!-- 无子菜单：渲染为普通链接 -->
80
    <a
81
      href={processedLink.external ? processedLink.url : url(processedLink.url)}
82
      target={processedLink.external ? "_blank" : null}
83
      class="btn-plain scale-animation rounded-lg h-11 font-bold px-5
84
             active:scale-95 navbar-link-item"
85
    >
86
      <div class="flex items-center">
87
        {processedLink.icon && (
88
          <Icon name={processedLink.icon} class="text-[1.1rem] mr-2 navbar-icon" />
89
        )}
90
        <span class="navbar-link-text">{processedLink.name}</span>
91
        {processedLink.external && (
92
          <Icon name="fa7-solid:arrow-up-right-from-square"
93
                class="text-[0.875rem] -translate-y-px ml-1 text-black/20 dark:text-white/20" />
94
        )}
95
      </div>
96
    </a>
97
  )}
98
</div>

显示更多显示更少

下拉菜单交互脚本（is）：

1
(function() {
2
  function initDesktopDropdowns() {
3
    var dropdowns = document.querySelectorAll('[data-dropdown]');
4

5
    dropdowns.forEach(function(dropdown) {
6
      var trigger = dropdown.querySelector('[data-dropdown-trigger]');
7
      var menu = dropdown.querySelector('[data-dropdown-menu]');
8
      if (!trigger || !menu) return;
9

10
      // 克隆节点清除旧事件监听器
11
      var newTrigger = trigger.cloneNode(true);
12
      trigger.parentNode && trigger.parentNode.replaceChild(newTrigger, trigger);
13

14
      // 点击切换下拉
15
      newTrigger.addEventListener('click', function(e) {
16
        e.preventDefault();
17
        e.stopPropagation();
18
        dropdown.classList.toggle('dropdown-open');
19
        var isOpen = dropdown.classList.contains('dropdown-open');
20
        newTrigger.setAttribute('aria-expanded', String(isOpen));
21
      });
22

23
      // 键盘导航：ArrowDown 展开，Escape 关闭
24
      newTrigger.addEventListener('keydown', function(e) {
25
        if (e.key === 'ArrowDown') {
26
          e.preventDefault();
27
          dropdown.classList.add('dropdown-open');
28
          newTrigger.setAttribute('aria-expanded', 'true');
29
          var firstItem = menu.querySelector('.dropdown-item');
30
          if (firstItem) firstItem.focus();
31
        } else if (e.key === 'Escape') {
32
          dropdown.classList.remove('dropdown-open');
33
          newTrigger.setAttribute('aria-expanded', 'false');
34
          newTrigger.focus();
35
        }
36
      });
37
    });
38

39
    // 点击外部关闭所有下拉
40
    document.addEventListener('click', function(e) {
41
      dropdowns.forEach(function(dropdown) {
42
        if (!dropdown.contains(e.target)) {
43
          dropdown.classList.remove('dropdown-open');
44
          var trigger = dropdown.querySelector('[data-dropdown-trigger]');
45
          if (trigger) trigger.setAttribute('aria-expanded', 'false');
46
        }
47
      });
48
    });
49

50
    // Escape 关闭所有
51
    document.addEventListener('keydown', function(e) {
52
      if (e.key === 'Escape') {
53
        dropdowns.forEach(function(dropdown) {
54
          dropdown.classList.remove('dropdown-open');
55
          var trigger = dropdown.querySelector('[data-dropdown-trigger]');
56
          if (trigger) { trigger.setAttribute('aria-expanded', 'false'); trigger.focus(); }
57
        });
58
      });
59
    });
60
  }
61

62
  // 首次加载 + Swup 导航后重新初始化
63
  if (document.readyState === 'loading') {
64
    document.addEventListener('DOMContentLoaded', initDesktopDropdowns);
65
  } else {
66
    initDesktopDropdowns();
67
  }
68
  document.addEventListener('swup:contentReplaced', initDesktopDropdowns);
69
})();

显示更多显示更少

CSS 下拉动画：

1
.dropdown-menu {
2
  @apply absolute top-full left-0 pt-2 opacity-0 invisible pointer-events-none
3
         transition-all duration-200 ease-out transform translate-y-[-8px] z-50;
4
}
5

6
/* 悬停或激活时显示 */
7
.dropdown-container:hover .dropdown-menu,
8
.dropdown-container:focus-within .dropdown-menu,
9
.dropdown-container.dropdown-open .dropdown-menu {
10
  @apply opacity-100 visible pointer-events-auto translate-y-0;
11
}
12

13
/* 箭头旋转动画 */
14
.dropdown-container:hover .dropdown-arrow,
15
.dropdown-container.dropdown-open .dropdown-arrow {
16
  @apply rotate-180;
17
}

显示更多显示更少

4.4 NavMenuPanel.astro — 移动端侧滑菜单#

NavMenuPanel.astro 实现了移动端的侧滑抽屉菜单，包含 个人信息卡片 + 导航链接列表：

核心结构：

1
<!-- 遮罩层 -->
2
<div id="nav-menu-overlay" class="menu-overlay"></div>
3

4
<!-- 侧滑面板 -->
5
<div id="nav-menu-panel" class="menu-panel" data-menu-open="false"
6
     role="dialog" aria-modal="true" aria-hidden="true">
7

8
  <!-- Profile Card: 头像、昵称、简介、统计数据、CTA按钮、社交链接 -->
9
  <div class="menu-profile">
10
    <a href="/about/" class="group relative block w-20 h-20 mb-3
11
       rounded-full overflow-hidden border-2 border-white dark:border-neutral-700">
12
      <ImageWrapper src={profileConfig.avatar} alt="Profile Image"
13
                    class="w-full h-full object-cover"
14
                    loading="eager" fetchpriority="high" />
15
    </a>
16
    <div class="text-center">
17
      <div class="font-bold text-lg">{profileConfig.name}</div>
18
      <div class="text-xs text-neutral-500">{profileConfig.bio}</div>
19
    </div>
20
    <!-- 统计数据：文章数、标签数、动态数 -->
21
    <div class="flex w-full justify-around py-3 border-y">
22
      {stats.map(stat => (
23
        <div class="flex flex-col items-center">
24
          <span class="text-[10px]">{stat.label}</span>
25
          <span class="text-base font-bold">{stat.count}</span>
26
        </div>
27
      ))}
28
    </div>
29
    <!-- CTA 按钮和社交图标 -->
30
    ...
31
  </div>
32

33
  <!-- 导航链接 -->
34
  <nav class="menu-nav">
35
    {processedLinks.map((link) => (
36
      <div>
37
        {link.children?.length > 0 ? (
38
          <!-- 有子菜单：可折叠展开 -->
39
          <div class="menu-dropdown" data-mobile-dropdown>
40
            <button class="menu-link" data-mobile-dropdown-trigger>
41
              {link.icon && <Icon name={link.icon} class="menu-link-icon" />}
42
              <span class="menu-link-text">{link.name}</span>
43
              <Icon name="material-symbols:chevron-right-rounded" class="menu-arrow" />
44
            </button>
45
            <div class="menu-submenu" data-mobile-submenu>
46
              {link.children.map((child) => (
47
                <a href={child.url} class="menu-sublink">
48
                  {child.icon && <Icon name={child.icon} class="menu-link-icon sub-icon" />}
49
                  <span>{child.name}</span>
50
                </a>
51
              ))}
52
            </div>
53
          </div>
54
        ) : (
55
          <!-- 无子菜单：直接链接 -->
56
          <a href={link.url} class="menu-link">
57
            {link.icon && <Icon name={link.icon} class="menu-link-icon" />}
58
            <span class="menu-link-text">{link.name}</span>
59
          </a>
60
        )}
61
      </div>
62
    ))}
63
  </nav>
64
</div>

显示更多显示更少

交互逻辑：

1
// 打开菜单：显示遮罩、侧滑面板、锁定body滚动
2
function openMenu() {
3
  ensureMenuPortal(); // 确保面板挂载到body下（避免被overflow裁剪）
4
  resetDropdowns();
5
  panel.setAttribute("data-menu-open", "true");
6
  overlay.classList.add("active");
7
  btn.classList.add("hamburger-open");
8
  document.body.style.overflow = "hidden";
9
}
10

11
// 关闭菜单：恢复所有状态
12
function closeMenu() {
13
  panel.setAttribute("data-menu-open", "false");
14
  overlay.classList.remove("active");
15
  btn.classList.remove("hamburger-open");
16
  document.body.style.overflow = "";
17
  resetDropdowns();
18
}
19

20
// 注册事件：astro:page-load + swup:page:view
21
document.addEventListener("astro:page-load", init);
22
document.addEventListener("swup:contentReplaced", onPageTransition);

显示更多显示更少

CSS 动画：

1
.menu-panel {
2
  position: fixed; top: 0; right: 0; bottom: 0;
3
  width: min(82vw, 20rem);
4
  height: 100dvh;
5
  background: var(--card-bg);
6
  transform: translate3d(100%, 0, 0);        /* 初始在屏幕外 */
7
  transition: transform 0.3s cubic-bezier(0.4, 0, 0.2, 1);
8
}
9
.menu-panel[data-menu-open="true"] {
10
  transform: translate3d(0, 0, 0);           /* 滑入 */
11
}
12

13
/* 子菜单折叠动画 */
14
.menu-submenu {
15
  max-height: 0; overflow: hidden;
16
  transition: max-height 0.25s ease;
17
}
18
.menu-dropdown[data-expanded="true"] .menu-submenu {
19
  max-height: 20rem;
20
}
21
.menu-dropdown[data-expanded="true"] .menu-arrow {
22
  transform: rotate(90deg);                  /* 箭头旋转 */
23
}

显示更多显示更少

设计亮点：

ensureMenuPortal() 将面板挂载到 body 下，避免被父容器的 overflow: hidden 裁剪
侧滑面板使用 translate3d 触发 GPU 加速，确保流畅动画
子菜单使用 max-height 过渡实现折叠动画，同时箭头旋转 90°

4.5 公共组件：DropdownPanel 和 DropdownItem#

DropdownPanel.astro — 下拉面板容器：

1
<div class:list={["float-panel p-2", className]} role="none">
2
  <slot />
3
</div>

DropdownItem.astro — 下拉选项项：

1
---
2
interface Props {
3
  href?: string;
4
  target?: string;
5
  isActive?: boolean;
6
  isLast?: boolean;
7
  class?: string;
8
  onclick?: string;
9
}
10

11
const Tag = href ? "a" : "button";
12
---
13

14
<Tag href={href} target={target} class={allClasses} onclick={onclick}>
15
  <slot />
16
</Tag>

显示更多显示更少

这两个组件非常精简，作为通用 UI 原子被导航栏下拉菜单、亮暗色切换面板、显示设置面板等多处复用。

4.6 Search.svelte — 搜索组件#

Search.svelte 基于 Pagefind 实现全文搜索：

1
<script lang="ts">
2
import { onMount } from "svelte";
3

4
let keywordDesktop = "";
5
let keywordMobile = "";
6
let result: SearchResult[] = [];
7
let isSearching = false;
8
let initialized = false;
9

10
// 300ms 防抖搜索
11
const search = async (keyword: string, isDesktop: boolean): Promise<void> => {
12
  if (!keyword) { setPanelVisibility(false, isDesktop); return; }
13
  if (!initialized) return;
14

15
  isSearching = true;
16
  clearTimeout(debounceTimer);
17
  debounceTimer = setTimeout(async () => {
18
    try {
19
      let searchResults: SearchResult[] = [];
20
      if (import.meta.env.PROD && window.pagefind) {
21
        const response = await window.pagefind.search(keyword);
22
        searchResults = await Promise.all(
23
          response.results.map((item) => item.data()),
24
        );
25
      } else if (import.meta.env.DEV) {
26
        searchResults = fakeResult; // 开发环境使用假数据
27
      }
28
      result = searchResults;
29
    } finally {
30
      isSearching = false;
31
    }
32
  }, 300);
33
};
34

35
onMount(() => {
36
  // 等待 Pagefind 初始化完成
37
  if (window.pagefind) {
38
    initialized = true;
39
  } else {
40
    document.addEventListener("pagefindready", () => { initialized = true; });
41
  }
42
});
43
</script>
44

45
<!-- 桌面端搜索框：favorite 展开 -->
46
<div id="search-bar" class="hidden lg:flex ...">
47
  <Icon icon="material-symbols:search" />
48
  <input bind:value={keywordDesktop}
49
         class="h-full w-40 focus:w-60 transition-all ..." />
50
</div>
51

52
<!-- 移动端搜索按钮 -->
53
<button id="search-switch" class="btn-plain lg:hidden! ...">
54
  <Icon icon="material-symbols:search" />
55
</button>
56

57
<!-- 搜索结果面板 -->
58
<div id="search-panel" class="float-panel float-panel-closed ...">
59
  {#if isSearching}
60
    <div>搜索中...</div>
61
  {:else if result.length > 0}
62
    {#each result.slice(0, 5) as item}
63
      <a href={item.url} class="group block rounded-xl px-3 py-2 ...">
64
        <div class="flex items-center">
65
          {@html item.meta.title}
66
          <Icon icon="fa7-solid:chevron-right" />
67
        </div>
68
        {#if item.excerpt.includes('<mark>')}
69
          <div class="flex items-start mt-0.5">
70
            <span class="badge">摘要</span>
71
            <div>{@html item.excerpt}</div>
72
          </div>
73
        {/if}
74
      </a>
75
    {/each}
76
    {#if result.length > 5}
77
      <a href={getSearchUrl(keyword)}>查看更多结果 ({result.length - 5} 个更多)</a>
78
    {/if}
79
  {:else if result.length === 0}
80
    <div>找不到相关结果</div>
81
  {/if}
82
</div>

显示更多显示更少

4.7 LightDarkSwitch.svelte — 亮暗色切换#

LightDarkSwitch.svelte 集成在导航栏右侧：

1
<script lang="ts">
2
import { DARK_MODE, LIGHT_MODE, SYSTEM_MODE } from "@/constants/constants";
3
import type { LIGHT_DARK_MODE } from "@/types/config";
4
import { getStoredTheme, setTheme } from "@/utils/setting-utils";
5

6
let mode: LIGHT_DARK_MODE = $state(LIGHT_MODE);
7
let displayedMode: LIGHT_DARK_MODE = $state(LIGHT_MODE);
8

9
function switchScheme(newMode: LIGHT_DARK_MODE) {
10
  mode = newMode;
11
  setTheme(newMode);
12
}
13

14
// 在 system 模式下显示实际主题图标
15
function updateDisplayedMode() {
16
  if (mode === SYSTEM_MODE) {
17
    const isSystemDark = window.matchMedia(
18
      "(prefers-color-scheme: dark)",
19
    ).matches;
20
    displayedMode = isSystemDark ? DARK_MODE : LIGHT_MODE;
21
  } else {
22
    displayedMode = mode;
23
  }
24
}
25

26
onMount(() => {
27
  const storedTheme = getStoredTheme();
28
  mode = storedTheme;
29
  updateDisplayedMode();
30
  // 监听系统主题变化
31
  if (storedTheme === SYSTEM_MODE) {
32
    const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
33
    mediaQuery.addEventListener("change", () => updateDisplayedMode());
34
  }
35
});
36
</script>
37

38
<div class="relative z-50">
39
  <button id="scheme-switch" class="btn-plain rounded-lg h-11 w-11 navbar-icon-btn">
40
    <!-- 使用 opacity 切换太阳/月亮图标 -->
41
    <div class:opacity-0={displayedMode !== LIGHT_MODE}>
42
      <Icon icon="material-symbols:wb-sunny-outline-rounded" />
43
    </div>
44
    <div class:opacity-0={displayedMode !== DARK_MODE}>
45
      <Icon icon="material-symbols:dark-mode-outline-rounded" />
46
    </div>
47
  </button>
48

49
  <!-- 下拉面板：亮色/暗色/跟随系统 -->
50
  <div id="theme-mode-panel" class="float-panel-closed ...">
51
    <DropdownPanel>
52
      <DropdownItem isActive={mode === LIGHT_MODE}
53
                    onclick={() => switchScheme(LIGHT_MODE)}>
54
        {i18n(I18nKey.lightMode)}
55
      </DropdownItem>
56
      <DropdownItem isActive={mode === DARK_MODE}
57
                    onclick={() => switchScheme(DARK_MODE)}>
58
        {i18n(I18nKey.darkMode)}
59
      </DropdownItem>
60
      <DropdownItem isActive={mode === SYSTEM_MODE}
61
                    onclick={() => switchScheme(SYSTEM_MODE)}>
62
        {i18n(I18nKey.systemMode)}
63
      </DropdownItem>
64
    </DropdownPanel>
65
  </div>
66
</div>

显示更多显示更少

4.8 DisplaySettingsIntegrated.svelte — 显示设置面板#

DisplaySettingsIntegrated.svelte 提供壁纸模式、主题色相、布局切换等设置：

1
<script lang="ts">
2
import { WALLPAPER_BANNER, WALLPAPER_NONE, WALLPAPER_OVERLAY } from "@constants/constants";
3
import { getHue, setHue, getStoredWallpaperMode, setWallpaperMode } from "@utils/setting-utils";
4

5
let hue = $state(getHue());
6
let wallpaperMode: WALLPAPER_MODE = $state(backgroundWallpaper.mode);
7
let currentLayout: "list" | "grid" = $state("list");
8

9
function switchWallpaperMode(newMode: WALLPAPER_MODE) {
10
  wallpaperMode = newMode;
11
  setWallpaperMode(newMode);
12
}
13

14
function switchLayout() {
15
  currentLayout = currentLayout === "list" ? "grid" : "list";
16
  localStorage.setItem("postListLayout", currentLayout);
17
  window.dispatchEvent(new CustomEvent("layoutChange", { detail: { layout: currentLayout } }));
18
}
19
</script>
20

21
<div id="display-setting" class="float-panel float-panel-closed ...">
22
  <!-- 主题色相滑块 -->
23
  <div>
24
    <span>主题色相</span>
25
    <input type="range" min="0" max="360" bind:value={hue} step="5" />
26
  </div>
27

28
  <!-- 壁纸模式切换（横幅/全屏透明/纯色） -->
29
  <div>
30
    <button onclick={() => switchWallpaperMode(WALLPAPER_BANNER)}>横幅壁纸</button>
31
    <button onclick={() => switchWallpaperMode(WALLPAPER_OVERLAY)}>全屏壁纸</button>
32
    <button onclick={() => switchWallpaperMode(WALLPAPER_NONE)}>纯色背景</button>
33
  </div>
34

35
  <!-- 文章布局切换（列表/网格） -->
36
  <div>
37
    <button onclick={switchLayout}>列表</button>
38
    <button onclick={switchLayout}>网格</button>
39
  </div>
40
</div>

显示更多显示更少

4.9 按钮交互脚本#

Navbar.astro 中的内联脚本处理所有浮动面板的打开/关闭和点击外部关闭逻辑：

1
function loadButtonScript() {
2
  // 显示设置按钮 → 切换面板
3
  document.getElementById("display-settings-switch").onclick = () => {
4
    document.getElementById("display-setting")
5
      ?.classList.toggle("float-panel-closed");
6
  };
7

8
  // 音乐按钮 → 切换面板
9
  document.getElementById("music-player-switch").onclick = () => {
10
    document.getElementById("music-nav-panel")
11
      ?.classList.toggle("float-panel-closed");
12
  };
13

14
  // 主题按钮 → 切换面板
15
  document.getElementById("scheme-switch").onclick = () => {
16
    document.getElementById("theme-mode-panel")
17
      ?.classList.toggle("float-panel-closed");
18
  };
19

20
  // 点击外部关闭所有面板
21
  document.addEventListener("click", (event) => {
22
    const panels = ["display-setting", "music-nav-panel", "theme-mode-panel"];
23
    const buttons = ["display-settings-switch", "music-player-switch", "scheme-switch"];
24
    panels.forEach((id, i) => {
25
      const panel = document.getElementById(id);
26
      const button = document.getElementById(buttons[i]);
27
      if (panel && button && !panel.classList.contains("float-panel-closed")) {
28
        if (!panel.contains(event.target) && !button.contains(event.target)) {
29
          panel.classList.add("float-panel-closed");
30
        }
31
      }
32
    });
33
  });
34
}

显示更多显示更少

五、样式层 — 导航栏 CSS#

5.1 透明模式系统#

navbar.css 实现了三种透明模式的完整样式，按屏幕尺寸和亮暗主题分四组定义：

模式	外观	行为
`semi`	毛玻璃半透明 + 阴影	始终可见
`full`	完全透明，无阴影	始终透明
`semifull`	初始透明 → 滚动后变半透明	动态切换

CSS 变量注入：

1
<!-- Navbar.astro 中通过 style 属性注入 --->
2
<div id="navbar"
3
     style="--navbar-glass-blur: ${navbarBlur}px;"
4
     data-transparent-mode="semifull"
5
     data-enable-blur="true">

桌面端亮色 - semifull 模式：

1
/* 初始状态：完全透明 */
2
#navbar[data-transparent-mode="semifull"] > div {
3
  background: transparent !important;
4
  border: none !important;
5
  box-shadow: none !important;
6
}
7

8
/* 滚动后（.scrolled）：半透明毛玻璃 */
9
#navbar[data-transparent-mode="semifull"].scrolled > div {
10
  backdrop-filter: blur(var(--navbar-glass-blur, 20px)) !important;
11
  background: rgba(255, 255, 255, 0.55) !important;
12
  border: 1px solid rgba(255, 255, 255, 0.55) !important;
13
  box-shadow: var(--shadow-navbar) !important;
14
}

暗色主题同理：

1
:root.dark #navbar[data-transparent-mode="semifull"].scrolled > div {
2
  background: rgba(0, 0, 0, 0.55) !important;
3
  border: 1px solid rgba(0, 0, 0, 0.55) !important;
4
  box-shadow: var(--shadow-navbar-dark) !important;
5
}

关闭毛玻璃：

1
#navbar[data-enable-blur="false"] > div {
2
  backdrop-filter: none !important;
3
}

5.2 滚动检测脚本#

Navbar.astro 中的 semifull 滚动检测使用 requestAnimationFrame 优化性能：

1
function initSemifullScrollDetection() {
2
  const navbar = document.getElementById('navbar');
3
  if (!navbar) return;
4
  if (navbar.getAttribute('data-transparent-mode') !== 'semifull') return;
5

6
  let ticking = false;
7

8
  function updateNavbarState() {
9
    const scrollTop = window.pageYOffset || document.documentElement.scrollTop;
10
    const threshold = 50; // 滚动50px后触发状态切换
11
    if (scrollTop > threshold) {
12
      navbar.classList.add('scrolled');
13
    } else {
14
      navbar.classList.remove('scrolled');
15
    }
16
    ticking = false;
17
  }
18

19
  function requestTick() {
20
    if (!ticking) {
21
      requestAnimationFrame(updateNavbarState);
22
      ticking = true;
23
    }
24
  }
25

26
  window.addEventListener('scroll', requestTick, { passive: true });
27
}
28

29
// 页面加载完成 + Swup导航后重新初始化
30
document.addEventListener('astro:page-load', initSemifullScrollDetection);
31
document.addEventListener('swup:contentReplaced', initSemifullScrollDetection);

显示更多显示更少

5.3 导航链接下划线效果#

全部导航链接（包括 Logo、菜单项、图标按钮）都使用主题色渐变下划线：

1
/* 菜单链接 */
2
#navbar .dropdown-container > a .navbar-link-text::after {
3
  content: '';
4
  position: absolute;
5
  bottom: -2px; left: 0;
6
  width: 100%; height: 2px;
7
  background: linear-gradient(90deg, var(--primary), var(--primary));
8
  border-radius: 1px;
9
  transform: scaleX(0);
10
  transform-origin: center;
11
  transition: transform 0.3s cubic-bezier(0.4, 0, 0.2, 1);
12
}
13

14
#navbar .dropdown-container > a:hover .navbar-link-text::after {
15
  transform: scaleX(1);
16
}
17

18
/* Logo 同款下划线 */
19
.navbar-logo-content::after {
20
  content: '';
21
  position: absolute;
22
  bottom: -4px; left: 0;
23
  width: 100%; height: 2px;
24
  background: linear-gradient(90deg, var(--primary), var(--primary));
25
  transform: scaleX(0);
26
  transition: transform 0.3s cubic-bezier(0.4, 0, 0.2, 1);
27
}
28

29
/* 图标按钮下划线 */
30
.navbar-icon-btn::after {
31
  content: '';
32
  position: absolute;
33
  bottom: 2px; left: 50%;
34
  transform: translateX(-50%) scaleX(0);
35
  width: 20px; height: 2px;
36
  background: linear-gradient(90deg, var(--primary), var(--primary));
37
  transition: transform 0.3s cubic-bezier(0.4, 0, 0.2, 1);
38
}

显示更多显示更少

5.4 响应式适配#

1
/* 平板端隐藏导航栏图标，节省空间 */
2
@media (max-width: 1199px) {
3
  .navbar-icon { display: none !important; }
4
}
5

6
/* 窗口缩小逐渐缩小文字 */
7
@media (max-width: 1400px) {
8
  #navbar .dropdown-container > a {
9
    font-size: 0.875rem !important;
10
  }
11
}
12

13
/* 移动端隐藏下拉菜单，汉堡菜单接管 */
14
@media (max-width: 768px) {
15
  .dropdown-container { display: none; }
16
}
17

18
/* 桌面端隐藏侧滑菜单 */
19
@media (min-width: 1024px) {
20
  .menu-overlay, .menu-panel { display: none !important; }
21
}

显示更多显示更少

5.5 全宽导航栏#

1
@media (min-width: 1024px) {
2
  #navbar[data-full-width="true"] > div {
3
    border-radius: 0 !important;
4
    width: 100% !important;
5
    max-width: none !important;
6
  }
7
}

六、架构总结#

整个导航栏模块的完整构建方案可以概括为以下架构图：

1
┌─────────────────────────────────────────────────────────┐
2
│                    五层架构                              │
3
├─────────────────┬───────────────────────────────────────┤
4
│ 1. 类型定义层    │ src/types/config.ts                   │
5
│                 │  - LinkPreset 枚举                     │
6
│                 │  - NavBarLink 类型                     │
7
│                 │  - NavBarConfig 类型                   │
8
├─────────────────┼───────────────────────────────────────┤
9
│ 2. 常量层        │ src/constants/link-presets.ts         │
10
│                 │  - LinkPresets 对象映射                │
11
│                 │  - i18n 集成（多语言文本）              │
12
├─────────────────┼───────────────────────────────────────┤
13
│ 3. 配置层        │ src/config/navBarConfig.ts            │
14
│                 │  - 动态菜单生成                        │
15
│                 │  - 页面开关控制子菜单                   │
16
│                 │ src/config/siteConfig.ts               │
17
│                 │  - Logo, 标题, 全宽                    │
18
│                 │ src/config/backgroundWallpaper.ts      │
19
│                 │  - 透明模式, 毛玻璃                     │
20
├─────────────────┼───────────────────────────────────────┤
21
│ 4. 组件层        │ Navbar.astro (主容器)                  │
22
│                 │ ├── DropdownMenu.astro (桌面下拉)       │
23
│                 │ ├── NavMenuPanel.astro (移动端侧滑)     │
24
│                 │ ├── Search.svelte (搜索)               │
25
│                 │ ├── LightDarkSwitch.svelte (主题切换)   │
26
│                 │ ├── DisplaySettings.svelte (显示设置)   │
27
│                 │ ├── DropdownPanel/DropdownItem (通用)   │
28
│                 │ └── 嵌入位置: MainGridLayout.astro      │
29
├─────────────────┼───────────────────────────────────────┤
30
│ 5. 样式层        │ src/styles/navbar.css                 │
31
│                 │  - 3种透明模式 × 2个主题 × 2个设备      │
32
│                 │  - 下划线hover动画                      │
33
│                 │  - 响应式适配                           │
34
│                 │  - 全宽/半宽适配                        │
35
│                 │ DropdownMenu内联样式                    │
36
│                 │  - 下拉动画                            │
37
│                 │ NavMenuPanel内联样式                    │
38
│                 │  - 侧滑动画 + 子菜单折叠                │
39
└─────────────────┴───────────────────────────────────────┘

显示更多显示更少

核心设计思想：

关注点分离：类型 → 常量 → 配置 → 组件 → 样式，每层只关心自己的职责
条件渲染：所有可选模块通过配置文件控制，无需修改组件代码
i18n 优先：所有展示文本通过 i18n() 函数获取，预设链接也使用 i18n 文本
性能优先：滚动检测使用 requestAnimationFrame 节流，下拉菜单使用 CSS 动画而非 JS 动画
多端统一：桌面端下拉菜单 + 移动端侧滑面板，同一套配置数据驱动两种 UI 形态
GPU 加速：透明效果使用 backdrop-filter + GPU 层的 translate3d，避免重绘

日志技术

Fri, 22 May 2026 00:00:00 GMT

日志技术#

定义#

日志用于记录应用程序的运行信息、状态信息和错误信息。专业的日志框架（如 Logback）替代 System.out.println，提供灵活的日志级别控制、多种输出目标（控制台/文件）和格式化能力。

为什么需要日志框架#

使用 System.out.println(...) 记录日志的缺陷：

硬编码：无法灵活控制输出与否，只能删除代码
输出受限：只能输出到控制台
不便于扩展维护：无法按级别过滤、按格式输出

日志框架对比#

框架	特点
JUL	JavaSE 官方日志框架，配置简单但不够灵活，性能较差
Log4j	流行的日志框架，灵活的配置选项，支持多种输出目标
Logback	基于 Log4j 升级，更多功能和配置选项，性能优于 Log4j
Slf4j	简单日志门面，提供标准接口，允许切换底层日志框架

Logback 入门#

依赖引入#

SpringBoot 已内置传递 Logback 依赖，无需额外引入。若单独使用：

1
<dependency>
2
    <groupId>ch.qos.logback</groupId>
3
    <artifactId>logback-classic</artifactId>
4
    <version>1.4.11</version>
5
</dependency>

配置文件 logback.xml#

放置在 src/main/resources 目录下：

1
<?xml version="1.0" encoding="UTF-8"?>
2
<configuration>
3
    <!-- 控制台输出 -->
4
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
5
        <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
6
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50}-%msg%n</pattern>
7
        </encoder>
8
    </appender>
9

10
    <!-- 日志输出级别 -->
11
    <root level="ALL">
12
        <appender-ref ref="STDOUT" />
13
    </root>
14
</configuration>

基本使用#

1
public class LogTest {
2
    private static final Logger log = LoggerFactory.getLogger(LogTest.class);
3

4
    @Test
5
    public void testLog() {
6
        log.debug("开始计算...");
7
        int sum = 0;
8
        int[] nums = {1, 5, 3, 2, 1, 4, 5, 4, 6, 7, 4, 34, 2, 23};
9
        for (int i = 0; i < nums.length; i++) {
10
            sum += nums[i];
11
        }
12
        log.info("计算结果为: " + sum);
13
        log.debug("结束计算...");
14
    }
15
}

显示更多显示更少

Pattern 格式化占位符说明：

占位符	含义
`%d`	日期
`%thread`	线程名
`%-5level`	日志级别，左对齐 5 字符宽度
`%logger{50}`	Logger 名称，最长 50 字符
`%msg`	日志消息
`%n`	换行符

输出到文件#

1
<appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
2
    <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
3
        <FileNamePattern>D:/tlias-%d{yyyy-MM-dd}-%i.log</FileNamePattern>
4
        <MaxHistory>30</MaxHistory>
5
        <maxFileSize>10MB</maxFileSize>
6
    </rollingPolicy>
7
    <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
8
        <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50}-%msg%n</pattern>
9
    </encoder>
10
</appender>

关键配置项：

配置项	说明
`FileNamePattern`	日志文件名模式，`%i` 表示序号
`MaxHistory`	最多保留的历史日志文件数量
`maxFileSize`	单个文件最大大小，超出触发滚动

日志级别#

级别由低到高：TRACE → DEBUG → INFO → WARN → ERROR

<root level="info"> 表示仅输出大于等于 INFO 级别的日志（INFO / WARN / ERROR），DEBUG 和 TRACE 不会输出。

常用配置：

1
<root level="info">
2
    <appender-ref ref="STDOUT" />
3
    <appender-ref ref="FILE" />
4
</root>

配置值	效果
ALL	输出所有级别日志
OFF	关闭所有日志
INFO	仅输出 INFO、WARN、ERROR（生产环境推荐）
DEBUG	输出 DEBUG 及以上（开发调试推荐）

案例实战：@Slf4j 注解#

Lombok 提供的 @Slf4j 注解可简化日志记录器定义，等价于：

1
private static Logger log = LoggerFactory.getLogger(Xxx.class);

在 DeptController 中应用：

1
@Slf4j
2
@RequestMapping("/depts")
3
@RestController
4
public class DeptController {
5

6
    @Autowired
7
    private DeptService deptService;
8

9
    @GetMapping
10
    public Result list() {
11
        log.info("查询部门列表");
12
        List<Dept> deptList = deptService.findAll();
13
        return Result.success(deptList);
14
    }
15

16
    @DeleteMapping
17
    public Result delete(Integer id) {
18
        log.info("根据id删除部门, id: {}", id);
19
        deptService.deleteById(id);
20
        return Result.success();
21
    }
22

23
    @PostMapping
24
    public Result save(@RequestBody Dept dept) {
25
        log.info("新增部门, dept: {}", dept);
26
        deptService.save(dept);
27
        return Result.success();
28
    }
29

30
    @GetMapping("/{id}")
31
    public Result getById(@PathVariable Integer id) {
32
        log.info("根据ID查询, id: {}", id);
33
        Dept dept = deptService.getById(id);
34
        return Result.success(dept);
35
    }
36

37
    @PutMapping
38
    public Result update(@RequestBody Dept dept) {
39
        log.info("修改部门, dept: {}", dept);
40
        deptService.update(dept);
41
        return Result.success();
42
    }
43
}

显示更多显示更少

使用 log.info("xxx {}", var) 占位符风格替代字符串拼接，性能更优。

常见场景#

生产环境设为 INFO 级别记录关键业务操作
开发调试时设为 DEBUG 级别查看详细执行过程
将日志输出到文件并按日期/大小滚动，便于持久化追踪

注意事项#

SpringBoot 已内置 Logback，无需额外引入依赖
logback.xml 需放在 src/main/resources 下
使用 @Slf4j 注解可省略手动定义 Logger
日志消息推荐使用 {} 占位符而非字符串拼接
生产环境不建议使用 System.out.println，应统一使用日志框架

开发规范与工程搭建

Thu, 21 May 2026 00:00:00 GMT

开发规范与工程搭建#

定义#

在 Tlias 智能学习辅助系统的实战开发中，首先需要建立统一的开发规范并完成基础工程搭建。这包括前后端分离开发模式、RESTful API 风格约定、接口测试工具的使用，以及 SpringBoot 工程的基础结构搭建。

开发规范#

前后端分离开发#

企业项目开发主要有两种模式：前后台混合开发和前后台分离开发。

前后台混合开发的缺点：

沟通成本高：后台发现前端问题需找前端修改，再交回后台
分工不明确：后台开发需同时写前端代码
不便管理：所有代码在一个工程中
难以维护：前端更新需要整个工程重新打包部署

前后台分离开发将工程分为前端工程和后端工程，前端交给专业前端人员，后端交给专业后端人员，双方通过接口文档约定数据格式。

前后端分离开发

后端开发功能的具体流程：

后端开发流程

需求分析：阅读需求文档，分析需求
接口定义：查询接口文档中关于需求的接口定义（地址、参数、响应数据类型等）
前后台并行开发：各自按照接口文档进行开发
测试：各自按照接口文档进行测试
前后端联调测试：前端工程请求后端工程，测试功能

RESTful 风格#

REST（Representational State Transfer），表述性状态转换，是一种软件架构风格。

传统 URL 风格：

http://localhost:8080/user/getById?id=1 — GET：查询 id 为 1 的用户
http://localhost:8080/user/saveUser — POST：新增用户
http://localhost:8080/user/updateUser — POST：修改用户
http://localhost:8080/user/deleteUser?id=1 — GET：删除 id 为 1 的用户

传统 URL 将资源访问行为暴露在外，且不同开发人员命名习惯各异（getById、selectById、queryById），难以统一维护。

基于 REST 风格 URL：

http://localhost:8080/users/1 — GET：查询 id 为 1 的用户
http://localhost:8080/users — POST：新增用户
http://localhost:8080/users — PUT：修改用户
http://localhost:8080/users/1 — DELETE：删除 id 为 1 的用户

核心原则：通过 URL 定位要操作的资源，通过 HTTP 动词（请求方式）来描述具体的操作。

请求方式	操作
GET	查询
POST	新增
PUT	修改
DELETE	删除

注意事项：

REST 是风格、约定方式，约定不是规定，可以打破
描述模块功能通常使用复数（加 s），表示此类资源而非单个资源。如：users、emps、books

Apifox 工具#

Apifox 是一款集成了 API 文档、API 调试、API Mock、API 测试的一体化协作平台。

作用：接口文档管理、接口请求测试、Mock 服务
官网：https://apifox.com/

在前后端并行开发时，由于浏览器只能发起 GET 请求，无法直接测试 POST、DELETE、PUT 等接口，需要借助 Apifox 等接口测试工具完成接口测试。

工程搭建#

创建 SpringBoot 工程#

引入 web 开发起步依赖、MyBatis、MySQL 驱动、Lombok。

数据库准备#

创建 tlias 数据库，准备 dept 部门表：

1
CREATE TABLE dept (
2
  id int unsigned PRIMARY KEY AUTO_INCREMENT COMMENT 'ID, 主键',
3
  name varchar(10) NOT NULL UNIQUE COMMENT '部门名称',
4
  create_time datetime DEFAULT NULL COMMENT '创建时间',
5
  update_time datetime DEFAULT NULL COMMENT '修改时间'
6
) COMMENT '部门表';
7

8
INSERT INTO dept VALUES (1,'学工部','2023-09-25 09:47:40','2024-07-25 09:47:40'),
9
                      (2,'教研部','2023-09-25 09:47:40','2024-08-09 15:17:04'),
10
                      (3,'咨询部','2023-09-25 09:47:40','2024-07-30 21:26:24'),
11
                      (4,'就业部','2023-09-25 09:47:40','2024-07-25 09:47:40'),
12
                      (5,'人事部','2023-09-25 09:47:40','2024-07-25 09:47:40'),
13
                      (6,'行政部','2023-11-30 20:56:37','2024-07-30 20:56:37');

application.yml 配置#

1
spring:
2
  application:
3
    name: tlias-web-management
4
  datasource:
5
    driver-class-name: com.mysql.cj.jdbc.Driver
6
    url: jdbc:mysql://localhost:3306/tlias
7
    username: root
8
    password: 1234
9
mybatis:
10
  configuration:
11
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

基础代码结构#

实体类 Dept：

1
package com.itheima.pojo;
2

3
import lombok.AllArgsConstructor;
4
import lombok.Data;
5
import lombok.NoArgsConstructor;
6
import java.time.LocalDateTime;
7

8
@Data
9
@NoArgsConstructor
10
@AllArgsConstructor
11
public class Dept {
12
    private Integer id;
13
    private String name;
14
    private LocalDateTime createTime;
15
    private LocalDateTime updateTime;
16
}

显示更多显示更少

统一响应结果 Result：

1
package com.itheima.pojo;
2

3
import lombok.Data;
4
import java.io.Serializable;
5

6
@Data
7
public class Result {
8
    private Integer code;  // 编码：1成功，0失败
9
    private String msg;    // 错误信息
10
    private Object data;   // 数据
11

12
    public static Result success() {
13
        Result result = new Result();
14
        result.code = 1;
15
        result.msg = "success";
16
        return result;
17
    }
18

19
    public static Result success(Object object) {
20
        Result result = new Result();
21
        result.data = object;
22
        result.code = 1;
23
        result.msg = "success";
24
        return result;
25
    }
26

27
    public static Result error(String msg) {
28
        Result result = new Result();
29
        result.msg = msg;
30
        result.code = 0;
31
        return result;
32
    }
33
}

显示更多显示更少

基础骨架类：

1
// DeptMapper
2
@Mapper
3
public interface DeptMapper {
4
}
5

6
// DeptService
7
public interface DeptService {
8
}
9

10
// DeptServiceImpl
11
@Service
12
public class DeptServiceImpl implements DeptService {
13
}
14

15
// DeptController
16
@RestController
17
public class DeptController {
18
}

显示更多显示更少

常见场景#

新项目启动时，首先确定前后端分离架构和接口规范
使用 Apifox 管理 API 文档，前后端并行开发
规范 RESTful 风格的 URL 设计，保证团队协作一致性

注意事项#

REST 是约定而非强制规范，特殊场景可打破
资源路径建议使用复数形式（如 /depts）
接口文档是前后端协作的核心契约，后端必须严格遵守
SpringBoot 工程中 Lombok 可简化实体类代码，减少样板代码

部门新增功能

Thu, 21 May 2026 00:00:00 GMT

部门新增功能#

定义#

部门新增功能用于保存新的部门数据。前端以 JSON 格式传递部门名称，后端通过 @RequestBody 注解将 JSON 数据绑定到实体对象，完成数据持久化。

接口描述#

请求方式：POST
请求路径：/depts
请求参数：JSON 格式 {"name":"研发部"}
响应数据：Result（统一响应结果）

实现思路#

新增部门三层架构

Controller 层：接收前端 JSON 请求参数，调用 Service 保存部门
Service 层：补全基础属性（创建时间、修改时间），调用 Mapper 保存
Mapper 层：执行 INSERT SQL 语句

JSON 参数接收#

前端传递 JSON 格式参数时，使用实体对象接收。

规则：JSON 数据的键名与方法形参对象的属性名相同，并使用 @RequestBody 注解标识。

JSON参数接收

如上图，JSON {"name":"研发部"} 通过 @RequestBody 绑定到 Dept 对象的 name 属性。

代码实现#

Controller 层#

1
@PostMapping("/depts")
2
public Result save(@RequestBody Dept dept) {
3
    System.out.println("新增部门, dept=" + dept);
4
    deptService.save(dept);
5
    return Result.success();
6
}

Service 层#

1
// DeptService 接口
2
void save(Dept dept);
3

4
// DeptServiceImpl 实现
5
public void save(Dept dept) {
6
    // 补全基础属性
7
    dept.setCreateTime(LocalDateTime.now());
8
    dept.setUpdateTime(LocalDateTime.now());
9
    // 保存部门
10
    deptMapper.insert(dept);
11
}

Service 层负责补全 createTime 和 updateTime 等非前端传入的基础属性。

Mapper 层#

1
@Insert("insert into dept(name, create_time, update_time) values(#{name}, #{createTime}, #{updateTime})")
2
void insert(Dept dept);

在 Mapper 接口中传递多个参数时，封装到一个对象中。SQL 中 #{...} 内写的是对象的属性名，不是表的字段名。

常见场景#

表单提交新增记录，前端发送 JSON 请求体
批量导入时循环调用新增接口

注意事项#

@RequestBody 注解必须加在 Controller 方法形参前，否则无法绑定 JSON
JSON 的 key 必须与实体类属性名一致
#{...} 中应填写 Java 对象的属性名（驼峰命名），而非数据库字段名
Service 层负责补全非业务字段（如时间戳），保持 Controller 层简洁

部门删除功能

Thu, 21 May 2026 00:00:00 GMT

部门删除功能#

定义#

部门删除功能根据 ID 删除指定部门数据。核心知识点包括简单参数的接收方式（HttpServletRequest、@RequestParam、形参自动绑定）以及 MyBatis 的 DELETE 注解使用。

接口描述#

请求方式：DELETE
请求路径：/depts
请求参数：id（Integer，部门 ID）
响应数据：Result（统一响应结果）

实现思路#

删除部门三层架构

Controller 层：接收前端传递的部门 ID，调用 Service 删除
Service 层：调用 Mapper 接口方法，执行删除操作
Mapper 层：执行 DELETE SQL 语句

简单参数接收#

在 Controller 中接收前端传递的简单参数（如 ?id=1），有三种方案：

方案一：HttpServletRequest（不推荐）#

1
@DeleteMapping("/depts")
2
public Result delete(HttpServletRequest request) {
3
    String idStr = request.getParameter("id");
4
    int id = Integer.parseInt(idStr);
5
    System.out.println("根据ID删除部门: " + id);
6
    return Result.success();
7
}

需要手动获取参数并进行类型转换，较为繁琐，项目开发很少使用。

方案二：@RequestParam 注解#

1
@DeleteMapping("/depts")
2
public Result delete(@RequestParam("id") Integer deptId) {
3
    System.out.println("根据ID删除部门: " + deptId);
4
    return Result.success();
5
}

@RequestParam 的 value 属性需与前端传递的参数名一致。required 属性默认为 true，参数必须传递；若可选，设置为 false。

方案三：形参名匹配（推荐）#

1
@DeleteMapping("/depts")
2
public Result delete(Integer id) {
3
    System.out.println("根据ID删除部门: " + id);
4
    return Result.success();
5
}

请求参数名与形参变量名相同时，直接定义方法形参即可接收，无需额外注解。

代码实现#

Controller 层#

1
@DeleteMapping("/depts")
2
public Result delete(Integer id) {
3
    System.out.println("根据id删除部门, id=" + id);
4
    deptService.deleteById(id);
5
    return Result.success();
6
}

Service 层#

1
// DeptService 接口
2
void deleteById(Integer id);
3

4
// DeptServiceImpl 实现
5
public void deleteById(Integer id) {
6
    deptMapper.deleteById(id);
7
}

Mapper 层#

1
@Delete("delete from dept where id = #{id}")
2
void deleteById(Integer id);

Mapper 接口方法形参只有一个普通类型参数时，#{…} 里面的属性名可以随便写（如 #{id}、#{value}）
DML 语句执行完毕有返回值（影响的记录数），可将方法返回值设为 Integer，但通常不需要，设为 void 即可

常见场景#

列表页行内删除按钮，传递行 ID 调用删除接口
批量删除时循环调用或扩展为接收 ID 列表

注意事项#

推荐使用方案三（形参名匹配），代码最简洁
@RequestParam 的 required 默认为 true，参数缺失会报错
DML 语句的 #{...} 在单参数时属性名可任意填写
实际项目中删除前应做关联校验（如该部门下是否有员工）

部门修改功能

Thu, 21 May 2026 00:00:00 GMT

部门修改功能#

定义#

部门修改功能分为两个步骤：查询回显和修改数据。查询回显根据 ID 获取部门数据用于页面展示，修改数据接收 JSON 请求体更新数据库记录。涉及路径参数接收（@PathVariable）和 @RequestMapping 路径抽取。

查询回显#

接口描述#

请求方式：GET
请求路径：/depts/{id}
请求参数：路径参数 id
响应数据：Result（data 为 Dept 对象）

实现思路#

查询回显三层架构

路径参数接收#

/depts/1、/depts/2 这种在 URL 中传递的参数称为路径参数。使用 @PathVariable 注解获取：

路径参数接收

路径参数名与 Controller 方法形参名称一致时，@PathVariable 的 value 属性可省略。

代码实现#

1
// Controller
2
@GetMapping("/depts/{id}")
3
public Result getById(@PathVariable Integer id) {
4
    System.out.println("根据ID查询, id=" + id);
5
    Dept dept = deptService.getById(id);
6
    return Result.success(dept);
7
}
8

9
// Service
10
Dept getById(Integer id);
11

12
// ServiceImpl
13
public Dept getById(Integer id) {
14
    return deptMapper.getById(id);
15
}
16

17
// Mapper
18
@Select("select id, name, create_time, update_time from dept where id = #{id}")
19
Dept getById(Integer id);

显示更多显示更少

修改数据#

接口描述#

请求方式：PUT
请求路径：/depts
请求参数：JSON 格式 {"id":1, "name":"研发部"}
响应数据：Result

实现思路#

修改数据三层架构

代码实现#

1
// Controller
2
@PutMapping("/depts")
3
public Result update(@RequestBody Dept dept) {
4
    System.out.println("修改部门, dept=" + dept);
5
    deptService.update(dept);
6
    return Result.success();
7
}
8

9
// Service
10
void update(Dept dept);
11

12
// ServiceImpl
13
public void update(Dept dept) {
14
    dept.setUpdateTime(LocalDateTime.now());  // 补全更新时间
15
    deptMapper.update(dept);
16
}
17

18
// Mapper
19
@Update("update dept set name = #{name}, update_time = #{updateTime} where id = #{id}")
20
void update(Dept dept);

显示更多显示更少

@RequestMapping 路径抽取#

部门相关接口请求路径都以 /depts 开头。可将公共路径抽取到类上：

1
@Slf4j
2
@RequestMapping("/depts")
3
@RestController
4
public class DeptController {
5

6
    @GetMapping           // → /depts (GET)
7
    public Result list() { ... }
8

9
    @DeleteMapping        // → /depts (DELETE)
10
    public Result delete(Integer id) { ... }
11

12
    @PostMapping          // → /depts (POST)
13
    public Result save(@RequestBody Dept dept) { ... }
14

15
    @GetMapping("/{id}")  // → /depts/{id} (GET)
16
    public Result getById(@PathVariable Integer id) { ... }
17

18
    @PutMapping           // → /depts (PUT)
19
    public Result update(@RequestBody Dept dept) { ... }
20
}

显示更多显示更少

完整请求路径 = 类上的 @RequestMapping 的 value + 方法上的映射注解的 value。

常见场景#

编辑表单的”回显-修改-保存”两阶段交互
RESTful 风格中 PUT + 路径参数的组合使用
同类接口的公共路径抽取，减少重复代码

注意事项#

路径参数名与形参名一致时可省略 @PathVariable 的 value
@RequestBody 用于接收 JSON 请求体，@PathVariable 用于接收 URL 路径参数
修改操作每次都应更新 updateTime 字段
抽取公共路径到类上后，方法上的路径只需写差异部分

部门查询功能

Thu, 21 May 2026 00:00:00 GMT

部门查询功能#

定义#

部门查询功能用于查询所有部门数据并展示在部门管理页面中。基于 SpringBoot 三层架构（Controller → Service → Mapper）实现，涉及 MyBatis 字段映射、驼峰命名规则、请求方式限定以及前后端联调。

实现思路#

三层架构每一层的职责：

查询部门三层架构

Controller 层：接收前端请求，调用 Service 查询部门数据，响应结果
Service 层：调用 Mapper 接口方法，查询所有部门数据
Mapper 层：执行查询所有部门数据的 SQL 操作

代码实现#

Controller 层#

1
@RestController
2
public class DeptController {
3

4
    @Autowired
5
    private DeptService deptService;
6

7
    @GetMapping("/depts")
8
    public Result list() {
9
        List<Dept> deptList = deptService.findAll();
10
        return Result.success(deptList);
11
    }
12
}

限定请求方式有两种方法：

@RequestMapping(value = "/depts", method = RequestMethod.GET) — 通过 method 属性限定
@GetMapping("/depts") — 使用衍生注解（推荐）

请求方式	衍生注解
GET	`@GetMapping`
POST	`@PostMapping`
PUT	`@PutMapping`
DELETE	`@DeleteMapping`

Service 层#

1
// DeptService 接口
2
public interface DeptService {
3
    public List<Dept> findAll();
4
}
5

6
// DeptServiceImpl 实现
7
@Service
8
public class DeptServiceImpl implements DeptService {
9
    @Autowired
10
    private DeptMapper deptMapper;
11

12
    public List<Dept> findAll() {
13
        return deptMapper.findAll();
14
    }
15
}

显示更多显示更少

Mapper 层#

1
@Mapper
2
public interface DeptMapper {
3
    @Select("select * from dept")
4
    public List<Dept> findAll();
5
}

数据封装 — 字段映射#

当实体类属性名和数据库表字段名不一致时，MyBatis 不能自动封装。

例如数据库字段 create_time、update_time，实体类属性 createTime、updateTime。

三种解决方案：

方案一：手动结果映射（@Results + @Result）#

1
@Results({
2
    @Result(column = "create_time", property = "createTime"),
3
    @Result(column = "update_time", property = "updateTime")
4
})
5
@Select("select id, name, create_time, update_time from dept")
6
public List<Dept> findAll();

方案二：SQL 起别名#

1
@Select("select id, name, create_time createTime, update_time updateTime from dept")
2
public List<Dept> findAll();

方案三：开启驼峰命名（推荐）#

如果字段名与属性名符合驼峰命名规则（abc_xyz → abcXyz），MyBatis 可自动映射。

1
mybatis:
2
  configuration:
3
    map-underscore-to-camel-case: true

前提：实体类属性与数据库字段名严格遵守驼峰命名规则。

前后端联调#

前端工程通过 Nginx 反向代理访问后端 Tomcat 服务器。

Nginx反向代理

请求访问流程：

请求访问流程

Nginx 配置关键指令：

location：定义匹配特定 URI 请求的规则
^~ /api/：精确匹配以 /api/ 开头的路径
rewrite：重写匹配到的 URI 路径
proxy_pass：代理转发，将匹配到的请求转发给后端服务器

使用 Nginx 反向代理的原因：

安全：后端 Tomcat 集群不直接暴露给前端
灵活：后端增减服务器对前端无感知，只需修改 Nginx 配置
负载均衡：可方便实现后端 Tomcat 的负载均衡

常见场景#

列表页数据加载，一次性查询全部记录并展示
前后端分离项目中，通过 Nginx 代理解决跨域和负载均衡
数据库下划线字段与 Java 驼峰属性之间的自动映射

注意事项#

推荐使用 @GetMapping 等衍生注解限定请求方式，简洁优雅
驼峰命名映射是最推荐的字段映射方案，但前提是命名严格遵循规范
@Results 手动映射仅在字段名无法自动映射时使用
Nginx 的反向代理使前后端解耦，前端始终请求同一地址

博客命令行工具箱

Wed, 20 May 2026 00:00:00 GMT

博客的 scripts/ 目录下脚本越来越多——同步笔记用 Node，下载影视和音乐用 Python，生成描述用 tsx，语言和参数格式各不相同。每次要用的时候还得翻文档查命令，太麻烦了。

于是做了一个统一命令行工具箱：一个入口 pnpm cli，搞定所有操作。

使用方式#

Terminal window

1
# 直接运行，进入交互菜单
2
pnpm cli
3

4
# 或者直达子命令
5
pnpm cli sync          # 同步笔记
6
pnpm cli new "文章名"    # 创建新文章
7
pnpm cli media "片名"   # 下载影视封面 + 生成 md
8
pnpm cli music "歌名"   # 下载音乐 + 歌词 + 封面
9
pnpm cli lrc ./music/  # 提取本地 M4A 歌词
10
pnpm cli desc          # AI 生成文章摘要
11
pnpm cli dev           # 启动开发服务器
12
pnpm cli build         # 构建站点

为什么好用#

只记一个命令 pnpm cli，交互菜单列出所有功能
智能识别 — 菜单里直接打片名/歌名，自动问你是搜影视还是音乐
旧命令不受影响 — 原来的 pnpm sync、pnpm new-post 等照样能用
参数转发 — pnpm cli media "星际穿越" -y 直接透传给 Python 脚本

技术实现#

纯 Node.js 写的，零依赖。核心原理是用 child_process.spawn 桥接已有的 Python/JS/TS 脚本，交互模式用 readline 做菜单问答，启动子进程前释放 stdin 避免输入抢占。

JDBC介绍与连接

Tue, 19 May 2026 00:00:00 GMT

JDBC介绍与连接#

定义#

JDBC（Java DataBase Connectivity），是使用Java语言操作关系型数据库的一套API，也是操作数据库最为基础、底层的技术。

本质：

sun公司官方定义的一套操作所有关系型数据库的规范，即接口。
各个数据库厂商去实现这套接口，提供数据库驱动jar包。
开发者使用这套接口(JDBC)编程，真正执行的代码是驱动jar包中的实现类。

架构#

在Java代码中通过JDBC接口操作数据库，底层由各数据库厂商的驱动实现：

1
Java Application
2
       │
3
  JDBC API (接口)
4
       │
5
  数据库驱动 (MySQL / Oracle / ...)
6
       │
7
    数据库

生态定位#

JDBC是操作数据库最为基础、底层的技术。在企业项目开发中，一般都会使用基于JDBC封装的高级框架：

框架	市场地位
Mybatis	最为主流
MybatisPlus	其次
Hibernate	较少
SpringDataJPA	较少

常见场景#

直接编写JDBC程序执行SQL语句（学习/小型工具）
作为Mybatis/MybatisPlus等框架的底层依赖

注意事项#

JDBC程序需要手动管理数据库连接、结果集解析和资源关闭，代码较为繁琐。
生产环境中一般不直接使用原生JDBC，而是使用基于JDBC封装的高级框架。
数据库驱动jar包需与数据库版本匹配。

JDBC增删改操作

Tue, 19 May 2026 00:00:00 GMT

JDBC增删改操作#

定义#

JDBC中执行增删改（DML）操作通过 PreparedStatement.executeUpdate() 方法完成，返回值为受影响的记录行数。

语法/用法#

执行DML语句的标准流程#

1
// 1. 建立数据库连接
2
Connection conn = DriverManager.getConnection(
3
    "jdbc:mysql://localhost:3306/web", "root", "1234");
4

5
// 2. SQL语句（预编译）
6
String sql = "UPDATE user SET password = ?, age = ? WHERE id = ?";
7

8
// 3. 创建PreparedStatement
9
PreparedStatement pstmt = conn.prepareStatement(sql);
10

11
// 4. 设置参数
12
pstmt.setString(1, newPassword);
13
pstmt.setInt(2, newAge);
14
pstmt.setInt(3, userId);
15

16
// 5. 执行更新
17
int rowsUpdated = pstmt.executeUpdate();
18

19
// 6. 关闭资源
20
pstmt.close();
21
conn.close();

显示更多显示更少

DML vs DQL 返回值#

操作类型	方法	返回值
DML（INSERT/UPDATE/DELETE）	`executeUpdate()`	`int` — 影响的记录数
DQL（SELECT）	`executeQuery()`	`ResultSet` — 查询结果集

事务处理#

JDBC默认自动提交。如需手动控制事务：

1
conn.setAutoCommit(false);   // 关闭自动提交
2
// ... 执行多条DML ...
3
conn.commit();               // 手动提交
4
// 或 conn.rollback();       // 出错时回滚

常见场景#

用户信息的增删改操作
批量数据导入/更新
需要事务控制的复杂业务操作

注意事项#

DML操作必须使用预编译SQL（PreparedStatement），防止SQL注入。
执行完毕后必须关闭 PreparedStatement 和 Connection。
executeUpdate() 返回值可用于判断操作是否成功（影响行数 > 0）。
多条DML需保证原子性时，务必使用事务控制。

JDBC查询操作

Tue, 19 May 2026 00:00:00 GMT

JDBC查询操作#

定义#

JDBC查询操作通过 PreparedStatement 执行 SELECT 语句，返回 ResultSet 结果集，遍历解析后获取数据。

语法/用法#

核心代码流程#

1
// 1. 获取连接
2
Connection conn = DriverManager.getConnection(
3
    "jdbc:mysql://localhost:3306/web", "root", "1234");
4

5
// 2. 创建预编译的PreparedStatement对象
6
PreparedStatement pstmt = conn.prepareStatement(
7
    "SELECT * FROM user WHERE username = ? AND password = ?");
8

9
// 3. 设置参数
10
pstmt.setString(1, "daqiao");
11
pstmt.setString(2, "123456");
12

13
// 4. 执行查询
14
ResultSet rs = pstmt.executeQuery();
15

16
// 5. 处理结果集
17
while (rs.next()) {
18
    int id = rs.getInt("id");
19
    String username = rs.getString("username");
20
    String password = rs.getString("password");
21
    String name = rs.getString("name");
22
    int age = rs.getInt("age");
23
}
24

25
// 6. 关闭资源
26
rs.close();
27
pstmt.close();
28
conn.close();

显示更多显示更少

参数化测试版本#

1
@ParameterizedTest
2
@CsvSource({"daqiao,123456"})
3
public void testJdbc(String _username, String _password) throws Exception {
4
    Connection conn = DriverManager.getConnection(
5
        "jdbc:mysql://localhost:3306/web", "root", "1234");
6
    PreparedStatement pstmt = conn.prepareStatement(
7
        "SELECT * FROM user WHERE username = ? AND password = ?");
8
    pstmt.setString(1, _username);
9
    pstmt.setString(2, _password);
10
    ResultSet rs = pstmt.executeQuery();
11
    while (rs.next()) {
12
        // 解析结果...
13
    }
14
    rs.close();
15
    pstmt.close();
16
    conn.close();
17
}

显示更多显示更少

Maven依赖#

1
<dependency>
2
    <groupId>mysql</groupId>
3
    <artifactId>mysql-connector-java</artifactId>
4
    <version>8.0.30</version>
5
</dependency>
6
<dependency>
7
    <groupId>org.junit.jupiter</groupId>
8
    <artifactId>junit-jupiter</artifactId>
9
    <version>5.9.3</version>
10
    <scope>test</scope>
11
</dependency>

ResultSet 详解#

ResultSet（结果集对象）封装了DQL查询语句查询的结果。

方法	说明
`next()`	将光标从当前位置向前移动一行，返回 `true`（有效行）/ `false`（无效行）
`getXxx(列编号)`	按列索引获取数据
`getXxx("列名")`	按列名获取数据（推荐）

解析步骤：光标初始指向第0行 → 每次 next() 前移一行 → 有数据则用 getXxx 取值。

预编译SQL#

两种风格对比#

风格	示例	特点
静态SQL	`"SELECT * FROM user WHERE username = 'daqiao'"`	参数硬编码，不安全
预编译SQL	`"SELECT * FROM user WHERE username = ?"`	参数动态传递，推荐

SQL注入#

SQL注入：通过控制输入来修改事先定义好的SQL语句，以达到执行代码对服务器进行攻击的方法。

典型攻击输入：密码输入 ' or '1' = '1，拼接后SQL变为：

1
SELECT * FROM user WHERE username = 'xxx' AND password = '' or '1' = '1'

or '1'='1' 恒为真，导致绕过登录验证。

解决方案#

预编译SQL将 ' or '1'='1 整体作为字符串参数处理（转义为普通字符串），而非SQL逻辑的一部分，从而杜绝SQL注入。

性能优势#

预编译SQL在数据库端可缓存执行计划，同一SQL模板多次执行时性能更高。

注意事项#

始终使用预编译SQL（PreparedStatement），禁止直接拼接SQL字符串。
ResultSet、PreparedStatement、Connection 使用完毕后必须关闭，推荐使用 try-with-resources。
JDBC执行DQL语句用 executeQuery()，返回 ResultSet。

Mybatis基础

Tue, 19 May 2026 00:00:00 GMT

Mybatis基础#

定义#

MyBatis 是一款优秀的持久层框架，用于简化JDBC的开发。原本是Apache的开源项目iBatis，2010年迁移至Google Code并改名为MyBatis，2013年11月迁移到Github。

官网：https://mybatis.org/mybatis-3/zh/index.html

持久层：即数据访问层（DAO），负责与数据库交互。

框架：一套可重用、通用、半成品的软件基础代码模型，在框架基础上开发更高效、规范。

快速入门#

1. 创建SpringBoot工程，导入依赖#

1
<dependency>
2
    <groupId>org.mybatis.spring.boot</groupId>
3
    <artifactId>mybatis-spring-boot-starter</artifactId>
4
</dependency>
5
<dependency>
6
    <groupId>mysql</groupId>
7
    <artifactId>mysql-connector-java</artifactId>
8
</dependency>
9
<dependency>
10
    <groupId>org.projectlombok</groupId>
11
    <artifactId>lombok</artifactId>
12
</dependency>

2. 数据准备#

实体类 User（位于 com.itheima.pojo 包）：

1
@Data
2
@NoArgsConstructor
3
@AllArgsConstructor
4
public class User {
5
    private Integer id;
6
    private String username;
7
    private String password;
8
    private String name;
9
    private Integer age;
10
}

3. 配置Mybatis#

application.properties：

1
spring.datasource.url=jdbc:mysql://localhost:3306/web
2
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
3
spring.datasource.username=root
4
spring.datasource.password=root@1234

4. 编写Mapper接口#

1
@Mapper
2
public interface UserMapper {
3
    @Select("select * from user")
4
    public List<User> findAll();
5
}

@Mapper：表示Mybatis中的Mapper接口，运行时框架自动生成代理对象并交由Spring IOC容器管理。
@Select：编写select查询语句。

5. 单元测试#

1
@SpringBootTest
2
class ApplicationTests {
3
    @Autowired
4
    private UserMapper userMapper;
5

6
    @Test
7
    public void testFindAll() {
8
        List<User> userList = userMapper.findAll();
9
        userList.forEach(System.out::println);
10
    }
11
}

JDBC vs Mybatis#

JDBC缺点	Mybatis解决方案
url/username/password硬编码在代码中	配置在 `application.properties` 中
查询结果解析封装繁琐	自动完成映射封装
频繁获取/释放连接造成资源浪费	内置数据库连接池技术

数据库连接池#

数据库连接池是一个容器，负责分配、管理数据库连接。

工作原理：

程序启动时，在连接池中创建一定数量的Connection对象。
客户端执行SQL时从连接池获取Connection，执行完毕后归还（复用）。
空闲时间超过最大空闲时间的连接会被自动释放。

好处：资源重用、提升响应速度、避免连接遗漏。

常见连接池产品#

连接池	说明
Hikari	SpringBoot默认，性能优越
Druid	阿里巴巴开源，功能强大
C3P0 / DBCP	老牌连接池，较少使用

切换为Druid#

1
<dependency>
2
    <groupId>com.alibaba</groupId>
3
    <artifactId>druid-spring-boot-starter</artifactId>
4
    <version>1.2.19</version>
5
</dependency>

1
spring.datasource.type=com.alibaba.druid.pool.DruidDataSource
2
spring.datasource.druid.driver-class-name=com.mysql.cj.jdbc.Driver
3
spring.datasource.druid.url=jdbc:mysql://localhost:3306/web
4
spring.datasource.druid.username=root
5
spring.datasource.druid.password=1234

增删改查操作#

注解速查#

操作	注解	示例
查询	`@Select`	`@Select("select * from user where id = #{id}")`
新增	`@Insert`	`@Insert("insert into user(...) values(#{...})")`
修改	`@Update`	`@Update("update user set ... where id = #{id}")`
删除	`@Delete`	`@Delete("delete from user where id = #{id}")`

参数占位符#

Mybatis提供两种占位符：

占位符	特点	推荐
`#{...}`	预编译SQL（生成 `?`），防SQL注入	强烈推荐
`${...}`	直接字符串拼接，存在SQL注入风险	不推荐

删除示例#

1
@Delete("delete from user where id = #{id}")
2
public Integer deleteById(Integer id);

Integer 返回值表示DML语句影响的记录数。

新增示例#

1
@Insert("insert into user(username,password,name,age) values(#{username},#{password},#{name},#{age})")
2
public void insert(User user);

多个参数封装到对象中，通过 #{对象属性名} 引用。

修改示例#

1
@Update("update user set username=#{username},password=#{password},name=#{name},age=#{age} where id=#{id}")
2
public void update(User user);

查询示例（多参数）#

1
@Select("select * from user where username = #{username} and password = #{password}")
2
public User findByUsernameAndPassword(@Param("username") String username, @Param("password") String password);

@Param 注解为方法形参起名；基于官方骨架创建的SpringBoot项目中接口编译时会保留方法形参名，@Param 可省略（直接 #{形参名}）。

XML映射配置#

使用场景#

注解：简单的增删改查功能。
XML：复杂的SQL功能。

注意：一个接口方法对应的SQL语句，要么使用注解，要么使用XML，不可同时配置。

XML配置规范#

XML映射文件名称与Mapper接口名称一致，放在相同包下（同包同名）。
XML映射文件的 namespace 为Mapper接口全限定名。
SQL语句的 id 与Mapper接口方法名一致，返回类型一致。

XML示例#

1
<?xml version="1.0" encoding="UTF-8" ?>
2
<!DOCTYPE mapper
3
  PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
4
  "https://mybatis.org/dtd/mybatis-3-mapper.dtd">
5
<mapper namespace="com.itheima.mapper.UserMapper">
6

7
    <select id="findAll" resultType="com.itheima.pojo.User">
8
        select * from user
9
    </select>
10

11
</mapper>

辅助配置#

SQL提示#

在IDEA中配置与MySQL数据库的连接，可在 @Select 注解中获得SQL语法提示和表名/列名校验。

Mybatis日志输出#

1
mybatis.configuration.log-impl=org.apache.ibatis.logging.stdout.StdOutImpl

开启后可在控制台查看执行的SQL语句及参数。

注意事项#

测试类所在包需要与引导类所在包相同。
强烈建议使用 #{} 占位符，防止SQL注入。
DML操作建议定义 Integer 返回值接收影响行数。
MybatisX是IDEA中快速开发Mybatis的插件，可快速定位Mapper与XML的映射关系。

SpringBoot配置文件

Tue, 19 May 2026 00:00:00 GMT

SpringBoot配置文件#

定义#

SpringBoot项目支持两种配置文件格式：

格式	文件名	特点
properties	`application.properties`	`key=value` 形式，层级不清晰
yml	`application.yml` / `application.yaml`	以数据为中心，层级清晰，推荐使用

语法#

YML基本语法#

大小写敏感
数值前必须有空格作为分隔符
使用缩进表示层级关系，不允许使用Tab键，只能用空格（IDEA中自动将Tab转换为空格）
相同层级的元素左侧对齐即可
# 表示注释

定义对象/Map集合#

1
user:
2
  name: zhangsan
3
  age: 18
4
  password: 123456

定义数组/List/Set集合#

1
hobby:
2
  - java
3
  - game
4
  - sport

常见场景#

数据库连接配置对比#

properties 写法：

1
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
2
spring.datasource.url=jdbc:mysql://localhost:3306/web01
3
spring.datasource.username=root
4
spring.datasource.password=root@1234
5
mybatis.configuration.log-impl=org.apache.ibatis.logging.stdout.StdOutImpl

yml 写法：

1
#数据源配置
2
spring:
3
  datasource:
4
    driver-class-name: com.mysql.cj.jdbc.Driver
5
    url: jdbc:mysql://localhost:3306/web01
6
    username: root
7
    password: root@1234
8
#mybatis配置
9
mybatis:
10
  configuration:
11
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

注意事项#

在项目开发中，推荐使用 application.yml 配置文件，简洁、明了。
如果配置项的值以 0 开头，值需要使用单引号引起来，因为以 0 开头在yml中表示八进制数据。
application.properties 和 application.yml 可共存，优先级由SpringBoot加载顺序决定。
切换配置文件格式时，将原文件重命名（如改为 _application.properties）即可避免冲突。

数据库基础概念

Mon, 18 May 2026 00:00:00 GMT

数据库基础概念#

定义#

数据库（DataBase，简称DB）：存储和管理数据的仓库。
数据库管理系统（DataBase Management System，简称DBMS）：操作和管理数据库的大型软件。
SQL（Structured Query Language）：结构化查询语言，操作关系型数据库的编程语言，定义了操作所有关系型数据库的统一标准。

三者关系：程序员给 DBMS 发送 SQL 语句，再由 DBMS 操作数据库中的数据。

数据库概念关系

Web开发中的数据流#

在 SpringBoot Web 开发中，程序分层为 Controller → Service → Dao。真实企业开发中，Dao 层不再读写文本文件，而是通过 SQL 操作数据库：

Web开发调用流程

主流数据库排名#

数据库	特点
Oracle	大型收费数据库，Oracle 公司产品
MySQL	开源免费的中小型数据库，互联网公司使用最广泛
SQL Server	Microsoft 收费中型数据库，C#/.NET 常用
PostgreSQL	开源免费的中小型数据库
DB2	IBM 大型收费数据库
SQLite	嵌入式微型数据库（Android 内置）
MariaDB	MySQL 的分支，开源免费，与 MySQL 兼容性好

注意事项#

MySQL 目前由 Oracle 维护，分为社区版（免费）和企业版（收费）。
所有关系型数据库都遵循统一的 SQL 标准，学会 SQL 即可操作 MySQL、Oracle、SQL Server 等。
课程大纲：MySQL 概述 → SQL（DDL/DML/DQL）→ 多表设计 → 多表查询 → 事务 → 索引。

影视封面一键下载与博客导入教程

Mon, 18 May 2026 00:00:00 GMT

影视封面一键下载与博客导入教程#

背景#

博客的影视与游戏页面（/movies-games）展示你看过的电影、电视剧和动画。每添加一部作品，需要准备：

内容	用途
`.jpg` 海报	卡片封面图
`.md`	博客内容文件（含标题、评分、标签、状态等）

之前得自己去 TMDB 或豆瓣搜海报、下载、手写 frontmatter。现在有了 fetch-media.py，一条命令全搞定。

原理#

flowchart TD A[输入影视名称] --> B{TMDB 搜索} B -->|找到| C[展示搜索结果列表] C --> D[选择 / 自动选第一个] D --> E[获取详情：标题、年份、类型标签、简介] E --> F[下载海报到 scripts/img-anime/] F --> G[交互确认 status / score / tags / 评价] G --> H[生成 MD 到 src/content/bangumi/anime/] B -->|未找到| I[降级为手动模式] I --> J[手动填写各字段] J --> F

脚本调用 TMDB API v3（免费无需审核），搜索支持中文，自动获取中文标题、类型标签和海报。

环境准备#

无需安装任何依赖，Python 3 标准库即可运行。

TMDB API key 已内置在脚本中，开箱即用。需要开启代理/加速器才能访问 TMDB。

使用方法#

快速模式（推荐）#

Terminal window

1
# 电影
2
python scripts/fetch-media.py "星际穿越" -y
3

4
# 电视剧
5
python scripts/fetch-media.py "黑暗荣耀" --type=tv -y
6

7
# 动画
8
python scripts/fetch-media.py "你的名字" --type=anime -y
9

10
# 纪录片
11
python scripts/fetch-media.py "地球脉动" --type=documentary -y

-y 模式下自动选第一个搜索结果，status 默认设为「看过」，跳过所有确认。

交互模式#

Terminal window

1
python scripts/fetch-media.py "唐人街探案"

交互模式下可以：

从多个搜索结果中手动选择
自定义状态（想看/看过/在看/搁置/抛弃）
修改评分 0-10
修改标签
填写评价

预设参数#

Terminal window

1
# 直接指定状态和评分
2
python scripts/fetch-media.py "让子弹飞" -y --status=2 --score=9
3

4
# 手动模式 + 提供封面 URL
5
python scripts/fetch-media.py "冷门电影" -y --cover-url=https://xxx.com/poster.jpg

完整参数表#

参数	说明	默认值
第一个参数	影视名称	必填
`-y` / `--yes`	快速模式，自动第一个结果	关闭
`--type=xxx`	指定类型：`movie` / `tv` / `anime` / `documentary`	自动判断
`--status=x`	状态：1想看 2看过 3在看 4搁置 5抛弃	2
`--score=x`	评分 0-10	0
`--cover-url=xxx`	手动模式下的封面图 URL	空
`--api-key=xxx`	TMDB API key（覆盖内置 key）	内置 key

实操示例#

示例一：搜索到结果（正常流程）#

Terminal window显示更多显示更少

1
$ python scripts/fetch-media.py "星际穿越" -y
2

3
搜索: 星际穿越
4

5
搜索结果:
6

7
  [ 1] [电影] 星际穿越 (2014)
8
       未来的地球黄沙遍野，农作物相继枯萎灭绝。人类不再像从前...
9
  [ 2] [电影] 走进星际穿越 (2015)
10
       该纪录片分为14个片段...
11
  [ 3] [电影] 星际穿越：诺兰的奥德赛 (2014)
12

13
快速模式: 自动选择第 1 个
14

15
获取详情...
16

17
==================================================
18
  标题: 星际穿越
19
  原名: Interstellar
20
  类型: 电影 → subcategory: movie
21
  年份: 2014
22
  标语: 爱是一种力量，能让我们超越时空的维度来感知它的存在
23
  标签: 冒险, 剧情, 科幻
24
==================================================
25

26
  下载封面: 星际穿越.jpg
27
  封面 [100%] =========================> 86 KB/86 KB
28
  [MD] 星际穿越.md
29

30
完成: 星际穿越

显示更多显示更少

示例二：TMDB 搜不到（手动模式）#

Terminal window

1
$ python scripts/fetch-media.py "写给阿嬷的情书" -y
2

3
搜索: 写给阿嬷的情书
4
  TMDB 未找到结果，切换到手动模式
5

6
快速模式: subcategory=movie, status=2(看过), score=0
7
  封面: [无]
8
  [MD] 写给阿嬷的情书.md
9

10
完成: 写给阿嬷的情书

搜不到时自动降级为手动模式，MD 照样生成。后续手动补充封面图即可。

输出文件#

1
scripts/img-anime/
2
└── 星际穿越.jpg          ← 海报封面（需手动上传 CDN）
3

4
src/content/bangumi/anime/
5
└── 星际穿越.md           ← 博客内容文件

生成的 Markdown 格式#

1
---
2
title: 星际穿越
3
name_cn: 星际穿越
4
category: anime
5
subcategory: movie
6
status: 2
7
image: https://ph.0824.uk/file/anime/星际穿越.jpg
8
score: 0
9
tags:
10
  - 冒险
11
  - 剧情
12
  - 科幻
13
published: 2026-05-18
14
---

image 字段指向 CDN 地址 https://ph.0824.uk/file/anime/
封面图生成后需手动上传到 CDN 对应路径
生成后可手动编辑 md 补充评价、调整评分

状态码#

值	含义
`1`	想看
`2`	看过
`3`	在看
`4`	搁置
`5`	抛弃

封面图上传#

脚本下载的海报保存在 scripts/img-anime/ 目录。需要手动上传到 CDN 的 https://ph.0824.uk/file/anime/ 路径，文件名保持一致即可。

例如：

脚本生成 scripts/img-anime/星际穿越.jpg
上传到 CDN → https://ph.0824.uk/file/anime/星际穿越.jpg
MD 中的 image 字段已自动填写该 URL，无需修改

常见问题#

Q: 报错 `urlopen error timed out`？#

TMDB API 需要代理。开启加速器/代理后再运行。

Q: 搜不到想要的结果？#

TMDB 作为国外数据库，部分华语冷门电影可能未收录。脚本会自动降级为手动模式，不影响 MD 生成。

Q: 快速模式选错了（如选了网剧而不是电影）？#

去掉 -y 用交互模式，手动选择正确的搜索结果。

Terminal window

1
python scripts/fetch-media.py "唐人街探案"
2
# → 选择序号: 2  （电影版）

Q: MD 已存在怎么办？#

脚本会自动跳过已有 MD 文件，不会覆盖。如需重新生成，先手动删除旧的 MD。

Q: 想换 CDN 地址？#

修改脚本顶部的 CDN_BASE 变量即可。

总结#

操作	命令
快速添加电影	`python scripts/fetch-media.py "片名" -y`
添加电视剧	`python scripts/fetch-media.py "剧名" --type=tv -y`
添加动画	`python scripts/fetch-media.py "动画名" --type=anime -y`
交互模式手动选择	`python scripts/fetch-media.py "片名"`
指定评分和状态	`python scripts/fetch-media.py "片名" -y --score=9 --status=2`

一条命令，海报 + MD 全部到位，再也不用手动搜图写 frontmatter 了。

MySQL数据模型

Mon, 18 May 2026 00:00:00 GMT

MySQL数据模型#

定义#

关系型数据库（RDBMS）：建立在关系模型基础上，由多张相互连接的二维表组成的数据库。二维表由行（记录）和列（字段）组成。

二维表示例

二维表的优点#

使用表存储数据，格式统一，便于维护
使用 SQL 语言操作，标准统一，使用方便，可用于复杂查询

基于二维表存储数据的数据库是关系型数据库；反之则是非关系型数据库（如 Redis）。

MySQL 数据存储层次#

MySQL数据模型

存储层次（由大到小）：

1
数据库服务器
2
  └── 数据库1
3
  │     ├── 表A（多行记录）
4
  │     └── 表B
5
  └── 数据库2
6
        └── 表C

MySQL 客户端通过 DBMS 发送 SQL，DBMS 根据 SQL 指令操作数据库中的表及数据。

常见场景#

在 MySQL 中存储数据的步骤：

创建数据库（多个数据库间相互独立）
在数据库下创建数据表（一个数据库可含多张表）
将数据存入数据表（一张表可存多行数据）

注意事项#

MySQL、Oracle、DB2、SQL Server 都属于关系型数据库（基于二维表）。
非关系型数据库（NoSQL）如 Redis，不基于二维表存储。

MySQL安装与连接

Mon, 18 May 2026 00:00:00 GMT

MySQL安装与连接#

定义#

MySQL 是当前互联网开发中最流行的开源关系型数据库管理系统。

版本说明#

版本	说明
MySQL Enterprise Edition（商业版）	收费，享有技术支持，可试用 30 天
MySQL Community Server（社区版）	免费，无官方技术支持

本课程使用 MySQL Community Server 8.0.34。

连接语法#

MySQL 服务器启动后，使用命令行连接：

Terminal window

1
mysql -u用户名 -p密码 [-h数据库服务器IP地址 -P端口号]

-h 省略时默认连接本地 127.0.0.1
-P 省略时默认端口 3306

两种密码输入方式#

方式一：密码直接跟在 -p 后（明文暴露，不安全）

方式二：-p 后回车，再在交互界面输入密码（推荐）

企业环境连接#

真实开发中，MySQL 部署在公司服务器（IDC 机房），开发人员通过网络远程连接：

1
mysql -h服务器IP -P端口号 -u用户名 -p

企业远程连接

注意事项#

学习阶段可本地安装，企业开发中数据库在远程服务器。
图形化管理工具（DataGrip / IDEA 内置数据库工具）可大幅提升效率。
驱动下载可能较慢，需耐心等待。

SQL-DDL语句

Mon, 18 May 2026 00:00:00 GMT

SQL-DDL语句#

定义#

DDL（Data Definition Language）：数据定义语言，用来定义数据库对象（数据库、表）。

语法/用法#

SQL 四大分类#

分类	全称	说明
DDL	Data Definition Language	数据定义语言，定义数据库/表
DML	Data Manipulation Language	数据操作语言，增删改数据
DQL	Data Query Language	数据查询语言，查询数据
DCL	Data Control Language	数据控制语言，权限管理

数据库操作#

1
-- 查询所有数据库
2
SHOW DATABASES;
3

4
-- 查询当前数据库
5
SELECT DATABASE();
6

7
-- 创建数据库（不存在则创建，指定字符集）
8
CREATE DATABASE [IF NOT EXISTS] 数据库名 [DEFAULT CHARSET utf8mb4];
9

10
-- 使用/切换数据库
11
USE 数据库名;
12

13
-- 删除数据库（存在则删除）
14
DROP DATABASE [IF EXISTS] 数据库名;

DATABASE 可替换为 SCHEMA，如 CREATE SCHEMA db01;、SHOW SCHEMAS;

表操作 — 创建#

1
CREATE TABLE 表名(
2
    字段1  字段1类型 [约束] [COMMENT '注释'],
3
    字段2  字段2类型 [约束] [COMMENT '注释'],
4
    ...
5
    字段n  字段n类型 [约束] [COMMENT '注释']
6
) [COMMENT '表注释'];

示例：

1
CREATE TABLE tb_user (
2
    id INT PRIMARY KEY AUTO_INCREMENT COMMENT 'ID,唯一标识',
3
    username VARCHAR(20) NOT NULL UNIQUE COMMENT '用户名',
4
    name VARCHAR(10) NOT NULL COMMENT '姓名',
5
    age INT COMMENT '年龄',
6
    gender CHAR(1) DEFAULT '男' COMMENT '性别'
7
) COMMENT '用户表';

约束#

约束	关键字	描述
非空	NOT NULL	字段值不能为 NULL
唯一	UNIQUE	字段值不能重复
主键	PRIMARY KEY	唯一标识一行记录（非空且唯一）
默认值	DEFAULT	未指定值时使用默认值
外键	FOREIGN KEY	关联其他表的主键

主键自增：AUTO_INCREMENT，插入时自动生成递增的 ID 值，从 1 开始。

MySQL 数据类型#

数值类型：

类型	大小	用途
TINYINT	1 byte	小整数值
INT / INTEGER	4 bytes	大整数值
BIGINT	8 bytes	极大整数值
FLOAT	4 bytes	单精度浮点
DOUBLE	8 bytes	双精度浮点

示例：age TINYINT UNSIGNED、score DOUBLE(4,1)

字符串类型：

类型	说明
CHAR(N)	定长字符串，性能高
VARCHAR(N)	变长字符串，按实际长度存储

示例：username VARCHAR(50)、phone CHAR(11)

日期时间类型：

类型	格式	说明
DATE	YYYY-MM-DD	日期
TIME	HH:MM	时间
DATETIME	YYYY-MM-DD HH:MM	日期时间
TIMESTAMP	时间戳	自动记录时间

示例：birthday DATE、create_time DATETIME

表操作 — 查询/修改/删除#

1
-- 查询当前数据库所有表
2
SHOW TABLES;
3

4
-- 查看表结构
5
DESC 表名;
6

7
-- 查看建表语句
8
SHOW CREATE TABLE 表名;
9

10
-- 添加字段
11
ALTER TABLE 表名 ADD 字段名 类型(长度) [COMMENT '注释'] [约束];
12

13
-- 修改字段类型
14
ALTER TABLE 表名 MODIFY 字段名 新数据类型(长度);
15

16
-- 修改字段名+类型
17
ALTER TABLE 表名 CHANGE 旧字段名 新字段名 类型(长度) [COMMENT '注释'] [约束];
18

19
-- 删除字段
20
ALTER TABLE 表名 DROP 字段名;
21

22
-- 修改表名
23
RENAME TABLE 表名 TO 新表名;
24

25
-- 删除表（含数据）
26
DROP TABLE [IF EXISTS] 表名;

显示更多显示更少

设计表流程#

阅读页面原型及需求文档，确定字段
确认各字段的类型、长度限制、约束
增加业务基础字段：id（主键自增）、create_time、update_time

员工表设计案例#

1
CREATE TABLE emp(
2
    id INT UNSIGNED PRIMARY KEY AUTO_INCREMENT COMMENT 'ID,主键',
3
    username VARCHAR(20) NOT NULL UNIQUE COMMENT '用户名',
4
    password VARCHAR(32) NOT NULL COMMENT '密码',
5
    name VARCHAR(10) NOT NULL COMMENT '姓名',
6
    gender TINYINT UNSIGNED NOT NULL COMMENT '性别, 1:男, 2:女',
7
    phone CHAR(11) NOT NULL UNIQUE COMMENT '手机号',
8
    job TINYINT UNSIGNED COMMENT '职位, 1:班主任,2:讲师,3:学工主管,4:教研主管,5:咨询师',
9
    salary INT UNSIGNED COMMENT '薪资',
10
    image VARCHAR(255) COMMENT '头像',
11
    entry_date DATE COMMENT '入职日期',
12
    create_time DATETIME COMMENT '创建时间',
13
    update_time DATETIME COMMENT '修改时间'
14
) COMMENT '员工表';

注意事项#

MySQL 8 默认字符集为 utf8mb4，创建数据库时可不额外指定。
id 字段应使用 PRIMARY KEY AUTO_INCREMENT 保证唯一性，避免手动维护。
同一数据库服务器中不允许创建同名数据库。
DROP TABLE 会同时删除表中所有数据，不可恢复。
实际开发中，查看/修改/删除表结构通常直接在图形化界面操作。

SQL-DML语句

Mon, 18 May 2026 00:00:00 GMT

SQL-DML语句#

定义#

DML（Data Manipulation Language）：数据操作语言，用来对数据库表中的数据记录进行增、删、改操作。

语法/用法#

INSERT — 插入数据#

1
-- 向指定字段插入
2
INSERT INTO 表名 (字段1, 字段2, ...) VALUES (值1, 值2, ...);
3

4
-- 向全部字段插入（字段顺序必须与表结构一致）
5
INSERT INTO 表名 VALUES (值1, 值2, ...);
6

7
-- 批量插入（指定字段）
8
INSERT INTO 表名 (字段1, 字段2, ...) VALUES
9
    (值1, 值2, ...),
10
    (值1, 值2, ...);
11

12
-- 批量插入（全部字段）
13
INSERT INTO 表名 VALUES
14
    (值1, 值2, ...),
15
    (值1, 值2, ...);

显示更多显示更少

示例：

1
-- 指定字段插入
2
INSERT INTO emp(username, name, gender, phone, create_time, update_time)
3
VALUES ('wuji', '张无忌', 1, '13309091231', NOW(), NOW());
4

5
-- 全字段插入
6
INSERT INTO emp(id, username, password, name, gender, phone, job, salary, image, entry_date, create_time, update_time)
7
VALUES (1, 'shinaian', '123456', '施耐庵', 1, '13309090001', 4, 15000, '1.jpg', '2000-01-01', NOW(), NOW());
8

9
-- 批量插入
10
INSERT INTO emp(username, name, gender, phone, create_time, update_time)
11
VALUES
12
    ('Tom1', '汤姆1', 1, '13309091231', NOW(), NOW()),
13
    ('Tom2', '汤姆2', 1, '13309091232', NOW(), NOW());

UPDATE — 修改数据#

1
UPDATE 表名 SET 字段1 = 值1, 字段2 = 值2, ... [WHERE 条件];

示例：

1
-- 修改指定记录
2
UPDATE emp SET name = '张三', update_time = NOW() WHERE id = 1;
3

4
-- 修改整张表（不加 WHERE 条件）
5
UPDATE emp SET entry_date = '2010-01-01', update_time = NOW();

DELETE — 删除数据#

1
DELETE FROM 表名 [WHERE 条件];

示例：

1
-- 删除指定记录
2
DELETE FROM emp WHERE id = 1;
3

4
-- 删除全部数据
5
DELETE FROM emp;

注意事项#

操作	注意点
INSERT	字段顺序与值的顺序必须一一对应；字符串和日期需用引号包裹；插入数据不得超出字段规定范围
UPDATE	不加 WHERE 条件会修改整张表的所有数据；一般需同步更新 `update_time` 字段
DELETE	不加 WHERE 条件会删除整张表的数据；不能删除某一个字段的值（应使用 UPDATE 置 NULL）；全量删除时会提示确认

SQL-DQL语句

Mon, 18 May 2026 00:00:00 GMT

SQL-DQL语句#

定义#

DQL（Data Query Language）：数据查询语言，用来查询数据库表中的记录。查询关键字为 SELECT。在业务系统中，查询是最常用、最重要的操作。

语法/用法#

完整语法结构#

1
SELECT     字段列表
2
FROM       表名列表
3
WHERE      条件列表
4
GROUP BY   分组字段列表
5
HAVING     分组后条件列表
6
ORDER BY   排序字段列表
7
LIMIT      分页参数

基本查询#

1
-- 查询指定字段
2
SELECT 字段1, 字段2 FROM 表名;
3

4
-- 查询所有字段
5
SELECT * FROM 表名;
6

7
-- 设置别名
8
SELECT 字段1 [AS] 别名1, 字段2 [AS] 别名2 FROM 表名;
9

10
-- 去除重复记录
11
SELECT DISTINCT 字段列表 FROM 表名;

示例：

1
SELECT name, entry_date FROM emp;
2
SELECT name AS 姓名, entry_date AS 入职日期 FROM emp;
3
SELECT DISTINCT job FROM emp;

* 号查询所有字段，开发中尽量少用（不直观、影响效率）。

条件查询（WHERE）#

1
SELECT 字段列表 FROM 表名 WHERE 条件列表;

比较运算符#

运算符	说明
`>` `>=` `<` `<=` `=`	大小比较
`<>` 或 `!=`	不等于
`BETWEEN ... AND ...`	在范围内（含边界）
`IN(...)`	多值匹配
`LIKE`	模糊匹配（`%` 任意字符，`_` 单个字符）
`IS NULL` / `IS NOT NULL`	空值判断

逻辑运算符#

运算符	说明
`AND` 或 `&&`	逻辑与
`OR` 或 `
`NOT` 或 `!`	逻辑非

示例：

1
-- 姓名等于
2
SELECT * FROM emp WHERE name = '杨逍';
3

4
-- 薪资范围
5
SELECT * FROM emp WHERE salary <= 5000;
6

7
-- NULL 判断
8
SELECT * FROM emp WHERE job IS NULL;
9
SELECT * FROM emp WHERE job IS NOT NULL;
10

11
-- 不等
12
SELECT * FROM emp WHERE password <> '123456';
13

14
-- 日期范围
15
SELECT * FROM emp WHERE entry_date BETWEEN '2000-01-01' AND '2010-01-01';
16

17
-- IN 多值
18
SELECT * FROM emp WHERE job IN (2, 3, 4);
19

20
-- 模糊匹配
21
SELECT * FROM emp WHERE name LIKE '__';       -- 两个字
22
SELECT * FROM emp WHERE name LIKE '张%';      -- 姓张
23
SELECT * FROM emp WHERE name LIKE '%二%';     -- 包含"二"

显示更多显示更少

聚合函数#

函数	功能
`COUNT(字段)`	统计行数（忽略 NULL）
`SUM(字段)`	求和
`MAX(字段)`	最大值
`MIN(字段)`	最小值
`AVG(字段)`	平均值

聚合函数会忽略 NULL 值。COUNT(*) 是统计总行数的推荐写法（MySQL 底层优化）。

示例：

1
SELECT COUNT(*) FROM emp;         -- 员工总数
2
SELECT AVG(salary) FROM emp;      -- 平均薪资
3
SELECT MIN(salary) FROM emp;      -- 最低薪资
4
SELECT MAX(salary) FROM emp;      -- 最高薪资
5
SELECT SUM(salary) FROM emp;      -- 薪资总额

分组查询（GROUP BY）#

1
SELECT 字段列表 FROM 表名 [WHERE 条件] GROUP BY 分组字段 [HAVING 分组后条件];

示例：

1
-- 按性别统计人数
2
SELECT gender, COUNT(*) FROM emp GROUP BY gender;
3

4
-- 分组前筛选 + 分组后过滤
5
SELECT job, COUNT(*)
6
FROM emp
7
WHERE entry_date <= '2015-01-01'
8
GROUP BY job
9
HAVING COUNT(*) >= 2;

WHERE 与 HAVING 的区别#

对比维度	WHERE	HAVING
执行时机	分组前过滤	分组后过滤
能否使用聚合函数	不能	可以

执行顺序：WHERE → 聚合函数 → HAVING

排序查询（ORDER BY）#

1
SELECT 字段列表 FROM 表名 ORDER BY 字段1 [ASC|DESC], 字段2 [ASC|DESC] ...;

ASC：升序（默认，可省略）
DESC：降序

示例：

1
-- 按入职时间升序
2
SELECT * FROM emp ORDER BY entry_date;
3

4
-- 按入职时间降序
5
SELECT * FROM emp ORDER BY entry_date DESC;
6

7
-- 多字段排序：入职时间升序，相同时按更新时间降序
8
SELECT * FROM emp ORDER BY entry_date ASC, update_time DESC;

分页查询（LIMIT）#

1
SELECT 字段列表 FROM 表名 LIMIT 起始索引, 查询记录数;

起始索引从 0 开始。
计算公式：起始索引 = (页码 - 1) × 每页记录数

示例：

1
-- 第1页，每页5条
2
SELECT * FROM emp LIMIT 0, 5;
3
-- 等价简写
4
SELECT * FROM emp LIMIT 5;
5

6
-- 第2页，每页5条
7
SELECT * FROM emp LIMIT 5, 5;
8

9
-- 第3页，每页5条
10
SELECT * FROM emp LIMIT 10, 5;

常见场景#

DQL 是业务系统中最核心的操作，网站/APP 的数据展示、搜索、报表导出等功能均依赖 DQL 实现。

注意事项#

NULL 判断只能用 IS NULL / IS NOT NULL，不能用 = NULL。
分组后 SELECT 的字段通常仅限聚合函数和分组字段，查询其他字段无意义。
LIMIT 是 MySQL 方言，不同数据库的分页语法不同。
分页查询第一页时，LIMIT 5 等价于 LIMIT 0, 5。

测试数据#

1
-- 创建 emp 表并插入测试数据，详见源文档 3.3.2 节。
2
-- 包含 30 条梁山好汉员工数据，覆盖性别、职位、薪资等多种筛选场景。

SpringBootWeb入门

Sun, 17 May 2026 00:00:00 GMT

SpringBootWeb入门#

定义#

SpringBoot是Spring家族中的一个项目，用于快速构建Spring应用程序。它最大的特点是简化配置和快速开发，通过起步依赖和内嵌服务器等机制，让开发者能够快速搭建Web应用。

语法/用法#

1. 创建SpringBoot工程#

通过Spring官方骨架或阿里云脚手架创建项目，勾选Web开发相关依赖。

2. 定义Controller类#

1
package com.itheima;
2

3
import org.springframework.web.bind.annotation.RequestMapping;
4
import org.springframework.web.bind.annotation.RestController;
5

6
@RestController //标识当前类是一个请求处理类
7
public class HelloController {
8

9
    @RequestMapping("/hello") //标识请求路径
10
    public String hello(String name){
11
        System.out.println("HelloController ... hello: " + name);
12
        return "Hello " + name;
13
    }
14
}

3. 运行测试#

运行SpringBoot自动生成的引导类（标识有@SpringBootApplication注解的类），访问 http://localhost:8080/hello?name=itheima。

常见场景#

快速构建Web应用：通过SpringBoot快速搭建RESTful API服务
微服务开发：作为微服务架构中的单个服务模块
企业级应用：开发企业内部的业务管理系统

注意事项#

起步依赖：SpringBoot通过起步依赖简化配置，如spring-boot-starter-web包含了Web应用开发所需的所有常见依赖
内嵌服务器：SpringBoot内置Tomcat服务器，无需单独部署
版本选择：如果官方脚手架提供的版本不合适，可以在创建项目后修改pom.xml中的版本号
网络问题：如果无法连接Spring官方脚手架，可以使用阿里云脚手架：https://start.aliyun.com

HTTP协议概述

Sun, 17 May 2026 00:00:00 GMT

HTTP协议概述#

定义#

HTTP：Hyper Text Transfer Protocol（超文本传输协议），规定了浏览器与服务器之间数据传输的规则。HTTP是互联网上应用最为广泛的一种网络协议，要求浏览器在向服务器发送请求数据时，或是服务器在向浏览器发送响应数据时，都必须按照固定的格式进行数据传输。

语法/用法#

HTTP协议特点#

基于TCP协议：面向连接，安全。TCP是一种面向连接的（建立连接之前需要经过三次握手）、可靠的、基于字节流的传输层通信协议。
基于请求-响应模型：一次请求对应一次响应（先请求后响应），请求和响应是一一对应关系，没有请求就没有响应。
无状态协议：对于数据没有记忆能力，每次请求-响应都是独立的。

BS架构与CS架构#

BS架构（Browser/Server）：客户端只需要浏览器，应用程序的逻辑和数据都存储在服务端。优点：维护方便；缺点：体验一般。
CS架构（Client/Server）：需要单独开发维护客户端。优点：体验不错；缺点：开发维护麻烦。

常见场景#

Web应用通信：浏览器与服务器之间的数据传输
前后端分离架构：前端通过HTTP请求调用后端API
移动端应用：移动App通过网络请求访问服务器接口

注意事项#

无状态的解决方案：由于HTTP协议无状态特性导致请求之间无法共享数据（如购物车场景），Java通过会话技术（Cookie、Session）来解决这个问题
静态资源与动态资源：HTML、CSS、JS及图片等属于静态资源（不会改变）；Servlet、基于Spring的动态资源会根据用户请求动态生成内容

HTTP请求与响应

Sun, 17 May 2026 00:00:00 GMT

HTTP请求与响应#

定义#

HTTP协议分为请求协议和响应协议。请求协议规定了浏览器将数据发送到服务器的格式，包括请求行、请求头、请求体。响应协议规定了服务器将数据返回给浏览器的格式，包括响应行、响应头、响应体。

语法/用法#

请求协议格式#

请求行：请求方式资源路径协议/版本（如：GET /brand/findAll?name=OPPO&status=1 HTTP/1.1）
请求头：key: value 格式，常见请求头如下：

请求头	含义
Host	请求的主机名
User-Agent	浏览器版本
Accept	能接收的资源类型
Accept-Language	偏好的语言
Accept-Encoding	支持的压缩类型
Content-Type	请求主体的数据类型
Content-Length	数据主体的大小（字节）

请求体：存储POST请求参数，与请求头之间有空行分隔

GET与POST请求区别#

区别方式	GET请求	POST请求
请求参数	在请求行中（URL可见）	在请求体中
请求参数长度	有限制	无限制
安全性	较低	相对较高

响应协议格式#

响应行：协议/版本响应状态码状态码描述（如：HTTP/1.1 200 OK）
响应头：常见响应头有 Content-Type、Content-Length、Content-Encoding、Cache-Control、Set-Cookie
响应体：存储响应数据，与响应头之间有空行分隔

获取请求数据（服务端）#

1
@RestController
2
public class RequestController {
3
    @RequestMapping("/request")
4
    public String request(HttpServletRequest request){
5
        //1.获取请求参数
6
        String name = request.getParameter("name");
7
        String age = request.getParameter("age");
8
        //2.获取请求路径
9
        String uri = request.getRequestURI();
10
        String url = request.getRequestURL().toString();
11
        //3.获取请求方式
12
        String method = request.getMethod();
13
        //4.获取请求头
14
        String header = request.getHeader("User-Agent");
15
        return "request success";
16
    }
17
}

显示更多显示更少

设置响应数据#

1
@RestController
2
public class ResponseController {
3
    @RequestMapping("/response")
4
    public void response(HttpServletResponse response) throws IOException {
5
        response.setStatus(401);
6
        response.setHeader("name","itcast");
7
        response.setContentType("text/html;charset=utf-8");
8
        response.getWriter().write("<h1>hello response</h1>");
9
    }
10

11
    @RequestMapping("/response2")
12
    public ResponseEntity<String> response2() {
13
        return ResponseEntity
14
                .status(401)
15
                .header("name","itcast")
16
                .body("<h1>hello response</h1>");
17
    }
18
}

显示更多显示更少

常见场景#

服务端根据请求头中的User-Agent判断浏览器类型，处理浏览器兼容问题
前后端分离项目中通过Content-Type指定JSON格式传输数据
通过Cache-Control控制浏览器缓存策略

注意事项#

响应状态码和响应头通常不需要手动设定，服务器会根据请求处理逻辑自动设置
Web服务器（Tomcat）已对HTTP协议数据进行封装（HttpServletRequest / HttpServletResponse），程序员无需直接操作协议

附录：常见状态码#

状态码	含义
200	客户端请求成功
404	请求资源不存在
500	服务端发生不可预期的错误

SpringBootWeb案例

Sun, 17 May 2026 00:00:00 GMT

SpringBootWeb案例#

定义#

本案例展示了如何使用SpringBoot开发一个Web应用，完成用户列表的渲染展示。前端页面通过Ajax请求后端接口，后端从文本文件中加载用户数据并返回JSON格式数据，前端再将数据渲染展示在表格中。

语法/用法#

1. 定义实体类#

1
package com.itheima.pojo;
2

3
import lombok.AllArgsConstructor;
4
import lombok.Data;
5
import lombok.NoArgsConstructor;
6
import java.time.LocalDateTime;
7

8
@Data
9
@NoArgsConstructor
10
@AllArgsConstructor
11
public class User {
12
    private Integer id;
13
    private String username;
14
    private String password;
15
    private String name;
16
    private Integer age;
17
    private LocalDateTime updateTime;
18
}

显示更多显示更少

2. 引入Hutool工具包#

1
<dependency>
2
    <groupId>cn.hutool</groupId>
3
    <artifactId>hutool-all</artifactId>
4
    <version>5.8.27</version>
5
</dependency>

3. 开发Controller#

1
import cn.hutool.core.io.IoUtil;
2
import cn.hutool.json.JSONConfig;
3
import cn.hutool.json.JSONUtil;
4
import com.itheima.pojo.User;
5
import org.springframework.web.bind.annotation.RequestMapping;
6
import org.springframework.web.bind.annotation.RestController;
7
import java.io.InputStream;
8
import java.nio.charset.StandardCharsets;
9
import java.time.LocalDateTime;
10
import java.time.format.DateTimeFormatter;
11
import java.util.ArrayList;
12
import java.util.List;
13
import java.util.stream.Collectors;
14

15
@RestController
16
public class UserController {
17
    @RequestMapping("/list")
18
    public String list(){
19
        //1.加载并读取文件
20
        InputStream in = this.getClass().getClassLoader().getResourceAsStream("user.txt");
21
        ArrayList<String> lines = IoUtil.readLines(in, StandardCharsets.UTF_8, new ArrayList<>());
22
        //2.解析数据，封装成User对象
23
        List<User> userList = lines.stream().map(line -> {
24
            String[] parts = line.split(",");
25
            return new User(
26
                Integer.parseInt(parts[0]), parts[1], parts[2],
27
                parts[3], Integer.parseInt(parts[4]),
28
                LocalDateTime.parse(parts[5], DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"))
29
            );
30
        }).collect(Collectors.toList());
31
        //3.响应JSON数据
32
        return JSONUtil.toJsonStr(userList, JSONConfig.create().setDateFormat("yyyy-MM-dd HH:mm:ss"));
33
    }
34
}

显示更多显示更少

4. @ResponseBody注解#

类型：方法注解、类注解
位置：书写在Controller方法上或类上
作用：将方法返回值直接响应给浏览器，如果返回值类型是实体对象/集合，将转换为JSON格式后响应
@RestController = @Controller + @ResponseBody，在类上加此注解后，所有方法自动带有@ResponseBody功能

常见场景#

前后端分离项目中，后端Controller返回JSON数据给前端渲染
将本地文本文件数据读取后通过API接口暴露
使用Hutool等工具库简化文件读取和JSON转换操作

注意事项#

代码职责混乱问题：上述案例将数据读取、逻辑处理、响应代码全部写在Controller中，当业务复杂时会导致代码复用性差、难以维护
前后端分离的项目中，一般直接在请求处理类上加@RestController注解，无需在方法上加@ResponseBody

三层架构与分层解耦

Sun, 17 May 2026 00:00:00 GMT

三层架构与分层解耦#

定义#

三层架构是将后端代码按照职责划分为三个层次的设计模式：

Controller（控制层）：接收前端发送的请求，对请求进行处理，并响应数据
Service（业务逻辑层）：处理具体的业务逻辑
Dao（数据访问层）：负责数据访问操作，包括数据的增、删、改、查

分层解耦的目标是降低层与层之间的依赖程度，遵循”高内聚、低耦合”的软件设计原则。

高内聚：一个模块中各个元素之间联系紧密 低耦合：软件中各个层/模块之间的依赖关联程度越低越好

语法/用法#

三层架构代码结构#

1
com.itheima
2
├── controller         # 控制层
3
│   └── UserController.java
4
├── service            # 业务逻辑层
5
│   ├── UserService.java         （接口）
6
│   └── impl/
7
│       └── UserServiceImpl.java （实现类）
8
├── dao                # 数据访问层
9
│   ├── UserDao.java             （接口）
10
│   └── impl/
11
│       └── UserDaoImpl.java     （实现类）
12
└── pojo               # 实体类
13
    └── User.java

Controller层代码#

1
package com.itheima.controller;
2

3
import com.itheima.pojo.User;
4
import com.itheima.service.UserService;
5
import com.itheima.service.impl.UserServiceImpl;
6
import org.springframework.web.bind.annotation.RequestMapping;
7
import org.springframework.web.bind.annotation.RestController;
8
import java.util.List;
9

10
@RestController
11
public class UserController {
12
    private UserService userService = new UserServiceImpl();
13

14
    @RequestMapping("/list")
15
    public List<User> list(){
16
        List<User> userList = userService.findAll();
17
        return userList;
18
    }
19
}

显示更多显示更少

Service层代码（接口+实现）#

1
// 接口
2
package com.itheima.service;
3
import com.itheima.pojo.User;
4
import java.util.List;
5

6
public interface UserService {
7
    public List<User> findAll();
8
}
9

10
// 实现类
11
package com.itheima.service.impl;
12
import com.itheima.dao.UserDao;
13
import com.itheima.dao.impl.UserDaoImpl;
14
// ...（省略import）
15

16
public class UserServiceImpl implements UserService {
17
    private UserDao userDao = new UserDaoImpl();
18

19
    @Override
20
    public List<User> findAll() {
21
        List<String> lines = userDao.findAll();
22
        // 解析数据、封装User对象并返回
23
        // ...
24
    }
25
}

显示更多显示更少

Dao层代码（接口+实现）#

1
// 接口
2
package com.itheima.dao;
3
import java.util.List;
4

5
public interface UserDao {
6
    public List<String> findAll();
7
}
8

9
// 实现类
10
package com.itheima.dao.impl;
11
import cn.hutool.core.io.IoUtil;
12
import com.itheima.dao.UserDao;
13
import java.io.InputStream;
14
import java.nio.charset.StandardCharsets;
15
import java.util.ArrayList;
16
import java.util.List;
17

18
public class UserDaoImpl implements UserDao {
19
    @Override
20
    public List<String> findAll() {
21
        InputStream in = this.getClass().getClassLoader().getResourceAsStream("user.txt");
22
        ArrayList<String> lines = IoUtil.readLines(in, StandardCharsets.UTF_8, new ArrayList<>());
23
        return lines;
24
    }
25
}

显示更多显示更少

执行流程#

前端请求 → Controller层接收并响应 → Controller调用Service层处理业务逻辑 → Service调用Dao层获取数据 → Dao层返回数据给Service → Service处理完后返回Controller → Controller响应给前端

常见场景#

几乎所有企业级Web项目的标准分层结构
需要将数据读取、业务逻辑、请求处理分离的场景
需要提高代码复用性和可维护性的项目

注意事项#

单一职责原则：一个类或一个方法只做一件事，只管一块功能，使类、接口、方法的复杂度更低、可读性更强、扩展性更好
三层架构的好处：复用性强、便于维护、利于扩展
接口+实现的设计：Service和Dao层使用接口定义规范，实现类负责具体逻辑，便于替换实现
直接new导致耦合：如果直接在Controller中new UserServiceImpl()，当需要切换实现类时就必须修改Controller代码，这就是耦合问题，需要通过IOC/DI来解决

IOC与DI

Sun, 17 May 2026 00:00:00 GMT

IOC与DI#

定义#

控制反转（IOC，Inversion Of Control）：对象的创建控制权由程序自身转移到外部（容器），即由Spring IOC容器负责创建和管理对象。

依赖注入（DI，Dependency Injection）：容器为应用程序提供运行时所需的资源（对象）。

Bean对象：IOC容器中创建和管理的对象。

核心思想#

提供一个容器，容器中存储bean对象
Controller程序从容器中获取所需类型的对象，而非直接new
将对象的创建权从程序员主动创建转移到容器管理

语法/用法#

1. Bean的声明（IOC）#

使用注解将类交给IOC容器管理：

注解	说明	位置
`@Component`	声明bean的基础注解	不属于以下三类时使用
`@Controller`	@Component的衍生注解	控制层类
`@Service`	@Component的衍生注解	业务层类
`@Repository`	@Component的衍生注解	数据访问层类

示例：

1
@Service
2
public class UserServiceImpl implements UserService {
3
    @Autowired
4
    private UserDao userDao;
5
    // ...
6
}
7

8
@Repository
9
public class UserDaoImpl implements UserDao {
10
    // ...
11
}
12

13
@RestController
14
public class UserController {
15
    @Autowired
16
    private UserService userService;
17
    // ...
18
}

显示更多显示更少

2. 组件扫描#

声明bean的四大注解需要被@ComponentScan扫描才能生效
@SpringBootApplication注解已包含@ComponentScan，默认扫描启动类所在包及其子包
因此只需将业务类放在启动类所在包的子包中即可

3. @Autowired依赖注入（DI）三种方式#

方式一：属性注入

1
@RestController
2
public class UserController {
3
    @Autowired
4
    private UserService userService;
5
}

优点：代码简洁、快速开发
缺点：隐藏了类之间的依赖关系、可能破坏封装性

方式二：构造函数注入（官方推荐）

1
@RestController
2
public class UserController {
3
    private final UserService userService;
4

5
    @Autowired //如果只有一个构造函数，@Autowired可以省略
6
    public UserController(UserService userService) {
7
        this.userService = userService;
8
    }
9
}

优点：依赖关系清晰、代码安全性高
注意：如果只有一个构造函数，@Autowired可省略

方式三：setter注入

1
@RestController
2
public class UserController {
3
    private UserService userService;
4

5
    @Autowired
6
    public void setUserService(UserService userService) {
7
        this.userService = userService;
8
    }
9
}

优点：保持封装性、依赖关系清晰
缺点：需要额外编写setter方法

4. 多实现类注入冲突解决方案#

当IOC容器中存在多个相同类型的bean时，使用以下方式指定：

方案	用法	说明
`@Primary`	加在实现类上	确定默认实现
`@Qualifier`	配合@Autowired使用	按bean名称指定注入
`@Resource`	JDK提供，name属性指定bean名称	按名称注入

1
// 方案一
2
@Primary
3
@Service
4
public class UserServiceImpl implements UserService { }
5

6
// 方案二
7
@Qualifier("userServiceImpl")
8
@Autowired
9
private UserService userService;
10

11
// 方案三
12
@Resource(name = "userServiceImpl")
13
private UserService userService;

常见场景#

解耦层与层之间的依赖：Controller不再直接new Service，Service不再直接new Dao
灵活切换实现类：当业务需求变更需要替换Service实现时，只需将新实现类交给IOC容器管理，无需修改Controller代码
依赖管理：Spring容器统一管理对象的生命周期和依赖关系

注意事项#

声明控制器bean只能用@Controller（在SpringBoot集成Web开发中）
bean名称：通过注解的value属性指定bean名字，默认类名首字母小写
@Autowired vs @Resource：@Autowired是Spring框架注解，默认按类型注入；@Resource是JDK注解，按名称注入
官方推荐构造函数注入方式（更规范），但企业项目中属性注入也很常见（更简洁高效）
只有被组件扫描到的注解才会生效，确保业务类在启动类的子包路径下

Maven概述与核心作用

Sat, 16 May 2026 00:00:00 GMT

Maven概述#

定义#

Maven 是一款用于管理和构建 Java 项目的工具，是 Apache 旗下的一个开源项目。

Maven介绍

Apache 软件基金会成立于 1999 年 7 月，是目前世界上最大的开源软件基金会，专门为支持开源项目而生的非盈利性组织。开源项目列表：https://www.apache.org/index.html#projects-list

官网：https://maven.apache.org/

Maven官网

Apache Maven 是一个项目管理和构建工具，它基于项目对象模型（Project Object Model，简称 POM）的概念，通过一小段描述信息来管理项目的构建、报告和文档。

Maven的核心作用#

Maven作用总览

1. 依赖管理#

方便快捷地管理项目依赖的资源（jar 包），避免版本冲突问题。

未使用 Maven 时：需要手动从官网下载 jar 包，再导入项目。

使用Maven前

使用 Maven 后：只需在 pom.xml 中添加依赖配置，Maven 自动下载对应的依赖。

使用Maven后

2. 项目构建#

Maven 提供标准化的跨平台自动化构建方式。代码需要经历编译、测试、打包、发布等过程，Maven 通过一套简单的命令完成这些操作：

项目构建流程

Maven构建命令

通过 Maven 命令即可完成编译（compile）、测试（test）、打包（package）、发布（deploy）等操作，且跨平台适用（Windows / Linux / Mac）。

3. 统一项目结构#

Maven 提供了一套标准的 Java 项目目录结构：

Maven标准目录结构

无论使用 Eclipse、MyEclipse 还是 IDEA，只要是基于 Maven 构建的 Java 项目，目录结构都相同，可以在各开发工具之间直接导入使用。

跨IDE导入

目录结构说明：

src/main/java：源代码文件
src/main/resources：源代码配置文件
src/test/java：测试代码文件
src/test/resources：测试代码配置文件
target：编译、打包生成文件存放目录

注意事项#

Maven 内容分为 Maven 核心和 Maven 进阶两部分，基础阶段先学习核心部分。
Maven 本身也是用 Java 开发的，运行时依赖其他 jar 包。

M4A音乐自动提取歌词与封面教程

Sat, 16 May 2026 00:00:00 GMT

M4A 音乐自动提取歌词与封面教程#

背景#

博客的音乐收藏页面（/music）需要为每首歌准备三样东西：

文件	用途
`.m4a` / `.mp3`	音频文件本身
`.lrc`	同步歌词（带时间轴的歌词文件）
`.jpg`	专辑封面图
`.md`	博客的 Markdown 内容文件

手动搜歌词、下载封面、写 md 实在太麻烦。我写了一套脚本，两种方式一条命令全部搞定。

两种使用模式#

脚本 fetch-lrc.py 支持两种模式：

模式	使用场景	命令
本地文件模式	已有 M4A 文件，提取内嵌封面+API 下载歌词	`python fetch-lrc.py song.m4a --md`
搜索下载模式	没有本地文件，直接搜歌名下载音频+封面+歌词	`python fetch-lrc.py "晴天" "周杰伦" --md`

工作原理#

flowchart TD A[输入] --> B{是文件路径?} B -->|是| C[读取 M4A 元数据] C --> D{内嵌封面?} D -->|有| E[提取封面] D -->|无| F[Meting API 搜索] B -->|否| G[搜歌名下载模式] G --> H[Meting API 搜索] H --> I[显示搜索结果列表] I --> J[用户选择/自动选第一首] J --> K[下载音频] K --> L[下载封面] L --> M[下载歌词] M --> N[生成 MD] F --> L E --> M

本地文件模式：读取 M4A 元数据（歌名、歌手）→ 提取内嵌封面 → API 搜索 → 下载歌词 → 生成 md
搜索下载模式：输入歌名搜索 → 选择结果 → 下载音频 → 下载封面 → 下载歌词 → 生成 md

环境准备#

安装依赖#

需要 Python 3 和 mutagen 库：

Terminal window

1
pip install mutagen

注意：Windows 上可能有多个 Python 版本，确保用装过 mutagen 的那个。可以用完整路径指定，如 C:/Users/xxx/AppData/Local/Programs/Python/Python313/python.exe

无需 ffmpeg，纯 Python 实现。

使用方法#

本地文件模式#

Terminal window

1
# 处理单个文件
2
python scripts/fetch-lrc.py "path/to/song.m4a" --md
3

4
# 处理整个目录（批量）
5
python scripts/fetch-lrc.py "path/to/music/folder" --md

脚本会遍历目录下所有 .m4a、.mp3、.flac 等文件，逐个提取封面和下载歌词。

搜索下载模式#

Terminal window

1
# 只搜歌名
2
python scripts/fetch-lrc.py "晴天" --md
3

4
# 歌名 + 歌手（提高准确度）
5
python scripts/fetch-lrc.py "海阔天空" "Beyond" --md
6

7
# 换平台
8
python scripts/fetch-lrc.py "起风了" --md --server=kugou
9

10
# 指定下载目录
11
python scripts/fetch-lrc.py "晴天" "周杰伦" --md --out=./downloads
12

13
# 只搜索预览（不下载）
14
python scripts/fetch-lrc.py "晴天" --dry-run

搜索结果有多条时会显示列表，交互模式下可手动选择序号，非交互终端自动选第一首。

完整参数表#

参数	说明	默认值
第一个参数	M4A 文件路径 / 歌名	必填
第二个参数	歌手名（搜索模式）	空
`--md`	生成博客 md 文件到 `src/content/bangumi/music/`	关闭
`--no-md`	只提取/下载，不生成 md	-
`--server=xxx`	音乐平台	`netease`
`--audio-base=xxx`	自定义 URL 前缀	`https://ph.0824.uk/file/music/`
`--md-dir=xxx`	自定义 md 输出目录	`src/content/bangumi/music/`
`--out=xxx`	搜索模式的下载目录	`scripts/downloads/`
`--dry-run`	搜索模式只预览，不下载	-

支持的平台#

值	平台
`netease`	网易云音乐
`tencent`	QQ 音乐
`kugou`	酷狗音乐
`baidu`	百度音乐
`kuwo`	酷我音乐

实操示例：本地文件模式#

以歌曲《暗恋过结局呢》为例。

第一步：准备 M4A 文件#

将 M4A 文件放到任意目录，例如 scripts/zcyyy/：

1
scripts/zcyyy/
2
└── 暗恋过结局呢.m4a

第二步：运行脚本#

Terminal window

1
python scripts/fetch-lrc.py scripts/zcyyy --md

第三步：查看输出#

1
scripts/zcyyy/
2
├── 暗恋过结局呢.m4a    ← 原始文件
3
├── 暗恋过结局呢.lrc    ← API 下载的同步歌词
4
└── 暗恋过结局呢.jpg    ← API 下载的封面图
5

6
src/content/bangumi/music/
7
└── 暗恋过 结局呢.md    ← 自动生成的博客内容文件

实操示例：搜索下载模式#

以歌曲《知我》为例。

第一步：运行命令#

Terminal window

1
python scripts/fetch-lrc.py "知我" "哦漏" --md

第二步：选择结果#

1
搜索: 知我 - 哦漏
2

3
搜索结果:
4

5
  [ 1] 知我 - 国风堂 / 哦漏
6
  [ 2] 知我 (伴奏) - 国风堂 / 哦漏
7
  ...
8

9
选择序号 (1-2, 默认 1): 1
10

11
选中: 知我 - 国风堂 / 哦漏
12
  音频 [100%] =========================> 11 MB/11 MB
13
  [封面] 知我-国风堂哦漏.jpg
14
  [歌词] 知我-国风堂哦漏.lrc (1950 字符)
15
  [MD] 知我.md

显示更多显示更少

第三步：输出文件#

1
scripts/downloads/
2
├── 知我-国风堂哦漏.m4a    ← 下载的音频
3
├── 知我-国风堂哦漏.jpg    ← 封面图
4
└── 知我-国风堂哦漏.lrc    ← 同步歌词
5

6
src/content/bangumi/music/
7
└── 知我.md               ← 自动生成的博客内容文件

生成的 Markdown 格式#

1
---
2
title: 知我
3
category: music
4
status: 2
5
image: https://ph.0824.uk/file/music/知我-国风堂哦漏.jpg
6
artist: 国风堂 / 哦漏
7
audioUrl: https://ph.0824.uk/file/music/知我-国风堂哦漏.m4a
8
lrcUrl: https://ph.0824.uk/file/music/知我-国风堂哦漏.lrc
9
score: 0
10
published: 2026-05-16
11
---

生成后手动调整 score（评分）、status（状态）、title（清理多余空格）即可。

状态码含义：

值	含义
`1`	想听
`2`	听过
`3`	在听
`4`	搁置
`5`	弃了

批量处理#

Terminal window

1
# 批量处理本地 M4A 文件
2
python scripts/fetch-lrc.py D:/Music/ --md
3

4
# 批量下载歌单（需提前准备好歌名列表，自行写批处理循环）

已处理的文件会自动跳过（封面、歌词、md 已存在则不再重复生成）。如需重新生成，先删除已有文件即可。

常见问题#

Q: 歌词下载失败？#

换个平台试试：

Terminal window

1
python scripts/fetch-lrc.py song.m4a --md --server=kugou

Q: 搜索下载模式下无法手动选择？#

非交互终端（如管道执行）会自动选第一首。手动终端用 PowerShell 或 CMD 打开运行即可交互选择。

Q: 音频下载失败？#

某些热门歌曲因版权限制，Meting API 可能返回 404。尝试换平台搜索：

Terminal window

1
python scripts/fetch-lrc.py "晴天" "周杰伦" --md --server=kugou

Q: 封面不对？#

本地文件模式优先使用 M4A 内嵌封面。如果内嵌封面不对，删除自动生成的 .jpg 后重新运行即可从 API 下载。

Q: 文件名有空格和特殊符号？#

最新版脚本会自动清理文件名中的空格和特殊字符，确保 URL 合法。

Q: 不想生成 md？#

Terminal window

1
python scripts/fetch-lrc.py song.m4a --no-md

Q: URL 前缀怎么改？#

Terminal window

1
python scripts/fetch-lrc.py song.m4a --md --audio-base=https://你的cdn.com/music/

Q: pip install mutagen 后还是报 ModuleNotFoundError？#

Windows 上可能有多个 Python 版本。检查方式：

Terminal window

1
# 查看当前 python 路径
2
where python
3

4
# 用装过 mutagen 的那个 Python 执行
5
C:/完整路径/python.exe scripts/fetch-lrc.py ...

总结#

操作	命令
本地文件 → 歌词+封面	`python scripts/fetch-lrc.py song.m4a --md`
批量导入本地文件	`python scripts/fetch-lrc.py ./music-folder/ --md`
直接搜歌下载	`python scripts/fetch-lrc.py "晴天" "周杰伦" --md`
只要音频+封面+歌词	`python scripts/fetch-lrc.py "晴天" --no-md`
换个平台搜	`python scripts/fetch-lrc.py "晴天" --md --server=kugou`

整个流程只需一条命令，博客音乐收藏页面就自动上线新歌了。

Maven模型与仓库

Sat, 16 May 2026 00:00:00 GMT

Maven模型与仓库#

Maven模型#

Maven 基于三种核心模型构建：

1. 构建生命周期模型（Build Lifecycle & Phases）#

定义标准化构建流程。当需要编译时，Maven 提供编译插件；需要打包时，提供打包插件等。

构建生命周期模型

2. 项目对象模型（Project Object Model）#

将项目抽象成一个对象模型，拥有专属坐标（唯一标识），通过坐标可以定位到所需资源位置。

项目对象模型

坐标由三部分组成：

组成部分	含义	示例
`groupId`	组织名（域名反写）	`com.itheima`
`artifactId`	模块名	`maven-project01`
`version`	版本号	`1.0-SNAPSHOT`

Maven项目坐标示例

3. 依赖管理模型（Dependency）#

使用坐标描述当前项目依赖哪些第三方 jar 包。过去需要手动复制 jar 包到 lib 目录，现在只需在 pom.xml 中配置依赖即可，对应的 jar 包存储在本地 Maven 仓库中。

依赖管理模型

pom.xml依赖配置

本地仓库jar文件

Maven仓库#

仓库本质是一个目录（文件夹），用于存储开发中所有依赖（jar 包）和插件。

Maven 仓库分为三类：

仓库类型	说明
本地仓库	自己计算机上的目录，用来存储 jar 包
中央仓库	由 Maven 团队维护的全球唯一仓库，地址：https://repo1.maven.org/maven2/
远程仓库（私服）	一般由公司团队搭建的私有仓库

Maven仓库分类

jar 包查找顺序#

当项目中使用坐标引入依赖 jar 包后：

先查找本地仓库中是否有对应的 jar 包
- 有 → 项目直接引用
- 没有 → 去中央仓库下载到本地仓库
如果搭建了远程仓库（私服），查找顺序变为：本地仓库 → 远程仓库 → 中央仓库

注意事项#

中央仓库在国外，下载速度可能较慢，建议配置阿里云私服镜像加速。
私服中通常缓存了常用的开源 jar 包，可以减少外网访问。

Maven安装配置与常见问题

Sat, 16 May 2026 00:00:00 GMT

Maven安装配置#

下载#

下载地址：https://maven.apache.org/download.cgi

建议解压到没有中文、特殊字符的路径下。

解压后目录结构：

目录	说明
`bin/`	存放可执行命令（重点关注 `mvn` 命令）
`conf/`	存放配置文件（`settings.xml` 后期需要修改）
`lib/`	存放 Maven 依赖的 jar 包（Maven 本身也是 Java 开发）

配置步骤#

1. 配置本地仓库#

在 conf/settings.xml 中配置 <localRepository> 标签，指定本地仓库路径，用于存储下载的 jar 包。

1
<localRepository>E:/maven/repository</localRepository>

2. 配置阿里云私服#

中央仓库在国外，下载速度较慢。在 conf/settings.xml 的 <mirrors> 标签中添加：

1
<mirror>
2
    <id>alimaven</id>
3
    <name>aliyun maven</name>
4
    <url>http://maven.aliyun.com/nexus/content/groups/public/</url>
5
    <mirrorOf>central</mirrorOf>
6
</mirror>

3. 配置环境变量#

新建系统变量 MAVEN_HOME，值为 Maven 解压安装目录
在 Path 中添加 %MAVEN_HOME%\bin
验证安装：命令行执行 mvn -v，输出版本信息表示安装成功

4. 配置关联 JDK 版本（可选）#

在 conf/settings.xml 的 <profiles> 中添加：

1
<profile>
2
    <id>jdk-17</id>
3
    <activation>
4
        <activeByDefault>true</activeByDefault>
5
        <jdk>17</jdk>
6
    </activation>
7
    <properties>
8
        <maven.compiler.source>17</maven.compiler.source>
9
        <maven.compiler.target>17</maven.compiler.target>
10
        <maven.compiler.compilerVersion>17</maven.compiler.compilerVersion>
11
    </properties>
12
</profile>

常见问题：依赖下载失败#

问题现象：Maven 项目中添加的依赖未正确下载，右侧 Maven 面板中依赖报红，reload 重新加载也不会再下载。

产生原因：由于网络原因，依赖下载不完整，Maven 仓库中生成了 xxx.lastUpdated 文件，该文件不删除则不会重新下载。

解决方案：

根据 Maven 依赖坐标，找到仓库中对应的 xxx.lastUpdated 文件并删除，然后重新加载项目。
通过命令 del /s *.lastUpdated 批量递归删除指定目录下的所有 xxx.lastUpdated 文件。
依赖下载完成后，若 Maven 面板仍然报红，可关闭 IDEA 后重新打开加载项目。

注意事项#

安装路径中避免包含中文和空格。
配置 settings.xml 时注意标签的嵌套层级，<mirror> 必须在 <mirrors> 内部。
首次下载依赖时耗时较长，需耐心等待。

Maven坐标与依赖管理

Sat, 16 May 2026 00:00:00 GMT

Maven坐标与依赖管理#

Maven坐标#

坐标是资源的唯一标识，通过坐标可以唯一定位资源位置，用于定义项目或引入依赖。

坐标组成#

组成部分	含义	说明
`groupId`	组织名称	通常为域名反写，如 `com.itheima`
`artifactId`	模块名称	如 `order-service`、`goods-service`
`version`	版本号	`SNAPSHOT`（快照版）或 `RELEASE`（发行版）

SNAPSHOT：功能不稳定、尚处于开发中的快照版本
RELEASE：功能趋于稳定、可以用于发行的版本

坐标表示项目

POM 文件结构#

POM（Project Object Model）通过 pom.xml 描述当前 Maven 项目。

1
<?xml version="1.0" encoding="UTF-8"?>
2
<project xmlns="http://maven.apache.org/POM/4.0.0"
3
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
5
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
6
    <!-- POM模型版本 -->
7
    <modelVersion>4.0.0</modelVersion>
8

9
    <!-- 当前项目坐标 -->
10
    <groupId>com.itheima</groupId>
11
    <artifactId>maven-project01</artifactId>
12
    <version>1.0-SNAPSHOT</version>
13

14
    <!-- 项目的JDK版本及编码 -->
15
    <properties>
16
        <maven.compiler.source>17</maven.compiler.source>
17
        <maven.compiler.target>17</maven.compiler.target>
18
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
19
    </properties>
20
</project>

显示更多显示更少

核心标签说明：

标签	说明
`<project>`	POM 文件根标签
`<modelVersion>`	POM 模型版本，目前为 4.0.0
`<groupId>` / `<artifactId>` / `<version>`	项目坐标，定位项目在本地仓库中的位置
`<maven.compiler.source>`	编译 JDK 版本
`<maven.compiler.target>`	运行 JDK 版本
`<project.build.sourceEncoding>`	项目字符集编码

依赖配置#

基本配置#

在 pom.xml 中使用 <dependencies> 和 <dependency> 引入依赖：

1
<dependencies>
2
    <dependency>
3
        <groupId>org.springframework</groupId>
4
        <artifactId>spring-context</artifactId>
5
        <version>6.1.4</version>
6
    </dependency>
7
</dependencies>

查找依赖坐标的途径：Maven 中央仓库 https://mvnrepository.com/

依赖传递#

在 Maven 项目中，如果 A 依赖 B，B 依赖 C，C 依赖 D，那么 A 项目中也会传递引入 C 和 D。

依赖传递

排除依赖#

如果传递下来的某个依赖不需要，可以通过 <exclusions> 排除，被排除的资源无需指定版本。

1
<dependency>
2
    <groupId>org.springframework</groupId>
3
    <artifactId>spring-context</artifactId>
4
    <version>6.1.4</version>
5

6
    <!-- 排除依赖 -->
7
    <exclusions>
8
        <exclusion>
9
            <groupId>io.micrometer</groupId>
10
            <artifactId>micrometer-observation</artifactId>
11
        </exclusion>
12
    </exclusions>
13
</dependency>

排除依赖

注意事项#

引入的依赖如果在本地仓库中不存在，会连接远程仓库/中央仓库下载，首次耗时较长。
依赖坐标信息不确定时，可到 https://mvnrepository.com/ 搜索。
排除依赖只需指定 groupId 和 artifactId，无需 version。

Maven生命周期

Sat, 16 May 2026 00:00:00 GMT

Maven生命周期#

定义#

Maven 的生命周期是对所有项目构建过程的抽象和统一，描述了一次项目构建经历哪些阶段。

Maven 从大量项目和构建工具中总结了一套高度完善的构建生命周期，包含清理、初始化、编译、测试、打包、集成测试、验证、部署和站点生成等几乎所有构建步骤。

三套生命周期#

Maven 将项目构建生命周期划分为三套，相互独立：

生命周期三套

生命周期	作用
clean	清理工作
default	核心工作：编译、测试、打包、安装、部署等
site	生成报告、发布站点等

生命周期阶段详解#

生命周期阶段

常用阶段：

阶段	说明
`clean`	移除上一次构建生成的文件
`compile`	编译项目源代码
`test`	使用单元测试框架运行测试（JUnit）
`package`	将编译后的文件打包（jar、war 等）
`install`	安装项目到本地仓库

执行顺序：同一套生命周期中，阶段是有顺序的，后面的阶段依赖于前面的阶段。执行后面的生命周期时，前面的生命周期都会执行。

跨生命周期：package 和 compile 属于同一套生命周期，执行 package 时 compile 会自动运行；但 clean 与 package 不属于同一套，执行 package 时 clean 不会运行。

插件机制#

Maven 的生命周期是抽象的，生命周期本身不做任何实际工作。实际任务（如源代码编译）都交由插件来完成。

插件执行机制

生命周期顺序：clean → validate → compile → test → package → verify → install → site → deploy

日常开发重点关注：clean → compile → test → package → install

执行方式#

方式一：IDEA 中执行 在 IDEA 右侧 Maven 工具栏中选择对应生命周期，双击执行。

方式二：命令行执行 在 Maven 项目目录下打开命令行，执行：

Terminal window

1
mvn compile    # 编译
2
mvn test       # 测试
3
mvn package    # 打包
4
mvn install    # 安装到本地仓库

注意事项#

同一套生命周期中，执行后面的阶段会自动执行前面所有阶段。
不同套的生命周期互不影响（如 clean 和 default 互不触发）。
生命周期本身是抽象定义，具体工作由插件实现。

单元测试与JUnit

Sat, 16 May 2026 00:00:00 GMT

JUnit单元测试#

测试概述#

测试是一种用来促进鉴定软件正确性、完整性、安全性和质量的过程。

测试阶段划分#

测试阶段划分

阶段	说明	目的	测试人员
单元测试	对软件最小组成单位进行测试	检验基本组成单位的正确性	开发人员
集成测试	将通过测试的单元组合后测试	检查单元之间的协作是否正确	开发人员
系统测试	对集成好的软件系统进行彻底测试	验证正确性、性能是否满足要求	测试人员
验收测试	针对用户需求、业务流程的正式测试	验证是否满足验收标准	客户/需求方

测试方法#

测试方法

方法	说明
白盒测试	清楚软件内部结构和代码逻辑，用于验证代码和逻辑正确性
黑盒测试	不清楚内部结构，用于验证功能、兼容性、验收测试
灰盒测试	结合白盒和黑盒，既关注内部结构又考虑外部表现

灰盒测试

JUnit 单元测试#

JUnit 是最流行的 Java 测试框架之一。相比在 main 方法中测试，JUnit 具有以下优势：

JUnit优势

main 方法测试的问题	JUnit 的优势
测试代码与源代码未分开，难维护	测试代码与源代码分离，便于维护
一个方法测试失败影响后面方法	各测试方法独立运行
无法自动化测试，得不到测试报告	可自动化测试，自动产出测试报告

入门示例#

引入依赖（pom.xml）：

1
<dependency>
2
    <groupId>org.junit.jupiter</groupId>
3
    <artifactId>junit-jupiter</artifactId>
4
    <version>5.9.1</version>
5
    <scope>test</scope>
6
</dependency>

编写测试类（src/test/java 目录下）：

1
@Test
2
public void testGetAge() {
3
    Integer age = new UserService().getAge("110002200505091218");
4
    System.out.println(age);
5
}

测试通过：显示绿色
测试失败：显示红色

命名规范：

测试类命名：XxxTest
测试方法命名：public void xxx() { ... }

断言#

JUnit 提供断言方法，验证被测试方法是否按预期工作。

1
@Test
2
public void testGetAge() {
3
    Integer age = new UserService().getAge("110002200505091218");
4
    Assertions.assertNotEquals(18, age, "两个值相等");
5
}
6

7
@Test
8
public void testGetGender() {
9
    String gender = new UserService().getGender("612429198904201611");
10
    Assertions.assertEquals("男", gender);
11
}

断言测试结果

常见注解#

注解	说明
`@Test`	标记方法为测试方法
`@BeforeEach`	每个测试方法执行前运行
`@AfterEach`	每个测试方法执行后运行
`@BeforeAll`	所有测试方法执行前运行一次（必须 `static`）
`@AfterAll`	所有测试方法执行后运行一次（必须 `static`）
`@DisplayName`	指定测试类或方法的显示名称
`@ParameterizedTest`	标记为参数化测试方法
`@ValueSource`	为参数化测试提供数据源

生命周期注解示例：

1
public class UserServiceTest {
2

3
    @BeforeEach
4
    public void testBefore() {
5
        System.out.println("before...");
6
    }
7

8
    @AfterEach
9
    public void testAfter() {
10
        System.out.println("after...");
11
    }
12

13
    @BeforeAll
14
    public static void testBeforeAll() {
15
        System.out.println("before all ...");
16
    }
17

18
    @AfterAll
19
    public static void testAfterAll() {
20
        System.out.println("after all...");
21
    }
22

23
    @Test
24
    public void testGetAge() {
25
        Integer age = new UserService().getAge("110002200505091218");
26
        System.out.println(age);
27
    }
28
}

显示更多显示更少

注解输出结果

参数化测试示例：

1
@DisplayName("测试-学生业务操作")
2
public class UserServiceTest {
3

4
    @DisplayName("测试-获取年龄")
5
    @Test
6
    public void testGetAge() {
7
        Integer age = new UserService().getAge("110002200505091218");
8
        System.out.println(age);
9
    }
10

11
    @DisplayName("测试-获取性别")
12
    @ParameterizedTest
13
    @ValueSource(strings = {"612429198904201611", "612429198904201631", "612429198904201626"})
14
    public void testGetGender(String idcard) {
15
        String gender = new UserService().getGender(idcard);
16
        System.out.println(gender);
17
    }
18
}

显示更多显示更少

参数化测试输出

依赖范围#

通过 <scope> 标签控制依赖的使用范围：

依赖范围

scope 值	主程序（main）	测试程序（test）	打包（package）
`compile`（默认）	✅	✅	✅
`test`	❌	✅	❌
`provided`	✅	✅	❌
`runtime`	❌	✅	✅

典型用法：JUnit 依赖设置 scope 为 test，表示该依赖仅测试程序可用，主程序中无法使用。

1
<dependency>
2
    <groupId>org.junit.jupiter</groupId>
3
    <artifactId>junit-jupiter</artifactId>
4
    <version>5.9.1</version>
5
    <scope>test</scope>
6
</dependency>

scope配置

注意事项#

单元测试代码应放在 src/test/java 目录下，与源代码分离。
@BeforeAll 和 @AfterAll 方法必须使用 static 修饰。
依赖范围合理设置可避免将测试依赖打入生产包。

JS对象与JSON

Fri, 15 May 2026 00:00:00 GMT

JS对象与JSON#

定义#

JavaScript对象是键值对的集合，用于组织和管理数据。JSON（JavaScript Object Notation）是一种轻量级的数据交换格式，基于JavaScript对象语法但独立于语言，现多用于网络数据传输。

语法/用法#

自定义对象#

1
let user = {
2
    name: "Tom",
3
    age: 10,
4
    gender: "男",
5
    // 方法定义（简化语法）
6
    sing() {
7
        console.log("悠悠的唱着最炫的民族风~");
8
    }
9
}
10

11
// 访问属性
12
console.log(user.name);
13
// 调用方法
14
user.sing();

JSON格式要求#

1
// JSON标准格式：key必须使用双引号
2
{
3
    "key": value,
4
    "key": value,
5
    "key": value
6
}

JS对象与JSON转换#

1
// JS对象
2
let person = {
3
    name: 'itcast',
4
    age: 18,
5
    gender: '男'
6
}
7

8
// JS对象 → JSON字符串
9
JSON.stringify(person);
10

11
// JSON字符串 → JS对象
12
let personJson = '{"name": "heima", "age": 18}';
13
JSON.parse(personJson).name;

常见场景#

自定义对象：封装实体数据，如用户信息、商品信息等
JSON.stringify()：将JS对象转换为JSON字符串，用于发送数据到服务器
JSON.parse()：将JSON字符串转换为JS对象，用于解析服务器返回的数据
前端与后端通信：API调用中JSON是主要的数据传输格式

注意事项#

JSON的key必须使用双引号，单引号或省略引号不符合JSON规范
JSON不支持函数，只能表示数据
对象方法简化语法：sing() { ... } 等同于 sing: function() { ... }
JSON.stringify循环引用问题：如果对象包含循环引用，JSON.stringify()会抛出错误
深度比较：两个内容相同的JS对象不相等，只有引用相同的才相等

JS变量与常量

Fri, 15 May 2026 00:00:00 GMT

JS变量与常量#

定义#

JavaScript中的变量用于存储数据值，可以存放不同类型的值。常量用于存储不可变的值，一旦声明就不能重新赋值。

语法/用法#

变量声明#

1
// 使用let关键字声明变量
2
let a = 20;
3
a = "Hello";  // JavaScript是弱类型语言，变量可以重新赋值为不同类型
4

5
// 早期使用var声明变量（不推荐）
6
var name = "A";
7
name = "B";
8
var name = "C";  // var可以重复声明

常量声明#

1
// 使用const关键字声明常量
2
const PI = 3.14;
3
// PI = 3.15;  // 错误：常量不能被重新赋值

常见场景#

变量使用场景：
- 存储用户输入
- 临时存储计算结果
- 循环计数器
- 动态数据存储
常量使用场景：
- 数学常数（π、e等）
- 配置参数
- 枚举值
- 不会改变的应用设置

注意事项#

变量命名规则：
- 组成字符可以是字母、数字、下划线(_)或美元符号($)
- 数字不能开头
- 严格区分大小写
- 不能使用关键字作为变量名（如let、if、for等）
let vs var：
- let是ES6引入的块级作用域变量声明
- var存在变量提升和重复声明问题，不推荐使用
- let不能重复声明，更安全
const注意事项：
- 常量必须在声明时初始化
- 常量不能被重新赋值
- 对于对象和数组，const保证的是引用不变，但对象属性和数组元素可以修改
作用域差异：
- let和const是块级作用域
- var是函数作用域

JS数据类型

Fri, 15 May 2026 00:00:00 GMT

JS数据类型#

定义#

JavaScript数据类型分为原始数据类型和引用数据类型。原始数据类型包括number、string、boolean、null、undefined等。使用typeof关键字可以返回变量的数据类型。

语法/用法#

基本类型检测#

1
// 原始数据类型
2
typeof 3;           // "number"
3
typeof 3.14;        // "number"
4
typeof "A";         // "string"
5
typeof 'Hello';     // "string"
6
typeof true;        // "boolean"
7
typeof false;       // "boolean"
8
typeof null;        // "object" (注意：这是JavaScript的历史遗留bug)
9
typeof undefined;   // "undefined"

模板字符串#

1
let name = 'Tom';
2
let age = 18;
3

4
// 传统字符串拼接
5
console.log('大家好, 我是新入职的' + name + ', 今年' + age + '岁了');
6

7
// 模板字符串（反引号）
8
console.log(`大家好, 我是新入职的${name}, 今年${age}岁了`);

常见场景#

number：数值计算、计数器、数组索引
string：文本处理、用户输入、HTML内容
boolean：条件判断、状态切换、开关控制
null：明确表示空值
undefined：变量已声明但未赋值
模板字符串：拼接字符串和变量时使用，比传统拼接更简洁

注意事项#

弱类型特性：JavaScript是弱类型语言，变量可以存放不同类型的值
typeof null：返回”object”是JavaScript的历史遗留bug，null实际是一个特殊的基本类型值
模板字符串：
- 必须使用反引号(`)
- 变量使用${}语法引用
- 支持换行和多行字符串
字符串表示：可以使用双引号(”)、单引号(‘)或反引号(`)
数值范围：JavaScript的number类型是双精度64位浮点数，整数范围在-(2^53-1)到2^53-1之间

JS函数

Fri, 15 May 2026 00:00:00 GMT

JS函数#

定义#

函数是被设计用来执行特定任务的代码块，方便程序的封装复用。JavaScript中的函数可以通过命名函数、函数表达式和箭头函数三种方式定义。

语法/用法#

方式一：命名函数#

1
function add(a, b) {
2
    return a + b;
3
}
4

5
let result = add(10, 20);

方式二：匿名函数#

1
// 函数表达式
2
var add = function (a, b) {
3
    return a + b;
4
}
5

6
// 箭头函数（推荐）
7
var add = (a, b) => {
8
    return a + b;
9
}

匿名函数的调用方式#

1
// 通过变量调用
2
let result = add(10, 20);
3

4
// 直接作为回调函数
5
document.querySelector('#btn').addEventListener('click', () => {
6
    alert("按钮被点击了");
7
});

常见场景#

命名函数：工具函数、公共方法、需要复用的代码块
函数表达式：需要将函数作为变量传递的场景
箭头函数：回调函数、简短的函数定义、需要保留外部this的场景
直接匿名调用：事件处理、数组方法（map、filter、forEach等）

注意事项#

参数灵活性：由于JavaScript是弱类型语言，形参不需要声明类型，返回值也不需要声明类型
参数个数：实参个数与形参个数可以不一致，但建议保持一致
箭头函数特性：
- 更简洁的语法
- 不绑定自己的this
- 不能用作构造函数
- 在现代前端开发中使用频率更高
函数提升：命名函数会被提升到作用域顶部，可以在声明前调用；函数表达式和箭头函数则不会

JS事件监听

Fri, 15 May 2026 00:00:00 GMT

JS事件监听#

定义#

事件监听是将函数绑定到HTML元素上的特定事件，当事件触发时自动执行对应的函数。事件是发生在HTML元素上的”事情”，如按钮点击、鼠标移动、键盘按下等。

语法/用法#

addEventListener（推荐）#

1
// 语法：事件源.addEventListener('事件类型', 要执行的函数)
2
document.querySelector("#btn1").addEventListener('click', () => {
3
    alert("按钮被点击了...");
4
});

DOM元素事件属性（早期方式）#

1
document.querySelector('#btn1').onclick = function() {
2
    alert("按钮被点击了...");
3
};

HTML标签事件属性#

1
<input type="button" onclick="on()">

常见场景#

click：按钮点击、链接点击
mouseenter / mouseleave：鼠标悬停效果，如隔行变色
keydown / keyup：键盘快捷键、输入验证
blur / focus：表单输入验证
input：实时搜索、字符计数
submit：表单提交前的数据验证

注意事项#

addEventListener vs on事件：
- on方式会被覆盖（重复绑定只保留最后一个）
- addEventListener可以绑定多次，拥有更多特性
- 推荐使用addEventListener
常见错误：
- 获取DOM元素时在元素渲染之前执行（应将脚本放在body底部或使用DOMContentLoaded）
- 事件类型名称大小写敏感（如”click”不能写成”Click”）
事件冒泡：默认事件会冒泡到父元素，可以通过event.stopPropagation()阻止
事件委托：通过父元素监听子元素事件，提高性能

Vue框架概述

Fri, 15 May 2026 00:00:00 GMT

Vue框架概述#

定义#

Vue是一款用于构建用户界面的渐进式JavaScript框架。它基于数据渲染出用户看到的界面，简化了DOM操作，提高了开发效率。

语法/用法#

Vue应用创建#

1
<div id="app">
2
    {{message}}
3
</div>
4

5
<script type="module">
6
    import { createApp } from 'https://unpkg.com/vue@3/dist/vue.esm-browser.js'
7
    createApp({
8
        data() {
9
            return {
10
                message: 'Hello Vue'
11
            }
12
        }
13
    }).mount('#app')
14
</script>

数据驱动视图#

1
// Vue实例中的数据
2
data() {
3
    return {
4
        message: 'Hello Vue'
5
    }
6
}
7

8
// 模板中的插值表达式
9
{{message}}

常见场景#

构建用户界面：基于数据渲染出用户看到的界面
局部模块改造：使用Vue改造现有项目的部分功能
工程化开发：基于Vue核心包和插件进行整站开发
数据绑定：实现数据与视图的自动同步更新

注意事项#

渐进式框架：
- 不需要一次性学习所有特性
- 可以逐步引入Vue的功能
- 从简单到复杂逐步使用
Vue应用结构：
- 必须通过createApp()创建Vue应用实例
- 数据必须定义在data()方法中
- 必须通过mount()方法挂载到DOM元素
插值表达式限制：
- 只能写在Vue控制的区域内（如#app内部）
- 只能使用Vue中定义的数据
- 不能使用JavaScript语句
开发模式：
- 局部模块改造：基于Vue核心包完成项目局部模块改造
- 工程化开发：基于Vue核心包、插件进行整站开发

Vue指令-v-for

Fri, 15 May 2026 00:00:00 GMT

Vue指令-v-for#

定义#

v-for指令用于列表渲染，遍历容器的元素或对象的属性。它可以根据数据源动态生成多个相同的HTML元素。

语法/用法#

基本语法#

1
<tr v-for="(item, index) in items" :key="item.id">
2
    {{item.name}}
3
</tr>

简化语法（省略index）#

1
<tr v-for="item in items" :key="item.id">
2
    {{item.name}}
3
</tr>

遍历对象属性#

1
<li v-for="(value, key) in object">
2
    {{key}}: {{value}}
3
</li>

常见场景#

列表渲染：员工列表、商品列表、消息列表等
表格数据展示：动态生成表格行
导航菜单：根据权限动态生成菜单项
下拉选项：动态生成select的option选项
组件列表：渲染多个相同结构的组件

注意事项#

key的重要性：
- 必须为每个遍历项添加唯一的key属性
- 推荐使用数据的唯一标识（如id）
- 不推荐使用index作为key（会变化，不对应）
- key帮助Vue正确排序复用，提升渲染性能
数据源要求：
- 遍历的数组必须在data()中定义
- 数据变化时视图会自动更新
作用域：
- 在v-for内部可以访问父作用域的属性
- 每个遍历项都有自己的作用域
性能优化：
- 避免在v-for内部使用复杂计算
- 大数据量时考虑虚拟滚动
- 使用v-if和v-for时，v-if的优先级更高

Vue指令-v-bind

Fri, 15 May 2026 00:00:00 GMT

Vue指令-v-bind#

定义#

v-bind指令用于动态绑定HTML标签的属性值，如href、src、style、class等。它可以将Vue实例中的数据绑定到HTML元素的属性上。

语法/用法#

完整语法#

1
<img v-bind:src="item.image" width="30px">

简化语法（推荐）#

1
<img :src="item.image" width="30px">

绑定class和style#

1
<!-- 绑定class -->
2
<div :class="{ active: isActive, 'text-danger': hasError }"></div>
3

4
<!-- 绑定style -->
5
<div :style="{ color: activeColor, fontSize: fontSize + 'px' }"></div>

绑定多个属性#

1
<a :href="url" :title="title" :target="target">链接</a>

常见场景#

动态图片路径：根据数据动态显示图片
动态链接：根据条件生成不同的URL
样式绑定：根据状态动态改变元素样式
类名绑定：根据条件添加或移除CSS类
表单属性：动态设置input的disabled、checked等属性

注意事项#

数据源要求：
- v-bind绑定的数据必须在data()中定义
- 或基于data()中定义的数据计算而来
简写形式：
- :属性名="属性值"是v-bind:属性名="属性值"的简写
- 推荐使用简写形式，代码更简洁
class和style绑定：
- 可以绑定对象、数组或字符串
- 对象语法：键为类名，值为布尔值
- 数组语法：包含多个类名字符串
属性值类型：
- 可以是字符串、数字、布尔值、对象或数组
- Vue会自动进行类型转换
性能考虑：
- 避免在绑定的表达式中进行复杂计算
- 复杂计算建议使用计算属性

Vue指令-v-if与v-show

Fri, 15 May 2026 00:00:00 GMT

Vue指令-v-if与v-show#

定义#

v-if和v-show都是用于控制元素显示与隐藏的指令，但实现机制不同。v-if通过条件判断创建或移除元素节点，v-show通过CSS的display属性控制显示隐藏。

语法/用法#

v-if指令#

1
<!-- 基本用法 -->
2
<span v-if="isVisible">显示内容</span>
3

4
<!-- v-else-if链式调用 -->
5
<span v-if="emp.job === '1'">班主任</span>
6
<span v-else-if="emp.job === '2'">讲师</span>
7
<span v-else-if="emp.job === '3'">学工主管</span>
8
<span v-else-if="emp.job === '4'">教研主管</span>
9
<span v-else-if="emp.job === '5'">咨询师</span>
10
<span v-else>其他</span>
11

12
<!-- v-else -->
13
<div v-if="isAdmin">管理员面板</div>
14
<div v-else>普通用户面板</div>

v-show指令#

1
<!-- 基本用法 -->
2
<span v-show="isVisible">显示内容</span>
3

4
<!-- 多个条件 -->
5
<span v-show="emp.job === '1'">班主任</span>
6
<span v-show="emp.job === '2'">讲师</span>
7
<span v-show="emp.job === '3'">学工主管</span>
8
<span v-show="emp.job === '4'">教研主管</span>
9
<span v-show="emp.job === '5'">咨询师</span>

常见场景#

v-if适用场景：
- 条件不经常变化
- 初始渲染条件为false时不需要渲染
- 需要配合v-else或v-else-if使用
- 性能要求不高，但需要完全销毁/重建元素
v-show适用场景：
- 条件频繁切换
- 初始渲染成本较高
- 只需要简单的显示/隐藏切换
- 需要保持元素状态（如表单输入）

注意事项#

实现机制差异：
- v-if：条件为false时，元素从DOM中移除
- v-show：条件为false时，元素通过display: none隐藏
性能考虑：
- v-if有更高的切换开销（创建/销毁）
- v-show有更高的初始渲染开销（总是渲染）
- 频繁切换用v-show，运行时条件很少改变用v-if
v-else规则：
- v-else必须紧跟在v-if或v-else-if之后
- v-else-if必须出现在v-if之后
- 可以有多个v-else-if
与v-for一起使用：
- 不推荐在同一元素上同时使用v-if和v-for
- 需要时，v-if的优先级更高

Vue指令-v-model

Fri, 15 May 2026 00:00:00 GMT

Vue指令-v-model#

定义#

v-model指令用于在表单元素上实现双向数据绑定。它可以方便地获取或设置表单项数据，实现Vue数据与表单输入之间的自动同步。

语法/用法#

基本用法#

1
<!-- 文本输入框 -->
2
<input type="text" v-model="username">
3

4
<!-- 下拉选择框 -->
5
<select v-model="selected">
6
    <option value="A">选项A</option>
7
    <option value="B">选项B</option>
8
</select>
9

10
<!-- 多选框 -->
11
<input type="checkbox" v-model="checked">
12

13
<!-- 单选框 -->
14
<input type="radio" v-model="picked" value="a">

表单数据绑定#

1
<form class="search-form">
2
    <input type="text" v-model="searchEmp.name" placeholder="姓名" />
3
    <select v-model="searchEmp.gender">
4
        <option value="">性别</option>
5
        <option value="1">男</option>
6
        <option value="2">女</option>
7
    </select>
8
</form>

常见场景#

表单输入：文本输入、密码输入、文本域
选择控件：下拉选择、单选框、多选框
搜索功能：搜索框与搜索条件的双向绑定
数据收集：用户注册、信息填写等表单场景
实时过滤：输入框内容实时过滤列表数据

注意事项#

数据源要求：
- v-model绑定的变量必须在data()中定义
- 变量可以是基本类型或对象属性
双向绑定原理：
- Vue数据变化 → 视图更新
- 视图输入变化 → Vue数据更新
- 本质是v-bind和v-on的语法糖
修饰符：
- .lazy：在change事件后同步数据
- .number：将输入转为数字类型
- .trim：自动过滤首尾空白字符
自定义组件：
- 在自定义组件上使用v-model需要特殊处理
- 需要组件内部实现modelValue和update:modelValue
与原生表单区别：
- 不需要手动获取表单值
- 数据变化自动同步到视图
- 支持多种表单元素类型

Vue指令-v-on

Fri, 15 May 2026 00:00:00 GMT

Vue指令-v-on#

定义#

v-on指令用于为HTML标签绑定事件，实现用户与页面的交互功能。它可以监听DOM事件，并在事件触发时执行Vue实例中定义的方法。

语法/用法#

完整语法#

1
<input type="button" value="点我" v-on:click="handle">

简化语法（推荐）#

1
<input type="button" value="点我" @click="handle">

方法定义#

1
createApp({
2
    data() {
3
        return {
4
            searchEmp: {
5
                name: '',
6
                gender: '',
7
                job: ''
8
            }
9
        }
10
    },
11
    methods: {
12
        search() {
13
            console.log(this.searchEmp)
14
        },
15
        clear() {
16
            this.searchEmp = {
17
                name: '',
18
                gender: '',
19
                job: ''
20
            }
21
        }
22
    }
23
}).mount('#container')

显示更多显示更少

常见场景#

点击事件：按钮点击、提交操作
表单处理：表单提交、输入验证
元素交互：鼠标悬停、移出效果
键盘事件：快捷键、输入监听
数据操作：增删改查功能触发

注意事项#

事件处理方法：
- 必须在Vue实例的methods中定义
- 方法名使用驼峰命名（camelCase）
- 方法中通过this访问Vue实例数据
this指向：
- methods函数中的this指向Vue实例
- 可以通过this获取到data()中定义的数据
事件修饰符：
- .prevent：阻止默认行为
- .stop：阻止事件冒泡
- .once：事件只触发一次
与原生JS事件区别：
- 不需要手动获取DOM元素
- 方法直接绑定，更简洁
- 数据更新自动反映到视图
常见事件类型：
- click：鼠标点击
- submit：表单提交
- keyup/keydown：键盘事件
- input：输入变化

Axios库使用

Fri, 15 May 2026 00:00:00 GMT

Axios库使用#

定义#

Axios是一个基于Promise的HTTP客户端，用于浏览器和Node.js环境。它对原生的Ajax进行了封装，简化了HTTP请求的编写和响应处理。

语法/用法#

官方文档#

Axios官网：https://www.axios-http.cn

引入Axios#

1
<script src="https://unpkg.com/axios/dist/axios.min.js"></script>

通用方式发送请求#

1
// GET请求
2
axios({
3
    url: 'https://api.example.com/data',
4
    method: 'get'
5
}).then(function(res) {
6
    console.log(res.data);
7
}).catch(function(err) {
8
    console.log(err);
9
})
10

11
// POST请求
12
axios({
13
    url: 'https://api.example.com/update',
14
    method: 'post'
15
}).then(function(res) {
16
    console.log(res.data);
17
}).catch(function(err) {
18
    console.log(err);
19
})

显示更多显示更少

请求方法别名#

1
// GET请求
2
axios.get("https://api.example.com/data")
3
    .then(result => {
4
        console.log(result.data);
5
    })
6

7
// POST请求
8
axios.post("https://api.example.com/update", "id=1")
9
    .then(result => {
10
        console.log(result.data);
11
    })
12

13
// 带参数GET请求
14
axios.get(`https://api.example.com/list?name=${name}&gender=${gender}&job=${job}`)
15
    .then(res => {
16
        this.empList = res.data.data;
17
    })

显示更多显示更少

与async/await结合使用#

1
async search() {
2
    const result = await axios.get(
3
        `https://api.example.com/list?name=${this.searchForm.name}`
4
    );
5
    this.empList = result.data.data;
6
}

常见场景#

GET请求：获取数据、查询操作
POST请求：提交表单、创建数据
PUT请求：更新数据
DELETE请求：删除数据
并发请求：同时发送多个请求并处理

注意事项#

引入方式：
- 可以通过CDN引入（在线）
- 可以通过npm安装（本地）
- 建议使用离线版本以提高稳定性
响应处理：
- 响应数据在res.data中
- 使用.then()处理成功响应
- 使用.catch()处理错误响应
请求方法区别：
- GET请求参数在URL中
- POST请求参数在请求体中
async/await优化：
- 使用async/await可以让异步代码像同步代码一样编写
- 提高代码可读性和可维护性
- 建议在前端项目中优先使用此方式
常见错误处理：
- 网络错误
- 服务器返回错误状态码
- 超时问题
- 跨域问题

Ajax与异步编程

Fri, 15 May 2026 00:00:00 GMT

Ajax与异步编程#

定义#

Ajax（Asynchronous JavaScript And XML）是一种在不重新加载整个页面的情况下，与服务器交换数据并更新部分网页的技术。它实现了前端与服务器的异步数据交互。

语法/用法#

同步vs异步对比#

1
同步请求流程：
2
浏览器 → 发送请求 → [等待服务器处理] → 接收响应 → 继续操作
3
        (期间页面被阻塞，无法操作)
4

5
异步请求流程：
6
浏览器 → 发送请求 → 继续其他操作
7
        (请求在后台处理)
8
服务器 → 处理完成 → 返回数据 → 更新页面局部内容
9
        (页面不刷新，用户体验好)

async/await语法#

1
// 用async声明异步方法
2
async search() {
3
    const result = await axios.get(
4
        `https://api.example.com/emps/list?name=${this.searchForm.name}`
5
    );
6
    this.empList = result.data.data;
7
}

Promise方式#

1
axios.get(url)
2
    .then(res => {
3
        console.log(res.data);
4
    })
5
    .catch(err => {
6
        console.log(err);
7
    });

常见场景#

数据获取：从服务器加载数据并动态展示
表单提交：异步提交表单数据，避免页面刷新
搜索联想：用户输入时实时获取联想建议
数据验证：用户名可用性检查、邮箱验证等
局部刷新：只更新页面中变化的部分

注意事项#

同步vs异步：
- 同步请求会阻塞页面，等待服务器响应期间无法操作
- 异步请求不阻塞页面，用户体验更好
async/await：
- async用于声明异步方法
- await用于等待异步任务执行
- 配合使用可以让异步代码看起来像同步代码
- 提高代码可读性和可维护性
错误处理：
- 使用try-catch包裹await调用
- Promise方式使用.catch处理错误
跨域问题：
- Ajax请求受同源策略限制
- 需要服务器配置CORS或使用代理
异步不是多线程：
- JavaScript是单线程语言
- 异步通过事件循环机制实现
- 不阻塞主线程但也不能利用多核并行计算

Vue生命周期

Fri, 15 May 2026 00:00:00 GMT

Vue生命周期#

定义#

Vue生命周期是指Vue实例从创建到销毁的完整过程。它包含8个阶段，每个阶段会自动执行对应的生命周期方法（也称为钩子函数）。其中mounted是最常用的钩子函数。

语法/用法#

生命周期钩子使用#

1
createApp({
2
    data() {
3
        return {
4
            empList: []
5
        }
6
    },
7
    methods: {
8
        async search() {
9
            const result = await axios.get('https://api.example.com/emps/list');
10
            this.empList = result.data.data;
11
        }
12
    },
13
    // 生命周期钩子：挂载完成
14
    mounted() {
15
        // 页面初始化自动加载数据
16
        this.search();
17
    }
18
}).mount('#container')

显示更多显示更少

常见场景#

mounted（挂载完成）：
- 页面初始化时自动请求后台数据
- 初始化第三方插件
- 获取DOM元素
- 设置定时器
created（创建完成）：
- 初始化数据
- 非DOM相关操作
beforeUnmount（卸载前）：
- 清理定时器
- 移除事件监听
- 取消未完成的请求

注意事项#

mounted是重点：
- Vue初始化成功，HTML页面渲染成功
- 用于页面初始化时自动发送Ajax请求
- 此时可以访问DOM元素
生命周期顺序：
- beforeCreate → created → beforeMount → mounted
- beforeUpdate → updated
- beforeUnmount → unmounted
钩子函数特性：
- 自动执行，不需要手动调用
- 在Vue实例选项对象中定义
- 每个实例都会经历完整的生命周期
数据可用性：
- created中可以访问data和methods
- mounted中可以访问DOM
- beforeCreate中无法访问data
避免内存泄漏：
- 在beforeUnmount中清理定时器
- 取消事件监听
- 清理全局引用

Web标准与浏览器内核

Thu, 14 May 2026 00:00:00 GMT

定义#

Web标准 是由 W3C（World Wide Web Consortium，万维网联盟）制定的一系列网页技术规范，确保不同浏览器对同一段前端代码的解析结果一致。其核心由三部分组成：

HTML（HyperText Markup Language）：负责网页的结构（页面元素与内容）
CSS（Cascading Style Sheet）：负责网页的表现（外观、位置、样式）
JavaScript：负责网页的行为（交互效果）

浏览器内核 是浏览器中负责解析和渲染前端代码的组件。不同浏览器的内核不同，对同一段代码的解析效果也存在差异——这正是 Web 标准存在的意义。

常见浏览器内核#

浏览器	内核
Chrome	Blink（早期为 WebKit）
Firefox	Gecko
Safari	WebKit
IE	Trident

常见场景#

判断某个 CSS 属性是否需要添加浏览器私有前缀
理解为何同一页面在不同浏览器中显示效果不一致
前端性能优化时考虑不同内核的渲染差异

注意事项#

HTML 标签是预定义好的，不可自定义（如不存在 <h7>）
HTML 语法相对松散，但编写时建议保持严谨

HTML基础

Thu, 14 May 2026 00:00:00 GMT

HTML基础结构#

定义#

HTML（HyperText Markup Language，超文本标记语言）是一种标记语言，由预定义的标签构成，浏览器负责解析这些标签并将其渲染为用户可见的网页。

超文本：超越普通文本的限制，可定义图片、音频、视频等内容
标记语言：由 <标签名> 构成，标签为浏览器预定义

基础文档骨架#

1
<!DOCTYPE html>
2
<html lang="en">
3
<head>
4
    <meta charset="UTF-8">
5
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
    <title>页面标题</title>
7
</head>
8
<body>
9
    <!-- 页面主体内容 -->
10
</body>
11
</html>

骨架结构说明#

标签	作用
`<!DOCTYPE html>`	声明文档类型为 HTML5
`<html>`	根标签，包裹整个页面
`<head>`	存放给浏览器看的信息（CSS 样式、网页标题、meta 元数据等）
`<body>`	存放给用户看的信息（文字、图片、视频、音频、表格等）
`<title>`	定义浏览器标签页标题
`<meta charset="UTF-8">`	声明字符编码

标签语法规则#

HTML 标签通常成对出现：<tagname>内容</tagname>
自闭合标签（空元素）：<img>、<br>、<input> 等
标签可以嵌套，但必须正确闭合
属性写在开始标签内：<tagname attr="value">

浏览器渲染#

浏览器从上往下逐行解析 HTML，将代码转换为可视化的网页内容。<head> 中的内容不直接显示，<body> 中的内容呈现在浏览器内容区域。

注意事项#

标签名不区分大小写，但建议统一使用小写
属性值可用单引号或双引号，推荐双引号
HTML 语法较松散，但编写时建议保持规范严谨

文件路径表示#

定义#

在 HTML 中引入图片、视频、音频、CSS 等外部资源时，需要指定文件的路径。路径分为 绝对路径 和 相对路径 两类。

语法/用法#

绝对路径#

绝对磁盘路径：从盘符开始指定完整的文件位置。

1
<img src="C:\Users\Administrator\Desktop\HTML\img\logo.png">

绝对网络路径：指向互联网上的资源 URL。

1
<img src="https://i2.sinaimg.cn/dy/deco/2012/0613/yocc20120613img01/news_logo.png">

相对路径#

以当前 HTML 文件所在目录为基准进行定位。

符号	含义	示例
`./` 或省略	当前目录	`src="img/photo.jpg"` 等价于 `src="./img/photo.jpg"`
`../`	上一级目录	`src="../images/logo.png"`

常见场景#

<img> 标签的 src 属性引用本地图片
<link> 标签引入外部 CSS 文件
<video> 标签的 src 属性引用本地视频
<a> 标签的 href 指定跳转链接

注意事项#

相对路径在项目迁移或部署到服务器后通常仍能正常工作，而绝对磁盘路径会失效
开发中优先使用相对路径，引用外部 CDN 资源时使用绝对网络路径
./ 可以省略不写，../ 不可省略

标题标签#

定义#

HTML 提供六级标题标签 <h1> 到 <h6>，用于定义文档的层级标题结构。<h1> 级别最高、字体最大，<h6> 级别最低、字体最小。

语法/用法#

1
<h1>一级标题</h1>
2
<h2>二级标题</h2>
3
<h3>三级标题</h3>
4
<h4>四级标题</h4>
5
<h5>五级标题</h5>
6
<h6>六级标题</h6>

常见场景#

页面主标题用 <h1>（一个页面通常只有一个 <h1>）
章节标题按层级递进使用 <h2>、<h3>
结合 id 属性用于锚点导航：<h1 id="title">标题</h1>

注意事项#

标题标签仅此六级，不存在 <h7>，HTML 标签不可自定义
标题标签自带加粗效果和上下外边距
SEO 场景中 <h1> 权重最高，应合理使用层级结构
不可为了字号大小而跳级使用（如直接从 <h1> 跳到 <h4>）

段落与文本标签#

定义#

HTML 提供多种标签用于组织文本内容，包括段落、换行、强调等。

语法/用法#

段落标签 `<p>`#

1
<p>这是一个段落，浏览器会自动在段落前后添加外边距。</p>

换行标签 `<br>`#

1
第一行<br>
2
第二行

强调标签#

标签	说明	示例
`<strong>`	加粗强调，语义重要	`<strong>重要内容</strong>`
`<em>`	斜体强调，语义强调	`<em>强调内容</em>`
`<span>`	行内容器，无语义	`<span class="highlight">高亮</span>`

文本格式化#

1
<p>这是一段包含 <strong>加粗</strong> 和 <em>斜体</em> 的文本。</p>
2
<p>换行<br>在这里</p>

常见场景#

新闻正文、文章内容使用 <p> 分段
地址、诗歌等需要强制换行处使用 <br>
关键词、重要信息用 <strong> 或 <em> 强调
需要单独样式控制的文本片段用 <span> 包裹

注意事项#

<p> 标签自带上下外边距，可通过 CSS 调整
<br> 是自闭合标签，无结束标签
<strong> 与 <b> 视觉效果相同，但语义不同（<strong> 表示重要性，<b> 仅视觉加粗）
<em> 与 <i> 同理，<em> 有强调语义，<i> 仅视觉斜体

字符实体#

定义#

HTML 中的字符实体（Character Entities）用于在页面中显示特殊字符，如空格、尖括号、引号等。浏览器无法直接识别代码中的这些字符，需通过实体表示。

语法/用法#

字符实体以 & 开头，以 ; 结尾。

常用字符实体#

字符	实体名称	实体编号	说明
`<`	`<`	`<`	小于号
`>`	`>`	`>`	大于号
`&`	`&`	`&`	和号
`"`	`"`	`"`	双引号
`'`	`'`	`'`	单引号
	` `	` `	不换行空格

示例#

1
<p>HTML 标签示例：&lt;p&gt; 这是一个段落 &lt;/p&gt;</p>
2
<p>版权所有 &copy; 2024 公司名称</p>
3
<p>价格：$100 &amp; 运费：$20</p>

常见场景#

在页面中显示 HTML 代码片段
需要保留多个连续空格（普通空格会被浏览器合并为一个）
显示版权、商标等特殊符号
避免与 HTML 标签冲突的字符

注意事项#

实体名称（如 <）比实体编号（如 <）更易读，推荐使用
不换行空格   常用于固定间距，但不应滥用（应使用 CSS 控制间距）
现代浏览器对字符编码支持良好，但使用实体可确保兼容性

HTML媒体标签

Thu, 14 May 2026 00:00:00 GMT

超链接标签#

定义#

<a> 标签用于创建超链接，用户点击后可跳转到指定 URL。它是 Web 导航的核心元素。

语法/用法#

1
<a href="https://news.cctv.com/" target="_blank">央视网</a>

属性#

属性	说明	取值
`href`	指定跳转的目标 URL	绝对路径或相对路径
`target`	指定在何处打开链接	`_self`（默认，当前页面打开）、`_blank`（新空白页面打开）

去除默认下划线#

超链接默认带有下划线，可通过 CSS 去除：

1
a {
2
    text-decoration: none;
3
}

常见场景#

页面导航菜单
外部链接跳转
页面内锚点跳转：<a href="#section-id">跳转到某节</a>
下载链接：<a href="file.pdf" download>下载文件</a>

注意事项#

href 为必填属性，不填则链接不可点击（仅作锚点占位）
target="_blank" 存在安全风险（新页面可通过 window.opener 操作原页面），建议搭配 rel="noopener noreferrer"
相对路径与绝对路径的选择参考文件路径表示

图片标签#

定义#

<img> 标签用于在 HTML 页面中嵌入图片。它是一个自闭合标签（空元素），通过 src 属性指定图片源。

语法/用法#

1
<img src="img/1.png" alt="图片描述" width="100%">

属性#

属性	说明	取值
`src`	图片源路径（必填）	相对路径或绝对路径
`alt`	替代文本，图片无法加载时显示	描述图片内容的字符串
`width`	图片宽度	像素值（如 `200`）或百分比（如 `100%`）
`height`	图片高度	像素值或百分比
`title`	鼠标悬停提示文本	字符串

常见场景#

新闻配图、产品展示图
图标、Logo 展示
轮播图、相册
响应式图片：结合 CSS max-width: 100% 防止图片溢出容器

注意事项#

alt 属性对 SEO 和可访问性至关重要，应准确描述图片内容
仅设置 width 或 height 之一，浏览器会自动按比例缩放另一维度
大图片应进行压缩优化，避免影响页面加载速度

视频标签#

定义#

<video> 标签用于在 HTML 页面中嵌入视频内容，支持播放本地或网络视频文件。

语法/用法#

1
<video src="video/news.mp4" controls width="80%"></video>

属性#

属性	说明	取值
`src`	视频源路径	相对路径或绝对路径
`controls`	显示播放控件（播放/暂停、音量、进度条等）	布尔值，存在即生效
`width`	视频宽度	像素值或百分比
`height`	视频高度	像素值或百分比
`autoplay`	页面加载后自动播放	布尔值
`loop`	循环播放	布尔值
`muted`	静音播放	布尔值
`poster`	视频封面图路径	图片路径

常见场景#

新闻视频、产品演示视频
背景视频、宣传片嵌入
在线课程视频播放
响应式视频：结合 CSS 实现自适应

注意事项#

浏览器对视频格式支持不同（MP4、WebM、Ogg），可提供多个源文件：

1
<video controls>
2
  <source src="video.mp4" type="video/mp4">
3
  <source src="video.webm" type="video/webm">
4
  您的浏览器不支持 video 标签
5
</video>

autoplay 可能被浏览器阻止，需配合 muted 使用
移动端浏览器对自动播放有更严格的限制

HTML表格与表单

Thu, 14 May 2026 00:00:00 GMT

表格标签#

定义#

HTML 表格用于展示行列结构化的数据，由 <table>、<tr>、<th>、<td> 等标签构成。

语法/用法#

基础表格结构#

1
<table>
2
  <thead>
3
    <tr>
4
      <th>姓名</th>
5
      <th>性别</th>
6
      <th>职位</th>
7
    </tr>
8
  </thead>
9
  <tbody>
10
    <tr>
11
      <td>令狐冲</td>
12
      <td>男</td>
13
      <td>讲师</td>
14
    </tr>
15
    <tr>
16
      <td>任盈盈</td>
17
      <td>女</td>
18
      <td>学工主管</td>
19
    </tr>
20
  </tbody>
21
</table>

显示更多显示更少

标签说明#

标签	说明	属性
`<table>`	表格容器	`border`、`width`、`cellspacing`、`cellpadding`
`<thead>`	表头区域（语义化）	-
`<tbody>`	表体区域（语义化）	-
`<tr>`	表格行	-
`<th>`	表头单元格	`colspan`（跨列）、`rowspan`（跨行）
`<td>`	数据单元格	`colspan`、`rowspan`

跨行跨列#

1
<td colspan="2">跨两列</td>
2
<td rowspan="3">跨三行</td>

常见场景#

数据报表、统计表格
产品规格对比表
课程表、日程表
后台管理系统中的数据列表

注意事项#

现代开发中表格的样式（边框、间距、颜色）应通过 CSS 控制，而非 HTML 属性
使用 <thead>、<tbody> 等语义化标签提升可访问性
避免使用表格进行页面布局（应使用 CSS Flex/Grid）
复杂表格可结合 colspan、rowspan 实现单元格合并

表单标签#

定义#

表单（Form）是网页中负责数据采集的核心组件，用户通过表单项录入数据后提交到服务端。表单数据一般会被服务端接收后存储到数据库中。

语法/用法#

表单容器 `<form>`#

1
<form action="/save" method="post">
2
    <!-- 表单项 -->
3
</form>

form 属性#

属性	说明	取值
`action`	数据提交的目标 URL	URL 路径，不指定则提交到当前页面
`method`	数据提交方式	`GET`（默认）或 `POST`

GET vs POST#

对比维度	GET	POST
数据位置	拼接在 URL 后面（`?key=value`）	放在请求体中
数据大小	URL 长度有限制	无大小限制
安全性	数据暴露在地址栏	相对安全
适用场景	搜索查询、筛选	登录、注册、数据提交

表单项标签#

`<input>` — 核心表单项#

通过 type 属性控制输入形式：

type 值	说明	示例
`text`	文本输入框	`<input type="text" name="name">`
`password`	密码输入框	`<input type="password" name="pwd">`
`radio`	单选按钮	`<input type="radio" name="gender" value="1">`
`checkbox`	复选框	`<input type="checkbox" name="hobby" value="java">`
`file`	文件上传	`<input type="file" name="image">`
`date`	日期选择	`<input type="date" name="birthday">`
`time`	时间选择	`<input type="time" name="time">`
`datetime-local`	日期时间选择	`<input type="datetime-local" name="dt">`
`hidden`	隐藏域（不可见但会提交）	`<input type="hidden" name="id" value="1">`
`submit`	提交按钮	`<input type="submit" value="提交">`
`reset`	重置按钮	`<input type="reset" value="重置">`
`button`	普通按钮	`<input type="button" value="按钮">`

`<select>` — 下拉列表#

1
<select name="degree">
2
    <option value="">请选择</option>
3
    <option value="1">大专</option>
4
    <option value="2">本科</option>
5
</select>

`<textarea>` — 文本域#

1
<textarea name="description" cols="30" rows="10"></textarea>

常见场景#

用户注册、登录表单
信息搜索与筛选
管理系统数据录入
个人信息编辑

注意事项#

表单项必须指定 name 属性，否则提交时不会采集该字段的数据
同一组 radio 的 name 必须相同以实现互斥

<label> 包裹 <input> 可实现点击标签文字聚焦控件：

1
<label><input type="checkbox" name="hobby" value="game"> 游戏</label>

value 属性决定了表单项提交到服务端的实际值

CSS布局

Thu, 14 May 2026 00:00:00 GMT

CSS盒模型#

定义#

页面中所有元素都可以看作一个盒子，由盒子将元素包含在矩形区域内。CSS 盒模型是页面布局的基石，包含四个部分：

内容区域（content）：实际内容（文字、图片）所在区域
内边距区域（padding）：内容与边框之间的空白
边框区域（border）：围绕内边距的边框线
外边距区域（margin）：盒子与其他元素之间的空白

语法/用法#

1
div {
2
    width: 200px;              /* 宽度 */
3
    height: 200px;             /* 高度 */
4
    box-sizing: border-box;    /* 宽高包含 border+padding */
5
    background-color: aquamarine;
6

7
    padding: 20px;             /* 内边距（四边统一） */
8
    border: 10px solid red;    /* 边框：粗细 线型 颜色 */
9
    margin: 30px;              /* 外边距（四边统一） */
10
}

padding / margin 简写规则#

写法	含义
`padding: 20px;`	上、右、下、左均为 20px
`padding: 20px 10px;`	上下 20px，左右 10px
`padding: 10px 20px 30px 40px;`	上 10px，右 20px，下 30px，左 40px（顺时针）

box-sizing#

值	说明
`content-box`（默认）	`width/height` 仅指 content 区域，不包含 padding 和 border
`border-box`	`width/height` 包含 content + padding + border，更直观，推荐使用

盒子大小计算#

盒子实际占据的空间 = content + padding + border + margin（margin 不计入盒子自身大小，但影响周围元素的位置）

常见场景#

版心居中：margin: 0 auto;
卡片布局：border + padding + background-color
元素间距控制：margin 设置同级元素间距，padding 设置内容与边界的间距
通过浏览器开发者工具可视化调试盒模型

注意事项#

相邻块级元素的上下 margin 会发生折叠（取较大值而非相加）
推荐全局使用 box-sizing: border-box;，避免宽高计算混乱
border 的三个参数顺序：宽度线型颜色，其中 solid（实线）最常用

Flex布局#

定义#

Flex（Flexible Box，弹性布局）是一种一维布局模型。设置 display: flex; 的元素成为 Flex 容器（container），其所有直接子元素自动成为 Flex 项目（item）。通过给父容器添加 flex 属性来控制子元素的位置和排列方式。

语法/用法#

1
.container {
2
    display: flex;
3
    flex-direction: row;           /* 主轴方向 */
4
    justify-content: space-between; /* 主轴对齐 */
5
    align-items: center;            /* 交叉轴对齐 */
6
}

容器属性（常用）#

属性	说明	常用值
`display: flex`	开启弹性布局	`flex`
`flex-direction`	主轴方向	`row`（横向，默认）、`column`（纵向）
`justify-content`	主轴对齐方式	`flex-start` / `flex-end` / `center` / `space-between` / `space-around`
`align-items`	交叉轴对齐方式	`flex-start` / `flex-end` / `center` / `stretch`（默认）

justify-content 对齐效果#

值	效果
`flex-start`	从头排列（默认）
`flex-end`	从尾排列
`center`	居中排列
`space-between`	两端贴边，中间平分剩余空间
`space-around`	每个项目两侧留白相等

常见场景#

顶栏布局：标题左对齐，操作按钮右对齐

1
.header {
2
    display: flex;
3
    justify-content: space-between;
4
    align-items: center;
5
}

搜索表单栏：多个输入控件水平排列
卡片列表：等宽等间距的卡片网格
垂直居中：flex-direction: column; justify-content: center; align-items: center;

注意事项#

Flex 是一维布局（行或列），如需二维布局（行和列同时），应使用 CSS Grid
flex-direction: column 时主轴变为纵向，justify-content 控制垂直方向对齐
子元素的 margin 在 Flex 容器中仍有效，margin: auto 可实现独特的居中效果
Flex 布局默认不换行，子元素总宽度超出容器时会被压缩；可通过 flex-wrap: wrap 实现换行

页面居中方案#

定义#

页面居中布局（版心居中）是指将网页主体内容限制在固定宽度内，并在浏览器窗口中水平居中显示。这是现代网页最常见的布局模式。

语法/用法#

核心实现#

1
.container {
2
    width: 70%;         /* 宽度占父元素70%，也可用固定像素如 960px */
3
    margin: 0 auto;     /* 上下0，左右自动（核心居中逻辑） */
4
}

说明#

margin: 0 auto; 的居中原理：将左右外边距均设为 auto，浏览器自动平分剩余空间，实现块级元素水平居中。

完整示例#

1
<style>
2
    body {
3
        margin: 0;
4
    }
5
    #container {
6
        width: 80%;
7
        margin: 0 auto;
8
    }
9
</style>
10

11
<body>
12
    <div id="container">
13
        <!-- 所有页面内容包裹在此容器中 -->
14
    </div>
15
</body>

显示更多显示更少

常见场景#

新闻资讯类网页的正文区域
企业官网的内容区
博客文章内容
后台管理系统中的表格和表单区域

注意事项#

margin: 0 auto 仅对块级元素且设置了明确 width 的元素生效
若使用 Flex 布局，也可通过 justify-content: center 实现子元素居中，但 margin: 0 auto 更轻量
响应式设计中，宽度通常使用百分比或 max-width 而非固定像素值
将 body 的 margin 设为 0 可消除浏览器默认的外边距

CSS核心

Thu, 14 May 2026 00:00:00 GMT

CSS引入方式#

定义#

CSS（Cascading Style Sheet，层叠样式表）用于控制页面元素的样式。在 HTML 中引入 CSS 有三种方式。

语法/用法#

1. 行内样式（Inline）#

通过元素的 style 属性直接设置：

1
<span style="color: #b2b2b2; font-size: 14px;">发布时间</span>

2. 内部样式（Internal）#

在 <head> 中通过 <style> 标签定义：

1
<head>
2
    <style>
3
        .publish-date {
4
            color: #b2b2b2;
5
            font-size: 14px;
6
        }
7
    </style>
8
</head>

3. 外部样式（External）#

通过 <link> 标签引入独立的 .css 文件：

1
<head>
2
    <link rel="stylesheet" href="css/news.css">
3
</head>

news.css 文件内容：

1
.publish-date {
2
    color: #b2b2b2;
3
}

对比#

方式	优点	缺点	使用情况
行内样式	直接、优先级最高	代码冗余、维护困难	不常用（偶尔配合 JS）
内部样式	当前页面集中管理	无法跨页面复用	小型页面、演示示例
外部样式	HTML/CSS 完全分离、可复用	额外 HTTP 请求	企业开发常用方式

常见场景#

外部样式：项目中所有页面的统一样式管理
内部样式：单页面独立样式、快速原型
行内样式：通过 JavaScript 动态设置的样式

注意事项#

三种方式中，行内样式优先级最高（权重：行内 > 内部/外部，后者按选择器优先级和声明顺序决定）
外部样式文件通常创建在 css/ 目录下
企业开发中外部样式是标准做法，实现结构（HTML）与表现（CSS）的完全分离

CSS选择器#

定义#

CSS 选择器用于选取需要设置样式的 HTML 元素。根据业务场景的不同，选择器有多种类型。

语法/用法#

通用格式#

1
选择器名 {
2
    属性名: 属性值;
3
    属性名: 属性值;
4
}

常见选择器类型#

选择器	语法	示例	说明
元素选择器	`tag {}`	`a { color: red; }`	选取所有指定标签
类选择器	`.classname {}`	`.publish-date { color: gray; }`	选取所有带指定 class 的元素
ID 选择器	`#idname {}`	`#title { font-size: 24px; }`	选取带指定 id 的唯一元素

联合使用示例#

1
/* 元素选择器：取消所有超链接下划线 */
2
a {
3
    text-decoration: none;
4
}
5

6
/* 类选择器：新闻发布时间 */
7
.publish-date {
8
    color: #b2b2b2;
9
}
10

11
/* 类选择器：版心居中容器 */
12
.news-content {
13
    width: 70%;
14
    margin: 0 auto;
15
}

显示更多显示更少

常见场景#

全局样式使用元素选择器（如 body、a、p）
组件化或可复用的样式使用类选择器
页面中唯一元素使用 ID 选择器
嵌套关系使用后代选择器（如 .header a）

注意事项#

类选择器（.）可以重复使用，一个元素可有多个 class
ID 选择器（#）在页面中应唯一，不可重复
后台开发场景下重点掌握元素选择器、类选择器、ID 选择器即可满足大多数需求
CSS 选择器权重（优先级）：id > class > 元素

CSS颜色表示#

定义#

CSS 中的颜色可以通过多种方式表示，用于设置文本颜色、背景色、边框色等。

语法/用法#

三种常见表示方式#

方式	语法	示例	说明
颜色关键字	`color: 颜色名;`	`color: gray;`	直接使用预定义颜色名称
十六进制	`color: #RRGGBB;`	`color: #b2b2b2;`	最常用，6位十六进制数
RGB	`color: rgb(r, g, b);`	`color: rgb(178, 178, 178);`	红绿蓝三通道 0-255

示例#

1
.text-gray {
2
    color: #b2b2b2;       /* 十六进制灰色 */
3
}
4

5
.text-white {
6
    color: white;          /* 关键字白色 */
7
}
8

9
.highlight {
10
    color: rgb(216, 57, 49);  /* RGB红色 */
11
}

常见场景#

文本颜色：color 属性
背景颜色：background-color 属性
边框颜色：border-color 属性
按钮、链接的多态颜色（正常、悬停、激活）

注意事项#

十六进制颜色值中的字母不区分大小写（#B2B2B2 等价于 #b2b2b2）
十六进制颜色可简写：如 #fff 等价于 #ffffff，#333 等价于 #333333
拾取网页中已有颜色时，可使用截图软件的拾色器插件
CSS3 还支持 rgba()（带透明度）和 hsl() 等方式，但基础开发中十六进制最为常用

CSS文本样式#

定义#

CSS 文本样式用于控制页面中文字的显示效果，包括字体颜色、缩进、行高、下划线等。

语法/用法#

常用文本属性#

属性	说明	示例	取值
`color`	字体颜色	`color: #b2b2b2;`	颜色值
`text-indent`	首行缩进	`text-indent: 2em;`	长度值（`em`、`px`）
`line-height`	行高（行间距）	`line-height: 2;`	数值（倍数）或长度值
`text-decoration`	文本装饰线	`text-decoration: none;`	`none` / `underline` / `line-through`
`font-size`	字体大小	`font-size: 24px;`	长度值
`font-weight`	字体粗细	`font-weight: bold;`	`normal` / `bold` / 数值

综合示例#

1
p {
2
    text-indent: 2em;     /* 首行缩进2个字符宽度 */
3
    line-height: 2;       /* 行高为字体大小的2倍 */
4
    color: #333;          /* 深灰色文字 */
5
}
6

7
a {
8
    text-decoration: none; /* 去除超链接下划线 */
9
}

常见场景#

新闻正文排版：段落首行缩进 + 行高
超链接样式：去除默认下划线或添加悬停下划线
标题样式：控制字号和粗细
次要信息：使用灰色字体弱化视觉权重

注意事项#

em 是相对于当前字体大小的单位（1em = 当前字号），在 text-indent 中常用于中文缩进（2em ≈ 两个汉字宽度）
line-height 为纯数值时表示当前字体大小的倍数（推荐），为像素值时是固定高度
text-decoration: none 常用于去除 <a> 标签的默认下划线
文本样式可继承：父元素设置的 color、font-size 等会被子元素继承

div与span标签#

定义#

<div> 和 <span> 是无语义的布局标签，实际开发中大量用于页面结构和元素分组。

语法/用法#

1
<div class="container">
2
    <span class="label">姓名：</span>
3
    <span class="value">张三</span>
4
</div>

对比#

特性	`<div>`	`<span>`
显示方式	块级元素：独占一行	行内元素：一行可显示多个
默认宽度	父元素宽度的 100%	由内容撑开
默认高度	由内容撑开	由内容撑开
可设置宽高	可以（`width`、`height`）	不可以
典型用途	页面布局容器、区块划分	行内文本分组、局部样式控制

常见场景#

<div>：页面整体容器、顶栏、侧边栏、卡片容器、页脚等布局区块
<span>：行内文字某部分的样式控制、表单标签的文本分组
<div> 嵌套 <div>：构建复杂的页面布局结构

盒模型相关#

<div> 作为典型的块级容器，是 CSS 盒模型的主要应用对象。通过控制其 width、height、padding、border、margin 实现精确的布局效果。

注意事项#

<div> 和 <span> 本身没有语义，不传递任何内容含义，避免滥用——应优先使用语义化标签（<header>、<footer>、<section>、<article> 等）
需要将行内元素改为块级元素时，可用 CSS display: block;
需要将块级元素改为行内元素时，可用 CSS display: inline;

CloudFlare-ImgBed + Telegram 图床 + PicGo + Obsidian 自动上传全流程教程

Tue, 12 May 2026 00:00:00 GMT

一套真正适合 Markdown 写作者、Obsidian 用户、博客作者的自动化图床方案。

前言#

以前写博客时，我经常会遇到这些问题：

本地 Markdown 图片路径混乱
换电脑后图片丢失
博客迁移时图片全部失效
Typora / Obsidian / VSCode 各种编辑器图床不统一
Git 仓库越来越大

后来我开始折腾：

Cloudflare
Telegram
PicGo
Obsidian

最终整理出了现在这套方案：

1
Obsidian
2
↓
3
Image Auto Upload
4
↓
5
PicGo
6
↓
7
CloudFlare-ImgBed
8
↓
9
Telegram

效果就是：

✅ 在 Obsidian 中直接粘贴图片
✅ 自动上传图床
✅ 自动替换 Markdown 图片链接
✅ Telegram 作为底层存储
✅ Cloudflare 提供 CDN 与访问加速

整个过程几乎完全自动化。

整体架构#

flowchart LR A[Obsidian 写文章] --> B[Image Auto Upload] B --> C[PicGo Server] C --> D[CloudFlare-ImgBed] D --> E[Telegram 存储] E --> F[返回图片 URL] F --> G[自动写回 Markdown]

一、部署 CloudFlare-ImgBed#

项目地址：

https://github.com/MarSeventh/CloudFlare-ImgBed

部署方式推荐：

Cloudflare Pages

1. Fork 仓库#

先 Fork 官方仓库到自己的 GitHub。

2. 创建 Cloudflare Pages#

进入：

1
Cloudflare Dashboard
2
→ Workers & Pages
3
→ Create Application
4
→ Pages
5
→ Connect to Git

选择你 Fork 的仓库。

3. 构建设置（非常重要）#

保持默认即可：

配置项	内容
Framework preset	None
Build command	留空
Build output directory	留空

⚠️ 不要填写：

1
dist
2
build
3
out

否则 Functions 不会部署成功。

二、配置 Telegram 存储#

CloudFlare-ImgBed 最新版默认支持 Telegram 作为上传通道。

1. 创建 Telegram Bot#

打开：

@BotFather

发送：

1
/newbot

创建完成后获取：

1
TG_BOT_TOKEN

2. 获取 Chat ID#

方法：

把 Bot 拉进频道或群组。

然后访问：

1
https://api.telegram.org/bot你的BOT_TOKEN/getUpdates

找到：

1
"chat": {
2
  "id": xxxxxxxxx
3
}

这个就是：

1
TG_CHAT_ID

三、配置 Cloudflare 环境变量#

进入：

1
Cloudflare Pages
2
→ Settings
3
→ Environment Variables

添加：

Key	Value
TG_BOT_TOKEN	Telegram Bot Token
TG_CHAT_ID	Telegram Chat ID
AUTH_CODE	你自己的上传密码

例如：

1
AUTH_CODE=123456

保存后重新部署。

四、测试上传接口#

部署完成后访问：

1
https://你的域名/upload

如果出现：

1
Unauthorized

说明：

✅ 上传接口正常
✅ 认证生效
✅ 可以开始接入 PicGo

五、安装与配置 PicGo#

PicGo：

https://github.com/Molunerfinn/PicGo

1. 安装 picgo-plugin-cfbed-uploader 插件#

打开：

1
PicGo
2
→ 插件设置

搜索：（搜不到就去github下载导入）

1
picgo-plugin-cfbed-uploader

安装：

1
picgo-plugin-cfbed-uploader

安装完成后重启 PicGo。

六、PicGo 图床配置#

进入：

1
PicGo
2
→ 图床设置
3
→ picgo-plugin-cfbed-uploader

填写：

图床配置名#

1
随意

站点地址#

1
https://你的域名/upload

API令牌#

1
图床后台安全设置里添加

上传渠道#

1
自己的渠道

命名方式#

1
按自己的需求

返回格式#

1
默认

七、测试 PicGo 是否成功#

拖一张图片进入 PicGo。

如果成功：

PicGo 会自动复制图片链接。

例如：

1
https://你的域名/file/xxxxx.webp

八、Obsidian 自动上传配置#

插件：

1
Image Auto Upload

安装方式#

1
设置
2
→ 社区插件
3
→ 搜索 Image Auto Upload

安装并启用。

九、开启 PicGo Server#

进入：

1
PicGo
2
→ 设置
3
→ Server

开启：

1
Enable PicGo Server

记住端口。

例如：

1
36677

十、配置 Obsidian 插件#

进入：

1
Image Auto Upload 设置

填写：

1
http://127.0.0.1:36677/upload

十一、最终效果#

现在：

在 Obsidian 粘贴图片
自动触发上传
PicGo 调用图床接口
CloudFlare-ImgBed 存入 Telegram
返回 CDN 外链
自动替换 Markdown 图片

最终 Markdown：

1
![](https://你的域名/file/xxxxx.webp)

十二、推荐开启的功能#

CloudFlare-ImgBed#

建议开启：

WebP 转换
自动压缩
随机文件名

Obsidian#

建议配合：

Git 插件
Excalidraw
Dataview

一起使用。

十三、常见问题#

1. `/upload` 显示 404#

说明：

Functions 没部署成功
Build output 配错

重新部署即可。

2. 上传提示 Unauthorized#

说明：

authCode 不匹配
PicGo Header 配置错误

3. Obsidian 不自动上传#

检查：

PicGo Server 是否开启
端口是否正确
防火墙是否拦截

十四、总结#

这套方案最大的优点：

完全 Markdown 化
低成本
可迁移
自动化程度高
不依赖第三方图床

非常适合：

博客作者
Obsidian 用户
技术写作者
长期知识管理

尤其是：

1
Obsidian + PicGo + Cloudflare

这一套组合，真的非常舒服。

记录博客文件的最佳存储方式

Sun, 10 May 2026 00:00:00 GMT

存储库#

又拍云存储

相册图片管理#

已完成 PicGo 配置又拍云图床，当前作为主力图床使用。
本地新建相册专属文件夹做原始备份
将相册图片统一上传至固定又拍云图床
通过子文件夹对相册进行分类，便于区分管理
保障逻辑：主图床不可用时，可依托本地备份快速重新上传，批量更新各相册图片 URL

普通图片、音乐资源#

本地：按域名建立总文件夹，下级子文件夹分类归档备份
线上：统一存放至又拍云存储

视频资源#

统一托管至哔哩哔哩，使用B站外链链接引用

备用存储方案#

Cloudflare R2 对象存储：10G 容量，无限流量
腾讯云服务器：年费79元，40G 存储空间，每月300G 流量

本地资源备份#

百度网盘

微信读书 × Obsidian × Astro 博客：阅读数据与笔记的完美集成方案

Sat, 09 May 2026 00:00:00 GMT

前言#

如果你同时是微信读书的重度用户和个人博客的拥有者，你一定会遇到这样的痛点：阅读笔记散落在各个平台，无法统一展示和管理。微信读书里有你的划线批注，Obsidian 里有你的知识体系，而博客是你对外展示的数字名片——如何让这三者无缝衔接？

本文将详细介绍一套完整的解决方案：利用 Obsidian Weread 插件将微信读书的书籍信息和笔记同步到本地 Obsidian，再通过 Astro 内容集合将数据自动集成到博客的「记录」页面中，最终呈现为一个美观、可交互的书籍展示模块。

阅读本文前，你需要具备以下基础：

已搭建基于 Astro 的个人博客（本方案基于 Astro v5 + Firefly 主题）
熟悉 Markdown 和 YAML frontmatter 的基本语法
安装了 Obsidian 笔记软件

一、Obsidian Weread 插件简介#

1.1 插件概述#

Obsidian Weread 是由社区开发者 zhaohongxuan 开发的开源 Obsidian 插件。它的核心功能是将微信读书中的书籍元数据、高亮划线、阅读笔记和书评同步到 Obsidian 本地仓库中，以 Markdown 文件的形式存储。

1.2 主要功能#

功能	说明
书架同步	自动拉取微信读书书架上的所有书籍列表
高亮划线	同步书中所有的划线内容（热门划线 + 个人划线）
阅读笔记	同步书中记录的个人笔记和想法
书评导入	同步自己和社区的热门书评
元数据提取	自动获取书名、作者、封面图、ISBN、出版社等信息
增量更新	支持增量同步，避免重复拉取已有数据
自定义模板	支持自定义笔记文件的命名格式和 frontmatter 模板

1.3 同步后的文件格式#

插件同步后，每本书会生成一个独立的 .md 文件，结构大致如下：

1
---
2
doc_type: weread-highlights-reviews
3
bookId: "918483"
4
title: 人性的弱点（卡耐基经典励志系列）
5
author: 戴尔·卡耐基
6
reviewCount: 3
7
noteCount: 5
8
cover: https://cdn.weread.qq.com/weread/cover/35/YueWen_918483/t6_YueWen_918483.jpg
9
---
10

11
> ![人性的弱点（卡耐基经典励志系列）|200](https://cdn.weread.qq.com/...)
12
> **书名**： 人性的弱点（卡耐基经典励志系列）
13
> **作者**： 卡耐基
14

15
# ✍️ 高亮划线
16

17
## 第一章 与他人相处的有效方式
18
📌 "抱怨是很愚蠢的行为..."
19
⏱ 2025-04-26 16:27:37
20

21
# 📒 读书笔记
22

23
## 我的想法
24
这是一本改变我人际交往观念的书...
25

26
# 🤖 本书评论

显示更多显示更少

这个格式非常关键——它既是 Obsidian 中的可读笔记，也是后续博客集成的基础数据源。

二、插件安装与配置#

2.1 安装插件#

方法一：通过 Obsidian 社区插件市场安装（推荐）

打开 Obsidian，进入设置 → 第三方插件（Community Plugins）
关闭安全模式（Safe Mode），点击浏览（Browse）
搜索 Weread，找到 Weread 插件
点击安装 → 启用

方法二：手动安装

Terminal window

1
# 进入你的 Obsidian 仓库插件目录
2
cd your-vault-path/.obsidian/plugins/
3

4
# 克隆插件仓库
5
git clone https://github.com/zhaohongxuan/obsidian-weread-plugin.git
6

7
# 安装依赖
8
cd obsidian-weread-plugin
9
npm install
10
npm run build

然后在 Obsidian 的第三方插件列表中启用它。

2.2 微信读书账号授权#

插件安装完成后，需要进行微信读书的账号授权：

打开 Obsidian，点击左侧工具栏的 Weread 图标（书本图标）
首次使用时，会弹出扫码授权页面——使用微信读书 App 扫描二维码
微信读书 App 中确认授权后，Obsidian 插件即完成了登录绑定

Obsidian Weread 登录界面

安全提醒：你的登录凭证仅存储在本地 Obsidian 的 data.json 中，不会上传到第三方服务器。插件的所有网络请求直接访问微信读书官方 API。

2.3 配置同步选项#

进入设置 → Weread 配置页面，可以根据需求调整以下选项：

配置项	建议值	说明
笔记保存目录	`Weread` 或自定义	同步后的 .md 文件存放位置
同步频率	手动触发	避免频繁请求被封
书籍文件命名	`{{title}} - {{author}}`	使用书名+作者命名
同步热门划线	关闭	只同步个人内容更精简
同步书评	按需开启	可能会拉取大量社区评论
Frontmatter 模板	默认	保持 `doc_type`、`bookId` 等字段

三、数据同步操作#

3.1 首次全量同步#

配置完成后，回到 Obsidian 主界面：

点击左侧工具栏的 Weread 图标
在打开的侧边面板中，点击同步按钮（或使用命令面板 Ctrl+P → 搜索 “Weread: Sync”）
等待同步完成——根据书架书籍数量，可能需要几分钟
同步完成后，你的笔记保存目录下会出现所有书籍的 .md 文件

3.2 增量同步#

当你在微信读书中有新的划线或笔记后，再次点击同步按钮即可。插件会自动对比已有数据，只拉取新增或变更的内容，不会重复写入。

3.3 文件迁移到博客目录#

同步完成后，你需要将书籍文件从 Obsidian 笔记目录复制或移动到 Astro 博客的 bangumi 内容目录：

1
# 从 Obsidian 笔记目录
2
your-vault/Weread/人性的弱点（卡耐基经典励志系列）.md
3

4
# 移动到博客目录（按个人分类建立子目录）
5
blog/src/content/bangumi/book/个人成长/人性的弱点.md

小技巧：本项目支持将书籍文件按主题分类（如 个人成长/、心理/、文学/、精品小说/ 等），这些子目录会被自动识别为路径的一部分，方便管理大量书籍。

四、博客集成实现详解#

这是本文最核心的部分。我们将详细介绍如何将 Obsidian 同步的书籍数据无缝集成到博客的「记录」页面中。

4.1 整体架构#

1
┌──────────────────────────────────────────────────────┐
2
│                                                      │
3
│  微信读书 App                                        │
4
│  ┌────────────┐                                      │
5
│  │ 划线/笔记  │                                       │
6
│  │ 书评/书籍  │                                       │
7
│  └─────┬──────┘                                      │
8
│        │ 扫码授权                                    │
9
│        ▼                                             │
10
│  Obsidian Weread 插件 ◄── API 请求 ──► 微信读书服务器 │
11
│  ┌────────────┐                                      │
12
│  │ .md 文件   │                                       │
13
│  └─────┬──────┘                                      │
14
│        │ 文件复制                                    │
15
│        ▼                                             │
16
│  src/content/bangumi/book/                           │
17
│  ┌────────────┐                                      │
18
│  │ book/*.md  │ ◄── Astro Content Collections        │
19
│  └─────┬──────┘                                      │
20
│        │ getCollection("bangumi")                    │
21
│        ▼                                             │
22
│  src/pages/bangumi.astro                             │
23
│  ┌────────────────────┐                              │
24
│  │  数据映射处理       │                              │
25
│  │  → UserSubjectCollection                          │
26
│  └─────┬──────────────┘                              │
27
│        │ props                                       │
28
│        ▼                                             │
29
│  src/components/pages/bangumi/                       │
30
│  ┌──────────────┐  ┌─────────────────┐              │
31
│  │ Card.astro   │  │ [...slug].astro │              │
32
│  │ (卡片/列表)  │  │ (详情页)        │              │
33
│  └──────────────┘  └─────────────────┘              │
34
│                                                      │
35
└──────────────────────────────────────────────────────┘

显示更多显示更少

4.2 数据模型定义#

首先，在 src/content.config.ts 中定义 bangumi 内容集合的 Schema。这是整个系统的数据结构基础：

src/content.config.ts显示更多显示更少

1
const bangumiCollection = defineCollection({
2
  loader: glob({
3
    pattern: "**/*.{md,mdx,yaml,yml}",
4
    base: "./src/content/bangumi",
5
  }),
6
  schema: ({ image }) =>
7
    z.object({
8
      title: z.string(),                                 // 书名
9
      name_cn: z.string().optional(),                    // 简短显示名
10
      category: z.enum(["book", "anime", "music", "game", "real"]).default("anime"),
11
      status: z.number().min(1).max(5).default(2),       // 1:想看 2:看过 3:在看 4:搁置 5:抛弃
12
      image: image().or(z.string()),                      // 封面图
13
      link: z.string().optional(),                        // 自定义链接（可选）
14
      score: z.number().min(0).max(10).optional(),        // 评分 0-10
15
      comment: z.string().optional(),                     // 一句话评价
16
      tags: z.array(z.string()).optional().default([]),  // 标签
17
      published: z.date().optional(),                     // 发布日期
18
    }),
19
});

显示更多显示更少

设计要点：

link 字段为可选——如果未提供，系统会自动从文件路径推导（后文会详细说明）
category 使用枚举限制，确保数据一致性
image 接受 Astro 优化的图片对象或纯 URL 字符串
score 采用 0-10 分制（符合番组计划评分标准）
status 数字映射——1 想看 / 2 看过 / 3 在看 / 4 搁置 / 5 抛弃

4.3 书籍文件的 Frontmatter 格式#

每个书籍的 .md 文件需要包含以下 frontmatter 字段，以 人性的弱点 为例：

1
---
2
doc_type: weread-highlights-reviews   # Weread 插件标注
3
bookId: "918483"                       # 微信读书书籍ID
4
title: 人性的弱点（卡耐基经典励志系列）
5
reviewCount: 3
6
noteCount: 5
7
category: book                         # 类别：book
8
status: 2                              # 状态：看过
9
image: https://cdn.weread.qq.com/weread/cover/35/YueWen_918483/t6_YueWen_918483.jpg
10
tags:
11
  - 个人成长-沟通表达
12
  - 卡耐基
13
published: 2026-05-10
14
---

注意：category: book 是必需的，否则书籍不会出现在「书籍」标签页中。title 字段决定了详情页 URL 的路径来源。

4.4 页面数据处理#

在 src/pages/bangumi.astro 中，核心的数据处理流程如下：

1
---
2
import { getCollection } from "astro:content";
3
import { removeFileExtension } from "@/utils/url-utils";
4

5
const customBangumi = await getCollection("bangumi");
6
const allPosts = await getCollection("posts");
7

8
const categoryMap = {
9
  book:  { id: "book",  name: "书籍", subjectType: 1 },
10
  anime: { id: "anime", name: "影视", subjectType: 2 },
11
  music: { id: "music", name: "音乐", subjectType: 3 },
12
  game:  { id: "game",  name: "游戏", subjectType: 4 },
13
};
14

15
const mappedData = customBangumi.map((item) => {
16
  const { data } = item;
17
  const categoryInfo = categoryMap[data.category];
18

19
  // 链接自动生成逻辑
20
  let rawLink = (data.link || "").trim();
21
  if (!rawLink) {
22
    // 无自定义链接时，从文件路径自动推导
23
    const entrySlug = removeFileExtension(item.id);
24
    rawLink = `/bangumi/${entrySlug}/`;
25
  }
26

27
  // 检查是否匹配某篇博客文章
28
  let finalLink = rawLink;
29
  const matchingPost = allPosts.find((p) => {
30
    // ... 匹配逻辑 ...
31
  });
32
  if (matchingPost) {
33
    finalLink = `/posts/${matchingPostSlug}/`;
34
  }
35

36
  return {
37
    subject_type: categoryInfo.subjectType,
38
    rate: data.score || 0,
39
    type: data.status,
40
    comment: data.comment || null,
41
    tags: data.tags || [],
42
    link: finalLink,
43
    subject: {
44
      name: data.title,
45
      name_cn: data.name_cn || data.title,
46
      images: {
47
        medium: typeof data.image === "string" ? data.image : data.image.src,
48
        // ... 其他尺寸
49
      },
50
      score: data.score || 0,
51
    },
52
  };
53
});
54
---

显示更多显示更少

自动链接生成的巧妙之处：

item.id 是 Astro 内容集合自动生成的 ID，反映了文件在 src/content/bangumi/ 下的相对路径
removeFileExtension() 去除 .md 后缀后，直接拼接为 /bangumi/{path}/
例如 book/个人成长/人性的弱点 → /bangumi/book/个人成长/人性的弱点/
这个 URL 自动与 [...slug].astro catch-all 路由生成的路径完全一致

4.5 卡片组件实现#

书籍在列表页中呈现为「番组计划」风格的卡片，代码位于 src/components/pages/bangumi/Card.astro：

1
---
2
const { item } = Astro.props;
3
const link = item.link || `${subject_base_url}${item.subject.id}`;
4
const subType = item.subject_type;
5
const title = item.subject.name_cn || item.subject.name;
6
---
7

8
<a
9
  href={link}
10
  target={item.link ? "_self" : "_blank"}
11
  class="bm-card group"
12
  data-type={subType}
13
>
14
  <div class="bm-cover">
15
    <img
16
      src={item.subject?.images?.medium || ""}
17
      alt={title}
18
      class="bm-img"
19
      loading="lazy"
20
    />
21

22
    <!-- 底部渐变遮罩 -->
23
    <div class="bm-gradient" />
24

25
    <!-- 左上：阅读状态 -->
26
    <span class="bm-status bg-emerald-500/80">看过</span>
27

28
    <!-- 右上：评分 -->
29
    <span class="bm-score">
30
      <svg>★</svg> 9
31
    </span>
32

33
    <!-- 底部文字叠层 -->
34
    <div class="bm-info">
35
      <h3 class="bm-title">人性的弱点</h3>
36
      <div class="bm-tags">
37
        <span class="bm-tag">个人成长</span>
38
        <span class="bm-tag">卡耐基</span>
39
      </div>
40
    </div>
41

42
    <!-- 悬停评论遮罩 -->
43
    <div class="bm-overlay">
44
      <p class="bm-comment">人际交往的永恒经典</p>
45
    </div>
46
  </div>
47
</a>

显示更多显示更少

CSS 设计要点：

1
/* 书籍保持 2:3 竖版封面（与电影海报一致） */
2
.bm-cover {
3
  aspect-ratio: 2/3;
4
}
5

6
/* 游戏使用 3:2 横向比例 */
7
.bm-card[data-type="4"] .bm-cover {
8
  aspect-ratio: 3/2;
9
}
10

11
/* 音乐使用 1:1 正方形比例 */
12
.bm-card[data-type="3"] .bm-cover {
13
  aspect-ratio: 1/1;
14
}
15

16
/* 悬停时封面微缩放 */
17
.bm-card:hover .bm-img {
18
  transform: scale(1.06);
19
}
20

21
/* 悬停时显示评论遮罩 */
22
.bm-card:hover .bm-overlay {
23
  opacity: 1;
24
}

显示更多显示更少

交互细节：

交互	效果
鼠标悬停	卡片上浮 3px + 主色边框光晕
封面悬停	图片缓慢放大 6%
评论遮罩	从透明渐显，仅在有 comment 时显示
点击卡片	跳转到该书的详情页

4.6 详情页路由#

详情页使用 Astro 的动态路由 [...slug].astro 来匹配所有 bangumi 条目：

1
---
2
import { getCollection, render } from "astro:content";
3
import { removeFileExtension } from "@/utils/url-utils";
4

5
export async function getStaticPaths() {
6
  const bangumiEntries = await getCollection("bangumi");
7
  return bangumiEntries.map((entry) => ({
8
    params: { slug: removeFileExtension(entry.id) },
9
    props: { entry },
10
  }));
11
}
12

13
const { entry } = Astro.props;
14
const { Content, headings } = await render(entry);
15
---
16

17
<MainGridLayout title={entry.data.title} headings={headings}>
18
  <div class="card-base">
19
    <h1>{entry.data.title}</h1>
20
    <!-- 元数据：发布日期、分类、评分、状态 -->
21
    <div class="post-meta">
22
      <span>评分: ⭐⭐⭐⭐ 9/10</span>
23
      <span>分类: 书籍</span>
24
      <span>状态: 看过</span>
25
    </div>
26

27
    <!-- 渲染书籍 markdown 正文 -->
28
    <Markdown>
29
      <Content />
30
    </Markdown>
31
  </div>
32
</MainGridLayout>

显示更多显示更少

详情页完整展示了书籍的所有信息：封面 banner、元数据栏（评分/分类/状态/日期）、一句话评价引用块、标签列表，以及使用 render() 渲染的 Markdown 正文（包含高亮划线和读书笔记）。

五、实际案例#

5.1 同步效果展示#

以《人性的弱点》为例，以下是完整的数据流展示：

微信读书中的划线：

“在30年前我就已经明白，抱怨是很愚蠢的行为。我从不埋怨上帝对智慧的分配不均。”

Obsidian 中的 Markdown 文件：

1
## 与他人相处的有效方式
2
📌 "...抱怨是很愚蠢的行为..."
3
⏱ 2025-04-26 16:27:37

博客中的展示效果：

博客的书籍详情页会以结构化方式呈现所有高亮划线，按章节分组，每条划线下方显示添加时间。页面使用 Firefly 主题的原生 Markdown 渲染，支持深色/浅色模式。

5.2 书籍管理列表#

在博客的「记录」页面（/bangumi/），点击顶部 📚 书籍 标签，即可看到所有已读和在读的书籍卡片。每张卡片以书籍封面为主体，底部叠层显示书名和标签，左上角标注阅读状态，右上角展示评分。

点击任意书籍卡片，即可进入该书详情页，查看完整的高亮划线、阅读笔记和书评内容。

5.3 新增一本书的完整操作流程#

从微信读书读完一本书到博客展示，完整流程如下：

在微信读书中阅读并划线、写笔记
打开 Obsidian → 点击 Weread 同步按钮（几秒到几分钟）
将生成的 .md 文件移到博客目录：src/content/bangumi/book/分类名称/书名.md

在文件 frontmatter 中补充以下字段：

1
category: book
2
status: 2          # 1:想看 2:看过 3:在看
3
tags: [标签1, 标签2]
4
published: 2026-05-10
5
score: 9
6
comment: 一句话评价

保存文件 → Astro 开发服务器自动热重载 → 书籍即刻出现在博客中

提示：不需要手动添加 link 字段！系统会从文件路径自动推导跳转链接。

六、总结与优化方向#

6.1 方案优势#

优势	说明
一次配置，长期受益	插件和博客集成配置完成后，新增书籍只需补充几行 frontmatter
数据完全自主可控	所有数据以 Markdown 文件存储在你的本地仓库中，不依赖任何第三方服务
链接零配置	系统自动从文件路径推导跳转链接，无需手动维护 URL
主题原生适配	利用 Firefly 主题的 Markdown 渲染和暗黑模式，无需额外前端开发
可扩展性强	基于 Astro Content Collections 架构，可轻松扩展到影视、游戏、音乐等品类

6.2 可能的优化方向#

自动补全 Frontmatter：编写脚本自动为同步后的文件添加 category、status 等字段，减少手动操作
Obsidian Callout 渲染：同步后的笔记中可能包含 Obsidian 风格的多类型 callout（如 > [!tip]、> [!warning]），可以通过 marked 扩展或自定义渲染器来呈现更丰富的视觉效果
阅读进度追踪：在卡片或详情页显示阅读进度百分比（基于微信读书的阅读数据）
批量操作脚本：开发 Node.js 脚本，一键将 Obsidian 中所有 Weread 书籍迁移到博客目录，并自动添加必要的 frontmatter
API 自动同步：如果微信读书开放了更完善的 API，可以考虑在博客构建时直接从微信读书拉取最新数据，完全省去手动同步步骤
阅读统计可视化：基于书籍数据和笔记数量，在博客中生成阅读热力图、年度阅读总结等可视化图表

6.3 相关资源#

结语#

通过 Obsidian Weread 插件 + Astro Content Collections 的组合方案，我们成功打通了「微信读书 → Obsidian → 博客」的数据链路。你只需要在手机上阅读、划线和写想法，剩下的同步和展示工作全部自动化完成。

这套方案的价值不在于技术有多复杂，而在于它真正解决了「阅读输入 → 笔记沉淀 → 知识输出」的完整闭环。希望这篇文章能帮助同样热爱阅读和写作的你，建立属于自己的数字阅读档案馆。

如果你对这个方案有任何疑问或改进建议，欢迎在评论区交流！

AI摘要打字机使用指南

Thu, 07 May 2026 00:00:00 GMT

AI摘要打字机使用指南#

博客为每篇文章详情页顶部配备了一个 AI 摘要打字机组件，读者打开文章时会以打字机动画形式逐字展示文章摘要，提升阅读体验。

功能概览#

文章详情页顶部自动展示一段摘要
摘要以打字机动画逐字显示，标点处稍作停顿，模拟真人打字节奏
只在首次滚动到摘要区域时播放一次，不会重复触发
尊重用户系统设置：开启了「减少动态效果」的设备会直接静态显示全文
摘要内容优先读取你手动编写的 description 字段，没有时才由 AI 补全

摘要来源#

所有文章的摘要来源由 frontmatter 中的 descriptionSource 字段标记：

值	含义	页面显示
`manual`	人工编写	📝 人工编写
`ai`	千问 AI 生成	🧠 AI 摘要

你完全可以自己写 description 并标记 descriptionSource: manual，这样就不会被 AI 覆盖。

如何手动编写摘要#

在你的文章 frontmatter 中添加 description 字段即可：

1
---
2
title: 我的文章标题
3
published: 2026-04-15
4
description: "一段自然的、像博客导语一样的摘要文字，60~120字左右。"
5
descriptionSource: manual
6
tags:
7
  - 标签
8
category: 分类
9
---

字段说明：

description：文章的摘要内容。建议长度 60～120 字，自然、口语化，像博主在给读者做开场铺垫。
descriptionSource：标记来源。manual 表示你自己写的，ai 表示由脚本生成的。

使用 AI 补全缺失摘要#

如果你的文章有 description 字段，脚本会直接跳过这篇文章，不会做任何改动。只有当你新增了一篇文章但没有写 description 时，补全脚本才会介入。

运行补全脚本#

在项目根目录执行：

Terminal window

1
npx tsx scripts/fill-descriptions.ts

脚本做了什么#

扫描 src/content/posts/ 下所有 .md 和 .mdx 文件
找出所有没有 description 字段的文章
提取文章标题和正文前 2600 字作为上下文
调用千问（Qwen）API，用专门优化过的提示词生成一段「像人写的」摘要
将生成的摘要写入文章 frontmatter 的 description 字段
同时添加 descriptionSource: ai 标记
已有 description 的文章 完全不动，不会覆盖你的手写内容

执行日志示例#

1
[09:15:32] 🚀  AI 摘要补全脚本启动
2
[09:15:32] 📡  模型: qwen-plus
3
[09:15:32] 📂  文章目录: src/content/posts
4
[09:15:32] 📊  扫描到 29 篇文章
5
[09:15:32] 📋  27 篇已有描述 -> 跳过
6
[09:15:32] 📝  2 篇缺少描述 -> 准备补全
7
[09:15:33] ⏳  正在生成: 技术分享/新文章.md
8
[09:15:34] ✅  补全完成: 技术分享/新文章.md
9
[09:15:34]    → 折腾了两天终于把Nginx反代配通了……
10
[09:15:35] 🏁  执行完毕
11
[09:15:35]    跳过（已有描述）: 27 篇
12
[09:15:35]    需要补全: 2 篇
13
[09:15:35]    ✅ 成功: 2 篇
14
[09:15:35]    ❌ 失败: 0 篇

失败处理#

单次 API 请求失败会自动重试最多 2 次，每次间隔递增等待
全部重试失败后，该文章会被标记为失败，不影响其他文章继续处理
脚本执行结束后会列出所有失败的文章，你可以修改后再次运行重试
请求之间间隔 600ms，避免触发 API 限流

AI 生成的摘要是「像人写的」吗？#

我们在补全脚本中内置了一套精心设计的提示词（Prompt），让千问知道：

不要用「本文主要讲述了」「这篇文章介绍了」这种机械开头
不要堆砌概念、不要写成说明书提纲
要自然、口语化，像一个真实的博主在给读者做开场铺垫
技术文章保持清晰但别冷冰冰，生活感文章语气柔和一些
保留原作者的情绪和语气

所以生成出来的摘要更像这样：

折腾了两天终于把Nginx反代配通了，中间踩了三个莫名其妙的坑，趁热记下来免得下次再掉进去 😤

而不是：

本文主要介绍了Nginx反向代理的配置方法，包括常见的错误排查和解决方案。

如何在构建前自动补全#

如果你希望每次 pnpm build 时自动补全新文章的摘要，可以修改 package.json 的 build 脚本：

1
{
2
  "scripts": {
3
    "build": "npx tsx scripts/fill-descriptions.ts && node scripts/generate-icons.js && astro build && pagefind --site dist"
4
  }
5
}

这样每次部署前都会自动检查并补全缺失的摘要，无需手动运行脚本。

注意事项#

脚本不上传 GitHub：scripts/fill-descriptions.ts 已加入 .gitignore，因为它包含千问 API 密钥，确保不会泄露到公开仓库。
只写 description 不写 content：脚本只修改 frontmatter 中的 description 和 descriptionSource，不会触碰文章正文内容。
无描述不显示摘要：如果文章没有 description 且未运行过补全脚本，文章页面不会显示摘要区域，不影响正常页面渲染。
千问模型选择：当前使用 qwen-plus（性价比之选），如有需要可切换为 qwen-max（质量更好）或 qwen-turbo（更快更便宜）。

ZeppLife刷步数全教程

Fri, 24 Apr 2026 00:00:00 GMT

⚠️重要提醒第三方刷步工具存在账号被盗、信息泄露、被平台检测异常风险，本教程仅作技术学习参考，操作请谨慎。

从应用商店搜索下载zepp life或zepp软件，不支持第三方登陆，所以没有账号的请用邮箱注册
登陆zepplife后点击 “我的->第三方接入” 选择绑定微信或支付宝
用浏览器访问本平台，填写zepplife的账号、密码和你要走的步数，提交即可
如遇账号密码正确但还是提示错误，请登陆一次你的zepp life软件账号。

✔提交成功但没有同步问题解答#

可能存在延迟，稍等一会再看。
如果一直不行，微信取关”amazfit华米”公众号，用WX重新扫码绑定zepplife再试。如果还不同步，用邮箱注册一个新号绑定尝试。再不行的话就等1-2天再试。

一、下载并注册 Zepp Life 账号（必做）

手机应用商店搜索 Zepp Life（原小米运动），下载安装。
打开 App，点击注册（不要用微信 / QQ / 小米账号快捷登录）。
选择邮箱注册（推荐 QQ 邮箱 / 163 邮箱，如 123456@qq.com），填写邮箱、密码，完成注册并登录。
注册后随意填写性别、身高、体重等信息，跳过绑定手环 / 手表（不需要设备）。

二、绑定微信运动（同步步数到微信）

Zepp Life 底部点我的 → 找到第三方接入。
选择微信 → 点击绑定，生成二维码。
微信扫一扫该二维码，关注 Amazfit 华米公众号，完成授权绑定。
绑定成功后，微信运动可同步 Zepp Life 步数（不可取关公众号，否则解绑）。

三、网页刷步数操作

手机浏览器打开网址：https://ze.tsh520.cn/
输入信息：（生日为0824）

账号：注册的 Zepp Life 邮箱 / 手机号
密码：Zepp Life 登录密码
步数：建议 8000–25000（过高易异常）

点击提交 / 更新运动步数，提示成功后等待 1–3 分钟同步。

四、查看结果

打开 Zepp Life → 运动，确认今日步数已更新。
打开微信 → 微信运动，下拉刷新，步数同步到排行榜。

五、常见问题

提交失败：核对账号密码、确认非第三方快捷登录、换浏览器重试。
微信不同步：Zepp Life 重新绑定微信；微信运动→设置→重新授权。
异常提示：降低步数数值（≤25000），不要频繁提交

Obsidian 笔记同步指南

Tue, 21 Apr 2026 00:00:00 GMT

Obsidian 笔记同步指南#

本文档介绍如何使用博客内置的同步工具，将 Obsidian 笔记库中的内容同步到博客的 content 文件夹。

概述#

同步工具是一个 Node.js 脚本，位于 scripts/sync.js。它可以：

将 Obsidian 笔记库中的笔记同步到博客的 content 文件夹
支持多种同步策略（跳过、增量、强制覆盖）
自动处理笔记中的图片资源
支持按类型选择性同步
交互式菜单操作，简单易用

工作原理#

1
Obsidian 笔记库                          博客项目
2
┌─────────────────────┐                ┌─────────────────────┐
3
│ posts/              │                │ src/content/        │
4
│   └── 技术笔记/      │  ── 同步 ──>   │   └── posts/        │
5
│       └── Java.md   │                │       └── 技术笔记/ │
6
│ moments/            │                │           └── Java.md
7
│   └── 2026-04-21.md │               │ moments/            │
8
│ bangumi/            │                │   └── 2026-04-21.md │
9
│   └── anime/        │                │ bangumi/            │
10
│       └── 巨人.md   │                │   └── anime/        │
11
│       └── 巨人.md   │                    └── 巨人.md        │
12
│ life/               │                │ life/               │
13
│   └── health/       │                │   └── health/       │
14
│       └── workout/  │                │       └── workout/  │
15
│           └── ...   │                │           └── ...   │
16
└─────────────────────┘                └─────────────────────┘

显示更多显示更少

目录结构#

同步脚本位于 scripts 目录下：

1
scripts/
2
├── sync.js              # 同步主脚本
3
├── sync.config.js       # 配置文件（包含你的实际配置）
4
├── sync.config.example.js  # 配置模板（用于参考）
5
├── sync.sh             # Linux/macOS Shell 脚本
6
├── sync.ps1            # Windows PowerShell 脚本

快速开始#

1. 配置 Obsidian 路径#

编辑 scripts/sync.config.js 文件，修改 obsidianVaultPath 为你的 Obsidian 笔记库路径：

1
export default {
2
  // Obsidian 笔记库路径（必须修改！）
3
  // Windows 示例: 'E:/Obsidian/Vault'
4
  // macOS/Linux 示例: '/Users/username/Obsidian/Vault'
5
  obsidianVaultPath: 'B:/GitHub/dumplingandcake_warehouse/网络笔记',
6

7
  // 博客项目 content 文件夹路径（通常不需要修改）
8
  projectContentPath: path.resolve(__dirname, '../src/content'),
9
  // ...
10
};

2. 运行同步#

Terminal window

1
# 进入 scripts 目录
2
cd scripts
3

4
# 运行同步脚本
5
node sync.js

运行后会显示交互式菜单，引导你完成同步操作。

3. 交互式菜单#

1
🚀 Obsidian 笔记同步工具
2

3
==================================================
4

5
请选择同步策略:
6

7
  1. 跳过已存在 - 只复制新文件，已存在的跳过
8
  2. 增量同步 - 源文件较新时才更新
9
  3. 强制覆盖 - 覆盖所有文件
10

11
请输入选项 (1-3):

选择策略后，再选择要同步的内容类型：

1
请选择要同步的内容类型:
2

3
  1. 同步文章
4
  2. 同步动态
5
  3. 同步记录
6
  4. 同步生活
7
  5. 同步相册
8
  6. 同步弹幕
9
  7. 同步导航
10
  8. 同步全部
11
  9. 返回上级

命令行参数#

除了交互模式，还支持命令行参数直接执行：

基本用法#

Terminal window显示更多显示更少

1
# 交互模式（默认 skip 策略）
2
node sync.js
3

4
# 增量同步
5
node sync.js --strategy incremental
6

7
# 强制同步
8
node sync.js --force
9

10
# 仅同步文章
11
node sync.js --type 文章
12

13
# 仅同步动态
14
node sync.js --type 动态
15

16
# 同步多个类型
17
node sync.js --type 文章 --type 动态
18

19
# 同步全部
20
node sync.js --all

显示更多显示更少

参数说明#

参数	说明	示例
`-s, --strategy <策略>`	同步策略	`skip` / `incremental` / `force`
`-t, --type <类型>`	指定同步类型	`文章` / `动态` / `记录` 等
`-a, --all`	同步全部类型	-
`-f, --force`	强制覆盖	等同于 `--strategy force`
`-h, --help`	显示帮助	-

同步类型#

支持的类型对应配置中的 type 字段：

类型	说明	Obsidian 文件夹
`文章`	博客文章	`posts/`
`动态`	日常动态	`moments/`
`记录`	番组记录	`bangumi/`
`生活`	生活记录	`life/`
`相册`	相册	`album/`
`弹幕`	弹幕留言	`danmu/`
`导航`	网站导航	`daohang/`

同步策略#

skip（默认）#

跳过已存在的文件，只复制新文件。

1
适用场景：
2
- 首次同步
3
- 只添加新内容，不想修改已有内容

incremental（增量同步）#

仅当源文件较新时才更新目标文件。

1
适用场景：
2
- 在多台设备上编辑，需要合并更改
3
- 希望自动保持同步状态

force（强制覆盖）#

无条件覆盖所有文件。

1
适用场景：
2
- 想用 Obsidian 版本完全替换博客版本
3
- 调试时需要重置同步状态

配置文件详解#

sync.config.js 完整配置说明：

1
export default {
2
  // ========================================
3
  // 主要配置
4
  // ========================================
5

6
  // Obsidian 笔记库路径
7
  obsidianVaultPath: 'B:/GitHub/dumplingandcake_warehouse/网络笔记',
8

9
  // 博客项目 content 路径（通常不需要修改）
10
  projectContentPath: path.resolve(__dirname, '../src/content'),
11

12
  // 是否输出详细信息
13
  verbose: true,
14

15
  // 默认同步策略
16
  syncStrategy: 'skip',
17

18
  // ========================================
19
  // 映射规则
20
  // ========================================
21
  mappings: [
22
    {
23
      type: '文章',
24
      obsidianFolder: 'posts',
25
      targetFolder: 'posts',
26
      datePrefix: false,        // 是否添加日期前缀
27
    },
28
    {
29
      type: '动态',
30
      obsidianFolder: 'moments',
31
      targetFolder: 'moments',
32
      datePrefix: true,         // moments 需要日期前缀
33
      dateField: 'published',   // frontmatter 中的日期字段
34
      dateFormat: 'YYYY-MM-DD',
35
    },
36
    // ... 其他类型
37
  ],
38
};

显示更多显示更少

mapping 配置说明#

字段	说明
`type`	类型名称（用于命令行识别）
`obsidianFolder`	Obsidian 中对应的文件夹名称
`targetFolder`	博客 content 中对应的文件夹
`datePrefix`	是否自动添加日期前缀
`dateField`	frontmatter 中的日期字段名
`dateFormat`	日期格式

图片资源处理#

同步工具会自动处理笔记中引用的图片资源：

同级 assets 文件夹：如果笔记所在目录有 assets 文件夹，会自动同步到博客对应的 assets 目录
保持相对路径：笔记中的图片引用路径保持不变
支持多种格式：jpg、png、gif、webp 等

1
Obsidian 结构：
2
posts/
3
└── 我的文章/
4
    ├── 我的文章.md      ← 笔记正文
5
    └── assets/          ← 笔记图片
6
        ├── img1.png
7
        └── img2.jpg
8

9
同步后博客结构：
10
src/content/posts/
11
└── 我的文章/
12
    ├── 我的文章.md
13
    └── assets/
14
        ├── img1.png
15
        └── img2.jpg

显示更多显示更少

使用场景#

场景 1：日常写作#

在 Obsidian 中写文章
完成编辑后运行 node sync.js
选择「同步文章」或「同步全部」
在博客项目中 npm run dev 预览效果

场景 2：多设备同步#

在公司电脑上编辑笔记
通过 Git 同步 Obsidian vault 到云端
在家里电脑拉取最新笔记
运行同步脚本更新博客

场景 3：批量更新#

Terminal window

1
# 批量同步多个类型
2
node sync.js --type 文章 --type 动态
3

4
# 强制同步全部（用于重置）
5
node sync.js --all --force

常见问题#

Q: 同步后图片不显示？#

检查以下几点：

图片是否在笔记同级的 assets 文件夹中
笔记中的图片引用路径是否正确（相对于笔记文件）
图片格式是否被博客支持

Q: 如何排除某些文件不同步？#

目前脚本会自动同步文件夹中的所有文件。如需排除，可以：

将不需要同步的文件放在 Obsidian 的 .obsidian 文件夹（会被自动跳过）
或在同步后手动删除不需要的文件

Q: 同步冲突怎么办？#

如果同一文件在多处被修改，建议：

使用增量同步策略
先备份重要文件
手动解决冲突后重新同步

Q: 如何修改同步的文件夹映射？#

编辑 sync.config.js 中的 mappings 数组，添加或修改映射规则。

Q: 提示 “Obsidian vault 路径不存在”？#

检查 sync.config.js 中的 obsidianVaultPath 配置：

Windows 路径使用正斜杠：E:/Obsidian/Vault
路径是否存在且正确

平台脚本#

除了直接运行 Node 脚本，还提供了各平台的快捷脚本：

Windows (PowerShell)#

Terminal window

1
# 运行同步
2
.\sync.ps1
3

4
# 带参数运行
5
.\sync.ps1 -Type "文章" -Strategy "incremental"

Linux/macOS (Shell)#

Terminal window

1
# 添加执行权限
2
chmod +x sync.sh
3

4
# 运行同步
5
./sync.sh
6

7
# 带参数运行
8
./sync.sh --type 文章 --strategy incremental

与坚果云等云服务配合#

可以将 Obsidian vault 同步到坚果云等云存储服务，实现多设备同步：

1
┌─────────────────────────────────────────────────────────┐
2
│                     坚果云同步                           │
3
│  ┌─────────┐    ┌─────────┐    ┌─────────┐              │
4
│  │   PC    │◄──►│  云端   │◄──►│   手机   │              │
5
│  └────┬────┘    └─────────┘    └─────────┘              │
6
│       │                                                   │
7
│       │  sync.js                                          │
8
│       ▼                                                   │
9
│  ┌─────────────────────────────────────┐                 │
10
│  │           Astro 博客                 │                 │
11
│  │        src/content/                 │                 │
12
│  └─────────────────────────────────────┘                 │
13
└─────────────────────────────────────────────────────────┘

更新日志#

2026-04-21: 初始版本

如有问题或建议，欢迎反馈！

博客使用指南

Sat, 18 Apr 2026 00:00:00 GMT

博客使用指南#

本文档详细介绍博客的各项功能和使用方法。

目录#

项目结构
命名规范
文章系统 (posts)
日常动态 (moments)
生活记录 (life)
相册 (album)
导航 (daohang)
弹幕 (danmu)
特殊页面 (spec)
番组计划 (bangumi)
侧边栏组件
评论系统
高级功能配置
SEO 与统计
主题定制
部署与维护
常见问题
附录

项目结构#

1
src/
2
├── content/
3
│   ├── posts/           # 博客文章
4
│   ├── moments/         # 日常动态
5
│   ├── album/           # 相册
6
│   ├── daohang/         # 网站导航
7
│   ├── danmu/           # 弹幕留言
8
│   ├── bangumi/         # 番组计划
9
│   ├── spec/            # 特殊页面（关于、友链等）
10
│   └── life/            # 生活记录
11
│       ├── ideas/       # 想法
12
│       ├── places/      # 地点
13
│       ├── checkin/     # 打卡
14
│       ├── routines/    # 日常规划
15
│       ├── health/
16
│       │   ├── workout/ # 运动
17
│       │   ├── sleep/  # 睡眠
18
│       │   └── food/   # 饮食
19
│       └── notebooks/   # 笔记本
20
├── pages/               # 页面路由
21
├── components/          # 组件
22
├── config/              # 配置文件
23
│   ├── siteConfig.ts    # 站点配置
24
│   ├── sidebarConfig.ts # 侧边栏配置
25
│   ├── navBarConfig.ts  # 导航栏配置
26
│   ├── commentConfig.ts # 评论配置
27
│   └── ...
28
└── i18n/                # 国际化

显示更多显示更少

命名规范#

为了保持博客内容的整洁有序，建议按照以下规范命名文件和文件夹。所有文件名和文件夹名建议使用中文，与各功能模块的语义相匹配。

概览#

功能模块	存放路径	命名建议	示例	子文件夹
文章	`src/content/posts/`	按主题分类的子文件夹 + 文章标题	`技术/Java基础.md`、`生活/第一次旅行.md`	✅ 支持
日常动态	`src/content/moments/`	日期格式	`2026-04-20.md`	❌ 不支持
运动记录	`src/content/life/health/workout/`	日期格式	`2026-04-20.md`	❌ 不支持
睡眠记录	`src/content/life/health/sleep/`	日期格式	`2026-04-20.md`	❌ 不支持
饮食记录	`src/content/life/health/food/`	日期格式或描述性名称	`2026-04-20.md`、`健康早餐.md`	❌ 不支持
奇思妙想	`src/content/life/ideas/`	简短描述性标题	`晨跑计划.md`、`新项目想法.md`	❌ 不支持
打卡项目	`src/content/life/checkin/`	习惯/目标名称	`每日阅读.md`、`早睡早起.md`、`喝水提醒.md`	❌ 不支持
日常规划	`src/content/life/routines/`	规划类型或时间	`晨间习惯.md`、`晚间安排.md`、`周末计划.md`	❌ 不支持
去过的地方	`src/content/life/places/`	地点名称	`成都.md`、`杭州西湖.md`、`公司.md`	❌ 不支持
笔记本	`src/content/life/notebooks/`	笔记本类型（文件夹） + 日期（条目）	`日记/2026-04-20.md`、`读书笔记/2026-04.md`	✅ 本身就是文件夹
番组计划	`src/content/bangumi/`	按类型分子文件夹 + 作品名称	`anime/进击的巨人.md`、`book/人类简史.md`	✅ 支持

子文件夹分类说明#

功能模块	是否支持子文件夹	说明
文章 (posts)	✅ 支持	可以按主题/分类创建子文件夹，子文件夹名称即为分类
日常动态 (moments)	❌ 不支持	建议扁平化管理，所有动态文件直接放在 `moments/` 目录
运动记录 (workout)	❌ 不支持	建议按日期命名，扁平化管理
睡眠记录 (sleep)	❌ 不支持	建议按日期命名，扁平化管理
饮食记录 (food)	❌ 不支持	建议按日期或简短描述命名，扁平化管理
奇思妙想 (ideas)	❌ 不支持	建议扁平化管理，用标题区分不同想法
打卡项目 (checkin)	❌ 不支持	每个文件代表一个打卡项目，扁平化管理
日常规划 (routines)	❌ 不支持	建议扁平化管理，每个规划一个文件
去过的地方 (places)	❌ 不支持	建议扁平化管理，每个地点一个文件
笔记本 (notebooks)	✅ 本身就是文件夹	每个笔记本是一个文件夹，条目放在各自的文件夹内
番组计划 (bangumi)	✅ 支持	建议按类型创建子文件夹：anime、book、music、game、real

详细说明#

图例说明:

✅ 支持子文件夹分类

❌ 不支持子文件夹（建议扁平化管理）

1. 文章 (posts) ✅ 支持子文件夹分类#

命名建议: 子文件夹按主题/分类命名，文件名使用文章标题。

1
posts/
2
├── 技术/
3
│   ├── Java基础.md
4
│   ├── Docker入门.md
5
│   └── 算法笔记.md
6
├── 生活/
7
│   ├── 第一次旅行.md
8
│   └── 养猫日记.md
9
├── 英语学习/
10
│   ├── 背单词方法.md
11
│   └── 语法笔记.md
12
└── 随笔/
13
    └── 关于成长.md

说明:

子文件夹名称代表文章分类

文件名使用文章的实际标题，便于识别内容

避免使用 1.md、a.md 等无意义名称

2. 日常动态 (moments) ❌ 不支持子文件夹#

命名建议: 使用日期格式 YYYY-MM-DD.md。

1
moments/
2
├── 2026-04-20.md    # 4月20日的动态
3
├── 2026-04-19.md    # 4月19日的动态
4
└── 2026-04-18.md    # 4月18日的动态

说明:

每条动态对应一天的记录

日期格式便于按时间排序和查找

文件名只作为元数据，实际内容在 frontmatter 的 published 字段指定

不支持子文件夹分类，所有动态文件直接放在 moments/ 目录下

3. 健康记录#

命名建议: 使用日期格式或简短的描述性名称。

运动记录 (workout)#

1
workout/
2
├── 2026-04-20.md    # 4月20日的运动
3
├── 2026-04-18.md    # 4月18日的运动
4
└── 2026-04-15.md    # 4月15日的运动

说明:

主要按日期命名，因为每天可能有多次运动记录

如果一天有多次不同运动，可用简短描述: 2026-04-20-晨跑.md、2026-04-20-健身房.md

睡眠记录 (sleep)#

1
sleep/
2
├── 2026-04-20.md    # 4月20日晚的睡眠
3
├── 2026-04-19.md    # 4月19日晚的睡眠
4
└── 2026-04-18.md    # 4月18日晚的睡眠

说明:

睡眠记录按日期命名，指当天晚上的睡眠

通常每天一条记录

饮食记录 (food)#

1
food/
2
├── 2026-04-20.md    # 4月20日的饮食
3
├── 健康早餐.md        # 健康早餐记录
4
└── 节日大餐.md        # 特殊日期的饮食

说明:

日常饮食按日期命名

特殊的饮食记录可用描述性名称

4. 奇思妙想 (ideas) ❌ 不支持子文件夹#

命名建议: 简短描述想法内容，不要超过20个字。

1
ideas/
2
├── 晨跑计划.md        # 关于晨跑的想法
3
├── 学习新语言.md       # 关于学外语的想法
4
├── 开发独立博客.md     # 关于做博客的想法
5
└── 每周一本书.md      # 关于阅读的想法

说明:

想法名称应简洁明了，概括核心内容

不需要包含日期，因为有 createdAt 字段记录创建时间

已完成的想法会在侧边栏显示，使用有意义的名称很重要

5. 打卡记录 (checkin) ❌ 不支持子文件夹#

命名建议: 使用习惯/目标名称。

1
checkin/
2
├── 每日阅读.md        # 阅读打卡
3
├── 早睡早起.md         # 作息打卡
4
├── 每日喝水.md         # 喝水打卡
5
├── 运动健身.md         # 运动打卡
6
└── 单词背诵.md         # 学习打卡

说明:

文件名就是打卡项目的名称

一次打卡代表一个习惯/目标

打卡记录保存在 frontmatter 的 checkins 数组中

6. 日常规划 (routines) ❌ 不支持子文件夹#

命名建议: 按时间段或规划类型命名。

1
routines/
2
├── 晨间习惯.md         # 早晨的例行安排
3
├── 午休安排.md         # 午休时间规划
4
├── 晚间习惯.md         # 晚上的例行安排
5
├── 周末计划.md         # 周末活动规划
6
└── 学习计划.md         # 学习时间安排

说明:

规划代表一种例程或习惯模板

可以按一天中的时间段或按功能分类

文件名应体现规划的用途

7. 去过的地方 (places) ❌ 不支持子文件夹（可选支持）#

命名建议: 使用地点名称。

1
places/
2
├── 成都.md             # 成都旅行
3
├── 杭州西湖.md          # 西湖游玩
4
├── 公司.md              # 公司位置
5
├── 北京.md              # 北京出差
6
└── 故宫.md              # 故宫参观

说明:

可以是城市、地点或具体景点

如果同一地点去过多次，可以只创建一个文件，通过 visitCount 和正文记录每次

不建议使用子文件夹，建议扁平化管理，每个地点一个文件

8. 笔记本 (notebooks) ✅ 支持子文件夹分类（本身就是文件夹结构）#

命名建议: 笔记本（文件夹）按类型命名，条目（md文件）按日期或主题命名。

1
notebooks/
2
├── 日记/
3
│   ├── _index.md        # 日记本配置
4
│   ├── 2026-04-20.md    # 4月20日的日记
5
│   ├── 2026-04-19.md    # 4月19日的日记
6
│   └── 2026-04-18.md   # 4月18日的日记
7
├── 读书笔记/
8
│   ├── _index.md        # 读书笔记配置
9
│   ├── 2026-04-20.md    # 某本书的笔记
10
│   └── 2026-04-15.md    # 另一本书的笔记
11
├── 学习笔记/
12
│   ├── _index.md
13
│   └── 2026-04.md       # 4月的学习汇总
14
└── 工作日志/
15
    ├── _index.md
16
    └── 2026-04-20.md    # 4月20日的工作记录

显示更多显示更少

说明:

笔记本是文件夹，每个笔记本可以有多个条目

笔记本名称应体现用途: 日记、读书笔记、工作日志、灵感记录

条目按日期命名，保持时间顺序

每个笔记本文件夹内必须有 _index.md 文件定义笔记本配置

9. 番组计划 (bangumi) ✅ 支持子文件夹分类#

命名建议: 按类型分子文件夹，文件名使用作品名称。

1
bangumi/
2
├── anime/              # 动画
3
│   ├── 进击的巨人.md
4
│   ├── 鬼灭之刃.md
5
│   └── 咒术回战.md
6
├── book/               # 书籍
7
│   ├── 人类简史.md
8
│   └── 活着.md
9
├── music/              # 音乐
10
│   ├── 周杰伦专辑.md
11
│   └── 泰勒专辑.md
12
├── game/               # 游戏
13
│   ├── 王者荣耀.md
14
│   └── 原神.md
15
└── real/               # 影视
16
    ├── 肖申克的救赎.md
17
    ├── 泰坦尼克号.md
18
    └── 盗梦空间.md

显示更多显示更少

说明:

子文件夹按作品类型划分: anime、book、music、game、real

文件名使用作品名称（中文名优先）

同一作品只创建一个文件，通过 frontmatter 字段记录状态变化

命名原则总结#

语义化: 名称应准确反映内容含义
简洁: 避免过长的名称，但也不要过于简短（如 a.md、1.md）
一致性: 相同类型的内容保持相同的命名风格
中文优先: 推荐使用中文命名，与功能模块的语义匹配
避免特殊字符: 不要在名称中使用 :、/、\、*、? 等特殊字符

文章系统 (posts)#

路径#

src/content/posts/

创建文章#

在 src/content/posts/ 下创建 .md 或 .mdx 文件：

1
---
2
title: 我的第一篇文章
3
published: 2026-04-18
4
description: 这是文章描述
5
tags:
6
  - 标签1
7
  - 标签2
8
category: 分类名称
9
pinned: false
10
image: https://example.com/cover.jpg
11
---
12

13
文章正文内容...

字段说明#

字段	类型	必填	默认值	说明
`title`	string	是	-	文章标题，显示在页面标题和列表中
`published`	string/Date	是	-	发布日期，格式 YYYY-MM-DD
`description`	string	否	-	文章描述，显示在列表页的卡片摘要中
`tags`	string[]	否	[]	标签数组，用于文章分类和筛选
`category`	string	否	-	分类名称，用于按分类展示文章
`pinned`	boolean	否	false	是否置顶，置顶文章会显示在列表最前面
`image`	string	否	-	封面图 URL，建议尺寸 1200x630
`draft`	boolean	否	false	是否为草稿，草稿不会显示在列表中
`comment`	boolean	否	true	是否开启评论，设为 false 则禁用评论
`updated`	string/Date	否	-	最后更新日期，显示在文章底部

子目录#

支持在 posts/ 下创建子目录组织文章：

1
posts/
2
├── 技术/
3
│   └── docker.md
4
├── 生活/
5
│   └── daily.md
6
└── 示例.md

子目录名称会自动作为分类使用，如上面的文章会属于”技术”或”生活”分类。

日常动态 (moments)#

路径#

src/content/moments/

创建动态#

在 src/content/moments/ 下创建 .md 文件：

1
---
2
author: 团子和蛋糕
3
avatar: https://example.com/avatar.jpg
4
published: 2026-04-18
5
images: photo1.jpg, photo2.jpg, photo3.jpg
6
tags:
7
  - 日常
8
location: 上海
9
device: iPhone 15 Pro
10
---
11

12
动态正文内容...

注意：images 字段使用逗号分隔的字符串格式，不使用数组。

字段说明#

字段	类型	必填	默认值	说明
`author`	string	否	siteConfig.author	作者名称，显示在动态卡片上
`avatar`	string	否	siteConfig.avatar	头像 URL
`published`	string/Date	是	-	发布时间，用于排序和显示
`images`	string	否	-	图片路径，逗号分隔（注意不是数组），图片放在 `public/images/moments/` 目录
`tags`	string[]	否	[]	标签数组
`location`	string	否	-	地点名称
`device`	string	否	-	设备信息，如 “iPhone 15 Pro”

图片使用#

将图片放入 public/images/moments/ 目录
在 frontmatter 中使用文件名引用：images: photo1.jpg, photo2.jpg
支持 jpg、png、gif、webp 格式

生活记录 (life)#

生活记录是本博客的核心功能，包括健康追踪、想法管理、打卡、规划等多个模块。

健康记录 ❌ 不支持子文件夹（建议扁平化管理）#

健康记录包含三个子模块：运动、睡眠、饮食，都在 src/content/life/health/ 下。

运动 (workout)#

路径: src/content/life/health/workout/

1
---
2
date: 2026-04-18
3
workoutType: 户外跑步
4
runKm: 5.2
5
workoutMinutes: 30
6
stepsToday: 8000
7
heartRateAvg: 135
8
caloriesBurned: 320
9
---
10

11
今天跑步感觉不错，跑完了感觉很轻松。

字段	类型	必填	默认值	说明
`date`	string/Date	是	-	运动日期
`workoutType`	string	否	锻炼	运动类型，如 “户外跑步”、“健身房力量训练”、“游泳” 等
`runKm`	number	否	0	跑步距离（公里），用于统计总跑量和月度跑量
`workoutMinutes`	number	否	0	运动时长（分钟）
`stepsToday`	number	否	0	当日步数
`heartRateAvg`	number	否	-	平均心率
`caloriesBurned`	number	否	-	消耗卡路里

睡眠 (sleep)#

路径: src/content/life/health/sleep/

1
---
2
date: 2026-04-17
3
sleepHours: 7.5
4
sleepQuality: 4
5
wakeUpCount: 1
6
notes: 晚上喝水太多，中间起来上厕所了一次
7
---
8

9
记录一下今天的睡眠情况。

字段	类型	必填	默认值	说明
`date`	string/Date	是	-	睡眠日期（指当晚的睡眠）
`sleepHours`	number	是	-	睡眠时长（小时），用于计算平均睡眠时间
`sleepQuality`	number	否	3	睡眠质量评分，1-5 分，5 分最好
`wakeUpCount`	number	否	0	夜间醒来次数
`notes`	string	否	-	备注说明

饮食 (food)#

路径: src/content/life/health/food/

1
---
2
date: 2026-04-18
3
allowedFoods:
4
  - 西兰花
5
  - 鸡胸肉
6
  - 糙米饭
7
avoidFoods:
8
  - 奶茶
9
  - 炸鸡
10
breakfast: 燕麦粥 + 鸡蛋
11
lunch: 沙拉 + 全麦面包
12
dinner: 清蒸鱼 + 蔬菜
13
snacks: 坚果一小把
14
notes: 今天控制得不错，只吃了坚果作为零食
15
---
16

17
记录今天的饮食情况。

显示更多显示更少

字段	类型	必填	默认值	说明
`date`	string/Date	是	-	记录日期
`allowedFoods`	string[]	否	[]	推荐/计划吃的食物列表
`avoidFoods`	string[]	否	[]	需要避免的食物列表
`breakfast`	string	否	-	早餐内容
`lunch`	string	否	-	午餐内容
`dinner`	string	否	-	晚餐内容
`snacks`	string	否	-	零食记录
`notes`	string	否	-	备注说明

奇思妙想#

想法/点子管理，用于记录突然的想法、计划、目标等。

路径: src/content/life/ideas/

1
---
2
title: 晨跑计划
3
content: 每天早上6点起床跑步30分钟
4
createdAt: 2026-04-01
5
completedAt: 2026-04-10
6
label: 健康
7
priority: high
8
---
9

10
详细描述我的晨跑计划，包括目标、具体安排等。

字段	类型	必填	默认值	说明
`title`	string	否	-	想法标题，简短概括
`content`	string	是	-	想法内容，详细描述
`createdAt`	string/Date	是	-	创建时间，用于排序
`completedAt`	string/Date	否	-	完成时间。有值表示已完成，无值表示待完成
`label`	string	否	-	标签/分类，如 “健康”、“工作”、“学习”
`priority`	string	否	normal	优先级：high、normal、low

完成判断逻辑#

系统通过 completedAt 字段判断想法是否完成：

已完成: completedAt 有值（日期）
待完成: completedAt 为空

不需要设置 status 字段。

打卡记录#

用于追踪习惯养成和日常打卡。

路径: src/content/life/checkin/

1
---
2
name: 早睡早起
3
description: 23点前入睡，7点前起床
4
checkins:
5
  - 2026-04-01
6
  - 2026-04-02
7
  - 2026-04-03
8
  - 2026-04-04
9
---
10

11
养成健康的作息习惯，保持充沛精力。

字段说明#

字段	类型	必填	默认值	说明
`name`	string	是	-	打卡项目名称，如 “每日阅读”、“早起”、“喝水”
`description`	string	否	-	项目描述，说明打卡规则
`checkins`	string[]	否	[]	打卡日期数组，格式 YYYY-MM-DD
`$schema`	string	否	-	JSON Schema 标识

打卡说明#

打卡方式: 在 checkins 数组中添加日期字符串即可
日期格式: 使用 YYYY-MM-DD 格式
每次打卡: 在数组中添加一个新的日期条目
排序: 系统会自动按日期排序显示

示例：添加新打卡#

当完成一次打卡后，在 checkins 数组中添加新日期：

1
checkins:
2
  - 2026-04-01
3
  - 2026-04-02
4
  - 2026-04-03
5
  # 添加新打卡
6
  - 2026-04-21

日常规划#

用于规划和安排日常作息、习惯养成计划等。

路径: src/content/life/routines/

1
---
2
name: 晨跑计划
3
time: 早晨 6:30-7:30
4
icon: 🏃
5
color: "#22c55e"
6
description: 每天早上进行30分钟有氧运动
7
updatedAt: 2026-04-18
8
---
9

10
## 目标
11

12
保持健康的身体状态，提高一天的精力。
13

14
## 具体安排
15

16
1. 热身 5 分钟
17
2. 慢跑 20 分钟
18
3. 拉伸 5 分钟

显示更多显示更少

字段	类型	必填	默认值	说明
`name`	string	是	-	规划名称
`time`	string	否	-	时间安排描述，如 “早晨 6:30-7:30”、“晚上 10:00”
`icon`	string	否	📋	图标 emoji
`color`	string	否	-	主题色，十六进制格式
`description`	string	否	-	简短描述
`updatedAt`	string/Date	否	-	最后更新时间

正文内容支持 Markdown 格式，可以详细描述计划内容、目标、具体安排等。

去过的地方#

记录旅行足迹和到访过的地点。

路径: src/content/life/places/

1
---
2
province: 四川省
3
city: 成都
4
district: 武侯区
5
date: 2026-04-10
6
visitCount: 3
7
experience: 美食之城，非常喜欢这里的火锅和串串
8
highlights:
9
  - 春熙路
10
  - 太古里
11
  - 武侯祠
12
photos:
13
  - Chengdu_1.jpg
14
  - Chengdu_2.jpg
15
---
16

17
成都之旅记录，这次是第三次来成都了。

显示更多显示更少

字段	类型	必填	默认值	说明
`province`	string	是	-	省份/直辖市/自治区
`city`	string	是	-	城市名称
`district`	string	否	-	区县/城区（可选）
`date`	string/Date	是	-	到访日期
`visitCount`	number	否	1	到访次数，第几次来这个城市
`experience`	string	否	-	整体体验/感受
`highlights`	string[]	否	[]	亮点/推荐地点列表
`photos`	string[]	否	[]	照片文件名，存放在 `public/images/places/`
`rating`	number	否	-	评分 1-5

正文内容支持 Markdown，可以详细记录旅行见闻。

笔记本#

笔记本功能用于创建个人日记本，每个笔记本是一个文件夹。

路径: src/content/life/notebooks/

创建步骤#

在 src/content/life/notebooks/ 下创建文件夹
在文件夹内创建 _index.md 或 _index.json 文件定义笔记本
在文件夹内创建 .md 文件作为日记条目

目录结构#

1
notebooks/
2
└── 日记/
3
    ├── _index.md          # 笔记本配置
4
    ├── 2026-04-18.md      # 日记条目
5
    ├── 2026-04-17.md
6
    └── 2026-04-16.md

_index.md 配置#

1
---
2
name: 日记
3
cover: diary-cover.jpg
4
summary: 记录每天的生活点滴
5
color: "#ec4899"
6
icon: 📖
7
---
8

9
这里是笔记本的详细描述...

字段	类型	必填	默认值	说明
`name`	string	是	-	笔记本名称
`cover`	string	否	-	封面图片
`summary`	string	否	-	笔记本简介
`color`	string	否	-	主题色
`icon`	string	否	📔	图标 emoji

日记条目内容#

1
---
2
date: 2026-04-18
3
name: 今天很开心
4
mood: happy
5
weather: sunny
6
tags:
7
  - 日常
8
---
9

10
今天发生了一些有趣的事情...
11

12
## 今天做了什么
13

14
- 上午去了图书馆
15
- 下午和朋友一起喝咖啡
16
- 晚上看了部电影
17

18
## 感想
19

20
今天过得很充实！

显示更多显示更少

字段	类型	必填	默认值	说明
`date`	string/Date	是	-	日记日期
`name`	string	否	文件名	日记标题/名称，用于在列表中显示
`mood`	string	否	-	心情/情绪
`weather`	string	否	-	天气
`tags`	string[]	否	[]	标签

正文使用 Markdown 格式书写日记内容。

番组计划 (bangumi)#

用于记录动漫、书籍、音乐、游戏、影视的观看/阅读/游玩进度。

路径: src/content/bangumi/

支持 .md, .yaml, .yml 格式：

1
---
2
title: 攻壳机动队
3
name_cn: 攻壳机动队 Stand Alone Complex
4
category: anime
5
status: 2
6
image: https://example.com/cover.jpg
7
link: https://bgm.tv/subject/1
8
score: 10
9
tags:
10
  - 科幻
11
  - 神作
12
  - 赛博朋克
13
published: 2026-01-01
14
finishDate: 2026-01-15
15
episodes: 26
16
comments: 最喜欢的动画没有之一
17
---
18

19
关于这部作品的详细评论和感想...

显示更多显示更少

通用字段#

字段	类型	必填	默认值	说明
`title`	string	是	-	作品标题（英文/原名）
`name_cn`	string	否	-	中文名称
`category`	string	否	anime	作品类型
`status`	number	否	2	状态代码（1-5）
`image`	string	是	-	封面图 URL
`link`	string	是	-	Bangumi 链接
`score`	number	否	-	个人评分 1-10
`tags`	string[]	否	[]	标签
`published`	string/Date	否	-	作品发布年份/日期
`comment`	string	否	-	简短评论

status 状态码#

值	状态	说明
1	想看	想要观看/阅读/游玩
2	看过	已完成观看/阅读/游玩
3	在看	正在观看/阅读/游玩
4	搁置	暂时搁置
5	抛弃	放弃

category 类型#

值	类型	说明
anime	动画	番剧、剧场版、OVA
book	书籍	小说、漫画、杂志
music	音乐	专辑、单曲
game	游戏	电子游戏、桌游
real	影视	电影、电视剧、纪录片

分类专属字段#

anime 动画:

字段	类型	说明
`episodes`	number	总集数
`duration`	string	单集时长，如 “24min”

book 书籍:

字段	类型	说明
`author`	string	作者
`pages`	number	总页数

game 游戏:

字段	类型	说明
`platform`	string	平台，如 “PC”, “Switch”, “PS5”
`playTime`	number	游玩时长（小时）

侧边栏组件#

侧边栏组件在 src/config/sidebarConfig.ts 中配置。

可用组件#

组件	说明
`profile`	用户资料卡片，显示头像、名称、简介
`announcement`	公告通知
`music`	音乐播放器（需要音乐服务配置）
`categories`	文章分类列表
`tags`	标签云
`lifeStats`	生活统计数据面板
`relationship`	恋爱/纪念日计时器
`quoteOfTheDay`	今日一言/随机语录
`recentItems`	最近更新的文章列表
`stats`	站点统计（文章数、字数等）
`calendar`	更新日历
`sidebarToc`	文章目录（仅文章页显示）
`siteHeatmap`	更新热力图
`advertisement`	广告位（可放置自定义内容）

组件配置#

1
{
2
  type: "组件名称",
3
  enable: true,           // 是否启用
4
  position: "sticky",     // 布局位置：sticky(粘性)、normal(普通流)
5
  showOnPostPage: true,   // 是否在文章页显示
6
  showOnNonPostPage: true, // 是否在非文章页显示
7
  // 其他组件特定配置...
8
}

各组件配置详情#

profile#

1
{
2
  type: "profile",
3
  enable: true,
4
  position: "sticky",
5
  showOnPostPage: false,
6
  showOnNonPostPage: true,
7
}

lifeStats#

1
{
2
  type: "lifeStats",
3
  enable: true,
4
  position: "normal",
5
  showOnPostPage: false,
6
  showOnNonPostPage: true,
7
}

relationship#

1
{
2
  type: "relationship",
3
  enable: true,
4
  position: "sticky",
5
  showOnPostPage: false,
6
  showOnNonPostPage: true,
7
  startDate: "2020-01-01", // 纪念日日期
8
  label: "在一起",         // 显示标签
9
}

quoteOfTheDay#

1
{
2
  type: "quoteOfTheDay",
3
  enable: true,
4
  position: "normal",
5
  showOnPostPage: true,
6
  showOnNonPostPage: true,
7
  source: "hitokoto", // 语录来源：hitokoto(一言 API) 或 local(本地配置)
8
}

calendar#

1
{
2
  type: "calendar",
3
  enable: true,
4
  position: "normal",
5
  showOnPostPage: false,
6
  showOnNonPostPage: true,
7
}

评论系统#

博客使用 Waline 作为评论系统。

评论配置#

在 src/config/siteConfig.ts 中配置 Waline：

1
comment: {
2
  waline: {
3
    serverURL: "https://your-server.vercel.app",
4
    lang: "zh-CN",
5
  }
6
}

字段说明#

字段	类型	必填	说明
`serverURL`	string	是	Waline 服务地址
`lang`	string	否	语言设置

评论启用位置#

评论功能在以下位置可用：

文章详情页: 默认开启，可通过 frontmatter comment: false 关闭
日常动态页: /moments/ 页面默认开启
留言板: /guestbook/ 页面

配置文件#

siteConfig.ts#

主要配置文件，位于 src/config/siteConfig.ts

配置项	类型	说明
`title`	string	站点标题，显示在浏览器标签和首页
`description`	string	站点描述，用于 SEO
`author`	string	作者名称
`avatar`	string	默认头像 URL
`themeColor`	object	主题色配置
`themeColor.hue`	number	色调 0-360
`themeColor.saturation`	number	饱和度 0-100
`navbar`	array	顶部导航栏配置
`favicon`	string	网站图标路径
`pages`	object	页面开关
`pages.sponsor`	boolean	是否启用赞助页面
`pages.guestbook`	boolean	是否启用留言板
`pages.bangumi`	boolean	是否启用番组计划
`postListLayout`	string	文章列表布局：grid、list、masonry
`pagination`	object	分页配置
`mapConfig`	object	地图配置（高德地图 API）
`comment`	object	评论系统配置

navBarConfig.ts#

导航栏配置文件，位于 src/config/navBarConfig.ts

1
[
2
  { name: "首页", url: "/" },
3
  { name: "文章", url: "/posts/" },
4
  { name: "生活", url: "/life/" },
5
  {
6
    name: "工具",
7
    url: "/tools/",
8
    children: [  // 下拉菜单
9
      { name: "工具1", url: "/tools/tool1/" },
10
      { name: "工具2", url: "/tools/tool2/" },
11
    ]
12
  },
13
]

常见问题#

Q: 如何禁用某个页面？#

在 siteConfig.ts 中修改 pages 配置：

1
pages: {
2
  sponsor: false,    // 禁用赞助页
3
  guestbook: false,  // 禁用留言板
4
  bangumi: false,    // 禁用番组页
5
}

Q: 如何添加自定义页面？#

在 src/pages/ 下创建新的 .astro 文件
使用现有的 Layout 组件包装内容
在 navBarConfig.ts 中添加导航链接

Q: 如何修改主题色？#

在 siteConfig.ts 中修改 themeColor.hue 值（0-360）：

1
themeColor: {
2
  hue: 200,  // 蓝色调
3
  saturation: 70,
4
}

Q: 如何添加新内容类型？#

在 src/content/ 下创建新的文件夹
创建对应的 schema 定义（可选）
在 src/pages/ 下创建展示页面
更新导航配置

Q: 图片应该放在哪里？#

文章/生活记录图片: 直接放在正文中，图片放入 public/images/ 目录
生活记录图片:
- moments: public/images/moments/
- places: public/images/places/
笔记本图片: 放入 public/images/notebooks/

更新日志#

2026-04-21: 新增相册(Album)、导航(Daohang)、弹幕(Danmu)、特殊页面(Spec)功能说明；更新打卡记录的正确格式；补充高级功能章节
2026-04-20: 新增命名规范章节，详细说明各功能模块的文件和文件夹命名建议；新增子文件夹分类说明，明确标注哪些功能支持子文件夹分类
2026-04-18: 完善文档，添加所有字段详细说明
2026-04-10: 添加番组计划详细说明
2026-04-01: 初始版本

相册 (Album)#

用于展示照片集，以精美的拍立得风格呈现。

路径: src/content/album/

创建相册#

1
---
2
title: 2026年春天
3
subtitle: 记录春日里的美好时光
4
date: 2026-04-01
5
location: 郑州
6
cover: https://example.com/cover.jpg
7
tags:
8
  - 春天
9
  - 户外
10
photos:
11
  - src: https://example.com/photo1.jpg
12
    alt: 樱花盛开
13
    caption: 校园里的樱花开了
14
  - src: https://example.com/photo2.jpg
15
    alt: 踏青
16
    caption: 和朋友一起去踏青
17
---
18

19
2026年的春天，记录下每一个美好的瞬间。

显示更多显示更少

字段说明#

字段	类型	必填	默认值	说明
`title`	string	是	-	相册标题
`subtitle`	string	否	-	副标题/描述
`date`	string/Date	是	-	相册日期
`location`	string	否	-	拍摄地点
`cover`	string	否	-	封面图 URL
`tags`	string[]	否	[]	标签数组
`photos`	array	是	[]	照片数组
`draft`	boolean	否	false	是否为草稿

photos 数组项#

photos 支持两种格式：

简单格式（仅 URL）:

1
photos:
2
  - https://example.com/photo1.jpg
3
  - https://example.com/photo2.jpg

完整格式（带元数据）:

1
photos:
2
  - src: https://example.com/photo1.jpg
3
    alt: 照片描述
4
    caption: 照片说明/标题

照片数量显示#

相册卡片会根据照片数量显示不同的堆叠效果：

3张及以上: 显示三层拍立得堆叠效果
2张: 显示两层错位效果
1张: 显示单张照片
超过3张: 在顶层照片显示 “+N” 徽章

导航 (Daohang)#

用于展示常用网站链接和工具导航，支持分类管理和特色推荐。

路径: src/content/daohang/

创建导航项#

1
---
2
name: Cloudflare
3
url: https://dash.cloudflare.com/
4
icon: material-symbols:cloud
5
description: 全球CDN与网络安全服务
6
category: 常用网站
7
tags: [云服务, CDN]
8
color: "#f97316"
9
image: https://example.com/icon.png
10
featured: true
11
order: 10
12
---
13

14
网站CDN加速、DNS管理、安全防护一站式平台。

字段说明#

字段	类型	必填	默认值	说明
`name`	string	是	-	网站/工具名称
`url`	string	是	-	网站链接
`icon`	string	否	-	Material Symbols 图标名
`description`	string	否	-	简短描述
`category`	string	否	未分类	分类名称
`tags`	string[]	否	[]	标签数组
`color`	string	否	-	主题色（十六进制）
`image`	string	否	-	自定义图标/图片
`featured`	boolean	否	false	是否推荐展示
`order`	number	否	0	排序权重，数字越小越靠前

Icon 图标使用#

可以使用 Material Symbols 图标库：

1
icon: material-symbols:home-outline
2
icon: material-symbols:cloud
3
icon: material-symbols:code

访问 Material Symbols 查看可用图标。

命名规范#

导航项建议使用数字前缀进行排序：

1
daohang/
2
├── 01-tuanzi-email.md      # 第1个分类下的第1个
3
├── 02-tuanzi-photo.md      # 第2个
4
├── 10-cloudflare.md         # 第10个分类
5
├── 20-emoji-dict.md
6
├── 30-image-converter.md
7
├── 40-fomalhaut.md
8
├── 41-haiyong.md
9
├── 42-moewah.md
10
├── 50-qwerty-learner.md
11
├── 60-firefly-docs.md
12
├── 70-maptiler.md

弹幕 (Danmu)#

留言板功能，用户可以在留言板上发送弹幕风格的留言。

路径: src/content/danmu/

发送弹幕#

1
---
2
nickname: 小明
3
avatar: https://example.com/avatar.jpg
4
time: 2026-04-18
5
---
6

7
保持热爱，奔赴山海

字段说明#

字段	类型	必填	默认值	说明
`nickname`	string	是	-	留言者昵称
`avatar`	string	否	默认头像	头像 URL
`time`	string	否	-	留言时间

正文内容为弹幕显示的文字。

特殊页面 (Spec)#

特殊内容页面，包括关于、关于我、友链、项目推荐、留言板等。

路径: src/content/spec/

1. 关于页面 (about.md)#

1
---
2
title: 关于我
3
description: 个人介绍页面
4
---
5

6
# 关于我 / About Me
7

8
你好！我是 **团子和蛋糕**，一个在数字世界中默默无闻的一片叶子。
9

10
## 联系方式
11

12
- GitHub: [链接](https://github.com/xxx)
13
- Email: [邮箱](mailto:example@example.com)

2. 友链页面 (friends.md)#

1
---
2
title: 友情链接
3
description: 与优秀的朋友们一起成长
4
---
5

6
## 友链信息
7

8
站点名称: 团子和蛋糕
9
站点链接: https://blog.example.com
10
头像链接: https://example.com/avatar.jpg
11

12
## 申请方式
13

14
请将网站信息发送邮件至：xxx@example.com

3. 项目推荐 (projects.md)#

1
---
2
title: 常用网站
3
description: 精选优质开源项目和工具
4
---
5

6
## 推荐说明
7

8
这里收集了我日常使用的优质项目和工具。

4. 留言板 (guestbook.md)#

1
---
2
title: 留言板
3
description: 在这里留下你的足迹
4
---
5

6
- 请保持友善和尊重
7
- 欢迎分享你的想法

文章进阶功能#

高级功能#

博客支持多种高级功能，可以在文章中灵活使用：

1. 代码块主题#

使用 code shortcode 指定代码块语言和标题：

1
{% raw %}{% code "javascript" %}
2
const greeting = "Hello World";
3
{% /code %}{% endraw %}

2. 提醒块 (Callouts)#

支持多种主题的提醒块：

1
> [!NOTE]
2
> 这是一条普通笔记
3

4
> [!TIP]
5
> 这是一条提示
6

7
> [!WARNING]
8
> 这是一条警告
9

10
> [!CAUTION]
11
> 这是一条危险警告

主题类型：github、obsidian、vitepress（在 siteConfig.ts 中配置 rehypeCallouts.theme）

3. GitHub 卡片#

嵌入 GitHub 仓库信息：

1
{% raw %}{% github repo="CuteLeaf/Firefly" %}{% endraw %}

4. 嵌入组件#

支持嵌入多种内容类型：

音乐播放器
视频
幻灯片
CodePen 等

5. 公式支持#

支持 LaTeX 数学公式：

行内公式： $E = mc^2$

块级公式：

1
$$
2
\int_{0}^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
3
$$

6. 图片灯箱#

图片支持点击放大查看，使用 Fancybox 效果。

7. 自定义标题样式#

1
## 普通标题
2
### 带图标标题

文章置顶#

在 frontmatter 中设置 pinned: true 可以置顶文章，置顶文章会显示在列表最前面。

文章系列#

可以通过标签来组织系列文章：

1
tags:
2
  - Java基础
3
  - 系列:集合

自定义上/下篇#

在 frontmatter 中手动指定上下篇文章：

1
prevTitle: 上一篇文章标题
2
prevSlug: 上一篇文章的slug
3
nextTitle: 下一篇文章标题
4
nextSlug: 下一篇文章的slug

许可证设置#

1
licenseName: CC BY-NC-SA 4.0
2
licenseUrl: https://creativecommons.org/licenses/by-nc-sa/4.0/

高级功能配置#

许可证配置 (licenseConfig.ts)#

1
export const licenseConfig = {
2
  enable: true,
3
  default: {
4
    name: "CC BY-NC-SA 4.0",
5
    url: "https://creativecommons.org/licenses/by-nc-sa/4.0/",
6
  },
7
};

公告配置 (announcementConfig.ts)#

1
export const announcementConfig = {
2
  enable: true,
3
  // 可以是字符串或字符串数组
4
  content: "欢迎来到我的博客！",
5
};

背景壁纸 (backgroundWallpaper.ts)#

1
export const backgroundWallpaper = {
2
  enable: true,
3
  url: "https://example.com/bg.jpg",
4
};

看板娘 (pioConfig.ts)#

1
export const pioConfig = {
2
  enable: false,
3
  model: "pxl化模型",
4
  apiVersion: 34,
5
  hidden: false,
6
};

Live2D 模型 (featureConfig.ts)#

1
export const featureConfig = {
2
  live2d: {
3
    enable: false,
4
    model: {
5
      // Live2D 模型配置
6
    },
7
  },
8
};

音乐播放器 (musicConfig.ts)#

1
export const musicConfig = {
2
  enable: false,
3
  server: "tencent",  // netease, tencent, xiami, kugou
4
  id: "歌曲ID",
5
  type: "song",  // song, playlist, album
6
};

头像配置 (profileConfig.ts)#

1
export const profileConfig = {
2
  enable: true,
3
  avatar: "https://example.com/avatar.jpg",
4
  name: "团子和蛋糕",
5
  bio: "在数字世界中默默无闻的一片叶子",
6
  socials: [
7
    { name: "GitHub", url: "https://github.com/xxx" },
8
    { name: "Email", url: "mailto:xxx@example.com" },
9
  ],
10
};

赞助配置 (sponsorConfig.ts)#

1
export const sponsorConfig = {
2
  enable: true,
3
  title: "赞助作者",
4
  description: "如果觉得博客对你有帮助，可以请作者喝杯咖啡~",
5
  methods: [
6
    {
7
      name: "微信支付",
8
      image: "/images/sponsor/wechat.png",
9
    },
10
    {
11
      name: "支付宝",
12
      image: "/images/sponsor/alipay.png",
13
    },
14
    {
15
      name: "爱发电",
16
      image: "/images/sponsor/afdian.png",
17
    },
18
  ],
19
};

显示更多显示更少

关系计时器 (relationshipConfig.ts)#

1
export const relationshipConfig = {
2
  enable: true,
3
  startDate: "2020-01-01",  // 纪念日日期
4
  label: "在一起",           // 显示标签
5
  updateInterval: 3600000,   // 更新间隔（毫秒）
6
};

SEO 与统计#

站点配置 (siteConfig.ts)#

配置项	说明
`title`	站点标题
`subtitle`	站点副标题
`site_url`	站点 URL
`description`	站点描述（用于 SEO）
`keywords`	站点关键词
`author`	作者名称
`favicon`	网站图标

统计分析 (siteConfig.ts)#

1
analytics: {
2
  // Google Analytics ID
3
  googleAnalyticsId: "G-XXXXXXXXXX",
4
  // Microsoft Clarity ID
5
  microsoftClarityId: "XXXXXXXX",
6
},

OpenGraph 图片#

1
// 是否生成 OpenGraph 图片
2
generateOgImages: false,

RSS 订阅#

博客自动生成 RSS 订阅源，访问 /rss.xml 即可订阅。

主题定制#

主题色配置#

1
themeColor: {
2
  hue: 208,        // 色调 0-360
3
  saturation: 70,  // 饱和度 0-100
4
  fixed: false,    // 是否隐藏主题选择器
5
  defaultMode: "system",  // light, dark, system
6
},

预设主题色参考#

hue 值	颜色
0	红色
30	橙色
45	黄色
120	绿色
180	青色
200	天蓝色
220	蓝色
250	蓝紫色
280	紫色
330	粉色
345	玫红色

页面宽度#

1
pageWidth: 100,  // 单位：rem，数值越大内容区域越宽

卡片样式#

1
card: {
2
  border: true,  // 是否显示卡片边框和阴影
3
},

部署与维护#

构建命令#

Terminal window

1
# 开发调试
2
npm run dev
3

4
# 生产构建
5
npm run build
6

7
# 预览构建结果
8
npm run preview
9

10
# 部署到 GitHub Pages
11
npm run deploy

环境变量#

可以在 .env 文件中配置：

Terminal window

1
# 公开环境变量
2
PUBLIC_SITE_URL=https://your-site.com
3

4
# 私有环境变量
5
PRIVATE_VARIABLE=value

性能优化#

图片优化#

1
imageOptimization: {
2
  formats: "webp",  // avif, webp, both
3
  quality: 85,      // 1-100
4
},

字体配置#

在 fontConfig.ts 中配置中文字体和等宽字体：

1
fontConfig: {
2
  sans: ["Inter", "Noto Sans SC"],
3
  mono: ["JetBrains Mono", "Fira Code"],
4
},

常用问题#

Q: 如何禁用某个功能？#

将对应配置中的 enable 设为 false。

Q: 如何自定义页面？#

在 src/pages/ 下创建新的 .astro 文件
使用 Layout 组件包装内容
在 navBarConfig.ts 中添加导航

Q: 如何修改备案信息？#

在 footerConfig.ts 中配置：

1
footerConfig: {
2
  icp: {
3
    enable: true,
4
    code: "备案号",
5
    url: "https://beian.miit.gov.cn/",
6
  },
7
},

附录：页面路径一览#

功能	路径	说明
首页	`/`	博客首页
文章列表	`/posts/`	全部文章
文章详情	`/posts/[slug]/`	单篇文章
归档	`/archive/`	按时间归档
分类	`/categories/`	按分类查看
标签	`/tags/`	按标签查看
搜索	`/search/`	文章搜索
生活	`/life/`	生活记录首页
健康	`/life/health/`	健康数据
打卡	`/life/checkin/`	习惯打卡
想法	`/life/ideas/`	奇思妙想
日记	`/life/notebooks/`	笔记本
规划	`/life/routines/`	日常规划
地点	`/life/places/`	去过的地点
相册	`/album/`	照片集
动态	`/moments/`	日常动态
番组	`/bangumi/`	番组计划
番组详情	`/bangumi/[slug]/`	番组详情
友链	`/friends/`	友情链接
留言板	`/guestbook/`	留言板
关于	`/about/`	关于页面
赞助	`/sponsor/`	赞助页面
RSS	`/rss.xml`	RSS 订阅源
地图	`/map/`	足迹地图

附录：Content Schema 概览#

博客使用 Astro Content Collections，所有内容定义在 src/content/config.ts 中：

Collection	路径	主要用途
`posts`	`src/content/posts/`	博客文章
`moments`	`src/content/moments/`	日常动态
`album`	`src/content/album/`	相册
`daohang`	`src/content/daohang/`	网站导航
`bangumi`	`src/content/bangumi/`	番组计划
`life`	`src/content/life/*/`	生活记录
`danmu`	`src/content/danmu/`	弹幕留言
`spec`	`src/content/spec/`	特殊页面
`notebooks`	`src/content/life/notebooks/`	笔记本

最后更新: 2026-04-21

MySQL常用命令

Tue, 14 Apr 2026 00:00:00 GMT

作用	命令
进入root用户	mysql -u root -p

软件下载

Tue, 14 Apr 2026 00:00:00 GMT

导向	链接
应急文件夹	https://tsh520.lanzn.com/b014wsgruf
电脑软件	https://tsh520.lanzn.com/b014x78wah
手机软件	https://tsh520.lanzn.com/b014x78wfc
文本文档	https://tsh520.lanzn.com/b014x78wqd

英语学习方法

Wed, 11 Mar 2026 00:00:00 GMT

联想记忆法：背单词的时候联想到具体物品的模样
利用词根词缀记忆：词根+词缀

在抖音学长分享的方法 48个音标（熟悉）
自然拼读法则（新概念）
词根词缀（试试哔站8哥）
语法
背单词—>利用豆包和学习的语法造句

IO流

Wed, 11 Mar 2026 00:00:00 GMT

一、文件操作#

1.1 文件与文件流#

文件：保存数据的地方。
文件流：文件在程序中以流的形式进行操作。

1.2 创建文件对象 (File 类)#

构造器：
1. new File(String pathname)：根据路径字符串构建。
  
  |500

new File(File parent, String child)：根据父目录文件对象+子路径构建。
new File(String parent, String child)：根据父目录字符串+子路径构建。

1.3 获取文件信息#

常用方法：
- getName()：获取文件名。
- getAbsolutePath()：获取文件绝对路径。
- getParent()：获取文件父级目录。
- length()：获取文件大小（字节）。
- exists()：判断文件是否存在。
- isFile()：判断是否为文件。
- isDirectory()：判断是否为目录。

1.4 目录操作与文件删除#

mkdir()：创建一级目录。
mkdirs()：创建多级目录。
delete()：删除空目录或文件。

二、 IO流原理与分类#

2.1 原理#

I/O 指 Input/Output，用于数据传输。
Java 程序中，数据输入/输出以 “流 (stream)” 形式进行。
java.io 包提供各种流类和接口。
输入：将外部数据（磁盘等）读入到程序（内存）。
输出：将程序（内存）数据写出到外部设备（磁盘等）。

2.2 流的分类体系#

按操作数据单位：
- 字节流 (8 bit) ：用于处理二进制文件（如图片、视频、音频）。
- 字符流 (按字符) ：用于处理文本文件。
按数据流向：
- 输入流：从数据源到程序。
- 输出流：从程序到目的地。
按流的角色：
- 节点流：直接从数据源/目的地读写数据。
- 处理流（包装流） ：对节点流进行包装，提供更强大的功能。

2.3 抽象基类与命名规律#

所有流都派生自四个抽象基类：

抽象基类	字节流	字符流
输入流	InputStream	Reader
输出流	OutputStream	Writer

命名规律：子类名以其父类名作为后缀（如 FileInputStream）。

三、常用节点流#

3.1 字节输入流 FileInputStream#

作用：从文件读取字节数据到程序。
读取方式：
1. read()：每次读取一个字节，返回 int，到文件末尾返回 -1。
2. read(byte[] b)：每次读取最多 b.length 个字节到字节数组，返回实际读取的字节数，到文件末尾返回 -1。

3.2 字节输出流 FileOutputStream#

作用：将程序的字节数据写入文件。
写入方式：
1. write(int b)：写入一个字节。
2. write(byte[] b)：写入整个字节数组。
3. write(byte[] b, int off, int len)：写入字节数组的指定部分。
构造器：
- new FileOutputStream(filePath)：覆盖写入。
- new FileOutputStream(filePath, true)：追加写入。
注意：如果文件不存在，会自动创建（前提是目录存在）。

3.3 字符输入流 FileReader#

作用：从文件读取字符数据到程序。
读取方式（同 InputStream 思路，操作单位是 char）：
1. read()：每次读取一个字符。
2. read(char[] cbuf)：每次读取多个字符到字符数组。

3.4 字符输出流 FileWriter#

作用：将程序的字符数据写入文件。
写入方式（同 OutputStream 思路）：
1. write(int c)：写入一个字符。
2. write(char[] cbuf) / write(String str)：写入字符数组或字符串。
3. write(String str, int off, int len)：写入字符串的指定部分。
重要：使用 FileWriter 后，必须关闭流 (close()) 或 刷新流 (flush()) ，数据才会真正写入文件。

四、常用处理流（包装流）#

4.1 处理流概述#

作用：包装节点流，提供缓冲、便捷操作等功能，不直接连接数据源。
优势：
1. 提高性能：通过内部缓冲区减少IO次数。
2. 操作便捷：提供更方便的方法（如 readLine()）。
关闭：只需关闭最外层的处理流，底层会自动关闭节点流。

4.2 缓冲流（高效）#

BufferedReader / BufferedWriter：
- 包装字符流，提供缓冲。
- readLine()：按行读取文本，高效便捷。
- newLine()：写入一个行分隔符。
- 注意：只能用于处理文本文件。
BufferedInputStream / BufferedOutputStream：
- 包装字节流，提供缓冲。
- 用于处理二进制文件（如图片、音频拷贝），效率更高。

4.3 对象流（序列化与反序列化）#

作用：保存和恢复对象的值和数据类型。
ObjectOutputStream：提供序列化功能，将对象写入文件。
ObjectInputStream：提供反序列化功能，从文件读取对象。
序列化要求：
1. 被序列化的类必须实现 Serializable 接口（标记接口）。
2. 建议添加 serialVersionUID 以提高版本兼容性。
3. 序列化对象时，默认序列化所有属性（除了 static 和 transient 修饰的成员）。
4. 序列化具有可继承性。
注意事项：读写顺序必须一致。

4.4 转换流（解决编码问题）#

作用：在字节流和字符流之间进行转换，并可以指定编码。
InputStreamReader：将 InputStream（字节输入流）包装成 Reader（字符输入流）。
OutputStreamWriter：将 OutputStream（字节输出流）包装成 Writer（字符输出流）。
应用场景：处理纯文本数据时，使用字符流效率更高，并能有效解决中文乱码问题。

4.5 打印流#

PrintStream / PrintWriter：
- 只有输出流，没有输入流。
- 提供了一系列重载的 print() 和 println() 方法，输出非常方便。
- System.out 就是 PrintStream 类型。

五、 Properties 类#

5.1 概述#

Properties 类继承自 Hashtable，是专门用于读写配置文件的集合类。
配置文件格式：键=值（键值对，无需空格，值默认String类型）。

5.2 常用方法#

load(InputStream inStream)：从输入字节流加载属性列表（键值对）。
list(PrintStream out)：将属性列表输出到指定打印流。
getProperty(String key)：根据键获取值。
setProperty(String key, String value)：设置键值对。
store(OutputStream out, String comments)：将属性列表写入输出字节流（保存到文件）。

5.3 应用#

用于读取 .properties 配置文件（如数据库连接信息）。
可以方便地修改和保存配置。

Java 反射

Wed, 11 Mar 2026 00:00:00 GMT

一、反射的需求与快速入门#

1.1 引出反射的需求#

场景：根据配置文件（如 re.properties）中的信息（类全路径、方法名），动态创建对象并调用方法。
优势：不修改源码，仅通过外部配置文件即可控制程序，符合设计模式的开闭原则（OCP）。这是框架技术的底层核心。

1.2 快速入门案例#

读取配置文件，获取类全路径 classfullpath 和方法名 methodName。
传统 new 对象方式行不通，因为类名在编译时不确定。
反射解决方案：

1
// 1. 加载类，返回Class对象
2
Class cls = Class.forName(classfullpath);
3
// 2. 通过Class对象创建运行时实例
4
Object o = cls.newInstance();
5
// 3. 通过Class对象获取方法对象（万物皆对象）
6
Method method1 = cls.getMethod(methodName);
7
// 4. 通过方法对象调用方法：method1.invoke(o);

二、反射机制原理#

2.1 Java Reflection 定义#

反射机制允许程序在运行期借助 Reflection API 取得任何类的内部信息，并能操作对象的属性和方法。
原理核心：类加载后，在堆中会生成一个唯一的 Class 类对象，它像一面“镜子”，包含了该类的完整结构信息（成员变量、构造器、成员方法等）。通过这个 Class 对象可以反向获取类的结构。

2.2 反射能完成的操作#

运行时判断任意对象的类。
运行时构造任意类的对象。
运行时获取任意类的成员变量和方法。
运行时调用任意对象的成员变量和方法。
生成动态代理。

2.3 反射相关的主要类 (java.lang.reflect)#


类	代表	作用
java.lang.Class	一个类	表示某个类加载后在堆中的对象。反射的入口。
java.lang.reflect.Method	类的方法	通过 Class 对象获取，代表某个类的方法。
java.lang.reflect.Field	类的成员变量	通过 Class 对象获取，代表某个类的成员变量。
java.lang.reflect.Constructor	类的构造方法	通过 Class 对象获取，代表某个类的构造器。

2.4 反射的优缺点与性能优化#

优点：动态性，使框架具备灵活扩展能力，是框架技术的底层支撑。
缺点：主要是解释执行，对执行速度有影响。
性能优化：通过 Method/Field/Constructor 对象的 setAccessible(true) 方法，可以关闭访问安全检查（暴破），能显著提高反射效率。

三、 Class 类#

3.1 Class 类特点#

Class 也是类，继承自 Object。
Class 类对象不是 new 出来的，而是由JVM在类加载时创建的。
对于某个类，在内存中只有一份 Class 对象（因为类只加载一次）。
每个对象实例都记得它是由哪个 Class 对象生成的。
Class 对象包含了类的完整结构，可通过API获取。
Class 对象存放在堆中，类的字节码二进制数据（元数据）存放在方法区。

3.2 获取 Class 类对象的六种方式#


方式	代码示例	应用场景	备注
1. Class.forName	Class cls1 = Class.forName(“全类名”);	多用于配置文件，读取全类名，加载类。	可能抛出 ClassNotFoundException。
2. 类名.class	Class cls2 = Cat.class;	多用于参数传递，安全可靠，性能高。	最常用。
3. 对象.getClass()	Class cls3 = 对象.getClass();	已有对象实例，获取其 Class 对象。	获取对象的运行时类型。
4. 类加载器	ClassLoader cl = 对象.getClass().getClassLoader(); Class cls4 = cl.loadClass(“全类名”);	通过类加载器动态加载。
5. 基本数据类型.class	Class cls5 = int.class;	获取基本数据类型的 Class 对象。
6. 包装类.TYPE	Class cls6 = Integer.TYPE;	获取基本数据类型对应包装类的 Class 对象。	与方式5的 Class 对象相同。

3.3 哪些类型有 Class 对象？#

所有类型都有 Class 对象：外部类、内部类、接口、数组、枚举、注解、基本数据类型、void。

四、类加载#

4.1 静态加载 vs 动态加载#

静态加载：编译时加载相关类。如果类不存在，则编译报错。依赖性太强。
- 触发时机：new 对象、访问静态成员、继承等。
动态加载：运行时加载需要的类。如果运行时未使用该类，即使不存在也不报错。降低了依赖性。
- 触发时机：反射。

4.2 类加载过程#

加载 (Loading)：将类的字节码文件读入内存，并为之创建一个 java.lang.Class 对象。
连接 (Linking)：
- 验证 (Verification)：确保字节码文件符合JVM规范，安全。
- 准备 (Preparation)：为静态变量分配内存并设置默认初始值。
  - 注意：static final 修饰的常量，在准备阶段会直接赋值为指定的值。
- 解析 (Resolution)：将常量池中的符号引用替换为直接引用。
初始化 (Initialization)：执行类构造器 () 方法的过程，真正为静态变量赋值并执行静态代码块。JVM保证此过程线程安全。

五、通过反射获取类的结构信息#

5.1 第一组：java.lang.Class 方法#


方法	作用
getName()	获取全类名。
getSimpleName()	获取简单类名。
getFields()	获取所有 public 修饰的属性（包含父类的）。
getDeclaredFields()	获取本类中所有属性（任何修饰符）。
getMethods()	获取所有 public 修饰的方法（包含父类的）。
getDeclaredMethods()	获取本类中所有方法。
getConstructors()	获取所有 public 修饰的构造器。
getDeclaredConstructors()	获取本类中所有构造器。
getPackage()	获取包信息。
getSuperclass()	获取父类的 Class 对象。
getInterfaces()	获取实现的接口的 Class 数组。

5.2 第二组：java.lang.reflect.Field 方法#


方法	作用
getModifiers()	以 int 形式返回修饰符。可配合 Modifier 类解读。
getType()	以 Class 形式返回属性类型。
getName()	返回属性名。

5.3 第三组：java.lang.reflect.Method 方法#


方法	作用
getModifiers()	以 int 形式返回修饰符。
getReturnType()	以 Class 形式获取返回类型。
getName()	返回方法名。
getParameterTypes()	以 Class[] 返回参数类型数组。

5.4 第四组：java.lang.reflect.Constructor 方法#


方法	作用
getModifiers()	以 int 形式返回修饰符。
getName()	返回构造器名（全类名）。
getParameterTypes()	以 Class[] 返回参数类型数组。

六、通过反射创建对象和访问成员#

6.1 创建对象#

调用无参构造器（类中必须有 public 无参构造）：

1
Class cls = Class.forName("全类名");
2
Object o = cls.newInstance(); // 已过时，推荐用构造器

调用指定构造器：

1
// 1. 获取指定参数类型的构造器对象
2
Constructor constructor = cls.getDeclaredConstructor(参数类型.class, ...);
3
// 2. 如果是非public构造器，需要暴破
4
constructor.setAccessible(true);
5
// 3. 调用构造器创建实例
6
Object o = constructor.newInstance(实参列表);

6.2 访问属性#

根据属性名获取 Field 对象：Field f = cls.getDeclaredField(“属性名”);

暴破（针对非 public 属性）：f.setAccessible(true);
访问：

1
f.set(o, 值); // 设置属性值
2
f.get(o);     // 获取属性值

注意：如果是静态属性，set 和 get 中的对象参数 o 可以写成 null。

6.3 访问方法#

根据方法名和参数列表获取 Method 对象：Method m = cls.getDeclaredMethod(“方法名”, 参数类型.class, …);
暴破（针对非 public 方法）：m.setAccessible(true);
调用：Object returnValue = m.invoke(o, 实参列表);
- 注意：如果是静态方法，invoke 中的对象参数 o 可以写成 null。
- 返回值类型为 Object，但其实际运行类型与方法定义的返回类型一致。

Java 网络编程

Wed, 11 Mar 2026 00:00:00 GMT

一、网络基础概念#

1.1 网络通信#

概念：两台设备之间通过网络实现数据传输。
Java支持：java.net 包提供了一系列类/接口用于网络通信。

1.2 网络分类#

局域网 (LAN)：覆盖范围最小，如一个教室、机房。
城域网 (MAN)：覆盖一个城市。
广域网 (WAN)：覆盖全国或全球，如互联网。

1.3 IP地址#

作用：唯一标识网络中的每台计算机/主机。
表示形式：点分十进制 xx.xx.xx.xx（每个数范围0~255）。
组成：网络地址 + 主机地址。
IPv4 vs IPv6：IPv4地址资源有限，IPv6地址数量极大，是下一代协议。
IPv4地址分类：

类型	范围
A类	0.0.0.0 到 127.255.255.255
B类	128.0.0.0 到 191.255.255.255
C类	192.0.0.0 到 223.255.255.255
D类	224.0.0.0 到 239.255.255.255 (多播)
E类	240.0.0.0 到 247.255.255.255 (保留)

1.4 域名与端口#

域名：如 www.baidu.com。为了方便记忆，将IP地址映射成域名。
端口：
- 作用：标识计算机上某个特定的网络程序。
- 范围：0 ~ 65535。
- 约定：0~1024已被系统或知名服务占用（如HTTP:80, FTP:21, SSH:22）。
- 常见程序端口：Tomcat:8080, MySQL:3306, Oracle:1521。

1.5 网络通信协议#

TCP/IP协议簇：Internet最基本的协议，由网络层的IP协议和传输层的TCP协议等组成。
网络模型：


OSI模型	TCP/IP模型	TCP/IP模型各层协议
应用层	应用层	HTTP, FTP, Telnet, DNS…
表示层	应用层
会话层	应用层
传输层	传输层	TCP, UDP…
网络层	网络层	IP, ICMP, ARP…
数据链路层	物理+数据链路层	Link
物理层	物理+数据链路层	Link

1.6 TCP 与 UDP 协议#


特性	TCP (传输控制协议)	UDP (用户数据报协议)
连接性	面向连接 (三次握手)	无连接
可靠性	可靠，数据不丢失	不可靠，可能丢包
通信单位	字节流	数据报 (包)
数据大小	无限制	每个数据报 ≤ 64K
效率	较低 (需建立/释放连接)	较高
应用场景	文件传输、邮件、网页浏览	音视频通话、直播、DNS查询

二、 InetAddress 类#

作用：用于封装IP地址和域名。
常用方法：
- InetAddress.getLocalHost()：获取本机InetAddress对象。
- InetAddress.getByName(String host)：根据主机名/域名获取对象。
- getHostName()：获取主机名。
- getHostAddress()：获取IP地址字符串。

三、 Socket 编程#

3.1 Socket 概念#

套接字(Socket)是网络通信的端点。
通信两端都必须有Socket。
数据在Socket间通过IO流传输。
主动发起连接的是客户端，等待连接的是服务端。

四、 TCP 网络编程#

4.1 编程模型#

服务端：
1. 创建 ServerSocket，在指定端口监听。
2. 调用 accept() 等待客户端连接，连接成功返回 Socket 对象。
3. 通过 Socket.getInputStream() 读取客户端发送的数据。
4. 通过 Socket.getOutputStream() 向客户端回复数据。
5. 关闭资源。
客户端：
1. 创建 Socket，连接服务端（指定IP和端口）。
2. 通过 Socket.getOutputStream() 发送数据。
3. 通过 Socket.getInputStream() 接收服务端回复。
4. 关闭资源。

4.2 应用案例#

案例1 (字节流，单向)：客户端发送“hello, server”后退出，服务端接收并打印。
案例2 (字节流，双向)：客户端发送消息，服务端回复“hello, client”，客户端接收回复。
- 注意：通信结束时，应调用 socket.shutdownOutput() 设置输出结束标记，告知对方数据已发送完毕，避免对方 read 方法阻塞。
案例3 (字符流，双向)：使用 BufferedReader 和 BufferedWriter 包装流进行字符通信。
- 注意：使用 bufferedWriter.newLine() 插入换行作为结束标记，并调用 flush() 手动刷新缓冲区。
案例4 (文件上传)：客户端发送图片/文件，服务端保存到本地，并回复“收到图片”。
- 核心：使用 BufferedInputStream 和 BufferedOutputStream 提高效率。
- 工具类：使用 StreamUtils 将输入流转换为字节数组或字符串，简化操作。

4.3 注意事项#

实际通信中，客户端也会使用一个随机端口与服务端通信。
可使用 netstat -an 指令查看主机网络状态（监听端口和连接信息）。

五、 UDP 网络编程#

5.1 基本介绍#

核心类：DatagramSocket (数据报套接字) 和 DatagramPacket (数据包/数据报)。
无连接：每个数据包独立，包含发送方和接收方的IP与端口。
不可靠：不保证送达和顺序。

5.2 编程模型#

发送端：
1. 创建 DatagramSocket 对象。
2. 将数据封装到 DatagramPacket 对象中（指定数据、长度、目标IP、端口）。
3. 调用 socket.send(packet) 发送。
4. 可接收回复。
5. 关闭 socket。
接收端：
1. 创建 DatagramSocket 并在指定端口监听。
2. 创建空的 DatagramPacket 对象用于接收。
3. 调用 socket.receive(packet) 阻塞等待数据。
4. 拆包 (packet.getData()) 处理数据。
5. 可回复数据。
6. 关闭 socket。

5.3 应用案例#

接收端A在9999端口等待，发送端B发送“hello, 明天吃火锅~”，A接收后回复“好的，明天见”。

Java动态代理

Wed, 11 Mar 2026 00:00:00 GMT

一、动态代理核心概念#

1.1 什么是代理模式？#

1
代理模式 = 代理对象 + 目标对象

代理对象：不直接实现服务，而是通过调用目标对象的方法来提供服务
目标对象：真正执行业务逻辑的对象
核心价值：在不修改目标对象代码的前提下，增强或控制目标对象的行为

1.2 静态代理 vs 动态代理#

对比项	静态代理	动态代理
创建时间	编译期	运行期
代码生成	手动编写或工具生成	反射机制动态生成
灵活性	低（每个类需单独代理）	高（可统一处理多个类）
.class文件	运行前已存在	运行时生成

二、JDK动态代理（基于接口）#

2.1 核心类与接口#

1
// 1. InvocationHandler接口（必须实现）
2
public interface InvocationHandler {
3
    Object invoke(Object proxy, Method method, Object[] args) throws Throwable;
4
}
5

6
// 2. Proxy类（用于创建代理对象）
7
public static Object newProxyInstance(
8
    ClassLoader loader,      // 类加载器
9
    Class<?>[] interfaces,   // 目标对象实现的接口
10
    InvocationHandler h      // 调用处理器
11
)

2.2 实现步骤#

1
┌─────────────────────────────────────────────────┐
2
│  步骤1: 定义接口                                  │
3
│  步骤2: 创建目标类实现接口                        │
4
│  步骤3: 创建InvocationHandler实现类              │
5
│  步骤4: 通过Proxy创建代理对象                    │
6
│  步骤5: 调用代理对象方法                         │
7
└─────────────────────────────────────────────────┘

2.3 代码示例#

1
// ① 定义接口
2
public interface UserService {
3
    void addUser(String name);
4
    void deleteUser(String id);
5
}
6

7
// ② 目标类实现接口
8
public class UserServiceImpl implements UserService {
9
    @Override
10
    public void addUser(String name) {
11
        System.out.println("添加用户: " + name);
12
    }
13
    @Override
14
    public void deleteUser(String id) {
15
        System.out.println("删除用户: " + id);
16
    }
17
}
18

19
// ③ 创建InvocationHandler
20
public class UserServiceProxy implements InvocationHandler {
21
    private Object target; // 目标对象
22

23
    public UserServiceProxy(Object target) {
24
        this.target = target;
25
    }
26

27
    @Override
28
    public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
29
        // 前置增强
30
        System.out.println("=== 方法执行前：日志记录 ===");
31

32
        // 执行目标方法
33
        Object result = method.invoke(target, args);
34

35
        // 后置增强
36
        System.out.println("=== 方法执行后：事务提交 ===");
37

38
        return result;
39
    }
40
}
41

42
// ④ 测试类
43
public class Test {
44
    public static void main(String[] args) {
45
        UserService target = new UserServiceImpl();
46

47
        // 创建代理对象
48
        UserService proxy = (UserService) Proxy.newProxyInstance(
49
            target.getClass().getClassLoader(),
50
            target.getClass().getInterfaces(),
51
            new UserServiceProxy(target)
52
        );
53

54
        // 调用代理方法
55
        proxy.addUser("张三");
56
        proxy.deleteUser("001");
57
    }
58
}

显示更多显示更少

2.4 JDK动态代理特点#

优点	缺点
✅ JDK原生支持，无需额外依赖	❌ 只能代理接口
✅ 启动速度快	❌ 无法代理未实现接口的类
✅ 代码简洁易理解	❌ 无法代理final方法

三、CGLIB动态代理（基于继承）#

3.1 核心原理#

通过生成目标类的子类来实现代理
使用MethodInterceptor拦截方法调用
需要引入CGLIB依赖

3.2 Maven依赖#

1
<dependency>
2
    <groupId>cglib</groupId>
3
    <artifactId>cglib</artifactId>
4
    <version>3.3.0</version>
5
</dependency>

3.3 代码示例#

1
// ① 目标类（无需实现接口）
2
public class UserService {
3
    public void addUser(String name) {
4
        System.out.println("添加用户: " + name);
5
    }
6

7
    public void deleteUser(String id) {
8
        System.out.println("删除用户: " + id);
9
    }
10
}
11

12
// ② 创建MethodInterceptor
13
public class CglibProxy implements MethodInterceptor {
14
    @Override
15
    public Object intercept(Object obj, Method method, Object[] args, MethodProxy proxy) throws Throwable {
16
        // 前置增强
17
        System.out.println("=== CGLIB前置增强 ===");
18

19
        // 执行目标方法
20
        Object result = proxy.invokeSuper(obj, args);
21

22
        // 后置增强
23
        System.out.println("=== CGLIB后置增强 ===");
24

25
        return result;
26
    }
27
}
28

29
// ③ 创建代理对象
30
public class Test {
31
    public static void main(String[] args) {
32
        Enhancer enhancer = new Enhancer();
33
        enhancer.setSuperclass(UserService.class);
34
        enhancer.setCallback(new CglibProxy());
35

36
        UserService proxy = (UserService) enhancer.create();
37
        proxy.addUser("李四");
38
    }
39
}

显示更多显示更少

3.4 CGLIB动态代理特点#

优点	缺点
✅ 可代理普通类（无需接口）	❌ 需要额外依赖
✅ 功能更强大	❌ 无法代理final类/方法
✅ 适合第三方类代理	❌ 启动速度较慢

四、JDK vs CGLIB 对比总结#

1
┌──────────────────┬──────────────────┬──────────────────┐
2
│      对比项       │   JDK动态代理     │    CGLIB动态代理   │
3
├──────────────────┼──────────────────┼──────────────────┤
4
│    实现方式       │     基于接口       │     基于继承       │
5
│    核心类         │  Proxy+InvocationHandler │  Enhancer+MethodInterceptor │
6
│    是否需要接口    │        是         │        否         │
7
│    额外依赖       │        无         │       需要        │
8
│    代理final方法  │        不能       │        不能       │
9
│    性能           │    JDK8+后优化    │     略低于JDK     │
10
│    Spring默认选择  │  有接口用JDK       │  无接口用CGLIB    │
11
└──────────────────┴──────────────────┴──────────────────┘

五、实际应用场景#

5.1 Spring AOP#

1
// Spring根据目标类是否有接口自动选择代理方式
2
// 有接口 → JDK动态代理
3
// 无接口 → CGLIB动态代理
4

5
@Transactional  // 事务管理
6
@Cacheable      // 缓存管理
7
@Async          // 异步执行

5.2 常见应用场景#

日志记录 - 统一记录方法调用日志
权限校验 - 方法执行前检查用户权限
事务管理 - 自动开启/提交/回滚事务
性能监控 - 统计方法执行时间
RPC框架 - Dubbo、Feign等远程调用

六、学习要点总结#

1
📌 核心记忆点：
2
1. 动态代理 = 运行时生成代理类
3
2. JDK代理 → 接口 + Proxy + InvocationHandler
4
3. CGLIB代理 → 继承 + Enhancer + MethodInterceptor
5
4. Spring AOP自动选择代理方式
6
5. final类/方法都无法被代理
7

8
📌 面试常考点：
9
1. JDK和CGLIB的区别
10
2. 动态代理的实现原理
11
3. Spring AOP底层实现
12
4. 代理模式的应用场景

七、练习题建议#

手写一个JDK动态代理实现日志功能
手写一个CGLIB动态代理实现权限校验
对比两种代理方式的性能差异
分析Spring AOP的代理选择逻辑

💡 学习建议：动态代理是Java进阶的必备知识，建议多动手敲代码理解原理，结合Spring AOP一起学习效果更好！

希望这份笔记对您学习Java动态代理有帮助！如需更详细的内容，建议配合B站相关视频教程一起学习。

多线程

Wed, 11 Mar 2026 00:00:00 GMT

一、线程相关概念#

1.1 程序、进程与线程#

程序：是为完成特定任务、用某种语言编写的一组指令的集合，即我们写的静态代码。
进程：
1. 指运行中的程序。如启动QQ，操作系统会为其分配独立的内存空间。
2. 进程是程序的一次执行过程，是动态的，有其产生、存在和消亡的生命周期。
线程：
1. 由进程创建，是进程的一个实体。
2. 一个进程可以拥有多个线程（如一个QQ进程可以同时打开多个聊天窗口）。

1.2 单线程、多线程、并发与并行#

单线程：同一时刻，只允许执行一个线程。
多线程：同一时刻，可以执行多个线程。
并发：单核CPU实现的多任务。同一时刻，多个任务交替执行，造成“同时”的错觉。
并行：多核CPU实现的多任务。同一时刻，多个任务真正同时执行。

二、线程的创建与使用#

2.1 创建线程的两种方式#

继承 Thread 类，重写 run 方法。
实现 Runnable 接口，重写 run 方法。

2.2 方式一：继承 Thread 类#

步骤：
1. 定义一个类继承 Thread。
2. 重写 run 方法，在其中编写线程要执行的任务。
3. 创建该类的实例。
4. 调用实例的 start() 方法启动线程。
注意：
- start() 方法会调用底层的 start0() 方法，使线程进入可运行状态，由CPU调度执行。
- 直接调用 run() 方法仅是普通方法调用，不会启动新线程。

2.3 方式二：实现 Runnable 接口#

步骤：
1. 定义一个类实现 Runnable 接口。
2. 重写 run 方法。
3. 创建该类的实例。
4. 将此实例作为参数传递给 Thread 对象的构造器，创建 Thread 对象。
5. 调用 Thread 对象的 start() 方法启动线程。
原理：使用了代理模式。Thread 类本身实现了 Runnable 接口，其 run 方法会调用传入的 Runnable 对象的 run 方法。
优势：
1. 避免Java单继承的限制。
2. 更适合多个线程共享同一个资源的场景（只需创建一个 Runnable 实例，传递给多个 Thread 对象）。

三、线程常用方法#

3.1 第一组常用方法#

setName(String name) / getName()：设置/获取线程名称。
start()：启动线程，使其进入可运行状态。
run()：线程执行体，由JVM调用。
setPriority(int newPriority) / getPriority()：设置/获取线程优先级（范围1-10）。
sleep(long millis)：静态方法。让当前线程休眠指定的毫秒数。
interrupt()：中断线程，但并非强制结束。通常用于中断正在 sleep 或 wait 的线程，使其抛出 InterruptedException。

3.2 第二组常用方法#

yield() ：线程的礼让。让出CPU，给其他线程执行机会，但礼让成功与否取决于CPU调度，不一定成功。
join() ：线程的插队。调用此方法的线程会阻塞当前线程（如主线程），直到调用者执行完毕，当前线程才继续执行。
- 应用场景：主线程需要等待子线程执行完特定任务后再继续。

3.3 用户线程与守护线程#

用户线程（工作线程） ：线程任务执行完毕或通过通知方式结束。
守护线程：为工作线程服务。当所有用户线程结束时，守护线程自动结束。
- 典型例子：垃圾回收线程。
- 设置方法：线程对象.setDaemon(true); （必须在 start() 前调用）。

四、线程的生命周期#

JDK中 Thread.State 枚举定义了线程的六种状态：

NEW（新建） ：线程对象已创建，但尚未调用 start()。
RUNNABLE（可运行） ：线程正在JVM中执行，或已就绪等待CPU调度。对应操作系统中的 Ready（就绪） 和 Running（运行） 状态。
BLOCKED（阻塞） ：线程等待获取一个监视器锁（如进入 synchronized 代码块失败）。
WAITING（无限等待） ：线程等待另一个线程执行特定动作（如 Object.wait()）。
TIMED_WAITING（计时等待） ：线程在指定时间内等待（如 Thread.sleep(long)）。
TERMINATED（终止） ：线程执行完毕，已退出。

五、线程的同步#

5.1 同步的必要性#

在多线程环境下，当多个线程同时访问共享资源（如卖票系统的票数）时，可能导致数据不一致（超卖、重复卖）等问题。

5.2 同步机制 - Synchronized#

保证在任一时刻，最多只有一个线程访问同步代码，确保数据完整性。

同步代码块：

1
synchronized(对象) { // 得到对象的锁才能进入
2
    // 需要同步的代码
3
}

1
public synchronized void method() {
2
    // 需要同步的代码
3
}

5.3 互斥锁#

每个Java对象都有一个互斥锁（Monitor Lock） 标记。
synchronized 关键字与对象的互斥锁关联。
锁对象的选择：
1. 对于非静态同步方法，锁对象默认为 this（当前对象实例）。
2. 对于静态同步方法，锁对象默认为当前类.class。
3. 对于同步代码块，锁对象是 synchronized 后括号里指定的对象。
4. 核心原则：要求多个线程竞争的锁对象必须是同一个。

5.4 释放锁与不释放锁的操作#

会释放锁：
1. 同步代码块/方法执行完毕。
2. 同步代码块/方法中遇到 break、return。
3. 同步代码块/方法中出现未处理的 Error 或 Exception。
4. 同步代码块/方法中执行了 wait() 方法。
不会释放锁：
1. 调用 Thread.sleep() 或 Thread.yield() 暂停线程。
2. 其他线程调用了该线程的 suspend() 方法（该方法已废弃，应避免使用）。

5.5 线程死锁#

定义：多个线程都占用了对方所需的锁资源，并且互相等待对方释放，导致所有线程都无法继续执行。
产生条件：互斥使用、不可抢占、请求和保持、循环等待。
解决：在编程中应尽量避免。可以通过规定锁的获取顺序、使用 tryLock 等机制来预防。2

常用类

Wed, 11 Mar 2026 00:00:00 GMT

一、包装类 (Wrapper Class)#

1. 基本介绍#

目的：为八种基本数据类型提供对应的引用类型，使其具有类的特性（如调用方法）。

分类：
- Boolean, Character (继承关系特殊)
- Byte, Short, Integer, Long, Float, Double (均继承自 Number 类)

2. 装箱与拆箱#

装箱：基本类型 → 包装类型。
拆箱：包装类型 → 基本类型。
JDK5前后：
- JDK5前：手动 (new Integer() / intValue() )。
- JDK5后：自动（编译器完成，底层调用 valueOf() 和 xxxValue()）。

3. 与String类型的转换#

包装类 → String：
1. Integer i = 100; String str1 = i + “”;
2. String str2 = i.toString();
3. String str3 = String.valueOf(i);
String → 包装类：
1. Integer i1 = Integer.parseInt(“123”); (返回 int，可自动装箱)
2. Integer i2 = new Integer(“123”);

4. 常用方法与面试题#

Integer/Character常用方法：
- Integer.parseInt(String s)
- Character.isDigit(char ch) / isLetter() / isUpperCase() / isLowerCase()
- Character.toUpperCase(char ch) / toLowerCase()
重要面试题（Integer缓存机制）：
- Integer 类在 -128 到 127 之间有一个缓存数组。
- 通过自动装箱或 Integer.valueOf() 在这个范围内取值，会直接返回缓存中的对象。
- 例如：Integer i1 = 127; Integer i2 = 127; 则 i1 == i2 为 true。Integer i3 = 128; Integer i4 = 128; 则 i3 == i4 为 false。

二、String 类#

1. 基本特性#

final 类，不可被继承。
实现了 Serializable (可序列化) 和 Comparable (可比较) 接口。
用于保存字符串，底层是 private final char value[] (JDK8及之前) 或 byte[] (JDK9及之后)。
不可变性：value 数组引用地址不可变，内容可变但不会影响已创建的String对象。任何修改都会创建新对象。

2. 创建对象的两种方式与内存分配#

直接赋值：String s = “hsp”;
- 先从常量池查找是否有 ”hsp”，有则直接指向；无则创建后指向。
- s 指向常量池地址。
调用构造器：String s = new String(“hsp”);
- 先在堆中创建对象，其 value 属性指向常量池中的 ”hsp” (若无则创建)。
- s 指向堆中对象地址。

3. 字符串的特性与面试题#

常量相加：String s = “a” + “b”; 编译器会优化为 ”ab”，在常量池中只生成一个对象。
变量相加：String a = “a”; String b = “b”; String c = a + b;
- 底层使用 StringBuilder 进行 append 操作，最后 toString() 返回一个新对象在堆中。
- c 指向堆地址。
intern() 方法：返回字符串在常量池中的地址。
- 如果常量池已包含该字符串，则返回池中地址。
- 否则，将该字符串对象添加到池中，并返回此对象的引用。

4. 常用方法#

比较：equals, equalsIgnoreCase, compareTo
查找：indexOf, lastIndexOf, charAt
截取/替换：substring, replace
转换：toUpperCase, toLowerCase, toCharArray
分割/拼接：split (注意转义), concat
格式化：String.format(“格式”, 参数…) (占位符: %s, %d, %.2f, %c)
其他：trim, length, isEmpty

三、StringBuffer 与 StringBuilder#

1. 基本介绍#

共同点：代表可变的字符序列，是对String在需要频繁修改时效率低下的补充。底层也是 char[] 存储，但非final，可扩容。
关系：均继承自 AbstractStringBuilder。

2. 三者对比#

特性	String	StringBuffer	StringBuilder
可变性	不可变 (final char[])	可变	可变
线程安全	安全 (不可变)	安全(方法有 synchronized 修饰)	不安全
效率	低 (频繁修改会创建大量对象)	较高	最高
使用场景	少量字符串操作，或作为常量	多线程环境下大量字符串操作	单线程环境下大量字符串操作

3. StringBuffer/StringBuilder 常用方法#

增：append
删：delete(start, end)
改：replace(start, end, str), setCharAt
查：indexOf
插：insert(offset, str)
长度：length
遍历：for() + charAt()

4. 相互转换#

String → StringBuffer/StringBuilder：
1. 构造器：new StringBuffer(String str)
2. append：new StringBuffer().append(str)
StringBuffer/StringBuilder → String：
1. toString() 方法
2. 构造器：new String(StringBuffer sb)

四、Math 类#

基本介绍：包含用于执行基本数学运算的静态方法。
常用方法：
- abs (绝对值)
- pow (求幂)
- ceil (向上取整)
- floor (向下取整)
- round (四舍五入)
- sqrt (开平方)
- random (随机数，范围 [0.0, 1.0))
- max, min (求最值)

五、Arrays 类#

基本介绍：包含一系列操作数组的静态方法。
常用方法：
- toString (返回数组字符串形式)
- sort (排序，支持自然排序和定制排序——通过 Comparator 接口)
- binarySearch (二分查找，数组必须有序)
- copyOf (数组复制)
- fill (数组填充)
- equals (比较两数组内容)
- asList (将一组值转为 List)

六、System、BigInteger、BigDecimal#

1. System 类#

常用方法：
- exit (退出程序)
- arraycopy (复制数组，底层高效)
- currentTimeMillis (获取当前时间戳毫秒数)
- gc (运行垃圾回收)

2. BigInteger#

应用场景：存储、运算超大整数 (超出 long 范围)。
运算：使用对应方法，如 add, subtract, multiply, divide。

3. BigDecimal#

应用场景：存储、运算高精度浮点数，解决浮点数运算精度丢失问题。
运算：使用对应方法。
除法注意：可能抛出 ArithmeticException (无限循环小数)，需指定精度 BigDecimal.ROUND_CEILING 等。

七、日期类#

1. 第一代：Date & SimpleDateFormat#

Date：表示特定瞬间，精确到毫秒。大部分方法已过时。
SimpleDateFormat：用于格式化和解析日期。
- 格式化：Date → String (format 方法)
- 解析：String → Date (parse 方法，需处理异常)

2. 第二代：Calendar#

抽象类，用于字段操作 (YEAR, MONTH 等)。
缺点：可变、偏移性 (月从0开始)、格式化不便、非线程安全。

3. 第三代 (JDK8)：LocalDate, LocalTime, LocalDateTime#

核心类：不可变、线程安全、设计合理。
- LocalDate：只含日期。
- LocalTime：只含时间。
- LocalDateTime：含日期和时间。
Instant：时间戳。
DateTimeFormatter：格式化类 (替代 SimpleDateFormat)。
优点：方法丰富 (plusDays, minusHours 等)，无偏移问题。

泛型

Wed, 11 Mar 2026 00:00:00 GMT

泛型#

一、泛型的引入与好处#

1.1 传统方法的问题#

在集合中，使用传统方法（不使用泛型）存在两个主要问题：

类型不安全：不能对加入到集合中的数据类型进行约束，可以添加任意类型的对象。
效率低：遍历时，需要进行频繁的类型转换（Object -> 具体类型），数据量大时影响效率。

1.2 泛型的好处#

使用泛型可以解决上述问题：

类型安全：在编译时检查添加元素的类型，不符合则报错，提高了安全性。
提高效率：减少了遍历时不必要的类型转换次数。
- 不使用泛型：Dog -> Object (存入) -> Dog (取出，需强转)
- 使用泛型：Dog -> Dog (存入) -> Dog (取出，无需强转)
消除警告：代码更加简洁、健壮，不再有编译警告。

二、泛型介绍#

2.1 基本概念#

泛型：又称参数化类型，是 JDK 5.0 引入的新特性。
核心思想：在类声明或实例化时，通过一个标识符来指定操作的数据类型。
作用：可以在类声明时，用一个标识符表示类中某个属性的类型、某个方法的返回值类型或参数类型。
优点：保证如果程序在编译时没有发出警告，运行时就不会产生 ClassCastException 异常。

三、泛型语法与使用#

3.1 泛型的声明与实例化#

声明：在类名或接口名后使用尖括号 <> 定义泛型标识符，如 class Person<E>, interface List<T>。
实例化：在创建对象时，在尖括号 <> 中指定具体的类型。

1
// 声明一个泛型类
2
class Person<E> { ... }
3
// 实例化，指定 E 为 String 类型
4
Person<String> person = new Person<String>("韩顺平教育");

3.2 泛型使用的注意事项和细节#

类型限制：泛型标识符 T, E 等只能是引用类型，不能是基本数据类型。

1
List<Integer> list1 = new ArrayList<Integer>(); // OK
2
// List<int> list2 = new ArrayList<int>(); // 错误

继承关系：在给泛型指定具体类型后，可以传入该类型或其子类类型。
使用形式：

1
// 完整写法
2
ArrayList<Integer> list1 = new ArrayList<Integer>();
3
// 简化写法（类型推断），推荐使用
4
ArrayList<Integer> list2 = new ArrayList<>();
5
// 未指定泛型，默认为 Object
6
ArrayList list3 = new ArrayList(); // 等价于 ArrayList<Object> list3 = ...

四、自定义泛型#

4.1 自定义泛型类#

基本语法：class 类名<T, R…> { … }

|500

注意细节：
1. 普通成员（属性、方法）可以使用泛型。
2. 不能初始化使用泛型的数组（因为 new 时无法确定 T 的具体类型）。
3. 静态成员（属性、方法）中不能使用类的泛型（因为静态成员在类加载时初始化，而泛型类型在创建对象时才确定）。
4. 泛型类的类型，是在创建对象时确定的。
5. 如果在创建对象时没有指定类型，则默认为 Object。

4.2 自定义泛型接口#

基本语法：interface 接口名<T, R…> { … }
注意细节：
1. 接口中，静态成员也不能使用泛型（同泛型类）。
2. 泛型接口的类型，在继承接口或实现接口时确定。
3. 没有指定类型，默认为 Object。

4.3 自定义泛型方法#

基本语法：修饰符 <T, R…> 返回类型方法名(参数列表) { … }
注意细节：
1. 泛型方法可以定义在普通类中，也可以定义在泛型类中。
2. 当泛型方法被调用时，类型会确定。
3. public void eat(E e) {} 这样的方法，其泛型 E 依赖于类定义的泛型，不是泛型方法。
4. public <T> void fly(T t) {} 这样的方法，其泛型 T 独立于类，是泛型方法。

五、泛型的继承和通配符#

5.1 泛型没有继承性#

虽然 String 是 Object 的子类，但 List<String> 并不是 List<Object> 的子类。它们是并列关系，没有继承关系。

5.2 泛型通配符#

为了表示泛型之间的某种关系，引入了通配符 ?。

<?>：无界通配符
- 表示可以接受任意的泛型类型。
- List<?> 是 List<String>, List<Object> 等各种泛型 List 的父类。
- 注意：不能向 List<?> 中添加除 null 以外的任何元素（因为类型不确定），但可以读取，读取出的类型是 Object。
<? extends A>：上界通配符
- 表示可以接受 A 类以及 A 类的子类（不限于直接子类）。
- 规定了泛型的上限。
- 同样，不能向 List<? extends A> 中添加除 null 以外的任何元素（因为无法确定具体是哪个子类），但可以读取，读取出的类型是 A。
<? super A>：下界通配符
- 表示可以接受 A 类以及 A 类的父类（不限于直接父类）。
- 规定了泛型的下限。
- 可以向 List<? super A> 中添加 A 及其子类对象（因为父类引用可以指向子类对象）。
- 读取时，返回的类型是 Object。

六、 JUnit 单元测试（补充）#

6.1 为什么需要 JUnit#

传统测试需要将代码写入 main 方法，测试多个功能时需要来回注销、切换，非常麻烦。
JUnit 可以直接运行一个方法进行测试，并给出相关信息，方便快捷。

6.2 基本介绍#

JUnit 是一个 Java 语言的单元测试框架。
多数 Java 开发环境（如 IDEA）都已集成 JUnit 作为单元测试工具。

6.3 使用步骤（简述）#

在需要测试的类中，导入 JUnit 相关包（通常由 IDE 自动完成）。
在需要测试的方法上添加 @Test 注解。
在方法体内编写测试代码。
右键点击方法名或类名，选择 Run ‘方法名()’ 或 Run ‘类名’ 执行测试。

集合

Wed, 11 Mar 2026 00:00:00 GMT

一、集合概述#

1.1 集合的好处 (相比数组)#

动态保存：可以保存任意多个对象，长度可变。
丰富API：提供了一系列方便操作对象的方法，如 add, remove, set, get 等。
代码简洁：使用集合进行增删改查比数组更简洁。

1.2 集合框架体系 (两大主线)#

Java集合主要分为两大类：单列集合 (Collection) 和 双列集合 (Map)。

Collection 接口：存放单个对象。
- 有两个重要子接口：List 和 Set。
- List：有序、可重复。
  - 主要实现类：ArrayList, LinkedList, Vector。
- Set：无序、不可重复。
  - 主要实现类：HashSet, LinkedHashSet, TreeSet。
Map 接口：存放键值对 K-V。
- 主要实现类：HashMap, Hashtable, TreeMap, LinkedHashMap, Properties。

二、 Collection 接口#

2.1 Collection 接口特点#

可以存放多个元素，每个元素是 Object。
有些实现类可存放重复元素 (List)，有些不可以 (Set)。
有些是有序的 (List)，有些不是 (Set)。
Collection 接口没有直接实现类，通过其子接口 Set 和 List 实现。

2.2 Collection 接口遍历元素方式#

使用 Iterator 迭代器
- 所有实现了 Collection 接口的集合都有一个 iterator() 方法，返回迭代器对象。

迭代器仅用于遍历，本身不存放对象。
执行原理：hasNext() 判断是否还有下一个元素，next() 下移并返回元素。

注意：在调用 next() 之前必须调用 hasNext() 检测，否则可能抛出 NoSuchElementException。

增强 for 循环
- 本质就是迭代器的简化版，语法更简洁。
- 只能用于遍历集合或数组。
- 语法：for(元素类型元素名 : 集合名或数组名) { //访问元素 }

三、 List 接口#

3.1 List 接口特点#

有序：添加顺序和取出顺序一致。
可重复：允许存放相同的元素。
支持索引：每个元素都有其对应的顺序索引 (0-based)，可以通过 get(int index) 方法获取。

3.2 List 接口常用方法#

add(int index, Object ele)：在 index 位置插入 ele 元素。
addAll(int index, Collection eles)：从 index 位置开始将 eles 中的所有元素添加进来。
get(int index)：获取指定 index 位置的元素。
indexOf(Object obj)：返回 obj 在集合中首次出现的位置。
lastIndexOf(Object obj)：返回 obj 在集合中末次出现的位置。
remove(int index)：移除指定 index 位置的元素，并返回此元素。
set(int index, Object ele)：设置指定 index 位置的元素为 ele，相当于替换。
subList(int fromIndex, int toIndex)：返回从 fromIndex 到 toIndex 位置的子集合（前闭后开）。

3.3 List 的三种遍历方式#

迭代器 Iterator
增强 for 循环
普通 for 循环（利用索引）

四、 List 接口实现类#

4.1 ArrayList#

底层结构：可变长度的对象数组 Object[] elementData。
线程安全：线程不安全，但执行效率高。
扩容机制：
- 无参构造器：初始容量为0，第一次添加扩容至10，后续需要扩容时，按当前容量的1.5倍扩容。
- 有参构造器：初始容量为指定大小，后续需要扩容时，同样按1.5倍扩容。
其他：可以加入 null，且允许多个。

4.2 Vector#

底层结构：对象数组 Object[] elementData。
线程安全：线程安全（方法带有 synchronized 关键字），但效率较低。
扩容机制：
- 无参构造器：默认初始容量10，满后按2倍扩容。
- 有参构造器：初始容量为指定大小，满后按2倍扩容。
与 ArrayList 比较

	底层结构	版本	线程安全	效率	扩容倍数
ArrayList	可变数组	JDK1.2	不安全	高	无参：首次10，后续1.5倍；有参：直接1.5倍
Vector	可变数组	JDK1.0	安全	不高	无参：默认10，满后2倍；有参：满后2倍

4.3 LinkedList#

底层结构：双向链表。维护了属性 first 和 last 分别指向首尾节点。每个节点 (Node) 有 prev, item, next 属性。
特点：实现了双向链表和双端队列接口。可以添加任意元素（包括 null）。线程不安全。
操作机制：元素的添加和删除通过操作链表完成，不涉及数组扩容，因此增删效率高，改查效率低。
与 ArrayList 比较

	底层结构	增删效率	改查效率
ArrayList	可变数组	较低（数组扩容）	较高
LinkedList	双向链表	较高（链表追加）	较低

五、 Set 接口#

5.1 Set 接口特点#

无序（添加和取出顺序不一致，但 LinkedHashSet 和 TreeSet 除外）。
不允许重复元素，最多包含一个 null。
没有索引，不能使用普通 for 循环遍历。
遍历方式：迭代器、增强 for 循环。

5.2 HashSet#

底层结构：HashMap。即底层是数组 + 链表 + 红黑树。
添加机制（去重核心）：
1. 添加元素时，先得到 hash 值，然后转成索引值。
2. 找到存储数据表 table，看索引位置是否已有元素。
3. 如果没有，直接加入。
4. 如果有，调用 equals 比较：
  - 如果相同，放弃添加。
  - 如果不同，则添加到链表的最后（或树化）。

扩容与树化：
- 第一次添加时，table 扩容到16，临界值 (threshold) 为 16 * 0.75 = 12。
- 如果 table 使用到临界值，就扩容到当前容量 * 2，临界值也相应更新。
- 树化：当一条链表的元素个数达到 TREEIFY_THRESHOLD (默认8)，并且 table 的大小 >= MIN_TREEIFY_CAPACITY (默认64)，该链表会转为红黑树，否则仍采用数组扩容。

5.3 LinkedHashSet#

底层结构：LinkedHashMap。是 HashSet 的子类。
特点：在 HashSet 数组+链表/红黑树的基础上，增加了一套双向链表，用于维护元素的添加顺序。这使得元素看起来是以插入顺序保存的。
优点：既拥有了 HashSet 的去重能力，又能保证遍历顺序与插入顺序一致。

5.4 TreeSet#

底层结构：TreeMap（红黑树）。
排序/去重机制：
1. 传入比较器 (Comparator)：使用构造器传入的 Comparator 对象的 compare 方法进行排序和去重。返回0则认为相同，不添加。
2. 未传入比较器：则使用添加对象实现的 Comparable 接口的 compareTo 方法去重。如果对象没有实现 Comparable，添加时会抛出 ClassCastException。

六、 Map 接口#

6.1 Map 接口特点#

Map 与 Collection 并列存在，用于保存具有映射关系的数据 Key-Value。
Key 和 Value 可以是任何引用类型数据，封装在 HashMap$Node 对象中。
Key 不允许重复（原因同 HashSet），Value 可以重复。
Key 可以为 null（仅一个），Value 可以为 null（多个）。
常用 String 类作为 Map 的 Key。
Key 和 Value 是单向一对一关系，通过指定的 Key 总能找到对应的 Value。

6.2 Map 接口遍历方式#

keySet()：获取所有 Key 的 Set 集合，然后通过 get(key) 获取 Value。
values()：获取所有 Value 的 Collection 集合。
entrySet()：获取所有 Entry (K-V 对) 的 Set 集合。然后可以从 Entry 对象中获取 getKey() 和 getValue()。

6.3 HashMap#

使用频率最高的 Map 实现类。
线程不安全，方法未同步。
底层机制：数组 + 链表 + 红黑树。
扩容机制：与 HashSet 完全相同（因为 HashSet 底层就是 HashMap）。
- 首次扩容到16，临界值12。
- 后续扩容为2倍，临界值 = 新容量 * 0.75。
- 树化条件：链表长度 >= 8 且数组长度 >= 64。
添加/替换机制：添加相同的 Key 会覆盖原来的 Value，等同于修改。

6.4 Hashtable#

线程安全的 Map 实现类（方法使用 synchronized 修饰），效率较低。
键和值都不能为 null，否则抛出 NullPointerException。
与 HashMap 比较：

	版本	线程安全	效率	允许null键值
HashMap	JDK1.2	不安全	高	可以
Hashtable	JDK1.0	安全	较低	不可以

6.5 Properties#

继承自 Hashtable 并实现了 Map 接口。
同样使用 K-V 结构，键和值也不能为 null。
通常用于从 .properties 配置文件中加载数据，在IO流中常用。

七、 Collections 工具类#

7.1 介绍#

Collections 是一个操作 Set、List 和 Map 等集合的工具类，提供了一系列静态方法。

7.2 常用方法#

排序操作：
- reverse(List)：反转顺序。
- shuffle(List)：随机排序。
- sort(List)：自然排序（升序）。
- sort(List, Comparator)：定制排序。
- swap(List, int, int)：交换元素。
查找、替换：
- max(Collection) / min(Collection)：返回最大/最小元素。
- max(Collection, Comparator) / min(Collection, Comparator)：定制比较返回最大/最小。
- frequency(Collection, Object)：返回指定元素出现次数。
- copy(List dest, List src)：将 src 内容复制到 dest。
- replaceAll(List list, Object oldVal, Object newVal)：使用新值替换所有旧值。

八、开发中选择集合实现类的建议#

单列情况：
- 需要唯一元素 -> Set
  - 需要顺序 -> TreeSet (排序) 或 LinkedHashSet (插入顺序)。
  - 不需要顺序 -> HashSet。
- 允许重复元素 -> List
  - 增删多 -> LinkedList。
  - 查改多 -> ArrayList。
- 不确定情况 -> ArrayList。
双列情况 (键值对)：
- -> Map
  - 需要排序 -> TreeMap。
  - 不需要排序，但需要保持插入或访问顺序 -> LinkedHashMap。
  - 其他情况 -> HashMap。
线程安全：
- 需要线程安全 -> 使用 Collections.synchronizedXXX() 包装，或考虑 ConcurrentHashMap (对于 Map)。

枚举、注解、异常

Tue, 03 Mar 2026 00:00:00 GMT

一、枚举 (enum)#

1. 需求与问题分析#

需求：创建季节 (Season) 对象。
特点分析：
1. 季节的值是有限的几个（春、夏、秋、冬）。
2. 这些值通常是只读的，不需要修改。
传统实现的问题：使用普通类定义，虽然可以满足，但无法从语法层面强制限制对象数量和不可变性。

2. 枚举的解决方案#

枚举 (Enumeration)：是一组常量的集合。
本质理解：枚举是一种特殊的类，内部只包含一组有限的、特定的对象。

3. 枚举的两种实现方式#

自定义类实现枚举（JDK1.5之前的方式）。
使用 enum 关键字实现枚举（JDK1.5引入，推荐）。

4. 自定义类实现枚举#

实现步骤（小结）：
1. 构造器私有化：防止外部直接 new。
2. 本类内部创建一组对象：例如，创建四个 Season 对象代表四季。
3. 对外暴露对象：为这些对象添加 public final static 修饰符，使其成为公共静态常量。
4. 可以提供 get 方法，不提供 set 方法：保证只读性。
优点：实现了枚举的功能。
缺点：代码相对繁琐。

5. 使用 enum 关键字实现枚举（重点）#

快速入门：使用 enum 替代 class 来定义枚举类。
语法示例：

1
enum Season2 {
2
    // 1. 将常量对象定义在枚举类的行首，多个常量用逗号间隔，最后用分号结尾。
3
    SPRING("春天", "温暖"),
4
    WINTER("冬天", "寒冷"),
5
    AUTUMN("秋天", "凉爽"),
6
    SUMMER("夏天", "炎热"); // What() 如果有无参对象，也可以定义
7

8
    // 2. 定义属性
9
    private String name;
10
    private String desc;
11

12
    // 3. 构造器私有化
13
    private Season2(String name, String desc) {
14
        this.name = name;
15
        this.desc = desc;
16
    }
17
    // 可以提供无参构造器
18
    private Season2() {}
19
    // ... get方法
20
}

显示更多显示更少

注意事项：
1. 使用 enum 关键字定义的枚举类，默认隐式继承 java.lang.Enum 类，且是一个 final 类（可用 javap 反编译验证）。
2. 传统的 public static final Season2 SPRING = new Season2(“春天”, “温暖”); 简化为 SPRING(“春天”, “温暖”)。它调用的是对应的构造器。
3. 如果使用无参构造器创建枚举对象，则实参列表和小括号都可以省略，例如：BOY, GIRL;。
4. 枚举对象必须放在枚举类的行首。

6. enum 常用方法（继承自 Enum 类）#

方法名	说明
toString()	返回当前枚举对象名。Enum类已重写，子类可重写以返回更友好的信息。
name()	返回当前枚举对象名（常量名）。不能重写。
ordinal()	返回当前枚举对象的序号（从0开始）。
values()	返回该枚举类中所有的常量构成的数组（静态方法，由编译器生成）。
valueOf(String name)	将字符串转换为对应的枚举对象。字符串必须为已有常量名，否则报 IllegalArgumentException。
compareTo(Enum o)	比较两个枚举常量的序号（编号）。

7. enum 实现接口#

枚举类不能继承其他类（因为已隐式继承 Enum，Java是单继承）。
但枚举类可以实现一个或多个接口。
形式：enum 类名 implements 接口1, 接口2 { … }
可以在枚举类中统一实现接口方法，也可以让每个枚举对象单独实现接口方法（体现枚举对象之间的差异性）。

二、注解 (Annotation)#

1. 注解的理解#

注解：也被称为元数据 (Metadata)，用于修饰解释包、类、方法、属性、构造器、局部变量等数据信息。
与注释的区别：注释是给人看的，注解是给编译器或JVM等工具看的，可以被编译或运行，是嵌入代码中的补充信息。
作用：
- JavaSE：标记过时功能、忽略警告等。
- JavaEE：配置应用程序，代替繁琐的代码和XML配置（非常重要）。

2. 三个基本的 Annotation（必须掌握）#

使用 @ 符号，将其当成修饰符使用。

1) @Override#

作用：限定某个方法是重写父类方法。只能用于方法。
使用说明：
- 如果写了 @Override，编译器会检查该方法是否真的重写了父类方法。是则通过，否则报错。
- 如果不写，但实际构成了重写，程序也能运行。但写上可以提高代码可读性和安全性。
- 只能修饰方法。
源码分析：

1
@Target(ElementType.METHOD) // 表示只能修饰方法
2
@Retention(RetentionPolicy.SOURCE) // 作用范围：源码阶段，编译后就不存在了
3
public @interface Override {
4
}

2) @Deprecated#

作用：表示某个程序元素（类、方法、字段等）已过时。不推荐使用，但仍可使用。
使用说明：
- 可以修饰方法、类、字段、包、参数等。
- 通常用于版本兼容和过渡。
源码分析：

1
@Target(value={CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, PARAMETER, TYPE})
2
@Retention(RetentionPolicy.RUNTIME) // 运行时仍保留
3
@Documented // 会被 javadoc 工具提取
4
public @interface Deprecated { ... }

3) @SuppressWarnings#

作用：抑制编译器警告。
使用说明：
- 可以放置的具体位置有：类、字段、方法、参数、构造器、局部变量。
- 其作用范围与放置的位置相关（例如放在方法上，则抑制该方法内的警告）。
- 需要指定要抑制的警告类型，例如：

1
@SuppressWarnings({“rawtypes”, “unchecked”, “unused”})

3. JDK 的元注解 (Meta-Annotation)#

元注解是用于修饰其他注解的注解。了解即可，主要用于阅读源码。

1) @Retention#

作用：指定被修饰的注解可以保留多长时间（即生命周期）。必须指定 value 值。
三种取值：
- RetentionPolicy.SOURCE：编译器使用后直接丢弃（如 @Override）。

RetentionPolicy.CLASS：编译器记录在 .class 文件中，但JVM运行时不会保留（默认值）。
RetentionPolicy.RUNTIME：编译器记录在 .class 文件中，JVM运行时保留，程序可以通过反射获取（如 @Deprecated）。

2) @Target#

作用：指定被修饰的注解能用于修饰哪些程序元素（如方法、类、字段等）。
常见 ElementType 取值：TYPE(类/接口), FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE, ANNOTATION_TYPE(注解)等。

3) @Documented#

作用：指定被修饰的注解将被 javadoc 工具提取成文档。

4) @Inherited#

作用：被修饰的注解将具有继承性。如果父类使用了该注解，其子类将自动具有该注解。
注意：实际应用较少。

三、异常引入与基本概念#

1. 问题引入#

运行包含错误逻辑的代码（如除数为零）会导致程序崩溃并终止。
目标：通过异常处理机制，捕获并处理错误，使程序能够继续运行或优雅地结束。

2. 异常介绍#

异常：程序执行过程中发生的不正常情况（语法错误和逻辑错误不属于异常）。
异常体系两大类别：
1. Error（错误）：Java虚拟机无法解决的严重问题，如StackOverflowError（栈溢出）、OutOfMemoryError（OOM）。程序会崩溃，通常无法通过代码处理。
2. Exception（异常）：因编程错误或偶然外在因素导致的一般性问题，可以使用针对性代码进行处理。分为两大类：
  - 运行时异常（RuntimeException）：程序运行时发生的异常，编译器不强制检查。
  - 编译时异常：编译器要求必须进行处理的异常（如IOException）。

3. 异常体系图（重要）#

1
Throwable
2
├── Error (e.g., StackOverflowError, OutOfMemoryError)
3
└── Exception
4
    ├── RuntimeException (运行时异常)
5
    │   ├── NullPointerException
6
    │   ├── ArithmeticException
7
    │   ├── ArrayIndexOutOfBoundsException
8
    │   ├── ClassCastException
9
    │   └── NumberFormatException
10
    └── 其他Exception (编译时异常，e.g., IOException, SQLException)

小结：
- 运行时异常编译器不检查，通常由逻辑错误引起，程序员应尽量避免。
- 编译时异常编译器强制要求处理，否则编译不通过。

四、常见异常详解#

1. 常见运行时异常（RuntimeException）#

异常类型	触发场景
NullPointerException	试图在需要对象的地方使用 null（如调用 null 对象的方法或属性）。
ArithmeticException	出现异常的运算条件（如整数“除以零”）。
ArrayIndexOutOfBoundsException	用非法索引（负索引或大于等于数组长度）访问数组。
ClassCastException	试图将对象强制转换为不是其实例子类的类型。
NumberFormatException	试图将格式不正确的字符串转换为数值类型（如 Integer.parseInt(“abc”)）。

2. 编译时异常#

特点：编译期间就必须处理，否则代码无法通过编译。
常见类型：SQLException、IOException、FileNotFoundException、ClassNotFoundException 等。
说明：由于涉及后续章节知识（如文件、数据库操作），此处仅作概念了解。

五、异常处理机制#

1. 处理方式#

try-catch-finally：程序员在代码中捕获发生的异常，并自行处理。

throws：将发生的异常抛出，交给方法的调用者处理，最终可交给JVM。

2. try-catch-finally 处理#

基本语法：

1
try {
2
    // 可能发生异常的代码
3
} catch (ExceptionType e) {
4
    // 捕获到异常后的处理逻辑
5
    // e.getMessage(): 获取异常信息
6
} finally {
7
    // 无论是否发生异常，都会执行的代码（通常用于释放资源）
8
}

注意事项与细节：
1. 如果异常发生，异常行之后的 try 块内代码不会执行，直接跳入对应的 catch 块。
2. 如果异常未发生，则顺序执行完 try 块，跳过 catch 块。
3. finally 块中的代码必定执行（即使 catch 块中有 return 语句）。
4. 可以有多个 catch 块，捕获不同类型的异常并进行不同处理。必须遵循：子类异常在前，父类异常在后（例如 NullPointerException 在 Exception 之前）。
5. 可以进行 try-finally 配合使用（无 catch）。这种用法不捕获异常，程序遇到异常仍会崩溃，但 finally 块会执行。适用于“无论是否异常，都必须执行某段逻辑（如关闭资源）”的场景。
执行顺序小结：
- 无异常：执行 try → [跳过 catch] → finally。
- 有异常：执行 try (到异常处) → 匹配的 catch → finally。

3. throws 异常处理#

基本介绍：在方法声明处，用 throws 语句声明该方法可能抛出的异常类型，将异常的处理责任传递给该方法的调用者。
语法：访问修饰符返回类型方法名(参数列表) throws 异常类型1, 异常类型2 { … }
注意事项与细节：
1. 对于编译时异常，程序中必须处理（要么 try-catch，要么 throws）。
2. 对于运行时异常，程序中如果没有处理，默认就是 throws 的方式向上抛出。
3. 子类重写父类方法时，对抛出异常的规定：子类重写方法所抛出的异常类型，必须和父类抛出异常一致，或者是其子类。
4. 在某个方法内，如果已经用 try-catch 处理了异常，则相当于处理完毕，可以不必再 throws。

六、自定义异常#

1. 基本概念#

当程序中出现特定的错误，但Java标准异常类中没有合适的异常来描述时，可以自定义异常类。

2. 步骤#

定义类，类名自定义，继承 Exception 或 RuntimeException。
- 继承 Exception → 编译时异常（使用时必须处理）。
- 继承 RuntimeException → 运行时异常（推荐，更灵活）。
通常提供两个构造器：一个无参构造器，一个带 String message 参数的构造器（用于传递异常信息）。

3. 应用实例#

例如，定义 AgeException，在接收年龄参数时，若范围不在 18-120 之间，则抛出此自定义异常。

1
class AgeException extends RuntimeException {
2
    public AgeException(String message) {
3
        super(message);
4
    }
5
}
6
// 使用
7
if(age < 18 || age > 120) {
8
    throw new AgeException("年龄需要在 18~120 之间");
9
}

七、throw 与 throws 的区别（重要）#

关键词	意义	位置	后面跟随的东西
throws	异常处理的一种方式（声明可能抛出的异常）	方法声明处	异常类型（可以是多个）
throw	手动生成异常对象并抛出的关键字	方法体内	异常对象（new Exception(…)）

简单记忆：throws 是声明异常，throw 是抛出异常。

面向对象

Mon, 02 Mar 2026 00:00:00 GMT

一、面向对象与类、对象概述#

核心思想：面向对象编程 (OOP) 。将现实世界的事物抽象为程序中的对象，每个对象包含属性（状态）和行为（方法） 。
程序世界：一个程序就是一个由许多对象构成的世界。

类与对象的关系#

类 (Class) ：
- 抽象的、概念上的定义，代表一类事物（如“猫类”、“人类”）。
- 是对象的模板/数据类型，定义了该类对象共有的属性和行为。
对象 (Object) / 实例 (Instance) ：
- 具体的、实际存在的个体，是类的一个具体例子（如“一只叫小白3岁的猫”、“一个叫老韩的人”）。
关系：类是对象的抽象，对象是类的实例。必须先有类，才能创建对象。

对象在内存中的存在形式（重要！）#

栈：存放局部变量等（如对象引用 cat1）。
堆：存放对象本身（属性数据）。
方法区：存放类的信息（属性结构、方法代码）、常量池。

创建流程：Cat cat1 = new Cat();
1. 加载类信息：JVM将Cat类的属性、方法信息加载到方法区（只加载一次）。
2. 堆中分配空间：在堆中开辟内存，存放Cat对象的属性，并进行默认初始化（如int为0，String为null）。
3. 建立引用：将堆中对象的地址（如0x0011）赋给栈中的引用变量cat1。
4. 指定初始化：执行cat1.name = “小白”等语句，为属性赋具体值。

属性 / 成员变量 / 字段#

概念：属性是类的一个组成部分，表示对象的状态或数据。成员变量 = 属性 = 字段 (field)。
定义语法：访问修饰符属性类型属性名; （如 public String name;）
注意事项：
1. 属性可以是任意类型（基本类型或引用类型如数组、对象）。
2. 属性若不赋值，有默认值（规则同数组：int 0, double 0.0, boolean false, 引用类型 null）。

类和对象的内存分配机制#

基本数据类型赋值：传递的是值本身。int a = 10; int b = a; 修改b不影响a。
引用数据类型赋值：传递的是对象在堆中的地址。

1
Person p1 = new Person();
2
p1.age = 10;
3
Person p2 = p1; // p2 指向 p1 所指向的同一个对象
4
System.out.println(p2.age); // 10
5
p2.age = 20;
6
System.out.println(p1.age); // 20 (因为指向同一对象)

二、成员方法#

1. 为什么需要成员方法#

对象不仅有属性（状态），还有行为（功能）。方法用于封装对象的行为。
好处：
1. 提高代码复用性：将常用功能封装成方法，多处调用。
2. 实现细节封装：使用者只需调用方法，无需关心内部实现。

2. 成员方法的定义与调用#

原理（重要！）：

定义语法：

1
访问修饰符 返回数据类型 方法名(形参列表) {
2
    // 方法体
3
    语句;
4
    return 返回值; // 如果返回类型不是void
5
}

3. 方法传参机制（非常重要！）#

基本数据类型传参：传递的是值的拷贝。形参的改变不会影响实参。

1
public void swap(int a, int b) { // a, b 是实参值的拷贝
2
    int tmp = a; a = b; b = tmp; // 交换只发生在方法内部
3
}
4
// main: swap(x, y); 调用后 x, y 不变

引用数据类型传参：传递的是地址的拷贝。形参和实参指向同一个对象。通过形参修改对象属性，会影响实参指向的对象。

1
public void test100(int[] arr) { arr[0] = 200; } // 修改会影响原数组
2
public void test200(Person p) { p.age = 10000; } // 修改会影响原对象

注意：如果在方法内让形参引用指向一个新的对象（p = new Person();）或null，则不会影响实参的指向。

4. 方法递归调用#

概念：方法自己调用自己，每次调用传入不同的变量。
能解决的问题：数学问题（阶乘、斐波那契数列）、迷宫、汉诺塔、八皇后、各种算法（快排、二分查找）等。
重要规则：
1. 每次调用都会开辟新的栈空间，局部变量独立。
2. 如果方法中使用引用类型变量，则会共享该数据。
3. 必须向退出递归的条件逼近，否则会无限递归导致栈溢出 (StackOverflowError)。
4. 谁调用，结果就返回给谁。
image

5. 方法重载 (OverLoad)#

概念：在同一个类中，允许存在多个同名方法，但要求它们的形参列表不一致（类型、个数、顺序至少有一项不同）。
好处：减轻起名和记名的麻烦。
细节：
1. 方法名必须相同。
2. 形参列表必须不同。返回类型、参数名称无要求。
判断：void show(int a, char b, double c) {}
- 重载：void show(int a, double c, char b){} (顺序不同)
- 不重载：void show(int x, char y, double z){} (仅参数名不同，不算)

6. 可变参数#

概念：将同一个类中多个同名同功能但参数个数不同的方法，封装成一个方法。
语法：访问修饰符返回类型方法名(数据类型… 形参名) {}
细节：
1. 实参可以为0个到任意多个。
2. 可变参数的实参可以是数组。
3. 本质就是数组。
4. 可变参数必须放在形参列表的最后，且一个形参列表只能有一个可变参数。

1
public int sum(int... nums) { // nums 可当作数组使用
2
    int res = 0;
3
    for(int i = 0; i < nums.length; i++) { res += nums[i]; }
4
    return res;
5
}

三、作用域#

1. 基本概念#

全局变量（属性） ：作用域为整个类体，可以被本类方法使用，也可通过对象被其他类使用。有默认值，生命周期长（伴随对象）。
局部变量：作用域在定义它的代码块（如方法、循环体内）内。必须赋值后才能使用，无默认值。生命周期短（伴随代码块执行）。

2. 注意事项#

属性和局部变量可以重名，访问时遵循就近原则。
同一作用域内（如一个方法内），局部变量不能重名。
修饰符：属性可以加public、private等修饰符，局部变量不能加。

四、构造器 / 构造方法#

1. 为什么需要构造器#

在创建对象时，直接完成对象的初始化（为属性赋初值），而不是先创建空对象再赋值。

2. 基本介绍#

构造器是类的一种特殊方法，主要作用是完成新对象的初始化。
特点：
1. 方法名必须和类名相同。
2. 没有返回值，也不能写void。
3. 在创建对象时，系统自动调用相应的构造器。
语法：[修饰符] 方法名(形参列表) { 方法体; }

3. 注意事项#

一个类可以定义多个不同的构造器（即构造器重载）。
如果没有定义构造器，系统会生成一个默认的无参构造器。一旦定义了自己的构造器，默认构造器就被覆盖，除非显式定义。
构造器可以完成除了初始化之外的任何操作（如调用方法），但不推荐。

五、this 关键字#

1. 为什么需要 this#

当构造器或方法的形参名与属性名相同时，为了区分局部变量和属性，需要使用this。

1
class Dog {
2
    String name;
3
    public Dog(String name) { // 形参名与属性名相同
4
        this.name = name; // this.name 指当前对象的属性，name 指形参
5
    }
6
}

2. 深入理解 this#

this 代表当前对象。哪个对象调用，this就指向哪个对象。
在方法中，可以通过 this.属性名或 this.方法名(参数) 来访问本类的成员。

3. 注意事项和使用细节#

this 可用于访问本类的属性、方法、构造器。
用于区分当前类的属性和局部变量。
访问本类构造器语法：this(参数列表); 必须放在构造器的第一行。
this 不能在类定义的外部使用，只能在类定义的方法中使用。

六、访问修饰符 (Access Modifier)#

用于控制类、属性和方法的访问权限范围。

访问级别	修饰符	同类	同包	子类	不同包	说明
公开	public	✓	✓	✓	✓	对外完全公开
受保护	protected	✓	✓	✓	✗	对子类和同包类公开
默认	(无，即default)	✓	✓	✗	✗	仅对同包的类公开
私有	private	✓	✗	✗	✗	仅本类内部可访问

注意事项：

public和默认(无修饰符)可以修饰类。
成员方法的访问规则与属性完全相同。

七、封装 (Encapsulation)#

1. 封装的理解与好处#

理解：将数据和操作数据的方法封装在一起，对外隐藏实现细节。
好处：
1. 隐藏实现细节：使用者只需关注功能，无需了解内部复杂逻辑。
2. 数据验证：可以对数据进行有效性的校验，保证数据安全合理。
3. 便于维护：内部逻辑修改不影响外部调用。

2. 封装的实现步骤 (三步)#

私有化属性：将属性用private修饰。
提供公共的set方法：用于对属性进行判断和赋值。
提供公共的get方法：用于获取属性的值。

八、继承 (Inheritance)#

1. 为什么需要继承？#

解决多个类中存在相同属性和方法时的代码复用问题。

2. 继承的基本介绍与示意图#

概念：子类 (Subclass) 继承父类 (Superclass) 的属性和方法，同时可以拥有自己的特性。
语法：class 子类 extends 父类 { }
术语：父类（超类、基类）、子类（派生类）。

3. 继承的细节问题 (非常重要！)#

访问权限：子类继承了父类所有的属性和方法。但私有(private)成员不能在子类直接访问，需要通过父类提供的公共方法间接访问。
构造器调用：
- 创建子类对象时，必须调用父类构造器以完成父类初始化。
- 默认情况下，子类构造器会隐式调用父类的无参构造器 super()。
- 如果父类没有无参构造器，则必须在子类构造器中显式使用super(参数) 指定调用父类的哪个构造器，且super(…)必须是子类构造器的第一条语句。
单继承机制：Java中，一个子类最多只能直接继承一个父类（单继承）。
Object类：Java中所有类都默认继承Object类。
super关键字：代表父类的引用，用于访问父类的属性、方法和构造器。
- super.属性名 / super.方法名()：访问父类的成员（不能访问private）。
- super(参数列表)：在子类构造器中调用父类构造器。
继承的内存布局：子类对象在堆中包含了父类所有属性的空间。属性查找顺序：子类 -> 父类 -> … -> Object。

4. super 与 this 的比较#

区别点	this	super
访问属性	从本类开始查找	从父类开始查找
调用方法	从本类开始查找	从父类开始查找
调用构造器	调用本类构造器 (this(…))	调用父类构造器 (super(…))
特殊	表示当前对象	在子类中访问父类对象

注意：super(…)和this(…)都必须放在构造器第一行，因此二者不能共存于同一个构造器中。

九、多态 (Polymorphism)#

1. 多态的基本介绍#

概念：方法或对象具有多种形态。建立在封装和继承的基础之上。
体现：
1. 方法的多态：重载 (Overload) 和 重写 (Override) 。
2. 对象的多态 (核心) ：一个对象的编译类型和运行类型可以不一致。

2. 对象的多态 (核心)#

重要规则：
1. 对象的编译类型在定义时 (=左边) 就确定了，不能改变。
2. 对象的运行类型是可以变化的 (=右边)。
3. 编译时看左边，运行时看右边。

1
Animal animal = new Dog(); // animal编译类型Animal，运行类型Dog
2
animal = new Cat(); // animal运行类型变为Cat，编译类型仍是Animal

3. 多态的向上转型与向下转型#

向上转型：
- 本质：父类的引用指向子类的对象。
- 语法：父类类型引用名 = new 子类类型();
- 特点：可以调用父类中的所有成员（遵守访问权限），不能调用子类特有成员；运行效果看子类的具体实现（即动态绑定）。
向下转型：
- 本质：将父类引用强制转回子类引用。
- 语法：子类类型引用名 = (子类类型) 父类引用;
- 前提：父类引用必须指向当前要转换的子类类型对象。否则会抛出ClassCastException。
- 作用：转型后可以调用子类的所有成员。
instanceof比较操作符：用于判断对象的运行类型是否为XX类型或其子类型。对象 instanceof 类名

4. Java的动态绑定机制 (非常重要！)#

调用对象方法时：该方法会和对象的内存地址/运行类型进行绑定。
调用对象属性时：没有动态绑定机制，属性值取决于声明该属性的类型（即编译类型）。

5. 多态的应用#

多态数组：数组定义为父类类型，实际存放子类类型的对象。
多态参数：方法形参定义为父类类型，实参可以传入任意子类类型的对象。极大地提高了代码的复用性和扩展性。

十、方法重写/覆盖 (Override)#

1. 基本介绍#

子类有一个方法，和父类的某个方法的名称、返回类型、参数列表完全一样，我们就说子类的这个方法重写 (覆盖) 了父类的方法。

2. 注意事项与细节#

子类方法的形参列表、方法名称必须和父类方法完全一致。
子类方法的返回类型必须和父类方法一样，或者是父类返回类型的子类。
子类方法的访问权限不能比父类方法更严格（即不能缩小访问范围）。例如：父类是public，子类不能是protected。
子类不能重写父类的private方法。
重写(Override) vs 重载(Overload) ：

名称	发生范围	方法名	形参列表	返回类型	修饰符
重载 (Overload)	本类	必须相同	必须不同	无要求	无要求
重写 (Override)	父子类	必须相同	必须相同	相同或其子类	不能缩小访问范围

十一、Object 类详解#

Object类是Java所有类的根父类。

1. equals 方法#

== 操作符：
- 判断基本类型：比较值是否相等。
- 判断引用类型：比较地址是否相等（是否为同一个对象）。
equals 方法：
- 是Object类中的方法，只能判断引用类型。
- 默认行为：判断地址是否相等 (return (this == obj);)。
- 子类重写：如String、Integer、Date等类重写了equals方法，用于判断内容是否相等。
- 如何重写equals：通常比较两个对象的所有属性是否都相等。

2. hashCode 方法#

返回对象的哈希码值（整数），支持哈希表类（如HashMap）的高效运行。
两个引用指向同一个对象，哈希值肯定相同。
两个引用指向不同对象，哈希值一般不同（哈希值主要根据地址计算，但不完全等于地址）。
在集合中，如果需要重写equals方法，通常也需要重写hashCode方法。

3. toString 方法#

默认返回：全类名 + @ + 哈希值的十六进制字符串。
子类重写：通常返回对象的属性信息。
自动调用：当直接输出对象 (System.out.println(对象)) 或拼接对象时，会自动调用该对象的toString()方法。

4. finalize 方法 (已过时，了解即可)#

当对象被垃圾回收器回收时，系统会自动调用该方法。
子类可以重写它，用于释放资源（如关闭文件、数据库连接）。
注意：实际开发中几乎不会使用，垃圾回收由JVM管理，不建议主动调用System.gc()。

十二、断点调试 (Debug)#

1. 介绍与快捷键#

作用：逐行执行代码，查看变量变化，追踪程序执行流程，排查错误。
IDEA 常用调试快捷键：
- F7：跳入 (Step Into) 方法内部。
- F8：跳过 (Step Over) ，逐行执行。
- Shift + F8：跳出 (Step Out) 当前方法。
- F9：恢复程序 (Resume) ，执行到下一个断点。
- Alt + F9：运行到光标处。

‍

面向对象（高级）

Mon, 02 Mar 2026 00:00:00 GMT

一、类变量和类方法 (static关键字)#

1. 类变量（静态变量）#

提出问题：如何统计所有对象共享的一个数据？（如：统计玩游戏的小孩总数）
传统方法的局限：在main方法中定义计数变量，不面向对象，访问麻烦。
解决方案：使用类变量。
- 定义语法：访问修饰符 static 数据类型变量名; (推荐)
- 特点：
  1. 被该类的所有对象实例共享。
  2. 在类加载时就初始化生成。
  3. 生命周期随类的加载而开始，随类的消亡而销毁。
- 访问方式：
  - 类名.类变量名 (推荐)
  - 对象名.类变量名
- 内存布局：static变量是对象共享的（具体位置与JDK版本有关，可能在堆或方法区，共识是共享的）。

2. 类方法（静态方法）#

定义语法：访问修饰符 static 返回类型方法名() { }
调用方式：类名.类方法名或对象名.类方法名。
经典使用场景：工具类方法（如Math、Arrays中的方法）。当方法中不涉及任何和对象相关的成员时，可设计为静态方法，提高效率。
注意事项与细节：
1. 类方法和普通方法都随类加载而加载，结构信息存储在方法区。
2. 类方法中无this参数；普通方法中隐含着this参数。
3. 核心口诀：静态方法只能访问静态成员（静态变量、静态方法）。普通成员方法既可以访问非静态成员，也可以访问静态成员。
4. 类方法中不能使用this和super关键字。
5. 静态方法可以通过类名调用；普通方法必须通过对象名调用。

二、理解main方法语法#

public static void main(String[] args) {}
深入理解：
1. main方法由Java虚拟机(JVM)调用。
2. public: JVM需要调用，访问权限必须公开。
3. static: JVM调用时不必创建对象。
4. void: 无返回值给JVM。
5. String[] args: 接收命令行参数。
在main方法中的访问规则：
1. 可以直接访问本类的静态成员。
2. 不能直接访问本类的非静态成员，必须创建对象后通过对象访问。

三、代码块#

基本介绍：属于类的成员，类似于方法，将逻辑语句封装在{}中。没有方法名、返回、参数，在加载类或创建对象时隐式调用。
基本语法：

1
[修饰符] {
2
    // 逻辑语句
3
};

好处：是对构造器的补充，可将多个构造器中的重复语句抽取到初始化块中，提高代码重用性。
使用细节与执行顺序（非常重要！）：
1. 静态代码块：在类加载时执行，且只执行一次。可以初始化静态属性。
2. 普通代码块：在每次创建对象时执行，在构造器之前执行。
3. 执行顺序（继承关系下）：
  - 父类静态代码块 -> 子类静态代码块 -> 父类普通代码块 -> 父类构造器 -> 子类普通代码块 -> 子类构造器。
4. 普通代码块只能直接调用本类的静态成员，不能调用非静态成员（因为此时对象可能还未完全初始化）。

四、单例设计模式#

设计模式：在大量实践中总结出的优选代码结构、编程风格和解决问题的思考方式。
单例模式：保证在整个软件系统中，对某个类只能存在一个对象实例，并提供一个获取该实例的全局访问点。
实现步骤：
1. 构造器私有化（防止外部new）。
2. 类的内部创建对象。
3. 向外暴露一个公共的静态方法 (getInstance) 来获取该对象。
两种实现方式：
- 饿汉式：类加载时就创建对象实例。
  - 优点：线程安全（天然）。
  - 缺点：可能造成资源浪费（如果实例一直未被使用）。
- 懒汉式：使用时才创建对象实例。
  - 优点：避免资源浪费。
  - 缺点：存在线程安全问题（后续线程部分解决）。
应用实例：java.lang.Runtime 是经典的单例模式。

五、final关键字#

含义：最终的。可以修饰类、属性、方法和局部变量。
使用场景：
1. 修饰类：该类不能被继承（如String类）。
2. 修饰方法：该方法不能被重写/覆盖。
3. 修饰属性：该属性变为常量，值必须初始化且之后不能修改。
4. 修饰局部变量：该局部变量值不能修改。
使用细节：
1. final修饰的属性（常量）命名一般用XX_XX_XX（大写+下划线）。
2. final属性必须赋初值，赋值位置可选：
  - 定义时。
  - 在构造器中。
  - 在代码块中。
3. 如果final修饰的属性是静态的，则初始化位置只能是：
  - 定义时。
  - 在静态代码块中。（不能在构造器中）
4. final类不能继承，但可以实例化对象。
5. 含有final方法的非final类，该方法可以被继承，但不能被重写。

六、抽象类#

提出问题：父类方法需要声明，但无法确定具体实现（如Animal的eat方法）。
解决之道：使用abstract关键字。
- abstract修饰类 -> 抽象类。
- abstract修饰方法 -> 抽象方法（没有方法体）。
介绍：抽象类的价值更多在于设计，让子类继承并实现其抽象方法。是框架和设计模式中常用的知识点。
注意事项与细节：
1. 抽象类不能被实例化。
2. 抽象类不一定包含abstract方法。但一旦包含abstract方法，该类必须声明为abstract。
3. abstract只能修饰类和方法，不能修饰属性和其他。
4. 抽象类本质还是类，可以有任意成员（属性、方法、构造器、代码块等）。
5. 如果一个类继承了抽象类，则它必须实现父类的所有抽象方法，除非它自己也声明为abstract类。
6. 抽象方法不能使用private、final和static修饰，因为这些关键字与重写相违背。

七、抽象类最佳实践——模板设计模式#

介绍：抽象类体现了一种模板模式设计，作为多个子类的通用模板。子类在抽象类基础上扩展，但总体上保留抽象类的行为方式。
解决问题：当功能内部一部分实现是确定的，一部分不确定时。将不确定的部分暴露为抽象方法，让子类实现。
最佳实践案例：统计不同任务执行的时间。
- 在抽象父类 (Template) 中，定义计算时间的通用方法 (calculateTime)。
- 将具体任务 (job) 声明为抽象方法，由子类实现。
- 这样既统一了计时逻辑，又保留了子类任务的灵活性。

八、接口 (interface)#

为什么有接口：实现统一规范，解决高内聚低耦合的设计需求（类似于现实中的USB接口）。
快速入门：接口是更加抽象的抽象类。在JDK7.0及以前，接口中所有方法都是抽象方法（没有方法体）。JDK8.0后，接口可以有静态方法、默认方法（有具体实现）。
基本语法：

1
interface 接口名 {
2
    // 属性 (默认 public static final)
3
    // 方法 (默认 public abstract)
4
}
5
class 类名 implements 接口 {
6
    // 必须实现接口的所有抽象方法
7
}

核心定义

本质：一种行为规范（契约），定义了一组方法签名，但不包含具体实现（Java 8 之前）。
实例化：不能被实例化（new），不能有构造函数。
继承关系：类通过 implements 实现接口；接口通过 extends 继承其他接口（支持多重继承）。成员规则速查表

成员类型	默认修饰符	关键限制	备注
变量	public static final	必须是常量，声明即初始化	无法在实现类中修改
抽象方法	public abstract	实现类必须重写	核心契约
默认方法	default(Java 8+)	可有具体实现，可被重写	解决多继承冲突需显式调用Interface.super.method()
静态方法	static(Java 8+)	不可被继承或重写	只能通过接口名.方法()调用
私有方法	private(Java 9+)	仅接口内部可见	用于 default/static 方法的代码复用

三大关键陷阱与细节#

多继承冲突场景：类实现了两个接口，且这两个接口有同名的 default 方法。结果：编译报错。解决：实现类必须重写该方法，并使用 InterfaceName.super.methodName() 指定调用哪一个父接口的逻辑。优先级规则：抽象方法 > 默认方法。如果一个是抽象方法，一个是默认方法，实现类必须实现抽象方法（默认方法自动失效）。
访问权限控制对外：接口中的抽象方法和默认方法本质上都是 public。
重写规则：实现类在重写接口方法时，必须使用 public 修饰符，不能降低访问权限（如改为 protected或private）。
函数式接口 (Functional Interface) 定义：只包含一个抽象方法的接口。用途：Lambda 表达式的基础。
注解：推荐加上 @FunctionalInterface，编译器会检查是否只有一个抽象方法（允许有多个 default/static 方法）。

最佳实践建议#

接口隔离：保持接口小而专一，避免“胖接口”。
向后兼容：升级旧接口时，优先使用 default 方法添加新功能，避免破坏现有实现类。
代码复用：如果多个接口需要共享逻辑，优先考虑抽象类；如果必须用接口，利用 Java 9 的 private 方法在接口内部提取公共逻辑。
常量管理：虽然接口可以定义常量，但不要把接口当作纯粹的常量容器（Constant Interface 反模式），建议使用类或枚举来管理常量。

九、内部类#

1. 局部内部类#

定义：定义在方法体、构造器或代码块内部。
特点：
1. 可以直接访问外部类的所有成员（包含私有）。
2. 不能使用访问修饰符（public/private）或 static（地位如同局部变量），但可用final修饰。
3. 作用域仅限当前代码块，外部不可见。
4. 外部其他类不能访问局部内部类。
5. 如果外部类和内部类成员重名，默认就近原则，访问外部类成员用外部类名.this.成员。
6. 访问局部变量限制：只能访问 final 或 effectively final（初始化后未修改）的局部变量。
  - 原理：生命周期不一致（栈 vs 堆），Java 通过值复制实现闭包。
适用场景：逻辑仅在当前方法内使用，避免污染类结构。

2. 匿名内部类（极其重要！）#

定义：没有类名的内部类，定义即实例化。本质：同时是一个类、一个对象。特点：

本质是局部内部类的特例。
必须继承一个父类或实现一个接口。
不能定义构造函数（无名），不能定义静态成员。
this 指向匿名类实例本身。语法：

1
new 类/接口 (参数列表) {
2
    // 类体（重写方法或实现方法）
3
};

现代替代：若是函数式接口，优先使用 Lambda 表达式。

3. 成员内部类#

定义：位于外部类内部，与成员变量同级，无 static 修饰。
特点：
1. 可访问外部类所有成员（含私有）
2. 不能定义静态成员（static final 常量除外）。
3. 隐式持有外部类实例引用 (Outer.this)。
4. 可以添加任意访问修饰符（地位是一个成员）。
5. 作用域为整个类体。
6. 外部其他类访问成员内部类：
  - 外部类.内部类引用 = 外部类对象.new 内部类();
  - 通过外部类提供的返回内部类对象的方法。

实例化语法：

1
Outer outer = new Outer();
2
Outer.Inner inner = outer.new Inner(); // 必须依赖外部类实例

访问同名成员：

1
Outer.this.variableName; // 显式访问外部类成员

4. 静态内部类#

定义：位于外部类内部，使用 static 修饰。
特点：
1. 可以直接访问外部类的所有静态成员（含私有），不能直接访问非静态成员。
2. 可以定义静态成员。
3. 独立于外部类存在。
4. 不持有外部类实例引用（节省内存，防泄漏）。
5. 可以添加任意访问修饰符。
6. 作用域为整个类体。
7. 外部其他类访问静态内部类：
  - 外部类.内部类引用 = new 外部类.内部类(); （通过类名直接访问）
  - 通过外部类提供的返回静态内部类对象的方法。实例化语法：

1
Outer.StaticInner inner = new Outer.StaticInner(); // 直接 new

典型应用：
- 单例模式（静态内部类单例，线程安全且懒加载）。
- 工具类嵌套。

核心对比速查表#

特性	成员内部类	静态内部类	局部内部类	匿名内部类
static 修饰	❌	✅	❌	❌
外部类实例依赖	必须	不需要	视情况 (访问非静态需依赖)	视情况
访问外部私有成员	✅	仅静态成员	✅	✅
访问局部变量	N/A	N/A	仅 final/effectively final	仅 final/effectively final
定义静态成员	❌ (除常量)	✅	❌	❌
访问修饰符	public/private等	public/private等	无	无
主要用途	强耦合业务逻辑	解耦工具/单例	临时逻辑封装	一次性回调/监听

Lambda vs 匿名内部类#

推荐：Java 8+ 实现函数式接口时，首选 Lambda。
区别：
- Lambda 更简洁，编译器优化更好（复用 class 文件）。
- this 指向不同：Lambda 的 this 指向外部类；匿名内部类的 this 指向内部类。

48个音标

Sun, 01 Mar 2026 00:00:00 GMT

哎，学英语音标是不是总卡在“知道但念不准”的阶段？别硬啃PDF了，我直接给你整了个超清爽的48个音标小课堂——视频里每个音都带口型特写+对比纠音，连/j/和/w/这种易混音都帮你拎清楚了～边看边跟读，10分钟就能找回开口的信心！

英语词根

Sun, 01 Mar 2026 00:00:00 GMT

🔓Day01#

词根：radi#

核心含义：根（联想“抓地”的谐音记忆法）

引申义：由“根”引申为光线、辐射（如同树根向四周延伸）
词缀辅助：
后缀（如 -ate 表动词，-ant 表形容词，-ion/-um 表名词）

单词	词性	中文释义	拆解与记忆逻辑
radical	adj.	根本的；彻底的	radi (根) + -cal (形容词后缀) → 从“根”上的 → 根本的、彻底的
eradicate	v.	根除	e- (前缀：出/除去) + radi (根) + -ate (动词后缀) → 把根拔出来 → 根除、消灭
radiate	v.	辐射；发散；使显现	radi (根/光线) + -ate (动词后缀) → 像根/光线一样向外扩散 → 辐射、散发
radiant	adj.	辐射的；容光焕发的	radi (光线) + -ant (形容词后缀) → 向外散发着光的 → 容光焕发的、灿烂的
radio	n.	收音机	radi (辐射/无线电波) + -o (名词后缀) → 利用无线电波（辐射）传播声音的设备
radioactive	adj.	放射性的	radio (辐射) + active (活跃的) → 具有活跃辐射特性的 → 放射性的
radium	n.	镭	radi (辐射) + -um (化学元素名词后缀) → 一种具有强放射性的化学元素

🔓Day02#

词根：pose#

核心含义：摆放（联想“摆pose”的日常场景）

引申义：由“摆放”引申为放置、姿态、构成、提出等与“放置/安排”相关的含义
词缀辅助：结合之前学过的：
前缀（如 ex- 向外、com- 共同、pro- 向前、dis- 分开、op- 相反、de- 向下/除去）
后缀（如 -it, -ition, -ent 等）

单词	词性	中文释义	拆解与记忆逻辑
expose	v.	暴露；揭露；使显露	ex- (向外) + pose (摆放) → 把东西摆到外面 → 暴露、揭露
compose	v.	组成；创造；创作	com- (共同) + pose (摆放) → 把各部分摆在一起 → 组成、创作（如作曲/作文）
composition	n.	作文；作品；作曲	compos(e) (组成/创作) + -ition (名词后缀) → 创作的成果 → 作文、作品
composite	adj.	复合的；合成的	compos(e) (组成) + -ite (形容词/名词后缀) → 由多部分组成的 → 复合的
propose	v.	求婚；提名；提议	pro- (向前) + pose (摆放) → 把想法/计划摆到前面 → 提议、求婚
dispose	v.	扔掉；处理；安排	dis- (分开/离开) + pose (摆放) → 把东西摆到别处/移走 → 处理、扔掉
oppose	v.	反对	op- (相反) + pose (摆放) → 摆到对面/对立位置 → 反对
opponent	n.	敌人；对手	oppos(e) (反对) + -ent (表人的名词后缀) → 反对者 → 对手、敌人
depose	v.	废除；罢免	de- (向下/除去) + pose (摆放) → 把某人从位置上放下来 → 罢免、废除
deposit	n.	沉淀物；定金	de- (向下) + pos(e) (摆放) + -it → 向下放置的东西 → 沉淀物；存放的钱（定金）

🔓Day03#

词根：vers(t)#

核心含义：转（联想“转动的快速声响”）

引申义：由“转”引申为转变、转移、反转、转向等与“方向/状态改变”相关的含义
词缀辅助：前缀（如 re- 向后、a- 离开、con- 共同、di- 分开、intro- 向内、extro- 向外、ann(i)- 年、contro- 相反）

单词	词性	中文释义	拆解与记忆逻辑
reverse	v.	扭转；颠倒	re- (向后/相反) + verse (转) → 向反方向转 → 扭转、颠倒
avert	v.	转移（注意力）；避免	a- (离开) + vert (转) → 把目光/危险转开 → 转移、避免
convert	v.	转变；换算；改变信仰	con- (加强/共同) + vert (转) → 彻底转变形态/立场 → 转变、改信
divert	v.	转移；改道（注意力）	di- (分开/偏离) + vert (转) → 转离原方向 → 转移、改道
introvert	n./adj.	内向的人；内向的	intro- (向内) + vert (转) → 性格转向内心 → 内向的人/性格
extrovert	n./adj.	外向的人；外向的	extro- (向外) + vert (转) → 性格转向外部 → 外向的人/性格
anniversary	n.	周年纪念	anni- (年) + vers (转) + -ary (名词后缀) → 时间转了一年 → 周年纪念
controversy	n.	争论；争吵；争议	contro- (相反) + vers (转) + -y (名词后缀) → 观点转向对立 → 争论、争议

🔓Day04#

词根：press

核心含义：压（联想“按压、挤压”的动作，直观记忆词根含义）

引申义：由“压”进一步引申为压缩、按压、抑制、表达等与“施加压力/按压”相关的含义
词缀辅助：前缀（如 com- 共同、de- 向下、sup- 向下/在下面、im- 进入/使…、ex- 向外、re- 回/向后）

单词	词性	中文释义	拆解与记忆逻辑
compress	v.	压缩	com- (共同/一起) + press (压) → 一起往中间压 → 压缩、浓缩
depress	v.	使抑郁；使萧条/低迷	de- (向下) + press (压) → 向下压（情绪/经济）→ 使抑郁、使萧条
depression	n.	抑郁；萧条	depress (使抑郁/萧条) + -ion (名词后缀) → 抑郁、经济萧条
suppress	v.	镇压；抑制；控制	sup- (在下面/向下) + press (压) → 压在下面、压住 → 镇压、抑制
impress	v.	使印象深刻	im- (进入/使) + press (压) → 把印象压进脑海 → 使印象深刻
impressive	adj.	令人印象深刻的	impress (使印象深刻) + -ive (形容词后缀) → 令人印象深刻的
express	v. / adj. / n.	表达；特快的；快递	ex- (向外) + press (压) → 把想法/信息压出来 → 表达；快速传递 → 特快的、快递
repress	v.	抑制；忍住（感情）	re- (回/向后) + press (压) → 把感情压回去 → 抑制、忍住

英语词缀

Sun, 01 Mar 2026 00:00:00 GMT

一、核心方法：词根词缀拆解#

通过前缀（表词义）+ 词根（表核心义）+ 后缀（表词性）拆解单词，高效记忆。

示例：collaborate v. 合作

col-：前缀（同 com-），表“一起、共同”
labor：词根，表“劳动、劳作”
-ate：后缀，表“动词词性”
记忆逻辑：一起劳动 → 合作

二、前缀表（12类，表“义”）#

序号	核心含义	前缀变体	例词（附中文释义）
1	外 / 出	e / ex / ef	export(出口)
2	内 / 进	in / im	inject(注射)
3	前	pro / pre	progress(进步)；predict(预测)
4	回 / 重新 / 再次	re	return(返回)
5	聚集（一起 / 共同）	co / con / com / col	collaborate(合作)；connect(连接)
6	分散（分开）	di / dis / dif	divorce(离婚)；differ(不同)
7	上 / 超过	super / over / sur	superman(超人)；surpass(超越)
8	下 / 不足	under / de / sub / sup	underground(地下)；subway(地铁)
9	转移 / 转变	trans	transfer(转移)；translate(翻译)
10	相互之间	inter	internet(互联网)；interact(互动)
11	强调 / 无意义	a- + 双写辅音字母	accept(接受)；attract(吸引)
12	否定	un / in / im / dis / ab / il	unhappy(不开心)；impossible(不可能)

三、后缀表（3类，表“性”）#

1. 动词后缀（表“动作”）#

高频：-ate (约90%的动词以此结尾)
其他：-ize, -ify, -ish
例：collaborate (合作), activate (激活), realize (实现), simplify (简化)

2. 形容词后缀（表“属性”）#

常见：-ent/-ful/-ous/-al/-ive/-ible/-able/-ant
例：helpful (有帮助的), creative (有创造力的), possible (可能的)

3. 名词后缀（表“事物/状态”）#

常见：-ion/-tion/-ation/-ness/-ity/-ality/-ment/-ence/-ance/-ism
例：collaboration (合作，名词), happiness (幸福), development (发展)

类别	核心功能	常见后缀
1. 动词后缀	表动作 / 行为	-ate(高频，约 90%)、-ize、-ify、-ish
2. 形容词后缀	表属性 / 特征	-ent、-ful、-ous、-al、-ive、-ible、-able、-ant
3. 名词后缀	表事物 / 状态 / 性质	-ion、-tion、-ation、-ness、-ity、-ality、-ment、-ence、-ance、-ism

四、记忆技巧#

前缀定方向：看到 col-/com- 就想到“一起”，看到 re- 就想到“再次”。
词根定核心：抓住 labor (劳动)、port (搬运) 等核心含义。
后缀定词性：看到 -ate 大概率是动词，看到 -tion 大概率是名词。

计算机专用英语

Wed, 25 Feb 2026 00:00:00 GMT

Qwerty Learner网址：https://qwerty.kaiyi.cool/

⏱️day01#

单词	汉语
if	conj.如果
key	n.键，关键字，关键码
press	v.按，压
with	prep.用，与，随着
change	v.更换，改变，变动
program	n.程序
file	n.文件；v.保存文件
menu	n.菜单，目录
line	n.(数据，程序)行，线路
by	prep.凭，靠，沿
单词	汉语
from	prep.从，来自，以来
option	n.任选，选择，可选项
list	n.列表，显示，v.打印
directory	n.目录，索引簿
display	vt.显示，显示器
set	v.设置，n.集合
command	n.命令，指令
format	n.格式
cursor	n.光标
use	v.使用，用途
单词	汉语
specify	v.指定，规定，确定
database	n.数据库
box	n.箱，匣，(逻辑)框
character	n.字符，符号，特性
screen	n.屏幕，屏；v.屏蔽
record	n.记录
drive	v.驱动；n.驱动器
copy	n.复制，v.拷贝
type	n.型，类型；v.打印
memory	n.记忆存储，存储器
单词	汉语
move	v.移动
which	pron.哪个，a.那一个
see	v.看，看出，查看
disk	n.盘，磁盘
text	n.正文，文本
help	v.&,n.帮助
all	a.全，全部；ad.完全
name	n.名，名称；vt.命名
on	ad.接通，导电，开
current	n.电流

⏱️day02#

单词	汉语
also	ad.&,conj.也，亦，还
print	v.打印，印刷
procedure	n.过程，程序，工序
enter	v.键入，送入
shell	n.壳，外壳,·
select	vt.选择
selected	a.精选的
group	n.组，群
return	v.返回，回送
window	n.窗口
单词	汉语
information	n.信息，情报
field	n.字段，域，栏，场
number	n.数字，号码；vt.编号
want	v.需要，应该，缺少
delete	vt.删除，删去，作废
do	v.做，干；n.循环
choose	v.挑选，选择，选定
first	a.&,ad.&,n.第一，首先
margin	n.余量，边缘，边际
mark	n.标记；vt.加标记
单词	汉语
then	ad.&,conj.那时，则
each	a.&,ad.各(自)，每个
related	a.相关的
topic	n.题目，论题
item	n.项，项目，条款
message	n.信息，消息，电文
edit	vt.编辑，编排，编篡
string	n.行，字符串
start	v.起动，开始，启动
variable	a.可变的；n.变量
单词	汉语
example	n.例子，实例
insert	vt.插入
dialog	n.&,vt.对话
area	n.(区)域，面积，方面
tab	n.制表键
marked	a.有记号的
parameter	n.参数，参变量
up	ad.上，向上，a.高的
active	a.激活的，活动的
create	vt.创立，建立

⏱️day03#

单词	汉语










单词	汉语










单词	汉语










单词	汉语

⏱️day04#

单词	汉语










单词	汉语










单词	汉语










单词	汉语

Java基础

Fri, 06 Feb 2026 00:00:00 GMT

Java概述#

Java 语言是面向对象的(oop)、有跨平台性（一次编译到处运行）

Java 技术体系平台

JavaSE（Java Standard Edition）标准版
Java EE(Java Enterprise Edition）企业版
Java ME(Java Micro Edition)小型版

Java 语言是解释型的

解释性语言：javascript，PHP，java
编译性语言/ c++
- 区别是：解释性语言，编译后的代码。不能直接被机器执行,需要解释器来执行，
  编译性语言，编译后的代码，可以直接被机器执行，c/c++

Java 核心机制-Java 虚拟机 [JVM java virtual machine]

基本介绍：JVM是一个虚拟的计算机，具有指令集并使用不同的存储区域。负责执行指令，管理数据、内存、寄存器，包含在JDK 中。对于不同的平台，有不同的虚拟机。Java 虚拟机机制屏蔽了底层运行平台的差别，实现了“一次编译，到处运行“。

什么是JDK，JRE

JDK = JRE + 开发工具集（例如 Javac,java 编译工具等)
JRE = JVM+ Java SE 标准类库（java 核心类库）
如果只想运行开发好的.class 文件只需要 JRE

javac ：命令对该 java 文件进行编译，生成 .class 文件。
java ：命令对生成的 class 文件进行运行

Java常用转义字符

转义序列	含义	描述
‘	单引号	用于在字符常量’ ‘或字符串中包含单引号。
“	双引号	用于在字符串” “中包含双引号。
\	反斜杠	表示一个实际的反斜杠字符\。
\n	换行符	将光标移动到下一行的开头（Line Feed）。
\r	回车符	将光标移动到当前行的开头（Carriage Return）。 (注：Windows 换行通常是\r\n，Unix/Linux/macOS 通常是\n)
\t	制表符	插入一个水平制表符（Tab），通常相当于 4 或 8 个空格。
\b	退格符	将光标向后移动一格（Backspace）。
\f	换页符	用于打印机控制，表示换页（Form Feed）。
\0	空字符	ASCII 码为 0 的字符（Null），常用于 C 风格字符串结尾，Java 中较少直接使用。

初学java易犯错误

找不到文件：源文件名不存在或者写错，或者当前路径错误
主类名和文件名不一致：声明为public的主类应与文件名一致，否知编译失败
缺少分号：编译失败，注意错误出现的行数，再到源代码中指定位置改错。

注释

单行注释 //
多行注释 /* */
文档注释 /** */

变量#

变量的注意事项：

变量表示内存中的一个存储区域不同的变量，类型不同，占用的空间大小不同
变量必须先声明，后使用，即有顺序
变量在同一个作用域内不能重名
变量=变量名+值+数据类型，这一点请大家注意。变量三要素

数据类型#

基本数据类型：

类型	关键字	位数 (bit)	字节 (byte)	取值范围	默认值	说明
整数型	byte	8	1	-128 ~ 127	0	最小整数类型，常用于节省内存数组
	short	16	2	-32,768 ~ 32,767	0	较少使用
	int	32	4	-2³¹ ~ 2³¹-1	0	最常用的整数类型
	long	64	8	-2⁶³ ~ 2⁶³-1	0L	用于大整数，字面量需加L
浮点型	float	32	4	约 ±3.4E38 (7位有效数字)	0.0f	单精度，字面量需加F
	double	64	8	约 ±1.8E308 (15-17位有效数字)	0.0d	最常用的浮点类型
字符型	char	16	2	\u0000~\uffff(0 ~ 65535)	‘\u0000’	存储单个 Unicode 字符
布尔型	boolean	-	-	true或false	false	仅用于逻辑判断，大小由 JVM 决定

java数据类型分为两大类基本数据类型，引用类型

基本数据类型有8种：
数值型：[byte,short,int,long,float,double]
字符型：char
布尔型：boolean
引用类型[类，接口，数组]

JavaAPI文档#

网站：

下载

基本数据类型转换#

自动类型转换

规则：byte → short → char → int → long → float → double

1
  byte → short → int → long → float → double
2
         ↘ char ↗

细节：
- 有多种类型的数据混合运算时，系统首先自动将所有数据转换成容量最大的那种数据类型，然后再进行计算。
- 当我们把精度（容量）大的数据类型赋值给精度（容量）小的数据类型时，就会报错，反之就会进行自动类型转换。
- （byte，short）和char之间不会相互自动转换。
- byte，short，char 他们三者可以计算，在计算时首先转换为int类型。
- boolean不参与转换
- 自动提升原则：表达式结果的类型自动提升为操作数中最大的类型

强制类型转换

自动类型转换的逆过程，将容量大的数据类型转换为容量小的数据类型。使用时要加上强制转换符（)，但可能造成精度降低或溢出，格外要注意。

1
  目标类型 变量名 = (目标类型) 原值;

细节：当进行数据的大小从大一一>小，就需要使用到强制转换
强转符号只针对于最近的操作数有效，往往会使用小括号提升优先级
char类型可以保存int的常量值，但不能保存int的变量值，需要强转
byte和short，char类型在进行运算时，当做int类型处理。

基本数据类型和 String 类型的转换#

基本类型转String类型
语法：将基本类型的值+即可

String类型转基本数据类型【体验】
语法：通过基本类型的包装类调用parseXX方法即可

运算符#

算术运算符、赋值运算符、关系运算符 [比较运算符]、逻辑运算符、位运算符 [需要二进制基础]、三元运算符

算数运算符#

运算符	运算	范围	结果
+	正号	+7	7
-	负号	b=11; -b	-11
+	加	9+9	18
-	减	10-8	2
*	乘	7*8	56
/	除	9/9	1
%	取模(取余)	11%9	2
++	自增（前）：先运算后取值自增（后）：先取值后运算	a=2;b=++a; a=2;b=a++;	a=3;b=3 a=3;b=2
—	自减（前）：先运算后取值自减（后）：先取值后运算	a=2;b=—a; a=2;b=a—;	a=1;b=1 a=1;b=2
+	字符串相加	”hsp”+“edu"	"hsp edu”

细节说明：

对于除号 ”/“，它的整数除和小数除是有区别的
当对一个数取模时，可以等价表示为：a % b = a - (a / b) * b

示例：11 % 9 = 11 - (11/9)9 = 11 - 19 = 2
当自增当做一个独立语句使用时，不管是 ++i; 还是 i++; 都是一样的，等价于：→ i = i + 1;
当自增当做一个表达式使用时，
j = ++i 等价于：→ i = i + 1; j = i;
j = i++ 等价于：→ j = i; i = i + 1;

关系运算符#

运算符	运算	范例	结果
==	相等于	8 == 7	false
!=	不等于	8 != 7	true
<	小于	8 < 7	false
>	大于	8 > 7	true
<=	小于等于	8 <= 7	false
>=	大于等于	8 >= 7	true
instanceof	检查是否是类的对象	”hsp” instanceof String	true

细节说明：

关系运算符的结果都是boolean 型，也就是要么是 true，要么是 false。
关系运算符组成的表达式，我们称为关系表达式。a>b
比较运算符”==“不能误写成”=“

逻辑运算符#

a	b	a & b	a && b	a \| b	a \| b	!a	a ^ b
true	true	true	true	true	true	false	false
true	false	false	false	true	true	false	true
false	true	false	false	true	true	true	true
false	false	false	false	false	false	true	false

运算符	名称	类型	说明
&	按位与 / 逻辑与	位运算/逻辑	两边都为 true 才返回 true；无短路
&&	短路与	逻辑运算	左边为 false 时右边不执行，直接返回 false
\|	按位或 / 逻辑或	位运算/逻辑	任一边为 true 就返回 true；无短路
\|	短路或	逻辑运算	左边为 true 时右边不执行，直接返回 true
!	非	逻辑运算	取反
^	异或	位运算/逻辑	两边不同为 true，相同为 false

💡 注意：

虽然 &, |, ^ 可用于布尔值作逻辑运算，但它们也常用于整数的位运算。

而 &&, || 仅用于布尔逻辑，且具有“短路”特性。

📌 记忆口诀：

“与要全真才为真，或有一真即为真；
非是取反很简单，异或不同才是真；
短路运算效率高，左边决定右不跑！”

赋值运算符#

运算符	名称
=	基本赋值
+=	加后赋值
-=	减后赋值
*=	乘后赋值
/=	除后赋值
%=	取模后赋值
&=	按位与后赋值
\|=	按位或后赋值
^=	按位异或后赋值
<<=	左移后赋值
>>=	右移后赋值
>>>=	无符号右移后赋值

三元运算符#

条件表达式 ? 表达式 1: 表达式 2;

运算规则：

如果条件表达式为 true，运算后的结果是表达式 1；
如果条件表达式为 false，运算后的结果是表达式 2；

运算符优先级（熟悉即可）#

优先级	运算符	类型	结合性	示例
1	() [] .	括号、数组索引、成员访问	左 → 右	obj.method(),arr[0]
2	expr++ expr—	后缀自增/自减	左 → 右	i++,count—
3	++expr —expr + - ~ ! (type)	前缀操作符、正负号、按位非、逻辑非、强制类型转换	右 → 左	++i,-x,!flag,(int)y
4	* / %	乘、除、取模	左 → 右	a * b,x % 3
5	+ -	加、减	左 → 右	a + b,x - 1
6	<< >> >>>	移位运算	左 → 右	x << 2,y >>> 1
7	< > <= >= instanceof	关系运算	左 → 右	a > b,obj instanceof Class
8	== !=	相等性判断	左 → 右	x == 5,a != b
9	&	按位与	左 → 右	a & b
10	^	按位异或	左 → 右	a ^ b
11	\|	按位或	左 → 右	a \| b
12	&&	逻辑与	左 → 右	a && b
13	\|	逻辑或	左 → 右	a \| b
14	? :	三元条件运算符	右 → 左	cond ? a : b
15	= += -= *= /= %= &= ^= \|= <<= >>= >>>=	赋值运算	右 → 左	x = 5,sum += i

标识符命名规则和规范#

标识符概念：

Java 对各种变量、方法和类等命名时使用的字符序列称为标识符
凡是自己可以起名字的地方都叫标识符intnum1=90;

标识符的命名规则（必须遵守）

只能包含：字母（A-Z, a-z）、数字（0-9）、下划线（_）和美元符号（$）。
不能以数字开头，不可以使用关键字和保留字，但能包含关键字和保留字。
标识符不能包含空格。长度没有限制

软性规范（行业最佳实践）

命名风格（驼峰命名法）

大驼峰命名法：类名、接口名、枚举名、注解名
小驼峰命名法：方法名、变量名、参数名
常量名：全大写 + 下划线分隔
包名 (Package)：全小写 + 点号分隔

特殊场景规范

测试类：通常以被测试类名 + Test 结尾
异常类：以 Exception 或 Error 结尾
实现类：若接口名为 XxxService，实现类通常为 XxxServiceImpl

Java相关基础知识#

进制#

二进制：0,1，满2进1.以0b 或0B 开头

十进制：0-9，满10进1

八进制：0-7，满8进1．以数字0开头表示

十六进制：0-9 及 A(10)-F(15)，满16 进1．以0x或0X开头表示。此处的 A-F 不区分大小写

进制的转换

二进制转十进制：
规则：从最低位（右边）开始，将每个位上的数提取出来，乘以2的（位数-1）次方，然后求和。
案例：0b1011 → 十进制
```
1
0b1011 =
2
= 1*1 + 1*2 + 0*4 + 1*8
3
= 1 + 2 + 0 + 8 = 11
```
八进制转十进制：
规则：从最低位(右边)开始，将每个位上的数提取出来，乘以8的(位数-1)次方，然后求和。
案例：0234 → 十进制
```
1
0b1011 =
2
= 1*1 + 1*2 + 0*4 + 1*8
3
= 1 + 2 + 0 + 8 = 11
```
十六进制转十进制：
规则：从最低位(右边)开始，将每个位上的数提取出来，乘以16的(位数-1)次方，然后求和。
案例：0x1A3 → 十进制
```
1
0x1A3 =
2
= 3×16⁰ + A×16¹ + 1×16²
3
= 3×1 + 10×16 + 1×256 = 3 + 160 + 256 = 419
```

Java基础

Fri, 06 Feb 2026 00:00:00 GMT

一、集成开发环境 (IDE)#

1. IDEA 介绍与使用#

IDEA (IntelliJ IDEA) ：业界公认的优秀Java开发工具，支持多种语言。

基本使用：以项目 (Project) 为单位管理Java源码。

常用快捷键 (可自定义)：

删除当前行：Ctrl + D
复制当前行：Ctrl + Alt + ↓
代码补全：Alt + /
注释/取消注释：Ctrl + /
自动导包 & 优化导入：Alt + Enter
格式化代码：Ctrl + Alt + L
快速运行：Alt + R
生成代码 (构造器、Getter/Setter等)：Alt + Insert
查看类层级关系：Ctrl + H
定位到方法定义：Ctrl + B
自动分配变量名：表达式.var

重要设置：

主题与字体：File -> Settings -> Appearance & Behavior / Editor -> Font
字符编码：File -> Settings -> Editor -> File Encodings 设置为 UTF-8。

二、包 (Package)#

1. 包的作用#

区分同名类：解决多人开发时的命名冲突。
管理类：将功能相似的类组织在一起，便于管理和查找（参考Java API文档结构）。
控制访问范围：配合访问修饰符使用（见第三部分）。

2. 包的本质与使用#

本质：就是文件夹/目录，用于保存和管理.class文件。

定义语法：package 包名; (必须放在源文件第一行)。

命名规范：小写字母 + 小圆点。通常为：com.公司名.项目名.业务模块名。例如：com.sina.crm.user。

常用包：

java.lang.*：基本包，默认自动引入。
java.util.*：工具包（如Scanner, Arrays）。
java.net.*：网络开发包。
java.awt.*：图形界面开发包。

引入包 (import) ：

语法：import 包名.类名; 或 import 包名.*; (导入该包下所有类)。
位置：位于package语句之后，类定义之前。
建议：需要哪个类就导入哪个，不建议使用*通配符。

网络教室脱离控制方法

Tue, 18 Nov 2025 00:00:00 GMT

免责声明：仅供学习交流，后果自负。首先，教程针对此版本，其他版本未尝试，自行甄别。

方案一（首发）：#

删除 C:\Program Files (x86)\Os-Easy\os-easy multicast teaching system\MultiClient.exe，如图所示。此方法需在被控制前使用，使用后脱离教师端投屏。收发作业、消息等功能均正常，除了教师端可以看见你的电脑页面外，简直完美，故写在前面。

可能遇到的问题：

解决方案：1、断网：控制面板禁用以太网。2、关闭软件，详见方案二。恢复方案：在回收站恢复删除，几秒后立马被控。

方案二、关闭软件#

1，使用密码退出，默认密码为 OSeasy。 2，使用其他软件强制关闭。 3，使用任务管理器 + 断网关闭，网上有教程。缺点：在教师端显示离线

方案三、断网，不赘述。#

方案四、修改配置文件#

打开图上任意程序，点击保存后，无法连接到教师端。缺：教师端显示下线，万一收发作业等等，没救。（让朋友帮你交）

方案五、#

使用浏览器访问教师端 ip+ 端口，教师端投屏瘫痪，详细端口号自行摸索，不提供端口号。缺：全部学生脱控，没有隐蔽性。教师端没有提示，重启教师端恢复。