错误处理

响应状态码说明

API 响应中的 status 字段表示请求处理状态：

状态码	说明	解决方案
200	请求成功	正常处理返回的数据
401	需要重新授权	调用 /app/token 接口获取新 Token
404	接口不存在	检查请求 URL 是否正确
500	服务器错误	查看 desc 字段的详细错误信息，联系技术支持

状态码说明

• status = 200：请求成功，可以正常处理返回的数据
• status = 401：需要重新授权，调用 /app/token 接口获取新 Token
• status = 404：接口不存在，请检查请求 URL 是否正确
• status = 500：服务器错误，查看 desc 字段的详细错误信息

错误响应格式

所有错误响应都采用统一的格式：

{
  "status": 500,
  "desc": "错误描述",
  "time": 1640995200,
  "data": null
}

常见错误场景

1. 认证失败

错误响应：

{
  "status": 401,
  "desc": "认证失败，Token无效或已过期",
  "time": 1640995200,
  "data": null
}

原因及解决方案：

• Token 无效或过期：重新调用 /app/token 接口获取新 Token
• Token 未在请求头中正确传递：确保请求头中包含 token 字段

2. 设备不存在

错误响应：

{
  "status": 404,
  "desc": "设备不存在",
  "time": 1640995200,
  "data": null
}

原因及解决方案：

• 设备 SN 错误：检查设备序列号是否正确
• 设备未绑定到当前应用：确认设备是否已正确绑定

3. 设备正在控制中

错误响应：

{
  "status": 500,
  "desc": "设备正在控制中！",
  "time": 1640995200,
  "data": null
}

原因及解决方案：

• 设备正在被其他用户占用：等待当前会话结束，或选择其他空闲设备
• 建议先调用 /device/openList 接口查询设备的 useStatus 状态

4. 参数错误

错误响应：

{
  "status": 500,
  "desc": "参数错误",
  "time": 1640995200,
  "data": null
}

原因及解决方案：

• 必填参数缺失：检查所有必填参数是否都已提供
• 参数格式错误：检查参数类型和格式是否正确

错误处理最佳实践

1. Token 管理

let token = null;
let tokenExpiry = 0;

async function getToken() {
  const now = Date.now();
  
  // Token 快过期时提前刷新（提前 5 分钟）
  if (!token || now > tokenExpiry - 5 * 60 * 1000) {
    const response = await fetch('http://182.254.182.254:9090/app/token', {
      method: 'GET',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        appId: 'your_app_id',
        appSecret: 'your_app_secret'
      })
    });
    
    const data = await response.json();
    if (data.status === 200) {
      token = data.data.token;
      tokenExpiry = now + 3 * 60 * 60 * 1000; // 3小时
    } else {
      throw new Error(data.desc || '获取Token失败');
    }
  }
  
  return token;
}

2. 设备状态检查

async function findAvailableDevice() {
  const token = await getToken();
  
  const response = await fetch(
    'http://182.254.182.254:9090/device/openList?status=在线&pageSize=100',
    {
      method: 'GET',
      headers: { 'token': token }
    }
  );
  
  const data = await response.json();
  if (data.status === 200) {
    // 查找空闲设备
    const availableDevice = data.data.items.find(
      device => device.useStatus === '空闲'
    );
    return availableDevice;
  } else {
    throw new Error(data.desc || '查询设备列表失败');
  }
}

3. 状态码处理

根据响应中的 status 字段进行不同的处理：

async function handleApiResponse(response) {
  const data = await response.json();
  
  switch (data.status) {
    case 200:
      // 请求成功
      return { success: true, data: data.data };
      
    case 401:
      // 需要重新授权
      console.warn('认证失败，重新获取 Token');
      await reauthorize();
      return { success: false, error: '认证失败，请重新授权' };
      
    case 404:
      // 接口不存在
      console.error('接口不存在，请检查 URL');
      return { success: false, error: '接口不存在' };
      
    case 500:
      // 服务器错误
      console.error('服务器错误:', data.desc);
      return { success: false, error: data.desc };
      
    default:
      return { success: false, error: data.desc || '未知错误' };
  }
}

4. 优雅的错误处理

