一、合作规范#

基于规范提供更丰富的提交历史信息，加速代码审查，和保持提交历史的整洁

1.1 Commit 结构#

每个 commit 消息都包含三个部分：header, body, 和 footer。

1
<type>(<scope>): <subject>
2
<BLANK LINE>
3
<body>
4
<BLANK LINE>
5
<footer>

Header: type、scope 和 subject 是必需的。
- type: 必须是以下类型之一：
  - feat: 引入一个新功能。
  - fix: 修复一个 bug。
  - docs: 只修改了文档。
  - style: 不影响代码含义的改动（如格式化、删除空格等）。
  - refactor: 代码重构，既不是修复 bug 也不是添加功能。
  - perf: 提升性能的代码改动。
  - test: 添加或修改测试。
  - build: 影响构建系统或外部依赖的改动（如 go.mod、Makefile）。
  - ci: 对 CI 配置文件和脚本的改动。
- scope (可选): 指明本次提交影响的范围（如 model, controller, ci）。
- subject: 对变更的简洁描述，统一使用中文，不超过 50 个字符，结尾不加句号。
Body (可选): 对变更的更详细描述，解释变更的背景、动机和实现细节。
Footer (可选): 用于存放关联的文档链接（如飞书文档、Meego），或标记 BREAKING CHANGE

1.2 Commit 示例#

一个好的 commit 应该清晰、简洁地描述其目的和内容，并提供必要的上下文

示例 1：一个简单的新功能

1
feat(api): 支持在搜索结果中展示用户头像
2

3
在用户搜索接口的返回结构体中增加 `AvatarURL` 字段，
4
并从用户中心服务获取对应的头像地址。
5
该功能用于优化搜索结果页的用户体验。

示例 2：包含破坏性变更的重构

1
refactor(auth): 重构认证模块以支持多点登录
2

3
将原有的单点登录逻辑修改为基于 Token 的多点登录机制。
4
调整了 `Login` 接口的返回结构，并废弃了 `Session` 相关表。
5

6
BREAKING CHANGE:
7
- `Login` 接口不再返回 `session_id`，改为返回 `access_token` 和 `refresh_token`。
8
- 客户端需要适配新的登录流程，使用 `refresh_token` 刷新 `access_token`。
9
- 相关的用户会话管理功能已移除。
10

11
Doc: https://bytedance.feishu.cn/wiki/wikcnxxxxxxxxxxxx

二、分支管理#

1.2 分支命名模板#

1.需求分支（Feature）

前缀：feature/ 或 feat/
用途：用于开发新功能或需求，从开发分支（develop）创建，完成后合并回develop。
命名示例
- feature/user-login_20250212_JIRA-123
- feature/20250212_SSO-implementation
- feat/payment-integration （功能描述 + 日期 + 任务ID，增强可追溯性）

2.Bug修复分支

前缀：bugfix/ 或 fix/
**用途：**从develop分支创建，修复后合并回develop。
命名示例
- bugfix/login-error_20250212_JIRA-456
- fix/404-page-redirect

3.热修复分支（Hotfix）

前缀：hotfix/
**用途：**从master分支创建，修复后需同时合并到master和develop。
命名示例
- hotfix/security-patch_20250212

分支类型	前缀	创建来源	合并目标	场景
需求分支	feature/	develop	develop	新功能开发
Bug修复分支	bugfix/	develop	develop	普通Bug修复
热修复分支	hotfix/	master	master + develop	生产环境紧急修复

最高推荐（团队使用） <type>/<ticket-id>-<kebab-case-description>

1
feature/JIRA-1234-add-social-login
2
bugfix/LINEAR-567-fix-mobile-navbar-overflow
3
hotfix/urgent-fix-2026-01-rce-vulnerability
4
refactor/remove-deprecated-auth-endpoint

无 ticket 系统时的简化版（个人/小团队常用）

1
feature/add-dark-mode-toggle
2
bugfix/login-button-disabled-state
3
hotfix/increase-api-timeout-30s

带日期的紧急 hotfix（安全事件常用）

1
hotfix/2026-01-15-security-patch-jwt

禁止 / 不推荐的命名方式#

test、tmp、fix、new、update、bug（太泛，无信息量）
feature123、bug-456（没有前缀分类）
Feature/LoginPage（大写 + 驼峰）
feature_user_profile（下划线，排序不友好）
超长名字：this-is-a-very-very-long-branch-name-for-testing-purposes-only（阅读困难）
只用数字：12345、20260116（完全看不懂）

`git rebase`和`git merge`#

git rebase和git merge一样都是用于从一个分支获取并且合并到当前分支，但工作方式不同

