Introducción a la Depuración de Fallos JS en HarmonyOS

La optimización del rendimiento en aplicaciones HarmonyOS 5.0, especialmente aquellas que utilizan JavaScript (JS) o ArkTS, a menudo implica la resolución de errores en tiempo de ejecución. Este artículo examina dos categorías frecuentes de fallos JS que los desarrolladores pueden encontrar: los errores de tipo (TypeError) y los errores generales (Error).

Análisis de Fallos de Tipo (TypeError)

Los TypeError son quizás la clase de fallo JS más común durante el desarrollo y depuración de aplicaciones. Indican que una variable no es del tipo esperado o que se está intentando acceder a propiedades de un valor nulo o indefinido sin una verificaicón previa. Los mensajes de error típicos en los registros suelen ser:

Error name: TypeError
Error message: Cannot read property xxx of undefined

Caso Práctico 1: Fallo al Actualizar Propiedades Relacionadas con Gestos

Este escenario describe un TypeError que ocurre intermitentemente al actualizar propiedades vinculadas a animaciones de gestos.

1. Recopilación del Registro de Fallos JS

Un ejemplo de registro de fallos podría ser el siguiente:

Generated by HiviewDFX@OpenHarmony
================================================================
Device info:xxxx
Build info:xxxx
Fingerprint:9851196f9fed7fd818170303296ae7a5767c9ab11f38fd8b0072f0e32c42ea39
Module name:com.xxx.xxx
Version:1.0.0.29
VersionCode:10000029
PreInstalled:Yes
Foreground:No
Pid:2780
Uid:20020018
Reason:TypeError
Error name:TypeError
Error message:Cannot read property needRenderTranslate of undefined
Stacktrace:
Cannot get SourceMap info, dump raw stack:
    at updateGestureValue (phone/src/main/ets/SceneBoard/recent/scenepanel/recentpanel/RecentGesture.ts:51:51)
    at onRecentGestureActionBegin (phone/src/main/ets/SceneBoard/scenemanager/SCBScenePanel.ts:5609:5609)
    at anonymous (phone/src/main/ets/SceneBoard/scenemanager/SCBScenePanel.ts:555:555)
    at anonymous (phone/src/main/ets/SceneBoard/recent/RecentEventView.ts:183:183)

2. Extracción de Información Clave del Registro

El registro confirma un TypeError, específicamente "Cannot read property needRenderTranslate of undefined". Esto indica un intento de acceder a la propiedad needRenderTranslate de un objeto que es undefined. La traza de la pila (Stacktrace) apunta a la función updateGestureValue como el origen del error. La nota "Cannot get SourceMap info, dump raw stack" sugiere que se trata de una versión de lanzamiento sin mapas de origen, lo que dificulta la conversión de la pila JS a líneas de código eTS exactas; en estos casos, se recomienda una herramienta de análisis de pila de aplicaciones.

3. Identificación del Fragmento de Código Problemático

Basándonos en la traza de la pila y el mensaje de error, el código relevante en la función updateGestureValue es el siguiente:

// Actualiza propiedades relacionadas con la interacción de gestos
public updateGestureValue(screenWidth: number, recentScale: number, sceneContainerSessionList: SCBSceneContainerSession[]) {
    // Cálculo del desplazamiento vertical según el gesto
    this.translationUpY = (this.multiCardsNum >= 1) ? sceneContainerSessionList[this.multiCardsNum - 1].needRenderTranslate.translateY : 0; // Línea de error
    this.translationDownY = (this.multiCardsNum >= 2) ? sceneContainerSessionList[this.multiCardsNum - 2].needRenderTranslate.translateY : 0;
    this.screenWidth = px2vp(screenWidth);
    this.recentScale = recentScale;
}

El error se produce porque sceneContainerSessionList[this.multiCardsNum - 1] o sceneContainerSessionList[this.multiCardsNum - 2] podría ser undefined antes de intentar acceder a su propiedad needRenderTranslate.

4. Solución Propuesta

Para mitigar este tipo de TypeError, es fundamental añadir verificaciones de seguridad antes de acceder a las propiedades de un objeto. El operador de encadenamiento opcional (?.) en TypeScript/JavaScript es ideal para esto:

// Actualiza propiedades relacionadas con la interacción de gestos
public updateGestureValue(screenWidth: number, recentScale: number, sceneContainerSessionList: SCBSceneContainerSession[]) {
    // Cálculo del desplazamiento vertical según el gesto
    this.translationUpY = (this.multiCardsNum >= 1) ?
        sceneContainerSessionList[this.multiCardsNum - 1]?.needRenderTranslate.translateY : 0;
    this.translationDownY = (this.multiCardsNum >= 2) ?
        sceneContainerSessionList[this.multiCardsNum - 2]?.needRenderTranslate.translateY : 0;
    this.screenWidth = px2vp(screenWidth);
    this.recentScale = recentScale;
}

Al utilizar ?., si el elemento de la lista es undefined o null, la expresión entera evaluará a undefined en lugar de lanzar un TypeError, lo que permite que el valor predeterminado (0 en este caso) se asigne.

5. Reflexiones y Recomendaciones

Es crucial considerar la seguridad del acceso a objetos durente la fase de codificación, implementando verificaciones de nulidad necesarias. Sin embargo, en muchos casos, una simple verificación de nulidad solo evita el fallo inmediato. También es importante investigar si el objeto original se construye o se asigna incorrectamente, lo que podría ser la causa raíz subyacente del problema.

Análisis de Fallos de Clase Error

