响应格式

成功响应

成功响应使用标准 JSON 封装：

{
  "success": true,
  "data": { ... },
  "timestamp": "2026-04-23T12:00:00.000Z"
}

字段	类型	描述
`success`	`boolean`	成功响应中始终为 `true`。
`data`	`object \| array`	响应负载。具体结构随接口而变化。
`timestamp`	`string`	生成响应时的 ISO 8601 UTC 时间戳。

错误响应

错误响应会返回 "success": false，并包含 error 对象：

{
  "success": false,
  "error": {
    "code": "PROTEIN_NOT_FOUND",
    "message": "Protein record does not exist."
  },
  "timestamp": "2026-04-23T12:00:00.000Z"
}

字段	类型	描述
`error.code`	`string`	机器可读的错误码，例如 `INVALID_QUERY`、`FILE_NOT_FOUND`。
`error.message`	`string`	错误描述。
`error.details`	`object?`	可选的字段级校验错误映射。

分页

列表接口会在响应中嵌入 pagination 对象：

{
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "total": 48200,
    "totalPages": 4820,
    "hasNext": true,
    "hasPrev": false
  }
}

字段	类型	描述
`page`	`int`	当前页码，从 1 开始。
`pageSize`	`int`	每页条目数。
`total`	`int`	匹配记录总数。
`totalPages`	`int`	总页数。
`hasNext`	`boolean`	是否存在下一页。
`hasPrev`	`boolean`	是否存在上一页。

HTTP 状态码

状态码	含义
`200`	成功。
`400`	请求错误，缺少参数或参数无效。
`404`	资源不存在。
`500`	服务器内部错误。
`503`	服务不可用。

响应格式

成功响应

错误响应

分页

HTTP 状态码

目录