mobile wallpaper 1mobile wallpaper 2mobile wallpaper 3mobile wallpaper 4
2175 words
6 minutes
商城 Agent 实战(一):在 Spring Boot 商城接入 LangChain4j
2026-07-30
2026-09-28

用户在商城里问“推荐一款手机”,普通聊天模型可以给出建议,但它不知道店里实际有哪些商品,也不知道用户是否已经下单。把模型接到 Spring Boot,只是建立了对话通道;接入业务查询、规则检索和受控操作,才逐步形成商城 Agent。

这篇先解释模型如何进入现有商城:模块放在哪里,配置怎样加载,请求经过哪些对象,以及怎样判断第一条链路已经接通。

项目:AgentShop,基于 macrozheng/mall 二次开发。本文按 2026-09-28 本地源码核对,区分“用于理解的最小片段”和“仓库当前完整实现”,不要求把后续功能删掉后再逐篇重建。

1. 从一个问题看完整分工#

先用三种用户提问区分能力:

用户问题答案从哪里来
手机参数怎么选?模型组织通用解释
这款手机还有货吗?商品 Service 查询
签收后怎么退货?商城规则与售后流程

第一种问题可以先用基础聊天验证接入。后两种必须依赖商城自己的数据,不能把模型训练时见过的内容当作本店事实。

七篇文章分别讨论以下主题,可按正在解决的问题阅读:

这些能力可以组合,但职责不同。例如 Memory 帮助理解“刚才那款”,不能证明“刚才查到的库存现在仍然有效”。

2. 模型连接放在 mall-ai,业务入口留在应用中#

AgentShop 沿用 Maven 多模块结构。与本文相关的模块是:

mall-ai 模型配置、共享 AI 基础能力
mall-portal 会员聊天入口、商品/订单/售后 Tool
mall-admin 知识同步、评测、客服管理入口
mall-common CommonResult 与通用异常
mall-mbg 商城数据模型与 Mapper
mall-security 认证与权限基础设施

共享的是模型连接方式,不应因为前后台都能调用模型,就共享同一个业务能力集合。

当前前台使用 PortalAiAssistantController 和 PortalAssistant。公共模块中的基础 MallAssistant 类仍可用来理解最初接入,但早期的公共 MallAssistantController 与 /ai/chat 路由已经移除。阅读当前仓库时,应从 POST /ai/portal/chat 进入。

把 Controller 放进两个应用都扫描的公共模块,会让两个应用同时暴露它。以后增加后台工具时,很容易把权限含义混在一起,因此业务入口应有明确归属。

3. 先对齐版本,再排查模型调用#

本次核对的根 pom.xml 使用:

组件仓库配置
Java17
Spring Boot3.5.14
LangChain4j 核心1.18.1
Spring Boot Starter1.18.1-beta28

这是项目的依赖基线,不是所有读者都应立即升级到的版本。核心库与 Starter 的版本后缀可能不同,应以项目已经对齐的依赖组合为准。

根项目声明 mall-ai 模块并管理依赖版本;mall-portal、mall-admin 再依赖 mall-ai。用于模型连接的主要依赖是:

<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-open-ai-spring-boot-starter</artifactId>
</dependency>

这里使用 OpenAI-compatible 客户端连接 DeepSeek,open-ai 是库与配置前缀,并不表示请求一定发给 OpenAI。请求目标由 base-url 决定。

从 AgentShop 根目录先编译相关模块:

mvn -pl mall-ai,mall-portal -am -DskipTests compile

这一步验证 Java 与 Maven 依赖能否编译;它不会证明密钥有效、模型可用或数据库已经连接。

4. 配置只负责连接,不赋予商城能力#

共享模型配置位于 mall-ai/src/main/resources/mall-ai-langchain4j.yml。以下是适合放进文章和环境模板的写法:

