文档分层:随代码演进的技术文档入 git(团队 clone 可得、有版本与评审); 决策档案与含商务内容的治理文档留工作区 docs/(不随仓库分发,外包 clone 不携带)。 全部交叉引用已更新(README×2/实测报告×2/登记表/pom/ArchUnit 注释) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
8.4 KiB
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 MCP Server、schema 双闸校验
├── platform-parity C1 逐行对拍框架:录制/重放/逐行 diff(P1 一级交付物,可独立 CLI 跑批)
└── platform-app Spring Boot 启动器,组装上述模块
纪律(ArchUnit 规则固化):com.eip4.* 可调 com.dsasp.*,反向禁止;新代码必须单测,旧代码以对拍为完成定义;com.dsasp.* 与 framework 源码的 diff 保持最小。
二、选型决策表
| 决策 | 选择 | 理由 |
|---|---|---|
| 整体形态 | 模块化单体 + Flowable 独立服务(仅此一个独立) | 4 人团队 + 按客户私有化部署,拒绝微服务 |
| 运行时 | JDK 17 + Spring Boot 3.3.x | PoC 已验证,不追新 |
| 数据访问 | 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:
- 阿里 lowcode-engine(MIT,2026-02 仍发版 v1.3.2,自带设计器)— 首位备选
- antd ProComponents 薄渲染器(MIT,事实标准)— 次位,需自建协议解释器 + 设计器
- Vue 系(avue)、国际 headless(RJSF/JSONForms)— 不进备选(换栈 / 中国式表格弱)
八、落地映射(接《工程化实施计划》)
| 架构决策 | 落在哪个阶段 |
|---|---|
| 模块拆分 + ArchUnit 纪律 | P1 仓库正规化 |
| 标识符白名单 + Caffeine + DDL 索引 | P1 |
| 注入负例进对拍 + C3 压测基线 | M0 |
| 最小权限账户 + DDL 特权连接隔离 | P2(同数据权限真实现) |
| 渐进参数化 | P2 后,C3 热点 ∩ 安全风险点排序 |
| JWT 认证 | P2 |
| 只读副本 / 报表隔离 | P4 报表 D 类 |
| MCP Server | P5 |
本文档维护:随 P1 包结构落地校正;任何选型变更(尤其渲染层切换)回写第二、七节。