HarmonyOS 앱 개발을 위한 고도화된 네트워크 레이어 설계 및 구현 가이드

HarmonyOS 앱 개발 시 효율적이고 안정적인 네트워크 레이어를 구축하는 것은 서비스 품질을 결정짓는 핵심 요소입니다. 이번 글에서는 데이터 변환기, 쿼리 파라미터 구성기, 그리고 체계적인 예외 처리를 활용하여 유연하고 확장성 있는 네트워크 통신 구조를 설계하는 방법을 심도 있게 다룹니다.

1. 유연한 데이터 처리를 위한 데이터 변환기 설계

네트워크 통신 시 요청 데이터의 직렬화와 응답 데이터의 역직렬화는 필수적입니다. 인터페이스를 통해 이를 추상화하면 다양한 데이터 형식에 유연하게 대응할 수 있습니다.

/**
 * 네트워크 데이터 변환을 위한 인터페이스
 */
export interface INetworkDataTransformer {
  transformRequest(payload: string | Object | ArrayBuffer): string | Object | ArrayBuffer;
  transformResponse(data: string | Object | ArrayBuffer, type: http.HttpDataType): string | Object | ArrayBuffer;
}

/**
 * JSON 형식을 처리하는 기본 변환기 구현
 */
export class JsonDataTransformer implements INetworkDataTransformer {
  transformRequest(payload: string | Object | ArrayBuffer): string | Object | ArrayBuffer {
    // 객체를 JSON 문자열로 변환
    return JSON.stringify(payload);
  }

  transformResponse(data: string | Object | ArrayBuffer, type: http.HttpDataType): string | Object | ArrayBuffer {
    // 응답 타입에 따른 데이터 파싱
    if (type === http.HttpDataType.STRING && typeof data === 'string') {
      try {
        return JSON.parse(data);
      } catch (e) {
        return data;
      }
    }
    return data;
  }
}

2. 동적 쿼리 파라미터 구성기

GET 요청이나 복잡한 URL 파라미터가 필요한 경우, 맵 형태의 데이터를 URL 쿼리 문자열로 변환하는 로직이 필요합니다. 특히 배열 형태의 파라미터를 처리하는 로직을 포함하여 범용성을 높입니다.

export interface IUrlQueryBuilder {
  build(params?: Map<string, any>): string | undefined;
}

export class StandardQueryBuilder implements IUrlQueryBuilder {
  build(params?: Map<string, any>): string | undefined {
    if (!params || params.size === 0) return undefined;

    const queryParts: string[] = [];
    params.forEach((val, key) => {
      if (Array.isArray(val)) {
        val.forEach((item, index) => {
          queryParts.push(`${encodeURIComponent(`${key}[${index}]`)}=${encodeURIComponent(item.toString())}`);
        });
      } else {
        queryParts.push(`${encodeURIComponent(key)}=${encodeURIComponent(val.toString())}`);
      }
    });

    return queryParts.join('&');
  }
}

3. 네트워크 오류 정의 및 상수 관리

애플리케이션에서 발생하는 다양한 네트워크 상황과 HTTP 상태 코드를 체계적으로 정의하여 에러 핸들링의 일관성을 유지합니다.

export class NetworkCode {
  static readonly OFFLINE = 1000;
  static readonly INVALID_URL = 1001;
  static readonly REQUEST_TIMEOUT = 408;
  static readonly SERVER_ERROR = 500;
  // ... 기타 필요한 코드 정의
}

export abstract class AppError extends Error {
  constructor(public code: number, message: string) {
    super(message);
  }
}

export class ConnectionException extends AppError {
  constructor(code: number, message: string) {
    super(code, message);
    this.name = 'ConnectionException';
  }
}

export class HttpResponseException extends AppError {
  constructor(code: number, message: string) {
    super(code, message);
    this.name = 'HttpResponseException';
  }
}

4. 인터셉터: 네트워크 요청의 파수꾼

요청 전처리(인증 토큰 삽입 등), 응답 후처리(로그 기록 등), 에러 발생 시 공통 로직을 수행하기 위해 인터셉터 구조를 도입합니다.

