将接口对象传入期望字典类型的函数时报错原因解析

我编写了如下TypeScript代码，希望将请求对象传入Http Get函数。为何get函数接受helperObj中的对象参数，却不接受helperInt中的Req接口类型参数？

interface Req {
    key: string;
    page?: number;
}

function helperInt(req: Req) {
    get('', req); // ERROR
    // Argument of type 'Req' is not assignable to parameter of type '{ [key: string]: string | number | boolean | (string | number | boolean)[]; }'.
    // Index signature for type 'string' is missing in type 'Req'.(2345)
}

function helperObj(req: {
    key: string;
    page?: number;
}) {
    get('', req);
}

function get(url: string, params?: { [key: string]: string | number | boolean | (string | number | boolean)[] }) {
    console.log(url, params);
}

const myReq: Req = {
    key: "foo",
    page: 0,
};

helperInt(myReq);
helperInt({
    key: "foo",
    page: 0,
});

helperObj(myReq);
helperObj({
    key: "foo",
    page: 0,
});

补充说明：

• helperInt和helperObj均可接受Req类型对象或字面量对象；
• get函数的params类型匹配Angular的HttpParams；
• Req接口用于初始化并按需修改对象后传入get函数。

原因分析 #

核心在于TypeScript的结构类型检查规则：

1. 索引签名的严格要求：get函数的params参数定义了字符串索引签名，要求对象的所有属性值都必须是string | number | boolean | (string | number | boolean)[]类型，且允许任意字符串键。而Req接口仅声明了明确的key和page属性，没有显式的索引签名，TypeScript不会默认推断它满足索引签名约束——因为Req的实例可能被添加额外的、不符合值类型的属性（比如给myReq新增extra: Date属性）。
2. 字面量类型的特殊处理：当直接传入对象字面量时，TypeScript会进行"新鲜性检查"，临时认定字面量的结构完全匹配目标类型（无额外属性），因此可以通过检查。但当字面量被赋值给Req类型的变量后，变量的类型固化为Req，不再享受字面量的特殊待遇。

解决方案 #

1. 给Req接口添加匹配的索引签名

明确声明Req的所有属性都符合get参数的值类型：

interface Req {
    key: string;
    page?: number;
    // 覆盖所有属性类型，同时兼容可选属性的undefined
    [key: string]: string | number | undefined;
}

如果要完全匹配get的参数类型，也可以写成：

interface Req {
    key: string;
    page?: number;
    [key: string]: string | number | boolean | (string | number | boolean)[] | undefined;
}

2. 使用类型断言

当你确认Req实例不会有不符合要求的额外属性时，可以用断言跳过检查：

function helperInt(req: Req) {
    get('', req as { [key: string]: string | number | boolean | (string | number | boolean)[] });
}

3. 放宽get函数的参数类型

将get的params类型改为兼容结构类型的Record，避免强制要求索引签名：

function get(url: string, params?: Record<string, string | number | boolean | (string | number | boolean)[] | undefined>) {
    console.log(url, params);
}

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