python lint-staged

# 聊聊 Python 项目中的 lint-staged一个被低估的提效工具在 Python 项目里代码质量检查工具大家都不陌生像 flake8、black、isort 这些几乎是标配。但很多人可能遇到过这样的场景每次提交代码前都要手动跑一遍检查有时候忘了跑结果 CI 流水线就报错了还得重新修改提交。这种重复劳动不仅浪费时间还容易打断开发节奏。今天想聊的 lint-staged就是专门解决这个痛点的工具。它不是什么高深的技术但用好了能让整个团队的开发体验提升一个档次。lint-staged 到底是什么简单来说lint-staged 是一个只对“暂存区文件”运行检查的工具。这里的“暂存区”指的是 Git 的 staging area也就是你执行git add后那些准备提交的文件。很多人第一次听到这个概念会觉得有点绕其实可以把它想象成快递打包前的最后一道检查。假设你要寄一批书不会把整个仓库的书都翻出来检查一遍而是只检查已经打包好、准备寄出的那几箱。lint-staged 做的就是类似的事情——它只检查你准备提交的那部分代码而不是整个项目。这个设计很巧妙因为它解决了两个实际问题一是检查范围小速度快二是避免因为别人的旧代码或你还没修改的代码导致检查失败。它能解决哪些实际问题最直接的用处就是自动化代码检查流程。在没有 lint-staged 的时候团队往往要靠开发者的自觉性来保证代码质量。但人总会忘事特别是赶进度的时候很容易跳过检查步骤直接提交。用了 lint-staged 之后每次执行git commit它会自动对你修改过的文件运行配置好的检查命令。如果检查通过提交正常进行如果检查失败提交会被阻止并给出具体的错误信息。这就相当于在提交代码的必经之路上设了个自动门卫不合格的代码根本出不去。另一个不太明显但很重要的好处是它促进了工具的统一。有些团队虽然制定了代码规范但每个人用的格式化工具版本不同、配置不同导致同样的代码在不同机器上格式化结果不一样。lint-staged 可以把这些工具的配置和版本锁定在项目里确保团队每个成员执行的都是完全相同的检查标准。具体怎么用起来在 Python 项目里配置 lint-staged 其实很简单。首先需要安装它通常通过 npm 安装虽然它是 JavaScript 生态的工具但完全可以用于任何语言项目npminstall--save-dev lint-staged然后在项目根目录创建配置文件。lint-staged 支持多种配置格式个人比较喜欢用package.json因为很多项目本来就有这个文件比如前端混合项目而且配置集中在一个地方管理起来方便。在package.json里添加{lint-staged:{*.py:[black,isort,flake8]}}这个配置的意思是对所有暂存区的.py文件依次执行 black 格式化、isort 整理导入顺序、flake8 检查代码风格。配置好后还需要一个触发机制。通常搭配 husky 使用husky 能让我们在 Git 钩子里执行命令。安装 husky 后在.husky/pre-commit钩子里添加npx lint-staged这样每次提交前lint-staged 就会自动运行。有个细节值得注意lint-staged 默认会依次执行配置的命令但如果某个命令修改了文件内容比如 black 格式化后续命令检查的已经是修改后的版本。这种设计很合理避免了格式化前后的代码差异导致检查不一致。一些实践中的经验用了几年 lint-staged积累了一些不算最佳但很实用的经验。首先是命令的顺序很重要。像上面配置的那样应该把会修改文件的命令如 black、isort放在前面只做检查不修改的命令如 flake8、mypy放在后面。这样检查的就是最终要提交的代码版本。其次对于大型项目检查速度很关键。如果每次提交都要等一两分钟开发者就会想办法绕过检查。这时候可以做一些优化比如只对修改的文件运行 mypy 检查虽然 mypy 官方推荐全量检查但在提交前做增量检查总比不做强。可以用类似这样的配置{lint-staged:{*.py:[black,isort,flake8,mypy --no-error-summary]}}--no-error-summary参数能让 mypy 输出更简洁在提交前检查时体验更好。另一个经验是关于错误信息的可读性。默认情况下各种工具的错误信息格式不一有些很冗长。可以在团队内部约定统一的输出格式或者写简单的包装脚本让错误信息更友好。毕竟工具的目的是帮助人而不是制造障碍。还有一点不是所有检查都适合放在提交前。像单元测试、集成测试这种耗时较长的更适合放在 CI 流水线里。lint-staged 应该只放那些快速、轻量的检查确保提交的代码至少没有低级错误和风格问题。和其他方案的对比常见的代码检查方案大概有三种纯手动执行、CI 流水线检查、提交前自动检查。纯手动执行最灵活但也最不可靠完全依赖个人习惯。在小型项目或 solo 开发时还能接受一旦团队规模上去代码风格很快就会变得五花八门。CI 流水线检查现在是标准实践它的好处是强制性强不合格的代码无法合并。但缺点也很明显反馈周期长。开发者提交代码后要等 CI 跑完才知道有没有问题如果有问题还得重新修改提交一来一回时间成本很高。提交前检查是折中方案lint-staged 就属于这一类。它的反馈是即时的在本地就能发现问题并立即修复。但它的强制力取决于本地配置如果开发者跳过钩子或修改配置还是可能提交不规范的代码。实际上这三种方案并不互斥完全可以组合使用。一个比较成熟的实践是用 lint-staged 做提交前的快速检查保证基本质量用 CI 做更全面的检查包括测试、安全扫描等对于特别重要的规范可以在代码审查时人工检查。还有一点值得提除了 lint-stagedPython 生态里也有类似功能的工具比如 pre-commit。pre-commit 功能更强大支持更多类型的钩子而且本身是 Python 工具对 Python 项目更友好。但 lint-staged 的优势是简单直接配置更简洁特别是在已经有 npm 工具链的项目里集成起来更自然。选择哪个工具主要看项目具体情况和团队偏好。如果项目是纯 Python 且没有前端部分pre-commit 可能更合适如果是全栈项目或者团队对 JavaScript 工具链更熟悉lint-staged 是个不错的选择。最后一点想法工具的价值不在于它本身有多复杂而在于它解决了什么实际问题。lint-staged 这样的工具初看起来只是个小巧的自动化脚本但它改变了开发者的工作流程把代码质量检查从“可选的额外步骤”变成了“自动化的必经流程”。这种转变带来的影响是潜移默化的。当代码检查变成无感的后台操作时开发者会更自然地写出符合规范的代码而不是把规范视为负担。久而久之整个团队的代码质量会稳定在一个不错的水平而且不需要太多人为督促。好的工具应该像好的设计一样让人感受不到它的存在却又离不开它。lint-staged 差不多就是这样的存在——配置好后你几乎不会特意想起它但它一直在那里安静地守护着代码库的质量底线。