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

评估版本: QuickBlue v4.0.0 (PostgreSQL 版) 评估对象: QuickBlue-MicroAI-pg（后端 27 个 Maven 模块）+ QuickBlue-MicroAI-webpg（前端） 评估工具: 全量代码仓库扫描 + 静态分析 + 配置审计 评估日期: 2026-10-01 评估维度: 服务独立性、耦合度、数据隔离、扩展性、可维护性、技术栈先进性 评估角色: 专家团架构师(含架构设计师、安全专家、DBA、DevOps 专家、前端架构师) 基准环境（本项目根 pom 实测）: Spring Boot 4.1.1 · Spring Cloud 2025.1.3 · Spring Cloud Alibaba 2025.1.0.0 · PostgreSQL 18 · JDK 21 历史版本总结: 见 QuickBlue微服务架构评估报告_v3.0.md

一、架构全景概览

1.1 系统架构拓扑

​x
┌─────────────────────────────────────────────────────────────────────┐
│                     前端层 (Vue 3 + Ant Design Vue 4)                │
│                     QuickBlue-MicroAI-webpg                          │
│        238 个 .vue + 162 个 ts/js  |  views 按域组织(support/system/ai)│
└───────────────────────────┬─────────────────────────────────────────┘
                            │ HTTP / SSE
┌───────────────────────────▼─────────────────────────────────────────┐
│              API 网关层  (Spring Cloud Gateway + WebFlux)            │
│              QuickBlue-gateway   :8080                              │
│   ┌─────────────┬──────────────┬──────────────┬──────────────┐     │
│   │ 鉴权过滤器   │ 全局日志      │ 跨域配置      │ Sentinel 限流 │     │
│   │ Sa-Token    │ 请求/响应     │ 环境变量注入  │ + 规则持久化  │     │
│   │ + Redis     │ + 慢请求      │              │              │     │
│   └─────────────┴──────────────┴──────────────┴──────────────┘     │
└──┬───────────┬──────────────┬──────────────┬───────────────┬────────┘
   │           │              │              │               │
   ▼           ▼              ▼              ▼               ▼
┌──────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
│System│  │ Business │  │ Support  │  │   AI     │  │  Report  │
│:8086 │  │  :8082   │  │  :8083   │  │  :8084   │  │  :8085   │
│认证/ │  │ 通知/    │  │ 文件/字典│  │ 智能体/  │  │ 报表引擎 │
│组织/ │  │ 地区     │  │ 任务/模板│  │ RAG/合规 │  │ BI       │
│权限  │  │          │  │ 代码生成 │  │ /安全    │  │          │
└──┬───┘  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘
   │           │              │              │              │
   │    ┌──────┴──────────────┴──────────────┴──────────────┘
   │    │        统一主键策略：雪花算法 (BIGINT + ASSIGN_ID)
   │    │        SnowflakeIdentifierGenerator (common-database)
   │    └──────┬──────────────┬──────────────┬──────────────┐
   ▼           ▼              ▼              ▼              ▼
┌──────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
│  DB  │  │   DB     │  │   DB     │  │ DB+Vector│  │   DB     │
│system│  │ business │  │ support  │  │   ai     │  │ report   │
│ 21表 │  │   7表    │  │  33表    │  │ 23表+pgv │  │   5表    │
└──────┘  └──────────┘  └──────────┘  └──────────┘  └──────────┘
                        ↕ 服务间调用
        QuickBlue-api-* 契约层 (Spring 原生 @HttpExchange + RestClient
                              + LoadBalancer + Resilience4j 熔断)
┌─────────────────────────────────────────────────────────────────────┐
│  公共层: QuickBlue-common-*(8) │ QuickBlue-starter-*(2) │ QuickBlue-api-*(5) │
│  基础设施: Nacos 3.2.1 | Redis/Redisson 4.7.0 | Sentinel | SBA 4.1.2        │
│            Micrometer Tracing + Zipkin (默认关闭) │ pgvector                │
└─────────────────────────────────────────────────────────────────────┘

