项目：X-Pan ｜ 版本：v1.2 ｜ 生成日期：2026-10-06 ｜ 依据：源码分析
《00-项目总览》第 3 节已给出三端技术栈的速览表，本文做的是"逐个解析"：后端 Maven 依赖树（父 POM 仲裁 + framework/server 两层）、Web 前端 package.json、Flutter pubspec.yaml，每个依赖回答六个问题——版本、用途、使用位置（真实源码路径）、选型理由、替代方案、升级风险。三张速览表之外，第 2 节对决定架构走向的重点依赖逐段展开。先澄清一个常被误读的事实：X-Pan 后端没有引入任何 Spring Cloud 组件（全仓库 grep spring-cloud 零命中），"微服务"是按 ADR-001 的模块化单体形态实现的——服务发现、配置中心、RPC 网关这些 Spring Cloud 家族成员在这里都无用武之地，这与部分资料把本项目描述为"Spring Cloud 微服务"的说法不符，以源码为准。所有版本号取自 x-pan-parent/pom.xml 的 properties、各子模块 pom 与三端清单文件，均为 2026-10-06 时点快照；mvn dependency:tree 输出会随依赖传递略有出入，以清单文件为准。
x-pan-parent/pom.xml）父 POM 继承 spring-boot-starter-parent:3.4.13（Spring Boot 官方 BOM 负责 Spring 全家桶与大量三方库的版本仲裁），自己的 dependencyManagement 只管 Spring BOM 不管或管不到的库。版本属性逐项如下表（"消费方"指实际引入该依赖的模块）：
| 依赖 | 版本 | 用途 | 消费方 | 选型理由 | 替代方案 | 升级风险 |
|---|---|---|---|---|---|---|
| spring-boot-starter-parent | 3.4.13 | 框架基座与 BOM | 全部 | Boot 3 线最新补丁档，Jakarta 命名空间 | 固定 3.2.x LTS 心智 | 3.5+ 升级需回归 Redis 前缀与序列化 |
| mysql-connector-j | 8.4.0 | MySQL 驱动 | orm/mybatis-plus | 官方新坐标（com.mysql） | mariadb-java-client | 驱动与 MySQL 8.0 服务端兼容性需同测 |
| druid | 1.2.25 | 连接池 | distribution 配置（运行时经 MP 装配） | 监控页面与 SQL 防火墙生态成熟 | HikariCP（Boot 默认） | Hikari 迁移需重写池参数与监控面 |
| mybatis-plus-spring-boot3-starter | 3.5.9 | ORM 增强 | orm/mybatis-plus | 单表零 SQL、Service 封装 | Spring Data JPA / 原生 MyBatis | 3.5.9 → 3.5.x 补丁安全；跨 3.6 需回归 |
| velocity-engine-core | 2.3 | 代码生成器模板 | orm/mybatis-plus（CodeGenerator） | MP generator 官方默认模板引擎 | freemarker | 仅生成期使用，无运行时风险 |
| guava | 33.6.0-jre | 集合/切分工具 | framework/core（IdUtil 的 Splitter/Lists）、测试 | API 稳定、团队熟悉 | commons-collections4 | 大版本升级罕见破坏，低风险 |
| commons-lang3 / collections4 | 3.20.0 / 4.4 | 字符串与集合工具 | framework/core、server 各处 | Apache 基金会维护、语义稳定 | hutool（已并存） | 低风险 |
| commons-io | 2.18.0 | 文件工具 | framework/core FileUtils、local 引擎、ThumbnailServiceImpl | FilenameUtils/FileUtils 免重造 | JDK NIO.2 | 2.14+ 的 PathUtils API 变化需留意 |
| commons-compress | 1.27.1 | tar/gz/bz2/zip 解压 | server extract 模块（ExtractServiceImpl） | 纯 Java 零系统依赖，P1 注释明示 | TrueVFS / 系统 unzip | 1.27 起对 zip 加密/编码行为有微调 |
| fastjson2 | 2.0.64 | JSON 序列化（部分组件） | WS 处理器、分片清理任务、物理删除监听器、FolderTreeNodeVO、OSS 引擎 | 国产高性能 JSON，写法简洁 | 统一收敛到 Jackson | 与 Jackson 并存双栈（见第 5 节） |
| jjwt (api/impl/jackson) | 0.12.6 | JWT 签发验签 | framework/core JwtUtil | 0.12 新 fluent API、长期维护 | java-jwt / nimbus | 0.12 API 已是重写后形态，0.13+ 应平滑 |
| hutool-core | 5.8.47 | 雪花 ID、Base64、日期 | IdUtil、FileChunkServiceImpl（DateUtil.offsetDay）等 | 一个库顶十个工具库 | 分散引入多个 Apache 工具 | 5.8.x 补丁安全；6.x 是大版本 |
| resilience4j-spring-boot3 / micrometer | 2.2.0 | 熔断与重试 | storage-engine-minio、offline | Spring Boot 3 官方推荐、指标直通 Micrometer | Sentinel / Retryannotation 自研 | 2.x 内补丁安全 |
| springdoc-openapi-starter-webmvc-ui | 2.8.6 | OpenAPI 文档 | framework/swagger2 | Boot 3 配套的 springdoc 线 | springfox（已死） | 与 knife4j 版本需配套 |
| knife4j-openapi3-jakarta | 4.5.0 | 文档 UI（doc.html） | framework/swagger2 | 中文增强 UI、生产可全关 | 原生 swagger-ui | 跟随 springdoc 升级节奏 |
| aliyun-sdk-oss | 3.18.5 | OSS 引擎 SDK | storage-engine-oss（模块未接线） | 官方 SDK | S3 兼容层（MinIO 客户端连 OSS） | 未启用，升级零收益零风险 |
| fastdfs-client | 1.27.2 | FastDFS 引擎 | storage-engine-fastdfs（模块未接线） | 社区最活跃 Java 客户端 | 自研 HTTP 网关 | 未启用 |
| rocketmq-spring-boot-starter | 2.3.6 | （声明未使用） | 无 | 预留 | —— | 建议删除（见第 5 节） |
| reflections | 0.10.2 | （声明未使用） | 无 | 预留 | —— | 建议删除 |
| mapstruct / lombok / binding | 1.6.3 / 1.18.46 / 0.2.0 | PO↔Context↔VO 转换与样板消除 | 全部模块 annotationProcessorPaths | 编译期生成零反射开销 | 手写转换 / Java records | 两者注解处理器顺序敏感（binding 0.2.0 已锁） |
x-pan-parent/server/pom.xml）除六个框架模块外，server 自身引入的都是 P3/P4 阶段加的能力件：spring-boot-starter-aop（切面鉴权的前提，出现两次属冗余声明）、spring-boot-starter-websocket（原生 WS，无 STOMP）、resilience4j-spring-boot3 + resilience4j-micrometer、micrometer-registry-prometheus（/actuator/prometheus 抓取面）、micrometer-tracing-bridge-otel + opentelemetry-exporter-otlp（链路桥接与导出，导出开关默认关）、logstash-logback-encoder:7.4（server/src/main/resources/logback-spring.xml 第 32 行的 LogstashEncoder 提供 JSON 结构化日志）、commons-compress（解压扩展）。值得注意的两处细节：spring-boot-devtools 被标为 test scope（让测试期热加载可用而不进生产 fat jar，做法干净）；logstash-logback-encoder 是唯一一个没有走父 POM 仲裁、直接在 server pom 写死版本的三方依赖——它是第 5 节健康度评估的点名对象之一。
框架层依赖呈清晰的金字塔：x-pan-core 只依赖工具库（jackson-annotations/guava/lang3/collections4/commons-io/fastjson2/jjwt 三件/hutool-core/actuator/mapstruct），零业务框架依赖，是唯一的"叶子"；x-pan-web 依赖 core + starter-web + starter-validation；x-pan-cache-redis 依赖 cache-core + starter-data-redis + jackson-databind；x-pan-mybatis-plus 依赖 core + mysql-connector-j(runtime) + MP starter + generator + velocity；x-pan-schedule 与 x-pan-swagger2 各只依赖 core 加一个 starter；storage-engine-core 依赖 core + cache-core（给引擎实现提供缓存常量）；四个引擎实现各自只加自家 SDK——minio 引擎额外引 resilience4j-spring-boot3 与 aop（@CircuitBreaker 注解生效的前提）。这张依赖图最大的优点是没有一个框架模块依赖 server 或感知业务，方向恒定；最大的限制是 minio 引擎把熔断注解绑定进了引擎模块——意味着任何新引擎想获得同等熔断能力都要复刻这段注解与配置（见 ADR-009 的代价侧）。
把上面三张表合起来看，有三个值得记住的结构性事实。第一，版本声明高度集中：除 server pom 里的 logstash-logback-encoder 一处例外，全部三方版本都收敛在父 POM 的 properties 与 dependencyManagement 里，子模块引依赖不写版本号——升级一个版本号属性即可全仓库生效，这是 Maven 多模块项目的标准姿势，也是第 5 节健康度评估能"一处看清全部版本"的前提。第二，依赖的引入时间可从注释读出：server pom 的多个依赖带 P1/P3/P4 阶段注释（commons-compress 标 P1 解压扩展、micrometer-tracing 标 P4 链路追踪、websocket 标 P4 实时通知），与根 CHANGELOG.md 的阶段划分一一对应——依赖清单本身就是项目演进的化石层，排障时"这个能力是哪个阶段加的"直接看注释即可。第三，测试与文档依赖不进生产：devtools 锁 test scope、configuration-processor 标 optional、spring-boot-starter-test 只在测试类路径，最终 x-pan-server.jar（spring-boot-maven-plugin repackage 产出，mainClass 指向启动类）里的类路径与生产行为一致——这一点配合 Dockerfile 的"构建即产物"模式（mvn -pl server -am package），保证了"测试跑的、镜像跑的、上线跑的"是同一份依赖闭包。
Boot 3 线意味着三件事已一次到位：Jakarta 命名空间（全部 jakarta.servlet.* 导入）、Spring Framework 6 的 AOT 友好基础、以及 Boot 3 对 spring.data.redis 等配置前缀的迁移（历史上曾因三份配置文件不同步出过问题，见《14-配置与环境详解》第 4 节）。而"没有 Spring Cloud"是理解本项目架构的钥匙：服务间通信只有进程内接口调用与 Spring 事件（《07-模块详解》第 5 节），负载均衡交给 Nginx（least_conn 反代 MinIO 四节点），熔断用 Resilience4j 注解而非 Sentinel 集群流控——这套组合把"微服务技术栈"里每个组件都换成了单进程下的最简等价物。若未来真拆服务，最先要补的是接口调用换 OpenFeign 与事件换 MQ，而 DEV_GUIDELINES.md 的"模块间只走接口"红线正是为这一天预付的改造费。
io.minio:minio:8.5.10 声明在 x-pan-parent/framework/storage-engine/storage-engine-minio/pom.xml 的 properties（第 19 行），该模块也是全仓库唯一允许 import io.minio.* 的地方（DEV_GUIDELINES 红线："业务代码禁止绕过 StorageEngine 直接操作对象存储 SDK"）。选 8.5 线的理由：composeObject、预签名 URL、批量 removeObjects（迭代消费删除结果）三组 API 都是合并/直链/清理三个核心场景的直接依赖，8.5.x 对 okhttp 4.x 的适配成熟。升级风险有三：SDK 与 MinIO 服务端版本有隐式配套关系（生产集群是 RELEASE.2025-04，见《06-部署运行》），升 SDK 应与服务端升级同批验证；replaceEndpoint 的签名绑定问题（MinIOStorageEngine.java 第 509-517 行注释块）说明预签名 URL 的主机名语义是 SDK 行为中最脆弱的一环，任何升级必须回归 302 直链路径；okhttp 传递依赖版本会随 SDK 升级漂移，需关注连接池参数兼容。
JwtUtil 全部构建在 jjwt 的 0.12 fluent API 上（Jwts.builder().claim(...)），0.12 是 jjwt 的重写版本线，旧的 parser().setSigningKey() 链式 API 已废弃——这决定了回退到 0.11 是破坏性的，升级方向唯一。hutool 只引了 hutool-core 单 artifact（而非全家桶 hutool-all），依赖面克制；雪花 ID 用 cn.hutool.core.lang.Snowflake 而非手写，IdUtil.java 头注释明确记录了动机："规避手写实现中可能出现的网络接口枚举 NPE、时钟回拨、全局 synchronized 串行等隐患"——这是一次典型的"用成熟实现换掉自己造的轮子"决策。两者升级风险都集中在 framework/core 这个被全员依赖的叶子模块：core 一动，全模块重编译，且 JwtUtilTest/AES128UtilTest 的 8 个用例是唯一的回归网（《09-测试与质量保障》第 1 节）。
simple-uploader.js@0.6 + spark-md5@3.0.2 是上传协议的另一半真身（后端分片协议就是按它的 testChunks/chunkNumber 语义设计的）：前者负责分队、并发 3、断点续传判定（checkChunkUploadedByResponse 严格按 uploadedChunks），后者在 Web Worker 里算全文件 MD5。风险点在 simple-uploader.js 已经低维护（0.6 停留多年），但协议已被后端固化，替换它等于重新协商协议，性价比极低——更现实的演进是《10-性能设计与优化》第 7 节的预签名 PUT 直传，届时它将被绕开而非替换。预览矩阵（pdfjs-dist@6.2.108、@vue-office 四件、artplayer@5.4、aplayer@1.10.1、shiki@4.4.2、vditor@3.11.2、jszip、pdf-lib、qrcode、fuse.js）全部经 vite.config.ts manualChunks 拆为独立 vendor chunk 按需加载（《10-性能设计与优化》第 5 节），选择它们的共同理由是"纯前端、无后端依赖、可懒加载"；pdfjs-dist 大版本（v6）升级需同步 worker 加载方式，是前端依赖里单点升级成本最高的一个。状态与网络层（vue@3.5.13/pinia@2.3/vue-router@4.5/axios@1.7.9）全部取当前主流稳定线，vue-tsc@2.1.10 承担类型门禁（npm run build 先跑 vue-tsc --noEmit，见 x-pan-fronted/package.json scripts）。UI 侧没有组件库依赖——26 个 Base 组件 + tailwindcss@4.3.3 是刻意为之（理由见《00-项目总览》3.2）。
状态管理选 flutter_riverpod@2.6.1 而非 BLoC/getx：五个 provider 全部用 StateNotifier + copyWith 保持不可变（x-pan-mobile/lib/providers/），组合式的 provider 图天然适配"登录态广播驱动全局重登录"这类横切需求（onNeedRelogin 流）。网络层 dio@5.7 单例 + 拦截器（lib/core/network/http_client.dart）处理 token 注入、new-access-token 续期、code=10 抛 NeedReloginException——选 dio 而非 http 包的理由是拦截器模型与 Web 端 axios 拦截器行为一一对应，双端契约可镜像维护。媒体矩阵按"每类预览一个专用库"拆分：video_player@2.9.2 + chewie@1.8.5（视频）、just_audio@0.9.40（音频）、flutter_pdfview@1.3.2 + pdfx@2.9.2（PDF 双实现，前者原生渲染后者纯 Dart，可能因平台兼容双备）、webview_flutter@4.10.0（Office 兜底）、cached_network_image@3.4.1（图片缓存）。flutter_secure_storage@9.2.2 存 token（Keychain/Keystore），shared_preferences@2.3.2 存轻量偏好，upload_task_storage 自研持久化断点续传任务。实时通道 web_socket_channel@3.0.1 + flutter_local_notifications@17.2.2 组合把 WS 帧转系统推送。风险最值得点名的是 flutter_markdown@0.7.4：该包已被 Flutter 团队宣布停止维护（discontinued），Markdown 渲染长期应迁移到社区方案（markdown_widget 等）——⚠️ 待确认迁移计划；其余媒体库大版本升级普遍伴随 Android/iOS 平台实现的 breaking change，升级必须双端真机回归。
前端 dependencies 全量 23 个、devDependencies 18 个，上节已展开重点，这里补两点清单层面的观察。其一，前端 dependencies 里没有一个"状态管理之外的大型框架级依赖"——26 个 Base 组件替代了组件库、原生 WebSocket 封装替代了 socket.io 类库、自研 simple-http 补充 axios，这使得 npm ls 的依赖树很浅，lock 文件的升级冲突面小。其二，devDependencies 里的 unplugin-auto-import 与 unplugin-vue-components 两个自动导入插件值得点名：它们让页面代码里"看不见"的 import 在编译期生成，代价是读源码时需要在 vite.config.ts 与生成的 auto-imports.d.ts/components.d.ts 里二次确认来源——新协作者第一次遇到"这个组件没 import 却能用"时先查这两个插件。移动端 pubspec 的分组注释（状态管理/网络请求/本地存储/媒体播放等九组）与实际使用位置一一对应，是三端清单里可读性最好的一份。下表补齐移动端 dependencies 全量（x-pan-mobile/pubspec.yaml，Dart SDK ^3.9.2 / Flutter 3.35）：
| 依赖 | 版本 | 用途 | 使用位置 |
|---|---|---|---|
| flutter_riverpod | ^2.6.1 | 状态管理 | lib/providers/ 五个 provider |
| dio | ^5.7.0 | HTTP 客户端 | lib/core/network/http_client.dart |
| go_router | ^14.6.2 | 顶层三路由 + 登录守卫 | lib/router/app_router.dart |
| flutter_secure_storage | ^9.2.2 | Token 安全存储 | lib/core/storage/token_storage.dart |
| shared_preferences | ^2.3.2 | 轻量偏好存储 | 同上及设置页 |
| crypto | ^3.0.5 | MD5（秒传/分片标识） | lib/services/upload_service.dart、lib/utils/md5 |
| file_picker / path_provider / open_filex | ^8.1.2 / ^2.1.4 / ^4.5.0 | 选文件/取路径/打开文件 | 上传与下载链路 |
| cached_network_image | ^3.4.1 | 图片加载缓存 | 列表与预览页 |
| video_player + chewie | ^2.9.2 / ^1.8.5 | 视频播放 | video_preview_page.dart |
| just_audio | ^0.9.40 | 音频播放 | audio_preview_page.dart |
| flutter_pdfview + pdfx | ^1.3.2 / ^2.9.2 | PDF 双实现 | pdf_preview_page.dart |
| webview_flutter | ^4.10.0 | Office 预览兜底 | office_preview_page.dart |
| web_socket_channel | ^3.0.1 | WS 实时通道 | lib/services/notification_service.dart |
| flutter_local_notifications | ^17.2.2 | 系统推送 | lib/services/local_notification_service.dart |
| flutter_markdown | ^0.7.4 | Markdown 渲染 | AI 助手页（已停维护，见 2.5） |
| archive | ^3.6.1 | ZIP 解析（XMind 预览） | xmind_preview_page.dart |
| intl | ^0.19.0 | 日期/数字格式化 | 各列表页 |
按"在用程度 × 维护状态 × 升级路径"三个维度给后端与三端依赖做一次体检，结论按风险从高到低：
第一梯队（建议一次提交内处理）：rocketmq-spring-boot-starter 与 reflections 两项 dependencyManagement 声明全仓库零使用（grep 逐一核实），属"幽灵依赖"——拉包时间与安全扫描面白白扩大，删除无任何连带成本；server pom 里重复声明的 spring-boot-starter-aop 同理。第二梯队（列入观察）：其一，logstash-logback-encoder 是唯一绕过父 POM 仲裁写死版本（7.4）的三方件，7.4 已落后当前 8.x 线，且它直插日志管道，升级需在真实日志输出上回归；其二，fastjson2 与 Jackson 双 JSON 栈并存——R 契约、Spring Cache、IdEncryptSerializer 走 Jackson，而 WS 帧、清理任务、FolderTreeNodeVO 走 fastjson2（本次 grep 核实的五个文件），双栈意味着同一条消息可能被两种序列化器处理，字段行为差异（如 null 处理、日期格式）是隐性 bug 温床，长期建议收敛到 Jackson；其三，flutter_markdown 停止维护（2.5 节已述）。第三梯队（低风险常态升级）：Spring Boot 3.4 补丁线、hutool/commons 系工具库、mapstruct/lombok 均属"随版本走即可"的低维护负担依赖，其中 framework/core 的 8 个工具测试是升级的最低保障网，任何 core 依赖升级前应先让它们保持全绿。总体评价：这套依赖面在同类项目里属于克制型——后端直接依赖约 25 个（不含传递），前端 23 个，移动端 22 个，没有出现"引一个全家桶只为一处小功能"的滥用；两个幽灵声明 + 一处版本旁路 + 一处双 JSON 栈是仅有的结构性欠账，且全部有低成本出路。升级策略上建议固定节奏：每季度对齐一次 Spring Boot 补丁线与 CI 全绿，媒体类与 MinIO SDK 类升级必须带真机/集群回归，避免"清单上最新、行为上未知"的假升级。