1. 从一堆“重复造轮子”的痛说起QuickBlue 到底想解决什么做过企业级 Java 项目的人大概都有这种体会每启动一个新业务线架构组就要把过去几年攒下来的那套东西再抄一遍。注册中心、配置中心、网关、鉴权、限流、日志链路、分布式事务、多数据源、缓存穿透防护……代码仓库里躺着五六个“基础框架”分支每个分支都号称是最新最全的版本但真正维护起来谁碰谁头疼。更麻烦的是业务团队和架构团队之间永远在拉扯——架构组觉得业务方乱改底层业务方觉得架构组给的东西又重又难用加个字段要改三个模块。QuickBlue 这个项目本质上就是冲着这个场景来的。它想做的事情是把企业里那些“每个项目都要重来一遍”的通用能力收敛成一个统一的AI 应用底座。注意这里的关键词是“底座”不是“框架”也不是“脚手架”。框架是你得按它的规矩写代码脚手架是你生成完就扔而底座的意思是它长期存在、持续演进业务应用像插件一样插在上面跑底层的微服务治理、数据通信、AI 能力接入、可观测性这些脏活累活全部由底座兜住。那为什么标题里还带了个“AI”因为这两年企业做 AI 落地的路径变了。早几年大家是单独搞一个算法团队训练模型、部署推理服务业务系统通过 HTTP 调一下完事。现在不一样了AI 能力要嵌到业务流程里——客服工单要自动分类、合同要自动抽取条款、运营报表要自然语言查询、代码仓库要自动 review。这些场景对底座的诉求和传统微服务底座完全不是一回事传统底座关心的是服务发现和负载均衡AI 应用底座还得关心模型路由、Token 计量、向量检索、Prompt 版本管理、推理服务的弹性伸缩。QuickBlue 的定位就是把这套东西揉在一起。它基于 Spring Cloud 体系构建跑在 JDK 21 上用微服务拆分的方式把 AI 能力和业务能力解耦。你可以把它理解成一个“企业内部的 AI 操作系统”业务团队只管写自己的业务逻辑需要 AI 能力的时候从底座拿需要数据通信的时候走底座的总线需要限流降级的时候底座自动生效。这套思路和热搜词里频繁出现的“微服务架构”“微服务拆分”“spring cloud sentinel datasource redis 集群”是高度吻合的——它不是一个玩具项目而是一套要认真考虑生产环境落地的工程体系。这篇文章我会从架构设计、核心模块拆解、实操落地、踩坑排查几个角度把 QuickBlue 这类 AI 应用底座的完整面貌讲清楚。不管你是正在选型的技术负责人还是准备动手搭底座的架构师或者只是好奇“AI 应用底座”这个词到底指什么都能从下面这些内容里拿到能直接用的东西。2. 架构整体设计与技术选型背后的取舍2.1 为什么是 Spring Cloud 而不是别的选 Spring Cloud 做底座很多人第一反应是“老套”。但真在企业里落地过就知道技术选型的第一原则不是先进而是团队能不能接得住。国内绝大多数中大型企业的 Java 团队Spring 生态的熟练度是最高的招人好招出问题好查社区资料多。QuickBlue 选择 Spring Cloud 作为微服务治理的基础本质上是把学习成本压到最低。具体到组件层面一个典型的 QuickBlue 底座会包含这几块能力域选型选它的理由服务注册与发现Nacos注册配置一体控制台好用国内文档全配置中心Nacos Config和注册中心复用减少运维组件数量网关Spring Cloud Gateway响应式模型性能比 Zuul 好扩展点清晰熔断限流Sentinel规则动态推送控制台可视化和 Nacos 天然配合负载均衡Spring Cloud LoadBalancer替代已停更的 Ribbon官方维护分布式事务SeataAT 模式对业务侵入小适合大多数场景链路追踪Micrometer Tracing Zipkin和 Spring Boot 3 体系无缝集成缓存Redis 集群高可用支持多种数据结构这套组合不是拍脑袋定的而是踩过坑之后收敛出来的。比如早期有人用 Eureka 做注册中心结果 Eureka 2.x 停止维护迁移成本很高有人用 Zuul 1.x 做网关结果发现它是阻塞模型高并发下线程池直接打满。QuickBlue 直接跳过这些历史包袱用当前主流且仍在活跃维护的组件这是对团队负责。2.2 JDK 21 带来的实际收益JDK 21 是 LTS 版本QuickBlue 选它不只是为了“新”。最直接的收益是虚拟线程。微服务底座里大量操作是 IO 密集型的——调下游服务、查数据库、读 Redis、调模型推理接口。传统线程池模型下一个请求占一个线程线程池大小直接决定了并发上限调大了内存扛不住调小了吞吐上不去。虚拟线程把这个矛盾解开了你可以用同步的写法拿到接近异步的吞吐。实测数据上在一个典型的“网关转发 下游调用 缓存查询”链路里把 Tomcat 线程池换成虚拟线程后同样的硬件配置下 QPS 大概能提升 30% 到 50%而且 P99 延迟更稳定。当然虚拟线程不是银弹遇到 synchronized 块或者本地计算密集的场景它反而可能因为载体线程切换带来额外开销。QuickBlue 的做法是IO 密集的接入层和业务编排层用虚拟线程计算密集的模块保持平台线程池按场景区分。另一个收益是Record Patterns 和 Pattern Matching。底座里有很多“解析消息类型然后分发处理”的逻辑以前要写一堆 instanceof 判断加强制转换现在用模式匹配几行就搞定代码可读性提升明显。还有Sequenced Collections处理有序集合的时候不用再纠结用 List 还是 Deque统一接口更清爽。2.3 微服务拆分拆到什么粒度才算合适这是被问得最多的问题。QuickBlue 的拆分原则是按能力边界拆不按技术分层拆。什么意思很多团队拆微服务是按“controller 一个服务、service 一个服务、dao 一个服务”这么拆的结果一个业务请求要跨三个服务网络开销巨大事务也没法保证。正确的做法是按业务能力拆用户中心、订单中心、AI 推理中心、知识库中心、消息中心每个中心内部自己管自己的数据和技术实现。具体到 AI 应用底座我建议的拆分粒度是这样的网关服务统一入口负责鉴权、路由、限流、日志埋点不承载业务逻辑认证授权服务Token 签发校验、权限模型、租户隔离AI 编排服务Prompt 组装、模型路由、结果后处理是 AI 能力的统一出口模型接入服务对接不同模型提供方做协议适配和 Token 计量知识库服务向量存储、检索、文档解析、切片管理业务微服务各业务线自己的服务通过底座调用 AI 能力基础支撑服务文件、消息、定时任务、字典等通用能力拆到这个粒度好处是每个服务的职责清晰团队可以并行开发。坏处是服务数量上去了运维复杂度增加。QuickBlue 的应对方式是提供统一的部署模板和监控看板把运维成本摊薄。注意微服务拆分不是越细越好。我见过一个团队把用户服务拆成了“用户查询服务”和“用户写入服务”结果每次用户信息变更都要跨服务同步最后不得不引入分布式事务复杂度暴涨。拆分的判断标准是这个模块是否有独立的生命周期、独立的数据、独立的团队负责。三个都满足才拆否则先放在一起。2.4 AI 能力为什么要做成底座的一部分传统做法里AI 能力是外挂的。业务系统要调模型自己写 HTTP 客户端自己处理重试和超时自己记录 Token 消耗。问题是当公司里有二十个业务系统都要调模型的时候这二十份代码各写各的模型换了要改二十个地方密钥管理散落各处成本统计根本对不上。QuickBlue 把 AI 能力收进底座业务方通过统一的 SDK 或者内部网关调用。这样做有几个直接好处模型切换对业务透明底座改配置就行Token 计量和成本分摊在底座统一做Prompt 版本管理集中化避免各业务方各写各的推理服务的限流降级由底座统一控制防止某个业务把模型打挂影响所有人。3. 核心模块拆解与关键实现细节3.1 网关层不只是转发更是治理入口Spring Cloud Gateway 在 QuickBlue 里承担的角色远不止反向代理。它是整个底座的策略执行点。所有请求进来先过网关网关做这几件事第一是鉴权。解析 Token校验签名和有效期把用户身份和租户信息塞进请求头往下传。这里有个细节Token 校验不要每次都查数据库用 Redis 缓存校验结果设置合理的过期时间。QuickBlue 用的是“本地缓存 Redis 二级缓存”的结构热点 Token 在本地缓存命中减少 Redis 压力。第二是限流。基于 Sentinel 做规则从 Nacos 动态拉取。限流的维度可以按接口、按用户、按租户、按 IP。这里的关键是限流规则的粒度要合理——太粗了起不到保护作用太细了规则数量爆炸。我的经验是按“接口 租户”两个维度做既能防止单个租户刷爆接口又不会让规则数量失控。第三是路由。根据请求路径和请求头把请求转发到对应的后端服务。AI 相关的请求会路由到 AI 编排服务普通业务请求路由到对应业务服务。路由规则同样支持动态更新新增服务不用重启网关。第四是日志埋点。每个请求生成一个 TraceId贯穿整个调用链路。这个 TraceId 会通过请求头传递到下游所有服务最后在日志系统和链路追踪系统里可以串起来看。排查线上问题的时候一个 TraceId 就能把整条链路的所有日志捞出来效率提升非常明显。# 网关路由配置示例 spring: cloud: gateway: routes: - id: ai-orchestration uri: lb://ai-orchestration-service predicates: - Path/api/ai/** filters: - StripPrefix2 - name: RequestRateLimiter args: redis-rate-limiter.replenishRate: 100 redis-rate-limiter.burstCapacity: 2003.2 AI 编排服务Prompt 组装与模型路由的核心这是 QuickBlue 区别于普通微服务底座的关键模块。AI 编排服务要做的事情是把业务方的“意图”翻译成模型能理解的“请求”再把模型的“响应”翻译回业务方能用的“结果”。具体流程是这样的业务方调用时传入一个场景标识和参数编排服务根据场景标识找到对应的 Prompt 模板把参数填充进去然后根据路由规则选择模型发起调用拿到结果后做后处理比如 JSON 解析、格式校验、敏感词过滤最后返回给业务方。Prompt 模板管理是这里的重点。QuickBlue 把 Prompt 存在数据库里支持版本管理和灰度发布。每个模板有版本号业务方可以指定用哪个版本也可以不指定走最新稳定版。灰度发布的时候可以按租户或者按流量比例把请求导到新版本 Prompt观察效果后再全量。模型路由的规则设计也有讲究。不是简单地“哪个模型便宜用哪个”而是要综合考虑任务类型分类任务用小模型生成任务用大模型、响应时间要求实时交互用快模型离线批处理可以用慢模型、成本预算每个租户有 Token 配额、可用性主模型挂了自动切备用模型。QuickBlue 的路由规则用配置化的方式管理支持按优先级和权重组合。// 模型路由的核心逻辑示意 public ModelRoute decideRoute(AiRequest request) { // 1. 按场景查候选模型列表 ListModelCandidate candidates routeConfig.getCandidates(request.getScene()); // 2. 过滤掉不可用的模型 candidates candidates.stream() .filter(c - healthChecker.isHealthy(c.getModelId())) .filter(c - quotaManager.hasQuota(request.getTenantId(), c)) .collect(Collectors.toList()); // 3. 按权重选择 return weightedSelector.select(candidates); }3.3 数据通信层微服务之间的“高速公路”微服务拆开之后服务之间的通信就成了大问题。QuickBlue 在数据通信层做了几件事来保证可靠性和性能。首先是通信协议的选择。同步调用用 HTTP/REST简单通用调试方便。异步通信用消息队列解耦生产者和消费者。QuickBlue 默认集成 RocketMQ因为它在事务消息和顺序消息上支持比较好适合订单、支付这类场景。如果是纯事件驱动的场景Kafka 也是可选项。其次是序列化。默认用 JSON可读性好排查问题方便。但对性能敏感的内部调用可以切换到 Protobuf 或者 Avro序列化后的体积能小 60% 以上网络传输开销明显降低。QuickBlue 的做法是网关层和对外接口用 JSON内部服务间调用按需选择。第三是重试与幂等。网络调用失败是常态重试是必须的但重试必须配合幂等。QuickBlue 提供了幂等注解业务方在方法上标注一下底座自动根据请求中的业务唯一键做去重。重试策略也是配置化的最大重试次数、重试间隔、退避算法都可以调。实操心得重试次数不要设太多一般 2 到 3 次就够了。我见过设了 10 次重试的配置结果下游服务已经过载了上游还在疯狂重试直接把下游打挂。重试要配合熔断连续失败达到阈值就断开给下游恢复的时间。3.4 缓存与 Redis 集群的落地要点QuickBlue 里 Redis 承担了缓存、分布式锁、限流计数器、会话存储等多个角色。生产环境建议直接用 Redis Cluster至少 3 主 3 从保证高可用。缓存使用的核心原则是缓存穿透、缓存击穿、缓存雪崩三防。缓存穿透是指查一个不存在的数据请求直接打到数据库。解决办法是缓存空值设置较短的过期时间。缓存击穿是指热点 Key 过期瞬间大量请求打到数据库解决办法是用分布式锁保证只有一个请求去加载数据其他请求等待。缓存雪崩是指大量 Key 同时过期解决办法是过期时间加随机值避免同时失效。// 缓存穿透防护示例 public User getUser(Long userId) { String key user: userId; String cached redis.get(key); if (cached ! null) { return JSON.parseObject(cached, User.class); } // 加分布式锁防止缓存击穿 String lockKey lock:user: userId; try { boolean locked redis.tryLock(lockKey, 3, TimeUnit.SECONDS); if (locked) { User user userDao.selectById(userId); if (user null) { // 缓存空值防止穿透 redis.setex(key, 60, NULL); return null; } redis.setex(key, 3600 random.nextInt(600), JSON.toJSONString(user)); return user; } else { Thread.sleep(50); return getUser(userId); } } finally { redis.unlock(lockKey); } }3.5 Sentinel 规则持久化到 NacosSentinel 默认的规则是存在内存里的应用重启就没了。生产环境必须做持久化。QuickBlue 的方案是把规则存到 Nacos 配置中心Sentinel 通过 datasource 从 Nacos 拉取规则Nacos 配置变更时 Sentinel 自动刷新。这个集成的关键点在于配置格式要对齐。Sentinel 的 Nacos datasource 支持 JSON 和 XML 两种格式推荐用 JSON结构清晰。配置的 dataId 和 groupId 要和代码里配置的一致否则拉不到规则。# Sentinel Nacos 数据源配置 spring: cloud: sentinel: datasource: flow: nacos: server-addr: ${nacos.address} >spring: application: name: quickblue-gateway cloud: nacos: discovery: server-addr: 127.0.0.1:8848 namespace: quickblue-dev group: DEFAULT_GROUP config: server-addr: 127.0.0.1:8848 namespace: quickblue-dev group: DEFAULT_GROUP file-extension: yaml命名空间用来隔离环境开发、测试、生产各用一个避免配置串环境。分组用来隔离项目如果公司有多个项目共用一套 Nacos分组就很有必要。注意Nacos 的命名空间 ID 和名称是两个概念。控制台上创建命名空间时会生成一个 UUID 作为 ID配置里要填的是这个 ID 而不是名称。这个坑我踩过配置里填了名称结果一直连不上排查了半天。4.4 网关鉴权过滤器的实现网关鉴权的核心是一个 GlobalFilter在请求转发之前做校验。实现要点从请求头拿 Token校验 Token 有效性签名、过期时间解析出用户信息和租户信息把信息塞进请求头传给下游校验失败直接返回 401Component public class AuthGlobalFilter implements GlobalFilter, Ordered { Override public MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain) { String token exchange.getRequest().getHeaders().getFirst(Authorization); if (token null || !token.startsWith(Bearer )) { return unauthorized(exchange, 缺少认证信息); } try { Claims claims jwtUtil.parseToken(token.substring(7)); ServerHttpRequest mutated exchange.getRequest().mutate() .header(X-User-Id, claims.getSubject()) .header(X-Tenant-Id, claims.get(tenantId, String.class)) .build(); return chain.filter(exchange.mutate().request(mutated).build()); } catch (Exception e) { return unauthorized(exchange, 认证失败); } } Override public int getOrder() { return -100; // 优先级最高最先执行 } }白名单接口登录、注册、健康检查要放行这个在过滤器里判断路径前缀即可。白名单配置放 Nacos支持动态调整不用重启网关。4.5 AI 编排服务的 Prompt 模板管理Prompt 模板存 MySQL表结构大概是这样CREATE TABLE prompt_template ( id BIGINT PRIMARY KEY AUTO_INCREMENT, scene_code VARCHAR(64) NOT NULL COMMENT 场景编码, version VARCHAR(16) NOT NULL COMMENT 版本号, template_content TEXT NOT NULL COMMENT 模板内容, model_config JSON COMMENT 模型参数配置, status TINYINT DEFAULT 0 COMMENT 0-草稿 1-灰度 2-稳定, gray_ratio INT DEFAULT 0 COMMENT 灰度比例 0-100, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, UNIQUE KEY uk_scene_version (scene_code, version) );模板内容里用占位符表示变量比如{{question}}、{{context}}。渲染的时候用简单的字符串替换或者模板引擎Freemarker、Velocity 都行。模型参数配置存 JSON包括 temperature、max_tokens、top_p 这些。灰度发布的逻辑请求进来先查场景的稳定版本如果存在灰度版本且随机数落在灰度比例内就用灰度版本否则用稳定版本。灰度期间要记录两个版本的输出质量指标方便对比决策。4.6 模型接入服务的适配层设计不同模型提供方的接口协议不一样有的用 OpenAI 兼容格式有的用自己的私有格式。QuickBlue 在模型接入服务里做了一层适配对外暴露统一的接口对内根据模型类型路由到不同的适配器。public interface ModelAdapter { ModelResponse invoke(ModelRequest request); String getProvider(); } Component public class OpenAiCompatibleAdapter implements ModelAdapter { Override public ModelResponse invoke(ModelRequest request) { // 转换成 OpenAI 格式发起 HTTP 调用 // 解析响应转换成统一的 ModelResponse } Override public String getProvider() { return openai-compatible; } }新增模型提供方的时候只需要实现一个新的 Adapter注册到工厂里不用改上层代码。这就是适配器模式的价值——把变化点隔离在一个地方。4.7 链路追踪与日志规范链路追踪用 Micrometer Tracing 加 Zipkin。每个请求生成 TraceId 和 SpanId通过 HTTP 头在服务间传递。日志格式里带上 TraceId这样在日志系统里搜索一个 TraceId 就能看到整条链路。日志规范要统一ERROR 级别记录异常堆栈WARN 级别记录业务异常INFO 级别记录关键流程节点DEBUG 级别记录详细参数生产环境关闭。日志里不要打印敏感信息比如密码、Token、身份证号这些要做脱敏处理。// 日志脱敏示例 public static String maskPhone(String phone) { if (phone null || phone.length() 11) return phone; return phone.substring(0, 3) **** phone.substring(7); }5. 常见问题排查与避坑经验实录5.1 服务注册不上或注册后调不通这是接入 Nacos 后最常见的问题。排查思路按这个顺序走现象可能原因排查方法服务列表里看不到命名空间或分组配错检查配置里的 namespace 和 group服务能看到但调不通网络不通或端口不对telnet 目标 IP 端口偶尔调不通健康检查失败看 Nacos 控制台实例健康状态调用超时负载均衡选到了慢实例检查各实例的响应时间有个隐蔽的坑是多网卡环境。服务器有多张网卡时Nacos 可能注册了错误的 IP。解决办法是在配置里指定spring.cloud.nacos.discovery.ip和port强制用正确的地址注册。5.2 Sentinel 规则不生效规则不生效通常有三个原因规则没推送到 Nacos、datasource 配置不对、规则格式错误。排查的时候先看 Nacos 里有没有对应的配置文件再看应用启动日志里有没有拉取规则的记录最后检查规则 JSON 的字段名和 Sentinel 要求的对不对。实操心得Sentinel 的规则 JSON 字段名很容易写错比如 flow 规则的count写成thresholddegrade 规则的grade值写错。建议直接从 Sentinel 控制台导出规则 JSON改改数值再用避免手写出错。5.3 Redis 集群连接超时Redis Cluster 连接超时常见原因是集群拓扑变化后客户端没刷新。Lettuce 客户端默认会定期刷新拓扑但如果网络抖动导致刷新失败就可能一直连旧节点。解决办法是配置合理的刷新周期和重连策略同时监控连接池的活跃连接数异常时告警。另一个坑是大 Key 和热 Key。大 Key 会导致单次操作耗时过长热 Key 会导致单个节点压力过大。排查大 Key 用redis-cli --bigkeys排查热 Key 用监控工具或者自己埋点统计。发现之后要么拆分要么加本地缓存。5.4 虚拟线程下的 ThreadLocal 问题JDK 21 的虚拟线程对 ThreadLocal 的支持和平台线程不一样。虚拟线程数量可能非常多如果每个线程都存一份 ThreadLocal 数据内存会爆。QuickBlue 的做法是能用请求上下文传递的就用上下文必须用 ThreadLocal 的场景改用 ScopedValueJDK 21 预览特性或者显式传递参数。还有一个坑是 synchronized 块。虚拟线程在 synchronized 块里会被 pin 住无法释放载体线程导致吞吐下降。排查方法是启动时加-Djdk.tracePinnedThreadsfull日志里会打印被 pin 住的堆栈然后针对性改成 ReentrantLock。5.5 分布式事务的边界控制Seata 的 AT 模式虽然对业务侵入小但也不是万能的。它依赖数据库的本地事务和全局锁在高并发场景下全局锁会成为瓶颈。QuickBlue 的原则是能不用分布式事务就不用。具体做法是尽量把相关操作放在同一个服务内用本地事务保证跨服务操作尽量设计成最终一致用消息队列做补偿实在需要强一致的场景才用 Seata并且控制事务范围不要跨太多服务我见过一个项目在订单创建链路里用了 Seata结果大促时全局锁竞争严重TPS 上不去。后来改成“订单落库 发消息 下游异步处理”的最终一致方案性能提升了十几倍。5.6 模型调用的超时与重试策略AI 模型调用和普通接口调用不一样它的响应时间波动很大。同一个 Prompt有时候 2 秒返回有时候 20 秒。超时设置太短会误杀正常请求太长会拖垮上游。QuickBlue 的策略是分级超时普通对话场景 30 秒复杂推理场景 120 秒批处理场景不设超时但限制并发数。重试策略上模型调用失败一般不自动重试因为重试可能产生重复计费而且模型服务过载时重试会加剧问题。失败后返回明确的错误码由业务方决定是否重试。6. 底座后续可扩展的方向QuickBlue 这套底座搭起来之后扩展点其实很多。我目前看到比较有价值的方向有几个。一个是多模态能力的接入。现在底座主要处理文本但业务场景里图片、音频、视频的需求越来越多。扩展的方式是在模型接入服务里增加多模态适配器在编排服务里增加多模态的 Prompt 模板类型。存储层要支持大文件的存储和检索向量库要支持多模态向量。另一个是Agent 编排能力。现在的 AI 调用基本是单轮的业务方传参数、拿结果。但很多场景需要多步推理、工具调用、循环决策。底座可以增加 Agent 编排模块支持定义工作流让模型按步骤执行中间可以调用外部工具。这个方向技术上可行但工程复杂度不低需要仔细设计状态管理和错误恢复机制。还有一个是成本治理。现在 Token 计量做了但成本分析还比较粗。可以细化到按场景、按租户、按模型、按时间段做成本报表设置预算告警超预算自动降级到便宜模型。这个对企业的 AI 预算管理很有价值尤其是当 AI 调用量上来之后成本会变成一笔不小的开支。我在实际搭建这类底座的过程中最大的体会是底座的价值不在于功能多而在于稳定和透明。业务方用你的底座最怕的是出了问题不知道找谁、不知道哪里出了错。所以可观测性要做得足够好日志、指标、链路追踪三件套必须齐全而且要好用。另外就是文档和示例要跟上业务方接入的时候能照着抄比什么都强。