# Microservice Design

> 微服务架构设计时使用。覆盖服务拆分、通信模式、网关、服务发现、配置中心、分布式事务。

- Skill: `zhaoxuya520/microservice-design` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add zhaoxuya520/microservice-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhaoxuya520/microservice-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zhaoxuya520 (https://skillmd.com/u/zhaoxuya520)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zhaoxuya520/microservice-design

---


# 微服务架构设计（Microservice Design）

## 适用场景

- 单体应用拆分为微服务
- 新项目微服务架构设计
- 服务间通信方案选型（HTTP / gRPC / MQ）
- API 网关设计
- 服务发现与注册
- 配置中心
- 分布式事务

### 与其他 skill 的分工

| 场景 | 用什么 |
|------|--------|
| 微服务架构 / 拆分 / 通信 | **本 skill** |
| 单个服务内部实现 | `api-implementation/` |
| 数据库设计 | `data-access/` |
| 异步消息队列 | `async-jobs/` |
| 部署编排（K8s） | devops-engineer 工作流 |

---

## 核心原则

```text
1. 单体优先——不要上来就微服务（团队 < 30 人大概率不需要）
2. 按业务域拆分——不是按技术层拆分
3. 数据库独立——每个服务有自己的数据库（不共享）
4. 接口契约先行——服务间通过 API 契约协作
5. 异步优于同步——减少级联故障
6. 最终一致 > 强一致——分布式场景不追求 ACID
```

---

## 何时用微服务？

```text
┌─ 微服务决策 ───────────────────────────────────────────────┐
│                                                             │
│  用微服务（满足多个）：                                      │
│    □ 团队 > 30 人，多团队并行开发                           │
│    □ 不同模块发布频率差异大（订单日发/用户月发）             │
│    □ 不同模块技术栈需求不同（Go 高性能 + Python AI）        │
│    □ 需要独立扩缩容（支付服务需要 10x 实例）               │
│                                                             │
│  用单体（满足任一）：                                        │
│    □ 团队 < 10 人                                           │
│    □ 项目早期（MVP / 验证阶段）                             │
│    □ 业务边界不清晰                                         │
│    □ 没有 DevOps 能力支撑                                   │
│                                                             │
│  折中方案：模块化单体（Modular Monolith）                   │
│    - 单体部署，内部按域模块隔离                              │
│    - 未来可拆分（模块间通过接口通信，不直接依赖）           │
└─────────────────────────────────────────────────────────────┘
```

---

## 服务拆分方法

```text
DDD 限界上下文（Bounded Context）：
  1. 识别核心域 / 支撑域 / 通用域
  2. 每个限界上下文 = 一个潜在服务
  3. 聚合根 = 数据一致性边界

典型电商拆分：
  用户服务    → 注册/登录/个人信息/权限
  商品服务    → 商品/SKU/库存/分类
  订单服务    → 下单/状态流转/历史
  支付服务    → 支付/退款/对账
  通知服务    → 短信/邮件/推送/站内信
  搜索服务    → 全文搜索/推荐
  文件服务    → 上传/CDN/裁剪
```

---

## 通信模式

| 模式 | 协议 | 适合 | 延迟 |
|------|------|------|------|
| **HTTP REST** | HTTP/1.1~2 | 通用、跨语言 | 中 |
| **gRPC** | HTTP/2 + Protobuf | 内部高性能通信 | 低 |
| **消息队列** | AMQP/Kafka | 异步解耦、削峰 | 高（最终一致） |
| **事件驱动** | Event Bus | 领域事件广播 | 中~高 |

### 选择建议
```text
同步查询（需要立即返回） → HTTP REST / gRPC
命令（可以异步处理）    → 消息队列
事件通知（一对多）      → Event Bus / Kafka
高性能内部通信          → gRPC
```

---

## API 网关

```text
功能：
  - 路由（/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 小项目
```

---

## 分布式事务

```text
方案对比：
  本地消息表    → 最简单，可靠性高
  最终一致（MQ）→ 最常用，异步补偿
  Saga 模式     → 长事务分步执行 + 补偿
  TCC           → 最严格，实现复杂

推荐：90% 场景用"本地消息表 + MQ + 重试"

本地消息表模式：
  1. 业务操作 + 写消息表（同一事务）
  2. 定时任务扫描消息表，发送 MQ
  3. 下游消费成功 → 标记完成
  4. 消费失败 → 重试（幂等保证）
```

---

## 生产化检查清单

```text
□ 服务间有明确的 API 契约（OpenAPI/Proto）
□ 每个服务有独立数据库（不共享表）
□ 服务间通信有超时 + 重试 + 熔断
□ API 网关统一认证 + 限流 + 日志
□ 链路追踪（traceId 贯穿全链路）
□ 健康检查（/health 端点）
□ 配置中心管理（不硬编码地址）
□ 服务发现 or DNS（不硬编码 IP）
□ 异步通信有死信队列
□ 分布式事务方案明确（哪些需要一致性）
□ 每个服务独立 CI/CD
□ 灰度发布能力
```

---

## 常见坑

```text
1. 过早拆分 → 拆完才发现业务边界错了
2. 共享数据库 → 耦合比单体还严重
3. 同步调用链太长 → A→B→C→D 一个挂全挂
4. 不做幂等 → 重试导致重复操作
5. 不做熔断 → 一个慢服务拖垮所有调用方
6. 分布式事务追求强一致 → 性能崩溃
7. 不做链路追踪 → 跨服务问题定位地狱
8. 没有 API 网关 → 每个前端都要知道每个服务地址
9. 配置硬编码 → 环境切换改 N 处
10. 日志不统一 → 跨服务拼日志花半天
```

---

## 配套模板

- `templates/microservice-design-template.md`

## 与其他 skill 的协作

```text
上游：
  api-designer → 服务间 API 契约
  product-manager → 业务域划分

下游：
  devops-engineer → K8s 部署 + 服务网格
  sre-operations → 全链路监控
  async-jobs → 消息队列实现
```