Manual de Usuario de ApiCatcher

ApiCatcher es una herramienta profesional de depuración de redes iOS creada para desarrolladores, ingenieros de pruebas y personal de resolución de problemas de red. Al establecer una puerta de enlace virtual local, le ayuda a capturar, visualizar, analizar y depurar cómodamente el tráfico HTTP/HTTPS y WebSocket de las aplicaciones que desarrolla.

Este manual detallará cómo configurar y utilizar cada módulo de funciones para ayudar en la depuración del desarrollo diario, las pruebas Mock, el análisis automatizado de API y la resolución de problemas de rendimiento.

Índice

1. Preparación básica: Configuración de certificados y autorización de depuración
2. Filtrado de tráfico: Segmentación precisa de objetivos de depuración
3. Simulación y modificación de API: Reglas de reescritura (Rewrite)
4. Procesamiento personalizado avanzado: Scripts de JavaScript (Script)
5. Pruebas automatizadas: Reproducción combinada (Combo Replay)
6. Monitoreo en segundo plano: Tareas programadas (Scheduled Tasks)
7. Resolución de problemas de calidad y rendimiento: Escaneo de API (API Scan)
8. Herramientas de utilidad: Cifrado/Descifrado y sincronización de escritorio

1. Preparación básica: Configuración de certificados y autorización de depuración

1.1 Instalar y confiar en el certificado CA (Requerido para la depuración HTTPS)

La interacción de datos en las aplicaciones modernas generalmente se cifra basándose en el protocolo HTTPS. Al desarrollar y depurar sus propias aplicaciones, para poder ver correctamente las solicitudes de texto plano y los datos de respuesta de las API, debe configurar y confiar en un certificado de depuración para permitir el descifrado.

ApiCatcher proporciona dos formas de configurar certificados:

1. Usar el certificado CA generado por defecto del sistema (Recomendado para la mayoría de los escenarios): Siga la guía a continuación para instalar el certificado CA exclusivo generado automáticamente para usted por ApiCatcher.
2. Importar su propio certificado (Certificado empresarial): Si necesita utilizar un certificado autofirmado por la empresa, puede omitir esta sección directamente y leer la sección 1.2 Importación de certificados empresariales.

Pasos para usar el certificado CA predeterminado:

1. Haga clic en "Instalar certificado" en la aplicación y el sistema saltará al navegador para descargar el perfil de configuración.
2. Vaya a "Configuración" -> "General" -> "VPN y administración de dispositivos" de iOS e instale el perfil de ApiCatcher descargado.
3. Paso crucial: Vaya a "Configuración" -> "General" -> "Información" -> "Configuración de confianza de certificados", busque el certificado que comienza con ApiCatcher CA y active el interruptor para habilitar la confianza total.

💡 Guía común de resolución de problemas:

• Obteniendo "Tiempo de espera de conexión" o códigos de estado anormales durante la depuración: Generalmente porque el certificado no es de "confianza total" en el paso 3.
• Eliminó la aplicación y la reinstaló: El antiguo certificado de depuración ya no es válido. Debe ir a la configuración del sistema para eliminar el perfil antiguo y repetir el proceso anterior nuevamente.

1.2 Importación de certificados empresariales (Escenario de depuración de intranet empresarial)

Durante el desarrollo y las pruebas internas de la empresa, algunas aplicaciones internas pueden configurar políticas de confianza de certificados específicas (por ejemplo, confiar solo en la CA interna de la empresa).

• Uso: Importe el certificado .pem o .p12 proporcionado por la empresa y vincúlelo con el dominio de prueba interno (por ejemplo, *.corp.internal), para completar apretones de manos TLS legítimos durante la depuración local.
• Nota: Las importaciones o modificaciones de configuración deben realizarse mientras la captura está detenida, y es necesario reiniciar para que surtan efecto.

1.3 Uso de Certificados Personalizados

Para los desarrolladores individuales que no cuentan con un certificado empresarial y no desean usar los certificados predeterminados de ApiCatcher, pueden aprovechar la función de Certificado Empresarial para importar sus propios certificados. Para obtener más detalles, consulte la documentación: Uso de Certificados Personalizados

