【day15】绘制API链路图

以下是文旅产品业务流程实战中的API链路图设计及说明，以用户预订景区门票为例，展示核心系统间的调用关系：

---

一、业务场景概述

用户通过文旅平台预订景区门票，流程涉及：产品浏览 → 下单 → 支付 → 库存扣减 → 通知 → 核销。

---

二、API链路图（文字版）

1. 用户端（APP/小程序）
   │
   ├── 1.1 查询产品信息 → [产品服务] → 返回景区详情、库存、价格
   │
   ├── 1.2 提交订单 → [订单服务] → 生成预订单（未支付）
   │        │
   │        └── 1.2.1 调用 [库存服务] → 预扣库存（防止超卖）
   │
   ├── 1.3 发起支付 → [支付服务] → 对接第三方支付（支付宝/微信）
   │        │
   │        ├── 1.3.1 支付成功 → 回调 [订单服务] → 更新订单状态为“已支付”
   │        │               │
   │        │               └── 触发 [库存服务] → 确认库存扣减
   │        │               │
   │        │               └── 触发 [消息服务] → 发送短信/APP推送（电子票码）
   │        │
   │        └── 1.3.2 支付失败 → 回调 [订单服务] → 释放预扣库存
   │
   └── 1.4 核销门票 → [核销服务] → 验证票码有效性
            │
            ├── 1.4.1 调用 [订单服务] → 标记订单为“已完成”
            │
            └── 1.4.2 调用 [数据服务] → 更新景区实时客流量

---

三、关键API说明

1. 产品服务

   • API名称: GET /api/products/{id}
     功能: 返回景区详情、库存、价格、可用时间段等。
     参数: 景区ID、日期、票种。

2. 订单服务

   • API名称: POST /api/orders
     功能: 创建预订单，关联用户ID、票种、数量、总价。
     依赖: 调用库存服务预扣库存（PUT /api/inventory/lock）。

3. 支付服务

   • API名称: POST /api/payments
     功能: 生成支付链接，支持支付宝/微信支付。
     回调: 支付成功后通知订单服务（POST /api/orders/{id}/pay）。

4. 消息服务

   • API名称: POST /api/notifications
     功能: 发送电子票码短信/推送，含景区入口、有效期、使用规则。

5. 核销服务

   • API名称: POST /api/tickets/verify
     功能: 校验票码是否有效，防止重复使用。
     依赖: 调用订单服务更新状态（PUT /api/orders/{id}/complete）。

---

四、异常处理机制

• 库存不足: 下单时若库存不足，返回错误码 409 Conflict。
• 支付超时: 订单服务设置TTL（如15分钟），超时后自动释放库存。
• 重复核销: 核销服务记录核销时间戳，拒绝重复请求。

---

五、工具与设计建议

1. 绘图工具: 使用 Swagger 定义API文档，用 Draw.io 或 Mermaid 绘制链路图。
2. 性能优化:
   • 库存预扣采用Redis缓存，保证高并发下的响应速度。
   • 支付回调使用异步队列（如RabbitMQ）解耦。
3. 安全设计:
   • 敏感接口需鉴权（JWT Token）。
   • 支付回调验证签名防篡改。

---

通过此链路图，可清晰定位各环节的API职责，便于团队协作与问题排查。