响应解析器：JSON/XML/Protobuf

数据格式千千万，解析器帮你搞定它

一、背景与动机：为什么需要响应解析器？

后端接口的数据格式，从来不是"统一"的。

你可能会遇到这些情况：

• 新接口返回 JSON，老接口返回 XML
• 国内团队用 JSON，海外团队喜欢 Protobuf
• 普通接口返回文本，文件接口返回二进制流
• 第三方 SDK 返回的数据格式千奇百怪

如果每个接口都手动解析，代码会变成这样：

// 接口A：JSON
const dataA = JSON.parse(responseA.result as string);

// 接口B：XML
const dataB = parseXml(responseB.result as string);

// 接口C：Protobuf
const dataC = MyProto.decode(responseC.result as Uint8Array);

// 接口D：自定义格式
const dataD = customParse(responseD.result);

维护起来简直是噩梦。响应解析器就是为了解决这个问题——统一解析入口，自动识别格式，类型安全转换。

解析器要解决什么问题？

1. 格式识别：根据 Content-Type 自动选择解析方式
2. 类型转换：将原始数据转换为业务类型
3. 数据校验：检查必填字段、格式约束
4. 错误处理：解析失败时给出明确错误信息
5. 性能优化：大文件流式解析、缓存解析结果

二、核心原理：策略模式

解析器采用策略模式：定义统一的解析接口，不同格式实现各自的解析策略，运行时根据 Content-Type 选择策略。

flowchart TB
    A[收到响应] --> B{检查Content-Type}
    
    B -->|application/json| C[JSON解析器]
    B -->|application/xml| D[XML解析器]
    B -->|application/x-protobuf| E[Protobuf解析器]
    B -->|text/plain| F[文本解析器]
    B -->|application/octet-stream| G[二进制解析器]
    B -->|其他| H[默认解析器]
    
    C --> I[数据校验]
    D --> I
    E --> I
    F --> I
    G --> I
    H --> I
    
    I --> J{校验通过?}
    J -->|是| K[返回业务数据]
    J -->|否| L[抛出校验错误]
    
    classDef primary fill:#4A90E2,stroke:#2E5C8A,color:#fff
    classDef warning fill:#F5A623,stroke:#C17D10,color:#fff
    classDef error fill:#E74C3C,stroke:#C0392B,color:#fff
    classDef info fill:#7ED321,stroke:#5BA318,color:#fff
    
    class A,K primary
    class C,D,E,F,G,H info
    class I,J warning
    class L error

三、代码实战：五大解析器实现

示例1：解析器接口与注册中心

// network/parser/types.ets

/**
 * 解析器接口
 * 所有解析器必须实现此接口
 */
export interface ResponseParser<T = any> {
  /**
   * 解析响应数据
   * @param raw 原始响应数据
   * @param options 解析选项
   * @returns 解析后的数据
   */
  parse(raw: any, options?: ParseOptions): T;

  /**
   * 此解析器支持的Content-Type
   * 可以是字符串或正则表达式
   */
  readonly contentType: string | RegExp;
}

/**
 * 解析选项
 */
export interface ParseOptions {
  /** 目标类型（用于类型转换和校验） */
  targetType?: new (...args: any[]) => any;
  /** 是否严格模式（校验失败时抛错） */
  strict?: boolean;
  /** 自定义校验规则 */
  validators?: Validator[];
  /** 额外配置 */
  extra?: Record<string, any>;
}

/**
 * 数据校验器接口
 */
export interface Validator {
  validate(data: any): boolean;
  message: string;
}

/**
 * 解析错误类
 */
export class ParseError extends Error {
  constructor(message: string, public readonly raw?: any) {
    super(message);
    this.name = 'ParseError';
  }
}

// network/parser/ParserRegistry.ets
import { ResponseParser, ParseOptions } from './types';

/**
 * 解析器注册中心
 * 管理所有解析器，根据Content-Type选择合适的解析器
 */
export class ParserRegistry {
  private parsers: ResponseParser[] = [];
  private defaultParser: ResponseParser | null = null;

  /**
   * 注册解析器
   * @param parser 解析器实例
   */
  register(parser: ResponseParser): void {
    this.parsers.push(parser);
    console.info(`[ParserRegistry] 注册解析器: ${parser.contentType}`);
  }

  /**
   * 设置默认解析器
   * @param parser 默认解析器实例
   */
  setDefault(parser: ResponseParser): void {
    this.defaultParser = parser;
  }

  /**
   * 根据Content-Type获取解析器
   * @param contentType 响应的Content-Type
   * @returns 匹配的解析器，未找到则返回默认解析器
   */
  getParser(contentType: string): ResponseParser {
    // 遍历所有解析器，查找匹配的
    for (const parser of this.parsers) {
      if (this.matchContentType(parser.contentType, contentType)) {
        return parser;
      }
    }

    // 未找到，使用默认解析器
    if (this.defaultParser) {
      return this.defaultParser;
    }

    throw new Error(`未找到匹配的解析器: ${contentType}`);
  }

