API成功响应消息生成器

操作分析

• 操作类型：读取（列表分页查询）
• 业务场景：订单处理，查询近30天订单，支持按 status 筛选与按时间排序
• 返回内容：分页元数据（total、page）与订单摘要字段（id、amount、status）

推荐状态码

• 200 OK：成功返回列表数据（即使结果为空也返回 200，items 为空数组）
  • 说明：分页查询属于读取操作，返回资源集合应使用 200；不建议使用 204，因为需要返回分页与集合数据

响应结构

• Content-Type: application/json; charset=utf-8
• JSON 字段说明：
  • success: boolean，固定为 true，表示请求成功
  • message: string，简短的成功描述
  • data: object
    • total: integer，满足筛选条件且在近30天范围内的订单总数
    • page: integer，当前页码（建议从 1 开始）
    • pageSize: integer，可选，当前每页条数（用于客户端校准分页）
    • items: array[object]，订单摘要列表
      • id: string，订单ID
      • amount: number，订单金额
      • status: string，订单状态（如 PENDING/PAID/SHIPPED/COMPLETED/CANCELED 等）

完整示例

• HTTP/1.1 200 OK
• Body:

{
  "success": true,
  "message": "获取订单列表成功",
  "data": {
    "total": 128,
    "page": 2,
    "pageSize": 20,
    "items": [
      { "id": "ord_202411280023", "amount": 259.9, "status": "PAID" },
      { "id": "ord_202411279817", "amount": 89.0, "status": "SHIPPED" }
    ]
  }
}

使用说明

• 返回空结果时，仍返回 200，示例：total=0，page=请求页码，items=[]
• 服务端应在查询层面限定近30天时间范围，并按请求参数应用 status 筛选与时间排序
• 代码示例（Node.js/Express）：

  app.get('/api/orders', async (req, res) => {
    // 假设已解析 page、pageSize、status、sort，并限定近30天时间范围完成查询
    const { total, page, pageSize, items } = await queryOrders(/* ... */);
    res.status(200).json({
      success: true,
      message: '获取订单列表成功',
      data: { total, page, pageSize, items }
    });
  });
  

操作分析

• 操作类型：更新（PUT/PATCH 语义），幂等
• 业务场景：接收第三方支付回调（webhook/notify），将订单支付状态更新为“已支付”，并持久化支付渠道交易号与完成时间
• 返回要求：不返回业务数据（无订单号、交易号、金额等业务字段）

推荐状态码

• 首选：204 No Content
  • 含义：服务器已成功处理更新请求且无返回内容。非常适合“幂等更新且无业务数据返回”的场景
  • 幂等要求：重复回调（同一支付事件）也返回 204，表示已处理或已是目标状态
• 备选：200 OK（仅在支付渠道规范明确要求有响应体时）
  • 用最小化(JSON)确认文本，不包含任何业务字段，仅用于渠道确认接收

响应结构

• 204 No Content
  • Body：无
  • Headers：常规 HTTP 头。若团队有链路追踪，可通过 X-Request-Id 等头部传递（非必须）
• 200 OK（可选方案，用于需要应答体的渠道）
  • Content-Type: application/json
  • JSON 结构（不含业务数据）： { "message": "payment callback processed" }
  • 字段说明：
    • message：字符串，仅表示处理完成的确认文本，不包含业务明细

完整示例

• 首选（204 无响应体）

  • HTTP/1.1 204 No Content Content-Type: application/json Content-Length: 0 [空响应体]

• 备选（200 带最小应答体，仅在渠道要求时使用）

  • HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8

    { "message": "payment callback processed" }

使用说明

• 返回 204 的实现要点（示例：Spring Boot）

  • 核心流程：验证签名/幂等键 → 幂等更新订单状态与支付信息（channel_transaction_id、paid_at） → 快速返回 204
  • 代码示例（仅展示响应部分的写法与幂等返回约定）： @PostMapping("/payments/callback") public ResponseEntity paymentCallback(@RequestBody String payload, @RequestHeader Map<String, String> headers) { // 1) 验证签名（依渠道规范）与反放回攻击校验 // 2) 解析回调，提取商户订单号、渠道交易号、完成时间等 // 3) 幂等更新（例如基于订单号 + 渠道交易号的唯一约束/去重表/状态机）： // - 若订单未支付：更新为已支付，写入channelTransactionId与paidAt // - 若订单已是已支付：不重复更新 // 4) 成功或重复通知，统一返回 204 return ResponseEntity.noContent().build(); }

• 若渠道要求应答体文本（如“success”或JSON）

  • 将返回行改为：return ResponseEntity.ok(Map.of("message", "payment callback processed"));
  • 保持应答体不包含任何业务字段，仅为确认文本

• 重试与幂等

  • 重复通知须产生相同的成功响应（204 或 200），以避免渠道端持续重试
  • 更新逻辑需具备并发安全（如数据库唯一键、状态机更新、行级锁或原子条件更新）以保障幂等性