TypeScript如何约束映射类型仅含指定可选键与额外键？

需求回顾 #

需要实现一个build函数，满足：

• 接收initialState（任意结构的状态对象）和reducers对象
• reducers的键只能是initialState的键的任意可选子集，同时允许额外的extraKey
• 禁止传入不在上述范围内的非法键，也不需要强制包含所有State键

问题分析 #

你之前的两种写法存在的问题：

1. 第一种写法使用必选索引签名 {[TKeys in keyof TWithExtraKey<TState>] : ...}，要求reducers必须包含TWithExtraKey<TState>的所有键，少传就会报错
2. 第二种写法给索引加了?变成可选，但TypeScript中可选索引签名无法严格限制额外键，导致非法键（如asdfas）能被允许传入

解决方案 #

核心思路是用Partial<Record<AllowedKeys, ValueType>>组合：

• Record<AllowedKeys, ValueType>定义键的合法范围，以及对应的值类型
• Partial<...>让所有合法键变为可选，实现“任意子集”的需求

最终类型定义

// 可选：保留你原有的TWithExtraKey类型，也可以直接用keyof TState | "extraKey"
type TWithExtraKey<T> = T & { extraKey: any };

function build<TState>(
  initialState: TState,
  reducers: Partial<Record<keyof TWithExtraKey<TState>, {
    [actionType: string]: (state: TState, action: any) => TState
  }>>
) {
  // 函数逻辑
}

如果需要保留TReducers泛型以获取具体的键类型，也可以写成：

type TWithExtraKey<T> = T & { extraKey: any };

function build<TState, TReducers extends Partial<Record<keyof TWithExtraKey<TState>, {
  [K in keyof TReducers[keyof TReducers]]: (state: TState, action: any) => TState
}>>>(initialState: TState, reducers: TReducers) {
  // 函数逻辑
}

验证示例 #

const initialState = { propOne: 1, propTwo: "hello" };

// ✅ 合法：包含部分State键+extraKey
build(initialState, {
  propOne: { increment: (s) => ({ ...s, propOne: s.propOne + 1 }) },
  extraKey: { reset: () => initialState }
});

// ✅ 合法：仅包含extraKey
build(initialState, { extraKey: { reset: () => initialState } });

// ✅ 合法：仅包含单个State键
build(initialState, { propTwo: { update: (s, a) => ({ ...s, propTwo: a.payload }) } });

// ❌ 非法：包含未授权键'foo'，TypeScript会报错
build(initialState, { foo: { bar: (s) => s } });

// ❌ 非法：reducer返回类型错误，TypeScript会报错
build(initialState, { propOne: { increment: (s) => "wrong type" } });

原理说明 #

• keyof TWithExtraKey<TState>等价于keyof TState | "extraKey"，明确了reducers的合法键范围
• Partial<Record<...>>确保合法键都是可选的，不需要全部包含，同时严格禁止不在范围内的键传入
• 内部的对象类型约束了每个reducer子函数必须符合(state: TState, action: any) => TState的签名

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