项目代码提交规范

# 项目代码提交规范

本规范基于 Conventional Commits 1.0.0 (opens new window) 及 Angular Commit Guidelines (opens new window)，结合团队实践整理。

# 目录

01.Commit规范概述
02.CommitMessage格式
03.语义化版本与CHANGELOG
- 3.1 语义化版本规则
- 3.2 自动生成CHANGELOG
04.分支管理规范
05.GitHook与自动化
06.代码审查规范
07.Tag规范与管理
08.跨平台对比
09.常见反模式

# 01.Commit规范概述

# 1.1 为何需要提交规范

疑惑：代码能跑就行，commit message随便写不行吗？

答疑：当你半年后需要查找一个Bug的引入时间，面对以下两种提交记录：

# 无规范的提交记录
fix bug
update
修改了一些东西
test
asdfgh
aaa

# 有规范的提交记录
fix(login): 修复登录页面密码输入框无法获取焦点的问题 (#1234)
feat(order): 新增订单批量导出功能，支持CSV和Excel格式
refactor(network): 将网络层升级到OkHttp4，统一超时配置
chore(deps): bump lodash from 4.17.15 to 4.17.21

1
2
3
4
5
6
7
8
9
10
11
12
13

规范化提交信息是项目的可追溯文档，git log 就是你的变更日志。

# 1.2 规范的核心价值

价值	说明
自动生成CHANGELOG	`conventional-changelog` 从 commit 自动生成版本变更日志
快速定位问题	`git log --grep="fix(login)"` 精确搜索模块相关变更
语义化版本自动推断	`fix` → patch, `feat` → minor, `BREAKING CHANGE` → major
触发CI/CD	特定类型的 commit 可触发不同的自动化流水线
代码审查效率	Reviewer 一看标题就知道改了什么
新人上手成本低	统一风格降低沟通成本，git log 本身成为项目文档

# 1.3 适用范围

所有 Git 仓库的 commit message 均遵循本规范
前端/后端/移动端/基础库项目统一使用
Pull Request 的 squash merge 消息同样遵循此格式

# 02.CommitMessage格式

# 2.1 标准格式定义

采用 Conventional Commits 1.0.0 规范（Angular 风格）：

&lt;type>(&lt;scope>): &lt;subject>
空行
&lt;body>
空行
&lt;footer>

1
2
3
4
5

各部分说明：

部分	是否必填	说明
type	必填	提交类型（见 2.2）
scope	可选	影响范围/模块名，用括号括起
subject	必填	简短描述，≤ 50 字符，中文
body	可选	详细描述，每行 ≤ 72 字符，说明 what 和 why
footer	可选	关联 issue / Breaking Changes 声明

# 2.2 类型标识说明

类型	说明	语义化版本影响	示例
`feat`	新功能	minor	`feat(user): 添加手机号注册功能`
`fix`	修复Bug	patch	`fix(cart): 修复数量为0时仍可结算的问题`
`docs`	文档变更（README、注释、API文档）	—	`docs(api): 补充接口返回码说明`
`style`	格式调整（空格、分号、缩进等，不影响逻辑）	—	`style: 统一缩进为4个空格`
`refactor`	重构（不新增功能、不修Bug）	—	`refactor(db): 提取公共查询方法`
`perf`	性能优化	patch	`perf(list): 列表滚动使用虚拟化渲染`
`test`	测试相关（新增/修改/删除测试）	—	`test(login): 补充登录失败的单元测试`
`build`	构建系统或外部依赖变更（Gradle/Maven/npm等）	patch	`build: 升级Gradle到8.0`
`ci`	CI/CD 配置变更（Jenkinsfile/GitHub Actions 等）	—	`ci: 添加自动化代码检查流程`
`chore`	其他不修改 src/test 的杂项	—	`chore: 更新.gitignore`
`revert`	回退之前的提交	根据被回退的提交而定	`revert: 回退feat(user)的注册功能`

注：build 影响语义化版本，因为依赖变更可能影响消费者。

# 2.3 scope 范围说明

scope 标识此次修改影响的模块，常见取值：

Android项目：

feat(login):         登录模块
fix(network):        网络层
refactor(base):      基础库
perf(image):         图片加载
test(utils):         工具类测试

1
2
3
4
5

前端项目：

feat(component):     组件
fix(router):         路由
perf(bundle):        打包优化
style(theme):        主题样式
chore(deps):         依赖升级

1
2
3
4
5

后端项目：

feat(api):           API接口
fix(db):             数据库
refactor(service):   业务服务
perf(cache):         缓存层

1
2
3
4

通用模块：

ci:                  CI/CD
build:               构建系统
release:             发布相关
config:              配置文件

1
2
3
4

# 2.4 Subject 正文规范

✅ 规则：
1. 使用中文（团队统一），不超过 50 个字符
2. 使用祈使句（"添加"而非"添加了"或"添加过"）
3. 首字母不用大写
4. 结尾不加句号
5. 说清楚"做了什么"，而非"改了什么文件"

1
2
3
4
5
6

✅ 正确	❌ 错误	问题
`添加微信支付功能`	`添加了微信支付功能`	不用"了"
`修复OOM崩溃问题`	`修复了一个OOM崩溃`	去掉"一个"
`删除废弃的 v1 接口`	`删除文件`	太模糊
`重构网络层超时配置`	`重构NetWork模块网络请求的超时配置逻辑`	超过 50 字符

# 2.5 Body 与 Footer 规范

Body（详细描述）：

✅ 规则：
1. 说明变更的动机（why）和具体做了什么（what）
2. 每行不超过 72 个字符
3. 与 subject 之间空一行
4. 可以用列表形式组织（- 开头）

1
2
3
4
5

Footer（页脚信息）：

✅ Breaking Changes（不兼容变更）—— 必须以 BREAKING CHANGE: 开头
✅ 关联 Issue —— Closes #123、Fixes #456、Refs #789

1
2

完整示例：

feat(payment): 接入微信支付SDK，支持App支付和H5支付

集成微信支付 SDK v6.8.0，封装统一支付接口 PaymentManager。
支持以下支付方式：
- App支付：唤起微信客户端完成支付
- H5支付：微信外部浏览器完成支付
- 支付结果回调统一处理，支持成功/取消/失败三种状态

BREAKING CHANGE: PaymentManager 重构了 init 方法签名，
原来接受单个参数 String appId，现在改为 PaymentConfig 对象。
迁移方式请参考 `UPGRADE.md`。

Closes #456
Reviewed-by: @zhangsan

1
2
3
4
5
6
7
8
9
10
11
12
13
14

Breaking Changes 格式：

feat(user): 重构用户认证模块

采用 JWT Token 替代原有的 Session 认证方案

BREAKING CHANGE: 用户登录接口返回格式变更
旧格式: { "token": "...", "expire": 3600 }
新格式: { "accessToken": "...", "refreshToken": "...", "expiresIn": 3600 }

1
2
3
4
5
6
7

# 2.6 场景化示例

# 1. 简单新功能
feat(order): 新增订单批量导出功能

# 2. Bug修复 + issue关联
fix(image): 修复大图加载时OOM崩溃

问题原因：未对超大图片进行采样压缩
解决方案：加载前通过BitmapFactory.Options计算采样率

Fixes #789

# 3. 重构（无功能变更）
refactor(network): 将网络层超时配置统一提取到ConfigManager

提取硬编码的超时值到统一配置中，便于后续A/B测试。

# 4. 性能优化（附基准数据）
perf(list): RecyclerView滚动性能优化，FPS从45提升到58

优化手段：
- 使用DiffUtil替代notifyDataSetChanged
- ViewHolder绑定数据时减少findViewById调用
- 图片加载增加尺寸预处理

Benchmark:
- 优化前：列表滑动平均 FPS 45，卡顿率 8.3%
- 优化后：列表滑动平均 FPS 58，卡顿率 0.5%

# 5. 回退
revert: 回退 feat(payment) 的微信支付功能

线上出现 NoClassDefFoundError 崩溃，需要排查集成问题

Refs #890

# 6. 依赖升级
chore(deps): bump retrofit from 2.9.0 to 2.11.0

解决与 OkHttp 4.12 的兼容性问题，详见官方 CHANGELOG。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

# 2.7 常见错误与修正

#	错误提交	问题	修正
1	`修复bug`	无type/scope	`fix(login): 修复密码输入框焦点问题`
2	`fix: update`	描述无意义	`fix(cache): 修复LRU缓存淘汰策略溢出`
3	`feat: 新增了一个非常复杂的包含60个字符以上的功能描述`	超长	精简到 ≤ 50 字符
4	`Fix(login): fixed 登录 bug.`	中英混杂、大写、句号	`fix(login): 修复登录接口401错误`
5	`feat: 修改了xxx`	新功能不是"修改"	`feat: 添加xxx`
6	`update code`	完全无意义	说明具体变更内容
7	`Merge branch 'feature'`	默认 merge 消息	squash merge + 有意义的消息

# 03.语义化版本与CHANGELOG

# 3.1 语义化版本规则

采用 Semantic Versioning 2.0.0 (opens new window)：

主版本号.次版本号.修订号  →  MAJOR.MINOR.PATCH

版本位	递增时机	对应commit类型	示例
MAJOR	不兼容的API变更	`BREAKING CHANGE`	2.0.0 → 3.0.0
MINOR	向下兼容的新功能	`feat`	2.1.0 → 2.2.0
PATCH	向下兼容的问题修复	`fix`, `perf`	2.1.3 → 2.1.4

# 3.2 自动生成 CHANGELOG

# 安装 conventional-changelog（Node.js 项目）
npm install --save-dev conventional-changelog-cli

# 自动生成 CHANGELOG
npx conventional-changelog -p angular -i CHANGELOG.md -s

# 首次生成（覆盖）
npx conventional-changelog -p angular -i CHANGELOG.md -s -r 0

# 添加到 npm scripts
# "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"

1
2
3
4
5
6
7
8
9
10
11

生成效果示例：

## 2.2.0 (2024-03-15)

### Features

* **order**: 新增订单批量导出功能，支持CSV和Excel格式 ([abc1234])
* **user**: 添加手机号注册功能 ([def5678])

### Bug Fixes

* **login**: 修复登录页面密码输入框焦点问题 ([ghi9012])
* **image**: 修复大图加载时OOM崩溃 ([jkl3456])

### Performance Improvements

* **list**: RecyclerView滚动性能优化，FPS提升至58 ([mno7890])

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 04.分支管理规范

# 4.1 分支命名规则

分支类型          命名格式                      示例
──────────────   ────────────────────────     ────────────────────────────
主分支           main / master                main
开发分支         develop                      develop
功能分支         feature/&lt;模块>-&lt;描述>         feature/login-wechat-login
                 feature/&lt;issue号>-&lt;描述>      feature/456-excel-export
修复分支         fix/&lt;描述>                    fix/oom-image-loading
                 fix/&lt;issue号>-&lt;描述>           fix/789-crash-on-rotate
发布分支         release/&lt;版本号>              release/2.1.0
热修复分支       hotfix/&lt;版本号>-&lt;描述>         hotfix/2.0.1-payment-fix

1
2
3
4
5
6
7
8
9
10

命名细则：

全小写，单词用连字符 - 分隔
功能分支有明确终点（完成即合并，然后删除）
不用个人名字做分支名（如 zhangsan/test → 用模块名）

# 4.2 GitFlow 工作流

main    ───────●───────────────●─────────────── (生产环境，只接受 release/hotfix 合并)
                \             /
release/2.1 ─────●─────●─────●                  (发布准备：只修bug、改版本号)
                  \   /
develop ───────────●──●──●──●──●────────────── (开发主线)
                    \  \     /
feature/A ───────────●──●───/                  (功能分支：从 develop 拉出，合并回 develop)
                      \
feature/B ─────────────●──●                    (功能分支)
                          \
hotfix/2.0.1 ──────────────●──────────────────  (从 main 拉出，合并回 main + develop)

1
2
3
4
5
6
7
8
9
10
11

三原则：

main 分支永远处于可部署状态
所有开发在 feature 分支进行，完成后提 PR 到 develop
hotfix 直接从 main 拉出，修复后同时合并到 main 和 develop

# 4.3 分支合并策略

场景	策略	命令	说明
feature → develop	Squash Merge	`git merge --squash`	功能分支的多条 commit 压缩为一条，保持 develop 历史简洁
develop → main	Merge Commit	`git merge --no-ff`	保留分支历史，知道哪些提交属于同一个 release
hotfix → main	Merge Commit	`git merge --no-ff`	保留热修复轨迹
同步上游到 feature	Rebase	`git rebase develop`	保持 feature 分支线性历史，避免多余的 merge commit

Squash Merge 示例：

# 在 develop 分支执行
git checkout develop
git merge --squash feature/login-wechat
git commit -m "feat(login): 接入微信登录功能

支持微信OAuth2.0授权登录
- 接入微信SDK v6.8.0
- 封装WxAuthManager统一授权流程
- 添加登录状态持久化

Closes #123"

1
2
3
4
5
6
7
8
9
10
11

# Squash 前（feature 分支上 5 个小提交）：
* a1b2c3 - fix: 修复回调参数
* d4e5f6 - wip: 调试中
* g7h8i9 - feat: 添加token刷新
* j0k1l2 - feat: 接入SDK
* m3n4o5 - chore: 添加依赖

# Squash 后（develop 上 1 条整洁提交）：
* p5q6r7 - feat(login): 接入微信登录功能

1
2
3
4
5
6
7
8
9

# 05.GitHook与自动化

# 5.1 commit-msg 校验

方案一：commitlint（Node.js 项目推荐）

# 安装
npm install --save-dev @commitlint/cli @commitlint/config-conventional

# 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']
        ],
        'subject-max-length': [2, 'always', 50],
        'subject-case': [0],            // 允许中文
        'header-max-length': [2, 'always', 72],
    }
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 配置 husky（Git Hook 管理工具）
npx husky add .husky/commit-msg 'npx --no-install commitlint --edit $1'

