如何用TypeScript正确实现无类型转换的泛型MongoDB仓库？

问题背景 #

我希望仅使用mongodb-Driver和TypeScript实现一个泛型MongoDB仓库，但遇到了一些类型问题。以下是当前代码及简化后的TypeScript错误注释：

import type { Collection, Db, ObjectId, WithId } from 'mongodb';

export interface BaseDocument {
    _id?: ObjectId;
}

export abstract class BaseRepository<T extends BaseDocument> {
    protected readonly collection: Collection<T>;

    constructor(db: Db, collectionName: string) {
        this.collection = db.collection(collectionName);
    }

    public async findById(id: ObjectId): Promise<WithId<T> | null> {
        // No overload matches this call.
        // [...]
        return await this.collection.findOne({ _id: id });
    }

    public async save(document: T): Promise<void> {
        // Argument of type '{ _id: ObjectId | undefined; }' is not assignable to parameter of type 'Filter<T>'.
        // Type '{ _id: ObjectId | undefined; }' is not assignable to type '{ [P in keyof WithId<T>]?: Condition<WithId<T>[P]> | undefined; }'.
        await this.collection.updateOne({ _id: document._id }, { $set: document }, { upsert: true });
    }
}

问题根源 #

1. findById方法中，Collection<T>的findOne期望的Filter类型与{_id: ObjectId}不匹配——因为T的_id是可选字段，类型系统无法确认查询时_id的存在性。
2. save方法中，当document._id为undefined时，{_id: undefined}不符合MongoDB的Filter类型要求；同时混合upsert的逻辑导致类型推导混乱。

修正方案 #

核心调整点 #

• 重构基础文档结构：让BaseDocument不再包含_id字段，由MongoDB的WithId<T>自动注入必填的_id，避免可选性带来的类型冲突。
• 修正集合类型：将集合类型改为Collection<WithId<T>>，确保操作的是MongoDB中实际存储的完整文档（带_id）。
• 拆分save逻辑：通过类型守卫区分新增文档（无_id）和更新文档（有_id），分别使用insertOne和updateOne，避免类型歧义。

修正后的完整代码 #

import type { Collection, Db, ObjectId, WithId, Filter } from 'mongodb';

// 业务文档基础结构，仅定义业务字段，不含_id
export interface BaseDocument {}

export abstract class BaseRepository<T extends BaseDocument> {
    protected readonly collection: Collection<WithId<T>>;

    constructor(db: Db, collectionName: string) {
        this.collection = db.collection<WithId<T>>(collectionName);
    }

    public async findById(id: ObjectId): Promise<WithId<T> | null> {
        // 此时Filter类型完全匹配，因为WithId<T>的_id是必填的ObjectId
        return await this.collection.findOne({ _id: id });
    }

    public async save(document: T | WithId<T>): Promise<void> {
        // 类型守卫：判断是否为已存在的带_id文档
        const isExistingDocument = '_id' in document && document._id instanceof ObjectId;

        if (isExistingDocument) {
            // 更新已有文档，Filter的_id为确定的ObjectId，类型匹配
            await this.collection.updateOne(
                { _id: document._id } as Filter<WithId<T>>,
                { $set: document },
                { upsert: false }
            );
        } else {
            // 插入新文档，直接使用insertOne自动生成_id
            await this.collection.insertOne(document as WithId<T>);
        }
    }
}

补充说明 #

• 调整后的BaseDocument专注于业务字段，WithId<T>负责处理MongoDB的主键逻辑，更贴合实际存储模型。
• 集合类型改为Collection<WithId<T>>后，所有CRUD操作的类型推导都会更准确，避免了原代码中可选_id带来的类型冲突。
• save方法通过类型守卫拆分逻辑，既解决了Filter的类型问题，也让新增/更新的语义更清晰，比单纯依赖upsert更可控。

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