版本控制最佳实践指南

项目特征分析

• 项目规模评估
  • 小型团队、双周迭代、功能面较广（交易、库存、风控、活动、推送），对版本控制的核心诉求是：高频小批量交付、快速热修复与回滚、跨多环境稳定发布和可追踪性。
  • 前后端分别可独立发布，且服务端涉及多依赖（支付、物流、风控、埋点），需要强约束的发布链路与变更可见性。
• 团队协作模式分析
  • 敏捷开发+双周节奏：适合主干开发（Trunk-Based Development）+ 轻量发布分支的模型，避免复杂流程带来的沟通和等待成本。
  • 强调代码评审与自动化测试：应在合并请求上强制 CI 通过和评审通过；把“是否受灰度/开关控制”作为评审检查项。
• 技术栈适配建议
  • 前端 React Native 与后端 NestJS 均为 TypeScript，可通过工作区/包管理工作空间或接口契约生成（OpenAPI/TS 类型）减少接口偏差。
  • 使用 Git 属性规范换行和大文件策略（如将大体积素材用大文件机制管理，避免仓库膨胀）。
  • 严禁提交密钥/证书/敏感配置。环境配置通过密钥管理在 CI/CD 中注入，代码库只保留模板和非敏感默认值。
  • 测试体系：单元（Jest）、关键路径集成测试、端到端冒烟测试对发布分支和主干均生效。

分支管理策略

• 推荐的分支模型
  • 主干开发（Trunk-Based Development, TBD）+ 短生命周期特性分支 + 轻量发布分支（每个双周迭代一个）。
  • 说明：
    • 日常基于 main 开发，所有变更通过短小 PR 合并到 main。
    • 使用特性开关（Feature Flags）隐藏未完成功能，支持灰度与 A/B，不依赖长期分支。
    • 每个迭代进入提测/预发时从 main 切出 release/X.Y.0 分支用于收敛和验收；仅允许修复类合并，避免新增需求。
    • 线上紧急修复使用 hotfix 分支从对应生产 tag 切出。
• 分支命名规范
  • feature/--
  • fix/--
  • hotfix/-
  • release/（例如 release/1.8.0）
  • chore/-（构建、脚本、文档等）
  • scope 建议：app(ReactNative)、api(NestJS)、checkout、payment、inventory、promotion、abtest、tracking、deploy 等。
• 分支生命周期管理
  • 特性/修复分支：创建 → 持续基于 main 变基（rebase）保持最新 → 小 PR → 通过 CI+评审 → squash 合并回 main → 删除分支。
  • 发布分支：从 main 切出 → 仅接受修复（fix/chore/test）PR → 通过预发 → 打 tag 发布 → 合并回 main（避免分叉）。
  • 热修复分支：从生产 tag 切出 → 修复并在预发验证 → 打补丁版本 tag → 回合并 main 与在研 release 分支（避免丢修复）。

代码提交规范

• 提交信息格式标准（Conventional Commits，附加运营追踪）
  • 格式：type(scope)!: subject
    • body（可选，说明动机、影响范围）
    • BREAKING-CHANGE（可选，说明不兼容变更与迁移步骤）
    • Trailers（用于追踪与关联）
      • Issue: <跟踪号>
      • Campaign: <活动ID/策略ID>
      • Flag: <特性开关键>
      • Affected: frontend|backend|infra|db
  • 常用 type：feat, fix, perf, refactor, test, docs, build, ci, chore, revert
  • 示例：
    • feat(checkout): support split-order by warehouse
      • Explains: split by stock location; default off by flag
      • Flag: checkout.splitOrder
      • Campaign: CAMP-2025-12
      • Issue: EC-1234
• 提交频率指导
  • 小步提交、单一主题、可回滚。单次变更尽量控制在几百行以内，超出则拆分为独立 PR。
  • 未达成编译/测试通过的实验性工作以草稿 PR 或特性开关隔离，避免长时间悬挂分支。
• 提交内容质量要求
  • 必须通过静态检查（TypeScript、Lint、格式化）、单元测试；涉及接口/协议必须更新契约与测试。
  • 涉及埋点或风控的改动，提交说明中标记追踪字段变化，附更新文档位置。
  • 禁止提交构建产物、环境密钥、临时数据；大文件走大文件机制；二进制资源需说明来源与用途。

团队协作流程

• 代码审查机制
  • 每个 PR 至少 1 名评审，关键模块（支付、订单、风控、埋点）至少 2 名评审。
  • 评审清单：
    • 是否被特性开关/灰度保护（默认 off）
    • 回滚与降级策略是否明确
    • 测试是否覆盖关键路径（包含负向用例）
    • 性能/并发与幂等等风险点说明
    • 日志与埋点是否完整且不包含敏感信息
  • PR 体量：建议 ≤ 400 行差异，超过需拆分主题。
