热门赛事系统 API 文档

基于Yii框架的热门赛事管理系统接口文档

热门赛事列表

赛事详情

推荐赛事

🏆 热门赛事列表接口

📋 接口基本信息

GET /event/GetHotEvents

功能描述：获取热门赛事列表，支持多条件筛选、分页和排序功能。

📤 请求参数

参数名	类型	必填	默认值	说明
limit	Integer	否	10	返回数量限制
city	String	否	空	城市筛选条件
page	Integer	否	1	页码，从1开始
pageSize	Integer	否	20	每页数量
is_recommend	Integer	否	null	推荐状态筛选：1-推荐，0-不推荐
keyword	String	否	空	关键词搜索（标题、描述、场馆）
sport_type	String	否	空	运动类型筛选

📥 响应数据

成功响应

错误响应

HTTP状态码：200

{ "code": 200, "message": "获取成功", "data": { "list": [ { "id": 1, "title": "城市马拉松大赛2025", "cover_image": "/images/event1.jpg", "price_info": { "market_price": 150.00, "sales_price": 120.00, "member_price": 110.00, "agent_price": 100.00, "has_discount": true, "discount_rate": 20.0, "final_price": 120.00 }, "short_description": "年度城市马拉松赛事，欢迎参与", "address": "北京市朝阳区体育中心", "province": "北京市", "city": "北京市", "district": "朝阳区", "venue": "朝阳体育中心", "signup_deadline": "2025-12-30 18:00:00", "start_time": "2025-12-31 08:00:00", "is_recommend": 1, "recommend_weight": 90, "status": 1, "create_at": "2025-12-01 10:00:00", "updated_at": "2025-12-01 10:00:00", "days_remaining": 2, "is_urgent": true, "time_status": "signup_available" } ], "pagination": { "totalCount": 150, "pageSize": 20, "currentPage": 1, "pageCount": 8 } } }

响应字段说明

字段	类型	说明
code	Integer	状态码，200表示成功
message	String	操作结果消息
data	Object	数据对象
data.list	Array[Object]	赛事对象列表
data.list[].id	Integer	赛事的唯一标识
data.list[].title	String	赛事标题
data.list[].cover_image	String	赛事封面图URL
data.list[].price_info	Object	价格信息对象
data.list[].price_info.market_price	Decimal	门市价格（划线价）
data.list[].price_info.sales_price	Decimal	实际销售价格
data.list[].price_info.member_price	Decimal	会员价格
data.list[].price_info.agent_price	Decimal	代理价格
data.list[].price_info.has_discount	Boolean	是否有折扣
data.list[].price_info.discount_rate	Float	折扣比例（0-100）
data.list[].venue	String	场馆名称
data.list[].signup_deadline	String	报名截止时间
data.list[].start_time	String	比赛开始时间
data.list[].days_remaining	Integer	剩余报名天数
data.list[].is_urgent	Boolean	是否紧急（3天内截止）
data.list[].time_status	String	时间状态：signup_available-可报名，signup_ended-报名截止，ended-已结束
data.pagination	Object	分页信息对象
data.pagination.totalCount	Integer	总记录数
data.pagination.pageSize	Integer	每页数量
data.pagination.currentPage	Integer	当前页码
data.pagination.pageCount	Integer	总页数

HTTP状态码	错误消息	可能原因
500	获取热门赛事失败	服务器内部错误

🔍 使用示例

JavaScript Fetch 示例

// 获取热门赛事列表 fetch('/event/GetHotEvents?city=北京&page=1&pageSize=10&is_recommend=1') .then(response => response.json()) .then(data => { if (data.code === 200) { console.log('赛事数据:', data.data.list); console.log('分页信息:', data.data.pagination); // 处理赛事数据 } }) .catch(error => { console.error('获取赛事列表失败:', error); });

PHP cURL 示例

// 使用cURL获取热门赛事 $ch = curl_init(); $url = 'http://yourdomain.com/event/GetHotEvents?city=北京&page=1&pageSize=10'; curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); curl_close($ch); $data = json_decode($response, true); if ($data['code'] === 200) { $events = $data['data']['list']; $pagination = $data['data']['pagination']; // 处理赛事数据 }

