宠物鉴权接口文档
概览
- 基础路径: /api
- 文档范围: 鉴权路由中的 pet 模块接口
- 鉴权方式: 请求头 X-Token
- Content-Type: application/json
鉴权头
| 字段 |
类型 |
必填 |
说明 |
| X-Token |
string |
是 |
用户登录后获得的 JWT Token |
统一响应格式
{
"code": 200,
"msg": "操作成功",
"data": {}
}
返回字段说明
| 字段 |
类型 |
说明 |
| code |
integer |
业务状态码，200 表示成功，其他值表示失败 |
| msg |
string |
响应消息 |
| data |
object/array/null |
业务数据 |
通用鉴权失败响应
{
"code": 401,
"msg": "未登录或登录过期",
"data": null
}
{
"code": 401,
"msg": "登录已过期，请重新登录",
"data": null
}
宠物对象字段说明
| 字段 |
类型 |
说明 |
| id |
string |
宠物公开 ID |
| userId |
integer |
所属用户 ID |
| deviceId |
string |
关联设备 ID |
| name |
string |
宠物名称 |
| type |
string |
宠物类型，如 狗狗、猫咪、其他 |
| breed |
string |
品种 |
| age |
string |
年龄段，如 幼年、成年、老年 |
| gender |
string |
性别，如 男生、女生 |
| avatar |
string |
宠物头像标识，当前通常为 emoji 或短字符串 |
| weight |
integer |
体重，单位克 |
| createdAt |
string |
创建时间 |
| updatedAt |
string |
更新时间 |
1. 获取宠物列表
- 路径: /api/pet/list
- 方法: POST
- 是否鉴权: 是
请求 Body 参数
| 字段 |
类型 |
必填 |
说明 |
| deviceId |
string |
否 |
设备唯一标识。不传时按当前用户查询所有宠物，传入时按设备查询 |
请求示例
{
"deviceId": "dev_001"
}
也可传空对象：
{}
成功响应示例
{
"code": 200,
"msg": "操作成功",
"data": [
{
"id": "pet_001",
"userId": 1,
"deviceId": "dev_001",
"name": "豆豆",
"type": "猫咪",
"breed": "英短",
"age": "成年",
"gender": "女生",
"avatar": "🐱",
"weight": 4200,
"createdAt": "2026-05-09T10:00:00Z",
"updatedAt": "2026-05-09T10:00:00Z"
}
]
}
返回参数说明
| 字段 |
类型 |
说明 |
| code |
integer |
成功时为 200 |
| msg |
string |
成功时为 操作成功 |
| data |
array |
宠物列表 |
| data[].* |
object |
宠物对象，字段见上方宠物对象字段说明 |
失败响应示例
{
"code": 400,
"msg": "参数错误",
"data": null
}
{
"code": 500,
"msg": "获取宠物列表失败",
"data": null
}
2. 添加宠物
- 路径: /api/pet/add
- 方法: POST
- 是否鉴权: 是
请求 Body 参数
| 字段 |
类型 |
必填 |
说明 |
| deviceId |
string |
否 |
关联设备 ID。传入时服务端会校验设备存在且归当前用户所有 |
| name |
string |
是 |
宠物名称 |
| type |
string |
是 |
宠物类型，如 狗狗、猫咪、其他 |
| breed |
string |
否 |
品种 |
| age |
string |
否 |
年龄段 |
| gender |
string |
否 |
性别 |
| avatar |
string |
否 |
头像标识 |
| weight |
integer |
否 |
体重，单位克 |
请求示例
{
"deviceId": "dev_001",
"name": "豆豆",
"type": "猫咪",
"breed": "英短",
"age": "成年",
"gender": "女生",
"avatar": "🐱",
"weight": 4200
}
成功响应示例
{
"code": 200,
"msg": "宠物添加成功",
"data": {
"id": "pet_001",
"userId": 1,
"deviceId": "dev_001",
"name": "豆豆",
"type": "猫咪",
"breed": "英短",
"age": "成年",
"gender": "女生",
"avatar": "🐱",
"weight": 4200,
"createdAt": "2026-05-09T10:00:00Z",
"updatedAt": "2026-05-09T10:00:00Z"
}
}
返回参数说明
| 字段 |
类型 |
说明 |
| code |
integer |
成功时为 200 |
| msg |
string |
成功时为 宠物添加成功 |
| data |
object |
新建的宠物对象 |
| data.* |
mixed |
宠物对象字段，见上方宠物对象字段说明 |
失败响应示例
{
"code": 400,
"msg": "参数错误",
"data": null
}
{
"code": 400,
"msg": "设备不存在",
"data": null
}
{
"code": 400,
"msg": "无权限操作",
"data": null
}
3. 更新宠物信息
- 路径: /api/pet/update
- 方法: POST
- 是否鉴权: 是
请求 Body 参数
| 字段 |
类型 |
必填 |
说明 |
| id |
string |
是 |
宠物公开 ID |
| name |
string |
否 |
新宠物名称 |
| breed |
string |
否 |
新品种 |
| age |
string |
否 |
新年龄段 |
| gender |
string |
否 |
新性别 |
| avatar |
string |
否 |
新头像标识 |
| weight |
integer |
否 |
新体重，单位克，仅当大于 0 时更新 |
请求示例
{
"id": "pet_001",
"name": "豆豆",
"breed": "金渐层",
"age": "成年",
"gender": "女生",
"avatar": "🐱",
"weight": 4500
}
成功响应示例
{
"code": 200,
"msg": "宠物信息已更新",
"data": null
}
返回参数说明
| 字段 |
类型 |
说明 |
| code |
integer |
成功时为 200 |
| msg |
string |
成功时为 宠物信息已更新 |
| data |
null |
无返回数据 |
失败响应示例
{
"code": 400,
"msg": "参数错误",
"data": null
}
{
"code": 400,
"msg": "宠物不存在",
"data": null
}
{
"code": 400,
"msg": "无权限操作",
"data": null
}
4. 删除宠物
- 路径: /api/pet/delete
- 方法: POST
- 是否鉴权: 是
请求 Body 参数
| 字段 |
类型 |
必填 |
说明 |
| id |
string |
是 |
宠物公开 ID |
请求示例
{
"id": "pet_001"
}
成功响应示例
{
"code": 200,
"msg": "宠物已删除",
"data": null
}
返回参数说明
| 字段 |
类型 |
说明 |
| code |
integer |
成功时为 200 |
| msg |
string |
成功时为 宠物已删除 |
| data |
null |
无返回数据 |
失败响应示例
{
"code": 400,
"msg": "参数错误",
"data": null
}
{
"code": 400,
"msg": "宠物不存在",
"data": null
}
{
"code": 400,
"msg": "无权限操作",
"data": null
}
附录
说明
- 获取宠物列表返回数组；无数据时返回空数组，而不是 null。
- 添加宠物时，deviceId 可为空；为空时宠物仅归属用户，不强制绑定设备。
- 更新宠物时，type 和 deviceId 当前不支持修改；仅支持更新名称、品种、年龄、性别、头像和体重。