service-catalog-entry

服务目录条目技能

为微服务或内部平台服务编写完整的服务目录条目，让公司的任何工程师都能了解该服务的功能、如何依赖它、它的可靠性特征，以及出现问题时该联系谁。一份编写良好的目录条目可以消除“谁负责这个服务？”和“使用它安全吗？”这类问题，避免它们拖慢依赖共享服务的团队。

必需输入

如果尚未提供，请询问以下信息：

• 服务名称 — 在代码、监控和部署中使用的规范标识符
• 团队和负责人 — 团队名称、技术负责人姓名和当班联系人
• 架构概览 — 服务的功能、调用它的对象，以及它调用的对象
• SLA 要求 — 可用性目标、延迟 SLO、支持级别和维护时段
• 关键 API — 其他团队使用的最重要端点（方法、路径、简要说明）
• 处理的数据 — 服务存储或处理的数据、敏感性分类、保留期限

输出格式

---

服务目录：[Service Name]

[用一句话以通俗语言说明此服务为使用方提供什么]

例如：“Payments Service 为所有 Acme 产品处理扣款、退款和订阅计费事件。”

---

身份信息

字段	值
服务名称	[service-name]
规范代码仓库	[https://github.com/[org]/[repo]]
负责团队	[团队名称]
技术负责人	[姓名] ([Slack：@handle])
当班轮值	[PagerDuty 服务链接]
Slack 频道	#[team-channel]
支持级别	[级别 1 — 全天候 / 级别 2 — 工作时间 / 级别 3 — 尽力支持]
状态	[运行中 / 已弃用 / 结束日期：YYYY-MM-DD]
语言 / 运行时	[例如，Go 1.22 / Python 3.12 / Node 20]
部署平台	[Kubernetes / ECS / Lambda / 等]
环境	[生产环境：URL]

---

功能说明

[用通俗语言写两到三段——不使用术语或缩略语，除非同时加以说明。]

[第 1 段：此服务解决的业务问题。如果没有此服务，哪些功能会出故障或缺失？]

[第 2 段：此服务的高层工作方式——主要处理模型（例如，请求/响应 API、事件驱动的使用方、批处理器）、触发条件，以及它产生的结果。]

[第 3 段：明确说明此服务不负责什么——划定清晰的边界。这可以防止其他团队对服务范围产生错误假设。]

---

架构背景

系统图

[Upstream callers]          [This Service]             [Downstream dependencies]
                                                        
  [Web App]  ──────────→                          ──→  [Primary Database — PostgreSQL]
  [Mobile API]  ────────→  [Service Name]         ──→  [Cache — Redis]
  [Partner API] ────────→  (Port 8080/gRPC)       ──→  [Message Queue — Kafka/SQS]
                                                   ──→  [External Service / API]
                           ↓ emits events to
                        [Event Bus / SNS]
                           ↓ consumed by
                  [Downstream Service A]
                  [Downstream Service B]

依赖此服务的对象

调用方	使用方式	联系方式
[服务 / 团队 A]	[例如，“调用 POST /charges 发起付款”]	[Slack：#team-a]
[服务 / 团队 B]	[例如，“通过 Kafka 主题订阅 payment.completed 事件”]	[Slack：#team-b]
[服务 / 团队 C]	[例如，“调用 GET /subscriptions 查询计费状态”]	[Slack：#team-c]

此服务依赖的对象

依赖项	类型	关键程度	其当班联系人
[PostgreSQL 实例]	数据库	关键 — 没有它，所有写入都会失败	[DBA 团队：#db-oncall]
[Redis 集群]	缓存	高 — 没有它，延迟会增加	[基础设施团队：#infra-oncall]
[Kafka 集群]	消息队列	高 — 异步事件会排队等待处理	[基础设施团队：#infra-oncall]
[Stripe API]	外部 API	关键 — 付款处理会失败	[供应商状态页面：status.stripe.com]
[Auth Service]	内部服务	关键 — 所有身份验证都会失败	[Auth 团队：#auth-oncall]

---

服务级别协议

可用性和延迟

SLO	目标	测量窗口	错误预算
可用性	[99.9%]	滚动 30 天	[43 分钟/月]
p50 延迟（关键端点）	< [50] ms	滚动 24 小时	—
p99 延迟（关键端点）	< [500] ms	滚动 24 小时	—
p99.9 延迟（关键端点）	< [2000] ms	滚动 24 小时	—
错误率	< [0.1]%	滚动 1 小时	—

SLO 仪表板： [监控仪表板链接] 当前剩余错误预算： [SLO 仪表板链接或内联值]

支持等级

等级	范围	响应时间	解决时间
P1 — 服务宕机	所有经过身份验证的请求均失败	15 分钟	1 小时
P2 — 严重降级	错误率 >1% 或 p99 >2× SLO	30 分钟	4 小时
P3 — 轻微问题	非关键端点性能降级	下一个工作日	3 个工作日
功能请求 / Bug	通过标准工单流程处理	[工单 SLA]	按路线图执行

报告事故： 通过 [PagerDuty 服务链接] 呼叫值班人员，或在 #incidents 中发帖。 提交功能请求或 Bug： 在 [JIRA 项目 / GitHub 仓库的 Issues] 中创建工单。

维护窗口

• 计划停机： [例如：“周日 02:00–04:00 UTC — 提前 48 小时在 #[team-channel] 发布通知”]
• 部署窗口： [例如：“工作日 10:00–16:00 UTC — 周五或公共假期前一天不部署”]
• 重大变更通知： [例如：“API 重大变更至少提前 30 天通知 — 参见下文的版本管理政策”]

---

API 契约

身份验证

所有 API 调用均需：[例如：“通过 Authorization 标头传递 Bearer 令牌。令牌由 Auth Service (/api/v1/token) 签发”]

Authorization: Bearer [jwt-token]
Content-Type: application/json

基础 URL

环境	基础 URL
生产环境	https://[service-name].internal.[company].com
预发布环境	https://[service-name].staging.[company].com
本地开发	http://localhost:[port]

关键端点

方法	路径	说明	是否需要身份验证	速率限制
GET	/health	存活和就绪检查	否	无
GET	/api/v1/[resource]	[说明 — 例如：“列出经过身份验证的用户的资源”]	是	[100 req/min]
GET	/api/v1/[resource]/:id	[说明 — 例如：“按 ID 获取单个资源”]	是	[500 req/min]
POST	/api/v1/[resource]	[说明 — 例如：“创建新资源”]	是	[50 req/min]
PUT	/api/v1/[resource]/:id	[说明 — 例如：“更新现有资源”]	是	[50 req/min]
DELETE	/api/v1/[resource]/:id	[说明]	是	[20 req/min]

完整 API 文档： [OpenAPI/Swagger 规范 URL] | [Postman 集合 URL]

版本管理政策

• API 版本包含在 URL 路径中（/api/v1/、/api/v2/）
• 次要新增内容（新的可选字段、新端点）不构成破坏性变更，无需升级版本
• 破坏性变更（移除字段、更改类型、身份验证变更）需要发布新的主版本
• 已弃用的版本在后续版本达到 GA 后继续支持 [90 天]
• 弃用通知会发布到 #[team-channel]，并通过电子邮件发送给已注册的使用者

错误响应格式

{
  "error": {
    "code": "[ERROR_CODE]",
    "message": "[Human-readable description]",
    "request_id": "[UUID — include in support tickets]",
    "details": {}
  }
}

常见错误代码：

HTTP 状态	错误代码	含义
400	INVALID_REQUEST	请求正文或参数未通过验证
401	UNAUTHENTICATED	缺少身份验证令牌或令牌无效
403	FORBIDDEN	令牌有效，但没有访问此资源的权限
404	NOT_FOUND	资源不存在
409	CONFLICT	资源重复或状态冲突
422	UNPROCESSABLE_ENTITY	请求有效，但违反业务规则
429	RATE_LIMITED	请求过多 — 请等待一段时间后重试
500	INTERNAL_ERROR	意外的服务端错误 — 请在支持工单中附上 request_id
503	SERVICE_UNAVAILABLE	下游依赖项不可用 — 请采用退避策略重试

已发布的事件（适用于事件驱动型系统）

事件	主题 / 队列	架构	发布时机
[resource].created	[kafka-topic / sns-arn]	[架构 URL]	[创建新资源时]
[resource].updated	[kafka-topic / sns-arn]	[架构 URL]	[修改资源时]
[resource].deleted	[kafka-topic / sns-arn]	[架构 URL]	[删除资源时]

---

数据分类

数据元素	敏感度	存储位置	保留期限	静态加密
[用户个人身份信息（PII）——例如电子邮件、姓名]	[PII / 受限]	[PostgreSQL users 表]	[直至删除账户]	是
[财务数据——例如银行卡号末 4 位]	[PCI / 高度受限]	[PostgreSQL payment_methods 表]	[根据法规要求保留 7 年]	是 — 字段级加密
[运维日志]	[内部]	[CloudWatch / Datadog]	[90 天]	是（静态加密，不进行搜索）
[匿名化分析数据]	[公开]	[数据仓库]	[永久]	是

数据驻留： [例如："所有数据均存储在 us-east-1。根据 GDPR 要求，欧盟客户数据存储在 eu-west-1。"] 合规范围： [例如：SOC 2 Type II / PCI DSS Level 2 / HIPAA / GDPR] 数据访问政策： [例如："访问生产数据库需要经过[审批流程]。访问记录会被记录并每季度审核。"]

---

运维手册

手册	位置	适用场景
值班手册	[Wiki / GitHub 链接]	响应 PagerDuty 警报
部署手册	[Wiki / GitHub 链接]	将新版本部署到生产环境
数据库迁移手册	[Wiki / GitHub 链接]	执行架构迁移
回滚手册	[Wiki / GitHub 链接]	回滚有问题的部署
事件响应手册	[Wiki / GitHub 链接]	宣布并管理事件
灾难恢复计划	[Wiki / GitHub 链接]	可用区/区域故障或数据丢失

监控仪表板：

仪表板	链接	用途
服务概览	[Datadog / Grafana 链接]	错误率、延迟、吞吐量
基础设施	[链接]	CPU、内存、Pod 健康状况
数据库	[链接]	查询性能、连接池
SLO / 错误预算	[链接]	预算消耗速率、可用性
依赖项健康状况	[链接]	上游依赖项状态

---

已知限制

如实记录限制——本节可避免其他团队基于错误假设进行构建。

限制	影响	变通方法	计划修复
[例如：没有批量写入 API——必须逐个创建项目]	[大规模导入速度慢——需要调用 N 次 HTTP]	[超过 100 个项目时使用批量导入 CLI 工具]	[Q3 推出批量 API——工单：[URL]]
[例如：列表端点的最大页面大小为 100]	[单次调用最多只能获取 100 个项目]	[使用 cursor 参数进行分页]	[目前没有扩大上限的计划——这是有意设计]
[例如：速率限制按令牌设置，而非按服务设置]	[高流量使用方可能因同一令牌上的其他使用方而触及限制]	[申请专用服务账户令牌]	[路线图中计划加入按服务设置的速率限制]
[例如：列表端点在写入后读取时存在最终一致性]	[创建后记录可能不会立即出现在列表中（延迟 <500ms）]	[使用 GET /:id 确认创建；不要依赖列表实现即时一致性]	[正在开发通过 ?consistent=true 实现的读己之写一致性]

---

开始使用

开始使用此服务：

1. 申请访问权限：[访问申请表或相关说明链接]
2. 获取服务账号凭据：[流程链接]
3. 阅读 API 文档：[OpenAPI 规范 URL]
4. 试用沙盒环境：https://[service-name].sandbox.[company].com
5. 加入消费者 Slack 频道：#[service-name]-consumers

客户端库（如有）：

语言	软件包	安装
[Python]	[[package-name]]	pip install [package-name]
[Go]	[github.com/[org]/[package]]	go get github.com/[org]/[package]
[TypeScript/JS]	[@[org]/[package]]	npm install @[org]/[package]

---

质量检查

• “功能介绍”不含行话——其他团队的新工程师能在 2 分钟内看懂
• SLO 目标是经利益相关方确认的具体数值，而非理想化目标或从模板照搬的内容
• “依赖方”表格列出了所有直接的上游消费者，没有遗漏
• API 错误代码准确且经过测试，而非理想化的文档内容
• 如实说明已知限制，不掩饰任何问题来美化服务
• 所有运行手册链接均可访问，不是失效引用或 TODO 占位符
• 数据分类包含保留期限和加密状态，而不仅仅是敏感级别
• 至少有一个消费者团队审核了此条目，确认其与该团队对服务的实际体验相符

反面模式

• 不要编写理想化的 SLO 目标——目标必须经利益相关方确认，并基于历史数据，而非从模板照搬
• 不要将运行手册链接留作 TODO 占位符——在事故期间，失效或缺失的链接会让目录条目变得毫无用处，甚至适得其反
• 不要为了美化服务而省略“已知限制”部分——未披露的限制会导致错误集成和下游事故
• 不要在未经测试的情况下列出 API 错误代码——理想化的错误文档会误导消费者
• “功能介绍”部分不要使用行话——其他团队的新工程师必须能在 2 分钟内看懂