Banner/GetBanners API 文档

📋 接口基本信息

GET https://hapi.caixiangxiang.com/Banner/GetBanners

功能描述：获取指定类型的Banner广告列表，支持智能地域定向功能。

📤 请求参数

参数名	类型	必填	默认值	说明
type_key	String	否	HOME_BANNER	Banner类型键值（如：HOME_BANNER, PRODUCT_BANNER等）
limit	Integer	否	10	返回Banner数量限制

📥 响应数据

成功响应

错误响应

HTTP状态码：200

{
  "statusCode": 200,
  "message": "获取成功",
  "data": [
    {
      "id": 1,
      "nav_menu_id": 1,
      "type_key": "HOME_BANNER",
      "type_name": "首页横幅",
      "title": "足球赛事",
      "img_url": "https://example.com/images/banner1.jpg",
      "jump_url": "https://example.com/promotion/football",
      "start_time": null,
      "end_time": null,
      "province": "",
      "city": "",
      "district": "",
      "sort_order": 100,
      "status": 1,
      "impressions": 1500,
      "click_throughs": 120,
      "admin_id": 1,
      "create_at": "2025-11-16 01:28:40",
      "updated_at": "2025-11-16 01:28:40",
      "is_active": true
    }
  ]
}
                

响应字段说明

字段	类型	说明
statusCode	Integer	状态码，200表示成功
message	String	操作结果消息
data	Array[Object]	Banner对象列表
data[].id	Integer	Banner的唯一标识
data[].type_key	String	Banner类型键值
data[].type_name	String	Banner类型名称
data[].title	String	Banner标题
data[].img_url	String	Banner图片地址
data[].jump_url	String	点击跳转地址
data[].is_active	Boolean	当前是否活跃状态

HTTP状态码	错误消息	可能原因
400	参数错误	参数格式不正确
401	认证失败	Token无效或过期
500	获取Banner失败	服务器内部错误

🔍 使用示例

获取首页Banner（默认类型，最多10个）

fetch('https://hapi.caixiangxiang.com/Banner/GetBanners', {
  headers: {
    'Authorization': 'Bearer your_access_token_here'
  }
})
.then(response => response.json())
.then(data => {
  if (data.statusCode === 200) {
    console.log('Banner数据:', data.data);
  }
});
                

获取产品Banner（最多5个）

fetch('https://hapi.caixiangxiang.com/Banner/GetBanners?type_key=PRODUCT_BANNER&limit=5', {
  headers: {
    'Authorization': 'Bearer your_access_token_here'
  }
})
.then(response => response.json())
.then(data => {
  // 处理返回的Banner数据
});
                

使用cURL调用

curl -X GET "https://hapi.caixiangxiang.com/Banner/GetBanners?type_key=HOME_BANNER&limit=5" \
  -H "Authorization: Bearer your_access_token_here"
                

📍 地域定向逻辑

系统按照以下优先级返回Banner：

精确区域匹配（省份+城市+区域完全匹配）
城市匹配（省份+城市匹配，区域为空）
省份匹配（仅省份匹配，城市和区域为空）
全国通用（省份、城市、区域都为空）

示例说明

假设用户当前城市为上海市黄浦区（城市代码：310101）：

优先返回：province=310000, city=310100, district=310101 的Banner
其次返回：province=310000, city=310100, district= 的Banner
再次返回：province=310000, city=, district= 的Banner
最后返回：province=, city=, district= 的Banner

💡 最佳实践

1. 缓存策略

建议客户端对Banner数据进行适当缓存，避免频繁请求：

静态Banner：缓存时间可设置较长（如1小时）
动态Banner：缓存时间较短（如5-10分钟）

2. 错误处理

async function loadBanners(typeKey, limit = 5) {
  try {
    const response = await fetch(`/Banner/GetBanners?type_key=${typeKey}&limit=${limit}`, {
      headers: { 'Authorization': 'Bearer ' + getToken() }
    });
    
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    
    const result = await response.json();
    
    if (result.statusCode === 200) {
      return result.data;
    } else {
      console.error('API返回错误:', result.message);
      return [];
    }
  } catch (error) {
    console.error('加载Banner失败:', error);
    // 返回备用Banner或空数组
    return getFallbackBanners();
  }
}
            