如何在TypeScript异步函数中用satisfies运算符解决类型问题

问题根源在于SignatureDocumentResponse的data是联合类型，TypeScript无法确定POST请求返回的是单个SignatureDocument还是数组，导致访问id时触发类型报错。使用satisfies运算符可以在保持类型兼容性的同时，提供更精确的类型信息，具体实现如下：

方法1：在Mutation定义中用satisfies约束返回类型 #

直接在创建mutation时，用satisfies指定其返回值既符合SignatureDocumentResponse结构，又明确data为单个SignatureDocument：

import { useMutation } from '@tanstack/react-query';

const createSignatureDocumentMutation = useMutation({
  mutationFn: async (params) => {
    // 替换为你的实际请求逻辑
    const response = await fetch('/api/signature-documents', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(params),
    });
    const result = await response.json();
    return result;
  },
}) satisfies ReturnType<typeof useMutation<SignatureDocumentResponse & { data: SignatureDocument }>>;

定义完成后，TypeScript会明确该mutation返回的data是单个SignatureDocument，此时访问id就不会出现类型错误。

方法2：在mutationFn的返回值中使用satisfies #

也可以在请求完成后，用satisfies直接约束返回结果的类型，确保data是单个对象：

const createSignatureDocumentMutation = useMutation({
  mutationFn: async (params): Promise<SignatureDocumentResponse> => {
    const response = await fetch('/api/signature-documents', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(params),
    });
    const result = await response.json();
    // 用satisfies确保data是单个SignatureDocument，同时兼容SignatureDocumentResponse类型
    return result satisfies SignatureDocumentResponse & { data: SignatureDocument };
  },
});

原理说明 #

satisfies的核心作用是验证值的类型是否符合某个约束，同时保留值本身更精确的类型信息。这里通过SignatureDocumentResponse & { data: SignatureDocument }交叉类型，既保证返回结果兼容原有响应类型定义，又明确了POST请求特有的返回结构，让TypeScript能够安全推断出data的具体类型，从而解决属性访问的类型错误。

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