为什么要用 Spring AI

直接用 HTTP 打 OpenAI 兼容接口也能让模型回话，但各家厂商的兼容响应并不完全一致（比如通义千问会返回规范外的 reasoning_content 字段）。Spring AI 这类抽象层解决的就是这个问题：统一 API、自动装配、生态集成。

环境搭建

• JDK 21（LTS）+ Spring Boot 4.1.1 + Maven
• 注意 Boot 4 里 web starter 改名为 spring-boot-starter-webmvc（老教程的 -web 是 Boot 3 时代写法）
• 用 Maven Wrapper（mvnw）锁定版本，团队每人一致

BOM 依赖管理

两块配置，位置和写法都对：

1. dependencyManagement 导入 spring-ai-bom:2.0.1（type=pom + scope=import）
2. dependencies 引入 spring-ai-starter-model-openai，不写 version

不写 version 却不报错，就是 BOM 生效的证据。

接入阿里云百炼

OpenAI 兼容协议的三段式：厂商网关 / base-url（配置文件填到这里为止）/ 资源路径（框架自动拼）。

百炼的专属网关：https://token-plan.maas.qianwenaiapi.com/compatible-mode/v1

API Key 必须走环境变量，不硬编码进代码或配置。

ChatClient fluent API

核心链路：.prompt() → .user() → .call() → .content()，每一环职责清晰。

踩坑记录

• key 是有作用域的：百炼 key 打 dashscope 老端点必报 invalid_api_key
• 排错方法论：假 key 对照法——假 key 返回 InvalidApiKey 而真 key 报别的错，反证鉴权已通过
• 响应里除了 content 还有 reasoning_content（厂商自定义字段），这是需要抽象层的原因