模块扩充实现类型安全API遇类型推断异常求助

DevOps 小满

2026-8-23

解决Firestore严格类型API的模块扩充类型推断问题

问题根源

多次扩充DocsList接口后，addDoc的泛型推断逻辑错误地将文档类型解析为所有合法文档的联合类型，导致错误的集合-文档组合无法被拦截。这是因为原泛型定义允许集合名被推断为多个合法值的联合类型，进而让文档类型也变成对应联合类型，绕过了一对一的约束。

修复步骤

调整addDoc的泛型定义
移除多余的文档类型泛型，直接将文档参数的类型绑定到集合名对应的DocsList属性，确保集合名与文档类型严格一对一：

export function addDoc<CollectionName extends keyof DocsList>(
  collection: CollectionName,
  doc: DocsList[CollectionName]
) {
  // Firestore 内部逻辑
  return Promise.resolve({} as DocumentReference<DocsList[CollectionName]>);
}

确保模块扩充的正确性
在各个业务模块中，正确使用模块扩充扩展DocsList，每个扩充仅添加当前模块对应的集合与文档类型：

// diary模块
declare module "./types" {
  interface DocsList {
    diary: {
      title: string;
      content: string;
    };
  }
}

// logs模块
declare module "./types" {
  interface DocsList {
    logs: {
      timestamp: number;
      message: string;
    };
  }
}

验证类型约束
此时调用addDoc时，传入错误的文档类型会直接触发类型检查错误：

// 错误：类型“{ title: string; content: string; }”不能赋值给类型“{ timestamp: number; message: string; }”
addDoc("logs", { title: "Test", content: "Wrong doc" });

// 正确：匹配集合与文档类型
addDoc("diary", { title: "My Diary", content: "Today..." });