如何建模带多event/data的Server-Sent Events格式API响应

1. 先定义SSE的通用事件容器 #

SSE响应由多个独立的事件块组成，每个块包含event（事件类型）和data（JSON负载），块之间用空行分隔。先给这个结构建个通用模型：

interface SseEvent<T> {
  eventType: string; // 对应示例中的"balance"
  payload: T; // 对应data字段的JSON内容
}

2. 复用单段JSON的模型 #

你已经能处理单段JSON的建模，直接把这个模型作为上述SseEvent的payload类型。比如示例中的单段JSON可以拆解成这些嵌套模型：

// 核心业务负载模型
interface BalancePayload {
  appId: string;
  network: string;
  addresses: string[];
  balance: {
    deposits: Record<string, unknown>;
    debt: Record<string, unknown>;
    vesting: Record<string, unknown>;
    wallet: Record<string, WalletItem> | {};
    claimable: Record<string, unknown>;
    locked: Record<string, unknown>;
    nft: Record<string, unknown>;
  };
  totals: TotalItem[];
  errors: unknown[];
  app?: AppInfo; // 部分事件可能没有该字段，比如第二个示例
}

// 钱包内资产项模型
interface WalletItem {
  key: string;
  appId: string;
  address: string;
  network: string;
  balanceUSD: number;
  metaType: string;
  displayProps: DisplayProps;
  type: string;
  contractType: string;
  context: TokenContext;
  breakdown: unknown[];
}

// 展示属性模型
interface DisplayProps {
  label: string;
  secondaryLabel: string | null;
  tertiaryLabel: string | null;
  images: string[];
  stats: unknown[];
  info: InfoItem[];
  balanceDisplayMode: string;
}

// 信息项模型
interface InfoItem {
  label: { type: string; value: string };
  value: { type: string; value: string };
}

// 代币上下文模型
interface TokenContext {
  symbol: string;
  balance: number;
  decimals: number;
  balanceRaw: string;
  price: number;
}

// 总计项模型
interface TotalItem {
  key: string;
  type: string;
  network: string;
  balanceUSD: number;
}

// 应用信息模型
interface AppInfo {
  appId: string;
  network: string;
  data: unknown[];
  displayProps: {
    appName: string;
    images: string[];
  };
  meta: { total: number };
}

3. 组合成完整的多事件响应模型 #

把通用事件容器和业务payload模型结合，就得到了完整的多事件SSE响应模型：

type BalanceSseResponse = SseEvent<BalancePayload>[];

4. 实际处理流程 #

• 接收SSE流时，按空行分割成独立的事件块
• 对每个块，提取event字段值和data对应的JSON字符串
• 将data字符串解析为BalancePayload类型
• 把所有解析后的事件存入BalanceSseResponse数组统一处理

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