长文结构化

文档骨架

可固定章节顺序：摘要 → 背景与约束 → 方案对比 → 决策记录 → 风险与缓解 → 待办与 owner → 附录。每条决策尽量对应 ADR 编号或 Issue，便于追溯与自动化检查。

# RFC 文档完整模板（可直接复制使用）
---
title: "RFC-042: 统一认证服务重构"
status: "Draft"  # Draft | Review | Accepted | Rejected | Superseded
authors: ["@alice", "@bob"]
created: 2024-04-10
reviewers: ["@charlie", "@security-team"]
---

## TL;DR（不超过 3 句话）
将分散在 4 个服务中的 JWT 验证逻辑统一到 auth-gateway，
通过 sidecar 模式注入，减少重复代码 ~2000 行，
并统一刷新 token 的并发竞态保护。

## 背景与动机
- 现状：每个服务独立维护 JWT 验证逻辑，bug 需多处修复
- 触发事件：INC-3421 暴露 token 刷新竞态，影响 3% 用户
- 目标：单点维护、统一审计、简化服务接入流程

## 方案对比
| 方案 | 优点 | 缺点 | 推荐 |
|------|------|------|------|
| A. 共享库 | 轻量，无新服务 | 各服务独立升级，仍有版本漂移 | — |
| B. Auth Gateway Sidecar | 统一升级，强隔离 | 增加延迟 ~2ms，需 k8s 改造 | ✓ |
| C. Service Mesh Policy | 平台级，零代码 | 团队无 Istio 经验，引入新依赖 | — |

## 决策记录
**选择方案 B**。理由：可逐服务接入，延迟可接受，团队有 Go 经验。
拒绝 A：解决不了版本漂移根本问题。
拒绝 C：学习成本与运维复杂度超出当前阶段。

## 风险与缓解
| 风险 | 可能性 | 影响 | 缓解措施 |
|------|--------|------|----------|
| Sidecar 成为新单点 | 低 | 高 | 熔断降级，直通模式兜底 |
| 延迟增加 > SLO | 中 | 中 | 灰度接入，监控 P99 |

## 待办与 Owner
- [ ] @alice：sidecar 原型 + 单元测试（2024-05-01）
- [ ] @bob：接入 user-service 并采集基准延迟（2024-05-15）
- [ ] @security-team：安全评审（2024-05-20）

## 时间线
- 2024-04-10：RFC 草稿
- 2024-04-20：评审会，收集反馈
- 2024-05-01：Accepted / Rejected 决策

## 附录
- 参考：[JWT 刷新竞态分析](https://wiki.internal/inc-3421)
- 废弃方案归档：见本文件 git 历史

• 决策：主选方案、备选、取舍理由；拒绝「显然更好」式表述。
• 附录：术语表、参考链接、废弃段落归档，避免正文被外链打断。

评审闭环

长文的价值在「可被评审、可被合并、可被检索」。草稿阶段允许结构松散；进入评审后，评论应落到具体章节或小节标题，解决后更新正文并留下 ADR / PR 链接，而不是只在聊天里达成一致。

# 大型 PR 拆分策略：将大功能拆成可独立合并的小 PR

# 功能：「统一认证服务」（总计约 3000 行变更）

# PR 1/4：基础设施层（无业务逻辑变更，可独立合并）
# - 新增 auth-gateway sidecar 基础代码骨架
# - 添加配置项（feature flag 默认 off）
# - 单元测试覆盖基础路径
# 大小目标：< 400 行，评审时间 < 30 min

# PR 2/4：数据层（依赖 PR 1，可独立验证）
# - JWT 验证核心逻辑迁移
# - Token 刷新竞态保护（mutex + 缓存）
# - 集成测试

# PR 3/4：接入 user-service（依赖 PR 1+2，灰度）
# - user-service 切换到 sidecar 验证
# - 保留旧逻辑作降级路径（特性开关控制）
# - 监控基准延迟

# PR 4/4：全量接入 + 清理旧代码（依赖前三个 PR 全合并后）
# - 其余服务切换 + 删除重复验证代码
# - 移除特性开关

# 关键原则：每个 PR 都能独立回滚，不依赖后续 PR 才能工作

  [ 草稿 / 大纲 ]
                    │
                    ▼
            [ 结构自检：层级 ≤ 约定深度 ]
                    │
                    ▼
              [ 发起评审 / 评论锚定章节 ]
                    │
           ┌────────┴────────┐
           ▼                 ▼
    [ 需补充材料? ]     [ 可合并结论? ]
           │                    │
           │ yes                │ yes
           ▼                    ▼
    [ 更新「待确认事实」]   [ 合并正文 + 链接 ADR/PR ]
           │                    │
           └────────┬───────────┘
                    ▼
            [ 发布 / 归档版本号 ]

大纲层级自检

将 Markdown 式标题（以 # 开头）粘贴到下方，本页会估算最大标题深度以及各层级数量。一般技术方案正文建议 H1 仅一篇文档标题、正文从 H2 起跳，避免层级过深导致目录与 diff 难以阅读。