Generating commit message...
This commit is contained in:
203
docs/API-README.md
Normal file
203
docs/API-README.md
Normal file
@@ -0,0 +1,203 @@
|
||||
# 结伴客系统 API 使用指南
|
||||
|
||||
## 📖 概述
|
||||
|
||||
本文档提供了结伴客系统完整的API接口说明，包括认证、用户管理、旅行服务、动物认领、商家服务、推广奖励等核心功能接口。
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 环境要求
|
||||
- Node.js 16+
|
||||
- MySQL 8.0+
|
||||
- Redis (可选)
|
||||
- RabbitMQ (可选)
|
||||
|
||||
### 安装依赖
|
||||
```bash
|
||||
cd scripts
|
||||
npm install
|
||||
```
|
||||
|
||||
### 运行测试
|
||||
```bash
|
||||
# 运行完整API测试
|
||||
npm test
|
||||
|
||||
# 仅测试健康检查
|
||||
npm run test:health
|
||||
```
|
||||
|
||||
## 🔐 认证方式
|
||||
|
||||
所有需要认证的接口都需要在请求头中包含Bearer Token：
|
||||
|
||||
```http
|
||||
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
```
|
||||
|
||||
### 获取Token的流程：
|
||||
1. 用户注册或登录
|
||||
2. 从响应中获取token
|
||||
3. 在后续请求的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` - 获取成功案例列表
|
||||
|
||||
## 🎯 响应格式
|
||||
|
||||
### 成功响应
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"code": 200,
|
||||
"message": "操作成功",
|
||||
"data": {
|
||||
// 具体业务数据
|
||||
},
|
||||
"timestamp": "2025-01-01T00:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
### 错误响应
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"code": 400,
|
||||
"message": "错误信息",
|
||||
"error": "详细错误描述",
|
||||
"timestamp": "2025-01-01T00:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
## ⚠️ 注意事项
|
||||
|
||||
1. **时间格式**: 所有时间字段使用ISO 8601格式 (YYYY-MM-DDTHH:mm:ss.sssZ)
|
||||
2. **金额单位**: 人民币元，保留两位小数
|
||||
3. **图片URL**: 必须使用HTTPS协议
|
||||
4. **频率限制**: API调用频率限制为每分钟100次
|
||||
5. **敏感操作**: 需要二次验证确保安全
|
||||
|
||||
## 🔧 开发建议
|
||||
|
||||
### 1. 错误处理
|
||||
```javascript
|
||||
try {
|
||||
const response = await api.post('/auth/login', credentials);
|
||||
// 处理成功响应
|
||||
} catch (error) {
|
||||
if (error.response?.status === 401) {
|
||||
// 处理未授权错误
|
||||
} else if (error.response?.status === 429) {
|
||||
// 处理频率限制错误
|
||||
} else {
|
||||
// 处理其他错误
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 请求重试
|
||||
对于重要的请求，建议实现重试机制：
|
||||
|
||||
```javascript
|
||||
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自动刷新机制：
|
||||
|
||||
```javascript
|
||||
// 响应拦截器处理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调用进行监控和日志记录：
|
||||
|
||||
1. **性能监控**: 记录每个接口的响应时间
|
||||
2. **错误监控**: 记录API调用错误和异常
|
||||
3. **使用统计**: 统计接口调用频率和用户行为
|
||||
4. **安全审计**: 记录敏感操作和登录尝试
|
||||
|
||||
## 🚨 常见问题
|
||||
|
||||
### 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
|
||||
Reference in New Issue
Block a user