Files
eip4-platform/docs/架构设计.md

8.9 KiB
Raw Blame History

eip4-platform 架构设计

版本 v1.0(2026-06-10)| 上承《EIP3工程化实施计划》,是 P1「eip4-poc → eip4-platform」的设计依据 本文档固化了立项后关于工程结构、选型、中间件、保真层安全/性能的全部架构决策。 新会话/新成员开工 eip4-platform 前必读本文。


一、总原则:双层制——保真层供奉,现代层生长

移植的旧代码不重写、不"现代化改造"。理由:1,956 行 SQL 引擎的价值就在于与老系统行为逐字节一致——它是逐行对拍的基线、「业务数据零搬迁」的载体、老员工认知的延续。

eip4-platform(Maven 多模块单体)
├── platform-legacy-core    保真层:移植引擎原样,包名 com.dsasp.* 不动
│     POJOService/POJOCRUDService/Entity/POInfo/服务流引擎/脚本引擎
├── platform-metadata       现代层:REST API、DTO、OpenAPI(com.eip4.*)
├── platform-auth           P2:组织/权限/数据权限真实现(替换 PoC 桩)
├── platform-flow-gateway   Flowable REST 客户端、待办聚合、3 个 handler bean
├── platform-converter      模板转换器 + S3 脚本改写器(可独立 CLI 跑批)
├── platform-ai             AI Agent 开发底座、schema 双闸校验、自动修复、本地门禁和人工部署包
├── platform-cli            EIP4 Agent 受控命令入口:环境探测、AI 自动开发、后续发布编排
├── platform-parity         C1 逐行对拍框架:录制/重放/逐行 diff(P1 一级交付物,可独立 CLI 跑批)
└── platform-app            Spring Boot 启动器,组装上述模块

纪律(ArchUnit 规则固化):com.eip4.* 可调 com.dsasp.*,反向禁止;新代码必须单测,旧代码以对拍为完成定义;com.dsasp.* 与 framework 源码的 diff 保持最小。

二、选型决策表

决策 选择 理由
整体形态 模块化单体 + Flowable 独立服务(仅此一个独立) 4 人团队 + 按客户私有化部署,拒绝微服务
运行时 JDK 21(LTS)+ Spring Boot 3.3.x PoC 起于 JDK 17(Boot 3 最低要求、当时 LTS、不追新),F2-13 起编译目标升 release=21(修报表 500,见下)。红线:不可用 JDK 26——保真层服务流走 Groovy 4.0.27,其 ASM 不认 JDK 26 字节码(major 70),编译/运行均崩;升 JDK 须同步升 Groovy,目标取下个 LTS=25 而非 26
数据访问 JdbcTemplate,不引入 ORM 引擎本就是 JdbcTemplate;动态建表与 JPA 范式相克
平台表管理 Flyway(只管 SYS_* 平台表) 业务表由引擎动态建,不进 Flyway
认证 Spring Security + 无状态 JWT 免 session 共享,REST 自然选择
前端 独立 React 工程(amis 渲染宿主+设计器),Nginx 托管 amis 锁 6.13.0 本地化部署(fork 预演产物),不依赖 CDN
多租户 不做,按客户独立部署 项目制现实,砍掉整个复杂度维度

三、中间件:默认只有 PG + Nginx

压倒性约束:每个客户私有化部署,每多一个中间件 = 每个客户终身多一份运维负担。

中间件 决策 留口
PostgreSQL 15+ ✅ 唯一必需 单库分 schema(业务/元数据/Flowable)
Redis ❌ 不上 元数据缓存用进程内 Caffeine(接替 CCache,语义同为本地缓存);走 Spring Cache 抽象,多实例横扩时换 Redis 只改配置
消息队列 ❌ 不上 Quartz 定时沿用;轻量异步用 Spring 事件 + DB 表队列;Flowable 自带 DB-based async executor
Elasticsearch ❌ 不上 PG 能力足够
MinIO ⭕ 可选 FileService 默认本地盘(保持原行为),接口已抽象
Nginx ✅ 标配 静态托管 + 反代 + 切流期新旧路由分发(绞杀者流量阀门)
监控 Actuator + 日志 不上 Prometheus 全家桶,留 endpoint

单客户交付形态 = 4 进程:nginx + eip4-platform.jar + flowable-service.jar + postgres(docker-compose 模板复制)。

四、保真层安全方案(四层纵深)

代码实况(已读源码核实):值位置经 StringUtil.TO_STRING 单引号转义,最低级注入已挡;残余注入面 = 标识符裸拼(列名/表名/ORDER BY)+ 个别 ID 直拼点 + 转义本身脆弱。

