Git钩子脚本如何检查可读性

Git钩子脚本如何检查可读性：从自动化到代码审查的完整指南

目录导读

1. 为什么要用Git钩子检查代码可读性？
2. Git钩子基础与生命周期
3. 实战：编写可读性检查钩子
   • 1 前置检查钩子（pre-commit）
   • 2 提交信息钩子（commit-msg）
   • 3 推送前检查钩子（pre-push）
4. 检查指标与规则设计
5. 集成第三方工具（ESLint、Pylint、Checkstyle）
6. 常见问题与解答（FAQ）
7. 总结与最佳实践

为什么要用Git钩子检查代码可读性？

问题：为什么不在CI/CD阶段检查，而要用Git钩子？

回答：Git钩子在代码提交之前执行，能即时反馈，CI/CD通常在推送后检查，此时错误已进入仓库，钩子可以：

• 减少噪音：防止不可读代码进入版本历史。
• 降低成本：越早发现问题，修复成本越低。
• 统一标准：团队共享相同的可读性规则。

统计：研究表明，Code Review中平均20%的评论是关于可读性（如命名、格式、注释），用钩子自动化这部分，可提升代码审查效率50%以上。

Git钩子基础与生命周期

Git钩子位于 .git/hooks/ 目录，本质是可执行脚本（Shell、Python、Node.js等），常用钩子类型：

关键：钩子默认不启用，需手动将脚本复制到 .git/hooks/ 并赋予执行权限（chmod +x），推荐团队使用 husky（Node.js）或 pre-commit（Python）管理钩子。

实战：编写可读性检查钩子

1 前置检查钩子（pre-commit）

目标：阻止包含过长行、未格式化代码或违反命名规范的提交。

#!/bin/bash
# .git/hooks/pre-commit
# 1. 检查行长度（建议80-120字符）
max_line=100
git diff --cached --name-only --diff-filter=ACM | while read file; do
    if [[ "$file" == *.js || "$file" == *.py ]]; then
        while IFS= read -r line; do
            len=${#line}
            if [ $len -gt $max_line ]; then
                echo "❌ 文件 $file 第 $((i+1)) 行超出 $max_line 字符（实际 $len）"
                exit 1
            fi
        done < <(git show :"$file")
    fi
done
# 2. 检查TODO/FIXME残留（可读性差）
git diff --cached --name-only | xargs grep -n "TODO\|FIXME\|XXX" 2>/dev/null
if [ $? -eq 0 ]; then
    echo "⚠️  发现 TODO/FIXME 标记，建议在注释中添加上下文"
    exit 1
fi
# 3. 检查她变量命名（正则示例：避免单字母变量）
git diff --cached --name-only | xargs grep -P '\b[a-z]{1}\b' 2>/dev/null
if [ $? -eq 0 ]; then
    echo "⚠️  存在单字母变量名（如 a, b），可读性差"
    exit 1
fi

2 提交信息钩子（commit-msg）

目标：确保提交信息简洁、结构化（遵循 Conventional Commits）。

#!/bin/bash
# .git/hooks/commit-msg
commit_msg=$(cat "$1")
# 检查格式：类型（feat/fix/chore）+ 范围 + 简短描述
if [[ ! "$commit_msg" =~ ^(feat|fix|chore|docs|style|refactor|test)(\([a-z]+\))?:\ .+$ ]]; then
    echo "❌ 提交信息不满足格式：类型(范围): 描述"
    echo "示例：feat(api): 添加用户登录接口"
    exit 1
fi
# 检查长度（Header 不超过50字符）
header=$(head -n 1 "$1")
if [ ${#header} -gt 50 ]; then
    echo "⚠️  第一行超过50字符，建议精简"
    exit 1
fi

3 推送前检查钩子（pre-push）

目标：运行专业代码分析工具。

#!/usr/bin/env python3
# .git/hooks/pre-push
import subprocess, sys
# 集成的check Script（需要安装 flake8, pylint）
tools = {
    "flake8": "--max-line-length=100",
    "pylint": "--disable=missing-docstring",
}
for tool, args in tools.items():
    try:
        subprocess.run([tool, args], check=True, capture_output=True)
    except subprocess.CalledProcessError as e:
        print(f"❌ {tool} 检查失败：")
        print(e.stderr.decode())
        sys.exit(1)
print("✅ 可读性检查通过")

检查指标与规则设计

设计可读性规则时,应遵循 SMART原则（Specific, Measurable, Achievable, Relevant, Time-bound）。

核心指标：

1. 行长度：建议 ≤ 100 字符（研究显示，长行降低阅读速度30%）
2. 函数/方法长度：单个函数不超过50行
3. 嵌套深度：超过3层缩进应重构
4. 注释比率：代码中注释占比建议≥15%（但不要虚假注释）
5. 变量命名：禁止缩写（usr 应为 user），使用 camelCase 或 snake_case
6. 重复代码：同一模式出现3次以上应提取为函数

实用规则：

• 每个函数只做一件事
• 布尔变量用 is_、has_ 开头
• 异常类名以 Error

// package.json
{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged && npm run check-readability",
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  },
  "lint-staged": {
    "*.js": ["eslint --fix", "prettier --write"]
  }
}

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files
  - repo: https://github.com/psf/black
    rev: 23.1.0
    hooks:
      - id: black
        args: [--line-length=100]
  - repo: https://github.com/PyCQA/flake8
    rev: 6.0.0
    hooks:
      - id: flake8
        args: [--max-line-length=100]

# pylint: disable=too-many-lines
def complex_initialization():
    # 此函数需要很多行，已用noqa豁免
    pass