Arquitectura de complementos: cómo TypeScript nos permite pintar por números

Hola. Mi nombre es Lilia y soy una gerente de ingeniería en Snyk que lidera el equipo de servicios técnicos. Cuando comencé en Snyk hace aproximadamente cuatro años, tenía muy poco entendimiento de los desafíos que tendría por delante. Después de liderar un equipo de ingeniería que construía sitios web predefinidos en una pequeña agencia, mis expectativas eran que Snyk sería similar, pero tal vez más desafiante. Y ciertamente no estaba preparada para tener que entender de repente cada administrador de paquetes, como un registro y un sistema de gestión de control de código fuente que se haya construido alguna vez. Y todo esto porque me uní al equipo de ecosistemas.

Recuerdo que una de las primeras características fue agregar soporte para npm6. Esta es la primera vez que npm introdujo archivos de registro. Así que esto agregó un nuevo sabor de npm a la plataforma. Luego vinieron Yarn, Yarn Workspaces, Gradle, Go, diferentes sabores de Go, Kotlin, SPT, Cocoapods. Parecía ser una corriente interminable de administradores de paquetes y herramientas que necesitaban ser soportados. Y a veces las nuevas versiones eran completamente incompatibles con las versiones anteriores y requerían reescribir completamente el soporte.

No solo necesitábamos extender el soporte y mantenernos al día con los clientes que migraban a todas estas diferentes herramientas y versiones, también necesitábamos mantenernos al día con nuestro propio crecimiento. Nuevos miembros del equipo se unen todo el tiempo, y la incorporación al código puede llevar tiempo, ya que es complejo. Una vez que hemos agregado soporte para el administrador de paquetes una o dos veces, comenzamos a ver algunos patrones, y luego podemos acelerar. Sin embargo, cuando un nuevo miembro del equipo se une, tienen que comenzar desde cero, y les lleva otras 2 o 3 veces antes de comenzar a ver esos mismos patrones que tú. Así que necesitábamos pensar en cómo acelerar. A medida que el soporte llevaba más tiempo, a veces se pasaban por alto ciertas áreas del producto donde se necesitaba extender el soporte. Así que necesitábamos acelerar, pero también necesitábamos asegurarnos de cubrir cada área del producto donde se necesitaba extender el soporte. Necesitábamos una arquitectura de plugins.

La arquitectura de plugins consta de dos componentes principales, el sistema central y los propios módulos de plugins. Y los plugins interactúan con el sistema central a través de una interfaz predefinida. En ese momento, teníamos algo de eso en su lugar, pero no en la medida que queríamos. Con algo de tiempo, pudimos comenzar a ver cuál es la responsabilidad del sistema central y cuál es la responsabilidad de los plugins. Sin embargo, algunos de estos comportamientos aún pueden ser bastante confusos. Así que también tienes un poco de desafío allí. Entonces, cuando se presentó una oportunidad para construir una nueva biblioteca, utilizando la arquitectura de plugins, pudimos utilizar lo que aprendimos al introducir TypeScript muy temprano en nuestra aplicación, así como lo que aprendimos y las partes que nos gustaron y no nos gustaron de nuestra arquitectura de plugins existente. Y pudimos juntar todos nuestros aprendizajes y crear algo nuevo e intentarlo de nuevo. Y descubrimos que con una configuración inicial, podíamos apoyarnos en TypeScript y seguir la pista de los errores de TypeScript para ayudarnos. Así que veamos un ejemplo para entender cómo puedes seguir los errores de TypeScript como pistas.

Vamos a extender un CLI que proporciona alguna funcionalidad simple relevante para trabajar con diferentes sistemas de gestión de control de origen, herramientas como GitHub y GitLab. Así que vamos a sumergirnos.

Entonces, nuestro ejemplo de hoy es un CLI realmente simple llamado Asistente de Gestión de Control de Origen. Lo llamaremos SEM Helper abreviado. Así que echemos un vistazo aquí y básicamente tenemos un comando llamado Describir y estamos llamando a Describir GitHub y luego espera un par de parámetros, el propietario y el repositorio. Así que estamos tratando de describir un repositorio. Así que si le damos un propietario y un repositorio también, estamos devolviendo información muy simple, si el repositorio está bifurcado y si está archivado también.

Así que si lo vemos conceptualmente, básicamente tenemos un sistema central que puede decir repo.describe, por ejemplo. Y luego tenemos un conjunto de plugins que se pueden llamar, en este caso, es específicamente GitHub. Y devolvemos algunos metadatos muy simples, por ejemplo, para verdadero, archivado, falso. Así que vamos a entrar en el código y echemos un vistazo a lo que hemos configurado aquí.

Es una configuración muy simple, básica, lista para usar, siguiendo la documentación de TypeScript. Verás aquí que tenemos un índice de origen y estamos usando Oclef CLI. Así que no tenemos que preocuparnos por el análisis de parámetros ni nada de eso. Verás que también hay un directorio de comandos, así como un directorio de plugins de librería. En los comandos aquí, tenemos describir GitHub, que es lo que acabas de ver ejecutándose. Y en describir GitHub, tiene algunos argumentos, tiene un ejemplo, una descripción y la funcionalidad principal aquí es cargar un plugin, cargar un plugin de GitHub, y luego estamos llamando a plugin.describir y enviándole el repositorio y eso. Y eso es todo. Y luego en los plugins de librería, hay un directorio de GitHub en el que hay un poco de código, que es obtener credenciales y luego la llamada a la API de descripción en sí. Así que necesitamos poder obtener el token y luego estamos llamando en este caso, OctoKit rest, que es una biblioteca de GitHub y llamando al repositorio específico para obtener la información que queremos. Así que echemos un vistazo de nuevo dentro de los plugins. También tenemos un archivo de índice y tipos. Así que en el archivo de índice, verás que hay nuestra función de carga de plugin y toma un tipo de SCM, que son todos los SCM admitidos. Este es un enum de todos los SCM admitidos. Y queremos poder admitir también GitLab. Así que hagámoslo. Así que vamos a agregar y registrar GitHub así como GitLab como un plugin admitido aquí. Así que vamos a decir, GitLab equals GitLab. De acuerdo, y veamos qué pasa. Así que ahora que hemos hecho eso, verás que hay en nuestro archivo de carga de plugin en ese índice.

