demo/API.md

API 文档

所有API通过API Gateway (http://localhost:8080) 访问。

💡 快速生成测试数据？ 查看 BATCH_TEST_API.md 获取批量模拟请求API

一句命令生成50个订单: curl http://localhost:8080/api/test/order/batch?count=50

订单服务 (Order Service)

1. 创建订单

请求:

POST /api/order/create
Content-Type: application/json
X-User-Id: user123

{
  "userId": "user123",
  "price": 99.99,
  "description": "test order"
}

响应 (成功 200):

{
  "code": 0,
  "msg": "success",
  "data": {
    "orderId": "ORD-A1B2C3D4",
    "userId": "user123",
    "price": 99.99,
    "status": "CREATED",
    "description": "test order",
    "createdAt": 1707200445123
  }
}

响应 (失败):

{
  "code": -1,
  "msg": "price must be > 0",
  "data": null
}

---

2. 获取订单详情

请求:

GET /api/order/{orderId}

示例:

curl http://localhost:8080/api/order/ORD-A1B2C3D4

响应 (成功 200):

{
  "code": 0,
  "msg": "success",
  "data": {
    "orderId": "ORD-A1B2C3D4",
    "userId": "user123",
    "price": 99.99,
    "status": "CREATED",
    "description": "test order",
    "createdAt": 1707200445123
  }
}

---

3. 支付订单

请求:

POST /api/order/{orderId}/pay

示例:

curl -X POST http://localhost:8080/api/order/ORD-A1B2C3D4/pay

响应 (成功 200):

{
  "code": 0,
  "msg": "success",
  "data": null
}

---

4. 删除订单

请求:

POST /api/order/delete/{orderId}

示例:

curl -X POST http://localhost:8080/api/order/delete/ORD-A1B2C3D4

响应 (成功 200):

{
  "code": 0,
  "msg": "success",
  "data": null
}

响应 (已支付订单不能删除):

{
  "code": -1,
  "msg": "Paid order cannot be deleted",
  "data": null
}

---

支付服务 (Payment Service)

1. 支付订单

请求:

POST /api/payment/pay
Content-Type: application/json
X-User-Id: user123

{
  "orderId": "ORD-A1B2C3D4",
  "amount": 99.99,
  "paymentMethod": "WECHAT"
}

支付方式选项:

• CARD - 银行卡
• WECHAT - 微信
• ALIPAY - 支付宝

响应 (成功 200):

{
  "code": 0,
  "msg": "success",
  "data": {
    "paymentId": "PAY-X1Y2Z3W4",
    "orderId": "ORD-A1B2C3D4",
    "amount": 99.99,
    "status": "SUCCESS",
    "paymentMethod": "WECHAT",
    "paidAt": 1707200500234
  }
}

响应 (失败 - 30% 概率):

{
  "code": -1,
  "msg": "Third party payment failed",
  "data": null
}

---

2. 获取支付详情

请求:

GET /api/payment/{paymentId}

示例:

curl http://localhost:8080/api/payment/PAY-X1Y2Z3W4

响应 (成功 200):

{
  "code": 0,
  "msg": "success",
  "data": {
    "paymentId": "PAY-X1Y2Z3W4",
    "orderId": "ORD-A1B2C3D4",
    "amount": 99.99,
    "status": "SUCCESS",
    "paymentMethod": "WECHAT",
    "paidAt": 1707200500234
  }
}

---

3. 退款

请求:

POST /api/payment/refund/{paymentId}

示例:

curl -X POST http://localhost:8080/api/payment/refund/PAY-X1Y2Z3W4

响应 (成功 200):

{
  "code": 0,
  "msg": "success",
  "data": null
}

响应 (非成功支付无法退款):

{
  "code": -1,
  "msg": "Only success payment can be refunded",
  "data": null
}

---

日志对应关系

订单创建流程产生的日志链路

1. Gateway 收到请求
   └─ traceId: abc-123-def-456
   └─ uri: /api/order/create
   └─ uri_group: /order/*

2. Order Service 处理请求
   └─ event_class: order
   └─ duration: 156ms
   └─ status: success

3. 返回响应
   └─ 记录完整的MDC上下文

支付流程产生的日志链路

1. Gateway 收到请求
   └─ traceId: xyz-789-uvw-012
   └─ uri: /api/payment/pay
   └─ uri_group: /payment/*

2. Payment Service 处理请求
   └─ event_class: payment
   └─ duration: 234ms
   └─ status: success (70%) 或 server_error (30%)

3. 返回响应
   └─ 记录完整的MDC上下文

---

cURL 测试脚本

完整的订单+支付流程

#!/bin/bash

# 1. 创建订单
echo "Creating order..."
ORDER_RESPONSE=$(curl -s -X POST http://localhost:8080/api/order/create \
  -H "Content-Type: application/json" \
  -H "X-User-Id: user123" \
  -d '{
    "userId":"user123",
    "price":99.99,
    "description":"test order"
  }')

ORDER_ID=$(echo $ORDER_RESPONSE | jq -r '.data.orderId')
echo "Order created: $ORDER_ID"

# 2. 获取订单详情
echo "Fetching order details..."
curl -s http://localhost:8080/api/order/$ORDER_ID | jq .

# 3. 支付订单
echo "Processing payment..."
PAYMENT_RESPONSE=$(curl -s -X POST http://localhost:8080/api/payment/pay \
  -H "Content-Type: application/json" \
  -d "{
    \"orderId\":\"$ORDER_ID\",
    \"amount\":99.99,
    \"paymentMethod\":\"WECHAT\"
  }")

PAYMENT_ID=$(echo $PAYMENT_RESPONSE | jq -r '.data.paymentId')
echo "Payment processed: $PAYMENT_ID"

# 4. 标记订单为已支付
echo "Marking order as paid..."
curl -s -X POST http://localhost:8080/api/order/$ORDER_ID/pay | jq .

# 5. 尝试删除已支付订单（应该失败）
echo "Attempting to delete paid order..."
curl -s -X POST http://localhost:8080/api/order/delete/$ORDER_ID | jq .

# 6. 获取支付详情
echo "Fetching payment details..."
curl -s http://localhost:8080/api/payment/$PAYMENT_ID | jq .

# 7. 退款
echo "Processing refund..."
curl -s -X POST http://localhost:8080/api/payment/refund/$PAYMENT_ID | jq .

保存为 test.sh 并运行：

chmod +x test.sh
./test.sh

---

HTTP 状态码

状态码	含义
200	请求成功（响应体中 code=0 表示业务成功）
400	请求参数错误
500	服务器错误

请求头

头	说明	示例
Content-Type	必需 (POST/PUT)	application/json
X-User-Id	可选，用于日志追踪	user123
X-B3-TraceId	可选，Jaeger/Zipkin追踪ID	550e8400-e29b-41d4

---

错误处理

所有API响应都遵循统一的格式：

{
  "code": 0,           // 0 表示成功，非0表示错误
  "msg": "success",    // 错误或成功信息
  "data": {...}        // 业务数据（错误时为null）
}

实际的HTTP状态码始终是200，业务状态通过 code 字段判断。