Mi rastrillo: de trapos a riquezas

Antecedentes

He estado trabajando como desarrollador front-end durante un año. Mi primer proyecto fue un backend "enemigo". Sucede que este no es un gran problema cuando se establece la comunicación.

Pero en nuestro caso no fue así.

Desarrollamos el código, que se basó en el hecho de que el backend nos envía ciertos datos, cierta estructura y cierto formato. Mientras que el backend consideró normal cambiar el contenido de las respuestas, sin previo aviso. Como resultado, nos llevó horas determinar por qué cierta parte del sitio dejó de funcionar.

Nos dimos cuenta de que necesitábamos verificar lo que devuelve el backend antes de confiar en los datos que nos envió. Creamos una tarea de investigación sobre el tema de la validación de datos desde el front-end.

Este estudio me fue encargado.

He hecho una lista de lo que quiero ser en la herramienta que me gustaría usar para la validación de datos.

Los puntos de selección más importantes fueron los siguientes:

• Descripción declarativa (esquema) de validación, que se transforma en una función de validación que devuelve verdadero / falso (válido, no válido)
• umbral de entrada bajo;
• similitud de datos validados con una descripción de validación;
• facilidad de integración de validaciones personalizadas;
• facilidad de integración de mensajes de error personalizados.

Como resultado, encontré muchas bibliotecas de validación, después de haber revisado el TOP-5 (ajv, joi, roi ...). Todos son muy buenos. Pero me pareció que para resolver el 5% de los casos complejos, condenaron el 95% de los casos más comunes a ser bastante detallados y voluminosos.

Por lo tanto, pensé: ¿por qué no desarrollar algo tú mismo que me convenga?
Cuatro meses después, salió la séptima versión de mi biblioteca de validación de cuarteto .
Era una versión estable, totalmente probada, 11k descargas en npm. Lo usamos en tres proyectos en una campaña durante tres meses.

Estos tres meses han jugado un papel muy útil. Cuarteto ha demostrado todas sus ventajas. No hay problemas de datos desde el backend. Cada vez que cambiaron la respuesta, inmediatamente arrojamos un error. El tiempo dedicado a encontrar las causas de los errores ha disminuido dramáticamente. Prácticamente no quedan errores de datos.

Pero también se identificaron fallas.

Por lo tanto, decidí analizarlos y lanzar una nueva versión con correcciones de todos los errores que se cometieron durante el desarrollo.
Hablaré sobre estos errores arquitectónicos y sus soluciones a continuación.

Rastrillo arquitectónico

"Stroko" - un lenguaje tipificado del esquema

Daré un ejemplo de la versión anterior del esquema para el objeto de la persona.

const personSchema = { name: 'string', age: 'number', linkedin: ['string', 'null'] } 

Este esquema valida un objeto con tres propiedades: nombre - debe ser una cadena, edad - debe ser un número, enlace a una cuenta en LinkedIn - debe ser nulo (si no hay cuenta) o cadena (si hay una cuenta).

Este esquema cumple con mis requisitos de legibilidad, similitud con datos validados, y creo que el umbral de entrada para aprender a escribir dichos esquemas no es alto. Además, dicho esquema se puede escribir fácilmente con una definición de tipo en mecanografiado:

 type Person = { name: string age: number linkedin: string | null } 

(Como puede ver, es más probable que los cambios sean cosméticos)

Cuando tomé una decisión, qué debería usarse para las opciones de validación más frecuentes (por ejemplo, las que se usaron anteriormente). Elegí usar - cadenas, por así decirlo, los nombres de los validadores.

Pero el problema con las cadenas es que no están disponibles para el compilador o el analizador de errores. La cadena 'número' para ellos no es muy diferente de 'numder'.

Solución

La nueva versión del cuarteto 8.0.0. Decidí eliminar del cuarteto: el uso de cadenas como nombres de validadores dentro del esquema.

El diagrama ahora se ve así:

 const personSchema = { name: v.string age: v.number, linkedin: [v.string, null] } 

Este cambio tiene dos grandes ventajas:

• compiladores o analizadores de errores: podrán detectar que el nombre del método está escrito con un error.
• Líneas: ya no se utilizan como elemento de esquema. Esto significa que para ellos puede seleccionar una nueva funcionalidad en la biblioteca, que se describirá a continuación.

Soporte de TypeScript

En general, las primeras siete versiones se desarrollaron en Javascript puro. Al cambiar a un proyecto con Typecript, era necesario adaptar de alguna manera la biblioteca. Por lo tanto, se escribieron declaraciones de tipo para la biblioteca.

