feat(metadata): P1-5 DDL 索引增强(现代层后置,不改引擎)+ MetaController 接线

IndexEnhancer 建表后按元数据补 CREATE INDEX IF NOT EXISTS:外键(REFERENCEID=36位
uuid)列 + UPDATETIME 审计列;跳过 ISIDENTIFIER/ISCOMBIDENTIFIER(引擎已建 unique);
索引名截断到 PG 上限 63。BacklogIndexScriptGenerator 为存量实体只生成脚本落盘不执行
(客户库执行排切流期变更窗口)。MetaController 接入:createEntity 自动补索引 + 失效缓存、
dropEntity/新增 evict、backlog-index 端点。metadata pom 加 Caffeine(白名单+POInfo缓存)。
单测 6 个。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-06-11 12:11:02 +08:00
parent 4c9af8edd4
commit 3fa970adbf
5 changed files with 402 additions and 1 deletions

View File

@@ -0,0 +1,95 @@
package com.eip4.platform.metadata.perf;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.LocalDate;
import java.util.ArrayList;
import java.util.List;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Component;
/**
* 存量补索引脚本生成器(P1-5)。
*
* <p>扫描 {@code SYS_ENTITY} 全部已登记业务实体,按 {@link IndexEnhancer} 同一套规则
* (外键 uuid 列 + UPDATETIME,跳过 ISIDENTIFIER/ISCOMBIDENTIFIER)生成补索引 SQL,
* <b>只落盘成 .sql 文件,不对任何库执行</b>——存量库(尤其客户库)的执行排进切流期
* 变更窗口,由 DBA 在维护窗口跑。脚本全部 {@code IF NOT EXISTS} 幂等。
*
* <p>过滤前缀可选:默认扫全部业务实体;可传前缀(如 {@code EIP4PT_})只生成本地实体脚本。
*/
@Component
public class BacklogIndexScriptGenerator {
private final JdbcTemplate jdbcTemplate;
private final IndexEnhancer indexEnhancer;
public BacklogIndexScriptGenerator(JdbcTemplate jdbcTemplate, IndexEnhancer indexEnhancer) {
this.jdbcTemplate = jdbcTemplate;
this.indexEnhancer = indexEnhancer;
}
/**
* 生成存量补索引脚本文本。
* @param tablePrefix 表名前缀过滤(如 {@code EIP4PT_});为空则全部业务实体
* @return SQL 脚本全文(含头注释)
*/
public String generateScript(String tablePrefix) {
List<String> tables = listEntityTables(tablePrefix);
StringBuilder sb = new StringBuilder();
sb.append("-- ============================================================\n");
sb.append("-- 存量补索引脚本(P1-5 DDL 索引增强 / 现代层后置,不改引擎)\n");
sb.append("-- 生成日期: ").append(LocalDate.now()).append("\n");
sb.append("-- 规则: 外键(REFERENCEID=36位uuid)列 + UPDATETIME; 跳过 ISIDENTIFIER/ISCOMBIDENTIFIER(引擎已建unique)\n");
sb.append("-- 幂等: 全部 IF NOT EXISTS。⚠️ 客户库执行排切流期变更窗口,本文件只落盘不自动执行。\n");
sb.append("-- 实体数: ").append(tables.size()).append("\n");
sb.append("-- ============================================================\n\n");
int stmtCount = 0;
for (String table : tables) {
List<String> sqls = indexEnhancer.generateIndexSql(table);
if (sqls.isEmpty()) {
continue;
}
sb.append("-- ").append(table).append(" (").append(sqls.size()).append(" 索引)\n");
for (String sql : sqls) {
sb.append(sql).append(";\n");
stmtCount++;
}
sb.append("\n");
}
sb.append("-- 合计 CREATE INDEX 语句: ").append(stmtCount).append("\n");
return sb.toString();
}
/**
* 生成脚本并写入磁盘文件。
* @return 写入的字节数
*/
public long generateToFile(Path outputPath, String tablePrefix) {
try {
String script = generateScript(tablePrefix);
byte[] bytes = script.getBytes(StandardCharsets.UTF_8);
if (outputPath.getParent() != null) {
Files.createDirectories(outputPath.getParent());
}
Files.write(outputPath, bytes);
return bytes.length;
} catch (java.io.IOException e) {
throw new IllegalStateException("写补索引脚本失败: " + outputPath, e);
}
}
private List<String> listEntityTables(String tablePrefix) {
String sql = "SELECT TABLENAME FROM SYS_ENTITY WHERE ISACTIVE = 1 AND ISVIEW = 0";
List<Object> args = new ArrayList<>();
if (tablePrefix != null && !tablePrefix.isBlank()) {
sql += " AND TABLENAME LIKE ?";
args.add(tablePrefix.toUpperCase() + "%");
}
sql += " ORDER BY TABLENAME";
return jdbcTemplate.queryForList(sql, String.class, args.toArray());
}
}

