4. 支付订单系统微服务架构设计：职责划分与API设计

在基于Kubernetes的支付订单系统中，微服务架构的合理拆分是弹性伸缩与流量治理的基础。本章将四个核心服务——订单服务、支付服务、账户服务、通知服务——的职责边界、数据主权与API契约进行精确界定，确保每个服务可独立部署、独立扩缩容，并具备故障隔离能力。

4.1 服务职责划分与数据主权

每个微服务拥有独立的数据库实例（Database per Service模式），禁止跨服务直接访问数据库。服务间仅通过定义良好的API进行通信。

4.2 核心API设计

API设计遵循RESTful风格，使用JSON作为数据交换格式。所有API均需携带全局追踪ID（traceId）用于链路诊断。

4.2.1 订单服务 API

POST   /api/v1/orders                    # 创建订单（预占库存）
GET    /api/v1/orders/{orderId}          # 查询订单详情
POST   /api/v1/orders/{orderId}/cancel   # 取消订单（未支付状态）
POST   /api/v1/orders/{orderId}/confirm  # 确认订单（支付成功后回调）

• 创建订单请求体：包含用户ID、商品列表（skuId + quantity）、总金额。服务返回订单ID与状态（PENDING_PAYMENT）。
• 状态机约束：订单状态流转为 PENDING_PAYMENT → PAID → CONFIRMED → COMPLETED，或 PENDING_PAYMENT → CANCELLED。

4.2.2 支付服务 API

POST   /api/v1/payments                    # 发起支付（返回支付链接/二维码）
GET    /api/v1/payments/{paymentId}        # 查询支付交易状态
POST   /api/v1/payments/{paymentId}/refund # 发起退款（全额或部分）
POST   /api/v1/payments/callback           # 支付网关异步回调（Webhook）

• 幂等性：支付回调接口通过 paymentId + 网关流水号实现幂等，防止重复入账。
• 退款流程：支付服务调用账户服务的冻结接口，确认资金可退后执行退款。

4.2.3 账户服务 API

GET    /api/v1/accounts/{userId}           # 查询账户余额与状态
POST   /api/v1/accounts/{userId}/freeze    # 冻结指定金额（支付预占）
POST   /api/v1/accounts/{userId}/unfreeze  # 解冻金额（支付取消）
POST   /api/v1/accounts/{userId}/transfer  # 转账（扣减+增加，内部原子操作）

• 冻结/解冻：用于支付预占场景，防止超卖。冻结记录需关联 paymentId。
• 转账接口：采用两阶段提交（本地事务+消息补偿），确保账户A扣款与账户B入账最终一致。

4.2.4 通知服务 API

POST   /api/v1/notifications/send          # 发送通知（指定渠道与模板）
GET    /api/v1/notifications/{notifyId}    # 查询发送状态
POST   /api/v1/notifications/retry         # 手动重试失败通知

• 异步发送：通知服务接收请求后立即返回受理ID，实际发送通过内部队列异步执行。
• 去重机制：基于业务ID（如 orderId + notifyType）进行去重，避免重复发送。

4.3 服务间交互流程（SVG架构图）

下图展示了用户发起支付时，四个微服务之间的同步调用与异步事件交互流程：

4.4 API版本管理与错误码规范

所有API采用URL路径版本控制（/api/v1/），当接口发生不兼容变更时升级主版本号。错误响应统一格式如下：

{
  "code": "PAYMENT_AMOUNT_MISMATCH",
  "message": "支付金额与订单金额不一致",
  "traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": 1712567890123
}

4.5 服务间通信模式对比

4.6 服务依赖与隔离边界（SVG架构图）

下图展示了四个服务在Kubernetes命名空间中的部署边界与依赖关系：