Typescript React项目中如何将API响应映射为带额外属性的内部类型

API 探路者

2026-10-4

实现方案

1. 定义分层类型

先区分API返回类型和前端内部类型，避免类型耦合：

// API返回的事件原始类型
type ApiEvent = {
  identifier: string;
  name: string;
}

// 前端内部使用的带icon的扩展类型
type Event = {
  identifier: string;
  name: string;
  icon: string;
}

2. 维护前端独立图标映射表

映射表完全由前端控制，和后端API定义完全解耦，优先用identifier作为映射key（比name稳定性更高，后端不会随意修改唯一标识）：

// 事件唯一标识与对应图标的映射配置
const EVENT_ICON_MAP: Record<string, string> = {
  "1": "icon-gig",
  "2": "icon-concert",
  "3": "icon-custom-event",
  "4": "icon-other",
  // 后续API新增事件类型，仅需在此处添加对应配置即可
}

// 兜底图标：避免后端返回未提前配置的事件类型时出现异常
const DEFAULT_EVENT_ICON = "icon-default"

3. 封装统一转换逻辑

单独封装转换函数，后续如果需要新增其他扩展字段也可以统一在该函数内处理：

const mapApiEventToInternal = (apiEvent: ApiEvent): Event => {
  return {
    ...apiEvent,
    icon: EVENT_ICON_MAP[apiEvent.identifier] ?? DEFAULT_EVENT_ICON
  }
}

4. 请求时调用转换

拿到API响应后直接遍历调用转换函数即可得到符合内部要求的事件列表：

// 接口请求示例
const fetchEventList = async () => {
  const response = await fetch("/your/api/event/endpoint")
  const rawEventList: ApiEvent[] = await response.json()
  // 转换为前端内部类型
  const internalEventList = rawEventList.map(mapApiEventToInternal)
  return internalEventList
}