Una vez perdí una hora debido a una cadena de consulta. Se estaba enviando un webhook de terceros filter[status]=open&filter[assignee]=me, mi manejador estaba leyendo filter como cadena plana, no pude entender por qué cada solicitud se realizaba sin filtrar. En el momento en que pegué la URL sin procesar en un analizador de cadenas de consulta y la vi resolver en un objeto anidado, el error era obvio: el remitente usaba notación entre corchetes y mi analizador no. Esta guía cubre cómo uso el Analizador de cadenas de consultas en Toolz.dev, cuáles son realmente las partes complicadas de las cadenas de consulta y por qué la misma clave codificada de dos maneras diferentes puede romper silenciosamente una integración.
TL;Dr: Una cadena de consulta es la parte de una URL después del signo de interrogación que transporta parámetros como pares clave-valor. Un analizador de cadenas de consultas lo convierte en JSON estructurado, decodificando codificación porcentual y manejando claves repetidas y matrices de corchetes, y puede crear una cadena de consulta codificada correctamente desde JSON. El Analizador de cadenas de consultas realiza ambas direcciones en su navegador, por lo que puede inspeccionar una URL desordenada o ensamblar una limpia sin salir de la página.
¿qué es una cadena de consulta?
Una cadena de consulta es la sección de una URL que comienza después del primer signo de interrogación y termina en el fragmento, la parte después de un hash. Lleva parámetros como key=value pares unidos por ampersands, entonces ?q=json&page=2 pasa dos parámetros. Los servidores y el código de cliente los leen para filtrar una búsqueda, rastrear una campaña, paginar una lista o transportar el estado entre páginas. Las reglas genéricas para lo que es y lo que no es legal en ese componente provienen de RFC 3986, el estándar URI y las reglas específicas que siguen los navegadores para los parámetros de estilo de formulario provienen de Whatwg estándar de URL.
El problema es que RFC 3986 define la sintaxis del componente de consulta pero no su significado. Dice qué caracteres están permitidos y cómo deben codificarse en porcentaje, pero no dice nada sobre cómo key=value los pares se asignan a una estructura de datos. Esa interpretación se heredó del envío de formularios HTML y diferentes plataformas la ampliaron de manera incompatible. Es por eso que la misma cadena de consulta puede significar cosas ligeramente diferentes para un back-end PHP, un controlador Rails y un front-end JavaScript, y por qué un analizador tiene que hacer explícitas sus convenciones.
Cada clave y valor en una cadena de consulta está codificado por URL para que sobrevivan los caracteres reservados. Un espacio se convierte %20 o un signo más, un signo comercial dentro de un valor se convierte en %26 entonces no se confunde con un separador y se convierte en una barra %2F. Analizar significa dividir los pares y luego decodificar cada lado, y construir significa codificar cada lado y unir los pares. Obtenga la codificación incorrecta en cualquier dirección y los valores se corrompan silenciosamente.
¿qué hace realmente un analizador de cadenas de consultas?
Un analizador toma una URL o una cadena de consulta simple y la convierte en datos estructurados y legibles. En la forma en que elimina todo, incluido el signo de interrogación, ignora el fragmento después del hash, divide los pares, decodifica cada clave y valor, y decide cómo representar claves repetidas y claves entre corchetes. El resultado es un objeto JSON que puede leer y copiar, además de una tabla plana de cada par decodificado, por lo que los valores duplicados y vacíos son obvios.
En Toolz.dev, la herramienta se ejecuta en dos direcciones. En el modo de análisis, pega una URL completa o simplemente su cadena de consulta y obtiene el JSON y la tabla de parámetros. En el modo de compilación, pega un objeto JSON y obtiene una cadena de consulta codificada correctamente, con la opción de elegir cómo se representan las matrices. Cargue la muestra y podrá ver una URL real con un fragmento, una matriz de estilo repetido y un espacio codificado que se resuelve en JSON limpio, luego reconstrúyala.
La razón para utilizar un analizador dedicado en lugar de mirar la URL es que las cadenas de consultas ocultan su estructura. Es casi imposible leer correctamente una URL larga con caracteres codificados, teclas repetidas y notación entre corchetes escaneándola, y las partes más difíciles de leer, la codificación y los duplicados, son exactamente las partes que causan errores. Ver la tabla decodificada al lado del JSON elimina las conjeturas.
¿cómo se manejan las claves repetidas?
La misma clave puede aparecer legalmente más de una vez en una cadena de consulta, como en tags=react&tags=laravel, y no existe una única forma correcta de interpretar eso, que es la raíz de mucha confusión. Diferentes sistemas resuelven duplicados de manera diferente, por lo que un analizador debe permitirle elegir.
La convención más común, y la predeterminada en la herramienta Toolz.dev, es recopilar claves repetidas en una matriz, por lo tanto tags=react&tags=laravel se convierte en {"tags":["react","laravel"]}. Esto coincide con el propio navegador ' URLSearchParams.getAll expone los valores y cómo se comportan la mayoría de los back-ends modernos. Pero algunos marcos mantienen solo la primera aparición y otros solo la última, por lo que la herramienta también ofrece opciones de mantener primero y conservar último. Cuando está depurando una integración, hacer coincidir el comportamiento del analizador 's con el sistema que produjo o consume la URL es lo que hace que el JSON sea significativo.
Esta ambigüedad no es académica. Un problema clásico de seguridad y corrección llamado contaminación de parámetros HTTP existe precisamente porque dos sistemas en una ruta de solicitud pueden resolverse id=1&id=2 de otra manera, uno ve 1 y el otro viendo 2. Poder ver, explícitamente, cómo un analizador determinado resuelve duplicados es la forma más rápida de razonar sobre esa clase de error.
¿qué significan los corchetes como etiquetas[] o filtro[color]?
La notación de corchetes es una convención para codificar matrices y objetos anidados dentro de una cadena de consulta plana, y es donde los analizadores no están de acuerdo. Un corchete vacío posterior marca una matriz, por lo tanto tags[]=react&tags[]=laravel construye {"tags":["react","laravel"]}. Un soporte con nombre marca un objeto anidado, por lo que filter[color]=red&filter[size]=l construye {"filter":{"color":"red","size":"l"}}. Los soportes pueden anidar, así que a[b][c]=1 construye {"a":{"b":{"c":"1"}}}.
Esta sintaxis proviene de cómo PHP y Ruby on Rails serializan los datos de los formularios y de muchas bibliotecas de JavaScript, como qs síguelo. No forma parte de ningún estándar de URL principal, razón por la cual es simple URLSearchParams en el navegador no lo expandirá, dándole una clave literal de tags[] en lugar de una matriz. El analizador Toolz.dev comprende la convención y la expande a la estructura coincidente, y le permite desactivar ese comportamiento cuando desee las claves literales.
Así es como se alinean las principales convenciones, tanto al analizar como al construir:
| Estilo matriz | Codificado como | Analiza a | Común en |
|---|---|---|---|
| Tecla repetida | tags=a&tags=b |
["a","b"] |
Navegadores, la mayoría de los back-ends |
| Soporte vacío | tags[]=a&tags[]=b |
["a","b"] |
PHP, rieles, biblioteca qs |
| Cuadro indexado | tags[0]=a&tags[1]=b |
["a","b"] |
biblioteca qs, datos ordenados |
| Coma unida | tags=a,b |
una cadena para dividir | Algunas API, URL compactas |
Cuando crea una cadena de consulta con la herramienta, elige cuál de ellas emitir, de modo que la salida coincida con lo que espera el sistema receptor. Cuando analiza, la herramienta detecta claves repetidas y notación entre corchetes, y los valores unidos a comas permanecen como una sola cadena porque solo usted sabe si una coma es un separador o parte de los datos.
¿por qué los carteles plus se convierten en espacios?
En la cadena de consulta de una URL, un espacio literal suele codificarse como un signo más en lugar de %20. Esta es una regla heredada del application/x-www-form-urlencoded formato que utilizan los formularios HTML y el Whatwg estándar de URL lo codifica: al analizar datos codificados por formularios, a + está decodificado en un espacio. Entonces q=json+parser debería analizar json parser, y la herramienta Toolz.dev hace esto de forma predeterminada.
La sutileza es que esta regla se aplica al componente de consulta, no a la ruta. Un + en un segmento de ruta hay una ventaja literal. Y ocasionalmente sus datos realmente contienen signos positivos que deben conservarse, como un número de teléfono o una búsqueda C++. En esos casos, la herramienta tiene un interruptor para desactivar más como espacio, por lo que el plus sobrevive al viaje de ida y vuelta. Este es el tipo de detalle que tiene un propósito general Codificador de URL no decidirá por usted, porque no sabe si está mirando una consulta o una ruta.
Hacer esto bien también importa al crear. Cuando la herramienta codifica un valor, codifica porcentualmente caracteres reservados y, de forma predeterminada, utiliza un plus para espacios en el estilo codificado por formulario, por lo que la cadena que produce es una que los navegadores y los back-ends decodificarán de la forma prevista.
¿en qué se diferencia esto de un analizador de URL completo?
Un analizador de cadenas de consulta y un analizador de URL completo se superponen pero responden diferentes preguntas y, usando el correcto, guarda un paso. Un analizador de URL divide un enlace completo en sus componentes, el esquema, el host, el puerto, la ruta, la consulta y el fragmento, y es lo que desea cuando depura hacia dónde va una solicitud o por qué una redirección o una verificación CORS se comporta de manera extraña. Un analizador de cadenas de consultas se centra únicamente en la consulta y la convierte en JSON estructurado y editable, incluidas matrices y claves anidadas, y puede reconstruir la consulta.
los Analizador de URL en Toolz.dev es la herramienta de anatomía: dale un enlace y te muestra la distinción entre host y origen, el puerto predeterminado y las partes de la ruta. El analizador de cadenas de consultas es la herramienta para trabajar con parámetros: dale el mismo enlace y te brinda los parámetros que JSON puedes editar, y luego reconstruye una cadena de consultas a partir de tus ediciones. En la práctica, los uso juntos, el analizador de URL para comprender un enlace y el analizador de cadenas de consultas para cambiar sus parámetros, y si estoy ensamblando un enlace de campaña, accedo a constructor de um en cambio, es un creador de cadenas de consultas especializado en etiquetas analíticas.
¿Cuándo realmente busco esto?
La respuesta honesta es siempre que una URL hace más que apuntar a una página. Lo uso para depurar webhooks y redireccionamientos de OAuth, donde los parámetros transportan toda la carga útil y un valor mal codificado rompe el flujo. Lo uso para leer los parámetros de seguimiento en un enlace de marketing y poder ver exactamente lo que está pasando una campaña. Lo uso para convertir una cadena de consulta que un colega pegó en un chat en JSON. Puedo colocarlo en un dispositivo de prueba y hacer lo contrario, convirtiendo un objeto pequeño en una cadena de consulta para una solicitud manual rápida.
Un ejemplo trabajado hace que la recompensa sea concreta. Un proveedor de OAuth redirige a su aplicación con algo como ?code=abc123&state=xyz789&scope=read%20write&error=. Pegado en el analizador, que se resuelve en un objeto limpio: code y state como sus valores literales, scope decodificado a read write porque %20 es un espacio, y error como una cadena vacía en lugar de una clave faltante, lo que le indica que el proveedor envió el parámetro pero lo dejó en blanco. Al leer que desde la URL sin formato a simple vista, probablemente perderá el espacio codificado scope y malinterpretar lo vacío error, y ambos son exactamente los detalles que deciden si su controlador de devolución de llamada se ramifica correctamente. Ver la tabla decodificada elimina la ambigüedad y, si luego necesita reproducir la solicitud, el modo de compilación convierte su objeto editado nuevamente en una URL de devolución de llamada válida en un solo paso.
Debido a que gran parte de ese trabajo involucra URL que contienen tokens, valores firmados e identificadores de seguimiento, hacerlo en una herramienta que se ejecuta completamente en su navegador es importante. Nada de lo que pega se transmite, registra o almacena, y la herramienta sigue funcionando con la red apagada, por lo que puede inspeccionar de forma segura una URL de devolución de llamada firmada desde la producción en lugar de una copia desinfectada. Presento argumentos más amplios para mantener este tipo de trabajo del lado del cliente en el Privacidad de datos en herramientas en línea guía, y este analizador se encuentra junto a las otras utilidades de enlace y texto que describí en Kit de herramientas para desarrolladores web. Si parte de su trabajo consiste en convertir entradas complicadas en slugs e identificadores limpios, el Slug Generator es un compañero natural para el lado de salida del trabajo de URL.
Preguntas frecuentes
¿qué es una cadena de consulta?
Una cadena de consulta es la parte de una URL después del signo de interrogación que transporta parámetros como pares clave-valor unidos por signo comercial, como ?q=json&page=2. Los servidores y el código del cliente lo leen para filtrar resultados, rastrear campañas o pasar estado. Cada clave y valor está codificado por URL para que sobrevivan los espacios y caracteres reservados, y el fragmento después de un hash no forma parte de él.
¿cómo se manejan las claves repetidas al analizar?
De forma predeterminada, una clave que aparece más de una vez se combina en una matriz, por lo que tags=react&tags=laravel se analiza en {"tags":["react","laravel"]}. Puede cambiar para conservar solo el primer valor o solo el último valor, porque diferentes back-ends resuelven duplicados de manera diferente y desea que el JSON coincida con el sistema al que se dirige.
¿qué significan los corchetes como etiquetas[] o filtro[color]?
La notación de corchetes codifica matrices y objetos anidados dentro de una cadena de consulta plana. tags[]=react&tags[]=laravel crea una matriz y filter[color]=red&filter[size]=l crea el objeto anidado {"filter":{"color":"rojo" "tamaño":"l"}}. Es común en PHP, Rails y bibliotecas de formularios, por lo que el analizador lo expande a la estructura coincidente y puede desactivarlo para conservar las claves literales.
¿Por qué un signo más se convierte en un espacio?
En la cadena de consulta de una URL, un espacio literal a menudo se codifica como un signo más, una regla heredada del envío de formularios HTML, por lo que el analizador convierte + nuevamente a un espacio de forma predeterminada. Si sus datos contienen signos más reales que deben conservarse, como C++ o un número de teléfono, desactive la opción más como espacio y se conservará el más.
¿puedo crear una cadena de consulta desde JSON?
Sí. Cambie al modo de compilación y pegue un objeto JSON de pares clave-valor. El porcentaje de herramienta codifica cada clave y valor y los une con signo comercial, y puede elegir cómo se codifican las matrices: claves repetidas, corchetes vacíos, corchetes indexados o una lista separada por comas, para que la salida coincida con lo que espera el sistema receptor.
¿cuál es la diferencia entre este y un analizador de URL completo?
Un analizador de URL completo divide una URL completa en esquema, host, puerto, ruta, consulta y fragmento. Un analizador de cadenas de consultas se centra únicamente en la consulta, la convierte en JSON editable estructurado que incluye matrices y claves anidadas, y puede reconstruir la consulta. Utilice el analizador de URL para inspeccionar un enlace y esta herramienta para leer o cambiar sus parámetros.
¿Maneja una URL completa o solo la parte de consulta?
Ambos. Si pega una URL completa, el analizador deja todo incluido el signo de interrogación e ignora el fragmento después del hash, por lo que obtiene solo los parámetros. Si pega una cadena de consulta simple sin signo de interrogación, se analiza tal cual, lo cual resulta útil cuando solo copió los parámetros.
¿Mi URL se envía a alguna parte?
No. El análisis, la decodificación y la codificación se ejecutan como JavaScript en su navegador, por lo que no se transmite, registra ni almacena nada. Puede confirmarlo mirando la pestaña de red mientras analiza una URL o desconectándose de Internet, porque la herramienta sigue funcionando sin conexión una vez que la página se ha cargado.
Inspeccionar o ensamblar parámetros con el gratis Analizador de cadenas de consultas. Analiza una URL en JSON y crea una cadena de consulta, manejando claves repetidas, matrices de corchetes y codificación, completamente en su navegador.
