QuickBlue 微服务架构评估报告 v8.0

评估版本: QuickBlue v4.0.0 (PostgreSQL 版)
评估工具: Qoder 架构分析引擎
评估日期: 2026-06-26
评估角色: 专家团架构师(含架构设计师、安全专家、DBA、DevOps 专家、前端架构师)
上一版本: v7.0 (2026-05-17)

版本更新说明 (v7.0 → v8.0)

重大变更

一、架构全景概览

1.1 系统架构拓扑

┌─────────────────────────────────────────────────────────────────────┐
│                        前端层 (Vue 3 + Ant Design Vue)              │
│                       QuickBule-admin-webpg                        │
│                  Vite 5.2 + Pinia + Vue Router 4                   │
└───────────────────────────┬─────────────────────────────────────────┘
                            │ HTTP / WebSocket
┌───────────────────────────▼─────────────────────────────────────────┐
│              API 网关层  (Spring Cloud Gateway)                     │
│              QuickBlue-gateway   :8080                              │
│   ┌─────────────┬──────────────┬──────────────┬──────────────┐     │
│   │ AuthFilter  │ GlobalLog    │ RequestHeader│ OpenApiFilter│     │
│   │ + Redis验证 │ + 慢请求告警 │ + 链路追踪   │ + API聚合    │     │
│   └─────────────┴──────────────┴──────────────┴──────────────┘     │
└──┬───────────┬──────────────┬──────────────┬───────────────────────┘
   │           │              │              │
   ▼           ▼              ▼              ▼
┌──────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
│System│  │ Business  │  │ Support  │  │   AI     │  │  Admin   │
│:8081 │  │  :8082    │  │  :8083   │  │  :8084   │  │  :9090   │
│ 系统 │  │  业务     │  │  支撑    │  │  智能    │  │  监控    │
│ 管理 │  │  管理     │  │  服务    │  │  服务    │  │  中心    │
└──┬───┘  └────┬─────┘  └────┬─────┘  └────┬─────┘  └──────────┘
   │           │              │              │
   │    ┌──────┼──────────────┼──────────────┤
   │    │      │    雪花算法统一主键生成       │
   │    │   IdType.ASSIGN_ID (MyBatis-Plus)  │
   │    └──────┼──────────────────────────────┘
   ▼           ▼              ▼              ▼
┌──────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
│  DB  │  │   DB     │  │   DB     │  │ DB+Vector│
│system│  │ business │  │ support  │  │   ai     │
│PG18.3│  │ PG18.3   │  │ PG18.3   │  │PG18.3+pgv│
└──────┘  └──────────┘  └──────────┘  └──────────┘
                ↕ (OpenFeign + OkHttp)
┌─────────────────────────────────────────────────────────────────────┐
│  基础设施层: Nacos 2.4.3 | Redis/Redisson | Sentinel | SBA | Zipkin│
└─────────────────────────────────────────────────────────────────────┘

1.2 模块矩阵

二、核心评估维度

2.1 服务独立性评估

评分: 8.0 / 10 ⭐⭐⭐⭐ (v7.0: 8.0 → 持平)

2.1.1 优势

2.1.2 风险与不足

2.1.3 改进建议

1. 按需引入 common 模块: business 服务不需要 excel，应移除

2. 拆分 common-core: 将 web/mybatis-plus/sa-token 分离为独立 starter

3. 引入独立版本号: 各服务模块可独立定义 version，通过 BOM 管理兼容性

4. 本地缓存降级: Nacos 配置本地快照，Redis 不可用时使用 Caffeine 降级

5. 自定义 IdentifierGenerator: 为各服务配置不同的 workerId/datacenterId，避免分布式雪花 ID 冲突（当前 MyBatis-Plus 默认使用 MAC 地址 + PID，多实例同机部署可能碰撞）

2.2 耦合度评估

评分: 7.5 / 10 ⭐⭐⭐⭐ (v7.0: 7.5 → 持平)

2.2.1 服务间通信拓扑

