团队协作开发时，Git 提交记录不只是 "保存一下代码"，它还是后来排查问题、回滚代码、生成版本日志的重要线索。
如果提交记录都长这样：修改 更新一下 提交代码 修复 bug
时间一久，谁也看不懂这次提交到底干了什么。所以很多团队会使用一套比较通用的提交信息规范：Conventional Commits。
一、基本格式
推荐格式：
<type>(<scope>): <subject>示例：
feat(org): 新增集货点导出接口
fix(order): 修复待揽收订单统计错误
refactor(role): 移除角色编码唯一性校验
docs(api): 补充运费配置接口说明由三部分组成：
- type：提交类型
- scope：影响范围
- subject：本次提交说明
二、type：提交类型
type 用来说明这次提交属于什么性质。
常见类型：
-
feat：新功能
-
fix：修复 bug
-
refactor：重构，不改变功能
-
perf：性能优化
-
docs：文档修改
-
style：代码格式调整，不影响逻辑
-
test：新增或修改测试
-
chore：杂项，比如配置、脚本、依赖
-
build：构建相关，比如 Maven、Docker
-
ci：CI/CD 配置
-
revert：回滚提交
feat(freight): 新增按地区匹配运费配置接口
fix(org): 修复集货点导出空数据异常
refactor(org): 拆分网点和集货点分页接口
perf(org): 优化网点分页统计批量查询
docs(org): 补充分页筛选条件注释
三、scope：影响范围
scope 表示这次提交主要影响哪个模块。建议使用小写英文，尽量短一些。
常见写法：org、order、user、role、vehicle、freight、dict、auth、export、mapper、dto、api
feat(org): 新增网点分页统计字段
fix(order): 修复订单状态快照统计错误
refactor(dto): 优化批量操作DTO结构使用规则：
- 一次改了多个模块，写主要模块即可：
feat(org): 新增集货点库存统计字段 - 可写泛化范围：
refactor(api): 调整组织分页返回结构 - 不建议写得过细过长：
feat(master-data-org-collection-point-export): 新增导出（可读性差）
四、subject：提交说明
subject 是一句话说明本次提交的内容，建议用中文清晰描述。
示例：
feat(freight): 新增运费配置按ID和地区查询接口
fix(org): 修复集货点导出字段映射错误
refactor(role): 移除角色编码唯一性校验书写注意事项：
- 用动词开头：新增、修复、调整、优化、移除、重构
- 不写废话：禁止
fix(org): 修改bug、chore: 提交代码、feat: 更新一下 - 控制长度：50 字以内
- 结尾无需加句号
五、常用模板
可直接套用以下模板：
feat(module): 新增xxx功能
fix(module): 修复xxx问题
refactor(module): 重构xxx逻辑
perf(module): 优化xxx查询性能
docs(module): 补充xxx说明
chore(module): 调整xxx配置示例：
feat(freight): 新增运费配置按地区兜底查询
fix(org): 修复集货点导出非集货点ID异常
refactor(org): 拆分网点和集货点分页接口
perf(order): 优化订单快照批量查询
docs(api): 补充导出接口参数说明
chore(config): 调整本地开发配置六、实际项目里的写法示例
结合常见后端项目，规范写法如下：
新增功能
feat(org): 新增集货点分页接口
feat(freight): 新增运费配置按ID和地区查询接口
feat(order): 新增订单状态快照查询Facade修复问题
fix(org): 修复集货点导出字段映射错误
fix(order): 修复退款后订单统计未扣减问题
fix(auth): 修复登录用户角色为空异常重构代码
refactor(org): 拆分网点和集货点分页逻辑
refactor(dto): 优化批量操作请求结构
refactor(role): 移除角色编码唯一性校验性能优化
perf(org): 优化网点分页统计批量查询
perf(order): 优化订单快照按组织批量查询文档和注释
docs(org): 补充分页接口筛选条件注释
docs(api): 补充运费配置接口说明七、什么时候不用 scope？
如果改动很泛，或者不属于某个具体模块，可以省略 scope：
chore: 调整项目配置
docs: 更新接口说明文档
build: 调整Maven构建配置业务项目中，建议尽量带上 scope，提升提交记录可读性。
八、总结
一条好的提交信息，能让人一眼看懂三件事：
- 这次是什么类型的改动
- 影响哪个模块
- 具体做了什么
推荐格式：
<type>(<scope>): <subject>推荐示例：
feat(freight): 新增运费配置按ID和地区查询接口
fix(org): 修复集货点导出字段映射错误
refactor(org): 拆分网点和集货点分页接口
perf(order): 优化订单快照批量查询提交信息写规范，后续排查问题、查看历史、生成版本日志都会更高效。