接口状态码

最近和团队讨论接口返回格式时，遇到了一个很常见但容易纠结的小问题：

成功状态是 success 还是 succeeded？
失败状态是 failure 还是 failed？

简单整理一下词性和实际用法，结论其实很清晰。

词性分析

• success ↔ failure
  → 都是名词，表示“成功/失败”这个结果/状态
  → 英语里最自然的对仗，正式、对称

• succeed ↔ fail
  → 都是动词原形，描述动作（“成功了”“失败了”）
  → 适合写在日志或自然语言里，不太适合做状态字段

• succeeded ↔ failed
  → 都是动词过去分词，常被当形容词用，表示“已经成功/已经失败”的完成状态
  → 在 API 里也非常常见，尤其是支付、任务、订单系统

业界常见写法

1. success: true/false（最流行之一，尤其通用中后台/内部 API）

// 成功
{
  "success": true,
  "data": {
    "id": 123,
    "name": "Alice"
  },
  "message": "操作成功"   // 可选
}

// 失败（HTTP 200）
{
  "success": false,
  "error": {
    "code": "INVALID_PARAM",
    "message": "用户名不能为空"
  },
  "data": null             // 可选
}

• 为什么常见：简单、直观，前后端都容易处理。HTTP 状态码统一 200，失败不影响网关大盘。

2. status: “succeeded” / “failed”（支付、订单、任务、异步操作最常见）

// 成功
{
  "status": "succeeded",
  "data": {
    "transaction_id": "txn_abc123",
    "amount": 99.99
  }
}

// 失败（HTTP 200）
{
  "status": "failed",
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "余额不足"
  }
}

• 为什么常见：语义清晰，表示“操作已完成”的最终状态。Stripe、PayPal、AWS 很多服务类似风格。

3. status: “success” / “failure”（正式感强，企业级规范常见）

// 成功
{
  "status": "success",
  "data": {
    "user": {
      "id": 456,
      "email": "test@example.com"
    }
  }
}

// 失败（HTTP 200）
{
  "status": "failure",
  "error": {
    "code": 4001,
    "message": "参数验证失败"
  }
}

• 为什么常见：词性对称、正式，但比 “succeeded/failed” 略少见。

4. status: “ok” / “error”（极简风格，很多内部系统/新兴 API）

// 成功
{
  "status": "ok",
  "data": {
    "items": ["apple", "banana"]
  }
}

// 失败
{
  "status": "error",
  "message": "服务器内部错误",
  "code": 500
}

• 为什么常见：简洁，减少字符量。很多 Node.js / Go 项目喜欢。

5. 纯 error 对象 + data 存在与否判断（纯 REST 风格，越来越流行）

// 成功（HTTP 200/201）
{
  "data": {
    "id": 789,
    "title": "New Post"
  }
}

// 失败（HTTP 400/422 等）
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "标题长度不能超过 100 字符",
    "details": ["title: too long"]
  }
}

• 为什么常见：严格遵循 HTTP 语义，减少冗余字段。JSON:API、一些现代框架倾向这种。

6. 带 meta 的更完整结构（大型项目/分页场景常见）

// 成功
{
  "success": true,
  "data": [...],
  "meta": {
    "total": 100,
    "page": 1,
    "per_page": 20
  }
}

// 失败
{
  "success": false,
  "error": {
    "code": "AUTH_FAILED",
    "message": "Token 已过期"
  },
  "meta": {
    "timestamp": "2026-02-10T12:47:00Z"
  }
}

推荐

• 优先用 success / failure，最对称、最专业
• 如果喜欢更直观的完成态，用 succeeded / failed 也很好
• 最重要的是：全接口统一，别这个接口 success，那个接口又变成 succeeded

// 成功
{
  "success": true,
  "data": { ... }
}
// 失败（HTTP 200）
{
  "success": false,
  "error": {
    "code": "INVALID_PARAM",
    "message": "参数错误"
  }
}

// 成功
{
  "status": "succeeded",
  "data": { ... }
}
// 失败（HTTP 200）
{
  "status": "failed",
  "error": { ... }
}