Codacy PMD Java 镜像文档

1. 镜像概述和主要用途

1.1 镜像概述

Codacy PMD Java 镜像是 Codacy 平台集成 PMD (Programming Mistake Detector) 工具的 Docker 镜像，专为 Java 代码的静态分析设计。该镜像封装了 PMD 静态代码分析引擎，旨在自动化检测 Java 代码中的常见编程问题（如未使用变量、空指针风险、低效代码等），并与 Codacy 代码质量平台无缝集成。

1.2 主要用途

• 作为 Codacy 平台的 Java 代码分析引擎，提供标准化的静态质量检查结果
• 独立运行时，用于本地或 CI/CD 流程中的 Java 代码静态缺陷检测
• 支持自定义规则集，适配不同项目的代码质量规范

2. 核心功能和特性

• PMD 规则集成：内置 PMD 核心规则库，覆盖代码风格、错误风险、性能优化等维度
• Codacy 兼容性：输出符合 Codacy 平台格式的分析结果，支持质量报告可视化与问题追踪
• 多 Java 版本支持：兼容 Java 8 及以上版本代码分析
• 规则集可配置：支持通过外部文件自定义 PMD 规则集，适配项目特定需求
• 轻量级设计：基于 Alpine 基础镜像，镜像体积小，启动速度快
• CI/CD 友好：支持与主流 CI/CD 工具（Jenkins、GitHub Actions 等）集成，输出结构化结果（JSON/XML）

3. 使用场景和适用范围

3.1 适用场景

• Java 项目静态代码质量检查：在开发阶段或提交代码前，自动化检测潜在缺陷
• Codacy 平台集成：作为 Codacy 的分析节点，扩展其 Java 代码检查能力
• CI/CD 流程嵌入：在构建流水线中集成，阻断不合格代码合并（如检测到 critical 级别缺陷时终止流程）
• 代码规范统一：通过自定义规则集，强制团队遵循统一的编码标准

3.2 适用范围

• 语言：Java（8+）项目
• 环境：需 Codacy 账户（平台集成场景）或独立运行环境（本地/CI 场景）
• 输出：支持本地文件输出或 Codacy 平台上报

4. 使用方法和配置说明

4.1 基本使用（docker run 命令）

4.1.1 本地代码分析

通过挂载代码目录并指定规则集，输出分析结果到本地文件：

docker run --rm \
  -v /本地代码目录:/app/code \          # 挂载待分析代码目录
  -v /本地规则集目录:/app/rules \       # 挂载自定义规则集（可选）
  -e CODACY_PMD_RULESET=/app/rules/custom.xml \  # 指定规则集路径（默认使用内置规则）
  -e OUTPUT_FORMAT=json \                # 输出格式：json/xml（默认json）
  -e JAVA_VERSION=11 \                   # 目标代码的 Java 版本（默认8）
  codacy/codacy-pmdjava:latest \         # 镜像名称（需替换为实际标签）
  /app/code                              # 待分析代码目录路径（容器内路径）

4.1.2 输出结果

分析结果默认输出到容器内 /app/result.json（或指定格式文件），可通过挂载目录持久化：

docker run --rm \
  -v /本地代码目录:/app/code \
  -v /本地结果目录:/app/result \        # 挂载结果目录
  -e OUTPUT_PATH=/app/result/report.json \  # 自定义结果文件路径
  codacy/codacy-pmdjava:latest \
  /app/code

4.2 Docker Compose 配置

通过 docker-compose.yml 定义服务，适用于多环境复用：

version: '3'
services:
  codacy-pmdjava:
    image: codacy/codacy-pmdjava:latest
    volumes:
      - ./src:/app/code          # 本地代码目录映射到容器内 /app/code
      - ./pmd-rules:/app/rules   # 本地规则集目录映射（可选）
      - ./reports:/app/result    # 结果输出目录映射
    environment:
      - CODACY_PMD_RULESET=/app/rules/company-rules.xml  # 自定义规则集
      - JAVA_VERSION=17         # 目标代码 Java 版本
      - OUTPUT_FORMAT=xml       # 输出 XML 格式便于集成到其他工具
      - OUTPUT_PATH=/app/result/pmd-report.xml  # 结果文件路径
    command: /app/code          # 待分析代码的容器内路径

启动命令：

docker-compose up

4.3 配置参数说明

5. 注意事项

• 规则集格式：自定义规则集需符合 PMD 规则 XML 格式规范，可参考 PMD 官方文档
• 权限问题：挂载目录需确保容器内用户（通常为 codacy）有读/写权限，避免因权限不足导致文件访问失败
• Java 版本兼容性：JAVA_VERSION 需与待分析代码的编译版本匹配，否则可能出现语法解析错误
• Codacy 平台集成：通过 Codacy 平台使用时，无需手动配置 OUTPUT_FORMAT，镜像会自动适配平台要求的格式

6. 源码与构建信息

• 源码仓库：[***]
• 构建状态：[***]