假设当前你在feature分支上进行新功能的开发，与此同时master分支上也合入了其他人提交的代码如果采用merge的方式将master上新的代码合并到本地的feature分支上：

1
git merge master feature

此时git会在feature上自动产生一个新的commit（合并提交） merge最大的好处就是它是安全的，现有的分支不会被更改，从而避免了接下来要讲的rebase潜在的缺点。当合并过程中遇到冲突时，仅需要修改后重新commit。虽然merge详尽记录了真实commit的详情（并不一定是坏处），但是当master非常活跃时，每次合并上游更改都将引入一个合并提交，会产生比较多的分叉，这多少会污染提交记录，不利于后续梳理分支历史。

rebase则是采用了另外一种思路。当使用rebase时，git会找到feature和master两条分支的最近公共祖先（LCA），然后从master节点开始，重放从LCA到feature最近提交之间的所有提交，也就是把整个feature分支移动到master的后面，从而把master上新的提交合并进来

rebase最大的好处就是项目历史会非常整洁，不会像merge那样引入自动生成的合并提交，从而使得项目历史呈现出完美的线性——可以从项目的终点浏览到起点而不会遇到任何分叉。但是由于rebase本质上是重写提交历史，因此rebase后重新push时往往需要带上--force选项，即强制覆盖远端分支，如果使用不慎的话有可能会带来灾难性的后果。因此也引入了所谓rebase的黄金法则：

绝对不要在公共分支上使用rebase。

比如，如果把master分支rebase到feature分支上，rebase会将所有master分支的commit移动到你的feature分支的头部

然而，由于其他人还在original master上开发，由于你使用了rebase移动了master，git会认为你的主分支的历史与其他人的有冲突，当其他人拉取master分支将不得不去重新合并提交。

分支命名规范#

为了使分支管理更加清晰有序，提高团队协作效率，建议遵循以下分支命名规范：

功能分支 (Feature Branch): feature/功能名称，适用于开发新功能的分支
- 示例：feature/user-login, feature/payment-system
修复分支 (Fix Branch): fix/bug描述，用于修复 bug 的分支
- 示例：fix/login-error, fix/memory-leak
热修复分支 (Hotfix Branch): hotfix/紧急修复描述，用于紧急修复生产环境问题的分支
- 示例：hotfix/critical-security-fix, hotfix/payment-bug
发布分支 (Release Branch): release/版本号，用于准备发布的分支
- 示例：release/v1.2.0, release/2023.12
开发分支 (Develop Branch): develop，作为日常开发的主要分支
主分支 (Master/Main Branch): main 或 master，作为稳定版本的分支

命名规则通用要求：

使用小写字母
单词间使用连字符(-)分隔
描述简洁明确，能准确反映分支用途
避免使用无意义的数字或字母组合

分支落后及冲突处理方式#

当存在冲突时，可以通过 Merge 和 Rebase 两种方式进行解决

如无特殊需求，推荐使用 Merge 方式。

Merge 方式#

使用 Merge，本地解决冲突并推送到集成分支。

处理方式特点说明：

优点：集成分支和 master 分支的 commit 不会发生变化，且解决冲突复杂性较低。
缺点：会生成一个 Merge 节点，如果团队有线性提交记录的要求，将会破坏线性。
建议使用场景：团队没有线性提交记录的要求时。

进入对应的仓库，从当前发布单拉取对应的分支。

1
git fetch origin /归档分支变量/
2
git fetch origin /集成分支变量/
3
git checkout /集成分支变量/

将归档分支合并到集成分支，并在本地解决冲突

1
git merge /归档分支变量/

上传代码

1
git push origin /集成分支变量/

Rebase 方式#

使用 Rebase，本地解决冲突并推送到集成分支

优点：能够继续保持各分支提交记录的线性。
缺点：当前工作分支上的 commit 节点将发生变化，所有未合入到该工作分支的开发任务需要再次进行分支同步。Rebase 过程中解决冲突次数会大于 Merge 方式。
建议使用场景：团队有强烈的线性提交记录要求，且当前工作分支提交合码的次数较少。

进入对应的仓库，从当前发布单拉取对应的分支。

1
git fetch origin /归档分支变量/
2
git fetch origin /集成分支变量/
3
git checkout /集成分支变量/

将归档分支同步到集成分支，并在本地解决冲突。

1
git rebase /归档分支变量/

将本地已解决冲突的集成分支强制推送到远端。

1
git push origin /集成分支变量/ -f

根据团队规范，自行决定是否恢复保护策略。

`pnpm-lock.yaml` 冲突#

在多人协同开发过程中，rebase 分支可能会带来 pnpm-lock.yaml 文件的冲突。