Pero esto era un inconveniente: al agregar funcionalidad o al cambiar algunos elementos de la biblioteca, siempre era fácil olvidarse de actualizar las declaraciones de tipo.

También hubo inconvenientes menores de este tipo:

 const checkPerson = v(personSchema) // (0) // ... const person: any = await axios.get('https://myapi.com/person/42') if (!checkPerson(person)) {// (1) throw new TypeError('Invalid person response') } console.log(person.name) // (2) 

Cuando creamos el validador de objetos en la línea (0). Nos gustaría después de verificar la respuesta real del backend en la línea (1) y manejar el error. En la línea (2) para que esa person tipo Persona. Pero esto no sucedió. Desafortunadamente, tal verificación no era un tipo de guardia.

Solución

Decidí reescribir toda la biblioteca del cuarteto en Typecript para que el compilador se ocupara de verificar la correspondencia de la biblioteca con los tipos. En el camino, agregamos a la función que devuelve al validador compilado un parámetro de tipo que determinaría qué tipo de protección es este tipo de validador.

Un ejemplo se ve así:

 const checkPerson = v<Person>(personSchema) // (0) // ... const person: any = await axios.get('https://myapi.com/person/42') if (!checkPerson(person)) {// (1) throw new TypeError('Invalid person response') } console.log(person.name) // (2) 

Ahora en línea (2) person es del tipo Person .

Legibilidad

También hubo dos casos en los que el código se leyó mal: verificar el cumplimiento de un determinado conjunto de valores (verificaciones de enumeraciones) y verificar otras propiedades del objeto.

a) Verificar enumeraciones
Inicialmente, había una idea, en mi opinión, una buena. Lo demostraremos agregando el campo "género" a nuestro objeto.
La versión anterior del circuito se veía así:

 const personSchema = { name: 'string', age: 'number', linkedin: ['null', 'string'], sex: v.enum('male', 'female') } 

La opción es muy legible. Pero como de costumbre, todo salió un poco fuera de lo planeado.
Tener una enumeración declarada en el programa, por ejemplo, esto:

 enum Sex { Male = 'male', Female = 'female' } 

Naturalmente quiero usarlo dentro del circuito. De modo que al cambiar uno de los valores (por ejemplo, 'masculino' -> 'm', 'femenino' -> 'f'), el esquema de validación también debe cambiar.

Por lo tanto, casi siempre la validación de enumeración se escribió así:

 const personSchema = { name: 'string', age: 'number', linkedin: ['null', 'string'], sex: v.enum(...Object.values(Sex)) } 

Lo cual se ve bastante voluminoso.

b) Validación de las propiedades residuales del objeto.

Supongamos que agregamos una característica de este tipo a nuestro objeto (puede tener campos adicionales, pero todos deben ser enlaces a redes sociales), lo que significa que deben ser null o una cadena.

