团队开发规范智能生成器

团队协作规范总览

本规范适用于中型移动应用开发团队（6–15人），采用DevOps流程、monorepo（双平台共用模块）、并行CI（单元与UI测试）、灰度发布与A/B实验、紧急修复分支与签名证书管控。目标是最小化冲突与返工、提高交付质量与速度、确保提交可追踪（关联工单与构建号）。

• 仓库结构（monorepo建议）
  • apps/
    • android/
    • ios/
  • packages/
    • shared/（跨平台共享业务与逻辑模块）
    • android-lib/
    • ios-lib/
  • tools/
    • ci/（流水线脚本与配置）
    • qa/（测试工具与脚本）
  • docs/
  • configs/（环境配置、特性开关、实验配置）
• 工作节奏
  • 主干开发（main）持续集成，短分支迭代（1–3天）。
  • 发布分支按版本节奏创建，用于稳定与提交商店。
  • 热修复分支用于线上紧急问题，快速审查与发布。
• 角色与职责
  • 开发：按模块所有权负责实现与自测。
  • 代码所有者（模块负责人/跨平台）：对模块变更进行审核与把关。
  • 测试/QA：测试用例维护、灰度与实验验证。
  • DevOps：CI/CD、签名证书管控、分支保护与合规。
• 可追踪性要求
  • 每次提交必须关联工单ID；构建号由CI在合并或打标签阶段自动写入追踪信息。
  • 构建产物生成“构建清单（Build Manifest）”，记录提交SHA、工单ID、构建号、发布渠道、灰度比例、实验配置摘要。
• 灰度与A/B策略
  • 功能使用特性开关与远程配置实现；实验参数在configs/中版本化。
  • 不为实验建长期分支，所有实验走开关与配置，避免代码分叉。

分支管理策略

采用“主干为中心 + 轻量发布分支 + 热修复分支”的策略，兼顾移动应用发布与紧急修复场景。

主要分支说明

• main（受保护分支）
  • 始终保持可构建、可发布到内部测试渠道。
  • 所有功能通过短生命周期的feature分支并通过合并请求进入主干。
• release/
  • 例如：release/1.8.0，用于版本冻结、打包与商店提交。
  • 仅接受稳定性修复与发布相关变更，不接受新特性。
• hotfix/-
  • 例如：hotfix/1.8.0-ABC-123，基于当前生产版本的tag或对应release分支。
  • 面向紧急问题，最小化改动范围，快速验证与发布。
• 支持的标签
  • v..（版本标签，例：v1.8.0）
  • build//+（构建标签，CI自动生成，例：build/android/v1.8.0+20251113045）

功能开发分支规则

• 命名规范：feature/-
  • 例：feature/ABC-456-login-refactor
• 来源与生命周期
  • 从main创建；保持短周期（1–3天），避免长期漂移。
  • 每日与main同步一遍（rebase或merge），减少冲突风险。
• 变更范围
  • 尽量单一功能或模块；跨模块变更需拆分为多个PR，或明确说明影响范围并邀请对应模块所有者参与审核。
• 提交要求
  • 遵循提交信息格式标准（见后文）；本地通过预提交钩子执行格式化、静态检查与快速单元测试。

发布与热修复流程

• 发布流程
  1. 在准备发版时，从main创建 release/。
  2. 冻结新特性，仅合入修复与发布所需配置；开启完整CI（并行单元+UI测试、静态分析、打包验签）。
  3. 使用灰度发布：先内测渠道，再逐步扩大用户比例；A/B实验通过特性开关与远程配置实现。
  4. 通过CI对release分支进行签名打包；生成版本标签 v 与构建标签 build//+。
  5. 商店提交与发布完成后，将release分支的修复变更回合到main（保持主干状态最新）。
• 热修复流程
  1. 基于生产版本标签或release分支创建 hotfix/-。
  2. 限定改动范围，优先覆盖紧急问题；编写回归测试或最少受影响模块的针对性测试。
  3. 最少1名模块所有者 + 1名跨平台审查者快速审核。
  4. CI执行关键路径测试与打包验签；灰度快速验证（小比例），再扩大。
  5. 合并到对应release分支并打热修复包；同时将修复回合到main。

代码提交规范

提交信息格式标准

采用“约定式提交（Conventional Commits）+ 工单与构建追踪”的统一格式。构建号由CI在合并或打标签阶段自动补充到追踪信息（无需开发本地填写）。

• 提交头（Header）
  • ()<optional!>:
  • type：feat, fix, refactor, perf, docs, test, build, ci, chore
  • scope：模块或平台（如 android, ios, shared, auth）
  • “!””表示破坏性变更（需要在正文解释）
  • 例：feat(shared): add token refresh for dual-platform
