feat(B-1): 统一行校验 choke point —— 消除三份分叉的校验实现(A12/A17)

背景(PLAN-v0.7.5.md 根因 1):
修复前有**三份**行校验实现,覆盖面各不相同:

  位置                                        类型 required PK非空 maxLength min/max 未知列
  engine/memory.ts(disk/hybrid 共用)          ✓     ✓       ✓      ✗        ✗     静默丢弃
  engine/aria/index.ts → checkFieldType         ✓     ✓       ✓      ✓        ✓     静默丢弃
  table/schema.ts                               ✓     ✓       ✓      ✓        ✓     静默丢弃

后果一(A12):同一份 schema、同一条 INSERT 是否报约束错误取决于引擎选择 ——
`CREATE TABLE t (name STRING(3))` + 插入 'abcdef' 在 Aria 抛错,在
memory/disk/hybrid 静默写入超长值。

后果二(A17):四个引擎对未知列一律静默丢弃。`INSERT INTO t (id, nope) VALUES
('1',2)` 报成功,随后 `SELECT nope` 报 COLUMN_NOT_FOUND —— 同一列名在写路径与
读路径得到**相反结论**。TABLE API 直通路径尤其明显(executor 按 schema 列序
构造行,nope 那个位置根本没有值,所以连"校验 stmt.columns"都拦不住)。

根治方式:
1. 新增 src/table/validation.ts —— 唯一校验定义 `compileValidator(schema)`,
   约束覆盖面取三者并集,并把**规范化**(default 填充、undefined 跳过、
   __proto__ 防污染)与校验放在同一处。
   三种载荷形态刻意分成三个显式入口,不合成带 options 的函数:
     - validateRow(row, knownColumns?)  INSERT 语义(default 生效、缺列合法)
     - validatePartial(row)             UPDATE 语义(只校验出现的列)
     - assertNoUnknownColumns           独立可复用的列名存在性检查
   混成一个函数会让"required 是否生效"取决于调用方参数,重新引入跨路径差异。
2. MemoryEngine / AriaEngine 的私有 validateRow 改为委托;schema.ts 的公开
   validateRow 同样委托(API 不变,实现只剩一份)。
3. 四个引擎新增 validatePayload(table, rows, mode)(IStorageEngine 契约),
   Executor 在**任何副作用之前**调用:多行批量整体判定,错误消息一次列出全部
   未知列与已知列清单。
4. executeInsert 显式校验 stmt.columns 全部存在(A17)。
5. UPDATE 的外键级联写入(applyUpdateCascade)从"直接赋值"改为过
   validatePartial —— 此前 CASCADE 把新主键写进引用列时绕过 maxLength/min/max,
   与 A12 属同一类"校验只在部分写入路径生效"。

连带修正(测试夹具本身不忠实,B-1 使其暴露):
  - tests/engine/aria-cache.test.ts 的 makeRows 无条件返回 {id,name,age},
    部分用例的表只有 {id,name} —— 多余列被静默丢弃所以"通过"。新增 rowsFor()
    按 schema 裁剪,让夹具忠实反映表结构(而不是放宽校验)。
  - tests/v073-fixes.test.ts "schema 外列不持久化" 改为断言写路径即拒绝,
    并保留"合法行落盘后不含额外列"的检查。

验证:
  - 新增 tests/v080-unified-validation.test.ts:8 项 × 4 引擎 + 9 项校验器
    单元契约,共 41 断言;
  - 全量 84 套件 / 1499 测试通过;typecheck(src+tests) 与 lint 零错误。
