📚 接口文档

📖 通用说明

接口地址

所有接口的基础URL为：https://api.example.com

请求方式

支持 GET 和 POST 两种请求方式，具体以各接口说明为准。

返回格式

所有接口统一返回JSON格式数据，基本结构如下：

{
  "code": 200,           // 状态码，200表示成功
  "message": "success",  // 返回信息
  "data": {}            // 具体数据内容
}

状态码说明

状态码	说明
200	请求成功
400	请求参数错误
429	请求过于频繁，触发限流
500	服务器内部错误

☁️ 天气查询接口

请求参数

参数名	类型	必填	说明
city	string	必填	城市名称，支持中文，如：北京、上海、深圳

返回参数

参数名	类型	说明
city	string	城市名称
temperature	string	当前温度
weather	string	天气状况（晴、多云、雨等）
humidity	string	湿度
wind	string	风力风向
updateTime	string	数据更新时间

请求示例

// JavaScript (Fetch API)
fetch('https://api.example.com/api/weather?city=北京')
  .then(response => response.json())
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error('请求失败:', error);
  });

返回示例

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "city": "北京",
    "temperature": "22°C",
    "weather": "晴",
    "humidity": "65%",
    "wind": "东南风 3级",
    "updateTime": "2026-01-22 14:30:00"
  }
}

💱 汇率换算接口

请求参数

参数名	类型	必填	说明
amount	number	必填	金额，必须大于0
from	string	必填	源货币代码：CNY（人民币）、USD（美元）、EUR（欧元）
to	string	必填	目标货币代码：CNY、USD、EUR

返回参数

参数名	类型	说明
amount	number	原始金额
fromCurrency	string	源货币代码
toCurrency	string	目标货币代码
rate	number	汇率
result	number	换算结果
updateTime	string	汇率更新时间

请求示例

// JavaScript (Axios)
axios.get('https://api.example.com/api/exchange', {
  params: {
    amount: 100,
    from: 'CNY',
    to: 'USD'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error('请求失败:', error);
});

返回示例

{
  "code": 200,
  "message": "换算成功",
  "data": {
    "amount": 100,
    "fromCurrency": "CNY",
    "toCurrency": "USD",
    "rate": 0.14,
    "result": 14.00,
    "updateTime": "2026-01-22 14:30:00"
  }
}

📱 二维码生成接口

请求参数

参数名	类型	必填	说明
text	string	必填	要生成二维码的文本内容，支持网址、文字等，最大长度1000字符
size	number	可选	二维码尺寸（像素），默认300，范围：100-1000

返回参数

参数名	类型	说明
text	string	原始文本内容
format	string	图片格式
size	string	图片尺寸
base64	string	Base64编码的图片数据

请求示例

// JavaScript (Fetch API)
fetch('https://api.example.com/api/qrcode', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    text: 'https://example.com',
    size: 300
  })
})
.then(response => response.json())
.then(data => {
  // 在页面中显示二维码
  const img = document.createElement('img');
  img.src = data.data.base64;
  document.body.appendChild(img);
})
.catch(error => {
  console.error('请求失败:', error);
});

返回示例

{
  "code": 200,
  "message": "生成成功",
  "data": {
    "text": "https://example.com",
    "format": "image/png",
    "size": "300x300",
    "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  }
}

⚠️ 错误处理

常见错误示例

参数缺失：

{
  "code": 400,
  "message": "参数错误：缺少必填参数 city",
  "data": null
}

触发限流：

{
  "code": 429,
  "message": "请求过于频繁，请稍后再试",
  "data": {
    "retryAfter": 3600  // 建议等待时间（秒）
  }
}

服务器错误：

{
  "code": 500,
  "message": "服务器内部错误，请稍后重试",
  "data": null
}

错误处理建议

• 请求前务必验证参数的完整性和有效性
• 建议实现请求重试机制，遇到5xx错误可以重试
• 遇到429限流错误时，应根据retryAfter字段等待相应时间
• 在生产环境中应添加完善的错误日志记录