如何为API返回的复杂对象定义TypeScript类型？

我是TypeScript新手，现在需要处理一个API返回的复杂嵌套对象，结构如下：

{
  "_metadata": {
    "uid": "someuid"
  },
  "reference": [
    {
      "locale": "en-us",
      "close_icon_size": "",
      "icons": {
        "default": {
          "uid": "someuid",
          "dimension": {
            "height": 48,
            "width": 48
          },
          "title": "bell-icon-new.svg",
          "parent_uid": null,
          "is_dir": false,
          "url": "https://url.com"
        }
      },
      "link_text": "Text text tex",
      "styles": {
        "font_size": "24px",
        "width": "1400px",
        "font_color": {
          "colorTheme": "custom"
        },
        "height": "75px",
        "link_text_size": "16px",
        "background_color": {
          "colorTheme": "custom"
        },
        "font_family": "Arial"
      },
      "title": "Text",
      "_content_type_uid": "text text text"
    }
  ]
}

手动为每个键值对定义类型工作量极大，拖慢开发进度，请问该如何高效定义这类对象的类型？

解决方案 #

1. 利用typeof自动推导类型

如果有API返回的真实示例数据，直接用typeof推导整个对象的类型，这是最快的方式：

// 复制API返回的示例数据作为变量
const apiSample = {
  "_metadata": { "uid": "someuid" },
  "reference": [
    {
      "locale": "en-us",
      "close_icon_size": "",
      "icons": {
        "default": {
          "uid": "someuid",
          "dimension": { "height": 48, "width": 48 },
          "title": "bell-icon-new.svg",
          "parent_uid": null,
          "is_dir": false,
          "url": "https://url.com"
        }
      },
      "link_text": "Text text tex",
      "styles": {
        "font_size": "24px",
        "width": "1400px",
        "font_color": { "colorTheme": "custom" },
        "height": "75px",
        "link_text_size": "16px",
        "background_color": { "colorTheme": "custom" },
        "font_family": "Arial"
      },
      "title": "Text",
      "_content_type_uid": "text text text"
    }
  ]
};

// 自动推导整个响应的类型
type ApiResponse = typeof apiSample;
// 提取嵌套类型供单独使用
type ReferenceItem = ApiResponse['reference'][0];
type Icon = ReferenceItem['icons']['default'];

这种方式无需手动编写每个字段，TypeScript会自动根据示例数据生成对应类型。如果字段存在多种可能值（比如某个字段可能是string或null），可以在示例对象中补充这些情况，让推导更准确。

2. 抽离重复结构复用类型

对于嵌套结构中重复出现的部分（比如颜色配置、图标信息），抽离成独立的interface或type，避免重复编写：

// 抽离通用颜色配置类型
interface ColorConfig {
  colorTheme: 'custom' | string;
  // 补充其他通用颜色字段
}

// 抽离图标尺寸类型
interface IconDimension {
  height: number;
  width: number;
}

// 抽离图标类型
interface Icon {
  uid: string;
  dimension: IconDimension;
  title: string;
  parent_uid: string | null;
  is_dir: boolean;
  url: string;
  // 补充其他通用图标字段
}

// 定义单个参考项类型
interface ReferenceItem {
  locale: string;
  close_icon_size: string;
  icons: Record<string, Icon>; // 用Record处理多个键名不同但结构一致的图标
  link_text: string;
  styles: {
    font_size: string;
    width: string;
    font_color: ColorConfig;
    height: string;
    link_text_size: string;
    background_color: ColorConfig;
    font_family: string;
    // 补充其他样式字段
  };
  title: string;
  _content_type_uid: string;
  // 补充其他参考项字段
}

// 定义整个API响应类型
interface ApiResponse {
  _metadata: { uid: string };
  reference: ReferenceItem[];
}

这种方式既保证了类型的清晰度，又减少了重复代码，适合需要长期维护或扩展的场景。

3. 临时使用类型断言快速开发

如果赶进度，可以先用类型断言或any跳过类型检查，后续再逐步补全类型：

// 临时用any快速开发
const response: any = await fetch('/api/data');

// 或者用已定义的（未完全补全的）类型断言
const response = await fetch('/api/data') as ApiResponse;

这是权宜之计，适合紧急开发场景，但建议后续补全类型，避免类型不安全的问题。

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