⚠️ 已知偏离：business 的 NoticeMapper.xml L79/L128 存在跨库 SQL
   （SELECT ... FROM QuickBlue_system.t_employee），绕过 api-system 契约

1.2 模块矩阵与 Java 源文件统计

1.3 核心技术栈版本矩阵

二、核心评估维度

2.1 服务独立性评估

评分: 8.0 / 10 ⭐⭐⭐⭐

2.1.1 优势

2.1.2 风险与不足

2.1.3 改进建议

1. 整改跨库 SQL：改经 api-system 调用；确实高频时在 system 侧提供专用接口

2. 代码生成器库清单配置化：从 Nacos 读取，避免硬编码

3. 生产环境按服务独立建库账号：限制最小权限，杜绝跨库操作

2.2 耦合度评估

评分: 7.5 / 10 ⭐⭐⭐⭐

2.2.1 服务间通信拓扑

xxxxxxxxxx
                    ┌──────────────┐
        ┌──────────▶│ api-system   │◀── system 自身实现
        │           │ 13 契约文件   │
        │           └──────────────┘
        │
  ┌─────┴─────┬──────────────┬──────────────┐
  │           │              │              │
┌──────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
│system│  │ business │  │ support  │  │   ai     │  │  report  │
└──┬───┘  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘
   │           │              │              │              │
   │  import 计数（api-* 契约）                │              │
   │  system  → api×9                          │              │
   │  business→ api×14                         │              │
   │  support → api×5                          │              │
   │  ai      → api×0                          │              │
   │  report  → api×2                          │              │
   │           │              │              │              │
   └───────────┴──────────────┴──────────────┴──────────────┘
              ⚠️ 例外：business 经 SQL 直连 system 库（见 2.1.2）

  common 模块依赖层次（L0 → L3）：
  L0: common-core ◀────────── 所有模块的基础（抽象层）
  L1: common-web ← 依赖 core      common-redis ← 仅依赖 core
      common-swagger / common-excel ← 依赖 core
  L2: common-database ← core + web      common-log ← core + web
  L3: common-security ← core + redis

2.2.2 耦合分析

2.2.3 设计评价

公共层依赖层次清晰（L0→L3 四级），且边界已被"可执行门禁"固化 —— 这是本框架最有价值的工程资产。 但 business 的跨库 SQL 破坏了这套架构唯一的强制承诺：它绕过 api-system 契约，使两个服务的库表结构无法独立演进。

2.3 数据隔离评估

评分: 6.0 / 10 ⭐⭐⭐

2.3.1 数据库隔离策略

2.3.2 隔离评估

2.3.3 改进建议

1. 整改跨库 SQL（P0）：改经 api-system；这是恢复"每服务一库"承诺的唯一方式

2. 统一迁移机制（P1）：Flyway 与手工脚本二选一并对齐；清除三个空的 db/migration 目录

3. 生产环境每库独立账号：限制最小权限，从机制上杜绝跨库操作

4. 补齐租户列：为不含租户的表补 tenant_id 并纳入隔离

2.4 扩展性评估

评分: 7.5 / 10 ⭐⭐⭐⭐

2.4.1 水平扩展能力

2.4.2 扩展点盘点（本框架的核心优势）

2.4.3 弹性治理与扩展短板

2.5 可维护性评估

评分: 5.5 / 10 ⭐⭐

2.5.1 代码组织与工程质量

2.5.2 测试覆盖分布（实测）

2.5.3 配置管理

2.5.4 安全合规

2.5.5 监控可观测性

2.6 技术栈先进性评估

评分: 9.0 / 10 ⭐⭐⭐⭐⭐

2.6.1 技术选型评价

2.6.2 技术风险

三、架构评分总结

3.1 雷达图评分

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

                 综合：加权 7.13 / 10   （均权 7.25 / 10）

3.2 综合评分

口径说明（重要）： ① 上表采用加权口径（与历史报告 v6.0/v9.0 一致：服务独立性 20% / 耦合度 20% / 数据隔离 15% / 扩展性 15% / 可维护性 20% / 技术栈 10%）。 ② 若采用六维度均权口径，综合得分为 7.25 / 10（72.5 / 100）。 ③ 两种口径差异仅 1.2 分，源于可维护性权重不同 —— 本文档显式给出权重与两种结果，避免"一个分数、多种算法"。