This commit is contained in:
thzxx
2026-09-14 23:38:58 +08:00
parent 67e72d897f
commit 2a109ef933
11 changed files with 678 additions and 108 deletions
+48 -28
View File
@@ -9,6 +9,7 @@ import { DatabaseError } from '../constants';
import { cloneRow } from './interface';
import { matchWhere, applyOrderBy, projectColumns, containsUnresolvedSubqueries } from '../query/where-matcher';
import { stripUndefinedUpdates } from '../table/schema';
import { compileValidator, type RowValidator } from '../table/validation';
export class MemoryEngine implements IStorageEngine {
readonly name = 'memory';
@@ -498,10 +499,20 @@ export class MemoryEngine implements IStorageEngine {
const refTableData = this.tables.get(refTableName);
if (!refTableData) continue;
if (colDef.onUpdate !== 'CASCADE' && colDef.onUpdate !== 'SET NULL') continue;
// v0.8.0(B-1):级联写入也必须过统一校验。
//
// 此前这里**直接赋值**绕过校验:`onUpdate: 'CASCADE'` 把新主键写入引用列时,
// 若该列有 maxLength / min / max 约束(新主键更长或超出范围),
// 约束被静默绕过 —— 与 A12 是同一类"校验只在部分写入路径生效"的问题。
// SET NULL 到 required/非空列的检查由 checkUpdateRestrict 在任何修改前完成,
// 此处再校验可同时覆盖 maxLength/min/max 这类"具体值相关"的约束。
const validator = this.rowValidator(refSchema);
for (const [refPk, refRow] of refTableData) {
if (String(refRow[colName]) !== oldPk) continue;
const nextValue = colDef.onUpdate === 'CASCADE' ? newPk : null;
const { values } = validator.validatePartial({ [colName]: nextValue });
this.removeIndexEntries(refTableName, refRow, refPk);
refRow[colName] = colDef.onUpdate === 'CASCADE' ? newPk : null;
refRow[colName] = values[colName];
this.updateIndexes(refTableName, refRow, refPk);
}
}
@@ -750,35 +761,44 @@ export class MemoryEngine implements IStorageEngine {
}
private validateRow(schema: TableSchema, row: Record<string, unknown>): Record<string, unknown> {
const validated: Record<string, unknown> = {};
for (const [colName, colDef] of Object.entries(schema.columns)) {
let value = row[colName];
if (value === undefined && colDef.default !== undefined) value = colDef.default;
if (colDef.required && (value === undefined || value === null)) {
throw new DatabaseError(`Column "${colName}" is required in table "${schema.name}"`, 'VALIDATION_ERROR');
}
// v0.7.4: 主键列强制非空(SQL 语义 PK 隐含 NOT NULL)——
// 此前 null/undefined 主键被 String() 化为 "null"/"undefined" 静默入库
if (colDef.primaryKey && (value === undefined || value === null)) {
throw new DatabaseError(
`Primary key column "${colName}" in table "${schema.name}" cannot be null or undefined`,
'VALIDATION_ERROR',
);
}
if (value !== undefined && value !== null) this.checkType(colName, colDef.type, value);
if (value !== undefined) validated[colName] = value;
}
return validated;
// v0.8.0B-1):委托给**唯一**的行校验实现(table/validation.ts)。
//
// 此前这里是第三份独立实现:只做类型检查,**没有** maxLength / min / max
// 约束(Aria 有)—— 于是同一份 schema、同一条 INSERT 是否报错取决于引擎
//(缺陷 A12)。同时它对未知列静默丢弃(A17)。
return this.rowValidator(schema).validateRow(row);
}
private checkType(colName: string, type: string, value: unknown): void {
const jsType = typeof value;
switch (type) {
case 'string': if (jsType !== 'string') throw new DatabaseError(`Column "${colName}" expects string, got ${jsType}`, 'TYPE_ERROR'); break;
case 'number': if (jsType !== 'number') throw new DatabaseError(`Column "${colName}" expects number, got ${jsType}`, 'TYPE_ERROR'); break;
case 'boolean': if (jsType !== 'boolean') throw new DatabaseError(`Column "${colName}" expects boolean, got ${jsType}`, 'TYPE_ERROR'); break;
case 'date': if (jsType !== 'string' || isNaN(Date.parse(value as string))) throw new DatabaseError(`Column "${colName}" expects valid date`, 'TYPE_ERROR'); break;
case 'json': if (jsType !== 'object') throw new DatabaseError(`Column "${colName}" expects object/array, got ${jsType}`, 'TYPE_ERROR'); break;
/**
* 取该 schema 的行校验器(每次调用重新编译)。
*
* 不缓存在引擎字段上:`alterTable` 会原地修改 schema 对象,
* 长期缓存会继续用过期列定义("加了列却仍被当未知列"这类难查问题)。
* 编译本身只是 `Object.entries` + Set 构造,相对一次 INSERT 的索引维护可忽略。
*/
private rowValidator(schema: TableSchema): RowValidator {
return compileValidator(schema);
}
/**
* v0.8.0B-1):写入前置校验(见 `IStorageEngine.validatePayload` 契约)。
*
* 引擎在 `insert` / `update` 内部**同样**会校验 —— 本方法只是让 Executor 与
* QueryBuilder 能在"开始写入之前"拿到同一套判定结果,从而:
* - 多行 INSERT 的预检发生在任何副作用之前(错误信息带列名清单);
* - 直通路径与 SQL 路径不可能给出不同结论(同一个 `compileValidator`)。
*/
async validatePayload(
tableName: string,
rows: Record<string, unknown>[],
mode: 'insert' | 'update' = 'insert',
): Promise<void> {
this.ensureTable(tableName);
const schema = this.schemas.get(tableName)!;
const validator = this.rowValidator(schema);
for (const row of rows) {
if (mode === 'update') validator.validatePartial(stripUndefinedUpdates(row));
else validator.validateRow(row);
}
}