7.7 KiB
7.7 KiB
内容规范（CONTRIBUTING）
本仓库是结构化的学习内容：既能直接在 Git 平台上阅读，也能被以后的在线学习平台导入。所有新增、修改的内容都按本规范写，提交前运行校验脚本。
1. 目录结构
zhuangang/
├── README.md # 仓库入口
├── CONTRIBUTING.md # 本文件：内容规范
├── catalog.json # 自动生成的内容目录（不要手改）
├── schema/frontmatter.schema.json
├── tools/
│ ├── build_catalog.py # 校验 + 生成 catalog.json
│ ├── gen_week_topics.py # 根据 week 字段生成周计划的“本周相关专题”
│ ├── run_examples.py # 运行示例代码（Python / Go / TypeScript / 单文件 Java）
│ └── check_sensitive.py # 提交前脱敏检查（第 8 周建立）
├── plan/ # 16 周学习计划（日程），链接到专题，不重复讲概念
│ ├── README.md # 总纲
│ └── weekNN-*.md # type: week
├── topics/ # 专项学习：按领域 / 技术栈组织
│ ├── index.md
│ └── <domain>/<stack>/
│ ├── index.md # type: index，技术栈首页：学习路线、课程列表
│ ├── NN-<slug>.md # type: lesson，课程，NN 是顺序
│ ├── scenarios/<slug>.md # type: scenario，该技术栈的企业场景
│ ├── interview.md # type: interview，分级面试题
│ └── examples/ # 可运行的示例代码
├── scenarios/ # 跨技术栈的企业服务场景（type: scenario，domain: cross）
│ ├── index.md
│ └── <slug>.md
└── research/ # 岗位调研记录（type: research，domain: plan），只记录实际看到的内容
domain取值：backend（Go、数据库、缓存、消息队列、微服务）、devops（Docker、Nginx、Linux、CI/CD、Git）、python、ai（RAG、Agent 等）、frontend、cs（计算机基础：算法、网络与操作系统、Web 安全）、cross（跨栈场景）、plan（计划）。<stack>是技术栈标识，只用小写字母、数字和-，例如redis、grpc-microservices、fe-testing-perf。
2. frontmatter
每个 .md 文件（examples/ 下的除外）第一行开始是 frontmatter。为了让校验脚本不依赖第三方库，只允许两种写法：键: 标量 和 键: [a, b, c]（列表写在一行）。
---
id: backend.redis.cache-patterns
title: 缓存模式：旁路缓存与穿透、击穿、雪崩
type: lesson
domain: backend
stack: [redis]
tags: [缓存, 高并发, 一致性]
level: intermediate
prerequisites: [backend.redis.data-structures]
est_hours: 2
related: [backend.redis.interview, scenario.flash-sale]
week: [3, 14]
order: 2
---
| 字段 | 必填 | 说明 |
|---|---|---|
id |
是 | 全局唯一、发布后不再修改（平台用它做进度记录和链接）。格式：小写字母数字，用 . 分段 |
title |
是 | 标题 |
type |
是 | index / lesson / scenario / interview / project / week / research（岗位调研记录，放在 research/） |
domain |
是 | 见上 |
stack |
lesson、scenario、interview 必填 | 列表；跨栈场景写多个 |
level |
lesson、scenario、interview 必填 | basic（基础）/ intermediate（进阶）/ advanced（高级） |
tags |
否 | 关键词，平台用于搜索 |
prerequisites |
否 | 先修内容的 id |
related |
否 | 相关内容的 id |
est_hours |
否 | 预计学习小时数 |
week |
否 | 在 16 周计划的哪几周用到（1~16） |
order |
否 | 同一技术栈内的排序 |
id 约定：
| 内容 | id 格式 | 例子 |
|---|---|---|
| 技术栈首页 | <domain>.<stack>.index |
backend.redis.index |
| 课程 | <domain>.<stack>.<slug> |
backend.redis.cache-patterns |
| 技术栈场景 | <domain>.<stack>.scenario.<slug> |
backend.redis.scenario.leaderboard |
| 面试题 | <domain>.<stack>.interview |
backend.redis.interview |
| 跨栈场景 | scenario.<slug> |
scenario.flash-sale |
| 计划 | plan.index、plan.weekNN |
plan.week03 |
3. 各类型的写法
课程（lesson）
必须包含以下二级标题（标题里包含这些词即可，可以加后缀）：
## 解释说明：是什么、为什么，用大白话；和 JS / 前端经验类比更好。## 案例：在真实业务里用在哪。## 代码示例：最小、正确、能运行；代码块写语言标记。较长的完整示例放进examples/，在正文里链接。## 易错点：常见错误和原因。- 可选：
## 面试常问（链接到本技术栈的interview.md）、## 延伸阅读。
场景（scenario）
企业服务场景解决方案，必须包含：
## 业务背景与问题## 约束：规模、性能、成本、合规、团队等限制条件## 方案设计：架构图（mermaid）、关键流程、数据模型## 关键代码## 取舍：为什么选这个方案、放弃了什么## 易错点## 面试怎么讲：一段 1~2 分钟的讲法 + 可能的追问
面试题（interview）
- 每道题一个三级标题，必须以级别开头：
### 【基础】…、### 【进阶】…、### 【场景题】…。校验脚本按这个格式统计题数。 - 题目下面写
**参考答案**，再写**追问**（常见的追问和要点）。 - 能结合项目的写上“在本计划的哪个项目里体现”。
计划（week）
- 日程安排：每天的任务、要建的文件、运行方式、完成标准。
- 概念讲解放在专题里，计划文件用链接引用，不重复写。项目的分步实现代码保留在计划文件里（type 仍为
week）。
4. 写作规则
- 中文写作，术语第一次出现时附英文。
- 代码必须正确：能运行的示例放进
examples/并能被tools/run_examples.py跑通；需要外部服务的在文件开头写不自动运行，并说明怎么手动运行。 - 更新快的框架（LangChain、LangGraph、MCP、Vite、Next.js、Nuxt 等）标注“以官方文档为准”并附链接，写明验证时的版本。
- 脱敏：不出现公司内部项目名、代码、接口路径、表名、内网地址、密钥、客户数据。场景都用通用的业务描述。
- 不编造数据：性能数字、统计数字必须注明来源，或写成“以实测为准”。
- 链接一律用相对路径，校验脚本会检查链接是否存在。
5. 提交前
python3 tools/build_catalog.py # 校验并更新 catalog.json
python3 tools/gen_week_topics.py # 修改了 week 字段时，重新生成周计划的“本周相关专题”
python3 tools/run_examples.py # 运行示例（可加关键词只跑部分，例如 redis）
python3 tools/check_sensitive.py # 脱敏检查（如果已经按第 8 周装好钩子，会自动执行）
6. 给学习平台的导入说明
- 以
catalog.json为入口：stacks是技术栈列表（含课程数、场景数、各级面试题数、示例路径），items是全部内容（frontmatter + 文件路径 + 二级标题列表 + 面试题统计）。 - 内容正文就是 Markdown 文件本身（去掉 frontmatter）；mermaid 图需要前端渲染。
- 学习进度按
id记录；prerequisites可以生成学习路线图，week可以生成日程视图。 - 面试题可以按
### 【级别】标题切分成单题，**参考答案**和**追问**是固定的小标题。