asaasdev/codenarc

CodeNarc Docker镜像文档

概述

CodeNarc是一款针对Groovy语言的静态代码分析工具，可检测代码中的风格违规、潜在错误、未使用变量、复杂逻辑等问题，帮助团队提升代码质量。CodeNarc Docker镜像将CodeNarc及其运行依赖（如Groovy环境）封装为容器，用户无需在本地安装配置相关依赖，即可通过Docker快速启动代码分析任务，有效解决环境差异导致的分析结果不一致问题，简化代码质量检查流程。

核心功能与特性

• 内置完整工具链：镜像已预装CodeNarc及所需的Groovy运行环境，开箱即可使用，无需额外安装依赖。
• 自定义规则支持：支持挂载本地规则配置文件（codenarc.xml），灵活定义团队代码规范，满足个性化检查需求。
• 多格式报告输出：支持生成XML、HTML、文本等多种格式的分析报告，便于集成到CI/CD工具或人工查看。
• 轻量级设计：基于精简基础镜像构建，体积小、启动速度快，资源占用低。
• 环境隔离：容器化运行确保不同环境（开发、测试、CI）中代码分析过程的一致性，避免本地环境干扰。

使用场景

• CI/CD流程集成：作为代码提交或合并前的质量门禁，集成到Jenkins、GitLab CI、GitHub Actions等CI/CD管道，自动阻断违规代码进入后续流程。
• 本地开发辅助：开发人员在提交代码前，通过Docker快速运行CodeNarc检查本地Groovy代码，实时发现并修复风格问题及潜在错误。
• 团队规范落地：通过共享规则配置文件，确保团队所有成员遵循统一的代码规范，减少代码评审中的风格争议。

使用方法与配置说明

前提条件

• 已安装Docker Engine（版本20.10+）。
• 待分析的Groovy代码目录路径已知（本地路径）。

基本使用步骤

1. 拉取镜像
   从Docker仓库拉取CodeNarc镜像（以下示例假设镜像名为codenarc:latest，实际使用时需替换为具体仓库地址）：

   bash
   docker pull codenarc:latest
   

2. 运行基础代码分析
   分析本地Groovy代码目录，使用默认规则输出结果到控制台：

   bash
   docker run --rm -v "$(pwd)/src/main/groovy:/code" codenarc:latest --source /code
   

   • --rm：容器运行后自动删除，避免残留容器文件。
   • -v "$(pwd)/src/main/groovy:/code"：将本地Groovy代码目录（示例为当前目录下的src/main/groovy）挂载到容器内的/code路径（容器内固定分析目录）。
   • --source /code：指定CodeNarc分析的源代码目录（需与容器内挂载路径一致）。

高级使用示例

1. 使用自定义规则配置文件

若需使用团队自定义规则，将本地规则文件（如./config/codenarc.xml）挂载到容器，并通过--rulesetfiles参数指定：

bash
docker run --rm \
  -v "$(pwd)/src/main/groovy:/code" \
  -v "$(pwd)/config/codenarc.xml:/config/codenarc.xml" \
  codenarc:latest \
  --source /code \
  --rulesetfiles file:/config/codenarc.xml

• file:/config/codenarc.xml：容器内规则文件路径，需与挂载路径对应。

2. 生成HTML格式报告

指定输出HTML报告到本地目录（如./reports），便于直观查看分析结果：

bash
docker run --rm \
  -v "$(pwd)/src/main/groovy:/code" \
  -v "$(pwd)/reports:/reports" \
  codenarc:latest \
  --source /code \
  --report html:/reports/codenarc-report.html

执行后，报告将生成在本地./reports/codenarc-report.html，可通过浏览器打开查看详细分析结果（含违规代码位置、规则说明等）。

3. 设置违规数量阈值（CI场景）

通过--maxPriority1Violations等参数设置严重违规数量阈值，超过阈值时容器返回非0退出码，触发CI流程中断：

bash
docker run --rm \
  -v "$(pwd)/src/main/groovy:/code" \
  codenarc:latest \
  --source /code \
  --maxPriority1Violations 0  # 不允许优先级1（严重）违规
  --maxPriority2Violations 5  # 允许最多5个优先级2（中等）违规

配置参数说明

CodeNarc支持多种命令行参数，常用参数如下：

规则配置文件示例

规则配置文件（codenarc.xml）用于定义检查规则，示例结构如下：

xml
<?xml version="1.0"?>
<codenarc>
  <ruleset name="My Project Rules">
    <!-- 禁止未使用变量 -->
    <rule class="org.codenarc.rule.unused.UnusedVariableRule" priority="2"/>
    <!-- 禁止空catch块 -->
    <rule class="org.codenarc.rule.exceptions.EmptyCatchBlockRule" priority="1"/>
    <!-- 方法最大行数限制（自定义参数） -->
    <rule class="org.codenarc.rule.size.MethodSizeRule" priority="3">
      <property name="maxLines" value="50"/> <!-- 方法最大行数为50行 -->
    </rule>
  </ruleset>
</codenarc>

更多规则及配置细节可参考https://codenarc.github.io/CodeNarc/%E3%80%82