codacy/codacy-jackson-linter

Codacy Jackson Linter (JSON) 镜像文档

1. 镜像概述和主要用途

1.1 概述

Codacy Jackson Linter镜像是Codacy平台专用的JSON静态分析工具，基于Jackson库开发，用于对JSON文件进行自动化语法验证和规范性检查。该镜像旨在确保JSON数据格式正确、符合行业最佳实践，并可无缝集成到CI/CD流程中实现代码质量管控。

1.2 主要用途

• JSON文件语法错误检测
• JSON格式规范性校验
• 集成Codacy平台实现分析结果可视化
• 支持CI/CD流程中的自动化JSON质量检查

1.3 源码与构建信息

• 源码仓库：https://github.com/codacy/codacy-jackson-linter
• 构建状态：[***]

2. 核心功能和特性

• JSON语法验证：自动检测JSON文件中的语法错误（如括号不匹配、逗号遗漏、键值对格式错误等）
• 格式规范性检查：验证JSON文件是否符合预设格式标准（如缩进规则、引号使用规范、键名命名格式等）
• Codacy平台集成：原生支持将分析结果上报至Codacy平台，生成可视化质量报告
• 轻量级设计：基于Java构建，镜像体积优化，适合CI/CD环境快速部署
• 自动化集成：支持与主流CI/CD工具（GitHub Actions、GitLab CI、Jenkins等）集成

3. 使用场景和适用范围

3.1 典型使用场景

• CI/CD流水线集成：在代码提交或构建阶段自动检查项目中的JSON配置文件（如package.json、config.json等）
• 开发环境本地校验：开发者本地运行工具对修改的JSON文件进行即时检查
• 代码审查辅助工具：作为团队代码规范的一部分，确保JSON文件提交前符合格式要求
• Codacy平台增强：为Codacy项目提供JSON文件专项质量分析能力

3.2 适用范围

• 需要验证JSON格式的开发团队
• 使用Codacy平台进行代码质量管控的项目
• 包含JSON配置文件的前端、后端或DevOps项目
• 追求自动化质量检查的CI/CD流程

4. 详细的使用方法和配置说明

4.1 基础使用（Docker Run）

4.1.1 本地JSON文件检查

直接运行容器对本地JSON文件目录进行扫描：

bash
docker run --rm \
  -v /本地/json文件目录:/app/json \
  codacy/jackson-linter:latest

参数说明：

• --rm：容器运行结束后自动清理
• -v /本地/json文件目录:/app/json：将本地JSON文件目录挂载至容器内分析路径（必填）

4.2 与Codacy平台集成

4.2.1 基本集成命令

配置Codacy项目令牌，将分析结果上报至Codacy平台：

bash
docker run --rm \
  -v /本地/json文件目录:/app/json \
  -e CODACY_PROJECT_TOKEN=your-codacy-project-token \
  codacy/jackson-linter:latest

环境变量说明：

• CODACY_PROJECT_TOKEN：Codacy项目访问令牌（在Codacy项目设置→集成→API令牌中获取）

4.3 Docker Compose配置

创建docker-compose.yml文件实现服务化部署：

yaml
version: '3.8'
services:
  json-linter:
    image: codacy/jackson-linter:latest
    volumes:
      - ./project-json-files:/app/json  # 挂载本地JSON文件目录
      - ./custom-rules:/app/config      # 可选：挂载自定义规则文件
    environment:
      - CODACY_PROJECT_TOKEN=your-codacy-project-token  # 可选：Codacy集成令牌
      - LOG_LEVEL=INFO                                   # 可选：日志级别(DEBUG/INFO/WARN/ERROR)
    command: ["--scan-path", "/app/json"]                # 可选：自定义扫描路径

启动命令：

bash
docker-compose run --rm json-linter

4.4 高级配置

4.4.1 自定义规则配置

通过挂载规则文件自定义检查标准：

bash
docker run --rm \
  -v /本地/json文件目录:/app/json \
  -v /本地/custom-rules.json:/app/config/rules.json \
  codacy/jackson-linter:latest

规则文件格式：规则文件需为JSON格式，具体规范参考https://github.com/codacy/codacy-jackson-linter/blob/master/docs/rules.md

4.4.2 环境变量完整列表

5. 注意事项

• 挂载目录权限：确保本地JSON文件目录对容器具有可读权限（建议设置权限为755）
• 网络要求：集成Codacy平台时需确保容器可访问https://api.codacy.com
• 规则更新：自定义规则文件变更后需重启容器使配置生效
• 版本控制：生产环境建议固定镜像版本号（如:v1.2.0）而非使用:latest

6. 参考链接

• 源码仓库：https://github.com/codacy/codacy-jackson-linter
• 构建状态：[***]
• Codacy平台文档：[***]