القائمة
微服务架构设计时使用。覆盖服务拆分、通信模式、网关、服务发现、配置中心、分布式事务。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف 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 → 消息队列实现