yoheimuta/protolint

protolint 镜像文档

镜像概述和主要用途

protolint是一款针对Protocol Buffer文件（proto2+proto3）的可插件化 linting 工具，旨在强制实施Protocol Buffer的代码风格和约定规范。它无需依赖编译器，直接解析文件即可快速运行，规则与官方风格指南完全对应，同时支持通过文件内注释临时禁用规则（适用于需保持API兼容性同时尽可能强制风格的场景），可加载自定义规则插件，并提供多种集成方案（如protoc插件、编辑器集成、GitHub Action、CI流程等）。

核心功能和特性

• 快速高效：无需编译器，直接解析文件，运行速度快
• 官方风格对齐：规则与官方风格指南完全对应，默认启用所有官方规则
• 灵活的规则控制：支持通过注释在文件内禁用/启用指定规则，可精确作用于当前行（:this）或下一行（:next）
• 插件化扩展：可加载自定义规则插件，满足项目特定 lint 需求
• 全面测试验证：所有规则均经过测试覆盖
• 多场景集成：支持protoc插件、编辑器（VS Code、IntelliJ、Vim等）、GitHub Action、CI/CD流程等多种集成方式

使用场景和适用范围

• 需规范团队或项目内Protocol Buffer文件格式的开发场景
• 需在保持API兼容性的同时，尽可能强制实施风格指南的项目
• 需要通过自动化工具（如CI/CD流程）持续检查protobuf文件风格的场景
• 需要自定义规则来满足特定项目规范的进阶使用场景

详细使用方法和配置说明

Docker镜像基本使用

protolint提供官方Docker镜像yoheimuta/protolint，可直接集成到Docker工作流中，快速进行protobuf文件 lint 检查。

基础运行命令

挂载当前目录并检查所有protobuf文件：

bash
docker run --volume "$(pwd):/workspace" --workdir /workspace yoheimuta/protolint lint .

• --volume "$(pwd):/workspace"：将宿主机当前目录挂载到容器内的/workspace目录
• --workdir /workspace：设置容器工作目录为/workspace，确保工具在挂载的项目目录中查找文件
• lint .：对当前目录下所有protobuf文件（递归查找）执行 lint 检查

检查指定文件/目录

检查特定目录下的protobuf文件：

bash
docker run --volume "$(pwd):/workspace" --workdir /workspace yoheimuta/protolint lint _example/proto

输出示例：

[_example/proto/invalidFileName.proto:1:1] File name should be lower_snake_case.proto.
[_example/proto/issue_88/oneof_options.proto:11:5] Found an incorrect indentation style "    ". "  " is correct.
[_example/proto/issue_88/oneof_options.proto:12:5] Found an incorrect indentation style "    ". "  " is correct.

常用命令参数

• -fix：自动修复部分可修复规则（如IMPORTS_SORTED、INDENT）

  bash
  docker run --volume "$(pwd):/workspace" --workdir /workspace yoheimuta/protolint lint -fix .
  

• -config_path：指定自定义配置文件路径

  bash
  docker run --volume "$(pwd):/workspace" --workdir /workspace yoheimuta/protolint lint -config_path=path/to/.protolint.yaml .
  

• -reporter：指定输出格式（支持plain默认、junit、json、unix）

  bash
  docker run --volume "$(pwd):/workspace" --workdir /workspace yoheimuta/protolint lint -reporter junit .
  

• -plugin：加载自定义规则插件

  bash
  docker run --volume "$(pwd):/workspace" --workdir /workspace yoheimuta/protolint lint -plugin ./my_custom_rule .
  

• list：列出当前启用的所有规则

  bash
  docker run yoheimuta/protolint list
  

配置说明

通过注释控制规则

在protobuf文件中，可通过特定注释临时禁用或启用规则：

proto
// protolint:disable ENUM_FIELD_NAMES_UPPER_SNAKE_CASE
enum Foo {
  firstValue = 0; // 无错误
}
// protolint:enable ENUM_FIELD_NAMES_UPPER_SNAKE_CASE

使用:this或:next参数精确控制作用范围：

proto
enum Foo {
  // protolint:disable:next ENUM_FIELD_NAMES_UPPER_SNAKE_CASE
  firstValue = 0; // 无错误（仅下一行禁用）
  second_value = 1; // protolint:disable:this ENUM_FIELD_NAMES_UPPER_SNAKE_CASE（仅当前行禁用）
  THIRD_VALUE = 2; // 会触发错误（规则已启用）
}

配置文件（.protolint.yaml）

protolint支持通过.protolint.yaml配置规则，默认在当前目录及父目录中自动查找。示例配置：

yaml
all_default: true  # 启用所有默认官方规则
rules:
  ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH:
    suffix: "INVALID"  # 自定义枚举零值后缀为"INVALID"（默认"UNSPECIFIED"）
  FILE_NAMES_LOWER_SNAKE_CASE:
    exclude: ["legacy.proto"]  # 排除特定文件不检查文件名规则
  SERVICE_NAMES_END_WITH:  # 启用非官方规则：服务名需以"Service"结尾
    suffix: "Service"

规则说明

官方规则（默认启用）

非官方规则（默认禁用，需配置启用）

退出码说明

• 0：lint成功，无错误
• 1：lint成功，存在至少一个风格错误
• 2：lint失败（如文件解析错误、内部运行错误等）