在线咨询

    十、商城站点API调用示例

    我们先分析一下商城站点有哪些页面，再拆解每一个页面所需要的接口。

    10.1 商城站点页面结构分析

    典型的商城站点通常包含以下页面：

    10.1.1 主要页面类型

    • 首页 - 展示最新商品、热门商品、推荐商品、促销活动等
    • 商品分类页 - 按分类展示商品列表
    • 商品详情页 - 展示单个商品的详细信息
    • 购物车页 - 用户选购商品的购物车页面
    • 订单确认页 - 确认订单信息的页面
    • 订单支付页 - 完成订单支付的页面
    • 个人中心页 - 用户个人信息和订单管理
    • 订单详情页 - 查看单个订单的详细信息
    • 我的订单页 - 用户订单列表
    • 收货地址页 - 管理用户收货地址
    • 商品搜索页 - 搜索商品结果页面
    • 促销活动页 - 优惠券、秒杀等促销活动页面
    • 用户相关页面 - 登录、注册、个人中心等

    10.2 各页面所需API接口详解

    10.2.1 首页

    商城首页是最重要的页面，通常包含多种内容展示。

    主要接口调用：

    1. 获取商品列表 (/api/archive/list)

      {
"moduleId": 2, // 商品模块ID
 "limit": 10,
 "page": 1,
 "order": "created_time desc"
}
      • 用途：获取最新商品列表
      • 参数：moduleId=2(商品模块ID是2)、limit(每页数量)、page(页码)、order(排序方式)

    2. 获取推荐商品 (/api/archive/list)

      {
"moduleId": 2, // 商品模块ID
 "flag": "c",  // 推荐商品
 "limit": 5
}
      • 用途：获取推荐商品列表
      • 参数：flag(推荐标识)、limit(数量)

    3. 获取热门商品 (/api/archive/list)

      {
"moduleId": 2, // 商品模块ID
 "order": "views desc",
 "limit": 5
}
      • 用途：获取点击量最高的商品
      • 参数：order(按浏览量排序)、limit(数量)

    4. 获取商品分类列表 (/api/category/list)

      {
"moduleId": 2, // 商品模块ID
 "limit": 10
}
      • 用途：获取所有商品分类，用于导航菜单

    5. 获取商品标签列表 (/api/tag/list)

      {
 "type": "list",
 "limit": 20
}
      • 用途：获取热门标签，用于标签云

    6. 获取系统设置 (/api/setting/system)

      • 用途：获取商城标题、描述、关键词等基础信息

    7. 获取首页设置 (/api/setting/index)

      • 用途：获取首页特定配置信息

    8. 获取导航列表 (/api/nav/list)

      • 用途：获取网站导航菜单

    9. 获取Banner列表 (/api/banner/list)

      • 用途：获取首页轮播图

    10. 获取促销活动信息 (/api/setting/system)

      • 用途：获取促销活动配置信息

    11. 获取优惠券列表 (/api/coupon/codes)

      {
  "limit": 5
}
      • 用途：获取可用的优惠券列表

    10.2.2 商品分类页面

    商品分类页面展示特定分类下的商品列表。

    主要接口调用：

    1. 获取分类详情 (/api/category/detail)

      {
 "id": 1
}
      • 用途：获取当前分类信息
      • 参数：id(分类ID) 或 filename(分类别名)

    2. 获取分类下商品列表 (/api/archive/list)

      {
"moduleId": 2, // 商品模块ID
 "categoryId": 1,
 "limit": 10,
 "page": 1
}
      • 用途：获取该分类下的商品列表
      • 参数：categoryId(分类ID)、limit(每页数量)、page(页码)

    3. 获取子分类列表 (/api/category/list)

      {
 "parentId": 1,
 "limit": 10
}
      • 用途：获取当前分类的子分类
      • 参数：parentId(父分类ID)

    4. 获取系统设置 (/api/setting/system)

      • 用途：获取网站基础信息

    5. 获取商品分类列表 (/api/category/list)

      • 用途：获取所有分类，用于侧边栏导航

    6. 获取筛选条件 (/api/archive/list)

      {
"moduleId": 2, // 商品模块ID
 "categoryId": 1,
 "type": "filter"
}
      • 用途：获取当前分类下的筛选条件

    10.2.3 商品详情页面

    商品详情页面展示单个商品的完整信息。

    主要接口调用：

    1. 获取商品详情 (/api/archive/detail)

      {
 "id": 1
}
      • 用途：获取商品详细内容
      • 参数：id(商品ID) 或 filename(商品别名)

    2. 获取商品参数 (/api/archive/params)

      {
 "id": 1,
 "sorted": true
}
      • 用途：获取商品自定义参数
      • 参数：id(商品ID)、sorted(返回格式)

    3. 获取商品SKU信息 (/api/archive/sku)

      {
 "id": 1
}
      • 用途：获取商品SKU规格信息
      • 参数：id(商品ID)

    4. 获取上一个商品 (/api/archive/prev)

      {
 "id": 1
}
      • 用途：获取上一个商品信息

    5. 获取下一个商品 (/api/archive/next)

      {
 "id": 1
}
      • 用途：获取下一个商品信息

    6. 获取相关商品 (/api/archive/list)

      {
 "type": "related",
 "limit": 5,
 "id": 1
}
      • 用途：获取同分类的其他商品
      • 参数：type=“related”(相关商品类型)、limit(数量)、id(当前商品)

    7. 获取商品评论列表 (/api/comment/list)

      {
 "archive_id": 1,
 "limit": 10,
 "page": 1
}
      • 用途：获取商品评论列表
      • 参数：archive_id(商品ID)、limit(每页数量)、page(页码)

    8. 检查收藏状态 (/api/favorite/check)

      {
 "archive_id": 1
}
      • 用途：检查当前用户是否收藏了该商品
      • 需要认证

    9. 获取系统设置 (/api/setting/system)

      • 用途：获取网站基础信息

    10. 获取购物车商品数量 (/api/cart/list)

      • 用途：获取当前用户购物车中的商品数量
      • 需要认证

    10.2.4 购物车页面

    购物车页面展示用户已选择的商品。

    主要接口调用：

    1. 获取购物车列表 (/api/cart/list)

      • 用途：获取当前用户的购物车商品列表
      • 需要认证

    2. 更新购物车商品数量 (/api/cart/update)

      {
 "id": 1,
 "quantity": 2
}
      • 用途：更新购物车中某个商品的数量
      • 参数：id(购物车项目ID)、quantity(数量)
      • 需要认证

    3. 从购物车移除商品 (/api/cart/remove)

      {
 "id": 1
}
      • 用途：从购物车中移除某个商品
      • 参数：id(购物车项目ID)
      • 需要认证

    4. 获取系统设置 (/api/setting/system)

      • 用途：获取网站基础信息

    5. 获取优惠券列表 (/api/coupon/codes)

      • 用途：获取可用的优惠券列表
      • 需要认证

    10.2.5 订单确认页面

    订单确认页面用于确认订单信息。

    主要接口调用：

    1. 获取购物车列表 (/api/cart/list)

      • 用途：获取当前用户的购物车商品列表
      • 需要认证

    2. 获取收货地址列表 (/api/order/addresses)

      • 用途：获取用户的收货地址列表
      • 需要认证

    3. 获取默认收货地址 (/api/order/address)

      • 用途：获取用户的默认收货地址
      • 需要认证

    4. 获取商品结算信息 (/api/orders/checkout)

      {
 "cart_ids": [1, 2, 3]
}
      • 用途：获取商品结算信息（价格、运费等）
      • 参数：cart_ids(购物车项目ID列表)
      • 需要认证

    5. 获取优惠券列表 (/api/coupon/codes)

      • 用途：获取可用的优惠券列表
      • 需要认证

    6. 获取系统设置 (/api/setting/system)

      • 用途：获取网站基础信息

    10.2.6 订单支付页面

    订单支付页面用于完成订单支付。

    主要接口调用：

    1. 创建订单 (/api/order/create)

      {
 "address_id": 1,
 "coupon_id": 2,
 "remark": "订单备注",
 "cart_ids": [1, 2, 3]
}
      • 用途：创建新订单
      • 参数：address_id(收货地址ID)、coupon_id(优惠券ID)、remark(备注)、cart_ids(购物车项目ID列表)
      • 需要认证

    2. 获取订单详情 (/api/order/detail)

      {
 "order_id": "202211232209080046"
}
      • 用途：获取订单详情
      • 参数：order_id(订单ID)
      • 需要认证

    3. 订单支付 (/api/order/payment)

      {
 "order_id": "202211232209080046",
 "pay_way": "alipay"
}
      • 用途：发起订单支付
      • 参数：id(订单ID)、payment_method(支付方式)
      • 需要认证

    4. 获取系统设置 (/api/setting/system)

      • 用途：获取网站基础信息

    10.2.7 个人中心页面

    个人中心页面展示用户个人信息和订单管理。

    主要接口调用：

    1. 获取用户详情 (/api/user/detail)

      • 用途：获取当前用户详细信息
      • 需要认证

    2. 获取用户订单列表 (/api/orders)

      {
 "limit": 5,
 "page": 1
}
      • 用途：获取用户订单列表
      • 参数：limit(每页数量)、page(页码)
      • 需要认证

    3. 获取用户收藏列表 (/api/favorite/list)

      {
 "limit": 5,
 "page": 1
}
      • 用途：获取用户收藏的商品列表
      • 参数：limit(每页数量)、page(页码)
      • 需要认证

    4. 获取用户愿望清单 (/api/wishlist)

      • 用途：获取用户愿望清单
      • 需要认证

    5. 获取用户收货地址列表 (/api/order/addresses)

      • 用途：获取用户收货地址列表
      • 需要认证

    6. 获取用户评论列表 (/api/comment/list)

      {
 "user_id": 1,
 "limit": 5,
 "page": 1
}
      • 用途：获取用户发表的评论
      • 参数：user_id(用户ID)、limit(每页数量)、page(页码)
      • 需要认证

    7. 获取系统设置 (/api/setting/system)

      • 用途：获取网站基础信息

    10.2.8 订单详情页面

    订单详情页面展示单个订单的详细信息。

    主要接口调用：

    1. 获取订单详情 (/api/order/detail)

      {
 "order_id": "202211232209080046"
}
      • 用途：获取订单详细信息
      • 参数：order_id(订单ID)
      • 需要认证

    2. 获取系统设置 (/api/setting/system)

      • 用途：获取网站基础信息

    3. 获取订单评价 (/api/review/list)

      {
 "order_id": "202211232209080046"
}
      • 用途：获取订单商品的评价
      • 参数：order_id(订单ID)
      • 需要认证

    10.2.9 我的订单页面

    我的订单页面展示用户的所有订单。

    主要接口调用：

    1. 获取用户订单列表 (/api/orders)

      {
 "limit": 10,
 "page": 1,
 "status": "paid"
}
      • 用途：获取用户订单列表
      • 参数：limit(每页数量)、page(页码)、status(订单状态)
      • 需要认证

    2. 取消订单 (/api/order/cancel)

      {
 "order_id": "202211232209080046"
}
      • 用途：取消订单
      • 参数：order_id(订单ID)
      • 需要认证

    3. 完成订单 (/api/order/finished)

      {
 "order_id": "202211232209080046"
}
      • 用途：完成订单
      • 参数：order_id(订单ID)
      • 需要认证

    4. 获取系统设置 (/api/setting/system)

      • 用途：获取网站基础信息

    10.2.10 收货地址页面

    收货地址页面用于管理用户的收货地址。

    主要接口调用：

    1. 获取收货地址列表 (/api/order/addresses)

      • 用途：获取用户收货地址列表
      • 需要认证

    2. 保存收货地址 (/api/order/address)

      {
 "name": "收货人姓名",
 "phone": "收货人电话",
 "province": "省份",
 "city": "城市",
 "country": "区域",
 "address": "详细地址",
 "is_default": 1
}
      • 用途：保存收货地址
      • 参数：name(姓名)、phone(电话)、province(省份)、city(城市)、country(区域)、address(详细地址)、is_default(是否默认)
      • 需要认证

    3. 获取系统设置 (/api/setting/system)

      • 用途：获取网站基础信息

    10.2.11 商品搜索页面

    商品搜索页面展示搜索关键词相关的商品。

    主要接口调用：

    1. 搜索商品列表 (/api/archive/list)

      {
 "moduleId": 2, // 商品模块ID
 "q": "关键词",
 "limit": 10,
 "page": 1
}
      • 用途：搜索包含关键词的商品
      • 参数：q(搜索关键词)、limit(每页数量)、page(页码)

    2. 获取热门搜索 (/api/archive/list)

      {
 "moduleId": 2, // 商品模块ID
 "order": "views desc",
 "limit": 10
}
      • 用途：获取热门搜索内容

    3. 获取搜索建议 (/api/archive/list)

      {
 "moduleId": 2, // 商品模块ID
 "q": "关键词前缀",
 "limit": 5
}
      • 用途：获取搜索建议

    4. 获取系统设置 (/api/setting/system)

      • 用途：获取网站基础信息

    10.2.12 促销活动页面

    促销活动页面展示优惠券、秒杀等促销活动。

    主要接口调用：

    1. 获取优惠券列表 (/api/coupon/codes)

      {
 "limit": 10,
 "page": 1
}
      • 用途：获取优惠券列表
      • 参数：limit(每页数量)、page(页码)

    2. 获取有效优惠券列表 (/api/coupon/valid)

      • 用途：获取当前有效的优惠券列表

    3. 获取优惠券码 (/api/coupon/code)

      {
 "id": 1
}
      • 用途：获取优惠券码
      • 参数：id(优惠券ID)
      • 需要认证

    4. 获取限时秒杀商品 (/api/archive/list)

      {
 "moduleId": 2, // 商品模块ID
 "flag": "s",  // 秒杀标识
 "limit": 10,
 "page": 1
}
      • 用途：获取秒杀商品列表

    5. 获取系统设置 (/api/setting/system)

      • 用途：获取网站基础信息

    10.2.13 用户相关页面

    10.2.13.1 登录页面

    主要接口调用：

    1. 用户登录 (/api/login) 
      
