Firebase Firestore异步withConverter解析引用类型报错咨询

• 运行环境：Node.js服务端，基于10.2.0版本firebase-admin包调用Firebase能力，代码采用TypeScript编写
• 业务结构：采用商品、分类双集合模型，每个商品必须关联一个分类，Firestore中商品文档通过Document Reference字段关联对应分类文档
• 实现目标：通过withConverter实现商品数据的自动转换，自动解析商品关联的分类引用，拉取分类完整数据填充到返回的商品对象中
• 核心矛盾：Firestore文档读取是异步操作，但withConverter的fromFirestore方法要求同步返回转换后的目标类型，二者约束存在冲突，公开资料未检索到可行的内置实现方案。

错误实现的转换器代码 #

const converter = {
    toFirestore: (data: Product) => data,
    fromFirestore: async (snap: FirebaseFirestore.QueryDocumentSnapshot) => {
        const { category, ...rest } = snap.data();

        const categoryDS = await category.get();
        const materializedCategory = { id: categoryDS.id, ...categoryDS.data() } as Category;

        return { id: snap.id, category: materializedCategory, ...rest } as Product;
    }
};

调用代码 #

const doc = await firestore.collection(COLLECTION).withConverter(converter).doc(id).get();

触发的TypeScript报错 #

Types of parameters 'data' and 'modelObject' are incompatible.
Type 'Promise' is missing the following properties from type 'Product': category, name ts(2769)

数据结构参考 #

10.2.0版本firebase-admin的FirestoreDataConverter类型定义明确要求fromFirestore方法同步返回目标类型T，不支持返回Promise<T>。就算通过as any等方式绕过TypeScript类型校验，SDK内部执行转换逻辑时也不会等待异步任务resolve，最终拿到的doc.data()会是处于pending状态的Promise对象，运行时逻辑完全无法正常使用，因此异步拉取关联数据的逻辑不能放在converter内部实现。

方案1：拆分转换逻辑+批量拉取关联数据（推荐，无N+1性能问题） #

将转换逻辑拆为两部分：converter只负责基础字段的同步映射，关联分类数据在查询完成后统一批量拉取组装，兼顾类型安全和查询性能。

1. 编写基础同步转换器，仅处理非关联字段转换，保留分类的DocumentReference：

import type { FirestoreDataConverter, DocumentReference } from 'firebase-admin/firestore';

// 基础转换后的商品类型：分类字段为引用类型，未做物化
type BaseProduct = Omit<Product, 'category'> & {
    category: DocumentReference<Category>
};

const baseProductConverter: FirestoreDataConverter<BaseProduct> = {
    toFirestore: (model) => {
        // 写入时将分类对象转回对应DocumentReference
        const { id, category, ...rest } = model;
        return {
            ...rest,
            category: firestore.collection('categories').doc(category.id)
        };
    },
    fromFirestore: (snap) => {
        const data = snap.data();
        return {
            id: snap.id,
            ...data
        } as BaseProduct;
    }
};

2. 封装商品查询方法，查询完成后批量拉取关联分类并组装最终数据：

// 单个商品查询
async function getProductById(productId: string): Promise<Product | null> {
    const productSnap = await firestore
        .collection('products')
        .withConverter(baseProductConverter)
        .doc(productId)
        .get();
    
    const baseProduct = productSnap.data();
    if (!baseProduct) return null;

    const categorySnap = await baseProduct.category.get();
    return {
        ...baseProduct,
        category: {
            id: categorySnap.id,
            ...categorySnap.data()
        } as Category
    };
}

// 商品列表查询（批量拉取分类，避免N+1查询）
async function getProductList(): Promise<Product[]> {
    const productQuerySnap = await firestore
        .collection('products')
        .withConverter(baseProductConverter)
        .get();
    const baseProducts = productQuerySnap.docs.map(doc => doc.data());

    // 去重收集所有关联分类的引用
    const categoryRefs = [...new Set(
        baseProducts.map(product => product.category.path)
    )].map(path => firestore.doc(path) as DocumentReference<Category>);

    // 批量拉取全部分类，性能远高于循环单个get
    const categorySnaps = await firestore.getAll(...categoryRefs);
    const categoryMap = new Map<string, Category>();
    categorySnaps.forEach(snap => {
        categoryMap.set(snap.ref.path, {
            id: snap.id,
            ...snap.data()
        } as Category);
    });

    // 组装最终的带完整分类数据的商品列表
    return baseProducts.map(product => ({
        ...product,
        category: categoryMap.get(product.category.path)!
    }));
}

方案2：自定义链式查询包装器 #

如果需要保持类似原生withConverter的链式调用体验，可以基于原生查询对象封装一层自定义包装，在get方法执行完成后自动触发关联数据拉取和组装逻辑，本质和方案1逻辑一致，只是封装形式不同。列表查询场景依然需要做分类引用去重和批量拉取，避免产生大量冗余查询。

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