约定与错误

分页

列表接口支持两个分页参数：

参数	默认值	说明
`page`	`1`	页码，小于 1 时按 1 处理。
`pageSize`	`50`	每页数量，当前最大值为 200。

列表接口通常支持一个轻量查询参数：

接口	查询参数	匹配字段
`/api/v1/items`	`q`	`id`、`name`、`type`
`/api/v1/characters`	`q`	`id`、`name`、`engName`、`profession`
`/api/v1/weapons`	`q`	`id`、`name`、`weaponType`、`weaponTypeName`
`/api/v1/equips`	`q`	`id`、`itemId`、`name`、`suitName`、`partType`
`/api/v1/world-energy`	`region`	`id`、`name`、`groupName`、`gameCategory`

错误响应统一使用 error 包裹：

{
  "error": {
    "code": "NOT_FOUND",
    "message": "资源不存在"
  }
}

常见状态码：

状态码	code	触发场景
`401`	`Unauthorized`	请求缺少有效 Bearer token。
`404`	`NOT_FOUND`	路径不存在、详情资源不存在，或请求了不支持的语言。
`413`	`TOO_LARGE`	`/api/v1/i18n/{locale}` 请求的 `ids` 为空或超过最大单次查询量。
`500`	`INTERNAL_ERROR`	服务端未处理异常。

/api/v1/i18n/{locale} 支持：

br, cn, zh, zh-cn, de, en, fr, id, it, jp, ja, kr, ko,
mx, ru, tc, zh-tw, th, vn, vi