Multi-Agent Orchestrator项目中JSON解析错误的深度分析与解决方案

2025-06-11 17:00:16作者：胡唯隽

在基于Multi-Agent Orchestrator框架开发聊天机器人应用时，开发团队可能会遇到一个典型的API响应解析问题：系统预期接收JSON格式数据，却意外收到了HTML文档。这种情况通常表现为控制台抛出"Unexpected token '<'"的错误提示，表明解析器在预期JSON数据的位置遇到了HTML文档的起始标签。

问题本质分析

这种错误的核心在于HTTP响应内容类型(Content-Type)与预期不符。当API端点发生内部错误时，服务器可能返回一个HTML格式的错误页面而非预期的JSON数据。常见触发场景包括：

服务器端路由配置错误，请求被错误地重定向到HTML页面
认证失败导致跳转到登录页面
服务器内部错误(500)时返回的错误页面
反向代理配置不当导致的意外响应

技术实现细节

在JavaScript生态中，这个问题通常出现在使用fetch或axios等HTTP客户端时。开发者直接调用response.json()方法，而该方法会无条件尝试将响应体解析为JSON，不考虑实际内容类型。

// 典型的有风险实现
fetch('/api/endpoint')
  .then(response => response.json()) // 此处可能抛出解析错误
  .then(data => console.log(data))
  .catch(err => console.error('解析失败:', err))

专业级解决方案

方案一：内容类型验证

在尝试解析响应体之前，应先验证Content-Type头：

fetch('/api/endpoint')
  .then(response => {
    const contentType = response.headers.get('content-type')
    if (!contentType || !contentType.includes('application/json')) {
      throw new TypeError("非JSON响应")
    }
    return response.json()
  })
  .then(data => processData(data))
  .catch(error => handleError(error))

方案二：响应状态检查

结合HTTP状态码进行更全面的验证：

fetch('/api/endpoint')
  .then(response => {
    if (!response.ok) { // 检查2xx状态码
      throw new Error(`HTTP错误! 状态: ${response.status}`)
    }
    return response.json()
  })
  .catch(error => {
    console.error('请求失败:', error)
    // 可在此处添加重试逻辑或用户通知
  })

方案三：防御性解析

实现一个安全的JSON解析包装器：

async function safeJsonParse(response) {
  const text = await response.text()
  try {
    return JSON.parse(text)
  } catch (e) {
    console.error('解析原始响应失败:', text.substring(0, 100))
    throw e
  }
}

// 使用示例
fetch('/api/endpoint')
  .then(safeJsonParse)
  .then(data => console.log('解析成功:', data))