View File

@@ -0,0 +1,110 @@
package com.eip4.platform.metadata.perf;
import java.util.ArrayList;
import java.util.List;
import java.util.regex.Pattern;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Component;
/**
* DDL 索引增强(P1-5,《架构设计》(docs/架构设计.md) 第五节「动态表无索引」改造点)。
*
* <p>引擎 {@code Entity.createTableSql} 只建表 + 主键/唯一约束,<b>不建普通索引</b>。
* C3 客户库实测 34k 行表首页 P95 1.18s、38k 行复杂视图 4.6s,无索引是主因之一。
* 本类<b>现代层后置</b>:实体建表后按元数据生成并执行 {@code CREATE INDEX IF NOT EXISTS},
* <b>不改引擎</b>。规则:
* <ul>
* <li><b>外键列</b>——{@code REFERENCEID} 为 36 位 uuid 的列(指向其他实体,引擎不建索引);</li>
* <li><b>审计常用列</b>——{@code UPDATETIME}(列表默认排序 / 增量同步高频过滤);</li>
* <li><b>标识符列</b>({@code ISIDENTIFIER}/{@code ISCOMBIDENTIFIER})<b>跳过</b>——引擎
* 已在 {@code createTableSql} 里建了 {@code unique} 约束,其自带的唯一索引已覆盖。</li>
* </ul>
* 全部 {@code IF NOT EXISTS} 幂等,重复建表/补跑安全。
*/
@Component
public class IndexEnhancer {
/** 36 位 uuid(8-4-4-4-12)——引擎用它做引用类型列的 displayType/REFERENCEID。 */
private static final Pattern UUID_36 = Pattern.compile(
"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}");
/** PG 标识符上限 63 字节,索引名超长截断。 */
private static final int PG_IDENT_MAX = 63;
private static final String AUDIT_COL = "UPDATETIME";
private final JdbcTemplate jdbcTemplate;
public IndexEnhancer(JdbcTemplate jdbcTemplate) {
this.jdbcTemplate = jdbcTemplate;
}
/**
* 为新建实体补索引:读元数据生成 SQL 并立即执行(建表后调用)。
* @return 实际执行的 CREATE INDEX 语句(已执行)
*/
public List<String> enhanceForNewEntity(String table) {
List<String> sqls = generateIndexSql(table);
for (String sql : sqls) {
jdbcTemplate.execute(sql);
}
return sqls;
}
/**
* 按元数据生成某实体的补索引 SQL(不执行)。供存量补索引脚本生成器复用。
* 列来源:SYS_ENTITYATTRIBUTE(现代层直读,不经引擎)。
*/
public List<String> generateIndexSql(String table) {
if (table == null || table.isBlank()) {
return List.of();
}
String upper = table.toUpperCase();
List<AttrRow> attrs = jdbcTemplate.query(
"SELECT a.COLUMNNAME, a.REFERENCEID, a.ISIDENTIFIER, a.ISCOMBIDENTIFIER "
+ "FROM SYS_ENTITYATTRIBUTE a JOIN SYS_ENTITY e ON a.ENTITYID = e.SYS_ENTITY_ID "
+ "WHERE e.TABLENAME = ? AND e.ISACTIVE = 1 AND a.ISACTIVE = 1 "
+ "ORDER BY a.COLUMNNAME",
(rs, n) -> new AttrRow(
rs.getString("COLUMNNAME"),
rs.getString("REFERENCEID"),
rs.getInt("ISIDENTIFIER") > 0,
rs.getInt("ISCOMBIDENTIFIER") > 0),
upper);
List<String> sqls = new ArrayList<>();
for (AttrRow a : attrs) {
if (a.columnName == null || a.columnName.isBlank()) {
continue;
}
// 标识符列引擎已建 unique(自带唯一索引),跳过
if (a.isIdentifier || a.isCombidentifier) {
continue;
}
boolean isForeignKey = a.referenceId != null && UUID_36.matcher(a.referenceId).matches();
boolean isAudit = AUDIT_COL.equalsIgnoreCase(a.columnName);
if (isForeignKey || isAudit) {
sqls.add(createIndexSql(upper, a.columnName.toUpperCase()));
}
}
return sqls;
}
private static String createIndexSql(String table, String column) {
String name = indexName(table, column);
return "CREATE INDEX IF NOT EXISTS " + name + " ON " + table + " (" + column + ")";
}
static String indexName(String table, String column) {
String name = "IDX_" + table + "_" + column;
if (name.length() > PG_IDENT_MAX) {
name = name.substring(0, PG_IDENT_MAX);
}
return name;
}
private record AttrRow(String columnName, String referenceId,
boolean isIdentifier, boolean isCombidentifier) {
}
}

