服务管理系统 API 文档

服务列表、服务详情和推荐服务接口文档

服务列表

服务详情

推荐服务

📋 服务列表接口

接口基本信息

GET /service/list

功能描述：获取服务列表，支持分页、分类筛选、搜索等功能。服务类型包括：住宿服务(2)、餐饮服务(3)、景点服务(4)、商品服务(5)。

请求参数

参数名	类型	必填	默认值	说明
page	Integer	否	1	页码，从1开始计数
pageSize	Integer	否	20	每页显示数量
service_type	Integer	否	空	服务类型筛选：2-住宿，3-餐饮，4-景点，5-商品
keyword	String	否	空	搜索关键词，在标题、描述和地址中搜索
city	String	否	空	城市筛选
is_recommend	Integer	否	空	推荐状态筛选：1-推荐，0-不推荐
status	Integer	否	1	状态筛选：1-上架，0-下架

响应数据

成功响应

错误响应

HTTP状态码：200

{ "statusCode": 200, "message": "获取成功", "data": { "list": [ { "id": 101, "service_type": 2, "service_type_name": "住宿服务", "title": "豪华大床房", "cover_image": "https://example.com/images/hotel1.jpg", "price": 299.00, "formatted_price": "¥299.00", "province": "上海", "city": "上海", "district": "黄浦区", "address": "南京东路123号", "full_address": "上海上海黄浦区南京东路123号", "short_description": "地理位置优越，靠近市中心", "status": 1, "is_recommend": 1, "recommend_weight": 10, "create_at": "2025-12-01 10:30:00", "updated_at": "2025-12-05 15:20:00", "shop_id": 201, "business_id": 301, "shop_info": { "id": 201, "name": "上海大酒店", "contact_phone": "021-12345678", "description": "五星级豪华酒店", "logo": "https://example.com/logos/hotel.jpg", "business_hours": "全天24小时", "detailed_address": "上海黄浦区南京东路123号", "latitude": 31.2304, "longitude": 121.4737, "status": 1, "audit_status": 1 }, "extension_info": { "room_type_name": "豪华大床房", "bed_type": "double", "room_area": 45.00, "max_occupancy": 2, "breakfast_included": 1, "market_price": 399.00, "sales_price": 299.00, "stock_available": 10, "room_facilities": ["空调", "电视", "迷你吧", "浴缸"] } } ], "pagination": { "totalCount": 45, "pageSize": 20, "currentPage": 1, "pageCount": 3 } } }

响应字段说明

字段	类型	说明
statusCode	Integer	状态码，200表示成功
message	String	操作结果消息
data	Object	数据对象
data.list	Array[Object]	服务对象列表
data.list[].id	Integer	服务的唯一标识
data.list[].service_type	Integer	服务类型：2-住宿，3-餐饮，4-景点，5-商品
data.list[].service_type_name	String	服务类型名称
data.list[].title	String	服务标题
data.list[].cover_image	String	封面图URL
data.list[].price	Decimal	参考价格
data.list[].formatted_price	String	格式化后的价格显示
data.list[].short_description	String	简短描述
data.list[].status	Integer	状态：1-上架，0-下架
data.list[].shop_info	Object	关联的店铺信息
data.list[].extension_info	Object	服务扩展信息（根据服务类型不同而不同）
data.pagination	Object	分页信息对象
data.pagination.totalCount	Integer	总记录数
data.pagination.pageSize	Integer	每页数量
data.pagination.currentPage	Integer	当前页码
data.pagination.pageCount	Integer	总页数

HTTP状态码	错误消息	可能原因
400	参数错误	参数格式不正确
500	获取服务列表失败	服务器内部错误

使用示例

获取所有服务（第一页）

// 获取服务列表 fetch('/service/list?page=1&pageSize=20') .then(response => response.json()) .then(data => { if (data.statusCode === 200) { console.log('服务数据:', data.data.list); console.log('分页信息:', data.data.pagination); } });

获取特定类型的服务

// 获取餐饮服务（第三页） fetch('/service/list?service_type=3&page=3&pageSize=10') .then(response => response.json()) .then(data => { // 处理返回的餐饮服务数据 });

搜索服务

