【知识整理】Git Commit Message 规范：Java 项目提交信息怎么写才规范

1. Java 团队协作里 Commit Message 到底乱在哪

你有没有遇到过这种场景：线上出了个 bug，需要回溯是哪次提交引入的，结果git log一拉，满屏都是「修改」「更新」「fix bug」「提交一下」。你只能一个个点进去看 diff，半小时过去了还没定位到问题。这不是个别现象，是绝大多数 Java 团队在协作初期都会踩的坑。

Commit Message 规范这件事，说大不大，说小也不小。它本质上是一份「给未来的自己和同事看的变更说明书」。写得清楚，代码审查快、问题定位快、发版说明能自动生成；写得随意，团队协作成本就会悄悄堆高。我待过的几个 Java 项目组，从最初的「随便写」到后来统一规范，最直观的变化就是：查历史提交的时间从十几分钟缩短到几十秒。

这篇内容聚焦 Java 团队日常协作场景，把 Git Commit Message 的写法、模板、校验配置讲透。你会看到三部分内容：一是规范本身怎么拆（Header/Body/Footer 三段式），二是怎么用工具把规范「强制」落地（commitizen + husky + commitlint），三是怎么在本地仓库里验证校验是否真的生效。所有配置都可以直接复制到你的 Java 项目里用。

适合谁看？如果你是 Java 后端开发、团队 Tech Lead，或者正在负责搭建项目工程化规范，这篇能直接拿去用。如果你只是个人项目随便提交，那规范可以简化，但三段式的思路依然值得了解。

先明确一个核心检索词：Java 项目 Git Commit Message 提交规范。它的作用是让每一次代码变更都有清晰的类型、范围和描述，从而支持自动化 changelog、语义化版本、问题追踪。下面从格式拆解开始。

2. 三段式格式拆解与 Java 场景 type 约定

Commit Message 的标准格式分三部分，用空行分隔：

<type>(<scope>): <subject> // 空一行 <body> // 空一行 <footer>

2.1 Header 行：type、scope、subject

Header 只有一行，是提交信息的门面，包含三个字段。

type（必填）指定提交类型。Java 项目里常用的约定如下：

scope（可选）说明影响范围，Java 项目里通常写模块名或分层名，比如order、user、dao、web、common。影响多个模块时用*。记得加括号。

subject（必填）简短描述，不超过 50 个字符。用动词开头，说明「做了什么」，不要写「修改了代码」这种废话。

一个合格的 Header 长这样：

feat(order): 新增订单批量导出 Excel 接口 fix(payment): 修复退款金额精度丢失问题 refactor(common): 抽取日期格式化工具类

2.2 Body：说清楚为什么改

Body 是详细描述，回答三个问题：为什么改、怎么改的、有没有副作用。小改动可以省略，重大需求必须写。要求用第一人称现在时，动词开头，首字母小写，结尾不加句号。

body: - 原订单导出只支持单条，运营反馈效率低 - 新增批量导出接口，支持按时间范围筛选 - 导出上限设为 10000 条，避免内存溢出

2.3 Footer：破坏性变更与 Issue 关联

Footer 用于标注BREAKING CHANGE和关联 Issue。如果接口参数减少、删除、迁移，必须写明：

BREAKING CHANGE: 订单查询接口移除 pageSize 参数，改用 limit Closes #128

Java 项目里如果打通了 Jira，可以写Refs: JIRA-2048。这部分对追溯需求来源非常有用。

把这三段理解清楚，规范就立住了一半。剩下的一半靠工具强制。下一节讲怎么在项目里配置校验。

3. 可复制的校验配置：commitlint + husky 落地

光有规范文档没用，队友该乱写还是乱写。必须用工具在提交时拦截。这里给一套可直接复制的配置，基于 commitlint + husky，适配 Java 项目（前端工程同样适用，因为校验发生在 Git 层）。

3.1 安装依赖

在项目根目录执行：

npm install --save-dev @commitlint/cli @commitlint/config-conventional husky

