Menú
微服务架构设计时使用。覆盖服务拆分、通信模式、网关、服务发现、配置中心、分布式事务。
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional SOC
设计 API 认证鉴权和权限矩阵时使用。适用于多角色系统、租户隔离、字段级权限。优先使用 OAuth 2.0 / JWT + RBAC + 资源归属检查。
设计具体 API 端点时使用。适用于资源建模后的下一步、列端点清单、HTTP 方法和状态码选择。优先使用 RFC 7231 HTTP 语义 + GitHub REST 命名规范。
设计 API 错误码和错误结构时使用。适用于错误响应规范、调用方错误处理、调试可观测。优先使用 RFC 7807 Problem Details + 业务错误码 + 调用方处理建议。
设计幂等接口和重试策略时使用。适用于支付、扣减、订单、关键写操作。优先使用 Idempotency-Key + 业务去重键 + 并发冲突处理（ETag/版本号）。
输出 OpenAPI 契约和 Mock 服务时使用。适用于 API 设计的最后一步、给前端/后端/QA 的交付。优先使用 OpenAPI 3.1 + Mock 数据覆盖所有路径 + 详细的下游交接清单。
设计列表接口的分页、筛选、排序、搜索时使用。适用于所有列表 API。优先使用 cursor 分页（大数据）或 offset 分页（小数据）+ 统一筛选/排序规范。
| name | microservice-design |
| description | 微服务架构设计时使用。覆盖服务拆分、通信模式、网关、服务发现、配置中心、分布式事务。 |
| 场景 | 用什么 |
|---|---|
| 微服务架构 / 拆分 / 通信 | 本 skill |
| 单个服务内部实现 | api-implementation/ |
| 数据库设计 | data-access/ |
| 异步消息队列 | async-jobs/ |
| 部署编排（K8s） | devops-engineer 工作流 |
1. 单体优先——不要上来就微服务（团队 < 30 人大概率不需要）
2. 按业务域拆分——不是按技术层拆分
3. 数据库独立——每个服务有自己的数据库（不共享）
4. 接口契约先行——服务间通过 API 契约协作
5. 异步优于同步——减少级联故障
6. 最终一致 > 强一致——分布式场景不追求 ACID
┌─ 微服务决策 ───────────────────────────────────────────────┐
│ │
│ 用微服务（满足多个）： │
│ □ 团队 > 30 人，多团队并行开发 │
│ □ 不同模块发布频率差异大（订单日发/用户月发） │
│ □ 不同模块技术栈需求不同（Go 高性能 + Python AI） │
│ □ 需要独立扩缩容（支付服务需要 10x 实例） │
│ │
│ 用单体（满足任一）： │
│ □ 团队 < 10 人 │
│ □ 项目早期（MVP / 验证阶段） │
│ □ 业务边界不清晰 │
│ □ 没有 DevOps 能力支撑 │
│ │
│ 折中方案：模块化单体（Modular Monolith） │
│ - 单体部署，内部按域模块隔离 │
│ - 未来可拆分（模块间通过接口通信，不直接依赖） │
└─────────────────────────────────────────────────────────────┘
DDD 限界上下文（Bounded Context）：
1. 识别核心域 / 支撑域 / 通用域
2. 每个限界上下文 = 一个潜在服务
3. 聚合根 = 数据一致性边界
典型电商拆分：
用户服务 → 注册/登录/个人信息/权限
商品服务 → 商品/SKU/库存/分类
订单服务 → 下单/状态流转/历史
支付服务 → 支付/退款/对账
通知服务 → 短信/邮件/推送/站内信
搜索服务 → 全文搜索/推荐
文件服务 → 上传/CDN/裁剪
| 模式 | 协议 | 适合 | 延迟 |
|---|---|---|---|
| HTTP REST | HTTP/1.1~2 | 通用、跨语言 | 中 |
| gRPC | HTTP/2 + Protobuf | 内部高性能通信 | 低 |
| 消息队列 | AMQP/Kafka | 异步解耦、削峰 | 高（最终一致） |
| 事件驱动 | Event Bus | 领域事件广播 | 中~高 |
同步查询（需要立即返回） → HTTP REST / gRPC
命令（可以异步处理） → 消息队列
事件通知（一对多） → Event Bus / Kafka
高性能内部通信 → gRPC
功能：
- 路由（/api/users → user-service）
- 认证（统一 JWT 验证）
- 限流（每 IP / 每用户 / 每服务）
- 熔断（下游故障时快速失败）
- 日志（统一 access log + traceId）
- CORS（跨域统一处理）
- 版本管理（/v1/ /v2/）
工具选型：
Kong — 功能最全，插件丰富（Lua）
APISIX — 国产高性能（Lua + etcd）
Traefik — K8s 原生，配置简单
Nginx — 最轻量（需要自己配）
Spring Gateway — Java 生态
Express Gateway — Node.js 小项目
方案对比：
本地消息表 → 最简单，可靠性高
最终一致（MQ）→ 最常用，异步补偿
Saga 模式 → 长事务分步执行 + 补偿
TCC → 最严格，实现复杂
推荐：90% 场景用"本地消息表 + MQ + 重试"
本地消息表模式：
1. 业务操作 + 写消息表（同一事务）
2. 定时任务扫描消息表，发送 MQ
3. 下游消费成功 → 标记完成
4. 消费失败 → 重试（幂等保证）
□ 服务间有明确的 API 契约（OpenAPI/Proto）
□ 每个服务有独立数据库（不共享表）
□ 服务间通信有超时 + 重试 + 熔断
□ API 网关统一认证 + 限流 + 日志
□ 链路追踪（traceId 贯穿全链路）
□ 健康检查（/health 端点）
□ 配置中心管理（不硬编码地址）
□ 服务发现 or DNS（不硬编码 IP）
□ 异步通信有死信队列
□ 分布式事务方案明确（哪些需要一致性）
□ 每个服务独立 CI/CD
□ 灰度发布能力
1. 过早拆分 → 拆完才发现业务边界错了
2. 共享数据库 → 耦合比单体还严重
3. 同步调用链太长 → A→B→C→D 一个挂全挂
4. 不做幂等 → 重试导致重复操作
5. 不做熔断 → 一个慢服务拖垮所有调用方
6. 分布式事务追求强一致 → 性能崩溃
7. 不做链路追踪 → 跨服务问题定位地狱
8. 没有 API 网关 → 每个前端都要知道每个服务地址
9. 配置硬编码 → 环境切换改 N 处
10. 日志不统一 → 跨服务拼日志花半天
templates/microservice-design-template.md上游：
api-designer → 服务间 API 契约
product-manager → 业务域划分
下游：
devops-engineer → K8s 部署 + 服务网格
sre-operations → 全链路监控
async-jobs → 消息队列实现