TypeScript中如何正确标注Mongoose文档toObject()方法的返回类型

为什么你当前的写法会出现类型不匹配 #

• 你定义的IUserModel继承了Mongoose内置Document类型，该类型在没有接收到明确Lean结构定义时，toObject()方法会自动从Document本身的结构逐层拆解生成嵌套的Pick类型，也就是你看到的Pick<Pick<_LeanDocument<IUserModel>, "_id"...>这种冗长推导结果
• 这种自动生成的Lean类型默认把_id识别为ObjectId类型，还会附带Mongoose内部的可选元属性，和你定义的IUserObject（_id为string、无额外元属性）结构完全不兼容
• 你直接把返回值硬标注为IUserObject时，TS会检测到两边结构的差异（字段类型不匹配、可选性不一致），就会抛出类型不匹配的报错

推荐的标准实现方式（Mongoose 6+ 全版本兼容） #

核心思路是在定义文档类型时，就把你期望的Lean返回值结构作为泛型参数绑定到Document上，让TS自动推导toObject()的返回类型，不需要手动标注。

1. 调整类型定义结构，拆分纯业务字段、Lean文档结构、Document实例结构三类接口：

   import {Schema, model, Document} from 'mongoose'
   
   // 纯业务字段接口，不带任何Mongoose相关属性
   export interface IUser {
     email: string
     password: string
   }
   
   // 定义Lean文档结构，也就是toObject/lean()返回的纯对象结构
   // 这里按你的需求把_id指定为string类型
   export interface IUserLean extends IUser {
     _id: string
   }
   
   // 定义文档实例接口，把Lean结构作为Document的第三个泛型参数传入
   // Document泛型签名：Document<原始文档字段, 查询辅助类型, Lean文档结构>
   export interface IUserModel extends Document<unknown, unknown, IUserLean>, IUser {}
   
   const userSchema = new Schema({
     email: { type: String, required: true },
     password: { type: String, required: true }
   })
   
   export const UsersModel = model<IUserModel>('Users', userSchema)
   

2. 调整业务代码的写法，不需要手动给返回值标注类型：

   const userDoc = await UsersModel.findOne({email})
   // 这行代码的user变量会被TS自动推导为IUserLean类型，和你的预期完全一致
   const user = userDoc.toObject()
   

低版本兼容方案 #

如果使用的Mongoose版本低于5.10，不支持通过泛型绑定Lean结构，可以在toObject()调用时直接做类型断言，不需要给左侧变量硬标注类型：

// 直接在调用处断言为目标类型，避免硬标注带来的结构不匹配问题
const user = userDoc.toObject() as IUserObject

注意事项 #

• 不要把Document实例类型和Lean文档类型混为一谈：Document是带Mongoose内置方法的类实例，Lean文档是无内置方法的纯JS对象，两类类型必须分开维护
• 上述泛型配置同样对lean()查询方法生效：调用await UsersModel.findOne({email}).lean()时，返回值也会自动推导为IUserLean类型
• 不要使用as any绕开类型检查：会失去TypeScript的类型保护能力

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