{
 "user_name": "用户名",
 "password": "密码"
}
      • 用途：用户登录认证
      • 参数：user_name(用户名)、password(密码)、email(邮箱)、phone(手机号)
    10.2.13.2 注册页面

    主要接口调用：

    1. 用户注册 (/api/register)

      {
 "user_name": "用户名",
 "password": "密码",
 "email": "邮箱",
 "captcha_id": "验证码ID",
 "captcha": "验证码"
}
      • 用途：新用户注册
      • 参数：user_name(用户名)、password(密码)、email(邮箱)、captcha(验证码)

    2. 获取验证码 (/api/captcha)

      • 用途：获取图形验证码

    3. 发送邮箱验证 (/api/verify/email)

      {
 "email": "邮箱地址"
}
      • 用途：发送邮箱验证码
    10.2.13.3 个人中心页面

    主要接口调用：

    1. 获取用户详情 (/api/user/detail)

      • 用途：获取当前用户详细信息
      • 需要认证

    2. 更新用户信息 (/api/user/update)

      {
 "real_name": "真实姓名",
 "email": "邮箱"
}
      • 用途：更新用户信息
      • 需要认证

    3. 更新用户头像 (/api/user/avatar)

      • 用途：更新用户头像
      • 需要认证

    4. 更新用户密码 (/api/user/password)

      {
 "old_password": "旧密码",
 "password": "新密码"
}
      • 用途：更新用户密码
      • 需要认证

    5. 重置用户密码 (/api/user/password/reset)

      {
 "email": "邮箱",
 "password": "新密码",
 "token": "验证token",
 "code": "验证码"
}
      • 用途：重置用户密码

    10.3 页面加载流程示例

    以商品详情页为例，说明完整的API调用流程：

    10.3.1 页面初始化

    1. 获取商品详情
    2. 增加商品浏览量（通过后续请求或服务端处理）
    3. 获取商品SKU信息

    10.3.2 侧边栏内容加载

    1. 获取上一个/下一个商品
    2. 获取相关商品推荐
    3. 获取热门商品列表

    10.3.3 评论区域加载

    1. 获取商品评论列表
    2. 如果用户已登录，获取用户对当前商品的收藏状态

    10.3.4 购物车功能

    1. 获取购物车商品数量（如果用户已登录）
    2. 添加到购物车（需要认证）

    10.3.5 交互功能

    1. 发布评论（需要认证）
    2. 收藏/取消收藏（需要认证）
    3. 评论点赞（需要认证）

    10.4 常见页面组合调用

    10.4.1 首页 + 分类页组合

    // 并行请求多个接口
