5.7.2 改了代码必须改文档——PR 流程
一句话破题
最好的文档更新时机是改代码的时候，而不是"以后再补"。
代码与文档同步更新
什么时候需要更新文档
| 代码变更类型 | 需要更新的文档 |
|---|---|
| 新增 API 接口 | API 文档 |
| 修改接口参数 | API 文档 |
| 添加新功能 | 使用指南 |
| 修改配置方式 | 部署文档 |
| 修改数据库结构 | 架构文档 |
PR 提交规范
包含文档更新的 commit 信息：
bash
# 功能开发 + 文档
feat: 添加文章搜索功能
- 实现关键词搜索 API
- 添加搜索结果分页
- 更新 API 文档
# 修复 Bug + 文档
fix: 修复登录超时问题
- 延长 token 有效期
- 更新认证文档说明
# 单独文档更新
docs: 更新部署文档
- 添加 Docker 部署说明
- 修正环境变量配置PR 检查清单
在提交 PR 前，检查：
markdown
## PR 检查清单
### 代码
- [ ] 代码能正常运行
- [ ] 通过所有测试
- [ ] 没有 lint 错误
### 文档
- [ ] API 变更是否更新了 docs/api.md
- [ ] 新功能是否添加了使用说明
- [ ] 配置变更是否更新了 README
- [ ] 数据库变更是否更新了架构文档独立开发者的简化流程
一个人开发时，流程可以简化：
关键是养成习惯：
- 每次改代码问自己："这个改动需要更新文档吗？"
- 如果需要，立刻更新，不要拖延
文档更新的最佳时机
❌ 不好的做法
1. 写完所有代码
2. 项目要上线了
3. 想起来还没写文档
4. 补文档（已经忘了很多细节）
✅ 好的做法
1. 写 API 代码
2. 立刻写 API 文档
3. commit: "feat: 添加用户注册接口"
4. 继续下一个功能让 AI 帮你写文档
你：我刚写了一个用户登录 API，帮我写文档
POST /api/auth/login
参数：email, password
返回：user 对象和 token
AI：## POST /api/auth/login
用户登录接口。
### 请求参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| email | string | 是 | 用户邮箱 |
| password | string | 是 | 用户密码 |
### 成功响应
\`\`\`json
{
"user": {
"id": "user_123",
"email": "user@example.com",
"name": "张三"
},
"token": "eyJhbGciOiJIUzI1NiIs..."
}
\`\`\`
### 错误响应
| 状态码 | 错误码 | 说明 |
|--------|--------|------|
| 400 | MISSING_EMAIL | 邮箱不能为空 |
| 401 | INVALID_CREDENTIALS | 邮箱或密码错误 |实用建议
- 代码和文档同一个 commit：保证版本对应
- 不要拖延：写完代码立刻写文档
- 用 AI 加速：让 AI 生成文档草稿
- 简洁为上：文档够用就行，不必过度详细