从 0 到 1：Java 后端 + 阿里云百炼接入超细致操作指南
2026-04-09========================
一,先讲原理:后端到底在做什么
========================
1)后端本质
- 前端(浏览器/小程序)发 HTTP 请求.
- 后端收到请求,执行 Java 逻辑,返回字符串或 JSON.
- Spring Boot 是"快速搭后端"的框架,内置 Web 服务器.
2)为什么先做健康检查接口
- 这是最小闭环:启动 -> 访问 URL -> 返回 ok.
- 先确认"后端服务本身正常",再接 AI,排错更简单.
3)为什么要先管版本
- Java,Spring Boot,Maven 不匹配会导致编译失败或依赖冲突.
- 所以第一步不是写业务,而是固定环境版本.
========================
二,准备环境(电脑层面)
========================
1)JDK
- 建议:JDK 21.
- 验证:java -version
- 看到 21.x 才算通过.
2)Maven
- 建议:Maven 3.9.x.
- 验证:mvn -v
- 重点看输出中的 Java 版本也必须是 21.
3)Windows 环境变量(你之前踩过的坑)
- JAVA_HOME = JDK21 安装目录
- MAVEN_HOME = Maven 安装目录
- Path 追加:%JAVA_HOME%\bin;%MAVEN_HOME%\bin
- 修改后重开终端和 IDEA.
========================
三,在 IDEA 新建后端项目(从点击开始)
========================
1)打开 IDEA -> New Project.
2)选择 Spring Initializr.
3)Project SDK 选择 JDK 21.
4)Group 填:com.flyyansii
5)Artifact 填:fllyyanaiagent
6)Language 选 Java,Build 选 Maven,Packaging 选 Jar.
7)依赖先勾选:Spring Web,Lombok.
8)点击 Create.
创建后目录含义:
- src/main/java:放 Java 代码(.java)
- src/main/resources:放配置(.yml / .properties)
- pom.xml:Maven 配置(.xml)
========================
四,先改 pom.xml(后端能跑的关键)
========================
文件:项目根目录/pom.xml
1)固定 Java 版本
- <java.version>21</java.version>
- <maven.compiler.release>21</maven.compiler.release>
2)新增工具依赖
A. Hutool(HTTP 请求,JSON 处理)
<dependency>
<groupId>cn.hutool</groupId>
<artifactId>hutool-all</artifactId>
<version>5.8.38</version>
</dependency>
B. Knife4j(接口文档)
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.4.0</version>
</dependency>
3)新增 AI 依赖
A. DashScope Java SDK
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>dashscope-sdk-java</artifactId>
<version>2.22.14</version>
</dependency>
B. Spring AI Alibaba
<dependency>
<groupId>com.alibaba.cloud.ai</groupId>
<artifactId>spring-ai-alibaba-starter</artifactId>
<version>1.0.0-M6.1</version>
</dependency>
4)新增仓库(M6 里程碑版本需要)
<repositories>
<repository>
<id>spring-milestones</id>
<url>https://repo.spring.io/milestone</url>
<snapshots><enabled>false</enabled></snapshots>
</repository>
</repositories>
5)你历史日志里的常见提示
- NoProviderFoundException:可补 hibernate-validator.
- SLF4J multiple bindings:通常是警告,不一定是调用失败.
========================
五,再改 application.yml(端口,路径,文档)
========================
文件:src/main/resources/application.yml
建议配置:
- server.port: 8123
- server.servlet.context-path: /api
- springdoc + knife4j 开启
为什么要 /api 前缀:
- 后续部署,网关转发和接口管理更清晰.
========================
六,重点说明:HealthController 不是初始化就有,是后面手动新建
========================
这个点上课必须讲清楚:
- 初始化项目时,通常只有启动类,不一定有 HealthController.
- 你现在的 HealthController 是后续自己新建的.
【具体新建步骤】
1)在 IDEA 左侧展开:
src/main/java/com.flyyansii.fllyyanaiagent
2)如果没有 controller 包:
- 右键 com.flyyansii.fllyyanaiagent -> New -> Package -> 输入 controller
3)右键 controller 包 -> New -> Java Class -> 输入 HealthController
4)文件后缀是 .java(IDEA 自动)
5)写入代码:
@RestController
@RequestMapping("/health")
public class HealthController {
@GetMapping
public String healthCheck() {
return "ok";
}
}
【地址拼接】
- 端口:8123
- 全局前缀:/api
- 控制器路径:/health
- 最终:http://localhost:8123/api/health
========================
七,先把后端基础跑通(先不碰 AI)
========================
1)运行主类:FllyyanaiagentApplication.
2)看到日志:Tomcat started on port 8123.
3)浏览器访问:
- http://localhost:8123/api/health
4)返回 ok 即通过.
========================
八,接入 Knife4j 文档页(验证扫描)
========================
1)启动后访问:
- http://localhost:8123/api/doc.html
- http://localhost:8123/api/v3/api-docs
2)如果没看到接口:
- 检查 controller 包路径是否在 springdoc 扫描配置内.
========================
九,阿里云百炼:从控制台到 API Key(超细)
========================
1)官方入口
- 获取 API Key:https://help.aliyun.com/zh/model-studio/get-api-key
- 配环境变量:https://help.aliyun.com/zh/model-studio/configure-api-key-through-environment-variables
- 模型列表:https://help.aliyun.com/zh/model-studio/models
- API 参考:https://help.aliyun.com/zh/model-studio/qwen-api-reference/
2)创建 API Key
- 登录百炼控制台.
- 进入 API Key 管理.
- 创建新 Key(sk-xxx).
- 复制后保存在安全位置,不要写进源码.
3)模型可用性检查
- 在模型列表确认模型名(例如 qwen-plus)存在.
- 确认当前业务空间有调用权限.
- 如果报 Model.AccessDenied,优先查权限,不是先改代码.
4)地域匹配(你之前高频坑)
- Key 所在地域要和域名一致.
- 国内常用:https://dashscope.aliyuncs.com
- 国际常用:https://dashscope-intl.aliyuncs.com
- 地域不一致常导致鉴权失败.
========================
十,把 API Key 配为环境变量(不要硬编码)
========================
1)变量名统一:DASHSCOPE_API_KEY
2)PowerShell 临时设置:
$env:DASHSCOPE_API_KEY="你的key"
3)PowerShell 永久(用户级):
[Environment]::SetEnvironmentVariable("DASHSCOPE_API_KEY","你的key","User")
4)验证:
echo $env:DASHSCOPE_API_KEY
5)设置后没生效:重开终端和 IDEA.
========================
十一,四种调用大模型方式(建议教学顺序)
========================
【方式1】SDK(先讲)
文件:src/main/java/com/flyyansii/fllyyanaiagent/demo/invoke/AiSdkInvoke.java
步骤:
1)读取环境变量 key
2)构造 messages(system + user)
3)设置 model=qwen-plus
4)调用 SDK
5)写入 result.json
注意:
- 运行这个类自己的 main,不是 SpringBoot 主类.
- 成功标志:result.json 有 status_code=200.
【方式2】Hutool HTTP 直调
文件:src/main/java/com/flyyansii/fllyyanaiagent/demo/invoke/HttpAiInvoke.java
步骤:
1)设置 URL
2)设置 Header(Authorization + Content-Type)
3)构造 Body(model/input/messages/parameters)
4)execute()
5)判断 response.isOk()
【方式3】Spring AI Alibaba
步骤:
1)pom 有 spring-ai-alibaba-starter
2)application.yml 增加 spring.ai.dashscope 配置
3)在 controller 下新建 SpringAiController
4)注入 ChatClient 或 ChatModel 调用
5)暴露 GET 接口测试
【方式4】LangChain4j
步骤:
1)增加 langchain4j-community-dashscope 依赖
2)新建 LangChain4jInvoke.java
3)builder 设置 apiKey + modelName
4)调用 model.chat(...)
5)打印结果
========================
十二,固定排错顺序(避免盲改)
========================
1)先确认运行入口类是否正确.
2)再看环境变量 key 是否存在.
3)再看地域与 endpoint 是否匹配.
4)再看 model 名和业务空间权限.
5)最后看依赖冲突和网络问题.
补充:
- 红色日志不一定是失败.
- 以接口返回与 result.json 为准.
========================
十三,课堂演示顺序(可直接照讲)
========================
第1轮:纯后端
- 创建项目 -> 改 pom -> 改 yml -> 新建 HealthController -> 跑通 /health
第2轮:接口文档
- 打开 /api/doc.html,确认接口扫描成功
第3轮:AI 接入
- 配环境变量
- 先跑 SDK
- 再跑 HTTP
- 最后讲 Spring AI / LangChain4j
第4轮:排错
- 按固定顺序定位,不盲改代码
========================
十四,安全规范(必须强调)
========================
1)不要把 API Key 写死在 Testapikey.java.
2)不要把账号密码发到聊天或群里.
3)泄露后立刻作废旧 key,重新生成.
4)敏感信息使用环境变量,不提交到仓库.
========================
十五,项目关键文件定位(讲课时方便打开)
========================
- C:\Users\FLY\Desktop\fllyyanaiagent\pom.xml
- C:\Users\FLY\Desktop\fllyyanaiagent\src\main\resources\application.yml
- C:\Users\FLY\Desktop\fllyyanaiagent\src\main\java\com\flyyansii\fllyyanaiagent\controller\HealthController.java
- C:\Users\FLY\Desktop\fllyyanaiagent\src\main\java\com\flyyansii\fllyyanaiagent\demo\invoke\AiSdkInvoke.java
- C:\Users\FLY\Desktop\fllyyanaiagent\src\main\java\com\flyyansii\fllyyanaiagent\demo\invoke\HttpAiInvoke.java
- C:\Users\FLY\Desktop\fllyyanaiagent\result.json