Los fallos de clase Error generalmente son excepciones lanzadas explícitamente por el desarrollador o por una biblioteca JavaScript utilizada en la aplicación. Existen dos escenarios principales para estos errores:

1. Cuando la aplicación encuentra una condición irrecuperable que requiere la terminación de la operación actual, se puede lanzar una excepción JS para detener el flujo de negocio y generar un registro de fallos.
2. Al utilizar interfaces de bibliotecas JS o módulos de terceros que pueden lanzar excepciones, es vital implementar un mecanismo try-catch para capturarlas. De lo contrario, estas excepciones no controladas también terminarán la ejecución del negocio actual.

Caso Práctico 1: Lanzar una Excepción JS Personalizada para Detener la Ejecución

Los desarrolladores pueden lanzar sus propias excepciones JS para indicar un fallo crítico de la lógica de negocio. Esto se logra con la siguiente sintaxis:

throw new Error("ERROR JS PERSONALIZADO: Fallo crítico en la operación");

Al utilizar herramientas de depuración y registro, la traza de la pila de esta excepción permitirá identificar directamente la ubicación donde se lanzó el error. La estrategia para resolver estos problemas es examinar el código circundante y la lógica de negocio para entender por qué se consideró necesario lanzar la excepción y si la condición de error puede ser manejada de otra manera.

Caso Práctico 2: Fallo JS Debido a una Excepción No Manejada de una Interfaz de Terceros

Este caso ilustra un fallo provocado por una excepción lanzada por una API externa que no fue capturada adecuadamente.

1. Contenido Clave del Registro de Fallos JS

Un registro de ejemplo podría mostrar:

Error name:Error
Error message:BusinessError  2501000: Operation failed.
Error code:2501000
Stacktrace:
Cannot get SourceMap info, dump raw stack:
  at onStart (product/phone/build/default/cache/default/default@CompileArkTS/esmodule/release/feature/systemstatus/linkspeedcomponent/src/main/ets/default/controller/NetSpeedController.ts:50:1)
  at NetSpeedController (product/phone/build/default/cache/default/default@CompileArkTS/esmodule/release/feature/systemstatus/linkspeedcomponent/src/main/ets/default/controller/NetSpeedController.ts:43:43)
  at getInstance (product/phone/build/default/cache/default/default@CompileArkTS/esmodule/release/staticcommon/basiccommon/src/main/ets/component/utils/SingletonHelper.ts:17:17)
  at func_main_0 (product/phone/build/default/cache/default/default@CompileArkTS/esmodule/release/feature/systemstatus/linkspeedcomponent/src/main/ets/default/controller/NetSpeedController.ts:325:325)

2. Extracción de Información Clave del Registro

El registro indica un fallo de tipo Error, con un mensaje "BusinessError 2501000: Operation failed.", lo que sugiere una excepción lanzada intencionalmente por alguna lógica de negocio o componente. La traza de la pila apunta al método onStart en el archivo NetSpeedController.ts. De nuevo, la ausencia de mapas de origen requiere una herramienta de análisis de pila para obtener líneas de código eTS precisas.

3. Identificación del Fragmento de Código Problemático

A partir de la traza de la pila, el fragmento de código relevante en NetSpeedController.ts se localiza en el método onStart, donde se realizan llamadas a la función wifiManager.on:

onStart(): void {
    super.onStart();
    console.info('Componente iniciado: onStart');
    // ...
    wifiManager.on('wifiConnectionChange', (data) => {
        this.isConnected = data === 1 ? true : false;
        this.handleUpdateState();
    });
    wifiManager.on('wifiStateChange', (data) => {
        this.isWifiActive = data === 1 ? true : false;
        this.handleUpdateState();
    });
    // ...
}

El análisis revela que la función wifiManager.on puede lanzar un BusinessError 2501000: Operation failed. en ciertas condiciones, y estas llamadas no están envueltas en bloques try-catch.

4. Solución Propuesta

Si la excepción lanzada por la API de terceros no es crítica para la funcionalidad principal de la aplicación y puede ser manejada con gracia, es aconsejable utilizar bloques try-catch para interceptar y gestionar estos errores sin detener la aplicación. La modificación podría ser la siguiente:

onStart(): void {
    super.onStart();
    console.info('Componente iniciado: onStart');
    // ...
    try {
        wifiManager.on('wifiConnectionChange', (status) => {
            this.isConnected = (status === 1);
            this.handleUpdateState(); // O un método específico de manejo de estado de Wi-Fi
        });
    } catch (error) {
        console.error('Error al suscribirse a cambios de conexión Wi-Fi:', error);
        // Lógica de recuperación o manejo de errores específica
    }

    try {
        wifiManager.on('wifiStateChange', (state) => {
            this.isWifiActive = (state === 1);
            this.handleUpdateState(); // O un método específico de manejo de estado de Wi-Fi
        });
    } catch (error) {
        console.error('Error al suscribirse a cambios de estado Wi-Fi:', error);
        // Lógica de recuperación o manejo de errores específica
    }
    // ...
}

Al encapsular las llamadas potencialmente problemáticas en bloques try-catch, el error es capturado, registrado, y la aplicación puede continuar su ejecución sin interrupciones abruptas.

5. Reflexiones y Recomendaciones

Es esencial aprovechar el mecanismo de excepciones de JS de manera flexible durante la fase de codificación para identificar diversos escenarios de error. Además, al integrar interfaces que pueden lanzar excepciones, siempre se debe evaluar si estas excepciones deben ser capturadas para mantener la robustez de la aplicación y evitar impactos negativos en las operaciones críticas del negocio.