2. Filtrado de tráfico: Segmentación precisa de objetivos de depuración

Durante el proceso de desarrollo, para eliminar la interferencia de tráfico del sistema subyacente y otras aplicaciones en segundo plano, se recomienda configurar reglas de filtrado para centrar su atención en el proyecto que se está depurando actualmente.

• Lista de bloqueo (Blocklist): Los dominios que aparecen en la lista de bloqueo no se registrarán. Si la lista de permitidos está vacía, se registrarán todas las solicitudes excepto las de la lista de bloqueo de forma predeterminada.
• Lista de permitidos (Allowlist): Siempre que haya reglas en la lista de permitidos, el sistema solo registrará las solicitudes que coincidan con la lista de permitidos, y el resto del tráfico no entrará en el canal de depuración.
• Consejos de configuración: Soporta comodín *. Por ejemplo, ingresar *.example-api.com puede coincidir con todos los subdominios del entorno de prueba bajo ese dominio principal.

💡 Guía común de resolución de problemas:

• No se pueden ver las solicitudes de la aplicación de destino: Verifique si la lista de permitidos está habilitada pero se omitió el dominio de destino, o si el dominio de destino se agregó por error a la lista de bloqueo.
• Nota de sintaxis: Utilice la coincidencia de asterisco básica (por ejemplo, *.api.com); no es necesario escribir expresiones regulares complejas.

3. Simulación y modificación de API: Reglas de reescritura (Rewrite)

Durante el desarrollo paralelo del front-end y el back-end, las API de back-end a menudo aún no están listas, o necesita probar ciertos códigos de estado anormales. A través de reglas de reescritura, puede realizar Mocking de API y pruebas de límites de manera elegante.

3.1 Configuración del alcance (Scope)

Al agregar una regla de reescritura, debe especificar el alcance en el que la regla surte efecto para evitar afectar accidentalmente solicitudes no relacionadas. El sistema proporciona un método de configuración extremadamente fácil y no necesita escribir condiciones de coincidencia complejas:

