API 文档

获取API访问权限

所有API端点均可公开访问，无需特殊权限。对于需要用户身份验证的端点（如提交分数），用户需要登录。

准备开发环境

确保您的开发环境支持HTTP请求发送和JSON数据处理。推荐使用以下工具：

• Postman - API测试工具
• cURL - 命令行工具
• JavaScript Fetch API - 前端开发
• Python requests - Python后端开发

基础请求格式

所有API请求都需要遵循以下基本格式：

修改请求参数

在每个API端点下方的测试面板中，您可以修改请求参数以满足测试需求。参数格式为JSON。

发送请求

点击"发送请求"按钮，系统将向对应的API端点发送请求。

查看响应

API响应将显示在请求按钮下方的响应区域中。响应内容会自动格式化以便阅读。

错误处理

始终检查API响应的成功状态，即使在测试时看起来一切正常：

// JavaScript示例
fetch('/api/gamedata.php', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(requestData)
})
.then(response => response.json())
.then(data => {
  if (data.success) {
    // 处理成功响应
    console.log('成功:', data);
  } else {
    // 处理错误响应
    console.error('错误:', data.message);
  }
})
.catch(error => {
  // 处理网络错误
  console.error('网络错误:', error);
});

数据验证

在提交数据前验证数据格式和范围：

// JavaScript示例
function validateScoreData(data) {
  if (!data.game_id || !Number.isInteger(data.game_id)) {
    throw new Error('游戏ID必须是整数');
  }
  
  if (!data.score || !Number.isInteger(data.score)) {
    throw new Error('分数必须是整数');
  }
  
  if (data.play_time && !Number.isInteger(data.play_time)) {
    throw new Error('游戏时长必须是整数');
  }
  
  return true;
}

性能优化

合理使用limit参数，避免获取过多数据：

// 获取排行榜时限制返回记录数
const leaderboardRequest = {
  action: 'get_leaderboard',
  game_id: 1,
  limit: 10  // 限制为10条记录
};

安全性

所有涉及用户数据的操作应验证用户身份：

// 提交分数前验证登录状态
function submitScoreIfLoggedIn(gameId, score, playTime) {
  fetch('/api/gamedata.php', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ action: 'verify_login' })
  })
  .then(response => response.json())
  .then(data => {
    if (data.logged_in) {
      // 用户已登录，可以提交分数
      submitScore(gameId, score, playTime);
    } else {
      // 用户未登录，提示登录
      alert('请先登录再提交分数');
    }
  });
}