• 提交正文（Body）
  • 说明动机、实现要点、影响范围与回滚策略。
• 提交脚注（Footer）
  • Ticket: <工单ID>（必填，例：Ticket: ABC-456）
  • Build: <构建号>（由CI自动添加或通过构建标签关联，无需本地填写）
  • BREAKING CHANGE: <说明>（如有破坏性变更）
• Pull Request 标题与描述
  • 标题与提交头一致；描述中包含工单链接、测试说明、灰度/实验影响说明。

提交频率和规模指南

• 小步提交：建议每次提交不超过400行改动（含新增/删除），确保评审效率。
• 原子性：每次提交完成一项可测试的最小变更；避免将多个独立功能混在同一提交。
• 频率：功能开发期间每天至少一次提交；避免积压到大合并。

代码审查机制

审查流程说明

1. 开发完成后发起合并请求（MR/PR），选择目标分支（main/release/hotfix）。
2. 指定审核人
   • 至少1名模块所有者（代码所有权映射在仓库中维护）。
   • 跨平台影响时，增加另一平台审核人。
3. CI自动触发并行检查
   • 路径感知构建：仅构建受影响的模块；共享模块改动触发双平台单元测试。
   • UI测试：对UI相关变更或影响范围标记的PR，执行对应平台的UI测试套件（并行）。
   • 静态分析与安全扫描、格式化检查。
4. 审核人根据审查标准进行评审；提出修改建议；开发者响应并更新。
5. 所有检查与审核通过后，按合并策略（见下文）合并。

审查标准和质量要求

• 功能正确性与边界条件处理合理。
• 代码风格一致、模块边界清晰；共享模块不引入平台耦合。
• 单元测试覆盖新增逻辑的关键路径（建议新增或变更代码至少达到70%的语句覆盖）。
• UI测试用例对关键交互路径提供验证（对于UI相关PR必须通过）。
• 性能影响评估（如网络、渲染、启动时长）。
• 安全与隐私合规（凭据不硬编码；敏感数据不落盘；日志不泄露隐私）。
• 配置与特性开关默认安全关闭；实验参数可回滚。
• 回滚策略明确；必要时提供迁移脚本或数据兼容方案。

合并请求处理

合并条件和验证

• 所有必需检查通过：
  • 编译/构建成功（双平台受影响模块）。
  • 并行单元测试与必要的UI测试通过。
  • 静态分析与安全检查无阻断问题。
  • 提交信息符合规范（含工单ID）。
• 审核通过：
  • 至少1名代码所有者批准；跨平台变更需额外批准。
• 分支要求：
  • 分支已与目标分支同步最新（无阻断冲突）。
• 版本与构建追踪：
  • CI在合并时生成或更新构建清单（commit SHA、工单ID、构建号、环境与灰度配置）。
  • 对release/hotfix合并，生成版本标签与构建标签。
• 合并策略：
  • feature分支：采用“压缩合并（Squash Merge）”，将多次开发提交聚合为一个清晰的变更提交，保留规范化信息。
  • release/hotfix分支：采用“合并提交（Merge Commit）或快进（Fast-forward）”，保留发布线变更轨迹以便审计。

冲突解决方案

• 预防
  • 每日从main同步feature分支；大改动前创建技术设计简要并与相关模块所有者对齐。
  • 路径与模块所有权映射：跨模块改动提前通知。
  • 使用格式化工具与静态分析预提交钩子统一风格。
• 处理
  • 发生冲突时，优先在本地rebase并运行受影响模块的测试；必要时进行结对解决。
  • 大规模冲突：分解为多步PR，先合入共享模块抽象层，再合入平台适配。
  • 若因同时变更同一文件导致PR互相阻塞，使用“合并队列（顺序合并）”策略：队列化合并，按顺序更新与验证，避免叠加冲突。
• 记录
  • 在PR中记录冲突原因与解决方式；更新相关模块文档，避免重复问题。

实施与优化建议

• 初始落地步骤
  1. 建立分支保护规则：main/release/hotfix必须通过必需检查；禁止直接推送。
  2. 配置提交钩子与服务端钩子：校验提交信息包含工单ID；阻断不合规提交。
  3. CI流水线
     • 路径感知并行执行：变更检测触发对应平台构建、单元与UI测试。
     • 构建清单生成与归档；为合并提交或标签写入构建号（可通过机器人账号写入合并提交脚注或创建构建标签）。
     • 构建产物签名：仅CI可访问签名证书，开发者本地不持有生产证书。
  4. 灰度与A/B配置管理：在configs/中维护开关与实验参数，定义默认关闭策略与回滚预案。
  5. 代码所有权映射：在仓库维护模块路径到负责人清单；CI在PR中自动请求相应审核人。