• Seleccionar dominio/host (Host): Puede seleccionar rápidamente de una lista desplegable de hosts de destino que ya se han capturado, o ingresarlo manualmente. Se admiten comodines (por ejemplo, *.example.com).
• Seleccionar API (Path): Después de seleccionar el host, puede seleccionar directamente API específicas de la lista (el método y la ruta se introducirán automáticamente) o ingresar rutas específicas manualmente (admite la coincidencia de ruta con comodín *, por ejemplo, /api/v1/*).

💡 Consejo de eficiencia: Si selecciona una API existente de la lista, el sistema precompletará (Prefill) automáticamente las plantillas de respuesta Mock posteriores o Headers para usted, ¡lo que le ahorrará mucho tiempo de configuración!

3.2 Acciones de depuración (Rewrite Action)

• Redirigir (Redirect): Enrute la solicitud a otra dirección (por ejemplo, redirija el tráfico de producción a Localhost o a un entorno de prueba).
• Respuesta Mock: No envíe una solicitud de red real, devuelva directamente los datos de prueba preestablecidos (JSON/XML). Admite la configuración de códigos de estado (por ejemplo, simulando excepciones 404, 500), encabezados de respuesta y cuerpos de respuesta.
• Descartar (Drop):
  • Descartar solicitud: Simular una solicitud que no se puede enviar (por ejemplo, escenario de desconexión de red).
  • Descartar respuesta: Simular la falta de respuesta/tiempo de espera del servidor.
• Retraso (Delay): Inyecte retraso de red artificialmente, utilizado para probar el rendimiento de interacción Loading de la aplicación en entornos de red débiles.
• Modificar solicitud/respuesta (Modify):
  • Editar encabezado: Se utiliza para inyectar Tokens de prueba en los encabezados de solicitud o modificar el User-Agent.
  • Reemplazar cuerpo (Body): Reemplazar completamente el contenido del cuerpo de la solicitud o del cuerpo de la respuesta.
  • Buscar y reemplazar cuerpo con expresiones regulares (Regex): Realizar reemplazo de campos de grano fino en JSON. Por ejemplo, use expresiones regulares para reemplazar "status": "pending" con "status": "success" para probar la lógica subsiguiente.

💡 Guía común de resolución de problemas:

• Regla que no tiene efecto: Hay otra regla con mayor prioridad (agregada recientemente) que anula la regla actual.
• El reemplazo de la expresión regular falla: Los datos JSON a menudo contienen sangrías y espacios. Si la expresión regular no tiene en cuenta los caracteres de espacio en blanco (por ejemplo, utilizando \s*), puede provocar que la coincidencia falle. Se recomienda utilizar el panel de "Prueba" integrado para verificar la expresión.

4. Procesamiento personalizado avanzado: Scripts de JavaScript (Script)

Para escenarios de Mock complejos que requieren cálculos dinámicos (como cálculo de firma de marca de tiempo, ensamblaje de datos dinámicos), el motor de secuencias de comandos proporciona el nivel más alto de capacidades de depuración programables.

4.1 Paneles de funciones centrales y herramientas auxiliares

Además de la codificación manual, ApiCatcher proporciona potentes herramientas circundantes para ayudarle a completar la creación y verificación de scripts:

• Auto-generar scripts con IA: No es necesario escribir una sola línea de código a mano. Solo necesita ingresar instrucciones en lenguaje natural (por ejemplo, "Ayúdame a cambiar el valor del campo price en el cuerpo de la respuesta a 9.9 y agregar discount_tag: true"), y el asistente de IA incorporado puede generar y completar directamente el código JS estándar para usted.
• Entorno de prueba local (Test Script): Antes de guardar oficialmente para que surta efecto, puede hacer clic directamente para probar. Puede elegir una solicitud realmente capturada del historial para alimentar el script, y el sistema mostrará intuitivamente los resultados de la comparación de datos antes y después de la modificación junto con los registros de errores, asegurando que su sintaxis sea correcta.
• Alojamiento remoto de scripts (Remote Script): Soporta la entrada directa de una URL de script pública http:// o https://. ApiCatcher cargará y ejecutará localmente el script de la nube, ¡lo cual es muy útil para implementar y mantener uniformemente reglas Mock públicas dentro de un equipo!

4.2 Funciones principales del script

Para saber cómo escribir scripts, lea la documentación: Guía de uso de funciones de script de APICatcher

Solo necesita implementar funciones de ciclo de vida predefinidas:

// Procesar solicitudes salientes
function interceptRequest(request) {
    // request.method, request.url, request.headers, request.body, request.queryParams
    if (request.path === '/api/v1/test') {
        request.headers['X-Debug-Token'] = 'test_token';
    }
    // Acciones de retorno: passthrough, modify, mock, drop
    return { action: 'modify', request: request };
}

// Procesar respuestas recibidas
function interceptResponse(request, response) {
    // response.statusCode, response.headers, response.body
    if (response.body) {
        var data = safeJsonParse(response.body); // Función de análisis seguro incorporada
        if (data) {
            data.mock_field = true;
            response.body = JSON.stringify(data);
            return { action: 'modify', response: response };
        }
    }
    return { action: 'passthrough' };
}

4.2 API avanzadas integradas

• localStore: Se utiliza para el mantenimiento del estado en las solicitudes. Por ejemplo, guardar el estado de autorización en la API de inicio de sesión e inyectarlo automáticamente en las API posteriores.
  • localStore.write('session_id', 'abc')
  • var t = localStore.read('session_id')
• httpClient: Soporta el envío de solicitudes de red adicionales durante la ejecución del script (se utiliza para sincronizar estados externos o buscar configuraciones dinámicas).
  • var res = httpClient.get('https://api.ipify.org')

💡 Guía común de resolución de problemas:

• Errores de sintaxis o de tiempo de ejecución: Utilice el botón "Script de prueba" incorporado para verificar la lógica. Puede usar console.log("...") y ver el resultado en la página de "Registros (Logs)".
• Conflictos del ciclo de vida: Si una solicitud ya ha sido Mocked o Dropped por una "Regla de reescritura" de mayor prioridad, ya no entrará en el flujo de ejecución del script posterior para esa solicitud.

5. Pruebas automatizadas: Reproducción combinada (Combo Replay)

Probar una sola API no puede satisfacer la verificación del flujo de negocios completo (por ejemplo: Iniciar sesión -> Obtener autorización -> Consultar información -> Enviar formulario). Combo Replay soporta la orquestación visual y la regresión automatizada de múltiples API asociadas.

5.1 Pasos de configuración

1. Agregar nodos: Agregue secuencialmente las solicitudes de flujo empresarial desde el historial al lienzo.
2. Establecer dependencias: Cree bordes dirigidos entre nodos para garantizar que las solicitudes se ejecuten estrictamente en secuencia de acuerdo con sus dependencias.
3. Mapeo de parámetros (Inyección de dependencia): Configurar flujo de datos. Inyecte dinámicamente campos específicos de la respuesta de una API ascendente en solicitudes descendentes.

5.2 Detalles de configuración del mapeo de parámetros

• Fuente de extracción: Se puede extraer de responseBody o responseHeader aguas arriba.
  • Ruta de extracción: Si es un cuerpo de respuesta JSON, use JSON Path directamente (por ejemplo, data.session.token).
• Objetivo de inyección: Se puede inyectar en requestHeader, queryParam o requestBody aguas abajo.
• Prefijo opcional (Optional Prefix): Se utiliza para la autocompletación de estándares específicos. Por ejemplo, si el valor extraído es abc, pero el estándar requiere enviar Bearer abc en el encabezado, simplemente complete Bearer aquí para concatenarlo automáticamente.

💡 Guía común de resolución de problemas:

• Parámetro no extraído correctamente: Utilice la estructura de árbol del "Cuerpo de respuesta de muestra" integrado en el nodo del lienzo para hacer clic y seleccionar, evitando errores de jerarquía de formato causados por la escritura manual de la ruta.

6. Ejecución en segundo plano: Tareas programadas (Scheduled Tasks)

Con la capacidad de residencia en segundo plano basada en el proceso VPN, puede usar "Tareas programadas" para ejecutar periódicamente solicitudes específicas o reglas de reproducción combinada. Escenario de aplicación típico: Al desarrollar o probar un evento de "venta flash" de comercio electrónico, debido a que la ventana de tiempo de venta flash es extremadamente corta, los clics manuales a menudo pierden el momento exacto. En este momento, puede configurar una tarea programada para permitir que la API solicite automáticamente la presentación del pedido a alta frecuencia justo antes de que comience la venta flash, lo que lo ayudará a verificar completamente la estabilidad de la concurrencia y la lógica empresarial del enlace de la venta flash.

6.1 Configuración del cronograma (Schedule Type)

• Expresión Cron: Utiliza sintaxis Cron estándar de 5 campos (por ejemplo, */5 * * * * significa ejecutar cada 5 minutos). Puede utilizar la asistencia de IA incorporada para generarlo.
• Configuración personalizada: Admite la configuración detallada del tiempo de inicio, la duración del intervalo y el número máximo de ejecuciones.