// 搜索包含"豪华"关键词的服务 fetch('/service/list?keyword=豪华&page=1&pageSize=20') .then(response => response.json()) .then(data => { // 处理搜索结果 });

📰 服务详情接口

接口基本信息

GET /service/detail/{id}

功能描述：获取指定服务的详细信息，包括完整的服务详情、店铺信息和扩展信息。

请求参数

参数名	类型	必填	默认值	说明
id	Integer	是	无	服务的唯一标识ID（路径参数）

响应数据

成功响应

错误响应

HTTP状态码：200

{ "statusCode": 200, "message": "获取成功", "data": { "id": 101, "service_type": 2, "service_type_name": "住宿服务", "title": "豪华大床房", "cover_image": "https://example.com/images/hotel1.jpg", "price": 299.00, "formatted_price": "¥299.00", "province": "上海", "city": "上海", "district": "黄浦区", "address": "南京东路123号", "full_address": "上海上海黄浦区南京东路123号", "short_description": "地理位置优越，靠近市中心", "status": 1, "is_recommend": 1, "recommend_weight": 10, "create_at": "2025-12-01 10:30:00", "updated_at": "2025-12-05 15:20:00", "shop_id": 201, "business_id": 301, "shop_info": { "id": 201, "name": "上海大酒店", "contact_phone": "021-12345678", "description": "五星级豪华酒店", "logo": "https://example.com/logos/hotel.jpg", "business_hours": "全天24小时", "detailed_address": "上海黄浦区南京东路123号", "latitude": 31.2304, "longitude": 121.4737, "status": 1, "audit_status": 1, "status_text": "营业中", "audit_status_text": "审核通过" }, "shop_ext_info": { "star_rating": 5, "checkin_time": "14:00:00", "checkout_time": "12:00:00", "front_desk_24h": 1, "hotel_intro": "五星级豪华酒店，设施齐全，服务周到" }, "service_detail": { "room_type_name": "豪华大床房", "room_type_code": "DLX001", "bed_type": "double", "bed_size": "1.8m大床", "room_area": 45.00, "floor_range": "5-10层", "max_occupancy": 2, "breakfast_included": 1, "breakfast_count": 2, "market_price": 399.00, "sales_price": 299.00, "stock_available": 10, "room_facilities": ["空调", "电视", "迷你吧", "浴缸"], "room_images": ["https://example.com/room1.jpg", "https://example.com/room2.jpg"], "room_desc": "宽敞明亮的豪华大床房，配备现代化设施" } } }

响应字段说明

字段	类型	说明
statusCode	Integer	状态码，200表示成功
message	String	操作结果消息
data	Object	服务详情对象
data.id	Integer	服务的唯一标识
data.service_type	Integer	服务类型
data.title	String	服务标题
data.shop_info	Object	完整的店铺信息
data.shop_ext_info	Object	店铺扩展信息（根据服务类型不同）
data.service_detail	Object	服务详细信息（根据服务类型不同）

不同服务类型的扩展信息

服务类型	service_detail 包含的字段	shop_ext_info 包含的字段
住宿服务(2)	房型信息、设施、价格等	酒店星级、入住时间、设施介绍等
餐饮服务(3)	菜品信息、价格、特色等	菜系、人均消费、环境介绍等
景点服务(4)	票务信息、游玩时长、包含服务等	景点类型、级别、开放时间等
商品服务(5)	商品信息、规格、库存等	店铺品类、价格区间、服务特色等

HTTP状态码	错误消息	可能原因
400	无效的服务类型	服务类型不符合要求（service_type ≤ 1）
403	服务已下架	服务状态为0（已下架）
404	服务不存在	指定的服务ID不存在
404	服务已被删除	服务已被软删除（is_del = 1）
500	获取服务详情失败	服务器内部错误

使用示例

JavaScript Fetch 示例

// 获取服务详情 fetch('/service/detail/101') .then(response => response.json()) .then(data => { if (data.statusCode === 200) { console.log('服务详情:', data.data); // 处理服务详情数据 } }) .catch(error => { console.error('获取服务详情失败:', error); });

错误处理示例