xxxxxxxxxx
                    ┌──────────────┐
           ┌───────▶│ api-system   │◀──── system 自身实现
           │        │ 6 FeignClient│       (LoginFeign, DeptFeign,
           │        └──────────────┘        EmployeeFeign, MenuFeign,
           │                                RoleFeign, OperateLogFeign)
           │
  ┌────────┼────────┐
  │ system │business │ support      ai
  │        │        │
  │        │   ┌────▼──────────┐
  │        ├──▶│ api-support   │◀──── support 自身实现
  │        │   │ 9 FeignClient │       (FileStorage, Captcha,
  │        │   └───────────────┘        LoginLog, OperateLog,
  │        │                            QRCode, Message, ApiEncrypt,
  │        │                            Level3ProtectConfig)
  │        │
  │        ├──▶ api-business (2 FeignClient)
  │        │
  └────────┼──▶ api-ai (3 FeignClient: AiApp, AiKnowledge, AiModel)
           │
           └──▶ system → api-support (跨服务调用)
               business → api-system + api-support (跨服务调用)
               ai → api-system (跨服务调用)

2.2.2 耦合分析

2.2.3 common 模块依赖关系

xxxxxxxxxx
common-core ◀──── 所有模块的基础
    ▲
    │
common-web ◀──── common-redis (redis 依赖 web 的 RepeatSubmit)
    ▲
    │
common-security ──▶ common-redis
    ▲
    │
common-database ──▶ common-core
common-swagger  ──▶ common-core
common-log      ──  独立
common-excel    ──  独立

核心问题: common-redis 反向依赖 common-web(为了防重复提交功能)，造成层次混乱。Redis 应为底层基础设施，不应依赖 Web 层。

2.2.4 改进建议

1. 全面补齐 Feign Fallback: 为所有 19 个 FeignClient 提供降级实现，避免级联故障

2. 解耦 redis→web 依赖: 将防重复提交抽象接口移至 core 或独立模块

3. 引入事件驱动: 日志记录、消息通知等场景用 RocketMQ 异步解耦(BOM 已声明但未使用)

4. DTO 版本兼容: 使用 @JsonIgnoreProperties(ignoreUnknown = true) 增强前后兼容性

2.3 数据隔离评估

评分: 9.5 / 10 ⭐⭐⭐⭐⭐ (v7.0: 9.0 → +0.5)

2.3.1 数据库隔离策略

2.3.2 隔离评估

2.3.3 主键策略统一详情 (核心改造)

xxxxxxxxxx
v7.0 混合策略                     v8.0 统一策略
┌────────────────────┐           ┌────────────────────┐
│ System: BIGSERIAL   │           │ System: BIGINT      │
│ Business: BIGSERIAL │           │ Business: BIGINT    │
│ Support: BIGSERIAL  │  ──────▶  │ Support: BIGINT     │
│ AI: VARCHAR(36)     │           │ AI: BIGINT          │
│   (UUID/ASSIGN_ID)  │           │    (ASSIGN_ID)      │
│ Region: VARCHAR(32) │           │ Region: BIGINT      │
└────────────────────┘           └────────────────────┘
       混合                        统一雪花算法
  (自增+UUID+手动)              (IdType.ASSIGN_ID)

2.3.4 表设计规范分析

2.3.5 改进建议

1. 生产环境每库独立账号: 限制最小权限，杜绝跨库操作

2. 密码加密存储: Nacos 配置启用 Jasypt 加密或 Vault 密钥管理

3. 统一表命名规范: 建议 qb_模块_表名 格式(如 qb_sys_employee，qb_ai_app)

4. 自定义雪花 workerId: 为每个服务实例配置独立的 workerId/datacenterId，防止多实例同机部署时 ID 碰撞

2.4 扩展性评估

评分: 8.5 / 10 ⭐⭐⭐⭐ (v7.0: 8.5 → 持平)

2.4.1 水平扩展能力

2.4.2 垂直扩展能力

2.4.3 弹性治理能力

2.4.4 改进建议

1. 落地 Sentinel 规则: 为核心接口配置限流/降级规则，通过 Nacos 持久化

2. RocketMQ 异步化: 日志写入、文件处理、AI知识库索引等场景异步化