1
2

方案二：自定义正则校验（非 Node.js 项目）

#!/bin/bash
# .git/hooks/commit-msg

COMMIT_MSG=$(cat "$1")

# 正则匹配：type(scope): subject
PATTERN='^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([a-zA-Z0-9_-]+\))?: .{1,50}$'

if ! echo "${COMMIT_MSG}" | head -1 | grep -qE "${PATTERN}"; then
    echo "❌ Commit message 格式错误！"
    echo ""
    echo "正确格式：<type>(<scope>): <subject>"
    echo "示例：feat(login): 接入微信登录功能"
    echo "     fix(cart): 修复数量为0时可结算的问题"
    echo ""
    exit 1
fi

echo "✅ Commit message 格式检查通过"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 5.2 pre-commit 检查

# 安装 lint-staged（仅对暂存文件执行检查）
npm install --save-dev lint-staged

# package.json 或 .lintstagedrc.json
{
    "lint-staged": {
        "*.{java,kt}": [
            "./gradlew spotlessCheck"
        ],
        "*.{js,ts}": [
            "eslint --fix",
            "prettier --write"
        ],
        "*.{swift}": [
            "swiftlint lint --strict"
        ]
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# husky pre-commit 钩子
npx husky add .husky/pre-commit 'npx lint-staged'

1
2

# 5.3 CI/CD 联动

# GitHub Actions: 根据 commit 类型触发不同流程
name: CI

on:
  push:
    branches: [main, develop]

jobs:
  # 永远执行
  lint-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

  # 仅 feat/fix 类型的提交
  deploy-staging:
    if: |
      startsWith(github.event.head_commit.message, 'feat') || 
      startsWith(github.event.head_commit.message, 'fix')
    needs: lint-and-test
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy-staging.sh

  # 仅 BREAKING CHANGE 触发
  notify-breaking:
    if: contains(github.event.head_commit.message, 'BREAKING CHANGE')
    runs-on: ubuntu-latest
    steps:
      - run: ./notify-team.sh

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

# 06.代码审查规范

# 6.1 PR 提交规范

Pull Request 描述模板（.github/PULL_REQUEST_TEMPLATE.md）：

## 变更说明
<!-- 简述本次 PR 的目的和主要变更内容 -->

## 变更类型
- [ ] feat: 新功能
- [ ] fix: Bug修复
- [ ] refactor: 重构
- [ ] perf: 性能优化
- [ ] docs: 文档
- [ ] test: 测试
- [ ] build/ci: 构建/CI
- [ ] chore: 其他

## 影响范围
<!-- 涉及的模块和可能影响的功能 -->

## 测试说明
<!-- 如何验证本次变更，包括测试用例覆盖情况 -->

### 已测试场景
- [ ] 正常路径
- [ ] 边界条件（空数据、极值、超时等）
- [ ] 异常路径（网络失败、权限不足等）

## 截图/录屏
<!-- UI 变更请附截图/录屏 -->

## 关联 Issue
Closes #xxx

## 自检清单
- [ ] 代码符合项目编码规范
- [ ] Commit message 符合 Conventional Commits 规范
- [ ] 无硬编码的敏感信息（密钥、密码、Token）
- [ ] 新增代码有必要的注释
- [ ] 已添加或更新相关单元测试
- [ ] 已考虑向后兼容性
- [ ] 无明显的性能问题

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

# 6.2 审查检查清单

# 必须项（不通过即驳回）

[ ] CI 全部通过：lint、test、build 无失败
[ ] 无安全漏洞：无硬编码密钥、无 SQL 注入、无 XSS 风险
[ ] Commit 格式：message 符合 Conventional Commits
[ ] 无破坏性变更：除非明确标注 BREAKING CHANGE
[ ] 测试覆盖：新增代码有对应测试，修改的代码测试仍然通过

# 审查要点

[ ] 命名合理：类/函数/变量命名符合项目规范
[ ] 职责单一：一个函数只做一件事，一个 PR 只改一个关注点
[ ] 无重复代码：公共逻辑提取为工具函数/类
[ ] 错误处理：异常路径有正确处理，不是空 catch
[ ] 性能考虑：无明显 N+1 查询、循环中频繁 I/O、大对象不必要拷贝
[ ] 可读性：代码意图清晰，复杂逻辑有注释
[ ] 向后兼容：API 变更是否影响下游消费者

# 6.3 PR 尺寸建议

PR 大小	变更行数	审查体验	建议
小	≤ 200 行	⭐⭐⭐ 快速审查	目标规格
中	200-500 行	⭐⭐ 可接受	需要拆分为 2 个 PR
大	500-1000 行	⭐ 吃力	必须拆分
超大	> 1000 行	无法有效审查	拒绝，要求拆分

# 07.Tag 规范与管理

# Tag 命名格式：v<MAJOR>.<MINOR>.<PATCH>
# 示例：v2.1.0, v2.1.1, v3.0.0-beta.1, v2.0.0-rc.2

# 创建轻量标签（不推荐）
git tag v2.1.0

# 创建附注标签（推荐：含发布说明）
git tag -a v2.1.0 -m "v2.1.0

### Features
- feat(order): 新增订单批量导出功能
- feat(user): 添加手机号注册

### Bug Fixes
- fix(login): 修复密码输入框焦点问题
- fix(image): 修复大图OOM崩溃"

# 推送标签到远程
git push origin v2.1.0

# 推送所有标签
git push origin --tags

# 删除本地标签
git tag -d v2.0.0

# 删除远程标签
git push origin --delete v2.0.0

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

预发布版本：

# Alpha：内部测试
git tag -a v2.0.0-alpha.1 -m "v2.0.0-alpha.1"

# Beta：公开测试
git tag -a v2.0.0-beta.1 -m "v2.0.0-beta.1"

# RC (Release Candidate)：候选发布
git tag -a v2.0.0-rc.1 -m "v2.0.0-rc.1"

1
2
3
4
5
6
7
8

# 08.跨平台对比

# 8.1 各平台 Git 规范

平台/组织	规范标准	工具支持	特点
Angular	Angular Commit Convention	commitlint	最早提出者，Conventional Commits 起源
Google	Google Commit Guidelines	gerrit + hook	强调变更描述和测试
阿里	阿里 Java 开发手册 + Aone	p3c 插件 + Aone 平台	合入主干前强制 code review
腾讯	工蜂规范 + 蓝盾 CI	蓝盾流水线	分支保护 + CI 门禁
微软	Conventional Commits	husky + lint-staged	VSCode / TypeScript 团队使用
开源社区	Semantic Versioning + Conventional Commits	semantic-release	全自动发版

# 8.2 工具链选型推荐

技术栈	推荐工具组合
Node.js / 前端	`commitlint` + `husky` + `lint-staged` + `conventional-changelog`
Java / Kotlin	Git Hook 脚本 + `spotless` (格式) + `detekt` (分析)
Python	`pre-commit` + `commitizen` + `python-semantic-release`
Go	自定义 Git Hook + `gofmt` + `golangci-lint`
Swift / iOS	Git Hook 脚本 + `SwiftLint` + `SwiftFormat`
Rust	`pre-commit` + `rustfmt` + `clippy`

# 09.常见反模式

反模式	问题	改进
"update" / "fix bug" 作为 message	完全无信息量	`fix(login): 修复xxx的具体问题`
一个 PR 包含 20+ 条 commit	其中 wip/fix typo 等无意义 commit	发 PR 前 `git rebase -i` 整理或 squash merge
`git add .` 无筛选提交	把所有修改一次性提交，变更范围过大	按逻辑分组，不同关注点分多次 commit
merge commit 乱飞	`git pull` 产生大量无意义 merge commit	`git pull --rebase`
commit 中包含 TODO 注释	缺少跟踪机制	TODO 注释必须关联 issue 编号
提交敏感信息	密钥、Token、密码被提交到仓库	`.gitignore` + `git-secrets` 扫描
force push 到共享分支	覆盖他人工作	仅在自己的 feature 分支使用 `--force-with-lease`
提交编译产物（.class / dist / build）	仓库体积膨胀	`.gitignore` 排除编译产物
分支长期不合并导致冲突堆积	合并时的冲突地狱	每日 rebase develop，控制分支 ≤ 3 天
commit 中包含大文件（>10MB）	拖慢 clone/fetch	用 Git LFS 管理大文件

本文档将随团队实践演进持续更新，欢迎通过 GitHub issues (opens new window) 反馈问题和建议。

#Git #规范

上次更新: 2026/06/17, 11:39:29

← Shell编程代码规范指南 Markdown 写作指南→