async function getServiceDetail(id) { try { const response = await fetch(`/service/detail/${id}`); 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); // 根据不同的错误码进行相应处理 switch(result.statusCode) { case 403: // 处理服务已下架的情况 break; case 404: // 处理服务不存在的情况 break; default: // 处理其他错误 } return null; } } catch (error) { console.error('获取服务详情失败:', error); return null; } }

⭐ 推荐服务接口

接口基本信息

GET /service/recommended

功能描述：获取推荐服务列表，按推荐权重排序。

请求参数

参数名	类型	必填	默认值	说明
limit	Integer	否	10	返回数量限制
service_type	Integer	否	空	服务类型筛选

响应数据

成功响应

错误响应

HTTP状态码：200

{ "statusCode": 200, "message": "获取成功", "data": [ { "id": 101, "service_type": 2, "service_type_name": "住宿服务", "title": "豪华大床房", "cover_image": "https://example.com/images/hotel1.jpg", "price": 299.00, "formatted_price": "¥299.00", "short_description": "地理位置优越，靠近市中心", "is_recommend": 1, "recommend_weight": 100, "shop_info": { "name": "上海大酒店", "contact_phone": "021-12345678" }, "extension_info": { "room_type_name": "豪华大床房", "market_price": 399.00, "sales_price": 299.00 } }, { "id": 205, "service_type": 3, "service_type_name": "餐饮服务", "title": "招牌北京烤鸭", "cover_image": "https://example.com/images/duck.jpg", "price": 198.00, "formatted_price": "¥198.00", "short_description": "传统工艺，皮脆肉嫩", "is_recommend": 1, "recommend_weight": 95, "shop_info": { "name": "北京烤鸭店", "contact_phone": "021-87654321" }, "extension_info": { "dish_name": "招牌北京烤鸭", "market_price": 228.00, "sales_price": 198.00, "is_signature": 1 } } ] }

响应字段说明

响应字段与服务列表接口类似，但只包含推荐服务且按推荐权重排序。

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

使用示例

获取推荐服务

// 获取推荐服务（默认10条） fetch('/service/recommended') .then(response => response.json()) .then(data => { if (data.statusCode === 200) { console.log('推荐服务:', data.data); } });

获取特定类型的推荐服务

// 获取餐饮类推荐服务（最多5条） fetch('/service/recommended?service_type=3&limit=5') .then(response => response.json()) .then(data => { // 处理餐饮类推荐服务 });

💡 最佳实践

1. 错误处理

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

// 统一的API调用函数 async function callApi(url, options = {}) { try { const response = await fetch(url, { headers: { 'Content-Type': 'application/json', ...options.headers }, ...options }); if (!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } const result = await response.json(); if (result.statusCode === 200) { return result.data; } else { // 处理业务逻辑错误 handleApiError(result.statusCode, result.message); return null; } } catch (error) { console.error('API调用失败:', error); // 处理网络错误 handleNetworkError(error); return null; } } // 错误处理函数 function handleApiError(statusCode, message) { switch(statusCode) { case 400: console.error('参数错误:', message); break; case 403: console.error('访问被拒绝:', message); break; case 404: console.error('资源不存在:', message); break; case 500: console.error('服务器错误:', message); break; default: console.error('未知错误:', message); } }

2. 缓存策略

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

推荐服务：缓存时间较短（5-10分钟）
普通服务列表：缓存时间适中（15-30分钟）
服务详情：缓存时间较长（1-2小时）

3. 性能优化

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

// 图片懒加载 function lazyLoadImages() { const images = document.querySelectorAll('img[data-src]'); const imageObserver = new IntersectionObserver((entries, observer) => { entries.forEach(entry => { if (entry.isIntersecting) { const img = entry.target; img.src = img.dataset.src; img.removeAttribute('data-src'); imageObserver.unobserve(img); } }); }); images.forEach(img => imageObserver.observe(img)); } // 无限滚动加载 let currentPage = 1; let isLoading = false; function setupInfiniteScroll() { window.addEventListener('scroll', () => { if (window.innerHeight + window.scrollY >= document.body.offsetHeight - 500 && !isLoading) { loadMoreServices(); } }); } async function loadMoreServices() { isLoading = true; currentPage++; try { const data = await callApi(`/service/list?page=${currentPage}&pageSize=20`); if (data && data.list.length > 0) { // 添加新数据到页面 appendServices(data.list); // 重新初始化懒加载 lazyLoadImages(); } } finally { isLoading = false; } }