3.2 创建 commitlint.config.js

在项目根目录新建commitlint.config.js：

module.exports = { extends: ['@commitlint/config-conventional'], rules: { 'type-enum': [ 2, 'always', ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert'] ], 'scope-empty': [2, 'never'], 'subject-empty': [2, 'never'], 'subject-full-stop': [2, 'never', '.'], 'header-max-length': [2, 'always', 72], 'body-leading-blank': [2, 'always'], 'footer-leading-blank': [2, 'always'] } };

这份配置强制了 type 白名单、scope 非空、subject 不以句号结尾、Header 不超过 72 字符。你可以按团队习惯调整。

3.3 配置 husky 钩子

初始化 husky 并添加 commit-msg 钩子：

npx husky install npx husky add .husky/commit-msg 'npx --no-install commitlint --edit "$1"'

执行后.husky/commit-msg文件内容应该是：

#!/usr/bin/env sh . "$(dirname -- "$0")/_/husky.sh" npx --no-install commitlint --edit "$1"

3.4 在 package.json 里加 prepare 脚本

为了让队友 clone 后自动装钩子，在package.json的 scripts 里加：

{ "scripts": { "prepare": "husky install" } }

这样npm install时会自动执行 husky install，钩子就位。

3.5 如果团队用 Maven 多模块

Java 项目常见 Maven 多模块结构，Git 仓库根目录和模块目录可能不一致。husky 钩子要装在 Git 仓库根目录，也就是.git所在的那一层。如果你的package.json在子目录，记得把 husky 配置指向根目录，或者干脆在根目录放一个轻量的package.json专门管工程化工具。

配置完成后，任何不符合规范的提交都会被拦截。下一节验证它是否真的生效。

4. 本地验证：提交格式是否真的被拦截

配置写完不验证，等于没配。下面在本地仓库走一遍完整流程，确认校验生效。

4.1 准备测试仓库

mkdir commit-demo && cd commit-demo git init npm init -y npm install --save-dev @commitlint/cli @commitlint/config-conventional husky npx husky install npx husky add .husky/commit-msg 'npx --no-install commitlint --edit "$1"'

把上面的commitlint.config.js复制进来。

4.2 故意提交一条不合规的信息

echo "test" > a.txt git add a.txt git commit -m "修改了一下"

预期结果：提交被拒绝，终端输出类似：

⧗ input: 修改了一下 ✖ subject may not be empty [subject-empty] ✖ type may not be empty [type-empty] ✖ scope may not be empty [scope-empty] ✖ found 3 problems, 0 warnings husky - commit-msg hook exited with code 1 (error)

看到这个报错，说明校验生效了。

4.3 提交一条合规的信息

git commit -m "feat(order): 新增订单批量导出接口"

这次应该顺利通过。再用git log --oneline查看：

a1b2c3d feat(order): 新增订单批量导出接口

4.4 验证 Body 和 Footer

git commit -m "feat(order): 新增订单批量导出接口" -m "- 支持按时间范围筛选 - 导出上限 10000 条" -m "Closes #128"

git log里能看到完整的三段式结构。到这里，本地校验链路就通了。

4.5 用 commitizen 交互式生成

如果不想手写，可以装 commitizen：

npm install -g commitizen commitizen init cz-conventional-changelog --save --save-exact

之后用git cz代替git commit，按提示选 type、填 scope、写 subject，自动生成合规信息。适合团队新人快速上手。

验证通过后，规范才算真正落地。下一节整理常见报错。

5. 常见报错排查：从 401 到 hook 失效

配置过程中会遇到各种报错，这里按真实场景整理。

5.1 husky 钩子不生效

最常见的原因是.git目录和package.json不在同一层。husky 依赖 Git 的core.hooksPath配置。检查：

git config core.hooksPath

如果输出不是.husky，手动设置：

git config core.hooksPath .husky

另一个原因是npx husky install没执行，或者队友 clone 后没跑npm install。确保package.json里有prepare脚本。

5.2 commitlint 报 type 不在白名单

报错：

✖ type must be one of [feat, fix, docs, ...] [type-enum]

说明你写的 type 不在配置里。要么改用白名单内的 type，要么在commitlint.config.js的type-enum数组里加上。Java 项目里如果团队自定义了wip（进行中）之类的 type，记得同步加进去。

5.3 scope 为空被拦截

报错：

✖ scope may not be empty [scope-empty]

如果你觉得 scope 太严格，可以把规则改成[0, 'always']关闭强制。但建议保留，scope 对 Java 多模块项目定位问题很有帮助。

5.4 提交信息含中文导致长度计算异常

commitlint 默认按字符数算，中文一个字符算一个，一般没问题。但如果你的终端编码不是 UTF-8，可能出现乱码。检查：

locale

确保LANG是zh_CN.UTF-8或en_US.UTF-8。

5.5 与 TaoToken 相关的接入报错

如果你在用 AI 辅助生成 commit message，或者把提交规范接入到 AI 编码工作流里，可能会遇到 API 调用报错。常见的有：

• 401 Unauthorized：API Key 无效或过期。检查 Key 是否正确复制，有没有多余空格。
• local proxy failed：本地代理配置问题。检查环境变量HTTP_PROXY、HTTPS_PROXY是否指向了不可用的地址。
• reading choices：响应体解析失败，通常是模型返回格式和预期不一致，检查请求参数里的model字段是否正确。

这类接入场景，Base URL、API Key、Model ID 三件套必须配全。以 TaoToken 为例：

Base URL: https://taotoken.net/api API Key: 你的密钥 Model ID: 按文档选择

配置时注意 Base URL 不要带多余路径，Key 不要泄露到公开仓库。如果遇到 OAuth 相关报错，检查 token 是否过期，重新获取即可。

5.6 回滚提交的 message 怎么写

用git revert时，Git 会自动生成Revert "xxx"的 message。如果被 commitlint 拦截，可以在配置里对 revert 类型放行，或者手动改成：

revert(order): 回滚订单导出接口

排查完这些，基本能覆盖 90% 的落地问题。

6. 把规范接进 AI 编码工作流

规范落地之后，可以进一步和 AI 辅助编码结合。比如让 AI 根据 diff 自动生成符合规范的 commit message，或者用 AI 做代码审查时顺带检查提交信息质量。

如果你在搭这类工作流，TaoToken 提供了统一的模型接入能力。模型对话入口适合快速验证 prompt 效果，Coding Plan 适合长期编码和 Agent 场景，API Keys 管理页用来生成和管理密钥，接入文档里有各语言的调用示例。Claude Code 相关的接入也有专门说明。

具体来说，你可以这样分流：

• 想先试试模型能不能生成合规的 commit message，去模型对话页面直接测。
• 要把生成能力接进 CI 或本地脚本，去 API Keys 页面拿密钥，参考接入文档写调用。
• 团队长期用 AI 辅助编码、跑 Agent 任务，看 Coding Plan。

配置时记住三件套：Base URL 用https://taotoken.net/api，Key 从控制台生成，Model ID 按文档选。别把 Key 硬编码进代码，用环境变量管理。

最后给一个实用技巧：把 commit message 模板做成 Git 的commit.template，每次git commit自动带出结构，配合 commitlint 校验，团队协作会顺畅很多。配置命令：

git config commit.template .gitmessage

.gitmessage文件内容：

# <type>(<scope>): <subject> # type: feat/fix/docs/style/refactor/perf/test/build/ci/chore/revert # scope: 模块名，如 order/user/dao # subject: 不超过 50 字符，动词开头 # Body: 为什么改、怎么改、有无副作用 # Footer: BREAKING CHANGE 或 Closes #issue

这套组合拳打下来，Java 团队的提交记录会从「一团乱麻」变成「可检索的变更日志」。查问题、发版本、写 changelog 都能省下大量时间。