chinese-commit-conventions

中文 Git 提交规范

1. Conventional Commits 中文适配

基于 Conventional Commits 1.0.0 规范，针对中文团队的实际使用习惯进行适配。

类型（type）定义

类型	说明	示例场景
feat	新功能	添加用户注册模块
fix	修复缺陷	修复登录页白屏问题
docs	文档变更	更新 API 接口文档
style	代码格式（不影响逻辑）	调整缩进、补充分号
refactor	重构（非新功能、非修复）	拆分过长的服务类
perf	性能优化	优化首页列表查询速度
test	测试相关	补充用户模块单元测试
chore	构建/工具/依赖变更	升级 webpack 到 v5
ci	持续集成配置	修改 GitHub Actions 流程
revert	回滚提交	回滚 v2.1.0 的登录重构

原则

• type 保留英文关键字（工具链兼容性好）
• scope 和 description 使用中文
• body 使用中文完整描述

2. 中文 commit message 模板

<type>(<scope>): <subject>

<body>

<footer>

完整示例

feat(用户模块): 添加手机号一键登录功能

- 接入运营商一键登录 SDK
- 支持移动、联通、电信三网
- 登录失败自动降级到短信验证码

Closes #128

fix(订单): 修复并发下单导致库存超卖的问题

在高并发场景下，原有的库存扣减逻辑存在竞态条件。
改用 Redis 分布式锁 + 数据库乐观锁双重保障。

影响范围：订单服务、库存服务
测试确认：已通过 500 并发压测验证

Closes #256

3. Subject 行规范

格式

<type>(<scope>): <description>

规则

• type: 必填，从上方类型表中选取
• scope: 选填，表示影响范围，使用中文模块名
  • 示例：用户模块、订单、支付、基础组件
• description: 必填，中文简述，不超过 50 个字符
  • 使用动宾短语：「添加 xxx」「修复 xxx」「优化 xxx」
  • 不加句号结尾
  • 不要写「修改了代码」这种无意义描述

好的示例

feat(权限): 添加基于 RBAC 的细粒度权限控制
fix(支付): 修复微信支付回调签名验证失败的问题
perf(列表页): 优化大数据量表格的虚拟滚动渲染
refactor(网关): 将单体网关拆分为独立微服务

反面示例

# 以下写法应避免
fix: 修了一个 bug
feat: 更新代码
chore: 改了点东西

4. Body 编写规范

Body 用于详细说明本次变更的动机、方案和影响。

编写要点

• 说明为什么要做这个改动（背景/原因）
• 说明怎么做的（技术方案摘要）
• 说明影响范围（哪些模块、接口受影响）
• 每行不超过 72 个字符（中文约 36 个汉字）
• 正文与标题之间空一行

Body 模板

<改动背景和原因>

技术方案：
- <方案要点 1>
- <方案要点 2>

影响范围：<受影响的模块或服务>

5. Breaking Changes 标注

当提交包含不兼容变更时，必须在 footer 中标注。

格式一：footer 标注

feat(接口): 重构用户信息返回结构

将用户接口返回的扁平结构改为嵌套结构，前端需同步调整字段取值路径。

BREAKING CHANGE: /api/user/info 返回结构变更
- avatar 字段移入 profile 对象
- 移除已废弃的 nickname 字段，统一使用 displayName

格式二：type 后加感叹号

feat(接口)!: 重构用户信息返回结构

团队约定

• 涉及数据库表结构变更 -> 必须标注 BREAKING CHANGE
• 涉及公共 API 参数/返回值变更 -> 必须标注
• 涉及配置文件格式变更 -> 必须标注
• 标注时须写明迁移方法或升级步骤

6. Issue 关联

GitHub 格式

Closes #128
Refs #129, #130

Gitee 格式