📄 赛事详情接口

📋 接口基本信息

GET /event/GetEventDetail/{id}

功能描述：获取指定赛事的详细信息，包括完整内容和相关元数据。

📤 请求参数

参数名	类型	必填	默认值	说明
id	Integer	是	无	赛事的唯一标识ID

📥 响应数据

成功响应

错误响应

HTTP状态码：200

{ "code": 200, "message": "获取成功", "data": { "id": 1, "title": "城市马拉松大赛2025", "cover_image": "/images/event1.jpg", "short_description": "年度城市马拉松赛事，欢迎参与", "address": "北京市朝阳区体育中心", "province": "北京市", "city": "北京市", "district": "朝阳区", "venue": "朝阳体育中心", "signup_deadline": "2025-12-30 18:00:00", "start_time": "2025-12-31 08:00:00", "event_arrangement": "

详细赛事安排...

", "event_notes": "

赛事须知内容...

", "other_notes": "

其他注意事项...

", "price_info": { "market_price": 150.00, "sales_price": 120.00, "member_price": 110.00, "agent_price": 100.00, "has_discount": true, "discount_rate": 20.0, "final_price": 120.00 }, "is_recommend": 1, "recommend_weight": 90, "status": 1, "create_at": "2025-12-01 10:00:00", "updated_at": "2025-12-01 10:00:00", "days_remaining": 2, "is_urgent": true, "time_status": "signup_available", "shop_info": { "name": "朝阳体育中心", "contact_phone": "010-12345678", "business_hours": "08:00-22:00", "detailed_address": "北京市朝阳区体育中心路1号", "latitude": 39.9042, "longitude": 116.4074 }, "venue_info": { "venue_type": 1, "sport_type": "马拉松,田径", "venue_level": 2, "max_capacity": 10000, "venue_area": 50000.00, "facility_details": "标准田径场、更衣室、医疗点" } } }

响应字段说明

字段	类型	说明
code	Integer	状态码，200表示成功
message	String	操作结果消息
data	Object	赛事详情对象
data.id	Integer	赛事的唯一标识
data.title	String	赛事标题
data.event_arrangement	String	赛事安排（富文本）
data.event_notes	String	赛事须知（富文本）
data.other_notes	String	其他须知（富文本）
data.shop_info	Object	商铺信息对象
data.shop_info.name	String	商铺名称
data.shop_info.contact_phone	String	联系电话
data.shop_info.business_hours	String	营业时间
data.venue_info	Object	场馆详细信息对象
data.venue_info.venue_type	Integer	场所类型：1-体育场馆，2-会议中心，3-室外场地，4-多功能厅，5-其他
data.venue_info.sport_type	String	主营运动类型（多选逗号分隔）
data.venue_info.venue_level	Integer	场馆等级：1-国际标准，2-国家级，3-省级，4-市级，5-其他
data.venue_info.max_capacity	Integer	最大容纳人数
data.venue_info.venue_area	Decimal	场地面积（平方米）
data.venue_info.facility_details	String	设施详情

HTTP状态码	错误消息	可能原因
404	赛事不存在	指定的赛事ID不存在
403	赛事已下架	赛事状态为下架
500	获取赛事详情失败	服务器内部错误

🔍 使用示例

JavaScript Fetch 示例

// 获取赛事详情 fetch('/event/GetEventDetail/1') .then(response => response.json()) .then(data => { if (data.code === 200) { console.log('赛事详情:', data.data); // 处理赛事详情数据 displayEventDetail(data.data); } else { console.error('获取赛事详情失败:', data.message); } }) .catch(error => { console.error('请求失败:', error); });

处理富文本内容示例

// 获取赛事详情并处理富文本内容 fetch('/event/GetEventDetail/1') .then(response => response.json()) .then(data => { if (data.code === 200) { const event = data.data; // 处理富文本内容 if (event.event_arrangement) { document.getElementById('event-arrangement').innerHTML = event.event_arrangement; } if (event.event_notes) { document.getElementById('event-notes').innerHTML = event.event_notes; } // 显示价格信息 displayPriceInfo(event.price_info); } });

⭐ 推荐赛事接口

📋 接口基本信息

GET /event/GetRecommendedEvents

功能描述：获取推荐赛事列表（置顶推荐），适合在首页展示重要赛事。

📤 请求参数

参数名	类型	必填	默认值	说明
limit	Integer	否	5	返回数量限制
city	String	否	空	城市筛选条件

📥 响应数据

成功响应

错误响应

HTTP状态码：200

{ "code": 200, "message": "获取成功", "data": [ { "id": 1, "title": "城市马拉松大赛2025", "cover_image": "/images/event1.jpg", "price_info": { "market_price": 150.00, "sales_price": 120.00, "member_price": 110.00, "agent_price": 100.00, "has_discount": true, "discount_rate": 20.0, "final_price": 120.00 }, "short_description": "年度城市马拉松赛事，欢迎参与", "address": "北京市朝阳区体育中心", "venue": "朝阳体育中心", "signup_deadline": "2025-12-30 18:00:00", "start_time": "2025-12-31 08:00:00", "is_recommend": 1, "recommend_weight": 90, "days_remaining": 2, "is_urgent": true, "time_status": "signup_available" }, { "id": 2, "title": "篮球邀请赛2025", "cover_image": "/images/event2.jpg", "price_info": { "market_price": 80.00, "sales_price": 60.00, "member_price": 50.00, "agent_price": 45.00, "has_discount": true, "discount_rate": 25.0, "final_price": 60.00 }, "short_description": "年度篮球邀请赛，强队云集", "address": "北京市海淀区体育馆", "venue": "海淀体育馆", "signup_deadline": "2025-12-28 18:00:00", "start_time": "2025-12-29 09:00:00", "is_recommend": 1, "recommend_weight": 85, "days_remaining": 0, "is_urgent": false, "time_status": "signup_ended" } ] }

HTTP状态码	错误消息	可能原因
500	获取推荐赛事失败	服务器内部错误

🔍 使用示例

JavaScript Fetch 示例

// 获取推荐赛事 fetch('/event/GetRecommendedEvents?limit=5&city=北京') .then(response => response.json()) .then(data => { if (data.code === 200) { console.log('推荐赛事:', data.data); // 在首页展示推荐赛事 displayRecommendedEvents(data.data); } }) .catch(error => { console.error('获取推荐赛事失败:', error); });

💡 最佳实践

1. 错误处理

建议在调用API时添加完善的错误处理机制：

async function getEventDetail(id) { try { const response = await fetch(`/event/GetEventDetail/${id}`); if (!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } const result = await response.json(); if (result.code === 200) { return result.data; } else { console.error('API返回错误:', result.message); // 根据不同的错误码进行相应处理 switch(result.code) { case 404: // 处理赛事不存在的情况 showErrorMessage('赛事不存在或已删除'); break; case 403: // 处理赛事已下架的情况 showErrorMessage('该赛事已下架，暂时无法查看'); break; case 500: // 处理服务器错误 showErrorMessage('服务器繁忙，请稍后重试'); break; default: // 处理其他错误 showErrorMessage('获取赛事详情失败'); } return null; } } catch (error) { console.error('获取赛事详情失败:', error); showErrorMessage('网络错误，请检查网络连接'); return null; } }

2. 缓存策略

根据赛事的更新频率设置合适的缓存策略：

热门赛事列表：缓存时间较短（2-5分钟）
赛事详情：缓存时间适中（10-30分钟）
推荐赛事：缓存时间较长（1-2小时）

3. 性能优化

对于赛事列表页，可以采用以下优化策略：

// 图片懒加载 function lazyLoadEventImages() { const images = document.querySelectorAll('.event-image[data-src]'); const imageObserver = new IntersectionObserver((entries, observer) => { entries.forEach(entry => { if (entry.isIntersecting) { const img = entry.target; img.src = img.dataset.src; img.classList.remove('lazy'); imageObserver.unobserve(img); } }); }); images.forEach(img => imageObserver.observe(img)); } // 在赛事列表加载完成后调用 document.addEventListener('DOMContentLoaded', function() { lazyLoadEventImages(); });