{"id":690566,"date":"2026-03-21T04:03:38","date_gmt":"2026-03-21T03:03:38","guid":{"rendered":"https:\/\/blog.jetbrains.com\/?post_type=platform&p=690566"},"modified":"2026-03-21T04:03:43","modified_gmt":"2026-03-21T03:03:43","slug":"ampliar-la-funcionalidad-de-qodana-con-inspecciones-personalizadas-de-codigo","status":"publish","type":"platform","link":"https:\/\/blog.jetbrains.com\/es\/platform\/2026\/03\/ampliar-la-funcionalidad-de-qodana-con-inspecciones-personalizadas-de-codigo\/","title":{"rendered":"Ampliar la funcionalidad de Qodana con inspecciones personalizadas de c\u00f3digo"},"content":{"rendered":"

Qodana es una herramienta de an\u00e1lisis est\u00e1tico de c\u00f3digo que lleva las inspecciones de c\u00f3digo<\/a> y los arreglos r\u00e1pidos de los JetBrains IDEs al \u00e1mbito de la integraci\u00f3n continua. Puede ejecutarse en la nube<\/a>, ejecutarse desde un contenedor Docker<\/a>, integrarse<\/a> en procesos de CI\/CD o invocarse a trav\u00e9s de un JetBrains IDE.<\/p>\n

Qodana ya ofrece un impresionante conjunto de inspecciones, pero no se limita a lo que lleva incorporado. Puede a\u00f1adir inspecciones personalizadas para hacer cumplir las especificaciones y convenciones del proyecto.<\/p>\n

Por ejemplo, imagine un proyecto con una convenci\u00f3n de c\u00f3digo espec\u00edfica:<\/p>\n

\n

Cada clase Kotlin de un paquete service<\/code> <\/mark> debe tener un sufijo Service<\/code>.<\/p>\n<\/blockquote>\n

En este caso, com.jetbrains.service.JetComponent<\/code> no se ajustar\u00eda a esta convenci\u00f3n, mientras que com.jetbrains.service.BrainComponentService<\/code> ser\u00eda perfectamente adecuada. Para continuar, crearemos un complemento que implemente esta inspecci\u00f3n, para que Qodana pueda hacer cumplir esta convenci\u00f3n en futuros proyectos.<\/p>\n

Podemos implementar esta convenci\u00f3n de c\u00f3digo creando una inspecci\u00f3n de c\u00f3digo<\/strong> personalizada empaquetada en un complemento<\/strong>. Los complementos de Qodana se desarrollan igual que los de los JetBrains IDEs, es decir, solo tenemos que crear un complemento de IntelliJ Platform que se pueda ejecutar en Qodana. He aqu\u00ed un r\u00e1pido resumen de los pasos que seguiremos:<\/p>\n

    \n
  1. Inicialice el proyecto desde IntelliJ Platform Plugin Template<\/a>.<\/li>\n
  2. Ajuste las propiedades del proyecto y el descriptor del complemento junto con las dependencias necesarias.<\/li>\n
  3. Declare la inspecci\u00f3n local en el descriptor del complemento e implem\u00e9ntelo en Kotlin.<\/li>\n
  4. Compile y empaquete el complemento.<\/li>\n
  5. En el proyecto de prueba de ejemplo, sit\u00fae el artefacto del complemento en un directorio correcto.<\/li>\n
  6. Ajuste el archivo de configuraci\u00f3n de Qodana.<\/li>\n
  7. Ejecute Qodana y mire el informe.<\/li>\n<\/ol>\n

    Preparaci\u00f3n del proyecto del complemento<\/h2>\n

    Para arrancar el proyecto, visite el repositorio IntelliJ Platform Plugin Template<\/a> y haga clic en el bot\u00f3n Use this template<\/em> para crear un repositorio de complementos. Ll\u00e1melo classname-inspection-qodana-plugin<\/code>, copie la URL del proyecto y \u00e1bralo en IntelliJ IDEA. Cuando el proyecto est\u00e9 listo, personalice gradle.properties<\/code> declarando pluginGroup<\/code>, pluginName<\/code> y pluginRepositoryUrl<\/code> seg\u00fan sea necesario. No se olvide de pulsar el bot\u00f3n flotante Sync Gradle Changes<\/em> para aplicar los cambios. Para modificar el identificador \u00fanico del complemento<\/a>, cambie el elemento id<\/code> en el descriptor del complemento plugin.xml<\/code>.<\/p>\n

    Declarar dependencias<\/h3>\n

    Nuestra inspecci\u00f3n de c\u00f3digo tiene como objetivo las clases Kotlin, por lo que necesitamos a\u00f1adir el complemento de Kotlin a las dependencias del complemento de Qodana. El archivo gradle.properties<\/code> requiere que declare:<\/p>\n

    platformBundledPlugins = org.jetbrains.kotlin<\/pre>\n
    Adem\u00e1s, el descriptor del complemento plugin.xml<\/code> debe contener el mismo complemento Kotlin empaquetado en sus dependencias:<\/p>\n
    org.jetbrains.kotlin<\/pre>\n
    De nuevo, recuerde sincronizar los cambios de Gradle pulsando el bot\u00f3n flotante.<\/p>\n
    Adem\u00e1s, la inspecci\u00f3n de clases de Kotlin debe ser compatible con el compilador K2 de Kotlin, habilitado de forma predeterminada desde la versi\u00f3n 2025.1 de IntelliJ Platform. En el descriptor del complemento, declare la extensi\u00f3n org.jetbrains.kotlin.supportsKotlinPluginMode<\/code>.<\/p>\n
        \n<\/pre>\n
    Creaci\u00f3n de la inspecci\u00f3n de c\u00f3digo<\/h3>\n
    El c\u00f3digo real para cualquier inspecci\u00f3n de c\u00f3digo que se dirija a clases Kotlin requiere tres pasos:<\/p>\n
      \n
    1. Declare una extensi\u00f3n com.intellij.localInspection<\/code> en el descriptor del complemento junto con los atributos necesarios y una referencia totalmente cualificada a la clase de implementaci\u00f3n.<\/li>\n
    2. Cree una clase de implementaci\u00f3n, preferiblemente en Kotlin.<\/li>\n
    3. Proporcione un archivo HTML independiente con una descripci\u00f3n de la inspecci\u00f3n, directrices de uso y un ejemplo.<\/li>\n<\/ol>\n
      Declarar la extensi\u00f3n<\/h4>\n
      A\u00f1ada la siguiente declaraci\u00f3n al archivo descriptor del complemento plugin.xml<\/code>:<\/p>\n
          \n<\/pre>\n
      El atributo language<\/code> indica que la inspecci\u00f3n se aplica a los archivos de c\u00f3digo fuente en Kotlin. Es importante activar expl\u00edcitamente la inspecci\u00f3n de forma predeterminada; de lo contrario, Qodana no la ejecutar\u00e1. A continuaci\u00f3n, proporcione un displayName<\/code> descriptivo, legible para el usuario, que se mostrar\u00e1 en el informe y en la configuraci\u00f3n. El atributo groupName<\/code> establece la categor\u00eda de inspecci\u00f3n que se muestra tanto en el informe de Qodana como en la configuraci\u00f3n del IDE. Por \u00faltimo, proporcione un nombre completamente cualificado para la clase de implementaci\u00f3n.<\/p>\n
      C\u00f3digo fuente de inspecci\u00f3n del c\u00f3digo<\/h4>\n
      El complemento de Kotlin proporciona una clase de inspecci\u00f3n base muy \u00fatil para las inspecciones de Kotlin: AbstractKotlinInspection<\/code>. Anule el m\u00e9todo buildVisitor<\/code> y proporcione una instancia de visitante PSI que recorra los elementos de clase de Kotlin de forma segura en cuanto a tipos. classVisitor<\/code> es una pr\u00e1ctica funci\u00f3n similar a la de DSL que devuelve este tipo de visitante PSI y se invoca sobre cualquier clase Kotlin del proyecto que est\u00e9 inspeccionando.<\/p>\n
      package org.intellij.sdk.codeInspection\n\nimport com.intellij.codeInspection.ProblemHighlightType\nimport com.intellij.codeInspection.ProblemsHolder\nimport com.intellij.psi.PsiElementVisitor\nimport org.jetbrains.kotlin.idea.codeinsight.api.classic.inspections.AbstractKotlinInspection\nimport org.jetbrains.kotlin.psi.KtClass\nimport org.jetbrains.kotlin.psi.KtVisitorVoid\nimport org.jetbrains.kotlin.psi.classVisitor\n\nclass ServicePackageClassNameInspection : AbstractKotlinInspection() {\n    override fun buildVisitor(holder: ProblemsHolder, isOnTheFly: Boolean) = classVisitor { klass ->\n        val classNamePsi = klass.nameIdentifier ?: return@classVisitor\n        val classFqn = klass.fqName?.asString() ?: return@classVisitor\n        if (klass.packageLastComponent == \"service\" && !classFqn.endsWith(\"Service\")) {\n            holder.registerProblem(\n                classNamePsi,\n                \"Class name in the 'service' package must have a 'Service' suffix\"\n            )\n        }\n    }\n\n    private val KtClass.packageLastComponent: String\n        get() = containingKtFile.packageFqName.shortName().asString()\n}<\/pre>\n
      La subclase del visitante extrae el nombre de clase de Kotlin totalmente cualificado, inspecciona el elemento del paquete situado m\u00e1s a la derecha y comprueba el sufijo correspondiente. Cualquier nombre de clase incorrecto se notifica a la instancia ProblemsHolder<\/code> con una clase envolvente como elemento PSI y una descripci\u00f3n del problema legible para el usuario.<\/p>\n
      Descripci\u00f3n de la inspecci\u00f3n<\/h4>\n
      Cada inspecci\u00f3n local requiere un archivo de descripci\u00f3n complementario, representado como HTML. Si utiliza el arreglo r\u00e1pido Create description file ServicePackageClassNameInspection.html<\/em>, se crear\u00e1 un archivo llamado src\/main\/resources\/inspectionDescriptions\/ServicePackageClassName.html<\/code> en la ubicaci\u00f3n adecuada. Tambi\u00e9n tendr\u00e1 que proporcionar una descripci\u00f3n que se mostrar\u00e1 en el informe de Qodana y en los ajustes del IDE.<\/p>\n
      Reports class names in the service<\/code> packages that lack the Service<\/code> suffix.<\/pre>\n
      Example:<\/b><\/p>\n
      \n  package com.example.foo.service\n  class SomeComponent {\n    \/* class members *\/\n  }<\/pre>\n
      Compile el complemento<\/h2>\n
      Ya est\u00e1 todo listo: \u00a1es hora de compilar! Ejecute la tarea buildPlugin<\/code> de Gradle y busque el artefacto build\/distributions\/qodana-code-inspection-0.0.1.zip<\/code> disponible en el directorio de salida de Gradle. El archivo JAR se utilizar\u00e1 como artefacto principal en el an\u00e1lisis de Qodana.\u00a0<\/p>\n
      Tenga en cuenta el tipo de artefacto del complemento<\/h4>\n
      Qodana no admite directamente artefactos de complementos ZIP locales que incluyan archivos JAR adicionales o dependencias de terceros. Cualquier complemento se debe empaquetar como un \u00fanico JAR o descomprimir en un directorio espec\u00edfico.<\/p>\n
      Ejecutar Qodana en un proyecto de prueba<\/h2>\n
      Vamos a crear un proyecto de prueba, escrito en Kotlin, que podamos inspeccionar con Qodana ahora que lo hemos extendido con nuestro complemento. Para ejecutar el complemento de Qodana de forma local, aseg\u00farese de que los siguientes dos componentes de software est\u00e9n disponibles en su sistema:<\/p>\n