# system-arch-notes

**Repository Path**: wangxiaopeng2/system-arch-notes

## Basic Information

- **Project Name**: system-arch-notes
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-19
- **Last Updated**: 2026-10-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 系统架构设计学习笔记（System Architecture Notes）

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
[![Docs: Markdown](https://img.shields.io/badge/docs-markdown-000000.svg)](./README.md)

个人长期维护的**软件架构设计学习库**：沉淀开源项目调研、架构方法、领域建模、分布式与数据基础设施等主题的学习笔记，以及每一次架构判断背后的证据与取舍。

> 本仓库只存放**知识资产**（文档、模板、索引、实验结论），不镜像第三方项目源码。可运行的案例代码放在独立仓库中，见 [docs/repository-map.md](./docs/repository-map.md)。

---

## 这个仓库解决什么问题

学习架构最容易出现三个问题：收藏了一堆链接但从不回看、读过源码却讲不清边界为什么这样划分、做出的判断没有证据支撑。

本仓库用统一的目录、模板和索引来对抗这三点：

1. **可检索**——任何一篇笔记都能从 [总索引](./docs/index.md) 出发按主题或时间找到。
2. **可比较**——同类项目使用相同的分析维度记录，便于横向对照。
3. **可追溯**——重要判断落成 ADR，写明备选方案、代价、验证方式与复查条件。

学习目标的完整阐述见：
- [架构学习型代码库建设调研报告](./notes/2026/2026-10-19-架构学习型代码库调研报告.md)
- [通用架构学习型代码库调研报告](./notes/2026/2026-10-19-通用架构学习型代码库调研报告.md)
- [值得学习的开源项目架构清单](./notes/2026/2026-10-19-值得学习的开源项目架构清单.md)

---

## 快速开始

```bash
git clone git@github.com:<your-name>/system-arch-notes.git   # 换成你的远端地址
cd system-arch-notes
```

不需要安装任何依赖即可阅读。唯一的约定是：**新增文件前先看 [CONTRIBUTING.md](./CONTRIBUTING.md) 的命名与模板规则**。

若需要本地预览：

```bash
# 任选其一，安装后阅读体验更好
npx markdownlint-cli2 "**/*.md"      # 检查 Markdown 规范
npx markdown-link-check README.md    # 检查外链是否失效
```

---

## 目录结构

```text
system-arch-notes/
├── README.md                  # 入口：定位、导航、约定
├── LICENSE                    # MIT
├── CONTRIBUTING.md            # 写作与提交规范
├── .gitignore                 # 忽略本地环境、编辑器与构建产物
├── .gitattributes             # 换行符、文本/二进制识别、GitHub 语言统计
├── .editorconfig              # 跨编辑器编码与缩进约定
├── .markdownlint.jsonc        # Markdown 规范配置
├── docs/                      # 仓库自身的说明性文档
│   ├── index.md               # 总索引（按主题 / 按时间 / 按项目）
│   ├── adr/                   # 架构决策记录（本学习库自身的决策）
│   ├── glossary.md            # 术语表：DDD、C4、CAP、Saga…
│   ├── learning-roadmap.md    # 学习路线与阶段性目标
│   ├── note-conventions.md    # 笔记类型的定义与写作约定
│   ├── repository-map.md      # 周边案例仓库、上游开源项目的索引
│   └── faq.md                 # 常见问题与排障
├── notes/                     # 按年份归档的笔记（主体内容）
│   └── 2026/
├── reading/                   # 面向“读源码”的产出
│   ├── projects/              # 每个开源项目一份：架构摘要、调用链、故障模型
│   ├── reading-notes/         # 阅读过程中的线索与摘录
│   └── experiments/           # 最小复现实验：假设、步骤、结果、结论
├── topics/                    # 按架构主题组织的专题笔记（见下方"主题目录"）
├── templates/                 # 模板：复制后改名使用，不直接编辑
│   ├── adr/
│   ├── review/
│   ├── project-analysis.md
│   ├── reading-note.md
│   └── experiment.md
├── assets/                    # 图片与图表源文件
│   └── diagrams/              # PlantUML / Mermaid 源文件，导出图与源并置
└── scripts/                   # 轻量校验脚本（链接检查、命名检查）
```

### 各目录的边界

| 目录 | 放什么 | 不放什么 |
|---|---|---|
| `notes/<年>/` | 一次成形的完整笔记、调研报告、复盘 | 半成品草稿（先放本地 `drafts/`，被忽略） |
| `reading/projects/` | 针对**一个上游项目**的架构分析 | 跨项目的比较（放 `topics/`） |
| `reading/reading-notes/` | 阅读过程中的问题、线索、待验证假设 | 已得结论（升格到 `projects/` 或 `topics/`） |
| `reading/experiments/` | 可重复的最小实验记录 | 没有结论的压测截图 |
| `topics/` | 跨项目、可复用的架构主题知识 | 单个项目的实现细节 |
| `docs/adr/` | **本学习库自身**的组织与工具决策 | 业务案例的架构决策（放在案例仓库里） |
| `assets/` | 图、架构图源文件、截图 | 大的二进制数据集（放对象存储，只留链接） |

### 主题目录（`topics/`）

| 目录 | 覆盖主题 | 典型笔记 |
|---|---|---|
| `topics/domain-modeling/` | DDD、限界上下文、聚合、模块边界 | 聚合边界如何确定、贫血模型与充血模型 |
| `topics/distributed/` | 一致性、消息、容错、分布式事务 | Outbox、Saga、幂等与重试、熔断限流 |
| `topics/data-infrastructure/` | 存储、索引、流处理、元数据 | 日志式存储、LSM 与 B+Tree、Checkpoint |
| `topics/platform/` | 云原生、网关、身份、可观测性 | 声明式 API 与控制循环、OIDC、Trace 模型 |
| `topics/engineering/` | 构建、CI、架构测试、ADR 实践 | 架构断言测试、依赖规则校验 |

未被上述主题覆盖的内容，新建目录前先在 [docs/adr/](./docs/adr/) 记录理由。

---

## 文件命名规则

```text
notes/YYYY/YYYY-MM-DD-<标题>.md          # 例：2026-10-19-架构学习型代码库调研报告.md
reading/projects/<项目名小写>.md          # 例：temporal.md、keycloak.md
topics/<主题>/<kebab-case>.md            # 例：topics/distributed/outbox-pattern.md
docs/adr/NNNN-<决策>.md                  # 例：docs/adr/0001-note-structure.md
templates/<类型>.md
```

- 日期前缀是**成文日期**，不是修改日期；后续修改直接提交，不改文件名。
- 中文标题保留中文，但不含空格、`/`、`\`、`:`、`?`、`*`、`"`、`<`、`>`、`|` 等字符。
- 主题目录与 ADR 文件名一律用英文 kebab-case，便于跨平台与工具处理。

---

## 笔记写作约定（摘要）

完整版见 [docs/note-conventions.md](./docs/note-conventions.md)。

1. **每篇笔记必须有前言元信息**：日期、状态（草稿/在维护/已归档）、关联主题、来源。
2. **结论先行**：开头用 3—5 行写清"这篇笔记解决了什么问题、结论是什么"。
3. **区分事实、推断与待验证**：引用的外部信息给出来源链接；自己的判断标注为判断；未验证的写进"待验证假设"。
4. **图表可重生成**：架构图优先用 Mermaid/PlantUML 源文件存放在 `assets/diagrams/`，避免只提交不可追溯的截图。
5. **记录未采用的方案**：只写"采用了什么"价值有限，"为什么不采用另一个"才是架构能力的体现。

---

## 维护节奏

| 频率 | 动作 |
|---|---|
| 每次阅读/实验后 | 新增或更新对应笔记；在 [docs/index.md](./docs/index.md) 登记一行 |
| 每周 | 整理 `reading/reading-notes/` 中已经闭环的内容，升格为 `projects/` 或 `topics/` 笔记 |
| 每月 | 复查陈旧笔记：标注"已过期"或补充现状；更新 ADR 中被替代的决策 |
| 每季度 | 对照 [learning-roadmap.md](./docs/learning-roadmap.md) 复盘阶段目标 |

---

## 贡献与许可

- 提交规范、模板使用方法见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
- 引用第三方项目内容时，必须在笔记末尾注明来源与许可证，不整段复制受限制许可的文档。
- 本仓库内容采用 [MIT License](./LICENSE)（Copyright © 2026 王大鹏）。

---

## 免责声明

笔记内容反映**写作当时**的认知与上游项目的状态。开源项目演进很快，引用具体代码位置或版本行为时请在笔记中标注版本号；若与最新版本不符，以官方文档为准。