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

@@ -17,6 +17,8 @@
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency>
<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId></dependency>
<dependency><groupId>com.networknt</groupId><artifactId>json-schema-validator</artifactId></dependency>
<!-- P1-3 标识符白名单缓存 / P1-4 POInfo 缓存:进程内本地缓存,版本走 Spring Boot BOM(3.1.8) -->
<dependency><groupId>com.github.ben-manes.caffeine</groupId><artifactId>caffeine</artifactId></dependency>
<dependency><groupId>com.fasterxml.jackson.datatype</groupId><artifactId>jackson-datatype-joda</artifactId></dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency>
</dependencies>

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) {

View File

@@ -0,0 +1,113 @@
package com.eip4.platform.metadata.perf;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.ArgumentMatchers.eq;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.when;
import java.util.List;
import org.junit.jupiter.api.Test;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.jdbc.core.RowMapper;
/**
* P1-5 单测:DDL 索引增强的 SQL 生成规则。
*
* <p>规则验证:外键列(REFERENCEID=36 位 uuid)建索引;UPDATETIME 审计列建索引;
* ISIDENTIFIER/ISCOMBIDENTIFIER 列跳过(引擎已建 unique);普通列跳过;全部 IF NOT EXISTS 幂等。
* 元数据读用 Mockito 桩 JdbcTemplate,不依赖 DB。
*/
class IndexEnhancerTest {
private static final String UUID_REF = "65aabf1c-2bf5-4f63-b023-486f5075e3cc";
/** 构造一个返回固定属性行的 JdbcTemplate 桩。 */
@SuppressWarnings("unchecked")
private JdbcTemplate stubWith(List<Object[]> rows) {
JdbcTemplate jt = mock(JdbcTemplate.class);
when(jt.query(any(String.class), any(RowMapper.class), any(Object[].class)))
.thenAnswer(inv -> {
RowMapper<Object> mapper = inv.getArgument(1);
java.sql.ResultSet rs = mock(java.sql.ResultSet.class);
java.util.List<Object> out = new java.util.ArrayList<>();
int[] i = {0};
for (Object[] r : rows) {
when(rs.getString("COLUMNNAME")).thenReturn((String) r[0]);
when(rs.getString("REFERENCEID")).thenReturn((String) r[1]);
when(rs.getInt("ISIDENTIFIER")).thenReturn((Integer) r[2]);
when(rs.getInt("ISCOMBIDENTIFIER")).thenReturn((Integer) r[3]);
out.add(mapper.mapRow(rs, i[0]++));
}
return out;
});
return jt;
}
@Test
void 外键uuid列建索引() {
JdbcTemplate jt = stubWith(List.<Object[]>of(
new Object[] {"EIP4PT_ORDER_ID", UUID_REF, 0, 0}));
List<String> sqls = new IndexEnhancer(jt).generateIndexSql("EIP4PT_ORDERLINE");
assertEquals(1, sqls.size());
assertTrue(sqls.get(0).contains("CREATE INDEX IF NOT EXISTS"));
assertTrue(sqls.get(0).contains("EIP4PT_ORDERLINE"));
assertTrue(sqls.get(0).contains("(EIP4PT_ORDER_ID)"));
}
@Test
void 审计列UPDATETIME建索引() {
JdbcTemplate jt = stubWith(List.<Object[]>of(
new Object[] {"UPDATETIME", "TIME", 0, 0}));
List<String> sqls = new IndexEnhancer(jt).generateIndexSql("EIP4PT_ORDER");
assertEquals(1, sqls.size());
assertTrue(sqls.get(0).contains("(UPDATETIME)"));
}
@Test
void 标识符列跳过_引擎已建unique() {
JdbcTemplate jt = stubWith(List.of(
new Object[] {"ORDERNO", "NVARCHAR", 1, 0}, // ISIDENTIFIER
new Object[] {"CODE1", "NVARCHAR", 0, 1})); // ISCOMBIDENTIFIER
List<String> sqls = new IndexEnhancer(jt).generateIndexSql("EIP4PT_ORDER");
assertTrue(sqls.isEmpty());
}
@Test
void 普通列与基础类型不建索引() {
JdbcTemplate jt = stubWith(List.of(
new Object[] {"CUSTOMER", "NVARCHAR", 0, 0},
new Object[] {"TOTAL", "MONEY", 0, 0},
new Object[] {"VERSION", "INTEGER", 0, 0},
new Object[] {"CREATETIME", "TIME", 0, 0})); // 非 UPDATETIME 的审计列不建
List<String> sqls = new IndexEnhancer(jt).generateIndexSql("EIP4PT_ORDER");
assertTrue(sqls.isEmpty());
}
@Test
void 混合列只对外键和UPDATETIME建() {
JdbcTemplate jt = stubWith(List.of(
new Object[] {"EIP4PT_ORDER_ID", UUID_REF, 0, 0}, // 外键 → 建
new Object[] {"ORDERNO", "NVARCHAR", 1, 0}, // 标识符 → 跳
new Object[] {"CUSTOMER", "NVARCHAR", 0, 0}, // 普通 → 跳
new Object[] {"UPDATETIME", "TIME", 0, 0})); // 审计 → 建
List<String> sqls = new IndexEnhancer(jt).generateIndexSql("EIP4PT_ORDERLINE");
assertEquals(2, sqls.size());
assertTrue(sqls.stream().anyMatch(s -> s.contains("(EIP4PT_ORDER_ID)")));
assertTrue(sqls.stream().anyMatch(s -> s.contains("(UPDATETIME)")));
assertFalse(sqls.stream().anyMatch(s -> s.contains("(ORDERNO)")));
assertFalse(sqls.stream().anyMatch(s -> s.contains("(CUSTOMER)")));
}
@Test
void 索引名超长截断到63() {
String longTable = "EIP4PT_VERYLONGTABLENAME_THATEXCEEDS";
String longCol = "AVERYLONGCOLUMNNAME_FORINDEXNAMETEST";
String name = IndexEnhancer.indexName(longTable, longCol);
assertTrue(name.length() <= 63);
assertTrue(name.startsWith("IDX_"));
}
}