• 合并请求流程
  • PR 模板固定结构：动机/方案/风险/回滚/开关/测试/影响面。
  • CI 必须绿灯（lint、typecheck、单元测试、关键路径集成测试、镜像构建或打包校验、敏感信息扫描）。
  • 合并策略：默认 squash merge，保持线性历史；PR 标题即合并提交标题，内容包含问题号/活动/开关。
  • 分支保护：main 与 release 分支强制评审+CI、禁止直接推送、禁止非快进历史。
• 冲突预防和解决方案
  • 预防：小 PR、频繁 rebase、避免大规模横切改动；前后端接口变更先落契约并逐步发布（向后兼容）。
  • 解决：
    • rebase 优先，确保提交顺序清晰；
    • 若冲突集中在构建锁文件或自动生成文件，使用“重建再提交”的策略而非手动拼接；
    • 发生 API 破坏时，采用“扩展-迁移-收缩”（expand/migrate/contract）三阶段，给下游留可兼容窗口。

版本发布管理

• 版本号规范
  • 全项目采用语义化版本（SemVer）：MAJOR.MINOR.PATCH
    • 双周迭代：常规以 MINOR+1（例如 1.7.0 → 1.8.0）
    • 紧急修复：PATCH+1（例如 1.8.1）
    • 重大不兼容：MAJOR+1（同时提供迁移指引）
  • 预发布：使用 -rc.X 标记（如 1.8.0-rc.1）用于预发与灰度。
  • 移动端额外要求：
    • versionName 对应 SemVer；versionCode/Build Number 递增；
    • JavaScript Bundle 支持 OTA（Over-the-Air）热更新与回滚，严格受开关与签名控制。
• 标签管理策略
  • 对每次发布进行“带注解的标签”（annotated tag），如 v1.8.0，包含：
    • 提交范围摘要（自动生成 changelog）
    • 生效的特性开关列表与默认值
    • 关联活动/策略（Campaign IDs）
    • 数据库迁移版本范围与回滚指引摘要
  • 镜像与制品标记：
    • 后端镜像：:-，推广（promote）沿用相同制品，避免“重建即不同”。
    • 移动端构建产物：标记 semver 与构建号；OTA 包额外以 gitsha 标识。
• 灰度发布与 A/B 实验
  • 灰度原则：先预发验证，再按比例放量（如 1% → 5% → 20% → 50% → 100%），每一档需要健康检查（错误率、延迟、转化、崩溃率）。
  • 服务端：
    • 使用两个维度控制：发布分批（副本/路由权重）+ 特性开关（按用户/地域/渠道过滤）。
    • A/B 实验以“开关键/实验键”受控，版本不分叉；变更记录在标签注解与发布清单中。
  • 移动端：
    • 应用商店分阶段发布与 OTA 配合；实验/活动使用开关或参数下发；确保客户端逻辑允许服务端关闭实验后恢复默认。
• 发布流程（双周节奏建议）
  • D-4：从 main 切 release/1.8.0，进入收敛；仅收 fix/chore/test。
  • D-3：预发部署 1.8.0-rc.1，跑冒烟+回归+关键链路 E2E；埋点验证与风控联调。
  • D-2：修复问题，rc.2；如无阻断问题，冻结变更。
  • D-1：生成正式 tag v1.8.0，推广到生产小流量灰度；观察指标后逐步放量至全量。
  • D：归档发布清单与变更日志，关闭 release 分支并合回 main。
• 紧急修复流程
  • 触发条件：P0 故障/安全问题/支付链路中断/重大崩溃。
  • 步骤：
    1. 从生产 tag（例如 v1.8.0）切出 hotfix/；
    2. 增补针对性的单元/集成测试，预发验证通过；
    3. 打补丁 tag v1.8.1，直接推广少量灰度，观察关键指标（错误率、退单率、崩溃率）；
    4. 放量至 100%；将修复变更合并回 main 与仍未发布的 release 分支；
    5. 更新变更日志与事后复盘。
  • 快速回滚：
    • 服务端：按部署记录回滚到上一个稳定 tag 的镜像；数据库迁移遵循“可回滚/向后兼容”策略（先加字段/影子写入，稳定后再移除旧结构）。
    • 移动端：OTA 热更新回滚到上一个稳定 bundle；如为商店构建，暂停分发并加急提审修复版。
• 可追踪性与合规
  • 变更追踪：
    • 每个 PR 和提交包含 Issue/Campaign/Flag 等 trailers；
    • 每个 tag 注解包含本次活动/实验清单与默认状态；
    • 发布产物与 gitsha 一一对应，部署系统记录“环境-版本-流量权重-开关快照”。
  • 文档与清单：
    • /docs/releases/.md：自动生成变更摘要+手动补充风险与回滚；
    • /ops/releases/.yml：活动与开关快照、迁移窗口、监控看板链接。
  • 审计与安全：
    • 分支保护、强制评审、强制 CI、受保护的 tag 创建与发布权限；
    • 提交与标签可选签名；敏感扫描纳入合并前置。

以上方案以“主干开发+特性开关”为核心，确保小团队在双周节奏下保持高效协作、可灰度/可实验、可热修复与快速回滚，并且在版本与运营活动之间实现稳定的双向追踪。