export interface IHttpInterceptor {
  onPreRequest(options: RequestConfig, client: http.HttpRequest): Promise<void> | void;
  onPostResponse(res: http.HttpResponse, options: RequestConfig): Promise<void> | void;
  onExecutionError(err: AppError, options: RequestConfig): Promise<void> | void;
}

export class LoggingInterceptor implements IHttpInterceptor {
  onPreRequest(options: RequestConfig): void {
    console.info(`[Request] Path: ${options.endpoint}, Method: ${options.method}`);
  }

  onPostResponse(res: http.HttpResponse): void {
    console.info(`[Response] Code: ${res.responseCode}`);
  }

  onExecutionError(err: AppError): void {
    console.error(`[Error] Code: ${err.code}, Message: ${err.message}`);
  }
}

5. 핵심 네트워크 서비스 엔진 구현

앞서 정의한 컴포넌트들을 하나로 통합하여 실제 통신을 담당하는 `NetworkManager` 클래스를 구현합니다.

export interface RequestConfig {
  baseUrl?: string;
  endpoint: string;
  method?: http.RequestMethod;
  params?: Map<string, any>;
  headers?: Record<string, string>;
  body?: any;
  dataType?: http.HttpDataType;
}

export class NetworkManager {
  private baseAddr: string;
  private transformer: INetworkDataTransformer = new JsonDataTransformer();
  private queryBuilder: IUrlQueryBuilder = new StandardQueryBuilder();
  private interceptors: IHttpInterceptor[] = [];

  constructor(baseAddr: string) {
    this.baseAddr = baseAddr;
  }

  addInterceptor(handler: IHttpInterceptor) {
    this.interceptors.push(handler);
  }

  async execute(config: RequestConfig): Promise<http.HttpResponse> {
    const session = http.createHttp();
    let finalError: AppError | null = null;

    try {
      const activeBase = config.baseUrl || this.baseAddr;
      
      for (const interceptor of this.interceptors) {
        await interceptor.onPreRequest(config, session);
      }

      let fullUrl = `${activeBase}${config.endpoint}`;
      const queryString = this.queryBuilder.build(config.params);
      if (queryString) {
        fullUrl += `?${queryString}`;
      }

      if (config.body && this.transformer) {
        config.body = this.transformer.transformRequest(config.body);
      }

      const response = await session.request(fullUrl, {
        method: config.method || http.RequestMethod.GET,
        header: config.headers || { 'Content-Type': 'application/json' },
        extraData: config.body,
        expectDataType: config.dataType || http.HttpDataType.STRING,
        connectTimeout: 30000,
        readTimeout: 30000
      });

      if (response.responseCode !== http.ResponseCode.OK) {
        throw new HttpResponseException(response.responseCode, "Server responded with error");
      }

      if (this.transformer) {
        response.result = this.transformer.transformResponse(response.result, config.dataType || http.HttpDataType.STRING);
      }

      for (const interceptor of this.interceptors) {
        await interceptor.onPostResponse(response, config);
      }

      return response;

    } catch (e) {
      if (e instanceof AppError) {
        finalError = e;
      } else {
        finalError = new ConnectionException(e.code || -1, e.message || "Unknown Error");
      }
      
      for (const interceptor of this.interceptors) {
        await interceptor.onExecutionError(finalError, config);
      }
      throw finalError;
    } finally {
      session.destroy();
    }
  }
}

이와 같은 구조화된 접근 방식은 네트워크 로직을 비즈니스 로직과 분리하여 코드의 가독성을 높이고, 유지보수 비용을 획기적으로 줄여줍니다. 각 컴포넌트는 독립적으로 테스트가 가능하며, 새로운 요구사항이 발생하더라도 기존 코드를 크게 수정하지 않고 확장할 수 있는 유연성을 제공합니다.

태그: HarmonyOS NetworkLayer APIEncapsulation TypeScript HttpRequest

10월 14일 17:45에 게시됨