3.3 架构成熟度定级

当前等级: L4 — 可管理级（部分达成）

维持 L4 的判断依据

• ✅ 契约与边界已固化：模块间零直接依赖（实测 import 矩阵）+ 4 条架构门禁可执行（扫描 1235 文件）

• ✅ RPC 熔断与 Web 限流双机制在用：Resilience4j 2.4.0 + Sentinel

• ✅ 合规与安全双护栏成型：模型合规（按端点域名判定，覆盖含向量化的四条链路）+ 内容安全（双向 + 流式分段缓冲 + 证据表）

• ✅ 数据权限 fail-closed：未接 SPI 即全拒绝，且在框架层而非业务层实现

• ⚠️ 链路追踪集成但默认关闭

• ⚠️ 分布式事务未落地：Seata 声明未用

• 🔴 跨库 SQL 击穿数据隔离

• 🔴 测试覆盖率 1.3%，CI 缺失

• 🔴 明文凭据入库且默认 profile 为 dev

晋升 L5 的前置条件：① 接入 CI 让门禁成为强制关卡；② 整改跨库 SQL 与凭据；③ 测试覆盖率提升至 30%+；④ 可观测常态化（追踪默认开启 + 告警）。

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

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

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

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

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

五、架构亮点与总结

5.1 核心亮点

1. 模块边界真实成立：五个业务模块互相零直接依赖（全量 import 矩阵实测），全部经 api-* 契约；api 与 modules 5:5 对齐

2. 架构边界可执行：arch-check.ps1 把 4 条边界做成"非零退出即失败"，扫描 1235 个文件（含"框架不得含行业语义"）

3. 数据权限 fail-closed + SPI 化：平台定接口、业务各自实现、DenyAll 兜底 —— 未接 SPI 即全拒绝，不静默越权

4. 合规与安全双护栏：模型合规按 baseUrl 真实域名判定区域且覆盖含向量化的四条链路；内容安全输入输出双向 + 流式分段缓冲

5. 留痕纪律统一：日志 / 异常 / 证据表三处一致"绝不记原文"；证据表只存长度 + 不可逆摘要 + 规则版本指纹

6. 技术栈处于行业前列：Spring Boot 4.1.1 + Spring Cloud 2025.1.3 + Java 21 + 原生 @HttpExchange

7. 五服务五库隔离准确：每个服务 JDBC 零例外只连自己的库

8. 部署资产齐备：Dockerfile、docker-compose、build.sh、Sentinel 规则、部署脚本

9. AI 能力内建：AgentScope 2.0.2 + LangChain4j + pgvector，智能体/工具/RAG/流程/评审齐备

5.2 风险汇总（实测）

5.3 总体评价

QuickBlue v4.0.0 是一个骨架强、边界清、技术栈新的微服务框架。它做对了三件在同类脚手架里少见的事：

• 模块间零直接依赖（实测，非声称），且靠 api-* 契约维系；

• 把架构边界做成可执行门禁，而不是写在文档里靠自觉；

• 合规与内容安全的留痕纪律统一（绝不记原文、脱敏必须真的生效）。

但它同时暴露出两个结构性问题：

• 一处跨库 SQL 就击穿了整套"每服务一库"的承诺 —— 说明再好的架构约定，只要缺少自动化检查，就会被单点绕过；

• 工程质量与架构水平严重不匹配 —— 1081 个 main 文件仅 14 个测试类、无 CI、三库迁移机制空转。

结论：这是一个 "架构已到位、工程化待补课" 的框架。 最值得投入的不是新增能力，而是把已有的边界与纪律变成机器守得住的东西 —— 这也是路线图把"接入 CI"列为 P0 第 1 项的原因。

六、专家团分席意见

6.1 架构设计师