Promise.all([
  fetch('/api/archive/list', { params: { moduleId: 2, limit: 10, page: 1 } }),
  fetch('/api/category/list', { params: { moduleId: 2, limit: 10 } }),
  fetch('/api/tag/list', { params: { type: 'list', limit: 20 } }),
  fetch('/api/setting/system'),
  fetch('/api/coupon/codes', { params: { limit: 5 } })
]).then(responses => {
  // 处理所有响应数据
  const [products, categories, tags, settings, coupons] = responses;
  // 渲染页面
});

    10.4.2 商品详情页完整调用

    // 串行或并行调用多个接口
const productId = 1;
Promise.all([
  fetch(`/api/archive/detail`, { params: { id: productId } }),
  fetch(`/api/archive/params`, { params: { id: productId } }),
  fetch(`/api/archive/sku`, { params: { id: productId } }),
  fetch(`/api/archive/prev`, { params: { id: productId } }),
  fetch(`/api/archive/next`, { params: { id: productId } }),
  fetch(`/api/comment/list`, { params: { archive_id: productId, limit: 10 } }),
  fetch(`/api/setting/system`)
]).then(responses => {
  const [product, params, sku, prev, next, comments, settings] = responses;
  // 组合数据并渲染页面
});

    10.4.3 订单确认页完整调用

    // 订单确认页面的API调用
const cartIds = [1, 2, 3];
Promise.all([
  fetch('/api/cart/list'),
  fetch('/api/order/addresses'),
  fetch('/api/orders/checkout', { params: { cart_ids: cartIds } }),
  fetch('/api/coupon/codes'),
  fetch('/api/setting/system')
]).then(responses => {
  const [cart, addresses, checkout, coupons, settings] = responses;
  // 组合数据并渲染页面
});

    可以看出一个完整的商城站点需要调用多个API接口来构建各个页面，开发者可以根据实际需求选择合适的接口组合，实现丰富的商城功能。

    结语

    通过本指南，您可以系统地了解和使用 AnQiCMS API，从基础概念到高级用法，逐步掌握接口的使用方法。建议按照指南的顺序逐步学习，并结合实际项目进行练习。