常见问题 FAQ

第十三章：常见问题解答（FAQ）

排障分层示意

13.1 401/403：鉴权失败

现象

返回 401/403
日志里出现 Key 为空或权限不足

排查顺序

环境变量是否真的生效：

echo $AI_DASHSCOPE_API_KEY

application.yml 是否引用了正确变量名：

spring:
  ai:
    dashscope:
      api-key: ${AI_DASHSCOPE_API_KEY:}

网关/容器是否注入了环境变量（K8s ConfigMap/Secret）

13.2 429：限流或配额不足

现象

少量请求没问题，高并发时大量 429
重试越多越糟，甚至拖垮应用

处理策略

先限并发：入口闸门（第 11 章）
再退避重试：指数退避 + 最大重试次数（第 10 章）
做缓存：重复问题直接命中缓存

13.3 5xx：供应商波动或网络问题

建议

开启超时与退避重试
打点 P95 延迟与失败率，配合告警
做降级：必要时回退到“非流式接口/简化回答”

13.4 SSE 流式断开

常见原因

代理/网关空闲超时（无数据时主动断）
连接过多导致资源耗尽

建议

心跳：每 10 秒发 ping（第 4 章）
限制单用户 SSE 连接数
浏览器端提供“重连”与“停止”按钮

13.5 结构化输出解析失败（JSON 解析错误）

常见原因

模型输出夹杂了自然语言或 Markdown 代码块
字段缺失、引号不闭合

建议

system 里要求只输出 JSON
先抽取 {...} 边界再解析
解析失败后用“修复提示”重试一次（第 6 章）

13.6 建议加一个统一错误返回

为了让前端/调用方更容易处理错误，建议用 @ControllerAdvice 统一包装：

package com.example.saa.api;

import java.util.Map;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(IllegalArgumentException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public Map<String, Object> handleBadRequest(IllegalArgumentException ex) {
        return Map.of("success", false, "error", ex.getMessage());
    }

    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public Map<String, Object> handleServerError(Exception ex) {
        return Map.of("success", false, "error", "服务异常，请稍后重试");
    }
}

13.7 本章小结

这份 FAQ 的核心是“按层排障”：

401/403 先看 Key 与权限
429 先限并发，再做退避重试与缓存
5xx 做超时、重试、告警与降级
SSE 断流看心跳与网关策略
JSON 解析失败用强约束 + 修复重试兜底

下一章整理一份资源清单，帮助你快速查到 Spring AI、Spring AI Alibaba 与 DashScope 相关文档与最佳实践。