• 签名证书管控
  • 证书与密钥存放于安全密钥管理系统，开启最小权限访问与审计。
  • 所有发布与热修复包由CI进行签名；紧急“破窗”流程需双人批准、审计记录与时限控制。
  • 定期轮换证书与密钥；本地构建使用开发/测试签名。
• 质量与效率度量
  • 持续监控DORA指标（变更交付频率、交付前置时间、平均修复时间、变更失败率）。
  • 每两周回顾一次流程瓶颈与冲突案例，更新规范与自动化规则。
• 培训与文档
  • 编写开发手册：分支策略、提交规范、审查清单、CI失败排查。
  • 新人培训包含monorepo结构、模块所有权、特性开关与实验实践。
• 持续改进
  • 引入“合并队列”与“预提交自动修复”减少阻塞。
  • 逐步扩展路径感知测试矩阵，提高并行度但控制稳定性。
  • 对高频冲突文件尝试抽象分层或拆分模块，减少耦合。

以上规范基于行业最佳实践，兼顾移动应用发布特点与团队规模，确保在monorepo与双平台共享模块的场景下，实现高效、可追踪、可审计的协同开发与发布。

团队协作规范总览

• 团队与项目特征

  • 团队规模：16–50 人，服务与平台团队并行，存在跨团队协作。
  • 项目类型：企业级系统，微服务架构（多仓库/多服务），长期维护与合规要求高。
  • 开发流程：混合模式（新功能按迭代，运维/修复按看板）。
  • 发布节奏：按月 release train（统一节奏协调各服务版本）。
  • 特殊需求：LTS 分支维护、变更需 CAB 审批、代码所有权矩阵、跨团队接口契约测试、合规审计留痕与事故复盘流程标准化。

• 目标

  1. 提供可扩展的分支策略，适应微服务与月度发布列车。
  2. 标准化提交与审查流程，降低冲突与回归风险。
  3. 在 CI/CD 中建立质量闸门与合规留痕，满足审计与 CAB 管理。
  4. 明确代码所有权与跨团队契约协作，提升协作效率与责任清晰度。

• 角色与职责（建议）

  • Release Manager：组织发布列车，管理 release/LTS 分支与里程碑。
  • Service Owner（服务负责人）：所属服务的技术与质量负责人，对契约与变更风险负责。
  • Code Owners（代码所有者）：基于所有权矩阵对特定路径文件审查与最终批准。
  • CAB 代表：审查高风险变更，裁决是否进入发布列车或紧急发布。
  • QA/SE（质量/安全）：把关测试、覆盖率、安全扫描与合规留痕。

分支管理策略

采用“Trunk + 短生命周期功能分支 + 月度 Release 分支 + LTS/Hotfix”混合策略，兼顾大型团队协作与长期维护。

主要分支说明

• main（主干）

  • 始终保持可集成与可部署到预生产环境的状态（绿色管线）。
  • 新功能通过短生命周期 feature 分支合入，默认启用功能开关以减少发布耦合。
  • 不直接打生产标签；生产标签打在 release/LTS 分支上。

• release/（月度发布列车分支）

  • 每月按节奏从 main 切出，如 release/2025.11。
  • 分支冻结窗口：分支切出后仅接受缺陷修复与稳定性优化，不再合入新特性。
  • 形成 RC（候选版）与最终 GA（正式版）标签，服务在该分支上打版本标签。

• lts/<major.minor>（长期维护分支）

  • 从稳定的 release 分支上切出，如 lts/2025.06。
  • 仅接受安全修复、严重缺陷修复与合规调整，保证 API 向后兼容。
  • 维护期与支持策略由 CAB 决定（如 12–24 个月），建立清晰的支持矩阵。

• hotfix//

  • 针对生产或 LTS 的紧急修复，从对应 release 或 lts 分支切出。
  • 合并完成后需要双向同步：合入目标分支并回灌至 main，以防止回归。

• support//

  • 可选：对于需要长期维护但不进入 LTS 的核心服务，建立支持分支以隔离大版本演进。

• 分支命名规则

  • feature//-
  • bugfix//-
  • hotfix//
  • release/<YYYY.MM>、lts/<YYYY.MM>

功能开发分支规则

