excess-property-checking

区分额外属性检查与类型检查

概述

对象字面量会受到特殊处理：TypeScript 会标记未知属性。

这可以捕获结构类型检查可能漏掉的拼写错误和其他问题。但这只适用于对象字面量——理解这一区别有助于避免困惑。

何时使用此技能

• 将对象字面量赋给带类型的变量时
• 不明白为什么有时额外属性会导致错误时
• 使用中间变量后错误消失时
• 处理容易出现拼写错误的可选属性时
• 设计包含许多可选字段的接口时

铁律

ALWAYS remember: Excess property checking only applies to OBJECT LITERALS.

请记住：

• 对象字面量 → 标记额外属性
• 变量赋值 → 应用结构类型检查
• 类型断言 → 绕过额外属性检查

检测：“额外属性”错误

当你看到“对象字面量只能指定已知属性”时，就说明触发了额外属性检查。

interface Room {
  numDoors: number;
  ceilingHeightFt: number;
}

// Excess property checking: Error!
const r: Room = {
  numDoors: 1,
  ceilingHeightFt: 10,
  elephant: 'present',
  // ~~~~~~~ Object literal may only specify known properties,
  //         and 'elephant' does not exist in type 'Room'
};

// Same value via intermediate variable: No error!
const obj = {
  numDoors: 1,
  ceilingHeightFt: 10,
  elephant: 'present',
};
const r2: Room = obj;  // OK - structural typing allows this

为什么要进行额外属性检查

结构类型检查功能强大，但限制宽松。它允许存在额外属性，而这些属性可能会掩盖错误：

interface Options {
  title: string;
  darkMode?: boolean;
}

function createWindow(options: Options) {
  if (options.darkMode) {
    setDarkMode();
  }
}

// Without excess property checking, this typo would be silent:
createWindow({
  title: 'Spider Solitaire',
  darkmode: true  // lowercase 'm' - TYPO!
  // ~~~~~~~ Object literal may only specify known properties,
  //         but 'darkmode' does not exist in type 'Options'.
  //         Did you mean to write 'darkMode'?
});

额外属性检查适用的场景

上下文	是否进行额外属性检查？
将对象字面量赋给带类型的变量	是
将对象字面量作为函数参数	是
将对象字面量作为返回值	是
将变量赋给带类型的变量	否
类型断言	否

interface Point { x: number; y: number; }

// Object literal - checking applies
const p1: Point = { x: 1, y: 2, z: 3 };  // Error: 'z' not in Point

// Variable - checking does NOT apply
const temp = { x: 1, y: 2, z: 3 };
const p2: Point = temp;  // OK

// Type assertion - checking does NOT apply
const p3 = { x: 1, y: 2, z: 3 } as Point;  // OK (but bad practice)

额外属性检查的作用

捕获可选属性中的拼写错误

interface Config {
  logLevel?: 'debug' | 'info' | 'warn' | 'error';
  timeout?: number;
  retries?: number;
}

const config: Config = {
  loglevel: 'debug',  // Error: Did you mean 'logLevel'?
  timeout: 5000,
};

防止属性名称错误

interface User {
  firstName: string;
  lastName: string;
}

const user: User = {
  first_name: 'John',  // Error: Did you mean 'firstName'?
  last_name: 'Doe',    // Error: Did you mean 'lastName'?
};

绕过额外属性检查（有意为之时）

为已知的额外属性使用索引签名

interface Options {
  darkMode?: boolean;
  [otherOptions: string]: unknown;
}

const o: Options = { darkmode: true };  // OK now

使用中间变量

const options = { title: 'Game', extraProp: true };
createWindow(options);  // OK - excess checking skipped

弱类型：相关检查

“弱”类型只包含可选属性。TypeScript 会添加一项特殊检查：

interface LineChartOptions {
  logscale?: boolean;
  invertedYAxis?: boolean;
  areaChart?: boolean;
}

const opts = { logScale: true };  // Note: capital 'S'
setOptions(opts);
// ~~~~ Type '{ logScale: boolean; }' has no properties in common
//      with type 'LineChartOptions'

即使使用中间变量，这项检查也会生效（与常规额外属性检查不同）。

常见错误

错误 1：以为结构类型检查会捕获拼写错误

// ❌ Typo passes silently because no excess property checking
const options = { darkmode: true };  // lowercase 'm'
const config: Options = options;     // No error!

// ✅ Use object literal for catching typos
const config: Options = { darkmode: true };  // Error caught!

错误 2：使用类型断言来消除错误

// ❌ Assertion bypasses the check
const config = { darkmode: true } as Options;

// ✅ Fix the typo instead
const config: Options = { darkMode: true };

错误 3：不明白错误为何会消失

// This has an error
const p: Point = { x: 1, y: 2, z: 3 };

// Why doesn't this?
const temp = { x: 1, y: 2, z: 3 };
const p: Point = temp;

// Answer: Excess property checking only applies to object literals!

抵御压力的操作准则

1. “只要加上 as Type 就行”

压力：“类型断言能让错误消失”

**回应：**断言会绕过安全检查。请修复实际问题。

**行动：**更正属性名称，或更新类型定义。

2. “TypeScript 太严格了”

压力：“额外属性不应该有影响”

**回应：**这可以捕获可选字段中的拼写错误等真实问题。

**行动：**如果确实需要额外属性，请使用索引签名。

3. “用变量就能通过”

压力：“只要使用中间变量就能避开错误”

**回应：**这会掩盖错误。这个错误提示是有原因的。

**行动：**查明额外属性为何存在。

危险信号——停下来重新考虑

• 使用类型断言来消除额外属性错误
• 仅为避开检查而创建中间变量
• 不明白为什么某些赋值会报错，而另一些不会
• 认为 TypeScript 对额外属性的处理前后不一致

常见借口（均不成立）

借口	事实
“这只是一个额外属性”	额外属性往往意味着存在拼写错误
“结构类型检查允许这样做”	对象字面量有更严格的规则，这是有充分理由的
“断言解决了问题”	断言只会掩盖错误，并不能修复错误

快速参考

场景	是否进行额外属性检查？	示例
将对象字面量赋给带类型的变量	是	const x: T = { ... }
将对象字面量作为参数	是	fn({ ... })
将变量赋给带类型的变量	否	const temp = {...}; const x: T = temp;
类型断言	否	{ ... } as T
弱类型（通过变量赋值）	检查是否存在常见属性	特殊情况

核心结论

多余属性检查可以捕获结构类型检查会漏掉的错误。

它只适用于对象字面量，不适用于变量。这是有意为之的——它能捕获属性名中的拼写错误，尤其是可选属性。不要通过类型断言或中间变量绕过它，而应修复根本问题。

参考

基于 Dan Vanderkam 的《Effective TypeScript》，第 11 条：区分多余属性检查与类型检查。