宠物商城系统接口文档（用户 / 宠物 / 订单）

基于RESTful 规范 设计，包含用户模块、宠物模块、订单模块核心接口，支持前后端直接对接，接口清晰、可直接用于开发。

通用规范

请求方式：GET (查询)、POST (新增)、PUT (修改)、DELETE (删除)
数据格式 ：请求 / 响应均使用 JSON
基础路径 ：/api/v1
统一响应格式

json

复制代码

{
  "code": 200,        // 状态码：200成功，400参数错误，401未授权，500服务器异常
  "msg": "操作成功",  // 提示信息
  "data": {}          // 业务数据
}

一、用户模块接口

负责用户注册、登录、信息管理（核心身份接口）

1. 用户注册

接口地址 ：POST /api/v1/user/register
请求参数

json

复制代码

{
  "username": "zhangsan",    // 用户名（必填）
  "password": "123456",      // 密码（必填）
  "phone": "13800138000",    // 手机号（必填）
  "nickname": "张三"         // 昵称（可选）
}

响应示例

json

复制代码

{
  "code": 200,
  "msg": "注册成功",
  "data": { "userId": 1001 }
}

2. 用户登录

接口地址 ：POST /api/v1/user/login
请求参数

json

复制代码

{
  "username": "zhangsan",
  "password": "123456"
}

响应示例

json

复制代码

{
  "code": 200,
  "msg": "登录成功",
  "data": {
    "userId": 1001,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // 身份凭证
    "nickname": "张三"
  }
}

3. 获取用户信息

接口地址 ：GET /api/v1/user/info
请求头 ：Authorization: Bearer {token}
响应示例

json

复制代码

{
  "code": 200,
  "msg": "success",
  "data": {
    "userId": 1001,
    "username": "zhangsan",
    "nickname": "张三",
    "phone": "13800138000",
    "createTime": "2025-05-20 10:00:00"
  }
}

4. 修改用户信息

接口地址 ：PUT /api/v1/user/update
请求头 ：Authorization: Bearer {token}
请求参数

json

复制代码

{
  "nickname": "张三_new",
  "phone": "13900139000"
}

二、宠物模块接口

负责宠物信息查询、上架、修改（商品核心接口）

1. 查询宠物列表（分页）

接口地址 ：GET /api/v1/pet/list
请求参数 （Query）
- page：页码（默认 1）
- size：每页条数（默认 10）
- category：宠物分类（可选，如：猫 / 狗 / 仓鼠）
- status：状态（0 下架 1 上架）
响应示例

json

复制代码

{
  "code": 200,
  "msg": "success",
  "data": {
    "total": 50,
    "pages": 5,
    "current": 1,
    "records": [
      {
        "petId": 1,
        "petName": "布偶猫",
        "category": "猫",
        "age": "6个月",
        "price": 3999.00,
        "stock": 10,
        "petPic": "https://xxx.com/cat.jpg",
        "status": 1
      }
    ]
  }
}

2. 查询宠物详情

接口地址 ：GET /api/v1/pet/detail/{petId}
路径参数：petId 宠物 ID
响应示例

json

复制代码

{
  "code": 200,
  "msg": "success",
  "data": {
    "petId": 1,
    "petName": "布偶猫",
    "category": "猫",
    "age": "6个月",
    "price": 3999.00,
    "stock": 10,
    "petPic": "https://xxx.com/cat.jpg",
    "detail": "温顺粘人，疫苗齐全",
    "createTime": "2025-05-18 14:30:00",
    "status": 1
  }
}

3. 新增宠物（管理员）

接口地址 ：POST /api/v1/pet/add
请求参数

json

复制代码

{
  "petName": "金毛犬",
  "category": "狗",
  "age": "1岁",
  "price": 2599.00,
  "stock": 8,
  "petPic": "https://xxx.com/dog.jpg",
  "detail": "性格活泼，适合家养"
}

4. 修改宠物信息

接口地址 ：PUT /api/v1/pet/update
请求参数（包含 petId）

5. 上下架宠物

接口地址 ：PUT /api/v1/pet/status
请求参数

json

复制代码

{
  "petId": 1,
  "status": 0  // 0下架 1上架
}

三、订单模块接口

负责订单创建、查询、支付、取消（交易核心接口）

1. 创建订单

接口地址 ：POST /api/v1/order/create
请求头 ：Authorization: Bearer {token}
请求参数

json

复制代码

{
  "petId": 1,          // 宠物ID
  "buyNum": 1,         // 购买数量
  "receiver": "张三",  // 收货人
  "phone": "13800138000",
  "address": "北京市朝阳区XX小区"
}

响应：返回订单 ID、订单金额

2. 查询我的订单列表

接口地址 ：GET /api/v1/order/myList
请求头 ：Authorization: Bearer {token}
请求参数：page、size、orderStatus (可选)
订单状态：0 待支付 1 已支付 2 已发货 3 已完成 4 已取消
响应示例

json

复制代码

{
  "code": 200,
  "msg": "success",
  "data": {
    "total": 5,
    "records": [
      {
        "orderId": "ORDER20250520001",
        "petName": "布偶猫",
        "petPic": "https://xxx.com/cat.jpg",
        "totalPrice": 3999.00,
        "orderStatus": 0,
        "createTime": "2025-05-20 11:20:00"
      }
    ]
  }
}

3. 查询订单详情

接口地址 ：GET /api/v1/order/detail/{orderId}

4. 取消订单

接口地址 ：PUT /api/v1/order/cancel/{orderId}
请求头 ：Authorization: Bearer {token}

5. 订单支付

接口地址 ：PUT /api/v1/order/pay/{orderId}
请求头 ：Authorization: Bearer {token}

总结

这套接口覆盖用户、宠物、订单三大核心业务，满足宠物商城基础功能
统一响应格式、权限校验，前后端可直接对接开发
可直接用于毕业设计、课程设计、小型商城项目开发
支持快速扩展：支付、评价、购物车等接口