SpringBoot + Spring AI MCP IP查询系统技术架构文档
·
SpringBoot + Spring AI MCP IP查询系统技术架构文档
1. 系统概述
本文档详细描述了基于SpringBoot和Spring AI构建的MCP (Model Context Protocol) IP查询系统的技术架构、设计原理，以及与Dify MCP客户端的架构差异。
1.1 核心技术栈
- SpringBoot 3.2.0 - 应用框架
- Spring AI 0.8.1 - AI能力集成
- MCP协议 - 模型上下文协议
- WebSocket - 实时通信
- Apache Commons Net - 网络工具库
2. 系统整体架构
2.1 系统架构图
图2.1 系统架构图说明：
这个架构图展示了整个IP查询系统的分层设计和组件关系：
-
客户端层：支持多种访问方式
- Web界面：提供用户友好的浏览器访问界面
- REST API客户端：支持HTTP API调用方式
- MCP客户端：支持标准MCP协议客户端连接
-
SpringBoot应用核心：
- 控制器层：IpQueryController处理所有HTTP请求和API路由
- 服务层：业务逻辑核心，IpNetworkService处理IP计算，SpringAiService提供AI增强功能
- MCP层：实现MCP协议的服务器端和客户端功能
- 配置层：管理WebSocket和Spring AI的配置
-
外部服务：
- OpenAI API：提供AI分析能力
- 网络工具库：提供IP地址和网段计算功能
-
数据流向：展示了请求如何从客户端流向各个服务组件，最终调用外部服务完成业务处理
2.2 MCP协议通信流程
图2.2 MCP协议通信流程说明：
这个时序图详细展示了MCP协议的完整通信过程：
-
连接建立阶段：
- 客户端通过WebSocket连接到MCP服务器
- 服务器发送欢迎消息，确认连接成功
-
初始化阶段：
- 客户端发送initialize请求，获取服务器能力
- 服务器返回支持的协议版本和功能列表
-
工具发现阶段：
- 客户端请求tools/list获取可用工具
- 服务器返回所有可用工具的详细信息，包括参数说明
-
工具调用阶段：
- 客户端调用具体工具（如query_network_info）
- 服务器调用对应的IP网段服务进行计算
- 可选择性地调用Spring AI进行增强分析
- 返回最终的综合结果给客户端
这个流程体现了MCP协议的标准化特点，确保不同客户端都能以统一的方式访问IP查询功能。
3. 核心组件设计
3.1 MCP服务器架构
图3.1 MCP服务器架构类图说明：
这个类图展示了MCP服务器的核心组件和它们之间的关系：
-
McpServer（核心服务器类）：
- 管理WebSocket会话连接池
- 处理来自客户端的消息
- 提供工具列表和工具调用功能
- 集成IP网段服务提供业务能力
-
McpRequest（请求对象）：
- 遵循JSON-RPC 2.0标准
- 包含请求ID、方法名和参数
- 支持initialize、tools/list、tools/call等标准方法
-
McpResponse（响应对象）：
- 标准化的响应格式
- 支持成功结果和错误信息
- 泛型设计，支持不同类型的返回数据
-
IpNetworkService（业务服务）：
- 提供具体的IP网段计算功能
- 支持网段信息查询、IP范围检查等
- 封装Apache Commons Net库的复杂性
这种设计实现了MCP协议的标准化，同时保持了业务逻辑的清晰分离。
3.2 MCP客户端架构
图3.2 MCP客户端架构类图说明：
这个类图展示了MCP客户端的响应式设计架构：
-
McpClient（核心客户端类）：
- 管理与服务器的WebSocket连接
- 使用Reactor Sinks实现响应式消息处理
- 通过CompletableFuture提供异步API
- 提供类型安全的业务方法封装
-
WebSocketHandler（连接处理器）：
- 处理WebSocket连接生命周期事件
- 管理连接建立、消息接收和连接关闭
- 实现Spring WebSocket标准接口
-
ReactorNettyWebSocketClient（底层客户端）：
- 基于Reactor Netty的高性能WebSocket客户端
- 提供非阻塞I/O操作
- 支持连接池和自动重连
-
核心特性：
- 异步处理：所有操作都返回CompletableFuture，支持非阻塞调用
- 请求管理：通过pendingRequests映射管理并发请求
- 响应式流：使用Reactor Sinks处理消息流
这种设计确保了客户端的高性能和可扩展性，适合高并发场景。
4. 与Dify MCP客户端架构对比
4.1 本系统MCP架构
图4.1 本系统MCP架构说明：
这个架构图展示了我们系统的自包含式设计理念：
-
自包含特性：
- 所有功能都集成在一个SpringBoot应用中
- MCP服务器和客户端都是内置实现
- 不依赖外部平台，完全自主控制
-
分层清晰：
- 应用层：包含MCP协议实现和业务服务
- 通信层：提供多种访问方式（WebSocket MCP协议 + REST API）
- 数据处理层：专业的IP网段计算和AI分析能力
-
优势：
- 高性能：直接内存调用，无额外网络开销
- 完全控制：可以深度定制所有组件
- 独立部署：不依赖任何外部平台
4.2 Dify MCP客户端架构
图4.2 Dify MCP客户端架构说明：
这个架构图展示了Dify的平台集成式设计理念：
-
平台集成特性：
- 依赖Dify平台提供基础设施
- MCP客户端作为平台组件存在
- 通过工具注册表管理外部MCP服务
-
分层架构：
- 平台层：Dify提供工作流、智能体和LLM集成
- 集成层：专门的MCP管理和工具注册机制
- 服务层：连接各种外部MCP服务器
-
优势：
- 快速开发：利用平台现有能力
- 丰富生态：可以集成多种MCP工具
- 可视化配置：通过界面配置工作流
-
适用场景：
- 需要快速搭建AI工作流
- 需要集成多种不同的工具
- 团队偏向低代码开发
4.3 架构对比分析
| 对比维度 | 本系统MCP | Dify MCP客户端 |
|---|---|---|
| 架构模式 | 自包含式架构 | 平台集成式架构 |
| 部署方式 | 独立SpringBoot应用 | Dify平台插件 |
| 通信协议 | 原生WebSocket + JSON-RPC | Dify标准MCP协议 |
| 工具管理 | 内置工具注册 | 动态工具发现 |
| AI集成 | Spring AI直接集成 | Dify工作流集成 |
| 扩展性 | Java生态扩展 | Dify插件生态 |
| 使用场景 | 专业IP网段分析 | 通用AI工作流 |
5. 技术实现原理
5.1 MCP协议实现机制
5.1.1 消息处理流程
图5.1.1 消息处理流程说明：
这个流程图详细展示了MCP服务器如何处理客户端请求：
-
消息接收阶段：
- WebSocket接收到客户端消息
- 解析JSON格式的MCP请求
-
消息分类处理：
- initialize：返回服务器协议版本和能力信息
- tools/list：返回所有可用工具的详细说明
- tools/call：执行具体的工具调用
-
工具调用处理：
- 解析工具名称和参数
- 根据工具类型路由到对应的处理逻辑
- 支持4种核心IP查询功能
-
服务调用：
- 统一调用IpNetworkService处理业务逻辑
- 进行网段计算和数据处理
-
响应构造：
- 将处理结果封装为标准MCP响应格式
- 通过WebSocket返回给客户端
这个设计确保了MCP协议的标准化实现，同时保持了良好的扩展性。
5.1.2 工具注册机制
// 工具注册示例
private Map<String, Object> listTools() {
List<Map<String, Object>> tools = new ArrayList<>();
// IP网段查询工具
Map<String, Object> networkInfoTool = new HashMap<>();
networkInfoTool.put("name", "query_network_info");
networkInfoTool.put("description", "查询IP地址的网段信息");
networkInfoTool.put("inputSchema", Map.of(
"type", "object",
"properties", Map.of(
"ip", Map.of("type", "string", "description", "IP地址"),
"cidr", Map.of("type", "integer", "description", "CIDR网段掩码", "default", 24)
),
"required", List.of("ip")
));
tools.add(networkInfoTool);
return Map.of("tools", tools);
}
5.2 Spring AI集成原理
5.2.1 AI增强处理流程
图5.2.1 AI增强处理流程说明：
这个流程图展示了Spring AI如何增强IP查询功能：
-
数据预处理：
- 收集IP网段的基础信息（网络地址、掩码、地址数量等）
- 获取地理位置信息
- 格式化数据为AI可理解的格式
-
提示词构建：
- 基于业务需求构建专业的提示词
- 包含网段分析、安全评估、使用建议等要求
- 结合具体的IP数据生成上下文
-
AI调用链路：
- 通过Spring AI框架调用OpenAI API
- 使用配置的模型（如GPT-3.5-turbo）
- 传递构建好的提示词和参数
-
结果处理：
- 解析AI返回的分析结果
- 与原始网段数据合并
- 生成包含AI洞察的综合报告
-
响应整合：
- 将技术数据和AI分析结合
- 提供更加智能和有价值的结果
这种设计让传统的网段查询具备了智能分析能力，提供更深层次的洞察。
5.2.2 AI分析示例
// AI分析实现
private String buildAnalysisPrompt(Map<String, Object> networkInfo, Map<String, Object> geoInfo) {
return String.format(
"请分析以下IP网段信息:\n" +
"网段: %s/%s\n" +
"网络地址: %s\n" +
"广播地址: %s\n" +
"可用地址数: %s\n" +
"地理位置: %s, %s\n" +
"ISP: %s\n\n" +
"请提供：\n" +
"1. 网段规模分析\n" +
"2. 地理位置特征\n" +
"3. 潜在用途分析\n" +
"4. 网络特征评估",
networkInfo.get("ip"), networkInfo.get("cidr"),
networkInfo.get("network"), networkInfo.get("broadcast"),
networkInfo.get("addressCount"),
geoInfo.get("city"), geoInfo.get("country"),
geoInfo.get("isp")
);
}
6. 性能优化策略
6.1 并发处理优化
图6.1 并发处理优化说明：
这个流程图展示了系统如何处理高并发请求：
-
并发请求处理：
- 系统可以同时接收多个IP查询请求
- 每个请求都是独立处理，互不影响
-
线程池管理：
- 使用SpringBoot内置的线程池
- 合理配置线程数量避免资源浪费
- 支持动态调整线程池大小
-
异步处理机制：
- 所有耗时操作都采用异步模式
- 避免阻塞主线程影响其他请求
- 提高系统整体吞吐量
-
CompletableFuture使用：
- 提供类型安全的异步API
- 支持链式调用和异常处理
- 可以组合多个异步操作
-
结果聚合：
- 将多个异步操作的结果合并
- 确保数据的完整性和一致性
- 优化响应时间
-
响应返回：
- 统一格式化响应数据
- 支持流式响应以提高用户体验
6.2 内存管理
- 连接管理: 使用ConcurrentHashMap管理WebSocket连接
- 请求缓存: CompletableFuture管理异步请求
- 数据流控: 使用Reactor Sinks控制消息流
6.3 错误处理机制
// 错误处理示例
private McpResponse<?> handleMcpRequest(McpRequest request) {
try {
// 业务处理逻辑
return processRequest(request);
} catch (IllegalArgumentException e) {
return new McpResponse<>(request.getId(),
new McpResponse.McpError(-32602, "参数无效: " + e.getMessage()));
} catch (Exception e) {
logger.error("处理MCP方法出错: " + request.getMethod(), e);
return new McpResponse<>(request.getId(),
new McpResponse.McpError(-32603, "内部错误: " + e.getMessage()));
}
}
7. 安全考虑
7.1 输入验证
// IP地址验证
private boolean isValidIpAddress(String ip) {
try {
InetAddress.getByName(ip);
return true;
} catch (UnknownHostException e) {
return false;
}
}
7.2 访问控制
- WebSocket连接来源限制
- API接口访问频率限制
- 输入参数严格验证
8. 部署架构
8.1 单机部署
图8.1 单机部署架构说明：
这个部署图展示了系统在单机环境下的部署架构：
-
服务器端：
- SpringBoot应用：运行在8080端口的单一应用实例
- 多服务支持：同时提供WebSocket、REST API和MCP服务
- 资源共享：所有服务共享相同的JVM和系统资源
-
客户端访问：
- 浏览器：通过HTTP/HTTPS访问REST API
- MCP客户端：通过WebSocket连接MCP服务
- API客户端：程序化访问REST接口
-
适用场景：
- 开发测试环境
- 小规模部署
- 资源有限的环境
8.2 集群部署
图8.2 集群部署架构说明：
这个部署图展示了系统在生产环境下的高可用集群架构：
-
负载均衡层：
- 分发请求到不同的应用实例
- 支持健康检查和故障转移
- 可以使用Nginx、HAProxy或云负载均衡器
-
应用集群：
- 多个SpringBoot应用实例并行运行
- 每个实例独立处理请求
- 支持水平扩展，根据负载增减实例
-
共享存储：
- Redis缓存：共享会话状态和缓存数据
- 数据库：存储持久化数据
- 确保数据一致性和高可用性
-
优势：
- 高可用性：单点故障不影响整体服务
- 可扩展性：根据负载动态增减实例
- 性能优化：请求分散处理，提高并发能力
9. 监控和运维
9.1 健康检查
management:
endpoints:
web:
exposure:
include: health,info,metrics
endpoint:
health:
show-details: always
9.2 日志配置
logging:
level:
com.example.demo2: DEBUG
org.springframework.ai: INFO
org.springframework.web.socket: DEBUG
pattern:
console: "%d{yyyy-MM-dd HH:mm:ss} - %msg%n"
10. 与Dify集成的差异总结
10.1 架构差异
| 特性 | 本系统 | Dify |
|---|---|---|
| 集成方式 | 独立应用 | 平台集成 |
| 开发复杂度 | 中等 | 低 |
| 定制化程度 | 高 | 中 |
| 维护成本 | 中等 | 低 |
| 性能控制 | 完全控制 | 平台限制 |
10.2 使用场景
- 本系统适用于: 需要深度定制、专业IP分析、独立部署的场景
- Dify适用于: 快速搭建、通用AI工作流、低代码开发的场景
10.3 技术选择建议
-
选择本系统方案：
- 需要完全控制业务逻辑
- 有专业的Java开发团队
- 对性能和安全有特殊要求
-
选择Dify方案：
- 快速原型开发
- 团队技术能力有限
- 需要集成多种AI能力
11. 总结
本系统通过SpringBoot + Spring AI + MCP协议的组合，实现了一个功能完整、架构清晰的IP网段查询系统。相比Dify MCP客户端，本系统提供了更高的定制化程度和性能控制能力，适合需要专业IP分析功能的企业级应用场景。
通过标准化的MCP协议，系统既可以作为MCP服务器为其他客户端提供服务，也可以作为MCP客户端连接其他服务，体现了MCP协议的互操作性优势。
Agent 垂直技术社区，欢迎活跃、内容共建。
更多推荐
10
0- 0
已为社区贡献6条内容
所有评论(0)