View File

@@ -12,6 +12,7 @@ import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import com.dsasp.server.common.dataDic.bean.GeneralPOJO;
@@ -19,9 +20,14 @@ import com.dsasp.server.common.dataDic.service.DataDicService;
import com.dsasp.server.common.dataDic.service.POJOCRUDService;
import com.dsasp.server.common.util.UserSession;
import com.dsasp.server.dataDic.bean.Entity;
import com.eip4.platform.metadata.perf.BacklogIndexScriptGenerator;
import com.eip4.platform.metadata.perf.IndexEnhancer;
import com.eip4.platform.metadata.perf.PoInfoCacheInvalidator;
import io.swagger.v3.oas.annotations.Operation;
import java.nio.file.Path;
/**
* 元数据 API(未来 MCP 工具面的雏形,WS5 AI 闭环用):
* POST /api/meta/entity 创建实体(元数据 + 动态物理表),
@@ -42,13 +48,22 @@ public class MetaController {
private final DataDicService dataDicService;
private final POJOCRUDService pojoCRUDService;
private final JdbcTemplate jdbcTemplate;
private final IndexEnhancer indexEnhancer;
private final PoInfoCacheInvalidator cacheInvalidator;
private final BacklogIndexScriptGenerator backlogIndexScriptGenerator;
public MetaController(DataDicService dataDicService,
POJOCRUDService pojoCRUDService,
JdbcTemplate jdbcTemplate) {
JdbcTemplate jdbcTemplate,
IndexEnhancer indexEnhancer,
PoInfoCacheInvalidator cacheInvalidator,
BacklogIndexScriptGenerator backlogIndexScriptGenerator) {
this.dataDicService = dataDicService;
this.pojoCRUDService = pojoCRUDService;
this.jdbcTemplate = jdbcTemplate;
this.indexEnhancer = indexEnhancer;
this.cacheInvalidator = cacheInvalidator;
this.backlogIndexScriptGenerator = backlogIndexScriptGenerator;
}
@Operation(summary = "创建实体:写入 SYS_ENTITY/SYS_ENTITYATTRIBUTE 元数据并动态创建物理表")
@@ -115,6 +130,11 @@ public class MetaController {
String ddl = newEnt.createTableSql();
dataDicService.executeCreateSql(ddl);
// P1-5:建表后按元数据补索引(外键 uuid 列 + UPDATETIME),引擎只建表不建索引
List<String> indexes = indexEnhancer.enhanceForNewEntity(table);
// P1-4:失效 POInfo + 白名单缓存,使后续读立即拿到新实体元数据,无需重启(C1 坑 3 回归)
cacheInvalidator.evictByTable(table);
Map<String, Object> resp = new LinkedHashMap<>();
resp.put("status", 0);
resp.put("msg", "created");
@@ -122,6 +142,7 @@ public class MetaController {
"entityId", entityId,
"tablename", table,
"attributeCount", created.size(),
"indexCount", indexes.size(),
"listApi", "/api/entity/" + table + "/list"));
return resp;
}
@@ -133,16 +154,76 @@ public class MetaController {
if (!t.startsWith("EIP4")) {
return err("仅允许删除 EIP4 前缀的测试实体");
}
// 删除前先取 entityId,供缓存失效钩子精确清 POInfo
List<String> ids = jdbcTemplate.queryForList(
"SELECT SYS_ENTITY_ID FROM SYS_ENTITY WHERE TABLENAME=?", String.class, t);
String entityId = ids.isEmpty() ? null : ids.get(0);
jdbcTemplate.execute("DROP TABLE IF EXISTS " + t);
int a = jdbcTemplate.update(
"DELETE FROM SYS_ENTITYATTRIBUTE WHERE ENTITYID IN (SELECT SYS_ENTITY_ID FROM SYS_ENTITY WHERE TABLENAME=?)", t);
int e = jdbcTemplate.update("DELETE FROM SYS_ENTITY WHERE TABLENAME=?", t);
// P1-4:删除实体后失效 POInfo + 白名单缓存,避免缓存里残留已删实体的元数据
cacheInvalidator.evictByEntityId(entityId, t);
Map<String, Object> resp = new LinkedHashMap<>();
resp.put("status", 0);
resp.put("msg", "dropped attrs=" + a + " entity=" + e);
return resp;
}
/**
* P1-4 手动失效 POInfo + 白名单缓存(C1 坑 3 修复的运维出口)。
* 元数据被旁路写入(直改 SYS_ENTITYATTRIBUTE 等)后调用本接口,使变更立即生效,无需重启。
*/
@Operation(summary = "失效指定实体的 POInfo + 白名单缓存(元数据旁路变更后调用,免重启)")
@PostMapping("/api/meta/evict/{table}")
public Map<String, Object> evict(@PathVariable String table) {
cacheInvalidator.evictByTable(table);
Map<String, Object> resp = new LinkedHashMap<>();
resp.put("status", 0);
resp.put("msg", "evicted " + table.toUpperCase());
return resp;
}
/**
* P1-5 存量补索引脚本生成器。扫描元数据按索引增强规则生成补索引 SQL 落盘成文件,
* <b>默认只落盘不执行</b>(客户库执行排切流期变更窗口);本地验证可传 {@code execute=true}
* 在<b>当前库</b>实际执行(仅本地库可这样用)。
*
* @param out 落盘文件路径(如 {@code platform-metadata/补索引-EIP4PT.sql})
* @param prefix 表名前缀过滤(如 {@code EIP4PT_});空则全部业务实体
* @param execute 是否在当前库实际执行(默认 false,仅落盘)
*/
@Operation(summary = "生成存量补索引脚本(默认只落盘;execute=true 在当前库执行,仅本地库用)")
@PostMapping("/api/meta/backlog-index")
public Map<String, Object> backlogIndex(@RequestParam String out,
@RequestParam(required = false) String prefix,
@RequestParam(defaultValue = "false") boolean execute) {
String script = backlogIndexScriptGenerator.generateScript(prefix);
long bytes = backlogIndexScriptGenerator.generateToFile(Path.of(out), prefix);
int executed = 0;
if (execute) {
// 仅本地验证用:对前缀范围内每个实体执行补索引(IF NOT EXISTS 幂等)
List<String> tables = jdbcTemplate.queryForList(
prefix == null || prefix.isBlank()
? "SELECT TABLENAME FROM SYS_ENTITY WHERE ISACTIVE=1 AND ISVIEW=0 ORDER BY TABLENAME"
: "SELECT TABLENAME FROM SYS_ENTITY WHERE ISACTIVE=1 AND ISVIEW=0 AND TABLENAME LIKE '"
+ prefix.toUpperCase() + "%' ORDER BY TABLENAME",
String.class);
for (String tbl : tables) {
executed += indexEnhancer.enhanceForNewEntity(tbl).size();
}
}
Map<String, Object> resp = new LinkedHashMap<>();
resp.put("status", 0);
resp.put("msg", execute ? "generated+executed" : "generated");
resp.put("data", Map.of(
"file", out,
"bytes", bytes,
"scriptLines", script.split("\n").length,
"executedIndexes", executed));
return resp;
}
private Map<String, Object> saveAttr(Map<String, Object> tpl, String entityId, String col,
String display, String ref, Integer len,
boolean mandatory, boolean isKey, Properties ctx) {