3. 容器化就绪: 🔴 高优先级 — 添加 Dockerfile 和 docker-compose.yml，为 K8s 部署做准备

4. Seata 分布式事务: 跨服务数据一致性场景引入 Seata AT 模式

5. 自定义雪花 WorkerId: 在 MybatisPlusConfig 中注入自定义 IdentifierGenerator，为每个服务实例分配唯一 workerId

2.5 可维护性评估

评分: 9.0 / 10 ⭐⭐⭐⭐⭐ (v7.0: 8.5 → +0.5)

2.5.1 代码组织

2.5.2 配置管理

2.5.3 监控可观测性

2.5.4 安全合规

2.5.5 改进建议

1. 多环境配置: 补全 test/staging/prod 环境的 Nacos 命名空间和配置

2. 敏感信息外置: 使用环境变量或 Vault 管理密码，从代码仓库中移除明文密码

3. 生产环境恢复 WallFilter: dev 环境为 Flyway 兼容临时禁用，prod 务必开启 wall 过滤器

4. 完善网关白名单: 定期审查 AuthenticationFilter 白名单，避免过度放行

5. AI 实体风格统一: AiragAgent、AiragFlow、AiragTool 缺少 @Schema、@Accessors(chain = true) 等注解，与其他 AI 实体风格不一致

2.6 技术栈先进性评估

评分: 9.5 / 10 ⭐⭐⭐⭐⭐ (v7.0: 9.5 → 持平)

2.6.1 核心技术栈版本矩阵

2.6.2 技术选型评价

2.6.3 技术风险

三、架构评分总结

3.1 雷达图评分

xxxxxxxxxx
                    技术栈先进性
                       9.5
                        │
              ┌─────────┼─────────┐
              │         │         │
   可维护性 9.0 ────────┼──────── 9.5 数据隔离
              │         │         │
              │         │         │
              └─────────┼─────────┘
                        │
    耦合度 7.5 ─────────┼───────── 8.5 扩展性
                        │
                   服务独立性
                      8.0

3.2 综合评分

3.3 架构成熟度定级

当前等级: L4 — 可管理级 (v7.0: L4 可管理级 → 维持)

维持 L4 说明:

• ✅ 数据治理增强: 主键策略从 3 种混合统一为雪花算法，数据规范性和分布式友好度大幅提升

• ✅ Flyway 迁移成熟: V6-V9 迁移脚本设计规范，包含变更说明、回滚路径、配套 Java 变更提醒

• ✅ 可维护性提升: 消除了主键策略不一致带来的维护负担

• ⚠️ 熔断降级仍未落地: Sentinel 规则未配置，Feign Fallback 缺失从 16 个增加到 19 个

• ⚠️ 分布式事务未引入: Seata 声明但未使用

• ⚠️ 容器化完全缺失: 项目中无任何 Docker/K8s 相关文件

四、专家团优先改进路线图

4.1 紧急修复 (P0 — 立即执行)

4.2 短期优化 (P1 — 1-2 月)

4.3 中期增强 (P2 — 3-6 月)

4.4 长期演进 (P3 — 6-12 月)

五、架构亮点与总结

5.1 核心亮点

1. 技术栈极度前沿: Java 21 + Spring Boot 3.5 + Spring Cloud 2025.0 + Spring Cloud Alibaba 2025.0，处于 Java 微服务技术栈的最前沿

2. AI 能力内建: LangChain4j + pgvector + LiteFlow 流程引擎，将 AI/RAG 能力作为微服务原生能力内建，架构前瞻性极强

3. 数据库选型正确: PostgreSQL 18.3 + pgvector 一体化方案，既满足关系型数据需求，又原生支持向量检索，减少运维复杂度

4. 安全合规齐全: 三级等保配置模块化、Argon2id 密码哈希、SM4 国密支持、数据权限多级控制、网关 Redis Token 验证

5. 主键策略统一: 🆕 全模块统一雪花算法(BIGINT + ASSIGN_ID)，消除 v7.0 存在的 BIGSERIAL/UUID/手动输入 3 种混合策略，分布式友好度大幅提升