  /**
   * 解析响应数据
   * @param raw 原始数据
   * @param contentType Content-Type
   * @param options 解析选项
   */
  parse<T = any>(raw: any, contentType: string, options?: ParseOptions): T {
    const parser = this.getParser(contentType);
    return parser.parse(raw, options) as T;
  }

  /**
   * 匹配Content-Type
   * @private
   */
  private matchContentType(pattern: string | RegExp, contentType: string): boolean {
    if (typeof pattern === 'string') {
      // 支持通配符匹配，如 application/*
      if (pattern.endsWith('/*')) {
        const prefix = pattern.slice(0, -2);
        return contentType.startsWith(prefix);
      }
      return contentType.includes(pattern);
    } else {
      return pattern.test(contentType);
    }
  }
}

示例2：JSON 解析器 - 最常用的解析器

// network/parser/JsonParser.ets
import { ResponseParser, ParseOptions, ParseError, Validator } from './types';

/**
 * JSON解析器
 * 功能：解析JSON格式数据，支持类型转换和数据校验
 */
export class JsonParser implements ResponseParser {
  readonly contentType = 'application/json';

  /**
   * 解析JSON数据
   * @param raw 原始数据（字符串或对象）
   * @param options 解析选项
   */
  parse<T>(raw: any, options?: ParseOptions): T {
    let data: any;

    // 1. 数据预处理
    if (typeof raw === 'string') {
      try {
        data = JSON.parse(raw);
      } catch (error) {
        throw new ParseError(`JSON解析失败: ${error}`, raw);
      }
    } else if (raw instanceof Uint8Array) {
      // 处理二进制JSON数据
      try {
        const decoder = new TextDecoder('utf-8');
        const text = decoder.decode(raw);
        data = JSON.parse(text);
      } catch (error) {
        throw new ParseError(`二进制JSON解析失败: ${error}`, raw);
      }
    } else {
      // 已经是对象，直接使用
      data = raw;
    }

    // 2. 类型转换（如果指定了目标类型）
    if (options?.targetType) {
      data = this.transform(data, options.targetType);
    }

    // 3. 数据校验
    if (options?.strict || options?.validators) {
      this.validate(data, options);
    }

    return data as T;
  }

  /**
   * 类型转换：将普通对象转换为目标类型实例
   * @private
   */
  private transform(data: any, TargetType: new (...args: any[]) => any): any {
    // 如果是数组，递归转换每个元素
    if (Array.isArray(data)) {
      return data.map(item => this.transform(item, TargetType));
    }

    // 创建目标类型实例
    const instance = new TargetType();

    // 复制属性
    for (const key of Object.keys(data)) {
      if (key in instance) {
        instance[key] = data[key];
      }
    }

    return instance;
  }

  /**
   * 数据校验
   * @private
   */
  private validate(data: any, options: ParseOptions): void {
    const validators = options.validators || [];

    // 如果指定了目标类型，生成默认校验器
    if (options.targetType) {
      validators.push(...this.generateDefaultValidators(options.targetType));
    }

    // 执行所有校验器
    for (const validator of validators) {
      if (!validator.validate(data)) {
        throw new ParseError(`数据校验失败: ${validator.message}`, data);
      }
    }
  }

  /**
   * 根据目标类型生成默认校验器
   * @private
   */
  private generateDefaultValidators(TargetType: new (...args: any[]) => any): Validator[] {
    const validators: Validator[] = [];

    // 获取类型的所有属性及其元数据
    // 这里可以通过装饰器或反射获取校验规则
    // 简化示例：只检查必填字段

    // 实际项目中可以配合 class-validator 等库使用

    return validators;
  }
}

示例3：XML 解析器 - 处理传统接口

// network/parser/XmlParser.ets
import { ResponseParser, ParseOptions, ParseError } from './types';

/**
 * XML解析器
 * 功能：解析XML格式数据，转换为JavaScript对象
 * 注意：HarmonyOS原生不支持XML解析，需要使用第三方库或手动实现
 */
export class XmlParser implements ResponseParser {
  readonly contentType = 'application/xml';

  /**
   * 解析XML数据
   * @param raw XML字符串
   * @param options 解析选项
   */
  parse<T>(raw: any, options?: ParseOptions): T {
    let xmlString: string;

    // 数据预处理
    if (typeof raw === 'string') {
      xmlString = raw;
    } else if (raw instanceof Uint8Array) {
      const decoder = new TextDecoder('utf-8');
      xmlString = decoder.decode(raw);
    } else {
      throw new ParseError('XML数据格式错误', raw);
    }

    // 解析XML为对象
    const data = this.parseXml(xmlString);

    // 类型转换
    if (options?.targetType) {
      return this.transform(data, options.targetType) as T;
    }

    return data as T;
  }

