144 lines
7.7 KiB
Markdown
144 lines
7.7 KiB
Markdown
# 内容规范（CONTRIBUTING）
|
||
|
||
本仓库是**结构化的学习内容**：既能直接在 Git 平台上阅读，也能被以后的在线学习平台导入。所有新增、修改的内容都按本规范写，提交前运行校验脚本。
|
||
|
||
## 1. 目录结构
|
||
|
||
```text
|
||
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]`（列表写在一行）。
|
||
|
||
```yaml
|
||
---
|
||
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. 写作规则
|
||
|
||
1. 中文写作，术语第一次出现时附英文。
|
||
2. **代码必须正确**：能运行的示例放进 `examples/` 并能被 `tools/run_examples.py` 跑通；需要外部服务的在文件开头写 `不自动运行`，并说明怎么手动运行。
|
||
3. 更新快的框架（LangChain、LangGraph、MCP、Vite、Next.js、Nuxt 等）标注“以官方文档为准”并附链接，写明验证时的版本。
|
||
4. **脱敏**：不出现公司内部项目名、代码、接口路径、表名、内网地址、密钥、客户数据。场景都用通用的业务描述。
|
||
5. 不编造数据：性能数字、统计数字必须注明来源，或写成“以实测为准”。
|
||
6. 链接一律用相对路径，校验脚本会检查链接是否存在。
|
||
|
||
## 5. 提交前
|
||
|
||
```bash
|
||
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` 可以生成日程视图。
|
||
- 面试题可以按 `### 【级别】` 标题切分成单题，`**参考答案**` 和 `**追问**` 是固定的小标题。
|