项目介绍

本文主要帮助新加入的朋友成员在 30 分钟内建立对 Refinex-Cloud 完整的认知框架——包括它要解决的核心问题、为什么以现在这种形态存在、以及它的边界在哪里。

阅读前置条件： 了解 Spring Boot 基础开发、对微服务概念有基本认知即可。

一、项目从哪个问题出发

当一个团队决定构建自己的 AI 应用平台，通常会在两个极端之间摇摆：直接调用大模型 API 快速上线，或者引入一套重量级 AI 中台。前者在业务规模增长后面临失控的成本和混乱的调用逻辑，后者则往往带来过度设计的复杂性，远超实际需求。

Refinex-Cloud 从一个更具体的问题出发：如何在 Java 技术栈内，用生产可用的方式将 AI 能力（对话、RAG、Agent、多模态生成）嵌入一个完整的企业级应用，而不需要引入另一套独立的 AI 中台？

这个问题的特殊性在于它同时包含两个相互制约的需求：

• AI 推理服务具有流式输出、长耗时、高并发的特征，天然适合响应式编程模型；

• 而权限管理、系统配置、字典管理等传统业务模块用命令式 MVC 开发更高效、更直观。

如果用同一套技术栈强行统一，两边都会有明显的摩擦成本。Refinex-Cloud 的核心架构决策，正是选择在同一个微服务工程内让 WebFlux 与 MVC 有条件地共存，而非强制统一。

二、项目定位

Refinex-Cloud 是 Refinex 平台的后端微服务工程，基于 Spring Cloud Alibaba 2025 + Spring AI 1.1.2 + Java 21 构建，为前端应用 Refinex-Agent 提供完整的后端能力支撑。

它的定位可以用一句话概括：一个以 AI 能力为核心、以企业级工程规范为底座的生产级 Spring Cloud 微服务平台。

这句话中的两个限定词都有实质含义：

• "以 AI 能力为核心" 意味着系统的技术选型、架构分层、服务拆分都围绕 AI 场景的特殊需求展开，而不是在一个传统管理系统上附加 AI 功能；
• "以企业级工程规范为底座" 意味着认证、限流、分布式事务、可观测性这些基础能力必须达到生产可用的标准，而不是以 Demo 形式存在。

三、它能做什么

下表列出 Refinex-Cloud 当前提供的核心能力及其实现状态，供快速了解平台全貌。

四、整体架构概览

Refinex-Cloud 的服务拆分遵循两条主轴：

• 其一是能力边界，将认证、业务、AI 推理、媒体生成、知识库分别承载于独立服务，避免跨能力域的耦合；
• 其二是技术栈边界，AI 推理类服务（refinex-ai、refinex-media）强制使用 WebFlux 响应式栈，其余业务服务使用 Spring MVC，两类服务通过网关统一暴露，调用方无感知。

下面是大致的架构图：

最关键的设计点是 MVC 与 WebFlux 的横向分区。两个栈的服务均注册到 Nacos，通过同一个 Gateway 对外暴露，但内部编程模型完全不同。refinex-ai 返回 Flux<String> 支持流式输出，而 refinex-system 返回普通 R<T> 对象。网关层的 SSE 代理配置保证了流式响应不会被截断。

五、核心设计决策

决策：MVC 与 WebFlux 在同一工程内有条件共存

背景： AI 对话接口需要 SSE 流式输出，Spring AI 的 ChatClient 原生返回 Flux<String>，响应式栈与此天然契合。但系统管理、认证等模块以 CRUD 为主，响应式编程会大幅增加这类业务的开发复杂度，且没有实质性收益。

决策结论： AI 推理类服务（refinex-ai、refinex-media）强制使用 WebFlux 栈；其余服务使用 Spring MVC 栈。两套栈的 Web 层封装分别在 refinex-common-webflux 和 refinex-common-web 中实现，不允许一个服务同时引入两者。

选择理由：

• Spring AI 1.1.2 的流式 API 返回 Flux<ChatResponse>，在 WebFlux 中可以直接透传至 SSE 响应，零转换损耗；在 MVC 中需要通过 SseEmitter 手动订阅，不仅增加代码量，还需要额外处理背压问题。
• refinex-system 的 MyBatis-Plus 查询本质上是阻塞 I/O，在 WebFlux 中运行阻塞调用必须包裹 Schedulers.boundedElastic()，否则会污染事件循环线程，这是一个容易被忽视的运行时风险。

放弃的替代方案：

已知风险： 维护两套通用模块（refinex-common-web 和 refinex-common-webflux）意味着同类能力需要写两套实现。当前通过明确的模块命名约定和代码审查控制这一成本，后续如功能趋于稳定可评估合并部分实现。

重新评估时机： 如果 MyBatis-Plus 的 R2DBC 支持进入稳定期（当前版本存在功能缺失），可以重新评估是否将 refinex-system 等服务迁移至 WebFlux 以统一栈。

决策：以 Spring AI 1.1.2 作为 AI 能力统一抽象层

背景： 项目需要同时支持 OpenAI、Ollama、通义千问等多个模型提供商，且将来可能新增其他提供商。如果直接调用各厂商 SDK，模型切换会触发代码改动，且不同 SDK 的流式输出接口不统一。

决策结论： 所有大模型交互通过 Spring AI 的 ChatClient、EmbeddingModel、ImageModel、SpeechModel 四个抽象接口访问，业务代码不直接依赖任何厂商 SDK。

选择理由：

• Spring AI 1.1.2 对四类模型能力（对话、Embedding、图像生成、TTS）均提供了统一抽象，切换提供商只需修改 application.yaml 中的 spring.ai.* 配置，无需改动业务代码。
• Spring AI 的 RAG 模块（QuestionAnswerAdvisor）与 VectorStore 接口天然集成，避免了手动实现 检索-增强-注入 的流程，减少了约 60% 的 RAG 管道样板代码。

放弃的替代方案：

已知风险： Spring AI 仍处于快速迭代期，1.1.2 到下一个版本之间可能存在 API 不兼容变更。应对策略是在 refinex-ai 模块内封装一层 AiService 接口，将 Spring AI 的具体 API 调用隔离在实现类中，业务层依赖 AiService 而不直接依赖 Spring AI 接口。

重新评估时机： 如果 Spring AI 的某个核心抽象（如 VectorStore）在迭代中发生破坏性变更，且迁移成本超过引入 LangChain4j 的适配成本，则重新评估。

六、项目边界：它不是什么

明确边界与明确能力同样重要。以下是 Refinex-Cloud 明确不承载的职责：

• 不是模型训练平台。 项目不涉及模型训练、微调（Fine-tuning）的任何基础设施，这些能力属于 MLOps 范畴，超出了本项目的定位。
• 不是通用 AI 网关。 项目不提供多租户 AI 流量代理、模型计费路由等 API 网关类功能。当前的限流实现（refinex-common-ratelimit）服务于平台自身的防滥用需求，而非对外提供 API 代理服务。
• 不替代向量数据库本身的管理。 项目使用 Milvus/PGVector 作为向量存储，但不提供向量数据库的集群管理、索引调优界面，这些交由 Milvus 自身的管控工具处理。

七、相关资源