node-elm 项目 API 接口详解指南

项目概述

node-elm 是一个基于 Node.js 的外卖平台后端项目，提供完整的 API 接口服务。本文将全面解析该项目的 API 接口设计和使用方法，帮助开发者快速理解和使用这套接口系统。

基础信息

• 基础 URL: https://elm.cangdu.org
• 接口版本: 主要使用 v1 和 v2 版本
• 数据格式: 全部接口返回 JSON 格式数据

核心功能接口详解

1. 城市相关接口

获取城市列表

接口路径: /v1/cities 请求方式: GET 参数说明:

• type (必填):
  • guess: 定位城市
  • hot: 热门城市
  • group: 所有城市

返回示例:

{
  "id": 1,
  "name": "上海",
  "abbr": "SH",
  "area_code": "021",
  "latitude": 31.23037,
  "longitude": 121.473701
}

获取城市详情

接口路径: /v1/cities/:id 请求方式: GET 参数说明:

• id (路径参数): 城市ID

2. 位置服务接口

搜索地址

接口路径: /v1/pois 请求方式: GET 参数说明:

• city_id (必填): 城市ID
• keyword (必填): 搜索关键词
• type: 搜索类型，默认为search

返回特点:

• 返回最多10条匹配结果
• 包含经纬度坐标和地理哈希值

经纬度定位

接口路径: /v2/pois/:geohash 请求方式: GET 参数说明:

• geohash (路径参数): 经纬度字符串，格式为"纬度,经度"

3. 商家相关接口

获取商铺列表

接口路径: /shopping/restaurants 请求方式: GET 重要参数:

• latitude & longitude: 用户当前位置坐标
• order_by: 排序方式(1:起送价,2:配送速度,3:评分等)
• delivery_mode: 配送方式筛选
• support_ids: 支持的特权筛选

返回数据结构:

• 包含商家基本信息、评分、配送信息、活动等
• 默认返回20条数据，可通过offset和limit分页

商家详情

接口路径: /shopping/restaurant/:shopid 请求方式: GET 返回内容:

• 完整商家信息
• 支持的服务和活动
• 营业执照等认证信息

4. 食品管理接口

获取食品分类

接口路径: /shopping/v2/restaurant/category 请求方式: GET 特点:

• 支持多级分类结构
• 包含分类图片和统计信息

添加食品

接口路径: /shopping/addfood 请求方式: POST 必填参数:

• restaurant_id: 商家ID
• category_id: 分类ID
• name: 食品名称
• specs: 规格数组

5. 订单系统接口

下单接口

接口路径: /bos/v2/users/:user_id/orders 请求方式: POST 需要参数:

• 用户ID
• 商家ID
• 配送地址
• 购物车信息
• 支付方式

订单查询

接口路径: /bos/v2/users/:user_id/orders 请求方式: GET 查询方式:

• 可分页查询
• 可按状态筛选

6. 用户系统接口

用户登录

接口路径: /v2/login 请求方式: POST 参数:

• username: 用户名
• password: 密码
• captcha_code: 验证码

获取用户信息

接口路径: /v1/user 请求方式: GET 返回内容:

• 基本信息
• 收货地址
• 订单统计等

接口使用最佳实践

1. 位置服务:

   • 先获取城市列表
   • 再获取具体城市信息
   • 最后进行位置搜索

2. 商家查询:

   • 先获取分类信息
   • 再根据分类筛选商家
   • 最后查看商家详情

3. 错误处理:

   • 所有接口错误都会返回标准错误格式
   • 包含错误码和错误信息

4. 权限控制:

   • 管理接口需要管理员权限
   • 用户相关接口需要登录凭证

性能优化建议

1. 合理使用分页参数，避免一次性获取大量数据
2. 对静态数据(如城市信息)适当做客户端缓存
3. 高频接口考虑使用CDN加速

总结

node-elm 的API设计遵循RESTful风格，接口分类清晰，文档完善。开发者可以根据业务需求选择合适的接口组合，快速构建外卖平台应用。所有接口都经过充分测试，具有良好的稳定性和性能表现。