{"id":690565,"date":"2026-03-21T03:59:44","date_gmt":"2026-03-21T02:59:44","guid":{"rendered":"https:\/\/blog.jetbrains.com\/?post_type=platform&p=690565"},"modified":"2026-03-21T03:59:49","modified_gmt":"2026-03-21T02:59:49","slug":"como-ampliar-a-funcionalidade-do-qodana-adicionando-inspecoes-personalizadas-de-codigo","status":"publish","type":"platform","link":"https:\/\/blog.jetbrains.com\/pt-br\/platform\/2026\/03\/como-ampliar-a-funcionalidade-do-qodana-adicionando-inspecoes-personalizadas-de-codigo\/","title":{"rendered":"Como ampliar a funcionalidade do Qodana adicionando inspe\u00e7\u00f5es personalizadas de c\u00f3digo"},"content":{"rendered":"

O Qodana \u00e9 uma ferramenta de an\u00e1lise est\u00e1tica de c\u00f3digo que traz as inspe\u00e7\u00f5es de c\u00f3digo<\/a> e as corre\u00e7\u00f5es r\u00e1pidas dos JetBrains IDEs para o dom\u00ednio da integra\u00e7\u00e3o cont\u00ednua. Ele pode ser executado na nuvem<\/a> ou a partir de um container do Docker<\/a>, pode ser integrado<\/a> a pipelines de CI\/CD ou invocado a partir de um JetBrains IDE.<\/p>\n

O Qodana j\u00e1 oferece um conjunto impressionante de inspe\u00e7\u00f5es, mas n\u00e3o se limita ao que j\u00e1 vem instalado. Voc\u00ea pode adicionar inspe\u00e7\u00f5es personalizadas para fazer valerem caracter\u00edsticas e conven\u00e7\u00f5es espec\u00edficas de cada projeto.<\/p>\n

Por exemplo, imagine um projeto com uma conven\u00e7\u00e3o espec\u00edfica para o c\u00f3digo:<\/p>\n

\n

Todas as classes Kotlin em um pacote service<\/code> precisam ter o sufixo Service<\/code>.<\/p>\n<\/blockquote>\n

Nesse caso, a classe com.jetbrains.service.JetComponent<\/code> n\u00e3o estaria de acordo com essa conven\u00e7\u00e3o, enquanto com.jetbrains.service.BrainComponentService<\/code> estaria perfeita. A seguir, criaremos um plug-in para implementar essa inspe\u00e7\u00e3o, permitindo que o Qodana fa\u00e7a valer essa conven\u00e7\u00e3o em projetos futuros.<\/p>\n

Podemos implementar essa conven\u00e7\u00e3o no c\u00f3digo criando uma inspe\u00e7\u00e3o de c\u00f3digo<\/strong> personalizada, envolta em um plug-in<\/strong>. Os plug-ins do Qodana s\u00e3o desenvolvidos da mesma forma que os dos JetBrains IDEs. Isso quer dizer que precisamos apenas criar um plug-in para a plataforma IntelliJ que possa ser executado no Qodana. Esta \u00e9 uma r\u00e1pida vis\u00e3o geral das etapas que realizaremos:<\/p>\n

    \n
  1. Inicializar o projeto a partir de IntelliJ Platform Plugin Template<\/a>.<\/li>\n
  2. Ajustar as propriedades do projeto, o descritor do plug-in e as depend\u00eancias necess\u00e1rias.<\/li>\n
  3. Declarar a inspe\u00e7\u00e3o local no descritor do plug-in e implement\u00e1-la no Kotlin.<\/li>\n
  4. Fazer a build do plug-in e empacot\u00e1-lo.<\/li>\n
  5. No projeto de exemplo de teste, colocar o artefato do plug-in em um diret\u00f3rio apropriado.<\/li>\n
  6. Ajustar o arquivo de configura\u00e7\u00f5es do Qodana.<\/li>\n
  7. Executar o Qodana e examinar o relat\u00f3rio!<\/li>\n<\/ol>\n

    Prepara\u00e7\u00e3o do projeto do plug-in<\/h2>\n

    Para inicializar o projeto, visite o reposit\u00f3rio IntelliJ Platform Plugin Template<\/a> e clique no bot\u00e3o Use this template<\/em> para criar um reposit\u00f3rio para o plug-in. D\u00ea a ele o nome de classname-inspection-qodana-plugin<\/code>, copie a URL do projeto e abra-a no IntelliJ IDEA. Quando o projeto estiver pronto, personalize gradle.properties<\/code> declarando pluginGroup<\/code>, pluginName<\/code> e pluginRepositoryUrl<\/code>, conforme necess\u00e1rio. Lembre-se de clicar no bot\u00e3o flutuante Sync Gradle Changes<\/em> para aplicar as altera\u00e7\u00f5es. Para modificar o identificador exclusivo do plug-in<\/a>, altere o elemento id<\/code> no descritor plugin.xml<\/code>.<\/p>\n

    Declara\u00e7\u00e3o de depend\u00eancias<\/h3>\n

    Nossa inspe\u00e7\u00e3o de c\u00f3digo tem como alvo classes Kotlin. Ent\u00e3o, precisamos adicionar o plug-in do Kotlin \u00e0s depend\u00eancias do plug-in do Qodana. O arquivo gradle.properties<\/code> exige que voc\u00ea declare:<\/p>\n

    platformBundledPlugins = org.jetbrains.kotlin<\/pre>\n
    Al\u00e9m disso, o descritor plugin.xml<\/code> precisa conter o mesmo plug-in incorporado do Kotlin entre suas depend\u00eancias:<\/p>\n
    org.jetbrains.kotlin<\/pre>\n
    Mais uma vez, lembre-se de sincronizar as altera\u00e7\u00f5es com o Gradle, clicando no bot\u00e3o flutuante.<\/p>\n
    Al\u00e9m disso, a inspe\u00e7\u00e3o de classe do Kotlin precisa ter suporte ao compilador Kotlin K2, que \u00e9 habilitado como padr\u00e3o desde a vers\u00e3o 2025.1 da plataforma IntelliJ. No descritor do plug-in, declare a extens\u00e3o org.jetbrains.kotlin.supportsKotlinPluginMode<\/code>.<\/p>\n
        \n<\/pre>\n
    Cria\u00e7\u00e3o da inspe\u00e7\u00e3o de c\u00f3digo<\/h3>\n
    O c\u00f3digo em si de qualquer inspe\u00e7\u00e3o de c\u00f3digo que tenha como alvo classes Kotlin requer tr\u00eas etapas:<\/p>\n
      \n
    1. Declarar a extens\u00e3o com.intellij.localInspection<\/code> no descritor do plug-in, juntamente com os atributos necess\u00e1rios e uma refer\u00eancia totalmente qualificada \u00e0 classe de implementa\u00e7\u00e3o.<\/li>\n
    2. Criar uma classe de implementa\u00e7\u00e3o, de prefer\u00eancia em Kotlin.<\/li>\n
    3. Fornecer um arquivo separado em HTML, contendo uma descri\u00e7\u00e3o da inspe\u00e7\u00e3o, diretrizes de uso e um exemplo.<\/li>\n<\/ol>\n
      Declara\u00e7\u00e3o da extens\u00e3o<\/h4>\n
      Adicione a seguinte declara\u00e7\u00e3o ao arquivo descritor plugin.xml<\/code>:<\/p>\n
          \n<\/pre>\n
      O atributo language<\/code> indica que a inspe\u00e7\u00e3o se aplica a arquivos de c\u00f3digo-fonte em Kotlin. \u00c9 importante manter a inspe\u00e7\u00e3o explicitamente habilitada, como padr\u00e3o; sen\u00e3o, o Qodana n\u00e3o a executar\u00e1. Depois, informe um atributo displayName<\/code>, descritivo e leg\u00edvel por seres humanos, para ser exibido no relat\u00f3rio e nas configura\u00e7\u00f5es. O atributo groupName<\/code> define a categoria da inspe\u00e7\u00e3o, mostrada tanto no relat\u00f3rio do Qodana quanto nas configura\u00e7\u00f5es do IDE. Por fim, d\u00ea um nome totalmente qualificado \u00e0 classe de implementa\u00e7\u00e3o.<\/p>\n
      C\u00f3digo-fonte da inspe\u00e7\u00e3o de c\u00f3digo<\/h4>\n
      O plug-in do Kotlin oferece uma classe \u00fatil como base para inspe\u00e7\u00f5es de Kotlin: AbstractKotlinInspection<\/code>. Fa\u00e7a override do m\u00e9todo buildVisitor<\/code> e forne\u00e7a uma inst\u00e2ncia do padr\u00e3o Visitor de PSI que percorre os elementos da classe Kotlin de forma type-safe. classVisitor<\/code> \u00e9 uma fun\u00e7\u00e3o estilo DSL que retorna esse tipo de visitor PSI e \u00e9 invocada em qualquer classe Kotlin do projeto inspecionado.<\/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
      A subclasse do visitor extrai o nome totalmente qualificado da classe Kotlin, inspeciona o elemento de pacote mais \u00e0 direita e verifica o sufixo correspondente. Qualquer nome de classe inadequado ser\u00e1 relatado \u00e0 inst\u00e2ncia ProblemsHolder<\/em> com a classe que o cont\u00e9m como elemento PSI e uma descri\u00e7\u00e3o leg\u00edvel do problema.<\/p>\n
      Descri\u00e7\u00e3o da inspe\u00e7\u00e3o<\/h4>\n
      Toda inspe\u00e7\u00e3o local precisa ser acompanhada de um arquivo de descri\u00e7\u00e3o, representada em HTML. Se voc\u00ea usar a corre\u00e7\u00e3o r\u00e1pida Create description file ServicePackageClassNameInspection.html<\/em>, ser\u00e1 criado um arquivo com o nome src\/main\/resources\/inspectionDescriptions\/ServicePackageClassName.html<\/code> no local apropriado. Voc\u00ea tamb\u00e9m ter\u00e1 que fornecer uma descri\u00e7\u00e3o, que ser\u00e1 mostrada no relat\u00f3rio do Qodana e nas configura\u00e7\u00f5es do 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
      Build do plug-in<\/h2>\n
      Tudo pronto \u2014 \u00e9 hora de fazer a build! Execute a tarefa buildPlugin<\/code> do Gradle e veja o artefato build\/distributions\/qodana-code-inspection-0.0.1.zip<\/code>, que estar\u00e1 dispon\u00edvel no diret\u00f3rio de sa\u00edda do Gradle. O arquivo JAR ser\u00e1 usado como artefato prim\u00e1rio na an\u00e1lise do Qodana.\u00a0<\/p>\n
      Tenha em mente o tipo de artefato do plug-in<\/h4>\n
      O Qodana n\u00e3o tem suporte direto a artefatos de plug-in em formato ZIP que incluam outros arquivos JAR ou depend\u00eancias de terceiros. Todo plug-in precisa ser empacotado em um s\u00f3 arquivo JAR ou descomprimido em um diret\u00f3rio espec\u00edfico.<\/p>\n
      Execu\u00e7\u00e3o do Qodana em um projeto de teste<\/h2>\n
      Vamos criar um projeto de teste em Kotlin que possamos inspecionar com o Qodana, ap\u00f3s ampli\u00e1-lo com nosso plug-in. Para executar localmente o plug-in do Qodana, certifique-se de que dois componentes de software estejam dispon\u00edveis no seu sistema:<\/p>\n