源码管理：Git分支策略、仓库结构与版本号规范

说到源码管理，我见过太多团队在这上面栽跟头了。分支策略选错了，合并冲突能让你怀疑人生。仓库结构设计不好，找文件比找钥匙还难。版本号不规范，发布时连自己都搞不清哪个包是最新的。

今天咱们就把这三件事掰扯清楚。说白了，源码管理就是给代码立规矩。规矩立好了，后面CI/CD流水线才能跑得顺。

一、Git分支策略：选对路子，少走弯路

分支策略这事儿，没有银弹。我这些年用过GitFlow，也用过Trunk-Based，各有各的适用场景。你想想看，一个几十人的团队和一个几百人的团队，玩法能一样吗？

1. GitFlow：传统项目的稳妥之选

GitFlow是我最早接触的分支模型。它把分支分成了几类：

• master：永远保持可发布状态
• develop：日常开发的主线
• feature/*：新功能开发分支
• release/*：发布准备分支
• hotfix/*：紧急修复分支

我在项目中遇到过一个问题：团队用了GitFlow，但每次合并release分支到master时，冲突多得让人崩溃。后来我加了一条规矩——release分支上只允许修bug，不允许加新功能。嗯，这才消停了。

# 创建feature分支
git checkout -b feature/login-page develop

# 开发完成后合并回develop
git checkout develop
git merge --no-ff feature/login-page

# 准备发布
git checkout -b release/1.2.0 develop
# 在release分支上修bug
git commit -m "fix: 修复登录超时问题"

# 发布完成，合并到master和develop
git checkout master
git merge --no-ff release/1.2.0
git tag -a v1.2.0 -m "Release version 1.2.0"

git checkout develop
git merge --no-ff release/1.2.0

2. Trunk-Based：持续集成的利器

Trunk-Based，说白了就是所有人在一条主干上开发。分支的生命周期很短，通常不超过一天。

我曾经在一个SaaS团队推行Trunk-Based，刚开始大家都不适应。有人问：「万一代码没测好就合并了怎么办？」我的回答是：「那就靠自动化测试兜底啊。」

Trunk-Based的关键规则：

• 所有开发都在主干（trunk/main）上进行
• 分支只用于短期开发（几小时到一天）
• 频繁合并，每天至少合并一次
• 合并前必须通过自动化测试

二、代码仓库结构设计：别让文件乱飞

仓库结构这事儿，看着简单，但设计不好真的很要命。我接手过一个SDK项目，源码、文档、测试、示例代码全混在一起，找个配置文件得翻半天。

下面是我个人比较推荐的结构：

sdk-project/
├── src/                    # 源码目录
│   ├── core/              # 核心逻辑
│   ├── utils/             # 工具函数
│   └── index.ts           # 入口文件
├── tests/                 # 测试代码
│   ├── unit/              # 单元测试
│   └── integration/       # 集成测试
├── docs/                  # 文档
│   ├── api/               # API文档
│   └── guides/            # 使用指南
├── examples/              # 示例代码
│   ├── basic/             # 基础示例
│   └── advanced/          # 高级示例
├── scripts/               # 构建脚本
│   ├── build.sh           # 构建脚本
│   └── release.sh         # 发布脚本
├── .github/               # GitHub配置
│   └── workflows/         # CI/CD流水线
├── package.json           # 依赖管理
├── tsconfig.json          # TypeScript配置
└── README.md              # 项目说明

这里有几个要点：

• 源码和测试分开：别把测试文件混在src里，不然打包时还得费劲排除
• 文档单独放：我习惯把文档放在docs目录，这样方便生成文档站点
• 示例代码独立：示例代码不是SDK的一部分，别放在src里
• 脚本统一管理：所有构建、发布脚本放scripts目录，别散落在各处

三、源码标签与版本号规范：给代码打上标记

版本号这事儿，看着简单，但坑不少。我见过有人用v1、v2这种版本号，结果发到v10的时候，排序都排不对了。

1. 语义化版本号（SemVer）

语义化版本号是目前最通用的规范。格式是：主版本号.次版本号.修订号

我建议在版本号后面加上预发布标识：

• 1.0.0-alpha.1：内部测试版
• 1.0.0-beta.2：公开测试版
• 1.0.0-rc.3：候选发布版

2. Git标签规范

Git标签要和版本号对应起来。我习惯用v前缀：

# 创建标签
git tag -a v1.2.0 -m "Release version 1.2.0"

# 推送标签
git push origin v1.2.0

# 查看所有标签
git tag -l

标签命名规则：

• 正式版：v1.2.0
• 预发布版：v1.2.0-beta.1
• 热修复版：v1.2.1

四、知识体系总览

下面这张图是我梳理的源码管理知识体系，你可以对照着看看自己团队在哪个环节还有改进空间：

你看，这三个东西其实是环环相扣的。分支策略决定了你怎么开发，仓库结构决定了代码怎么组织，版本规范决定了发布怎么管理。任何一个环节出了问题，整个SDK发布流程都会受影响。