• 生命周期与更新

  • feature 分支最长存活不超过 5 个工作日；每日与 main 同步（rebase/merge）以减少冲突。
  • 大型变更拆分为多个小 PR；每个 PR 有独立业务价值且可回滚。

• 开发要求

  • 强制启用功能开关/灰度策略以避免与发布列车强耦合。
  • 跨服务接口变更必须更新契约与版本，并在契约测试仓库通过兼容性检查。
  • 数据库变更必须提供迁移脚本与回滚方案，遵循“向后兼容、双写/影子表”策略。

• 合规与审查

  • 标注 issue-key、变更类型与风险级别；高风险变更需在合并前获得 CAB 批准。
  • 关联所有权矩阵，确保相关 Code Owners 自动加入审查。

发布与热修复流程

• 月度 release train（示例时间线）

  • T-14 天：Release Manager 评估就绪度，标记需入列的服务版本与依赖清单。
  • T-7 天：从 main 切出 release/<YYYY.MM>；分支进入冻结，仅允许修复与优化。
  • T-3 天：发布候选版（tag：v-<YYYY.MM>-rcN）；完成端到端与契约回归。
  • T：发布 GA（tag：v-<YYYY.MM>）；产出统一的发布清单与审计留痕。
  • T+1：决定是否将本次 release 列为 LTS（由 CAB 按业务与风险裁定）。

• 热修复（生产/LTS）

  • 触发条件：P1/P2 事故、安全漏洞或合规问题。
  • 流程：hotfix 分支 -> 快速审查与验证 -> 合并至目标 release/LTS -> 打补丁标签（v-<YYYY.MM>.patchN）-> 回灌至 main。
  • 紧急变更的 CAB：事后审批（Emergency Change），在事后复盘内补齐留痕。

代码提交规范

提交信息格式标准

• 建议采用“类型(scope): 摘要”的结构，并包含审计所需的元信息。示例：

  • 标题（<= 72 字符）：
    • feat(order-service): 支持部分发货并引入订单项状态机
  • 正文：
    • 变更说明、设计要点、风险与回滚策略、影响范围（契约/数据库/配置）
    • 测试说明（新增/修改的单元/集成/契约测试）
  • 页脚（审计元信息）：
    • Issue: PROJ-1234
    • Change-Type: Normal|Standard|Emergency
    • Risk-Level: Low|Medium|High
    • CAB-Approval: CAB-2025-11-045（如适用）
    • Breaking-Change: true|false（含兼容策略与迁移说明）
    • Signed-off-by: 姓名
    • Co-authored-by: 姓名 （如多人协作）

• 类型枚举（示例）

  • feat、fix、perf、refactor、docs、test、build、ci、chore、revert
  • 带 breaking 的需在正文中明确兼容策略与迁移指南。

提交频率和规模指南

• 小步提交、语义完整：建议单次提交更改不超过 ~300 行（含测试），确保可审查与可回滚。
• 每日至少一次同步提交，避免长期堆积。
• 不提交二进制产物与临时文件；配置与密钥使用模板与环境注入。
• 一次提交聚焦一项工作：避免混合功能、修复与格式化。

代码审查机制

审查流程说明

• 提交 PR/MR 至目标分支（feature -> main；bugfix -> release；hotfix -> release/LTS）。
• 自动请求 Code Owners（基于所有权矩阵按路径匹配）与 Service Owner。
• 质量闸门（CI）自动运行：
  • 语法与风格检查、静态分析、依赖安全扫描、SBOM 生成
  • 单元测试、契约测试（消费者/提供者）、集成测试、端到端关键路径测试
  • 覆盖率阈值（如：语句 80%/核心模块 90%），性能基线回归检查（核心服务）
• 审查人要求：
  • 常规变更：至少 2 名审查人，其中 1 名为 Code Owner。
  • 接口/数据库/安全相关变更：额外增加对应领域审查人。
  • 高风险变更：需 CAB 审批通过并在 PR 中附证据。

审查标准和质量要求

• 设计一致性：遵循架构准则、DDD/分层模式、公共库与编码规范。
• 向后兼容：接口变更需提供兼容期与弃用计划，契约测试必须通过。
• 可测试性：新增功能必须包含相应测试；缺陷修复需加回归测试。
• 性能与资源：关键路径性能不可回退；增加外部依赖需评估可靠性与成本。
• 文档与可运维：更新 README、变更日志、运行手册与迁移指南。
• 安全与合规：不引入高风险依赖；密钥不入库；审计元信息完整。

合并请求处理

合并条件和验证

