这份规范用于统一 Java 知识库每个章节的写法。目标不是把文档写成 API 字典，而是让新手能建立概念，高级开发者能理解机制，资深开发者能看到工程取舍、线上风险和面试表达方式。

1. 章节定位

每篇文档开头必须回答三个问题：

问题	写作要求
它是什么	用 2 到 4 句话定义概念，避免只堆术语
它解决什么问题	写出真实业务或 JVM/框架中的使用场景
学它要抓住什么	明确本篇核心机制、边界和常见坑

推荐开头模板：

`主题名` 是 Java 中用于解决 XXX 问题的机制。它常出现在 XXX 场景中。

学习这一节不要只记 API，更重要的是理解：

- 核心模型是什么。
- 底层如何工作。
- 适合和不适合哪些场景。
- 开发中有哪些常见坑。

2. 标准结构模板

每篇文档建议按以下结构组织。

---
title: 章节标题
date: 2026-06-25 00:00:00
article: false
permalink: /pages/唯一路径/
---

开篇定位：是什么、解决什么问题、为什么重要。

## 1. 核心概念

用简单语言讲清楚概念，给出最小可运行示例。

## 2. 结构模型

用 text 图、表格或 Mermaid 描述结构。

## 3. 执行流程

用流程图解释关键动作如何发生。

## 4. 常用 API

按场景分组，不要罗列所有方法。

## 5. 底层机制

解释源码思想、JVM 机制、数据结构或协议模型。

## 6. 典型场景

写真实开发场景和推荐代码。

## 7. 常见坑

写错误示例、原因、修复方式。

## 8. 选型与对比

与相近技术做表格对比。

## 9. 面试表达

把复杂知识压缩成可复述答案。

## Tips 快问快答

**Q：高频问题？**
A：简洁回答。

3. 内容深度标准

每个知识点至少覆盖五层。

层次	要求	示例
概念层	说清楚是什么	volatile 保证可见性
使用层	给出典型代码	状态开关示例
机制层	解释为什么	happens-before、内存屏障
边界层	说明不能做什么	不能保证 i++ 原子性
工程层	给出实践建议	单变量状态标记可用，复合状态用锁

只写概念和 API 不算完成。每篇至少要包含：

• 1 个核心结构图或流程图。
• 1 张对比表或速查表。
• 1 个正确示例。
• 1 个常见错误示例或风险说明。
• 1 个开发建议清单。
• 1 个 Tips 快问快答 区块。

4. 图表规范

优先使用文本图，复杂关系可用 Mermaid。

4.1 结构图

HashMap
├─ table: Node[]
├─ size
├─ threshold
└─ loadFactor

4.2 流程图

提交任务
  │
  ▼
核心线程是否满
  │
  ├─ 否：创建核心线程
  └─ 是：进入队列

4.3 对比表

对比项	A	B
底层结构	动态数组	双向链表
适合场景	随机访问	头尾操作

图表要服务理解，不要为了“好看”而堆装饰。

5. 代码示例规范

代码示例必须满足：

• 能表达一个明确知识点。
• 变量名贴近业务。
• 不写无意义的 foo/bar。
• 错误示例必须说明为什么错。
• 生产建议要包含超时、关闭、异常处理等边界。

推荐：

try (ExecutorService executor = Executors.newFixedThreadPool(4)) {
    Future<User> future = executor.submit(() -> queryUser(userId));
    User user = future.get(1, TimeUnit.SECONDS);
}

不推荐：

new Thread(() -> doSomething()).start();

如果确实展示裸线程，要说明它为什么不适合生产代码。

6. Tips 快问快答规范

每篇文档末尾必须包含 Tips 快问快答。

要求：

• 8 到 12 个问题。
• 覆盖概念、机制、边界、开发坑、面试表达。
• 回答尽量短，但必须准确。
• 不要出现“看情况”这种空回答，要说明看什么条件。

模板：

## Tips 快问快答

**Q：这个机制解决什么问题？**
A：回答一句话。

**Q：它最大的坑是什么？**
A：回答原因和规避方式。

7. Java 知识面覆盖清单

Java 章节整体应覆盖以下知识面。

模块	必须覆盖
Java 基础	语法、类型、OOP、数组、String、包装类、Object、泛型、枚举、注解、反射、值传递、Lambda、Stream、Optional、日期时间、现代语法
Java 集合	Collection/Map 体系、List、Set、Map、Queue、Iterator、Collections、排序、选型、fail-fast、不可变集合
Java 并发	线程、任务模型、线程安全、JMM、synchronized、volatile、wait/notify、线程池、AQS、Atomic、Lock、并发容器、CompletableFuture、虚拟线程、死锁排查
Java IO	IO 体系、字节流、字符流、缓冲流、文件、NIO、Buffer、Channel、Selector、零拷贝、序列化、大文件、乱码、性能、面试题
JVM	类加载、字节码、内存区域、对象布局、GC、垃圾回收器、JIT、锁优化、工具、线上排查、调优方法论

8. 章节完成标准

一篇文档完成前检查：

• 是否有清晰开篇定位。
• 是否解释了底层模型。
• 是否有结构图或流程图。
• 是否覆盖常用 API。
• 是否说明适用场景和不适用场景。
• 是否给出错误示例或常见坑。
• 是否有工程实践建议。
• 是否包含面试表达。
• 是否包含 Tips 快问快答。
• 是否没有行尾空白和无效链接。

9. 语言风格

• 面向开发者，不写教材腔。
• 少用空泛形容词，多写判断条件。
• 不把源码整段复制进文档，只保留关键逻辑。
• 同一个概念第一次出现时解释清楚，后续使用简称。
• 对“不推荐”的写法必须说明替代方案。
• 对版本相关内容要写清版本，例如 Java 8、Java 17、Java 21。

10. 总结模板

每篇结尾可以用一段总结收束。

## 总结

本节的核心是：XXX。开发中优先使用 XXX；当出现 XXX 场景时，再考虑 XXX。面试回答时要同时说清概念、底层机制和使用边界。

这份规范后续用于约束 Java 章节所有新增和重写内容，避免章节之间深浅不一、风格不一、只讲 API 不讲机制的问题。