宠物档案接口总览
本页汇总宠物档案的公共约定、数据对象与校验规则。每个接口的完整请求、完整返回示例和字段说明见对应接口页。
统一 JSON 响应
json
{
"code": 200,
"message": "success",
"data": {}
}| 字段 | 类型 | 说明 |
|---|---|---|
code | integer | 200 表示成功;失败时为业务错误码,与 HTTP 状态一致。 |
message | string | 状态提示信息:成功固定为 "success"(网关统一归一化),失败时为安全的中文提示。不要用它做程序判断。 |
data | any | 业务数据;结构与内容随接口变化。 |
列表不返回分页统计
列表接口接受 page、limit 等参数,但响应体只有 code、message、data 三个字段,不返回 page_info、total 或 total_pages。需要总数时请由接入方自行累计,或按返回条数是否等于 limit 判断是否还有下一页。
接口一览
| 接口 | 方法 | 返回 | 用途 |
|---|---|---|---|
/pets/pet-info | GET | 品种目录 | 前置:查询标准品种库,取得创建/更新档案用的 breed_code。 |
/pet-profiles | POST | 单个档案 | 创建宠物档案。 |
/pet-profiles | GET | data 为档案数组 | 分页查询档案列表。 |
/pet-profiles/{pet_profile_id} | GET | 档案 + records | 查询档案详情。 |
/pet-profiles/{pet_profile_id} | PATCH | 更新后的档案 | 部分更新档案。 |
/pet-profiles/{pet_profile_id} | DELETE | {"id": 44} | 逻辑删除档案。 |
数据对象:PetProfile
| 字段 | 类型 | 可写 | 说明 |
|---|---|---|---|
id | integer | 否 | 宠物档案 ID,创建后由平台生成。 |
name | string | 是 | 宠物名,创建必填,最长 64 个字符。 |
avatar | string | null | 是 | 头像 URL,最长 500 个字符。 |
birthday | string(date-time) | null | 是 | 出生日期。 |
gender | integer | null | 是 | 1 公、2 母、null 未知。 |
pet_type | integer | null | 是 | 1 猫、2 狗、3 异宠、null 未指定。 |
pet_variety | string | null | 是 | 调用方填写的品种文本,最长 100 个字符。 |
breed_code | string | null | 是 | 标准品种编码,最长 64 个字符。 |
weight | string | null | 是 | 体重,带单位的字符串,如 "10.10kg",最长 20 个字符。 |
is_neutered | integer | null | 是 | 0 未绝育、1 已绝育、null 未知。 |
locale | string | 否 | 本次响应实际使用的展示语言。 |
breed_display_name | string | null | 否 | 按 locale 返回的标准品种展示名。 |
created_at / updated_at | string(date-time) | 否 | 创建与更新时间。 |
records | object | 否 | 仅详情接口返回:按 record_type 分组的扩展记录;无记录时为 {}。 |
字段校验规则
| 字段 | 规则 |
|---|---|
name | 必填(创建时),最长 64 个字符。 |
gender | 只能是 1、2 或 null。 |
pet_type | 只能是 1、2、3 或 null。 |
is_neutered | 只能是 0、1 或 null。 |
breed_code | 非空时必须存在于平台标准品种库;pet_type 为猫或狗时品种类别必须匹配。 |
weight | 字符串,建议始终带单位(如 kg)。 |
birthday | ISO 8601 date-time 字符串。未知值用 null,不要用空字符串。 |
错误处理
| HTTP 状态 | 含义 | 调用方处理 |
|---|---|---|
400 | 业务规则不满足,例如 locale 未启用、品种与类型不匹配。 | 读取 message 修正输入。 |
401 / 403 | Token 缺失、无效或权限不足。 | 重新换取 Token;不要传递内部身份字段。 |
404 | 档案不存在、已删除或不属于当前用户。 | 刷新本地状态,不要当作可安全重试。 |
422 | 字段类型、长度或格式不符合 Schema。 | 按字段规则修正后重试。 |
429 | 触发限流。 | 退避后重试。 |
5xx | 服务或依赖暂时不可用。 | 读取类可重试;写操作先确认上一次结果,避免重复创建。 |
未纳入本轮的接口
宠物扩展记录(/pet-profiles/{pet_profile_id}/records 系列)在当前对外流程中没有被使用,因此本轮没有整理成接口页。需要时再单独评估。