如何在TypeScript中为接口正确注入属性？仿styled-components实现

问题背景 #

我曾实现过styled-components的主题机制，知道通过扩展DefaultTheme接口能让组件获得TypeScript自动补全。现在自研TypeScript库halt.js，定义了HaltList接口，希望动态注入自定义错误属性，让调用halt()时能自动补全这些属性。

我的操作流程：

• 在自定义配置文件中定义错误对象HALT，导出其类型HaltType；
• 通过test.d.ts扩展@lancejpollard/halt.js中的HaltList接口，使其继承HaltType；
• 将HALT赋值给Halt.list。

但遇到两个问题：

1. 赋值时出现类型不兼容错误，提示note函数的参数类型与HaltLink不匹配；
2. 给HALT指定HaltList类型后，halt()的自动补全失效，参数类型变为never。

解决方案 #

核心是让TypeScript正确识别扩展后的HaltList类型，同时保证赋值时的类型兼容性，避免never类型出现。

1. 正确扩展HaltList接口 #

采用TypeScript的接口合并特性（同名接口自动合并），在test.d.ts中扩展模块内的HaltList，不要直接让它继承HaltType：

// test.d.ts
import { HaltList } from '@lancejpollard/halt.js';

// 定义自定义错误结构类型
type HaltType = {
  userNotFound: {
    message: string;
    note?: (context: { userId: string }) => string;
  };
  invalidPassword: {
    message: string;
  };
};

// 合并到库的HaltList接口中
declare module '@lancejpollard/halt.js' {
  interface HaltList extends HaltType {}
}

2. 保证HALT对象的类型推导与赋值兼容 #

不要手动给HALT指定HaltList类型（会丢失具体属性信息），让TypeScript自动推导其类型，再通过类型断言完成赋值：

// config.ts
import { Halt, HaltList } from '@lancejpollard/halt.js';

// 定义错误对象，让TS自动推导类型
const HALT = {
  userNotFound: {
    message: '用户不存在',
    note: (context: { userId: string }) => `查询的用户ID：${context.userId}`
  },
  invalidPassword: {
    message: '密码错误'
  }
};

// 用类型断言完成赋值，确保类型兼容
Halt.list = HALT as HaltList;

3. 修复note函数的类型不兼容问题 #

确保自定义note函数的参数类型与halt.js中HaltLink的定义对齐：

// 先确认halt.js中HaltLink的定义，假设为：
interface HaltLink {
  message: string;
  note?: (context: Record<string, unknown>) => string;
}

// 调整自定义HaltType的note参数类型以匹配：
type HaltType = {
  userNotFound: {
    message: string;
    note?: (context: Record<string, unknown>) => string;
  };
};

// 若支持泛型上下文，也可通过交叉类型扩展：
type HaltType = {
  userNotFound: HaltLink & {
    note?: (context: { userId: string }) => string;
  };
};

关键注意事项 #

• 禁止手动给HALT指定HaltList类型，否则TypeScript会丢失具体属性信息，导致自动补全失效；
• 接口合并必须放在declare module块内，确保TypeScript识别模块类型扩展；
• 类型断言仅在赋值时使用，避免滥用以保证类型安全。

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