名称: 黄金路径 描述: 用于设计标准化开发工作流程、铺平道路或意见化默认设置时使用。涵盖黄金路径模式、模板设计、开发者工作流程优化和护栏。 允许工具: 读取、全局搜索、文本搜索
黄金路径
设计标准化、意见化开发工作流程的模式，使正确的方式成为最容易的方式。
何时使用此技能
- 设计标准化开发者工作流程
- 为常见模式创建铺平道路
- 构建基于模板的服务创建
- 实施具有灵活性的护栏
- 优化开发者入门
- 减少开发者的认知负荷
黄金路径基础
什么是黄金路径？
黄金路径定义：
一种意见化、得到良好支持的工作流程，使最佳实践
成为最小阻力的路径，同时不阻止替代方案。
关键特征：
┌─────────────────────────────────────────────────────────────┐
│ 黄金路径 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ✓ 意见化: 为你做出明确决策 │
│ ✓ 支持: 一流的文档和工具 │
│ ✓ 优化: 到生产的最快路径 │
│ ✓ 维护: 由平台团队保持更新 │
│ ✓ 可逃脱: 需要时可以偏离 │
│ │
│ "使正确的方式成为最容易的方式" │
│ │
│ 黄金路径 ≠ 唯一路径 │
│ 黄金路径 = 推荐路径 │
│ │
└─────────────────────────────────────────────────────────────┘
vs 铺平道路 vs 轨道：
├── 黄金路径：具有替代方案的推荐工作流程
├── 铺平道路：相同概念，Spotify术语
├── 轨道：更刚性，更难偏离（通常负面）
黄金路径 vs 自定义
黄金路径益处：
开发者时间：
├── 新服务：15分钟（黄金） vs 2天（自定义）
├── 设置CI/CD：自动 vs 4-8小时
├── 可观察性：内置 vs 手动集成
└── 安全：自动 vs 清单审查
平台支持：
├── 黄金路径：完全支持，快速修复
├── 自定义：尽力支持，优先级较低
├── 混合：仅支持平台组件
示例旅程：
黄金路径：
┌─────────────────────────────────────────────────────────────┐
│ 1. 选择模板 → node-api-template │
│ 2. 回答问题 → 名称、团队、数据库？ │
│ 3. 生成仓库 → 自动 │
│ 4. 首次部署 → 通过CI自动 │
│ 5. 开始编码 → 专注于业务逻辑 │
│ │
│ 时间：约15分钟 │
│ 结果：生产就绪服务 │
└─────────────────────────────────────────────────────────────┘
自定义路径：
┌─────────────────────────────────────────────────────────────┐
│ 1. 创建仓库 → 手动设置 │
│ 2. 选择框架 → 研究选项 │
│ 3. 设置构建 → 配置打包器/编译器 │
│ 4. 添加可观察性 → 集成日志、指标 │
│ 5. 安全审查 → 清单、手动修复 │
│ 6. 设置CI/CD → 编写流水线配置 │
│ 7. 部署流水线 → 调试问题 │
│ 8. 文档 → 从零编写 │
│ │
│ 时间：2-5天 │
│ 结果：可能错过最佳实践 │
└─────────────────────────────────────────────────────────────┘
设计黄金路径
识别候选
黄金路径选择标准：
高价值候选：
├── 频繁：由许多团队定期执行
├── 复杂：容易出错
├── 关键：安全/合规影响
├── 昂贵：手动花费大量时间
└── 可标准化：团队间的常见模式
评估矩阵：
┌────────────────────────────────────────────────────────────┐
│ 频率 │
│ 低 高 │
│ ┌─────────────┬─────────────┐ │
│ 高 │ 自定义 │ 黄金路径 │ ← 高影响 │
│ │ 解决方案 │ 优先级 │ │
│ 影响 ├─────────────┼─────────────┤ │
│ 低 │ 忽略 │ 文档/ │ │
│ │ │ 自动化 │ │
│ └─────────────┴─────────────┘ │
└────────────────────────────────────────────────────────────┘
常见黄金路径：
1. 新服务创建（按服务类型）
2. 数据库配置
3. CI/CD流水线设置
4. 安全扫描集成
5. 可观察性设置
6. 环境创建
7. API开发工作流程
8. 前端应用设置
模板设计原则
模板设计：
1. 意见化默认
├── 做出决策，开发者无需抉择
├── 选择成熟技术
├── 使用合理配置
└── 记录为何做出选择
2. 最小必要输入
├── 服务名称
├── 团队/所有者
├── 1-3个关键配置选择
└── 其他有默认值
3. 完整包
┌─────────────────────────────────────────────────────────┐
│ 模板内容： │
│ │
│ 应用层： │
│ ├── 应用代码骨架 │
│ ├── 配置管理 │
│ ├── 健康检查端点 │
│ └── API文档设置 │
│ │
│ 质量层： │
│ ├── 单元测试框架 │
│ ├── 集成测试设置 │
│ ├── 代码检查和格式化 │
│ └── 预提交钩子 │
│ │
│ 运维层： │
│ ├── Dockerfile │
│ ├── Kubernetes清单 │
│ ├── CI/CD流水线 │
│ └── 基础设施即代码 │
│ │
│ 可观察性层： │
│ ├── 结构化日志 │
│ ├── 指标仪表化 │
│ ├── 分布式追踪 │
│ └── 仪表板模板 │
│ │
│ 文档层： │
│ ├── README模板 │
│ ├── ADR模板 │
│ ├── 运行手册模板 │
│ └── API规范 │
└─────────────────────────────────────────────────────────┘
4. 清晰扩展点
├── 添加业务逻辑的位置
├── 如何添加新端点
├── 如何集成依赖
└── 如何自定义行为
模板架构
模板实现模式：
1. 脚手架/生成（Backstage, Yeoman）
输入 → 模板 + 变量 → 生成的仓库
优点：简单，完全控制
缺点：生成的代码随时间分歧
2. Cookiecutter/Copier
模板仓库 → 变量替换 → 新仓库
优点：易于维护模板
缺点：生成后更新困难
3. 基础镜像/库模式
┌─────────────────────────────────────────────────────────┐
│ 应用代码 │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 公司基础库 │ │
│ │ ├── 日志（预配置） │ │
│ │ ├── 指标（预配置） │ │
│ │ ├── 追踪（预配置） │ │
│ │ ├── HTTP客户端（带重试） │ │
│ │ └── 健康检查（标准） │ │
│ └─────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 公司基础镜像 │ │
│ │ ├── 运行时（Node, Go, .NET） │ │
│ │ ├── 安全补丁 │ │
│ │ └── 标准工具 │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
优点：更新自动传播
缺点：需要版本策略
4. 单一仓库与生成器
集中模板 → 生成到单一仓库
优点：一致性，共享工具
缺点：单一仓库复杂性
护栏与灵活性
护栏设计
护栏：自动执行标准而不阻塞。
护栏类型：
1. 预防性（阻止发生前）
├── 预提交钩子
├── PR检查
├── 模板验证
└── 基础设施策略
2. 检测性（发生后警报）
├── 合规扫描
├── 漂移检测
├── 审计日志
└── 安全扫描
3. 纠正性（自动修复问题）
├── 自动格式化
├── 自动修复
├── 自愈基础设施
└── 自动回滚
护栏实施：
┌─────────────────────────────────────────────────────────────┐
│ 开发生命周期 │
│ │
│ 代码 ──► 提交 ──► PR ──► 合并 ──► 部署 ──► 生产 │
│ │ │ │ │ │ │ │
│ ▼ ▼ ▼ ▼ ▼ ▼ │
│ [检查] [预提交] [PR检查] [构建门] [部署策略] [运行时监控] │
│ [格式化] │ │ │ │ │
│ │
│ 每个阶段的护栏： │
│ ├── IDE: 实时反馈，自动修复 │
│ ├── 提交: 秘密扫描，代码检查 │
│ ├── PR: 测试，安全扫描，批准 │
│ ├── 构建: 漏洞扫描，合规 │
│ ├── 部署: 金丝雀，健康检查 │
│ └── 运行时: 异常检测，自动扩展 │
└─────────────────────────────────────────────────────────────┘
逃脱舱口
逃脱舱口：需要时如何偏离黄金路径。
原则：
├── 使偏离可能但有意向
├── 要求理由，而非批准
├── 不因合法需求惩罚团队
└── 从偏离中学习以改进路径
逃脱舱口模式：
1. 文档化例外
# .platform/exceptions.yaml
exceptions:
- rule: 必须使用公司基础镜像
reason: "ML工作负载需要特定CUDA版本"
approved-by: 平台团队
expires: 2024-12-31
review-issue: PLAT-1234
2. 分层支持
┌─────────────────────────────────────────────────────────┐
│ 层级1：黄金路径 │
│ - 完全支持 │
│ - 自动更新 │
│ - 优先级错误修复 │
│ │
│ 层级2：支持偏离 │
│ - 文档化例外 │
│ - 尽力支持 │
│ - 可能需要手动更新 │
│ │
│ 层级3：自定义 │
│ - 自支持 │
│ - 无保证 │
│ - 必须满足最低安全标准 │
└─────────────────────────────────────────────────────────┘
3. 覆盖机制
# pipeline.yaml
lint:
enabled: true
override: true # 为此仓库跳过
override-reason: "遗留代码，lint修复计划于Q2"
常见黄金路径
服务创建路径
服务创建黄金路径：
┌─────────────────────────────────────────────────────────────┐
│ 步骤1：选择模板 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 可用模板： │
│ ○ REST API (Node.js) - 标准HTTP API │
│ ○ REST API (Go) - 高性能API │
│ ○ REST API (.NET) - 企业API │
│ ● GraphQL服务 - 灵活API层 │
│ ○ 事件消费者 - Kafka/消息处理 │
│ ○ 定时任务 - 批处理/cron工作负载 │
│ │
│ [继续使用GraphQL服务] │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ 步骤2：配置服务 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 服务名称： _________ (烤肉串式，例如，用户服务) │
│ 所有者团队： [▼ 选择团队 ] │
│ 描述： _________________________________________ │
│ │
│ 可选功能： │
│ ☑ 数据库（PostgreSQL） │
│ ☐ 缓存（Redis） │
│ ☑ 消息队列（Kafka消费者） │
│ ☐ 外部API客户端 │
│ │
│ [创建服务] │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ 步骤3：自动设置（60秒） │
├─────────────────────────────────────────────────────────────┤
│ │
│ ✓ 仓库创建 github.com/org/用户服务 │
│ ✓ CI/CD流水线配置 Actions工作流创建 │
│ ✓ 开发环境就绪 用户服务.dev.internal │
│ ✓ 数据库配置 PostgreSQL在RDS上 │
│ ✓ 秘密配置 Vault路径创建 │
│ ✓ 监控设置 Datadog仪表板创建 │
│ ✓ 注册到目录 Backstage条目创建 │
│ │
│ [打开仓库] [在目录中查看] [开始编码] │
└─────────────────────────────────────────────────────────────┘
部署路径
部署黄金路径：
开发者工作流程：
┌─────────────────────────────────────────────────────────────┐
│ │
│ 1. 开发者推送到特性分支 │
│ └── 自动：检查、测试、构建、安全扫描 │
│ │
│ 2. 开发者打开PR │
│ └── 自动：预览环境、E2E测试 │
│ │
│ 3. PR批准并合并 │
│ └── 自动：部署到暂存环境 │
│ │
│ 4. 暂存验证（自动 + 手动） │
│ └── 自动：冒烟测试、合成监控 │
│ │
│ 5. 生产部署 │
│ └── 自动：金丝雀 → 渐进式推出 │
│ │
│ 标准部署无需手动步骤 │
└─────────────────────────────────────────────────────────────┘
流水线配置：
# 模板中预配置
# 开发者仅在需要时修改
deploy:
staging:
trigger: merge-to-main
strategy: rolling
tests: [smoke, integration]
production:
trigger: staging-success
strategy: canary
canary-percentage: 5
canary-duration: 15m
rollback: automatic
采用策略
推出黄金路径
采用阶段：
阶段1：试点（1-2个团队，1-2个月）
├── 与友好团队合作
├── 收集密集反馈
├── 快速迭代
├── 构建成功故事
└── 记录学习
阶段2：早期采用者（5-10个团队，2-3个月）
├── 扩展到感兴趣团队
├── 基于反馈优化
├── 构建冠军网络
├── 创建培训材料
└── 测量采用指标
阶段3：早期多数（30-50%团队，3-6个月）
├── 营销和沟通
├── 培训会议
├── 自助服务文档
├── 弃用旧路径
└── 跟踪DORA指标
阶段4：晚期多数（70-90%团队，6-12个月）
├── 新服务强制使用
├── 现有服务迁移支持
├── 高级功能
├── 优化和持续改进
└── 持续改进
采用战术：
├── 使黄金路径比替代方案更快
├── 提供迁移工具
├── 庆祝早期采用者
├── 快速解决障碍
├── 不强制过早采用
└── 听取抵制者（他们发现真实问题）
测量成功
黄金路径指标：
采用指标：
├── % 新服务使用模板
├── % 团队至少有一个黄金路径服务
├── 按类型模板使用
├── 偏离率（为何团队不使用）
└── 迁移率（遗留到黄金路径）
效率指标：
├── 首次部署时间（新服务）
├── 生产变更时间
├── PR周期时间
├── 事件解决时间
└── 开发者节省时间
质量指标：
├── 部署成功率
├── 安全扫描通过率
├── 变更失败率
├── 事件率（黄金 vs 自定义）
└── 合规审计发现
满意度指标：
├── 开发者NPS为平台
├── 模板满意度调查
├── 支持工单量
├── 文档有效性
└── 入门体验评分
反模式
黄金路径反模式：
1. "一刀切黄金路径"
❌ 相同模板用于微服务和ML工作负载
✓ 不同用例多个路径
2. "轨道，非路径"
❌ 使偏离不可能或受罚
✓ 偏离可能需理由
3. "技术纯度高于实用性"
❌ 选择团队难以使用的流行技术
✓ 使用团队能实际使用的技术
4. "设置后忘记"
❌ 创建路径后永不更新
✓ 基于反馈持续改进
5. "无价值强制"
❌ 强制采用前路径不佳
✓ 使路径好到团队想使用
6. "隐藏复杂性"
❌ 隐藏所有复杂性，无学习机会
✓ 渐进式披露复杂性
7. "无逃脱舱口"
❌ 阻止合法偏离
✓ 明确例外流程
最佳实践
黄金路径最佳实践：
1. 从痛点开始
├── 访谈开发者关于摩擦
├── 测量当前到生产时间
├── 识别最常见任务
└── 首先专注于最高影响路径
2. 使正确方式容易
├── 黄金路径应比替代方案更快
├── 默认应安全且合规
├── 文档集成到工作流程
└── 错误应指导解决方案
3. 基于反馈迭代
├── 定期用户研究
├── 快速迭代周期
├── A/B测试改进
└── 优雅弃用
4. 平衡意见化与灵活性
├── 具有明确理由的强大默认
├── 记录为何做出选择
├── 允许覆盖需理由
└── 从偏离中学习
5. 投资文档
├── 入门指南
├── 决策解释
├── 故障排除指南
└── 迁移指南
6. 构建社区
├── 每个团队冠军
├── 定期办公时间
├── 贡献指南
└── 庆祝成功
相关技能
内部开发者平台- 平台工程概述自助服务基础设施- 基础设施配置模式设计面试方法论- 面试准备质量属性分类法- 理解质量要求