本文永久链接 – https://tonybai.com/2025/04/24/conventional-commits-guide

告别混乱Commit Log！用规范指引你写出有意义的提交！

大家好，我是Tony Bai。

Git的Commit Log (提交日志) 是项目演进的脉络，也是开发者之间沟通变更、追溯历史、理解代码演变的关键载体。然而，在实际开发中，我们常常面对杂乱无章、意义不明的提交信息——”fix bug”、”update code”、”wip” 等屡见不鲜。这些模糊的记录不仅让代码审查、问题排查和版本追溯变得异常困难，也阻碍了自动化流程的实施。Conventional Commits (约定式提交) 规范提供了一套清晰、简洁的指引，旨在将每一次提交都转化为有意义、结构化的信息单元，从而显著提升 Commit Log 的价值和可利用性。

在这篇文章中，我们将探讨Conventional Commits如何作为一项关键指引，帮助开发者和团队构建更清晰、更一致、更具信息量的提交历史。

1. Commit Log的困境：为何需要指引？

缺乏明确指引的Commit Log往往会陷入以下困境：

• 信息熵高，有效信息少: 大量模糊、随意的提交信息混杂在一起，难以快速定位关键变更或理解特定提交的目的。
• 沟通效率低下: 团队成员需要花费额外时间去解读他人的提交意图，代码审查效率降低。
• 历史追溯困难: 当需要回溯某个功能或 Bug 的引入/修复历史时，无结构的日志如同大海捞针。
• 自动化阻碍: 不一致、不可预测的提交信息使得自动化生成 Changelog、语义化版本控制（SemVer）等流程难以实现。

面对这些普遍存在的困境，业界亟需一套行之有效的规范来引导开发者记录更有价值的提交信息。这正是 Conventional Commits 规范所要解决的核心问题，它通过引入一套简洁而强大的结构化指引来实现这一目标。Conventional Commits并非强制性的铁律，而是一套强大的指引 (Guidance)，它通过引入轻量级的结构化约定，引导开发者在提交时思考并明确表达变更的性质、范围和影响。

2. Conventional Commits 核心指引：结构化的力量

该规范的核心指引体现在其简洁的提交信息结构上(如下所示)：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

遵循这项指引，每次提交都应包含以下关键要素：

• Type (类型): [必须遵循的指引] 表明提交的性质。规范定义了基础类型：

  • fix:：修复 Bug (对应 SemVer PATCH)。
  • feat:：引入新功能 (对应 SemVer MINOR)。
  • 鼓励扩展: 团队可以根据需要定义其他类型，如 build, chore(用于标记那些不涉及新特性或修复的常规维护工作，比如更新依赖项等), ci, docs, style, refactor, perf, test等，以适应具体工作流。这些扩展类型本身通常不直接影响版本号（除非包含破坏性变更）。

• Scope (范围): [可选但推荐的指引] 明确提交影响的代码库区域或模块，用括号包裹，如 feat(api): 或 fix(parser):。这极大地增强了信息的可定位性。

• Description (描述): [必须遵循的指引] 紧跟冒号和空格，用简洁的语言（推荐使用祈使句现在时）概括本次提交的核心变更内容。这是提交信息的“标题”。

• Body (正文): [可选指引] 当简短描述不足以说明时，提供更详细的上下文、动机和实现细节。与 Description 之间需空一行。