• 必须满足：

  • CI 全绿；契约/集成/安全扫描通过；无未解决审查意见。
  • 与目标分支无冲突；已完成 rebase/sync。
  • 满足审批数量与类型；高风险变更附 CAB-Approval。
  • 提交信息完整且包含审计页脚；关联 issue 与变更记录。
  • 对应环境验证完成（预生产/沙箱），必要时附验证报告。

• 合并策略

  • feature -> main：推荐 squash merge（保留清晰的功能变更历史），禁止直接推送。
  • bugfix/hotfix -> release/LTS：普通合并（保留详细修复轨迹），随后回灌 main。
  • release 打标签：各服务在 release 分支打注释标签（含版本号、构建号、提交哈希），统一汇总至发布清单。
  • main 不直接打生产标签，避免历史污染与回溯困难。

冲突解决方案

• 预防机制
  • 每日与 main 同步；尽早拆分 PR；跨服务接口变更先更新契约并沟通。
  • 在“冻结窗口”前完成大特性合入；采用功能开关减少耦合。
• 解决步骤
  • 先本地重放变更（rebase），解决三方冲突；运行全套测试。
  • 检查契约与集成用例是否覆盖冲突区域；必要时补充测试。
  • 复杂冲突由相关 Code Owners 共同参与；记录解决说明至 PR。
  • 冲突造成行为改变时，更新迁移/回滚指南与风险评估。

实施与优化建议

• 落地步骤

  1. 建立代码所有权矩阵：在每个仓库根目录维护 owners.yaml（路径模式 -> 负责人），CI 解析后自动请求审查。
  2. 统一分支与标签约定：在组织级文档与仓库模板中固化命名与保护规则（保护 main/release/LTS 分支；限制直接推送）。
  3. 配置 CI/CD 质量闸门：
     • 语法/格式、静态分析、依赖安全扫描、SBOM 出具与归档。
     • 单元/集成/契约测试流水线；端到端关键路径夜间构建。
     • 构建产物的来源与可追溯信息（提交哈希、构建时间、依赖摘要）。
  4. 契约测试落地：
     • 建立独立“契约仓库”与版本化策略（语义化版本：MAJOR.MINOR.PATCH）。
     • 变更流程：先更新契约 -> 消费者与提供者用例通过 -> 才可合并代码。
     • 在 PR 中强制检查契约兼容性与弃用窗口公告。
  5. CAB 集成与变更分类：
     • 变更类型：Standard（低风险、模板化）、Normal（常规）、Emergency（紧急）。
     • PR 模板包含风险等级、影响范围、回滚计划、验证证明；CI 自动检查是否填写完整。
     • 将 CAB 审批编号写入提交页脚与发布清单；紧急变更事后复盘。
  6. 审计留痕与发布清单：
     • 为每次 release train 生成“发布清单”与“审计包”：
       • 包含：服务版本标签、提交哈希、构建号、SBOM、测试报告摘要、CAB 决议、已知问题。
       • 归档结构：audit///，保留期不低于 24 个月。
  7. 事故复盘标准化：
     • 触发条件：P1/P2 事故或重大回归；采用统一模板：时间线、根因（5 Whys/鱼骨）、影响评估、修复与防再发行动、关联 PR 与提交、学习点。
     • 复盘文档与行动项跟踪入库（postmortems/），并在后续发布列车中验证效果。
  8. 培训与试运行：
     • 以 1–2 个核心服务试点，运行 2 个 release 周期；收集瓶颈并微调阈值。
     • 发布“开发者手册”：分支策略、提交规范、审查清单、契约指南、数据库迁移准则。

• 指标与持续改进（建议跟踪）

  • 变更前置时间、部署频率、缺陷逃逸率、回滚率、审查周期、测试覆盖率与管线稳定度。
  • 每季度审查所有权矩阵与依赖健康；优化冻结窗口与契约弃用周期。
  • 对高风险路径设“强审查”与“额外测试配额”，逐步降低事故率。

• 工程约束与原则

  • 简化优先：分支与流程在满足 LTS 与合规的前提下保持最小复杂度。
  • 自动化优先：质量闸门与审计留痕由 CI 自动生成与归档，减少人工错误。
  • 向后兼容与可回滚：所有跨团队接口与数据变更必须具备兼容策略与快速回滚手段。
  • 可观测与可追溯：每个发布与修复均可从运行环境追溯到提交与审计包。

以上规范适用于大型微服务团队的月度发布列车与长期维护场景，兼顾 CAB 审批、合规审计与跨团队协作的落地可行性。实施过程中如遇到团队特定限制（工具链、监管要求），可在不改变核心原则的前提下微调阈值与文档模板。