[WIP] Update API to unify error response format

[Copilot]

Thanks for asking me to work on this. I will get started on it and keep this PR's description up to date as I form a plan and make progress.

Original prompt

问题描述

当前API文档中定义了三种不同的错误响应格式:

1. 简单错误(只有 code, message, timestamp)
2. 字段验证错误(包含 errors 数组)
3. 带详情的错误(包含 details 对象)

这种设计存在以下问题:

• 前端需要处理多种错误格式,增加开发和维护复杂度
• 不利于实现统一的错误处理中间件
• 容易造成格式不一致的问题
• 实际业务中过于繁琐

解决方案

统一所有错误响应为单一灵活的格式,既能满足各种场景需求,又保持结构一致性。

统一的错误响应格式

{
  "code": 20001,
  "message": "操作失败的主要原因",
  "data": null,
  "errors": [],
  "timestamp": "2025-12-05T10:00:00Z"
}

字段说明:

• code: 业务错误码(保持不变)
• message: 主要错误消息,面向用户的友好提示
• data: 统一保留字段,错误时固定为 null
• errors: 可选的错误详情数组,仅在需要时使用
• timestamp: 响应时间戳

使用场景示例

场景1: 简单业务错误

{
  "code": 20001,
  "message": "图书不存在",
  "data": null,
  "errors": [],
  "timestamp": "2025-12-05T10:00:00Z"
}

场景2: 字段验证错误

{
  "code": 400,
  "message": "请求参数验证失败",
  "data": null,
  "errors": [
    {
      "field": "isbn",
      "message": "ISBN格式不正确",
      "value": "invalid-isbn"
    },
    {
      "field": "price",
      "message": "价格必须大于0",
      "value": -10
    }
  ],
  "timestamp": "2025-12-05T10:00:00Z"
}

场景3: 带业务上下文的错误

{
  "code": 30002,
  "message": "借阅数量已达上限",
  "data": null,
  "errors": [
    {
      "type": "borrow_limit_exceeded",
      "current_count": 5,
      "limit": 5,
      "message": "您当前已借阅5本图书,已达到借阅上限"
    }
  ],
  "timestamp": "2025-12-05T10:00:00Z"
}

场景4: 批量操作部分失败

{
  "code": 207,
  "message": "批量导入部分成功",
  "data": {
    "success_count": 5,
    "failed_count": 2
  },
  "errors": [
    {
      "index": 2,
      "isbn": "978-7-111-22222-2",
      "message": "ISBN已存在",
      "code": 20002
    },
    {
      "index": 5,
      "isbn": "978-7-111-33333-3",
      "message": "分类不存在",
      "code": 20004
    }
  ],
  "timestamp": "2025-12-05T10:00:00Z"
}

需要修改的内容

请更新 图书管理系统 API 文档.md 文件中的以下部分:

1. 修改 "1.2 响应格式" 章节

• 移除三种不同的错误响应示例
• 统一为上述单一格式
• 添加各种场景的使用示例
• 说明 errors 数组的可选性和灵活性

2. 更新所有接口的错误响应示例

将文档中所有接口的错误响应示例统一为新格式,确保:

• 所有错误响应都包含 data: null 字段
• 简单错误使用空 errors: []
• 复杂错误在 errors 数组中提供详情
• 保持一致的结构

3. 添加最佳实践说明

在响应格式部分添加:

• 前端如何统一处理错误响应
• errors 数组的推荐结构
• 何时使用 errors 字段的指导原则

预期效果

• ✅ 前端只需要一个错误处理函数
• ✅ 结构统一,易于理解和维护
• ✅ 灵活性足够,可应对各种错误场景
• ✅ 向后兼容,可以平滑迁移
• ✅ 符合RESTful API最佳实践

注意事项

• 保持所有现有的错误码定义不变
• 保持HTTP状态码映射关系不变
• 确保所有示例的一致性
• 添加前端TypeScript类型定义示例(可选)

This pull request was created as a result of the following prompt from Copilot chat.

问题描述

当前API文档中定义了三种不同的错误响应格式:

1. 简单错误(只有 code, message, timestamp)
2. 字段验证错误(包含 errors 数组)
3. 带详情的错误(包含 details 对象)

这种设计存在以下问题:

• 前端需要处理多种错误格式,增加开发和维护复杂度
• 不利于实现统一的错误处理中间件
• 容易造成格式不一致的问题
• 实际业务中过于繁琐

解决方案

统一所有错误响应为单一灵活的格式,既能满足各种场景需求,又保持结构一致性。

统一的错误响应格式

{
  "code": 20001,
  "message": "操作失败的主要原因",
  "data": null,
  "errors": [],
  "timestamp": "2025-12-05T10:00:00Z"
}

字段说明:

• code: 业务错误码(保持不变)
• message: 主要错误消息,面向用户的友好提示
• data: 统一保留字段,错误时固定为 null
• errors: 可选的错误详情数组,仅在需要时使用
• timestamp: 响应时间戳

使用场景示例

场景1: 简单业务错误

{
  "code": 20001,
  "message": "图书不存在",
  "data": null,
  "errors": [],
  "timestamp": "2025-12-05T10:00:00Z"
}

场景2: 字段验证错误

{
  "code": 400,
  "message": "请求参数验证失败",
  "data": null,
  "errors": [
    {
      "field": "isbn",
      "message": "ISBN格式不正确",
      "value": "invalid-isbn"
    },
    {
      "field": "price",
      "message": "价格必须大于0",
      "value": -10
    }
  ],
  "timestamp": "2025-12-05T10:00:00Z"
}

场景3: 带业务上下文的错误

{
  "code": 30002,
  "message": "借阅数量已达上限",
  "data": null,
  "errors": [
    {
      "type": "borrow_limit_exceeded",
      "current_count": 5,
      "limit": 5,
      "message": "您当前已借阅5本图书,已达到借阅上限"
    }
  ],
  "timestamp": "2025-12-05T10:00:00Z"
}

场景4: 批量操作部分失败

{
  "code": 207,
  "message": "批量导入部分成功",
  "data": {
    "success_count": 5,
    "failed_count": 2
  },
  "errors": [
    {
      "index": 2,
      "isbn": "978-7-111-22222-2",
      "message": "ISBN已存在",
      "code": 20002
    },
    {
      "index": 5,
      "isbn": "978-7-111-33333-3",
      "message": "分类不存在",
      "code": 20004
    }
  ],
  "timestamp": "2025-12-05T10:00:00Z"
}

需要修改的内容

请更新 图书管理系统 API 文档.md 文件中的以下部分:

1. 修改 "1.2 响应格式" 章节

• 移除三种不同的错误响应示例
• 统一为上述单一格式
• 添加各种场景的使用示例
• 说明 errors 数组的可选性和灵活性

2. 更新所有接口的错误响应示例

将文档中所有接口的错误响应示例统一为新格式,确保:

• 所有错误响应都包含 data: null 字段
• 简单错误使用空 errors: []
• 复杂错误在 errors 数组中提供详情
• 保持一致的结构

3. 添加最佳实践说明

在响应格式部分添加:

• 前端如何统一处理错误响应
• errors 数组的推荐结构
• 何时使用 errors 字段的指导原则

预期效果

• ✅ 前端只需要一个错误处理函数
• ✅ 结构统一,易于理解和维护
• ✅ 灵活性足够,可应对各种错误场景
• ✅ 向后兼容,可以平滑迁移
• ✅ 符合RESTful API最佳实践

注意事项

• 保持所有现有的错误码定义不变
• 保持HTTP状态码映射关系不变
• 确保所有示例的一致性
• 添加前端TypeScript类型定义示例(可选)

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.