Microservice Design
Applicable Scenarios
- Decomposing a monolith into microservices
- Microservice architecture design for new projects
- Selection of inter-service communication solutions (HTTP / gRPC / MQ)
- API gateway design
- Service discovery and registration
- Configuration center
- Distributed transactions
Division of labor with other skills
| Scenario |
What to use |
| Microservice architecture / decomposition / communication |
This skill |
| Internal implementation of a single service |
api-implementation/ |
| Database design |
data-access/ |
| Asynchronous message queue |
async-jobs/ |
| Deployment orchestration (K8s) |
devops-engineer workflow |
Core Principles
1. 单体优先——不要上来就微服务（团队 < 30 人大概率不需要）
2. 按业务域拆分——不是按技术层拆分
3. 数据库独立——每个服务有自己的数据库（不共享）
4. 接口契约先行——服务间通过 API 契约协作
5. 异步优于同步——减少级联故障
6. 最终一致 > 强一致——分布式场景不追求 ACID
When to use microservices?
┌─ 微服务决策 ───────────────────────────────────────────────┐
│ │
│ 用微服务（满足多个）： │
│ □ 团队 > 30 人，多团队并行开发 │
│ □ 不同模块发布频率差异大（订单日发/用户月发） │
│ □ 不同模块技术栈需求不同（Go 高性能 + Python AI） │
│ □ 需要独立扩缩容（支付服务需要 10x 实例） │
│ │
│ 用单体（满足任一）： │
│ □ 团队 < 10 人 │
│ □ 项目早期（MVP / 验证阶段） │
│ □ 业务边界不清晰 │
│ □ 没有 DevOps 能力支撑 │
│ │
│ 折中方案：模块化单体（Modular Monolith） │
│ - 单体部署，内部按域模块隔离 │
│ - 未来可拆分（模块间通过接口通信，不直接依赖） │
└─────────────────────────────────────────────────────────────┘
Service Decomposition Methods
DDD 限界上下文（Bounded Context）：
1. 识别核心域 / 支撑域 / 通用域
2. 每个限界上下文 = 一个潜在服务
3. 聚合根 = 数据一致性边界
典型电商拆分：
用户服务 → 注册/登录/个人信息/权限
商品服务 → 商品/SKU/库存/分类
订单服务 → 下单/状态流转/历史
支付服务 → 支付/退款/对账
通知服务 → 短信/邮件/推送/站内信
搜索服务 → 全文搜索/推荐
文件服务 → 上传/CDN/裁剪
Communication Patterns
| Pattern |
Protocol |
Suitable for |
Latency |
| HTTP REST |
HTTP/1.1~2 |
General purpose, cross-language |
Medium |
| gRPC |
HTTP/2 + Protobuf |
Internal high-performance communication |
Low |
| Message queue |
AMQP/Kafka |
Asynchronous decoupling, peak shaving |
High (eventual consistency) |
| Event-driven |
Event Bus |
Domain event broadcasting |
Medium~High |
Selection Recommendations
同步查询（需要立即返回） → HTTP REST / gRPC
命令（可以异步处理） → 消息队列
事件通知（一对多） → Event Bus / Kafka
高性能内部通信 → gRPC
API Gateway
功能：
- 路由（/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 小项目
Distributed Transactions
方案对比：
本地消息表 → 最简单，可靠性高
最终一致（MQ）→ 最常用，异步补偿
Saga 模式 → 长事务分步执行 + 补偿
TCC → 最严格，实现复杂
推荐：90% 场景用"本地消息表 + MQ + 重试"
本地消息表模式：
1. 业务操作 + 写消息表（同一事务）
2. 定时任务扫描消息表，发送 MQ
3. 下游消费成功 → 标记完成
4. 消费失败 → 重试（幂等保证）
Production Readiness Checklist
□ 服务间有明确的 API 契约（OpenAPI/Proto）
□ 每个服务有独立数据库（不共享表）
□ 服务间通信有超时 + 重试 + 熔断
□ API 网关统一认证 + 限流 + 日志
□ 链路追踪（traceId 贯穿全链路）
□ 健康检查（/health 端点）
□ 配置中心管理（不硬编码地址）
□ 服务发现 or DNS（不硬编码 IP）
□ 异步通信有死信队列
□ 分布式事务方案明确（哪些需要一致性）
□ 每个服务独立 CI/CD
□ 灰度发布能力
Common Pitfalls
1. 过早拆分 → 拆完才发现业务边界错了
2. 共享数据库 → 耦合比单体还严重
3. 同步调用链太长 → A→B→C→D 一个挂全挂
4. 不做幂等 → 重试导致重复操作
5. 不做熔断 → 一个慢服务拖垮所有调用方
6. 分布式事务追求强一致 → 性能崩溃
7. 不做链路追踪 → 跨服务问题定位地狱
8. 没有 API 网关 → 每个前端都要知道每个服务地址
9. 配置硬编码 → 环境切换改 N 处
10. 日志不统一 → 跨服务拼日志花半天
Supporting Templates
templates/microservice-design-template.md
Collaboration with Other Skills
上游：
api-designer → 服务间 API 契约
product-manager → 业务域划分
下游：
devops-engineer → K8s 部署 + 服务网格
sre-operations → 全链路监控
async-jobs → 消息队列实现