6.2 Condiciones de finalización automática (Auto Terminate)

Establezca condiciones de terminación para evitar reintentos sin sentido en situaciones anormales, o para salir automáticamente después de alcanzar la meta:

• Coincidencia de campos JSON: Por ejemplo, en el escenario de "prueba de venta flash", supervise el campo code del resultado devuelto. Una vez que code sea igual a 200 (lo que significa envío de compra exitoso) o igual a 400 (lo que significa que el inventario está vacío y finalizó el evento), se activa la terminación.
• Coincidencia de expresiones regulares: Realizar coincidencia de texto completo en el cuerpo de la respuesta. Siempre que se coincidan las firmas de caracteres como "msg": "Compra exitosa" o "error": "El evento ha finalizado", la tarea se detendrá completa y automáticamente.

💡 Guía común de resolución de problemas:

• La tarea no se puede ejecutar: El sistema iOS tiene estrictos controles en segundo plano. Cuando la memoria es escasa, el proceso VPN puede ser reclamado por el sistema y las tareas programadas se detendrán junto con él.
• No se muestran registros del historial: Las tareas programadas están monitoreando las solicitudes iniciadas directamente por el motor subyacente y no se registrarán en el "Historial" normal de la aplicación principal. Debe ver informes como la tasa de éxito y p95 en el panel de "Historial de ejecución" exclusivo de la tarea.
• Las actualizaciones de reglas no surten efecto: Las tareas programadas se vinculan a una instantánea de la regla en el momento de la creación. Si se cambia la regla original de "Reproducción combinada", la tarea programada debe volver a crearse.