• Footer(s) (脚注): [可选指引] 提供元数据，如关联 Issue (Refs: #123)。特别重要的两个脚注指引：

  • BREAKING CHANGE: ：明确标示不兼容的 API 变更 (对应 SemVer MAJOR)。
  • INITIAL STABLE RELEASE: ：标记项目从 0.y.z 进入 1.0.0。

强调重要变更的简化指引： 规范还提供了 ! (紧跟 type 或 scope 之后) 和 !! 作为标记 BREAKING CHANGE 和 INITIAL STABLE RELEASE 的快捷方式，进一步简化遵循指引的实践。

为了更直观地理解这个结构，以下是一些典型的Conventional Commits示例：

• 简单的 Bug 修复:

fix: correct minor typos in documentation

• 带范围的新功能:

feat(lang): add Polish language support

• 使用 ! 标记破坏性变更:

refactor!(auth): remove deprecated JWT authentication method

注意：这里的 ! 表明这是一个破坏性变更，即使type是refactor。

• 包含详细正文和脚注的提交:

perf(api): improve user query performance significantly

Implemented a new indexing strategy for the users table and optimized
the SQL query execution plan. Initial tests show a 50% reduction
in average query latency under heavy load.

Reviewed-by: Alice <alice@example.com>
Refs: #456, #478

• 使用 !! 标记首次稳定版发布:

chore(release)!!: prepare for 1.0.0 stable release

Finalized documentation, updated dependencies, and ran comprehensive
end-to-end tests to ensure stability for the first major release.

INITIAL STABLE RELEASE: The project is now considered stable for production use.

通过遵循这些简单的指引，原本混乱的Commit Log就被转化为结构清晰、信息丰富的记录。

理解了 Conventional Commits 的核心结构和要素后，我们自然会问：遵循这项指引究竟能为开发者和团队带来哪些实实在在的好处？答案是多方面的，它能让原本静态、难以利用的 Commit Log “活”起来，释放出巨大的潜在价值。

首先，结构化的 type 和 scope 提升了可读性与可理解性，使团队能够快速筛选和定位信息，清晰的 description 和 body 阐述了变更的“什么”和“为什么”。

其次，一致的格式增强了团队沟通与协作，减少了误解，提高了代码审查和协作效率，使每一次提交都成为清晰的沟通。

此外，结构化的日志简化了历史追溯与问题排查，便于查找特定功能引入、Bug 修复或破坏性变更的源头。

最后，一个充满有意义提交的日志自然而然地成为自动化工具的理想输入，能够驱动自动化生成 CHANGELOG、自动化 SemVer 版本判断，以及基于提交类型触发不同的 CI/CD 流程。

认识到 Conventional Commits 带来的显著价值后，如何在日常开发中有效地遵循并最大化其效益，就成了一个关键问题。仅仅了解规范的语法是不够的，掌握一些最佳实践和深入的洞察，能帮助我们更好地将这项指引融入工作流。

3. 遵循指引的最佳实践与洞察

为了更好地应用Conventional Commits指引，以下几点值得关注：

• 原子化提交: 我们鼓励将复杂的变更分解为多个逻辑上独立的、遵循单一type的提交。这本身就是一种良好的 Git 实践，很多大厂的git commit规范以及代码review规范也是这么要求的。Conventional Commits 进一步强化了这一点。

• 选择最合适的Type: 当一次提交包含多种类型的变更时（虽然应尽量避免），选择最能代表其核心意图的 type，并在 Body 中详述其他变更。

• 祈使句现在时: 推荐使用如 “Add feature”、”Fix bug” 的风格撰写 Description，简洁、直接，如同给代码库下达指令。

• 利用工具辅助: 社区提供了丰富的工具（如Commitizen, commitlint等）来帮助开发者遵循规范格式，并在提交前进行校验，降低遵循指引的负担。

• 团队共识与逐步采纳: 引入规范需要团队达成共识。可以通过分享、讨论和使用工具逐步推广。

当然，良好实践的推广离不开工具的支持。幸运的是，围绕 Conventional Commits 已经形成了一个活跃的社区和丰富的工具生态系统，它们极大地降低了开发者遵循规范的门槛，让指引更容易落地。

4. 社区生态：工具让指引落地

Conventional Commits 的流行离不开活跃的社区和丰富的工具支持，它们帮助开发者轻松地将这项指引融入日常工作流：

• Commitizen: 交互式命令行工具，引导用户创建符合规范的提交信息。
• Commitlint: 用于校验提交信息是否符合规范，常与 Git Hooks (如 husky) 集成。
• IDE 插件: 主流 IDE (VS Code, JetBrains IDEs 等) 均有插件提供模板、补全和校验支持。
• 自动化版本与 Changelog 工具: 如 semantic-release, goreleaser/chglog等，它们消费符合规范的提交历史。

这两年基于大模型的辅助生成commit log的工具以及一些代码智能体应用(如Cursor等）也在规范git commit log方面起到了非常积极的作用，对于像我这样英语非母语但又喜欢以英文log提交的选手来说，这些工具大幅降低了我在纠结如何写commit log时的心智负担，给予了我很大的帮助。

5. 小结

总而言之，Conventional Commits 远不止一套冷冰冰的格式规则，它更像是一位贴心的向导，一项旨在将每一次提交都转化为宝贵信息资产的核心指引。它赋予我们结构化的力量，能够将困扰许多团队的混乱、低效的Commit Log，转变为清晰、一致且富有洞察力的项目演进历史——这对于提升代码可维护性、团队协作效率乃至自动化流程都至关重要。

现在，就将这项指引融入你的日常开发吧！ 让每一次git commit不再是随意的记录，而是对项目演进负责任的、有意义的贡献。

那么，你的团队是如何采纳和实践提交规范的？你在使用Conventional Commits或其他规范时，有什么独到的心得或踩过的“坑”吗？

非常期待在评论区看到你的分享与交流！

如果这篇文章让你觉得“提交信息确实应该更有意义”，请分享给你的同事或团队，一起提升代码库的 Commit Log 质量吧!

别忘了关注我，持续获取更多提升研发效能的实用技巧与深度解析。

6. 参考资料

• Conventional Commits v1.0.0 – https://www.conventionalcommits.org/en/v1.0.0/#specification

著名云主机服务厂商DigitalOcean发布最新的主机计划，入门级Droplet配置升级为：1 core CPU、1G内存、25G高速SSD，价格6$/月。有使用DigitalOcean需求的朋友，可以打开这个链接地址：https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

Gopher Daily(Gopher每日新闻) – https://gopherdaily.tonybai.com

我的联系方式：

• 微博(暂不可用)：https://weibo.com/bigwhite20xx
• 微博2：https://weibo.com/u/6484441286
• 博客：tonybai.com
• github: https://github.com/bigwhite
• Gopher Daily归档 – https://github.com/bigwhite/gopherdaily
• Gopher Daily Feed订阅 – https://gopherdaily.tonybai.com/feed

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

本文永久链接 – https://tonybai.com/2025/04/23/tips-for-reading-technical-books

大家好，我是Tony Bai。

今天是世界读书日。聊到读书，尤其是咱们技术人经常要面对的那些厚重的“技术砖头”，估计不少朋友都有过类似的挣扎：道理都懂，书很重要，但就是感觉难啃、读不进去，或者读完就忘，效果不彰。

技术书籍往往信息密集、逻辑严谨、内容晦涩，想要高效地从中汲取养分，确实需要讲究一些方法。我自己就是一个长期主义者，坚信持续学习和深入思考的力量。多年来，我不仅坚持阅读，也一直在我的博客tonybai.com以及本公众号上进行长期的、持续的输出，这个过程让我对如何高效阅读和内化知识，有了一些切身的体会和思考。 此外，如今AI工具日益强大，如何结合传统方法与智能辅助，是一个非常值得探讨的话题。

今天，我就结合我的长期实践，和大家分享一些个人实践，特别是在攻克难点和整理笔记环节，我也会着重谈谈AI如何能成为我的得力助手，希望能帮助你更好地攻克技术“硬书”，将知识真正转化为自己的竞争力。

心法一：明确目标，精准选书——为何而读？

在信息爆炸的时代，选对书可能比努力读更重要。开始前，先明确“为何而读”：

• 当前痛点/目标是什么？ (深入Go并发？掌握K8s？学习AI Agent开发？)
• 这本书能解决问题吗？ 通过看目录、序言、书评（例如在豆瓣读书、亚马逊评论区、O’Reilly Learning Platform、Manning官网 等站点优质站点查找）、作者背景来判断。
• 难度是否匹配？ (是否需要前置知识？)

我的做法： 基于工作和学习规划、以及遇到的技术瓶颈选书，优先选择能直接解决我当下问题的、或者能为我未来方向打下坚实基础的书(这的确需要一些前瞻性的技术眼光)。带着明确的目的去读，效率和动力都会高很多。

心法二：主动出击，建立框架——如何开始？

面对“砖头书”，忌直接死磕。先做“侦察”，建立整体认知：

• 速览目录、序言、总结： 把握全书结构、核心思想。
• 带着问题阅读： 主动思考你想从中获得什么答案。

我的做法： 我通常会先花半小时到一小时快速“翻阅”全书，在脑海里构建一个大致的知识地图。然后根据我的目标，决定是通读全书，还是重点阅读某些章节。对于特别重要的章节，我会先看一遍小结，再带着问题去细读正文。

心法三：攻克难点，允许“跳过”

遇到难啃的概念或复杂逻辑卡壳时：

• 别死磕，标记跳过： 保持阅读节奏，避免挫败感。后续内容或整体理解可能有助于回头解决。
• 寻求外援： 查阅资料、社区提问，或同主题书籍的交叉阅读，从多个角度帮助理解难啃的技术概念。

AI在此环节的“神助攻”

在这个最容易卡壳、也最考验耐心的环节，AI展现出了惊人的辅助潜力，能显著提升我们攻克难点的效率。以下是一些你可以尝试的提示词示例（以经典书籍《The Go Programming Language》为例）：

• 多角度解释：

  • “请用一个现实生活中的例子，解释《The Go Programming Language》中描述的 Go channel 的概念，特别是带缓冲和不带缓冲 channel 的区别。”
  • “我正在读 TGPL 关于 interface 的章节，对于『接口值』的内部结构（类型和值）有点模糊，请用更通俗的语言解释一下，并说明为什么 nil 接口值不等于包含 nil 指针的接口值？”
  • “请对比 TGPL 中提到的 goroutine 和传统操作系统线程，用打比方的方式解释goroutine的『轻量』体现在哪里？”

• 代码示例具象化：

  • “请根据《The Go Programming Language》中关于 select 语句的介绍，写一个简单的 Go 代码示例，展示如何使用 select 实现一个非阻塞的 channel 发送操作。”
  • “我需要理解 TGPL 中错误处理章节提到的 %w 动词，请提供一个 Go 代码片段，演示如何使用 fmt.Errorf 和 %w 来包装错误，并随后使用 errors.Is 和 errors.As 来检查和提取原始错误。”

• 模拟对话与“抬杠”：

  • “假设你是一位 Go 语言专家，我正在学习 TGPL 的并发章节。我对于 mutex 和 channel 的选择有些困惑，在什么场景下应该优先选择 mutex？什么时候 channel 是更好的选择？我们来讨论一下，请给出你的理由和实例。”
  • “我看到 TGPL 中提到『不要通过共享内存来通信，而应该通过通信来共享内存』。这句话很经典，但我对其理解不够深入。你能挑战我的理解吗？比如，在哪些情况下共享内存（如使用 sync.Mutex）反而是更合适的选择？请举例说明。”

AI就像一位不知疲倦、拥有广阔知识的“智能私教”，能够针对你的难点进行个性化的“辅导”，极大地加速了理解和突破瓶颈的过程。

心法四：提炼精华，有效笔记

“不动笔墨不读书”，关键是怎么记：

• 用自己的话总结： 这是内化的核心，检验是否真懂。
• 建立知识关联： 将新知识与旧知识联系起来。
• 代码示例验证： 亲自实践代码是关键。
• 结构化整理： 思维导图、结构化笔记等，用于复习和输出。但在我来看，这不是必须。

AI在此环节的“效率加速器”

在整理和消化大量信息的过程中，AI 同样能扮演好“智能助手”的角色，帮助我们提高效率，聚焦核心。以下是一些你可以尝试的提示词示例（同样以《The Go Programming Language》为例，前提是你拥有该书籍的电子版数据，用来喂给AI）：

• 辅助总结与提炼：

  • “请帮我将《The Go Programming Language》第七章『接口（Interfaces）』的核心内容，总结成 5-7 个关键要点，用 bullet points 形式列出。”
  • “我正在阅读 TGPL 关于『并发（Concurrency）』的部分，特别是 goroutine 和 channel。请提取这段内容中关于『select 语句』的主要用途和注意事项。”
  • （重要提示） AI 的总结是草稿，你必须用自己的理解去审核、修改、重写和完善，将信息转化为你自己的知识结构。

• 笔记结构化建议：

  • “我正在为《The Go Programming Language》的第五章『函数（Functions）』做笔记，请给我建议 2-3 种不同的笔记组织结构，例如概念分类、按重要性排序、或者 Q&A 形式。”

• 快速原型代码：

  • “根据 TGPL 中关于『方法（Methods）』的讨论，特别是嵌入（embedding）和方法集（method sets）的概念，请给我生成一个简单的 Go 代码示例，演示结构体嵌入后方法的调用规则。”
  • “请基于 TGPL 中对 go test 工具的介绍，给我生成一个包含基本测试函数、基准测试函数（benchmark）和示例函数（example）的简单 Go测试文件模板。”

AI在这里的作用，不是替代思考，而是将我们从一些相对重复、机械性的信息整理工作中解放出来，让我们能将宝贵的认知资源更集中地用于深度理解、批判性思考、知识关联和创造性应用上，这一点与“AI会写Go代码了，初学者还需要系统学习吗？”一文观点异曲同工。

心法五：学以致用，输出倒逼

阅读只是输入，真正的内化需要输出和实践，这是一个需要长期坚持的过程：

• 实践应用： 在项目中应用所学知识。
• 分享与教学： 写文章、做分享，输出是最好的学习。这也是我的实践精华。
• 参与讨论： 与他人交流碰撞思想。
• 持续回顾： 温故而知新。

我的做法： 我长期坚持在tonybai.com博客进行输出，这是我奉行长期主义、内化知识最重要的方式之一。 把学到的东西用自己的理解讲出来、写出来，这个过程本身就是对知识体系最好的锤炼和检验。同时，在星球里回答大家的提问，也是在不断地进行知识输出和巩固。没有输出的阅读，效果终将有限。

小结：拥抱工具，以我为主，终身学习

高效阅读技术书籍，是一项可以通过刻意练习而不断提升的技能。在 AI 时代，我们拥有了强大的工具来辅助我们攻克难关、整理信息。但请始终牢记，AI 是我们的“协处理器”和“智能拐杖”，思考和理解的主体，永远是我们自己。

找到适合自己的节奏，在关键环节善用AI的辅助，保持耐心和好奇心，将阅读视为一场需要长期投入的修行。

如果你希望将阅读和实践更紧密地结合起来，系统性地提升Go语言能力，并探索Go与AI的结合：

• 我把我多年 Go 语言实践和思考的精华，沉淀在了 《Go语言精进之路》 这本书中，它侧重于连接理论与实践，希望能为你打通 Go 语言学习的“任督二脉”。

• 同时，在我的知识星球 「Go & AI 精进营」 中，我开设了像 【Go进阶课】 这样覆盖语法强化、设计先行与工程实践的体系化课程，并提供深度的 专家答疑 和活跃的 社区交流。我们一起学习，一起实践，一起拥抱 Go 和 AI 的未来。

【世界读书日 · 特别福利】点赞 + 留言 + 在看，赢取签名版《Go语言精进之路》！

为了感谢大家一直以来的支持，并响应世界读书日的精神，鼓励大家在阅读与实践的道路上不断精进，我特别准备了一个【世界读书日专属福利】活动！参加门槛很低，大家只需移步到我的公众号同名文章下点赞 + 留言 + 在看，我将结合留言内容的质量与【在看】情况，从参与本次活动的读者中，抽取1位幸运儿赠送一本由我亲笔签名的《Go语言精进之路》(卷1或卷2随机)！获奖名单将在五一劳动节当天公布，获奖读者请在名单公布后的 48 小时内，主动通过公众号后台联系我，并提供准确的邮寄信息，以便我将签名版书籍寄送给您。

活动时间：即刻起 – 2025年04月30日23:59。

期待大家的踊跃参与和精彩分享！ 让我们在阅读与交流中，共同进步！

希望今天分享的这些心法和 AI 应用思路能对你有所启发。你有什么高效阅读技术书籍的独门秘诀？或者你觉得 AI 在学习中还能扮演哪些角色？欢迎在评论区留言交流！

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。如有需求，请扫描下方公众号二维码，与我私信联系。