langchain4j:
open-ai:
chat-model:
base-url: ${DEEPSEEK_BASE_URL:https://api.deepseek.com}
api-key: ${DEEPSEEK_API_KEY}
model-name: ${DEEPSEEK_MODEL_NAME}
temperature: 0.2
timeout: 60s
max-retries: 2
log-requests: false
log-responses: false

密钥与模型名由部署环境明确提供。文章不沿用本地开发配置中的密钥默认值,也不把某个模型别名写成永远有效的常量。

截至 2026-09-28,DeepSeek 官方更新日志推荐使用 deepseek-flash;旧 deepseek-v4-flash 名称暂时映射到新模型。复现项目时应记录实际模型标识,并重新验证工具调用行为,不能仅凭旧别名推断模型版本没有变化。DeepSeek 更新日志

应用通过配置导入加载共享资源:

spring:
config:
import: optional:classpath:mall-ai-langchain4j.yml

optional: 只表示导入资源可以缺失,不表示依赖 ChatModel 的 Bean 也可以缺失。排查“找不到 ChatModel”时,需要一起看资源是否打包、配置前缀、环境变量和自动配置条件。

单次模型超时与重试也不等于整次 Agent 请求的总预算。后续工具循环可能产生多次模型调用;请求层还需要自己的截止时间和容量控制。

5. 把模型调用收在一个清晰的服务边界#

最小调用链只有四步:

HTTP 请求 → Java 服务 → ChatModel → 文本回答

早期 MallAssistant 使用 chatModel.chat(SYSTEM_PROMPT + message)。这能发送文本,但拼接后的内容仍是一条用户消息,不是真正的 system/user 角色分离。

如果重新实现这个最小服务,可以明确构造消息。以下为教学改写片段,省略 Spring 注解与 import:

String chat(String message) {
ChatResponse response = chatModel.chat(
ChatRequest.builder()
.messages(List.of(
SystemMessage.from("""
你是商城咨询助手,请用中文回答。
当前没有接入商品、库存和订单查询。
涉及实时数据时,请明确说明无法查询。
"""),
UserMessage.from(message)))
.build());
return response.aiMessage().text();
}

ChatRequest、消息类型和 ChatResponse 均来自 LangChain4j。角色分离使消息结构更清晰,但系统提示仍不能代替工具权限和业务校验。

当前完整商城使用另一层抽象:定义 PortalAssistant 接口,由 AiServices.builder(...) 创建代理,把模型、Tool、RAG 和 Memory 组合起来。Controller 调用接口,代理负责与模型交互。它与 Spring 的业务 Service 是不同层次的对象。LangChain4j AI Services

6. 当前 HTTP 接口是什么样#

聊天请求由 AiChatRequest 接收,消息要求非空且限制长度。长度限制保护入口资源,不保证模型输出正确,也不代替下游 Token 预算。

当前前台接口接收:

{
"conversationId": "shopping-demo",
"message": "你好,你能帮我做什么?"
}

使用会员登录态调用 POST /ai/portal/chat,成功结果中的 data 已经是对象:

{
"code": 200,
"message": "操作成功",
"data": {
"conversationId": "shopping-demo",
"answer": "这里是助手回答。"
}
}

answer 是示意文本,不能作为真实模型固定输出。前端需要读取 data.answer,不能继续按最早版本的 CommonResult<String> 解析。

在 PowerShell 中可以调用已启动的本地 Portal:

Terminal window
$chatBody = @{
conversationId = "shopping-demo"
message = "你好,你能帮我做什么?"
} | ConvertTo-Json
$chatArgs = @{
Method = "Post"
Uri = "http://localhost:8085/ai/portal/chat"
Headers = @{ Authorization = "Bearer $env:PORTAL_TOKEN" }
ContentType = "application/json; charset=utf-8"
Body = [Text.Encoding]::UTF8.GetBytes($chatBody)
}
Invoke-RestMethod @chatArgs

PORTAL_TOKEN 是会员登录后取得的 Token,不能用管理员 Token 代替。当前 Controller 还会访问 Redis 会话服务,完整应用也依赖现有商城设施;这个接口不是只填模型密钥就能独立启动的 Demo。

启动多模块工程时,可以先安装依赖,再只对可执行模块启动:

mvn -pl mall-portal -am -DskipTests install
mvn -f mall-portal/pom.xml spring-boot:run

避免把 spring-boot:run 对整个依赖 Reactor 执行,导致它先尝试启动没有主类的公共模块。运行前按项目说明准备商城数据库、Redis 及启用的其他依赖。

7. 用分层验证定位失败#

第一层验证 HTTP 协议:空消息是否被拦截,返回结构是否正确,未登录请求是否进入业务调用。这里可以 Mock Assistant,无需消耗模型额度。

第二层验证消息构造:用可控 ChatModel 检查系统消息、用户消息和模型返回值如何转换。这能验证程序协议,不能证明真实模型一定遵循所有要求。

第三层才是少量真实模型验证:使用测试账号和测试数据,确认模型可访问、响应能解析,并记录实际模型名。

遇到失败时,沿调用链定位:

现象先看哪一层
找不到 ChatModel依赖、配置导入与 Bean
商城接口拒绝登录Portal 的认证链
供应商返回鉴权错误模型密钥与供应商响应
回答没有真实商品商品 Tool 是否执行
前端展示为空是否仍读取旧 data 格式

一段流畅回答只能证明模型返回了文本。要证明它查过商城,应继续观察商品 Tool 的执行轨迹,而不是只问模型“你是否查询了数据库”。

本文完成的是内容与源码核对,没有重新执行 AgentShop 的真实 DeepSeek 调用。文中的命令是复现步骤,不能当作本次联调成功记录。

Share

If this article helped you, please share it with others!

商城 Agent 实战(一):在 Spring Boot 商城接入 LangChain4j
https://github.com/huanchenfeng/agentShop
Author
梦幻晨风
Published at
2026-07-30
License
CC BY-NC-SA 4.0

Some information may be outdated

Table of Contents