name: team-api-design description: 定义团队接口、合同和通信边界 allowed-tools: Read, Glob, Grep, Write, Edit
团队API设计技能
何时使用此技能
在以下情况下使用此技能：
- 团队API设计任务 - 处理定义团队接口、合同和通信边界的工作
- 规划或设计 - 需要团队API设计方法的指导
- 最佳实践 - 希望遵循已建立的模式和标准
概述
使用团队API模式定义清晰的团队接口、合同和通信边界。
强制要求：文档优先方法
在设计团队API之前：
- 调用
docs-management技能以获取团队接口模式 - 通过MCP服务器（如perplexity）验证团队API概念
- 基于Team Topologies团队API框架提供指导
什么是团队API？
团队API：团队向其他团队暴露的显式接口
┌─────────────────────────────────────────────────────────────────┐
│ 团队API │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 代码与 │ │ 版本控制 │ │ 服务目录 │ │
│ │ 工件 │ │ 与发布 │ │ │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Wiki与 │ │ 实践与 │ │ 工作方式 │ │
│ │ 文档 │ │ 操作手册 │ │ │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 聊天与 │ │ 办公时间 │ │ 支持轮换 │ │
│ │ 频道 │ │ │ │ │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
目的：使团队交互显式化、可预测且可持续
团队API组件
1. 代码和工件
技术接口：
代码库：
• 主代码库位置（URL）
• 贡献指南
• 代码审查期望
• 分支命名约定
API：
• OpenAPI/AsyncAPI规范
• 认证要求
• 速率限制和配额
• 弃用政策
工件：
• 包注册表位置
• 容器镜像注册表
• 工件版本控制方案
• 发布说明位置
2. 版本控制和发布
发布接口：
版本控制：
• 语义版本控制（主版本.次版本.补丁版本）
• 破坏性变更政策
• 弃用时间表
• 迁移指南
发布计划：
• 发布频率（每周、双周、持续）
• 发布窗口
• 热修复流程
• 回滚程序
兼容性：
• 支持的版本
• 终止支持公告
• 向后兼容性保证
• 向前兼容性方法
3. 文档
知识接口：
团队Wiki：
• 团队概述和使命
• 架构决策记录（ADRs）
• 设计文档
• 入门指南
API文档：
• 入门指南
• API参考
• 代码示例
• 常见问题解答和故障排除
操作文档：
• 操作手册
• 事件响应程序
• 监控仪表板
• 警报解释
4. 通信渠道
通信接口：
异步：
• 主要Slack/Teams频道
• 公告频道
• 错误/问题跟踪器
• 电子邮件分发列表
同步：
• 办公时间安排
• 值班轮换
• 升级路径
• 会议频率
响应时间：
• Slack：4个工作日小时
• 问题：1个工作日
• 紧急：1小时
• 事件：15分钟
5. 服务水平期望
服务接口：
可用性：
• 目标正常运行时间（99.9%）
• 维护窗口
• 计划停机通知期限
性能：
• 延迟目标（p50，p99）
• 吞吐量限制
• 错误率目标
支持：
• 工作时间支持
• 值班可用性
• 事件严重级别
• 解决时间目标
团队API模板
# 团队API：[团队名称]
## 团队概述
**使命：** [一句话使命声明]
**团队类型：** [流对齐 | 平台 | 赋能 | 复杂子系统]
**有限上下文：** [拥有的领域]
## 团队成员
| 角色 | 姓名 | 联系方式 |
|------|------|---------|
| 技术负责人 | [姓名] | @handle |
| 产品负责人 | [姓名] | @handle |
| 工程师 | [姓名] | @handles |
## 我们拥有的内容
### 服务
| 服务 | 描述 | 代码库 |
|---------|-------------|------------|
| [名称] | [目的] | [URL] |
### API
| API | 规范 | 状态 |
|-----|------|--------|
| [名称] | [OpenAPI URL] | [稳定/测试/alpha] |
## 如何联系我们
### 异步
- **Slack：** #team-[名称]
- **问题：** [Jira/GitHub项目URL]
- **电子邮件：** team-[名称]@company.com
### 同步
- **办公时间：** [星期/时间]
- **值班：** [PagerDuty URL或轮换]
### 响应时间
| 渠道 | 预期响应 |
|---------|------------------|
| Slack | 4个工作日小时 |
| 问题 | 1个工作日 |
| 紧急Slack | 1小时 |
| 事件 | 15分钟 |
## 如何与我们合作
### 请求变更
1. 在[代码库]中打开问题
2. 参加办公时间讨论
3. 提交PR，遵循[贡献指南]
### 使用我们的API
1. 阅读[入门指南]
2. 通过[流程]请求API凭证
3. 遵循[速率限制指南]
### 升级路径
1. 在#team-[名称]中发帖
2. 如果紧急，呼叫值班人员
3. 如果受阻，直接联系技术负责人
## 服务水平期望
### 可用性
- **目标：** 99.9%正常运行时间
- **维护窗口：** [星期/时间]
- **通知期限：** 计划停机48小时
### 性能
- **p50延迟：** [X]毫秒
- **p99延迟：** [X]毫秒
- **错误率：** <0.1%
### 支持
- **工作时间：** 9am-5pm [时区]
- **值班时间：** 24/7，适用于P1/P2
- **假期覆盖：** [政策]
## 版本控制和发布
### 发布频率
- **频率：** [每周/双周/持续]
- **发布日：** [星期]
- **变更日志：** [位置]
### API版本控制
- **策略：** [URL路径 | 头部 | 查询参数]
- **破坏性变更通知：** [X周]
- **弃用期限：** [X个月]
### 当前支持的版本
| 版本 | 状态 | 终止支持日期 |
|---------|--------|----------|
| v3 | 当前 | N/A |
| v2 | 维护 | [日期] |
| v1 | 弃用 | [日期] |
## 文档
### 对于用户
- [入门指南]
- [API参考]
- [代码示例]
- [常见问题解答]
### 对于贡献者
- [贡献指南]
- [架构概述]
- [开发设置]
- [测试指南]
### 操作
- [操作手册]
- [监控仪表板]
- [事件响应]
## 依赖关系
### 我们的依赖
| 团队/服务 | 类型 | 关键性 |
|--------------|------|-------------|
| [名称] | [API/库/数据] | [高/中/低] |
### 依赖我们的内容
| 团队/服务 | 接口 | 使用方式 |
|--------------|-----------|-------|
| [名称] | [API/事件/库] | [描述] |
## 路线图
### 当前季度
- [倡议1]
- [倡议2]
### 下一季度
- [计划工作]
### 已知限制
- [限制1]
- [限制2]
团队API治理
创建团队API
团队API创建流程：
1. 草案
□ 使用上述模板
□ 填写所有部分
□ 获取团队共识
2. 评审
□ 与利益相关者评审
□ 验证消费者需求
□ 检查完整性
3. 发布
□ 存储在团队wiki/代码库
□ 注册到服务目录
□ 向组织公告
4. 维护
□ 每季度评审
□ 变更时更新
□ 收集反馈
团队API成熟度级别
成熟度模型：
级别1：基础
□ 团队联系信息存在
□ 主要服务已文档化
□ 基本Slack频道
级别2：已定义
□ 完整的团队API文档
□ 响应时间期望
□ 版本控制政策已定义
□ 基本SLEs已文档化
级别3：已测量
□ SLEs被跟踪和报告
□ 收集消费者反馈
□ 依赖关系已映射
□ 定期API评审
级别4：优化
□ 团队API持续改进
□ API更新的自动化
□ 跟踪消费者满意度
□ 采用行业最佳实践
平台团队API示例
# 平台团队API：开发者平台
## 使命
通过自助服务基础设施和黄金路径，使流对齐团队更快交付软件。
## 团队类型：平台
## 我们提供的内容
### 自助服务能力
| 能力 | 接口 | 文档 |
|------------|-----------|------|
| 容器部署 | CLI/门户 | [链接] |
| 数据库配置 | Terraform模块 | [链接] |
| CI/CD流水线 | 模板 | [链接] |
| 秘密管理 | Vault API | [链接] |
### 黄金路径
| 路径 | 用例 | 指南 |
|------|----------|-------|
| Web服务 | 标准Web API | [链接] |
| 事件消费者 | Kafka消费者 | [链接] |
| 定时任务 | 批处理 | [链接] |
## 交互模型
### X-as-a-Service（默认）
- 使用我们的自助服务能力
- 遵循黄金路径文档
- 提交问题解决
- 参加办公时间提问
### 协作（按请求）
- 可用于复杂迁移
- 定制平台需求
- 有时间限制的参与
- 需要PM批准
## 办公时间
- **时间：** 星期二2-3pm，星期四10-11am
- **地点：** #platform-office-hours Slack会议
- **内容：** Q&A、演示、故障排除
## 支持层级
| 层级 | 响应 | 示例 |
|------|----------|---------|
| P1 - 生产中断 | 15分钟 | 平台不可用 |
| P2 - 性能下降 | 1小时 | 部署缓慢 |
| P3 - 受阻 | 4小时 | 无法配置资源 |
| P4 - 问题 | 1天 | 如何配置X |
流对齐团队API示例
# 团队API：支付团队
## 使命
可靠且安全地为所有商业流处理支付。
## 团队类型：流对齐
## 有限上下文：支付处理
## 我们拥有的内容
### 服务
| 服务 | 目的 | SLE |
|---------|---------|-----|
| 支付网关 | 处理支付 | 99.95%正常运行时间 |
| 退款服务 | 处理退款 | 99.9%正常运行时间 |
| 欺诈检测 | 实时欺诈 | p99 < 50毫秒 |
### API
| API | 描述 | 规范 |
|-----|-------------|------|
| /payments | 创建/查询支付 | [OpenAPI] |
| /refunds | 处理退款 | [OpenAPI] |
### 发布的事件
| 事件 | 主题 | 模式 |
|-------|-------|--------|
| PaymentCompleted | payments.completed | [Avro] |
| RefundProcessed | payments.refunds | [Avro] |
## 如何集成
### 对于支付处理
1. 阅读[集成指南]
2. 请求沙箱凭证
3. 完成安全评审
4. 上线检查清单
### 对于消费事件
1. 订阅Kafka主题
2. 实现幂等处理程序
3. 设置DLQ处理
4. 监控消费者延迟
## 约束
- **PCI合规：** 所有集成需要安全评审
- **速率限制：** 每个客户端1000请求/秒
- **数据保留：** 交易数据保留7年
评估清单
团队API健康检查：
可发现性
□ 团队API文档存在且可找到
□ 注册在服务目录
□ 链接有效且内容最新
完整性
□ 所有部分已填写
□ 联系信息准确
□ 依赖关系已文档化
□ SLEs已定义
清晰性
□ 非团队成员能理解
□ 无术语或未定义术语
□ 为消费者提供清晰行动号召
□ 提供示例
维护
□ 最近3个月内更新
□ 定期评审已安排
□ 反馈机制存在
□ 所有权清晰分配
有效性
□ 消费者找到所需内容
□ 响应时间符合
□ 重复问题减少
□ 团队对API满意
工作流程
设计团队API时：
- 审计当前状态： 今天存在什么？什么是隐式的？
- 识别消费者： 谁与团队交互？
- 文档化接口： 使用模板，完全填写
- 验证消费者需求： 这满足他们的需求吗？
- 发布和公告： 使其可发现
- 测量和迭代： 跟踪有效性，改进
参考资料
详细指导：
最后更新： 2025-12-26