全站技术知识库建设规范

这个站点不是只用来存放零散笔记，而是要建设成一套可以从零基础学习到商业项目落地、面试表达和线上排查的技术知识库。

以后新增或扩写任何技术文档，都必须围绕三个目标：

1. 小白能看懂：术语第一次出现要解释，不默认读者已经知道。
2. 原理能讲清：不能只给标准答案，要讲为什么这样设计，如果不用会怎样。
3. 项目能落地：每个核心知识点都要有流程图、代码 Demo、商业常见场景和排查思路。

全站学习主线

flowchart TD
    A["语言基础"] --> B["数据结构和常用 API"]
    B --> C["并发、IO、网络和运行时原理"]
    C --> D["Spring、ORM、安全和工程框架"]
    D --> E["数据库、缓存、消息队列和搜索"]
    E --> F["分布式架构、事务、一致性和治理"]
    F --> G["DevOps、可观测性和线上排查"]
    G --> H["AI、Python、Go 和跨技术场景"]
    H --> I["面试表达和商业项目复盘"]

学习顺序不是为了限制阅读，而是为了避免“会背框架配置，但不知道为什么线上会挂”。例如线程池打满，表面看是 Spring 接口慢，根因可能是 Java 并发、数据库连接池、下游超时、MQ 消费积压和 JVM 线程资源共同作用。

每篇文档必须回答的问题

问题	文档中应该怎么体现	如果缺失会怎样
这是什么	用零基础能懂的话定义概念	读者只能背名词
为什么需要	说明它解决了什么真实问题	不知道什么时候该用
怎么工作	给出流程图、调用链、关键数据结构	只能停留在 API 层
为什么这样设计	说明设计取舍和历史原因	面试追问答不上来
不这样会怎样	说明错误用法、故障后果、性能问题	项目里容易踩坑
怎么写 Demo	提供最小可运行代码或配置	读完不会落地
商业场景怎么用	贴近订单、支付、采集、库存、搜索、权限、批处理、监控排查	内容变成空泛博客
面试怎么答	给出标准回答并跳转原理页	面试页和知识点脱节

推荐文档结构

每个核心知识点建议按下面结构组织：

---
layout: doc
title: 知识点标题
---

# 知识点标题

## 学习目标
## 为什么需要
## 核心概念
## 工作原理图
## 原理详解
## 代码 Demo
## 商业常用场景
## 常见坑和排查
## 面试标准回答
## 关联知识点

不是每篇都必须机械套模板，但必须覆盖这些能力。内容越底层，越要多讲“为什么”；内容越工程化，越要多讲“配置、场景、排查、边界”。

Java 版本基准规则

Java 相关文档不能只基于 JDK 21。企业项目、面试和老系统维护里，JDK 7 和 JDK 8 仍然非常重要。因此 Java 文档统一采用下面规则：

flowchart TD
    A["先讲 JDK 7 及以前的基础能力"] --> B["重点讲 JDK 8 企业主流能力"]
    B --> C["补充 JDK 9 到 11 的工程变化"]
    C --> D["补充 JDK 17 的现代语法和长期支持"]
    D --> E["补充 JDK 21 及之后的新能力"]
    E --> F["每个差异说明旧版本怎么写、新版本怎么写、为什么变化"]

具体要求：

1. 基础语法、集合、线程池、JVM、Spring 老项目兼容，优先讲清 JDK 7/8 写法。
2. Lambda、Stream、Optional、CompletableFuture、java.time 作为 JDK 8 重点独立讲。
3. 模块化、HTTP Client、var、record、sealed、switch 表达式、虚拟线程等作为版本演进讲。
4. 每个新特性都要解释“旧版本怎么解决、痛点是什么、新版本解决了什么、项目是否建议使用”。
5. 面试题必须能区分 JDK 7、JDK 8、JDK 11、JDK 17、JDK 21 的常见差异。

Mermaid 图规范

流程图要清楚，不追求一张图画完所有东西。

推荐：

flowchart TD
    A["请求进入系统"] --> B["参数校验"]
    B --> C{"是否通过"}
    C -- "是" --> D["执行业务逻辑"]
    C -- "否" --> E["返回明确错误"]

注意：

1. 优先使用 flowchart TD，避免横向过宽。
2. 节点文字包含中文、括号、冒号、逗号时要加双引号。
3. 一个图最好只表达一个流程，不把架构、异常、重试、排查全塞进一张图。
4. 面试页可以用小图帮助记忆，原理页负责详细图。

Demo 规范

代码 Demo 不是为了“看起来有代码”，而是为了让读者能自己运行并验证原理。

类型	Demo 要求
Java 基础	提供单文件 main 方法，能直接 javac 和 java 运行
Spring/Spring Boot	提供依赖、配置、核心类、请求示例
数据库	提供建表 SQL、查询 SQL、EXPLAIN 或事务步骤
Redis/MQ/ES	提供最小配置、生产者消费者或读写示例、失败场景
DevOps	提供命令、配置文件、验证方式、排障命令
Python/Go	提供可直接运行的脚本或最小项目结构

面试页和知识点页关系

面试页负责“怎么答”，知识点页负责“为什么”。

flowchart TD
    A["面试问题"] --> B["标准回答"]
    B --> C["追问点"]
    C --> D["跳转知识点页"]
    D --> E["原理、流程图、Demo、排查"]

标准回答应该短、准、能背；知识点页应该深、细、能学会。不能把所有原理都堆到面试页，也不能让知识点页只有几句定义。

模块补齐优先级

优先级	模块	原因
P0	JavaSE、线程池、JVM、Spring Cloud、MySQL、Redis、MQ、分布式事务、ES、定时任务	面试高频，项目高频，线上问题高频
P1	Spring、Spring Boot、Spring Security、ORM、Netty、信息安全、DevOps	商业项目主干能力
P2	Python、AI、Spring AI、Go、MongoDB、工作流、设计模式	独立体系和扩展能力

优先级不代表不重要，而是落地顺序。每个模块最终都要达到同一质量标准。

质量检查清单

每次批量补文档后都要检查：

1. npm run build 是否通过。
2. 侧边栏链接是否都能打开。
3. Mermaid 是否渲染，不出现大面积不可读图。
4. 是否存在未完成标记、临时内容或空壳内容。
5. 每个核心页是否有原理图、Demo、商业场景、常见坑、面试回答。
6. 面试页是否跳转到对应知识点页。
7. Java 文档是否明确 JDK 7/8 和后续版本差异。

本章小结

全站文档的核心不是“数量多”，而是“点进去能学会”。每一个知识点都要把定义、原理、流程、代码、场景、坑点、排查和面试连起来。尤其 Java 相关内容必须以 JDK 7/8 为企业基础主线，再讲 JDK 11、17、21、25 的演进差异。