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

First Post:

Last Update:

Page View: loading...

一、合作规范

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

1.1 Commit 结构

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

1
2
3
4
5
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<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
2
3
4
5
6
feat(api): 支持在搜索结果中展示用户头像

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

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

1
2
3
4
5
6
7
8
9
10
11
refactor(auth): 重构认证模块以支持多点登录

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

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

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
2
3
4
feature/JIRA-1234-add-social-login
bugfix/LINEAR-567-fix-mobile-navbar-overflow
hotfix/urgent-fix-2026-01-rce-vulnerability
refactor/remove-deprecated-auth-endpoint

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

1
2
3
feature/add-dark-mode-toggle
bugfix/login-button-disabled-state
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
2
3
git fetch origin /归档分支变量/
git fetch origin /集成分支变量/
git checkout /集成分支变量/

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

1
git merge /归档分支变量/

上传代码

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

Rebase 方式

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

  • 优点：能够继续保持各分支提交记录的线性。
  • 缺点：当前工作分支上的 commit 节点将发生变化，所有未合入到该工作分支的开发任务需要再次进行分支同步。Rebase 过程中解决冲突次数会大于 Merge 方式。
  • 建议使用场景：团队有强烈的线性提交记录要求，且当前工作分支提交合码的次数较少。
  1. 进入对应的仓库，从当前发布单拉取对应的分支。
1
2
3
git fetch origin /归档分支变量/
git fetch origin /集成分支变量/
git checkout /集成分支变量/
  1. 将归档分支同步到集成分支，并在本地解决冲突。
1
git rebase /归档分支变量/
  1. 将本地已解决冲突的集成分支强制推送到远端。
1
git push origin /集成分支变量/ -f
  1. 根据团队规范，自行决定是否恢复保护策略。

pnpm-lock.yaml 冲突

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

处理方式如下：

  1. 通常情况下只需要再执行一次 pnpm i，让 pnpm 自动修复 lock 文件即可。
  2. 如果无法解决，很可能是此时你的 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
2
3
4
# 安装 husky、@commitlint/cli 和 @commitlint/config-conventional
npm install --save-dev husky @commitlint/cli @commitlint/config-conventional
# 或者使用 yarn
yarn add --dev husky @commitlint/cli @commitlint/config-conventional

3.2 配置 Commitlint

创建 commitlint.config.js 文件：

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
module.exports = {
    extends: ["@commitlint/config-conventional"],
    rules: {
        "type-enum": [
            2,
            "always",
            [
                "feat", // 新功能
                "fix", // 修复bug
                "docs", // 文档
                "style", // 代码格式调整
                "refactor", // 代码重构
                "perf", // 性能优化
                "test", // 测试
                "build", // 构建相关
                "ci", // CI配置
                "chore", // 其他修改
                "revert", // 回退
            ],
        ],
        "type-case": [0], // 设置为0则禁用此规则
        "type-empty": [0], // 设置为0则禁用此规则
        "scope-empty": [0],
        "subject-case": [0], // 设置为0则禁用此规则
        "subject-empty": [0], // 设置为0则禁用此规则
        "header-max-length": [2, "always", 72], // header最大长度为72
    },
};

3.3 配置 Husky

在 package.json 中添加 husky 配置：

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

或者通过命令行设置：

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

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

四、MR 准入检查

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

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

≡