async function controlDevice(deviceSn) {
  try {
    const token = await getToken();
    const response = await fetch(
      `http://omiok.cn/device/ctrlUrl?deviceSn=${deviceSn}`,
      { headers: { 'token': token } }
    );
    
    const result = await handleApiResponse(response);
    
    if (result.success) {
      return result.data.url;
    } else {
      // 根据错误类型处理
      if (result.error.includes('设备正在控制中')) {
        console.warn('设备正在被占用，请稍后重试');
      } else if (result.error.includes('认证失败')) {
        token = null;
        return controlDevice(deviceSn); // 重试
      } else {
        throw new Error(result.error);
      }
    }
  } catch (error) {
    console.error('控制设备失败:', error);
    throw error;
  }
}

故障排查

1. Token 获取失败

可能原因：

• appId 和 appSecret 不正确
• 网络连接问题
• 应用状态异常

排查步骤：

1. 检查 appId 和 appSecret 是否正确
2. 确认应用状态是否正常
3. 检查网络连接
4. 验证服务器地址是否正确

2. 控制地址获取失败

可能原因：

• 设备 SN 错误
• 设备未绑定到当前应用
• 设备不在线
• 设备正在被占用

排查步骤：

1. 确认设备已绑定到当前应用
2. 调用 /device/openList 查询设备状态
3. 检查设备是否在线（status 为"在线"）
4. 检查设备是否空闲（useStatus 为"空闲"）
5. 验证 Token 是否有效

3. 玩具车控制面板无法访问

可能原因：

• 网络连接问题
• 控制会话过期
• 玩具车离线

排查步骤：

1. 检查网络连接
2. 确认控制会话是否过期（默认30分钟）
3. 验证玩具车是否在线且支持远程控制
4. 检查玩具车电量是否充足

控制面板连接断开错误码

在控制面板使用过程中，当连接断开时会显示以下错误码。这些错误码用于标识不同的断开场景，帮助开发者了解断开原因并采取相应的处理措施。

错误码列表

错误码	说明	触发场景
E001	正常断开连接	用户主动断开或系统正常断开所有连接时显示
E002	断开连接接口调用失败	断开连接过程中，服务器接口调用失败，但已断开本地连接
E003	正常断开设备连接	用户点击返回/退出按钮，设备连接正常断开时显示
E004	设备断开连接失败	用户点击返回/退出时，服务器断开接口调用失败，但已断开本地连接
E005	使用时间到期，会话正常结束	倒计时归零，系统正常结束会话时显示
E006	使用时间到期，结束会话失败	倒计时归零时，服务器结束会话接口调用失败，但已断开本地连接
E007	收到服务器主动结束会话通知	服务器主动发送结束会话通知（如设备端操作、管理员操作等）时显示

错误码分类

根据错误码的性质，可以将其分为三类：

1. 正常流程结束（E001、E003、E005）

这些错误码表示连接正常断开，属于预期的业务场景：

• E001：用户主动断开或系统正常断开所有连接
• E003：用户点击返回/退出按钮，设备连接正常断开
• E005：倒计时归零，系统正常结束会话

处理建议：

• 这些是正常的断开场景，无需特殊处理
• 可以记录日志用于统计分析
• 可以提示用户"连接已正常断开"

2. 服务器接口调用失败（E002、E004、E006）

这些错误码表示本地连接已断开，但服务器接口调用失败：

• E002：断开连接过程中，服务器接口调用失败
• E004：用户点击返回/退出时，服务器断开接口调用失败
• E006：倒计时归零时，服务器结束会话接口调用失败

处理建议：

• 本地连接已断开，用户界面可以正常返回
• 建议记录错误日志，便于后续排查
• 可以尝试重试调用服务器接口（可选）
• 如果频繁出现，需要检查网络连接和服务器状态

3. 服务器主动结束会话（E007）

表示服务器主动发送结束会话通知：

• E007：服务器主动发送结束会话通知（如设备端操作、管理员操作等）

处理建议：

• 这是服务器端的主动操作，需要尊重服务器决定
• 提示用户"会话已被服务器结束"
• 可以询问用户是否需要重新连接
• 记录日志，分析服务器主动结束的原因

注意事项

1. 错误码显示时机：这些错误码在控制面板连接断开时显示，用于标识断开原因
2. 本地连接状态：E002、E004、E006 表示本地连接已断开，但服务器同步可能失败
3. 用户体验：对于正常断开（E001、E003、E005），可以显示友好的提示信息
4. 错误监控：建议记录所有错误码，特别是 E002、E004、E006，用于监控系统健康状态
5. 重连机制：对于 E007，可以考虑提供重新连接的选项

联系支持

如果遇到无法解决的问题，请联系技术支持：

• 检查错误日志
• 提供完整的请求和响应信息
• 说明具体的业务场景和复现步骤