El viejo esquema se vería así:

 const personSchema = { name: 'string', age: 'number', linkedin: ['null', 'string'], sex: v.enum(...Object.values(Sex)), ...v.rest(['null', 'string']) // Rest props are string | null } 

Esta entrada resaltó las propiedades restantes, de las que ya figuran. Es más probable que el uso de un operador de propagación confunda a una persona que quiere comprender este esquema.

Solución

Como se describió anteriormente, las cadenas ya no son parte de los esquemas de validación. Solo quedaron tres tipos de valores de Javascript como esquema de validación. Objeto: para describir el esquema de validación del objeto. Matriz para la descripción: varias opciones de validez. Función (biblioteca generada o personalizada): para todas las demás opciones de validación.

Esta disposición permitió agregar funcionalidad, lo que permitió aumentar la legibilidad del circuito muchas veces.

De hecho, ¿qué pasa si queremos comparar el valor con la cadena 'masculino'? ¿Realmente necesitamos saber algo más además del valor en sí y la cadena 'masculino'?

Por lo tanto, se decidió agregar los valores de los tipos primitivos como un elemento del circuito. Por lo tanto, cuando cumple un valor primitivo en el esquema, esto significa que este es el valor válido que el validador creado de acuerdo con este esquema debe verificar. Será mejor que dé un ejemplo:

Si necesitamos verificar el número para la igualdad 42-mente. Luego lo escribimos así:

 const check42 = v(42) check42(42) // => true check42(41) // => false check42(43) // => false check42('42') // => false 

Veamos cómo esto afecta el esquema de persona (sin tener en cuenta las propiedades adicionales):

 const personSchema = { name: v.string, age: v.number, linkedin: [null, v.string], // null is primitive value sex: ['male', 'female'] // 'male', 'female' are primitive values } 

Usando enumeraciones predefinidas, podemos reescribirlo así:

 const personSchema = { name: v.string, age: v.number, linkedin: [null, v.string], sex: Object.values(Sex) // same as ['male', 'female'] } 

En este caso, se eliminó la ceremonialidad innecesaria en la forma de usar el método enum y usar el operador de propagación para insertar valores válidos del objeto como parámetros en este método.

Lo que se considera un valor primitivo: números, cadenas, caracteres, true , false , null e undefined .

Es decir, si necesitamos comparar el valor con ellos, simplemente usamos estos valores ellos mismos. Y una biblioteca de validación: creará un validador que compara estrictamente el valor con los especificados en el esquema.

Para validar las propiedades residuales, se eligió usar una propiedad especial para todos los demás campos del objeto:

 const personSchema = { name: v.string, age: v.number, linkedin: [null, v.string], sex: Object.values(Sex), [v.rest]: [null, v.string] } 

Por lo tanto, el circuito parece más legible. Y más como anuncios de Typecript.

El validador está relacionado con la función que lo creó.

En versiones anteriores, las explicaciones de error no formaban parte del validador. Se agregaron a una matriz dentro de la función v .

Anteriormente, para obtener una explicación de los errores de validación, tenía que tener un validador con usted (para verificar) yv (para obtener una explicación de invalidez). Todo esto parecía lo siguiente:

a) Agregamos explicaciones al diagrama

 const checkPerson = v({ name: v('string', 'wrong name') age: v('number', 'wrong age'), linkedin: v(['null', 'string'], 'wrong linkedin'), sex: v( v.enum(...Object.values(Sex)), 'wrong sex value' ), ...v.rest( v( ['null', 'string'], 'wrong social networks link' ) ) // Rest props are string | null }) 

Para cualquier elemento del circuito, puede agregar una explicación del error utilizando el segundo argumento de la función del compilador v.

b) Borrar la matriz de explicación

Antes de la validación, era necesario borrar esta matriz global en la que se registraron todas las explicaciones durante la validación.

 v.clearContext() // same as v.explanations = [] 

c) Validar

 const isPersonValid = checkPerson(person) 

Durante esta verificación, si se detectó una validez, y en la etapa de creación del circuito, se le dio una explicación, esta explicación se coloca en la v.explanation global v.explanation .

d) Manejo de errores

 if (!isPersonValid) { throw new TypeError('Invalid person response: ' + v.explanation.join('; ')) } // ex. Throws 'Invalid person response: wrong name; wrong age' 

Como puede ver aquí hay un gran problema. Porque si queremos usar el validador no en el lugar de su creación. Necesitaremos pasarlo no solo a los parámetros, sino también a la función que lo creó. Porque es allí donde se ubica la matriz en la que se agregarán las explicaciones.

Solución

Este problema se resolvió de la siguiente manera: las explicaciones se convirtieron en parte de la función de validación. Lo que se puede entender de su tipo:
tipo Validator = (valor: any, explicaciones?: any []) => boolean

Ahora, si necesita una explicación del error, pasa la matriz a la que desea agregar la explicación.

Por lo tanto, el validador se convierte en una unidad independiente. También se ha agregado un método que puede transformar la función de validación en una función que devuelve nulo si el valor es válido y devuelve una matriz de explicaciones si el valor no es válido.

Ahora la validación con explicaciones se ve así:

 const checkPerson = v<Person>({ name: v(v.string, 'wrong name'), age: v(v.number, 'wrong age'), linkedin: v([null, v.string], 'wrong linkedin') sex: v(Object.values(Sex), 'wrong sex') [v.rest]: v([null, v.string], 'wrong social network') }) // ... const explanations = [] if (!checkPerson(person, explanation)) { throw new TypeError('Wrong person: ' + explanations.join('; ')) } // OR const getExplanation = v.explain(checkPerson) const explanations = getExplanation(person) if (explanations) { throw new TypeError('Wrong person: ' + explanations.join('; ')) } 

Epílogo

Destaqué tres premisas por las cuales tuve que reescribir todo:

• La esperanza de que las personas no se equivoquen al escribir líneas
• Uso de variables globales (en este caso, v.explanation array)
• Las pruebas con pequeños ejemplos durante el desarrollo no mostraron los problemas que surgen cuando se usan en casos realmente grandes.

Pero me alegro de haber realizado un análisis de estos problemas, y la versión lanzada ya se utiliza en nuestro proyecto. Y espero que nos sea útil no menos que el anterior.

Gracias a todos por leer, espero que mi experiencia les sea útil.