6. Flyway 迁移规范: 🆕 V6-V9 迁移脚本设计规范，包含详细的变更说明、配套 Java 变更提醒和回滚指导

7. API 文档一体化: Knife4j + SpringDoc 网关聚合，开发体验友好

8. 多级缓存设计: Caffeine(L1) + Redis(L2) + Redisson(分布式锁)，缓存架构成熟

9. OpenFeign + OkHttp 高性能通信: 连接池复用、GZIP 压缩、细粒度超时控制

10. 分布式链路追踪: Micrometer Tracing + Brave + Zipkin，完整的可观测性方案

5.2 与 v7.0 对比总结

5.3 总体评价

QuickBlue v4.0.0 从 v7.0 到 v8.0 的核心演进是 主键策略的统一——这是一次贯穿所有模块的数据库级基础架构重构。团队通过 4 个精心设计的 Flyway 迁移脚本(V6-V9)，成功将 System/Business/Support/AI 四个模块从 BIGSERIAL 自增和 VARCHAR(36) UUID 的混合策略统一为雪花算法 BIGINT，消除了长期存在的分布式 ID 不一致问题。

此次改造的工程亮点包括:

• 全局配置驱动: id-type: assign_id 使新模块自动继承雪花策略

• 迁移文档完善: V6-V9 每个脚本都包含变更说明、配套 Java 变更提醒和回滚指导

• 序列彻底移除: 不再依赖 PostgreSQL SEQUENCE，ID 生成完全由应用层控制

当前综合评分从 8.44 微升至 8.58，架构成熟度维持 L4 可管理级。主要改进空间集中在:

• 🔴 立即修复: AI/Region 实体 String→Long 类型适配(运行时报错风险)

• 🔴 立即修复: 自定义雪花 WorkerId 防止多实例碰撞

• 🟠 短期目标: 补齐 19 个 Feign Fallback、落地 Sentinel 规则、容器化改造

• 🟡 中期目标: RocketMQ 异步化、多环境配置、密码加密

在完成 P0 紧急修复和 P1 短期优化后，该架构可稳固 L4 可管理级，并向 L5 优化级迈进，具备支撑大规模生产部署的能力。

六、附录

6.1 评估范围

本报告基于以下代码和配置全量分析生成:

• ✅ POM 依赖树(父 POM + 5 个一级子模块 + 12 个二级子模块)

• ✅ 源码结构(8 个 common 模块 + 4 个 api 模块 + 4 个业务模块 + 网关 + 监控)

• ✅ 数据库 DDL(database/postgresql + Flyway 迁移脚本 V1~V9)

• ✅ Nacos 配置(5 个共享配置 + 6 个服务私有配置)

• ✅ 网关过滤器链(5 个 GlobalFilter)

• ✅ API 通信拓扑(20 个 FeignClient)

• ✅ 前端技术栈(Vue 3.4 + Ant Design Vue 4.2 + Vite 5.2)

• ✅ 技术文档(开发手册、安全指南、链路追踪指南等)

• ✅ 🆕 雪花算法迁移(V6-V9 共 4 个 Flyway 迁移 + 38+ 实体类改造)

• ✅ 🆕 代码生成模板更新

6.2 v8.0 新增评估维度

6.3 参考资料

• Spring Boot 3.5 官方文档

• Spring Cloud 2025.0 官方文档

• MyBatis-Plus 雪花算法

• Micrometer Tracing 官方文档

• Flyway 官方文档

• Sa-Token 官方文档

• LangChain4j 官方文档

• PostgreSQL 18 官方文档

v8.0 核心变更: 全模块主键策略统一为雪花算法(IdType.ASSIGN_ID)，通过 V6-V9 Flyway 迁移实现 BIGSERIAL→BIGINT、VARCHAR(36)→BIGINT 的数据库级重构。

下次评估建议: 在完成 P0 紧急修复和 P1 阶段改进后(预计 2026-08)，进行 v9.0 评估，重点关注 AI/Region 实体类型适配完成度、Feign Fallback 覆盖率、容器化改造进展、Sentinel 规则落地情况。