7. Resolución de problemas de calidad y rendimiento: Escaneo de API (API Scan)

En base a los registros de tráfico capturados localmente, proporciona comprobaciones no intrusivas de la calidad, el cumplimiento de la seguridad y la salud del rendimiento de la API. Todo el análisis se completa completamente dentro del bucle de memoria local del dispositivo.

7.1 Motor de escaneo incorporado

• Autoverificación de información confidencial: Soporta la detección de transmisiones de texto plano de números de teléfono, tarjetas de identificación, correos electrónicos y credenciales de servicios en la nube (como AWS Keys, OpenAI API Keys), ayudando a los diseñadores front-end y de API a descubrir omisiones de desensibilización de datos temprano.
• Fuga de pila anormal: Identifica las pilas de llamadas a errores Java, Python o SQL devueltas sin cuidado en los cuerpos de respuesta.
• Análisis de llamadas de alta frecuencia: En función de los umbrales establecidos (por ejemplo, el intervalo de solicitud promedio inferior a un número de milisegundos específico), soluciona problemas sobre si hay llamadas API redundantes causadas por bucles infinitos o una lógica incorrecta.
• Evaluación del consumo de tiempo: Agrega y calcula latencias p95 y p99 para varias API, ayudando a localizar cuellos de botella en el rendimiento del backend.

7.2 Detección de calidad personalizada (Custom Scan)

Puede escribir scripts JS para ejecutar comprobaciones de cumplimiento personalizadas de la empresa.

• Convención de valor de retorno: Si la función considera que la solicitud cumple con las expectativas, devuelve null; Si se detecta incumplimiento (por ejemplo, cuerpo de respuesta demasiado grande, encabezados de seguridad faltantes), devuelva una descripción concisa (≤200 caracteres), y el sistema lo incluirá automáticamente en el informe de escaneo.

💡 Guía común de resolución de problemas:

• No se han analizado resultados: Confirme si el "Alcance de escaneo (Host/Session)" en realidad contiene registros de tráfico JSON/API válidos, en lugar de recursos puramente estáticos. Para asegurar una buena experiencia, hay un límite máximo de registros para un solo escaneo.

8. Herramientas de utilidad: Cifrado/Descifrado y sincronización de escritorio

8.1 Caja de herramientas del desarrollador (Decrypt/Encrypt)

Para hacer frente a las transmisiones de carga útil cifrada, hay herramientas de códec comunes integradas:

• Descifrado AES: Soporta la introducción de claves (Key) y vectores de inicialización (IV) personalizados para descifrar y probar rápidamente las cargas útiles (Payloads).
• Base64 / URL Encode / MD5 / SHA256.
• Procesamiento personalizado: Soporta la escritura de fragmentos de JS de ejecución única para realizar la transformación de datos en el texto seleccionado.

8.2 Sincronización en tiempo real de escritorio (Realtime Sync)

Uso: Si necesita depurar datos con una vista más amplia en una PC, puede enviar paquetes de datos capturados sin problemas a la aplicación de escritorio ApiCatcher Desktop a través del protocolo WebSocket. Configuración:

• Ingrese la dirección WebSocket asignada dentro de la red de área local.
• Asegúrese de pasar la "Conectividad de prueba" primero para verificar el éxito del apretón de manos.
• Resolución de problemas: Asegúrese de que al terminal móvil se le haya otorgado el permiso de "Red local", que el firewall de la PC haya permitido el puerto correspondiente y asegúrese de que ambos estén en la misma subred LAN.