  /**
   * 简单XML解析器
   * 注意：这是简化实现，实际项目建议使用专业XML库
   * @private
   */
  private parseXml(xmlString: string): any {
    // 移除XML声明
    xmlString = xmlString.replace(/<\?xml.*\?>/g, '').trim();

    // 使用正则表达式解析（简化版）
    // 实际项目中建议使用 fast-xml-parser 等库
    const result: any = {};
    
    // 匹配标签和内容
    const tagPattern = /<(\w+)>(.*?)<\/\1>/gs;
    let match;

    while ((match = tagPattern.exec(xmlString)) !== null) {
      const tagName = match[1];
      let content = match[2];

      // 检查是否有子标签
      if (/<(\w+)>/.test(content)) {
        // 递归解析子标签
        result[tagName] = this.parseXml(content);
      } else {
        // 简单文本内容
        result[tagName] = this.parseValue(content);
      }
    }

    return result;
  }

  /**
   * 解析值：尝试转换为数字或布尔值
   * @private
   */
  private parseValue(value: string): any {
    // 布尔值
    if (value === 'true') return true;
    if (value === 'false') return false;

    // 数字
    const num = Number(value);
    if (!isNaN(num)) return num;

    // 字符串
    return value.trim();
  }

  /**
   * 类型转换
   * @private
   */
  private transform(data: any, TargetType: new (...args: any[]) => any): any {
    if (Array.isArray(data)) {
      return data.map(item => this.transform(item, TargetType));
    }

    const instance = new TargetType();
    for (const key of Object.keys(data)) {
      if (key in instance) {
        instance[key] = data[key];
      }
    }
    return instance;
  }
}

示例4：Protobuf 解析器 - 高性能二进制协议

// network/parser/ProtobufParser.ets
import { ResponseParser, ParseOptions, ParseError } from './types';

/**
 * Protobuf解析器
 * 功能：解析Protocol Buffers二进制数据
 * 注意：需要配合protobuf定义文件使用
 */
export class ProtobufParser implements ResponseParser {
  readonly contentType = 'application/x-protobuf';

  // 存储已加载的protobuf消息类型
  private messageTypes: Map<string, any> = new Map();

  /**
   * 注册Protobuf消息类型
   * @param typeName 类型名称
   * @param messageType 消息类型（从proto文件生成）
   */
  registerMessageType(typeName: string, messageType: any): void {
    this.messageTypes.set(typeName, messageType);
    console.info(`[ProtobufParser] 注册消息类型: ${typeName}`);
  }

  /**
   * 解析Protobuf数据
   * @param raw 二进制数据
   * @param options 解析选项（必须指定消息类型）
   */
  parse<T>(raw: any, options?: ParseOptions): T {
    // 检查数据类型
    if (!(raw instanceof Uint8Array)) {
      throw new ParseError('Protobuf数据必须是Uint8Array类型', raw);
    }

    // 获取消息类型
    const typeName = options?.extra?.typeName;
    if (!typeName) {
      throw new ParseError('未指定Protobuf消息类型');
    }

    const MessageType = this.messageTypes.get(typeName);
    if (!MessageType) {
      throw new ParseError(`未找到消息类型: ${typeName}`);
    }

    try {
      // 解码Protobuf数据
      const message = MessageType.decode(raw);
      
      // 转换为普通对象
      const data = MessageType.toObject(message, {
        longs: String,
        enums: String,
        bytes: String,
        defaults: true,
        arrays: true,
        objects: true,
        oneofs: true
      });

      return data as T;
    } catch (error) {
      throw new ParseError(`Protobuf解码失败: ${error}`, raw);
    }
  }
}

示例5：解析器集成到网络层

// network/parser/ParserInterceptor.ets
import { Interceptor, Response, RequestConfig } from '../types';
import { ParserRegistry } from './ParserRegistry';

/**
 * 解析器拦截器
 * 功能：自动根据Content-Type选择解析器解析响应数据
 */
export class ParserInterceptor implements Interceptor {
  private registry: ParserRegistry;

  constructor(registry: ParserRegistry) {
    this.registry = registry;
  }

  /**
   * 响应拦截：自动解析响应数据
   */
  async afterResponse<T>(response: Response<any>): Promise<Response<T>> {
    // 获取Content-Type
    const contentType = this.getContentType(response.headers);
    
    if (!contentType) {
      // 没有Content-Type，直接返回原始数据
      return response as Response<T>;
    }

    try {
      // 使用解析器解析数据
      const parsedData = this.registry.parse<T>(
        response.data,
        contentType,
        {
          targetType: (response.config as any).__responseType,
          strict: true
        }
      );

      // 返回解析后的响应
      return {
        ...response,
        data: parsedData
      };
    } catch (error) {
      console.error('[ParserInterceptor] 数据解析失败:', error);
      throw error;
    }
  }

