TypeScript数组对象精确类型校验：字面量与变量行为差异

问题背景 #

我需要在应用中实现对象的精确类型校验，由于TypeScript原生不支持该特性，编写了一个Exact泛型助手类型，但遇到了不一致的行为：

• 直接在变量中定义包含多余属性的对象字面量时，TypeScript会触发类型错误
• 将包含多余属性的数组或对象作为变量传入时，却不会触发任何错误

复现代码 #

type Exact<T, Struct> = T extends Struct ? (Exclude<keyof T, keyof Struct> extends never ? T : never) : never;

export type MultipleObjectSuccessResponse<T extends Record<string, any>> = {
    success: true
    code: 200;
    data: Array<Exact<T, T>>;
    pagination: {
        page: number;
        per_page: number;
        total_pages: number;
        total_records: number;
    };
};

type MyData = {
    prop1: string;
    prop2: number;
};

// 直接写字面量：prop3会触发错误
const test: MultipleObjectSuccessResponse<MyData> = {
    code: 200,
    success: true,
    data: [{
            prop1: "hello", 
            prop2: 123,
            prop3: "this will cause an error", 
        }],
    pagination: {
        page: 1,
        per_page: 10,
        total_pages: 1,
        total_records: 1,
    },
};

const tooManyArray = [{
            prop1: "hello",
            prop2: 123,
            prop3: "this will cause an error", 
        }];

const tooManyObject = {
            prop1: "hello",
            prop2: 123,
            prop3: "this will cause an error", 
        };

// 传入变量：无错误
const test2: MultipleObjectSuccessResponse<MyData> = {
    code: 200,
    success: true,
    data: tooManyArray,
    pagination: {
        page: 1,
        per_page: 10,
        total_pages: 1,
        total_records: 1,
    },
};

// 传入变量：无错误
const test3: MultipleObjectSuccessResponse<MyData> = {
    code: 200,
    success: true,
    data: [tooManyObject],
    pagination: {
        page: 1,
        per_page: 10,
        total_pages: 1,
        total_records: 1,
    },
};

原因分析 #

这是TypeScript两种机制共同作用的结果：

1. 对象字面量新鲜度检查：直接编写的对象字面量会被TypeScript做额外严格校验，不允许存在目标类型中未定义的属性，这就是test变量报错的原因。
2. 类型兼容性与拓宽：当对象被赋值给变量（如tooManyObject）时，TypeScript会自动拓宽变量类型，包含所有存在的属性。之后将该变量赋值给MultipleObjectSuccessResponse<MyData>时，由于TypeScript结构类型系统允许子类型赋值给父类型（带多余属性的对象是MyData的子类型），而当前Exact<T, T>写法等价于直接使用T，并未真正约束变量的精确类型，因此不会触发错误。

解决方案 #

1. 修复Exact泛型定义 #

更新Exact类型，通过双向约束确保对象结构完全匹配目标类型，不允许多余或缺失属性：

type Exact<T, U> =
  T extends U ?
  (U extends T ? T : never) :
  never;

2. 使用函数创建响应对象（推荐） #

利用函数参数的类型检查机制，即使传入变量也会强制精确校验：

function createSuccessResponse<T>(
  data: Array<Exact<T, T>>,
  pagination: { page: number; per_page: number; total_pages: number; total_records: number }
): MultipleObjectSuccessResponse<T> {
  return {
    success: true,
    code: 200,
    data,
    pagination
  };
}

// 传入变量会触发错误：类型"{ prop1: string; prop2: number; prop3: string; }"不满足Exact<MyData, MyData>
const test4 = createSuccessResponse<MyData>(tooManyArray, {
  page: 1,
  per_page: 10,
  total_pages: 1,
  total_records: 1,
});

3. 手动断言变量类型（不推荐） #

如果必须使用变量赋值，可以手动断言变量类型为精确类型，但会丢失部分类型安全性：

const validArray = tooManyArray as Array<Exact<MyData, MyData>>;
const test5: MultipleObjectSuccessResponse<MyData> = {
  code: 200,
  success: true,
  data: validArray,
  pagination: {
    page: 1,
    per_page: 10,
    total_pages: 1,
    total_records: 1,
  },
};

内容的提问来源于stack exchange，提问作者Bart Evelo