aiotagro/jiebanke

Fork 0

Files

mapleaf 7f9bfbb381 Generating commit message...

2025-08-30 14:33:49 +08:00

4.7 KiB

Raw Blame History

结伴客系统 API 使用指南

📖 概述

本文档提供了结伴客系统完整的API接口说明，包括认证、用户管理、旅行服务、动物认领、商家服务、推广奖励等核心功能接口。

🚀 快速开始

环境要求

Node.js 16+
MySQL 8.0+
Redis (可选)
RabbitMQ (可选)

安装依赖

cd scripts
npm install

运行测试

# 运行完整API测试
npm test

# 仅测试健康检查
npm run test:health

🔐 认证方式

所有需要认证的接口都需要在请求头中包含Bearer Token：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

获取Token的流程：

用户注册或登录
从响应中获取token
在后续请求的Header中包含token

📋 核心接口

用户认证

POST /auth/register - 用户注册
POST /auth/login - 用户登录
POST /auth/wechat-login - 微信登录
GET /auth/me - 获取当前用户信息

旅行服务

POST /travel/plans - 创建旅行计划
GET /travel/plans - 获取旅行计划列表
GET /travel/matches - 匹配旅行伙伴

动物认领

GET /animals - 获取可认领动物列表
POST /animals/{id}/claim - 认领动物
GET /animals/claims - 获取认领记录

商家服务

POST /merchants/register - 商家注册
POST /merchants/products - 发布商品/服务
GET /merchants/orders - 获取商家订单

推广奖励

GET /promotion/link - 获取推广链接
GET /promotion/stats - 获取推广数据
POST /promotion/withdraw - 申请提现

官网接口

POST /website/merchant/apply - 提交商家入驻申请
GET /website/cases - 获取成功案例列表

🎯 响应格式

成功响应

{
  "success": true,
  "code": 200,
  "message": "操作成功",
  "data": {
    // 具体业务数据
  },
  "timestamp": "2025-01-01T00:00:00.000Z"
}

错误响应

{
  "success": false,
  "code": 400,
  "message": "错误信息",
  "error": "详细错误描述",
  "timestamp": "2025-01-01T00:00:00.000Z"
}

⚠️ 注意事项

时间格式: 所有时间字段使用ISO 8601格式 (YYYY-MM-DDTHH:mm:ss.sssZ)
金额单位: 人民币元，保留两位小数
图片URL: 必须使用HTTPS协议
频率限制: API调用频率限制为每分钟100次
敏感操作: 需要二次验证确保安全

🔧 开发建议

1. 错误处理

try {
  const response = await api.post('/auth/login', credentials);
  // 处理成功响应
} catch (error) {
  if (error.response?.status === 401) {
    // 处理未授权错误
  } else if (error.response?.status === 429) {
    // 处理频率限制错误
  } else {
    // 处理其他错误
  }
}

2. 请求重试

对于重要的请求，建议实现重试机制：

async function requestWithRetry(url, data, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      return await api.post(url, data);
    } catch (error) {
      if (i === retries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
    }
  }
}

3. Token刷新

实现token自动刷新机制：

// 响应拦截器处理token过期
api.interceptors.response.use(
  (response) => response,
  async (error) => {
    if (error.response?.status === 401) {
      // 刷新token逻辑
      const newToken = await refreshToken();
      error.config.headers.Authorization = `Bearer ${newToken}`;
      return api.request(error.config);
    }
    return Promise.reject(error);
  }
);

📊 监控和日志

建议对API调用进行监控和日志记录：

性能监控: 记录每个接口的响应时间
错误监控: 记录API调用错误和异常
使用统计: 统计接口调用频率和用户行为
安全审计: 记录敏感操作和登录尝试

🚨 常见问题

Q1: 如何处理重复注册？

A: 注册接口会返回409状态码，提示"用户已存在"

Q2: 如何重置密码？

A: 目前需要通过客服渠道重置，后续会开发密码重置功能

Q3: 如何获取商家资质？

A: 商家需要准备营业执照等资质文件，通过官网提交申请

Q4: API调用频率限制是多少？

A: 每分钟100次请求，超过限制会返回429状态码

📞 技术支持

如有API使用问题，请联系：

邮箱: support@jiebanke.com
电话: 400-123-4567
微信: jiebanke-support

📄 版本历史

版本	日期	说明
v1.0	2025-01-01	初始版本发布
v1.1	2025-02-01	新增微信登录接口
v1.2	2025-03-01	优化错误处理机制

最后更新: 2025-01-01
文档版本: v1.0

4.7 KiB Raw Blame History Unescape Escape