处理方式如下：

通常情况下只需要再执行一次 pnpm i，让 pnpm 自动修复 lock 文件即可。
如果无法解决，很可能是此时你的 lock 文件已经损坏，可以拉取主分支完好的 lock 文件覆盖后，再执行一次 pnpm i。

三、Commit 规范自动化#

为了确保团队成员遵守统一的 commit 规范，可以借助 commitlint 和 husky 工具来自动化检查 commit 信息

1. Husky 介绍#

Husky 是一个 Git Hook 工具，它可以让你在 Git 的各个生命周期（如 commit、push、merge 等）中执行自定义脚本。通过 Husky，我们可以在开发者执行 git commit 时自动检查 commit 信息是否符合规范。

2. Commitlint 介绍#

Commitlint 是一个专门用来检查 commit 信息是否符合约定规范的工具。它通过配置文件定义规则，验证提交信息的格式。

3. 安装与配置#

3.1 安装依赖#

1
# 安装 husky、@commitlint/cli 和 @commitlint/config-conventional
2
npm install --save-dev husky @commitlint/cli @commitlint/config-conventional
3
# 或者使用 yarn
4
yarn add --dev husky @commitlint/cli @commitlint/config-conventional

3.2 配置 Commitlint#

创建 commitlint.config.js 文件：

1
module.exports = {
2
    extends: ["@commitlint/config-conventional"],
3
    rules: {
4
        "type-enum": [
5
            2,
6
            "always",
7
            [
8
                "feat", // 新功能
9
                "fix", // 修复bug
10
                "docs", // 文档
11
                "style", // 代码格式调整
12
                "refactor", // 代码重构
13
                "perf", // 性能优化
14
                "test", // 测试
15
                "build", // 构建相关
16
                "ci", // CI配置
17
                "chore", // 其他修改
18
                "revert", // 回退
19
            ],
20
        ],
21
        "type-case": [0], // 设置为0则禁用此规则
22
        "type-empty": [0], // 设置为0则禁用此规则
23
        "scope-empty": [0],
24
        "subject-case": [0], // 设置为0则禁用此规则
25
        "subject-empty": [0], // 设置为0则禁用此规则
26
        "header-max-length": [2, "always", 72], // header最大长度为72
27
    },
28
};

3.3 配置 Husky#

在 package.json 中添加 husky 配置：

1
{
2
    "husky": {
3
        "hooks": {
4
            "commit-msg": "commitlint -E HUSKY_GIT_PARAMS",
5
            "pre-commit": "npm run lint && npm run test"
6
        }
7
    }
8
}

或者通过命令行设置：

1
# 添加 commit-msg hook
2
npx husky add .husky/commit-msg 'npx --no-install commitlint --edit "$1"'
3
# 添加 pre-commit hook
4
npx husky add .husky/pre-commit 'npm run lint && npm run test'

配置完成后，当开发者执行 git commit 时，如果提交信息不符合规范，commit 会被拒绝，并显示错误信息，信息符合规范则提交成功

四、MR 准入检查#

为了保证代码质量和工程规范的有效执行，所有 MR都合入 master 分支前，须通过自动化检查

这个什么的到时候直接发code review吧自动化有时间可以整

音乐

音乐

一、合作规范#

1.1 Commit 结构#

1.2 Commit 示例#

二、分支管理#

1.2 分支命名模板#

禁止 / 不推荐的命名方式#

`git rebase`和`git merge`#

分支命名规范#

分支落后及冲突处理方式#

Merge 方式#

Rebase 方式#

`pnpm-lock.yaml` 冲突#

三、Commit 规范自动化#

1. Husky 介绍#

2. Commitlint 介绍#

3. 安装与配置#

3.1 安装依赖#

3.2 配置 Commitlint#

3.3 配置 Husky#

四、MR 准入检查#

分享到社交平台

评论

音乐

目录

音乐

音乐

2026-03-28-团队项目协作规范随记

一、合作规范#

1.1 Commit 结构#

1.2 Commit 示例#

二、分支管理#

1.2 分支命名模板#

禁止 / 不推荐的命名方式#

git rebase和git merge#

分支命名规范#

分支落后及冲突处理方式#

Merge 方式#

Rebase 方式#

pnpm-lock.yaml 冲突#

三、Commit 规范自动化#

1. Husky 介绍#

2. Commitlint 介绍#

3. 安装与配置#

3.1 安装依赖#

3.2 配置 Commitlint#

3.3 配置 Husky#

四、MR 准入检查#

分享到社交平台

评论

音乐

目录

`git rebase`和`git merge`#

`pnpm-lock.yaml` 冲突#