Tenemos un par de errores de TypeScript. Y verás lo mismo si ejecutas npm run build. Así que tenemos tres lugares donde ahora tenemos un error. Y dice que falta la propiedad GitLab en el tipo pero es requerida. Así que aquí puedes ver que se espera que llenemos el nombre de la entidad con la que estamos tratando. Entonces, para GitHub es un repositorio, para GitLab también es un repositorio. Así que agreguemos eso, repositorio de GitLab.

Bien, luego el tipo de entidad principal para GitHub es la organización. Así que para GitLab también necesitamos el equivalente que también es organización. Y el último es los plugins. Así que aquí tenemos un tipo que básicamente dice que cada SCM admitido debe registrarse aquí como un plugin. Así que registremos nuestro nuevo plugin de GitLab. Y parece que ahora tenemos que crear un archivo para que GitLab tenga plugins.

Bien, hagámoslo. Así que en GitLab index, exportemos nada. Solo un objeto vacío por ahora. Y registremoslo aquí. Y veamos qué obtenemos. Bien, eso está todo hecho. Oh espera, hay un error aquí. ¿Qué no le gusta? Oh, perfecto. Nos está diciendo que nos faltan dos funciones que son requeridas para cada plugin. Una llamada obtener credenciales y otra llamada describir. Y puedes ver que están definidas aquí. Así que cada una de estas debe ser una performance a la interfaz cliente SCM, donde necesitamos tener una función llamada obtener credenciales que devuelva credenciales de una forma determinada, así como la función describir que devolverá si está archivado o bifurcado. Y hasta que completemos esto y devolvamos el tipo correcto, este error no desaparecerá. Entonces, básicamente, al registrar un nuevo tipo de plugin que se va a admitir, TypeScript nos ha indicado los tres lugares donde necesitábamos registrar o tener una implementación específica de GitLab. E incluso cuando hemos agregado solo un plugin básico, no fue suficiente porque hemos definido una interfaz. Por lo tanto, se espera que devolvamos la información correcta. Así que vamos a implementar todas las partes faltantes, y luego veamos si todos los errores han desaparecido.

Ahora que hemos agregado todo el código necesario para que GitLab también funcione llamando a las API relevantes de GitLab, podemos ejecutar una CLI con el comando describe-gitlab como puedes ver, y estamos obteniendo los mismos resultados. Así que ahora soportamos tanto los repositorios de GitHub como los repositorios de GitLab. Y todo esto siguiendo un par de errores, realmente de TypeScript.

Entonces, ¿cómo pudimos hacer eso? El truco estaba realmente en tener la configuración correcta, donde cualquier variable, cualquier funcionalidad que necesite provenir del plugin debe registrarse como requerida. Así que tenemos nuestros SCM admitidos. Y verás que lo estamos usando en todas partes donde esperamos que la funcionalidad se extienda para el SCM. Así que aquí en el nombre de la entidad, aquí en el nombre de la entidad principal, aquí en el propio plugin. Y para el plugin, hemos tipado lo que se espera. Así que tenemos toda la interfaz escrita. Tenemos las funciones esperadas que debe implementar, que son obtener credenciales y describir. También podemos extender y agregar una nueva función que debe implementar. Tal vez sea un delete para eliminar el repositorio. Y tan pronto como hagamos eso, vamos a obtener errores de TypeScript en todos los plugins, porque ahora estos plugins ya no se ajustan a la interfaz definida.

Entonces, al tener la configuración correcta de antemano y asegurarse de registrar toda la funcionalidad necesaria con tipos, puedes registrar un nuevo plugin y luego seguir la pista de los errores de TypeScript para completar los espacios en blanco. Y eso significa que solo necesitas saber el lugar donde debes agregar el nuevo plugin como registrado, como admitido. Y no necesitas leer el resto del código porque ya tienes interfaces definidas que puedes implementar y completar los espacios en blanco. Así que no es necesario entender cómo funciona el plugin de GitHub, no es necesario entender cómo funciona el código principal del sistema también. Siempre y cuando sepas dónde registrar el soporte para el nuevo plugin. Al hacer estas cosas simples, pudimos agregar el plugin sin profundizar demasiado en el funcionamiento interno del código principal. Así que puedes reducir el tiempo de producción porque si sabes exactamente en qué parámetros necesitas escribir el código, las funciones que necesitas implementar, qué devuelven esas funciones, dónde se usan esas funciones, en qué caso aquí TypeScript te lo dirá. Entonces no necesitas familiarizarte con el código principal en absoluto. Preparar todo esto de antemano cuando estás configurando la arquitectura del repositorio tiene enormes beneficios más adelante, y puedes reducir el tiempo de incorporación al repositorio. No es necesario aprender cómo funciona todo el código en conjunto antes de poder contribuir a él. Solo necesitas aprender las áreas necesarias si te apoyas en TypeScript, y si realmente necesitas cambiar el código principal del sistema, puedes familiarizarte con él en ese momento. Así que te pido que ahorres tiempo para ti mismo en el futuro. Prueba la arquitectura de plugins con TypeScript en tu próximo proyecto. Gracias. ♪MÚSICA♪