分层（common → starter → api → modules）是对的，模块间零直连这一点比多数同类脚手架做得好。 但分层必须能回答"新东西放哪"—— 当前缺一条决策规则（含业务语义→域；需被多域复用→starter；需自动装配→starter；否则→common），否则 support（308 文件 / 18 包）这类模块会持续膨胀。 最该立刻做的一件事：把 NoticeMapper.xml 的跨库 SQL 改为经 api-system 调用 —— 它破坏的正是这套架构唯一的强制承诺。

6.2 安全专家

正向：Sa-Token 1.46.0 + Argon2id + SM4 国密 + BouncyCastle；网关鉴权、XSS 过滤、Druid WallFilter 在位；模型合规与内容安全的留痕纪律是同类项目里少见的自觉。 必须处理：① 明文口令入库，且 SPRING_PROFILES_ACTIVE 默认值为 dev；② redis 存在弱默认值；③ 跨库 SQL 绕过 system 侧的行级权限与字段脱敏；④ 进入 git 的口令应视为已泄露，需轮换而非仅删除。

6.3 DBA

正向：五服务五库，每服务只连自己的库（零例外）；Druid + p6spy + MyBatis-Plus 分页/租户插件齐备；89 张表规模可控。 两点必办：① 迁移机制不统一（三库只有 baseline，表实为手工脚本所建）—— 必须二选一并对齐，否则将来会在启动时报出难以定位的冲突；② 跨库查询使两库无法独立迁移/备份恢复，也破坏了"按域分库"带来的部署自由度。

6.4 DevOps 专家

正向：deploy/docker-compose.yml、deploy/build.sh、docker/Dockerfile.app、deploy/scripts、nacos_config/sentinel-rules 均齐备；Nacos 3.2.1 承担注册与配置；Spring Boot Admin 4.1.2 提供运行态面板。 最大缺口：没有 CI。 仓库内不存在任何 CI 配置。arch-check.ps1 已具备挂载形态，但在接入之前，架构边界仍然依赖"人记得执行"。 建议：先把 arch-check.ps1 与 mvn test 串成一条最小流水线 —— 这比补任何单个功能更能守住质量线。

6.5 前端架构师

实测：前端工程 QuickBlue-MicroAI-webpg —— 238 个 .vue + 162 个 ts/js，views 按域组织：support 54 / system 47 / ai 34 / business 16 / report 12 / install 2。 意见：① 页面规模已到需要按域拆分工程或至少拆分路由包的程度，否则构建与权限模型会先于功能成为瓶颈；② 前端测试未纳入自动化；③ .env 区分 development/localhost/pre/production/test 五套，环境治理良好，但需确认 .env.* 未携带敏感值入库。

七、附录

7.1 取证方式与证据

7.2 验证边界（本报告未做的事）

• ❌ 未做性能压测：并发、吞吐、故障注入、真实链路时延均未测试 → 本报告不含性能结论

• ❌ 未做渗透测试：仅做配置与依赖审计，未验证鉴权绕过、注入、越权等实际攻击面

• ❌ 未做前端深度审查：仅统计规模与目录结构，未审组件质量、状态管理与构建产物

• ❌ 未做运行时验证：网关路由、Fail-Closed 行为、告警链路等未做运行验证

• ⚠️ 评分是判断而非计算结果：各维度分值与权重由本次证据综合给出，用于排期与横向比较，不构成验收结论

7.3 版本约定

xxxxxxxxxx
最新版本 = v4.0（本文档，对应产品 QuickBlue 4.0.0）→ 描述【当前实际】
历史一代 = v3.0                                   → 见 QuickBlue微服务架构评估报告_v3.0.md

报告生成: 专家团架构师评审（架构设计师 / 安全专家 / DBA / DevOps 专家 / 前端架构师） 评估工具: 全量代码仓库扫描 + 静态分析 + 配置审计 技术栈: Spring Boot 4.1.1 + Spring Cloud 2025.1.3 + Spring Cloud Alibaba 2025.1.0.0 + PostgreSQL 18 + JDK 21 + Vue 3 项目版本: QuickBlue 4.0.0 规范: 所有边界规则以 tools/arch-check.ps1 为准（可执行、非零退出即失败）