层 做法 关键点
1. 标识符白名单(最优先) 列名/表名/排序列必须存在于该实体 SYS_ENTITYATTRIBUTE 元数据,否则拒绝 元数据即白名单——动态 SQL 引擎独有的安全红利,零维护零误杀。P1 随 REST 层实现
2. 渐进参数化 热点路径值位置改 ? 占位,每改一处过对拍 同时根治性能的计划缓存抖动(见下),一箭双雕。P2 后渐进,优先级=C3 热点∩安全风险点
3. 最小权限账户 CRUD 走受限账户;动态建表 DDL 走独立特权连接 漏一个点也炸不掉库。P2 实施
4. 检测兜底 对拍套件加注入负例(' OR 1=1--、'; DROP 等);REST 入参校验;statement_timeout 杀异常查询 把"不可注入"变成可回归的断言,而非一次性人工保证。M0 随 C1 对拍套件建立

核心洞察:第 1 层「标识符白名单」是杀手锏——元数据驱动引擎的"合法列名集合"是现成、精确、零维护的,普通手写 DAO 反而没有这个红利。

五、保真层性能方案

代码实况:JdbcTemplate + SqlRowSet(全量物化到内存);每次查询是全新拼出的 SQL 字符串 → PG 执行计划缓存几乎无法复用(头号性能税);级联/主子表有按行 N+1。

问题 解法 性质
计划缓存抖动(头号) 值位置参数化(=安全第 2 层)→ SQL 结构稳定 → 计划复用 根子级修复,实测更快
动态表无索引 DDL 生成器增强:建表自动给主键/外键/常用查询列加索引(引擎现仅建表不建索引) 根子级修复
大结果集内存 强制分页(已有)+ perPage 上限封顶;导出走 RowCallbackHandler 流式 补齐填坑
元数据反复读 POInfo 用 Caffeine 缓存(接替 CCache),避免每请求读 SYS_ENTITY 补齐填坑
N+1 级联 C3 压测定位热点 → 批量化(batch insert / IN 查询)→ 过对拍 补齐填坑
报表重查询 79 个服务流走 PG 只读副本,与 OLTP 隔离 隔离

关键协同:安全(值参数化)和性能(计划缓存)的根子是同一处——参数化一次还两笔债。改造优先级 = C3 压测热点 ∩ 安全风险点。

六、相对旧系统的诚实结论(决策层口径)

不能把性能当重构卖点。 正确对外口径:

维度 相比旧系统 性质
安全 明显且不可逆提高 从人工保证 → 工程能力(测试守着不退化)
性能-计划缓存/索引 实测更快 根子级修复
性能-内存/N+1 补齐填坑 不变慢,非超越
性能-单请求延迟 打平或略增 架构代价(前后端分离多一次网络跳),搬不动

被问"重构后是不是更快了",答案不是"是",而是"高负载下更稳、更安全、可持续,单次响应打平——而性能从来不是重构目标,AI 友好与摆脱 EOL 才是"。C3 压测的作用是量化这一点(验证不退化 + 高负载改善),不是证明"更快"。决策会已将单请求延迟列为风险 R2。

七、渲染层备选(amis fork 失败时的 Plan B)

「渲染层可替换」已被架构保证:后端引擎、79 服务流、REST API、元数据占总投入 ~70%,与渲染层无关;转换器的 XML 解析半段也中立。换渲染器损失 = 转换器后半段 + 已转页面 schema,量级 1–2 人月,非推倒重来。

触发(决策会止损 S2 / 触发条件 1:fork 预演失败或 amis 正式归档)后,按序做 1–2 天 spike:

  1. 阿里 lowcode-engine(MIT,2026-02 仍发版 v1.3.2,自带设计器)— 首位备选
  2. antd ProComponents 薄渲染器(MIT,事实标准)— 次位,需自建协议解释器 + 设计器
  3. Vue 系(avue)、国际 headless(RJSF/JSONForms)— 不进备选(换栈 / 中国式表格弱)

八、落地映射(接《工程化实施计划》)

架构决策 落在哪个阶段
模块拆分 + ArchUnit 纪律 P1 仓库正规化
标识符白名单 + Caffeine + DDL 索引 P1
注入负例进对拍 + C3 压测基线 M0
最小权限账户 + DDL 特权连接隔离 P2(同数据权限真实现)
渐进参数化 P2 后,C3 热点 ∩ 安全风险点排序
JWT 认证 P2
只读副本 / 报表隔离 P4 报表 D 类
MCP Server P5

本文档维护:随 P1 包结构落地校正;任何选型变更(尤其渲染层切换)回写第二、七节。