引入一个依赖的代价不是多一个 jar而是整条继承链的一次集体升级主题依赖治理 · 引入新依赖前的影响面实测先说结论当有人问我不引入 Agent 框架那 Agent 怎么写自己造船吗我意识到这个问题的前提就错了 ——把Agent等同于框架。Agent 的本体不是框架是一个循环 一份工具清单。真正缺的只是一层薄编排量化下来约 300 行其中一半还是参数 Schema 与工具实现。而**要不要引入一个依赖这个决策我最后不是靠查文档定案的是靠一次影响面实测定案的**新框架的最低版本要求会沿着继承链放大到整棵反应堆。13 个顶层模块全部继承同一个根 pom而 Boot 版本写在这个根 pom 的parent里 ——所以只影响 AI 模块是错觉真实代价是全站升级。我用的是一条可复用的四步套路① 先量化我到底缺什么能力 ② 候选方案逐条落到我的项目能不能落地 ↓ ↓ ③ ⭐ 影响面实测作决定性证据版本下限 × 继承链 真实代价 ↓ ④ 决策附诚实的代价 将来的迁移路径不锁死一、问题一个看起来很自然的引入请求需求本身很朴素给 AI 导购模块加上工具调用式 Agent模型自己决定调哪些工具、调几轮。我第一反应是上框架Spring AI 这类库自带工具编排、会话记忆、Advisor、向量库抽象生态成熟。顺着这个思路往下走问题很快就撞上来了候选方案能不能用关键理由手写薄编排 OpenAI 兼容 HTTP✅ 选定✅零新依赖与项目不新增外部依赖原则一致已有基础设施全部复用Spring AI❌卡版本代际官方GA 版本的支持矩阵是Boot 3.4.x→1.0.x / 3.5.x→1.1.x / 4.x→2.xBoot 3.3 及更早不在支持范围早期预发布里程碑曾支持更低 Boot但不适合作为生产依赖本项目Boot 3.2.5 低于下限→ 要接入必须先全站升级Spring AI Alibaba❌同样卡 Boot 代际且额外绑定一家云厂商生态LangChain4j可脱离 Spring Boot starter 使用、理论上能绕开 Boot 升级但a仍需核实版本适配b本身就是一个新增重依赖c本场景收益不足以抵消结论没有既用 Agent 框架、又不升 Boot的免费午餐。而升 Boot这四个字看起来只是改一行版本号。二、方案用影响面实测把争论一次性结束2.1 先量化到底缺什么Agent 一个循环 一份工具清单Function Calling ReAct 的本体只有六步① 拼 messagessystem 历史 本轮提问 ② 带工具清单调一次 → ③ 模型不再发起工具调用就收敛 ④ assistant 消息含 tool_calls原样回灌 → ⑤ 逐个执行工具、结果作为 tool 消息追加 ⑥ 最后一轮拿掉工具、流式吐出最终答案轮数上限兜底框架省掉的正是这几十行框架真正值钱的是周边生态多供应商抽象、MCP、向量库、Advisor、评测—— 而这些在本项目里要么已有、要么用不到。把方案拆成部件级清单之后结论就很清楚了真正要新写的只有工具契约 一次带 tools 的调用 循环会话、预算记账、并发闸门、SSE 流式、检索召回、降级兜底全都是现成的。一句话不是造船是装船舵。2.2 ⭐ 决定性证据影响面实测版本下限沿继承链放大① 版本声明在根 pom 里全体模块继承根 pom └─ parent spring-boot-starter-parent 3.2.5 ← Boot 版本在这里 properties spring-cloud.version 2023.0.3 ← 必须与 Boot 同代际 spring-cloud-alibaba.version 2023.0.1.2 ← 必须与 Boot 同代际实测这一步才是关键根 pom 里启用的module正好 13 个—— 10 个业务服务 1 个网关 2 个共享库模块mall-common/mall-pojo全部以根 pom 为 parent。⇒改根 pom 的 Boot 版本 整个反应堆一起改。只改 AI 模块这个假设在同一条实测面前直接不成立。② 版本约束是一整套矩阵不是一行Boot 之外Spring Cloud2023.0.3与 Spring Cloud Alibaba2023.0.1.2必须同代际接口文档组件springdoc 2.5.0 / Knife4j 4.5.0与 Boot 强耦合几乎必然要动ORM 与分页MyBatis-Plus 3.5.9 / mybatis-spring 3.0.3 / PageHelper 1.4.7、RPC / 事务 / 流控 starterDubbo 3.3.2 / Seata 2.1.0 / Sentinel BOM、连接池、分布式锁、定时任务、各测试依赖 ——每一类都得换成与目标 Boot 配对的版本。⚠️首要风险不在自己手里目标 Boot 能否落地取决于云生态 BOM 的发布节奏是否滞后。③ 影响面量化维度数量反应堆顶层模块1310 个业务服务 1 个网关 2 个共享库pom 文件总数含子模块34需重建部署11 个可运行单元11 个微服务含网关且跨机器必做回归认证与网关路由 / 秒杀 / 缓存主从 / 分布式事务 / RPC 全链路 / 搜索 / AI 全链路 / 流控规则 / 注册与配置中心④ 只升 AI 模块技术上能做但不该做理论上可以让 AI 模块不继承根 pom、单独挂一套高版本 Boot。但它依赖按旧代际编译的共享库→ 一个反应堆里出现两套 Spring 代际fat jar 里的高版本 Spring Framework 会覆盖传递依赖而共享库里的安全过滤器、Redis 配置是按旧代际编译的 →编译期无感、运行期NoSuchMethodError注册中心 / 流控 / 事务 / RPC 的 starter 也得为它单独选版本 →一个项目两套 Spring Cloud Alibaba构建与排障复杂度翻倍收益仅是让一个演示模块用上框架 →性价比不成立。⑤ 决策装船舵而不是造船部件处置依据工具契约接口 工具注册表 新建 ~60 行只需name / spec / execute带tools的请求 解析tool_calls 扩展客户端 ~80 行复用并发闸门 / 预算检查 / token 记账Agent 主循环 工具实现 ~100 行 ~40 行/工具主循环最后一轮复用现有流式接口工具内部复用既有检索服务零重复会话 / 预算 / 并发闸门 / 限流♻️已有Redis 会话 预算服务 并发闸门 流控规则SSE 流式 思考过程展示♻️已有客户端流式方法 前端组件检索 / 召回 / 重排、降级兜底♻️已有检索服务 双路径降级设计→新增 ≈ 300 行一半还是 Schema 与工具。引擎、油箱、安全阀、驾驶舱都已具备。反向论证框架自带的记忆 / Advisor / 向量库抽象进来后反而要绕过或适配我已有的 Redis 会话、ES 检索、预算闸门 ——框架的净收益被自己的既有设施抵消了。三、⭐ 更深一层的认知版本约束是传染性的这一节才是这次决策里最值钱的部分。① 版本不是一个数字是一条链。Spring Boot 版本写在根 pom 的parent里而 Spring Cloud、SCA、接口文档组件、ORM、RPC、事务、流控 starter必须同代际。所以升一次 Boot一整套 starter 矩阵重排不是改一行。② “模块能单独编译” ≠ “能单独升级”。这是最容易骗过人的地方给某个模块单独挂一套新 Boot编译毫无问题 —— 因为问题不在编译期。fat jar 里的 Spring Framework 会在运行期覆盖传递依赖而共享库里编译好的配置类、过滤器是按旧代际写的 →编译期无感、运行期才炸。③ 决定性的证据往往只有一条但它必须是实测而不是推断。“根 pom 里启用的模块正好 13 个、全部以其为 parent” —— 这一条比一整页功能对比更能定案。能实测的影响面 文档与直觉。④ 框架的净收益要减去适配成本。如果自家已有会话、检索、预算、闸门那么框架自带的同类设施不但不省事反而是要绕开的障碍。⑤ 决策必须带诚实的代价和将来的迁移路径。不用框架会失去什么我逐条写清并给了缓解不用框架会失去影响缓解现成工具编排自己写循环 解析就是那 ~150 行且已被实验验证多供应商无缝切换换供应商要改请求体地址 模型占位符已可配主流平台都是OpenAI 兼容协议→配置层可换只有换非兼容协议才需改客户端结构化输出 / 可观测自己校验参数、自己记账本来就必须做JSON Schema 声明 服务端二次校验不能只信模型记账与链路追踪已有而将来真迁框架这条路也没有堵死 —— 本次刻意让接口契约与配置文件都框架无关工具接口 / 能力档位配置 → 框架的工具注解与 ChatOptionsAgent 主循环 → 框架的 ChatClient Advisor也可直接删除而工具实现类一行都不用改业务实现与框架无关。⇒迁移是替换实现不是重写业务本次投入不浪费。五、踩坑清单认知 / 坑说明⭐版本约束是传染性的Boot 版本在根 pom 的parentCloud / SCA / 接口文档组件 / ORM / RPC / 事务必须同代际→ 一次升级 一整套 starter 矩阵重排⭐只影响一个模块要先用一行实测打掉实测根 pom 启用的模块共 13 个、全部以其为 parent → 一句实测比十页功能对比更能定案⚠️“模块能单独编译” ≠ “能单独升级”单独挂新版本会造成一个反应堆两套 Spring 代际编译期无感、运行期NoSuchMethodError⭐把缺什么能力量化到行数与部件拆成 11 个部件并标注 新建 / ♻️已有 → 得出≈300 行、一半是 Schema与不是造船是装船舵不量化就只能靠感觉争论⚠️框架的净收益会被自家既有设施抵消已有会话 / 检索 / 预算 / 闸门时框架自带的同类设施反而要绕过或适配⚠️首要风险常来自上游发布节奏目标 Boot 能不能落地取决于云生态 BOM 是否滞后发布—— 这部分不受自己控制必须提前核实⭐诚实的代价必须带缓解方案失去的四条能力逐条给出已有能力 / 配置层可换 / 本来就必须做避免决策看起来像硬撑⭐选型要留退出通道接口契约 配置文件都与框架无关 → 将来迁移是替换实现而非重写业务六、一句总结要不要那个 jar不是查文档能回答的问题是一条可实测的算式先在继承链上量影响面再决定要不要它。本文基于一个个人微服务电商演示项目的真实实施记录整理涉及的环境信息已做脱敏处理。