  /**
   * 从响应头获取Content-Type
   * @private
   */
  private getContentType(headers: Record<string, string>): string | null {
    // Content-Type可能有不同的大小写形式
    const keys = Object.keys(headers);
    for (const key of keys) {
      if (key.toLowerCase() === 'content-type') {
        // 移除charset等参数，只保留MIME类型
        return headers[key].split(';')[0].trim();
      }
    }
    return null;
  }
}

示例6：完整使用示例

// 初始化解析器
const parserRegistry = new ParserRegistry();

// 注册各种解析器
parserRegistry.register(new JsonParser());
parserRegistry.register(new XmlParser());
parserRegistry.register(new ProtobufParser());

// 设置默认解析器（JSON最常用）
parserRegistry.setDefault(new JsonParser());

// 初始化网络层
const httpClient = new HttpClient({ baseUrl: 'https://api.example.com' });

// 添加解析器拦截器
httpClient.use(new ParserInterceptor(parserRegistry));

// 使用示例：指定响应类型
interface User {
  id: number;
  name: string;
  email: string;
}

// 请求会自动解析JSON并转换为User类型
const response = await httpClient.get<User[]>('/users', {
  headers: { 'Accept': 'application/json' },
  // 通过自定义字段指定响应类型
  __responseType: User
});

console.log('用户列表:', response.data); // data已经是User[]类型

四、踩坑与注意事项

坑1：Content-Type 大小写问题

问题：后端返回 Application/JSON（大写），解析器匹配失败。

解决：匹配时忽略大小写：

private matchContentType(pattern: string, contentType: string): boolean {
  return contentType.toLowerCase().includes(pattern.toLowerCase());
}

坑2：JSON 解析性能问题

问题：返回数据很大（几MB），JSON.parse 卡顿。

解决：使用流式解析或分页请求：

// 方案1：后端分页
const response = await httpClient.get('/large-data', { 
  params: { page: 1, size: 100 } 
});

// 方案2：使用Web Worker解析（HarmonyOS支持TaskPool）
import taskpool from '@ohos.taskpool';

@taskpool.Decorator
function parseJsonInWorker(jsonString: string): any {
  return JSON.parse(jsonString);
}

const data = await taskpool.execute(parseJsonInWorker, largeJsonString);

坑3：XML 解析的实体编码

问题：XML 中包含 < > 等实体编码，解析后没有还原。

解决：手动替换实体编码：

private decodeEntities(text: string): string {
  const entities: Record<string, string> = {
    '&lt;': '<',
    '&gt;': '>',
    '&amp;': '&',
    '&quot;': '"',
    '&apos;': "'"
  };
  
  return text.replace(/&[^;]+;/g, entity => entities[entity] || entity);
}

坑4：Protobuf 版本兼容

问题：后端升级了 proto 定义，前端解析失败。

解决：使用 Protobuf 的向后兼容特性，忽略未知字段：

const data = MessageType.toObject(message, {
  // 忽略未知字段
  defaults: true,
  // 兼容旧版本
  oneofs: true
});

五、HarmonyOS 6 适配要点

1. TextDecoder API 增强

// HarmonyOS 6 支持更多编码
const decoder = new TextDecoder('utf-8', {
  fatal: true,  // 解码失败时抛错
  ignoreBOM: false  // 是否忽略BOM
});

2. TaskPool 并行解析

// HarmonyOS 6 的 TaskPool 更强大
import { taskpool } from '@kit.ArkTs';

// 使用装饰器定义任务函数
@taskpool.Decorator
function parseLargeJson(jsonString: string): any {
  return JSON.parse(jsonString);
}

// 执行解析（自动在后台线程）
const result = await taskpool.execute(parseLargeJson, largeData);

3. Uint8Array 性能优化

// HarmonyOS 6 对 Uint8Array 操作有优化
const buffer = new Uint8Array(response.data);

// 使用 slice 避免复制
const view = buffer.subarray(start, end);

// 直接转换为字符串（更高效）
const decoder = new TextDecoder();
const text = decoder.decode(buffer);

六、总结

响应解析器是网络层的"翻译官"，让各种格式的数据都能被业务层理解：

记住几个原则：

• ✅ 优先使用 JSON，性能和可读性最佳
• ✅ 大数据用流式解析或后台线程
• ✅ 类型转换要校验，别盲目信任后端
• ✅ 解析失败要给明确错误，方便定位

下一篇我们深入错误处理策略，看看如何构建健壮的网络异常处理体系。

💡 最佳实践提示：建议在项目中定义统一的响应格式（如 { code, message, data }），在 JsonParser 中统一处理，业务层只关心 data 部分。