Logo

菜单

易君召
发布于 2026-08-19 / 作者：易君召 / 1 阅读
0

团队共享代码最佳实践

覆盖Git 协作、代码风格、提交规范、评审、文档、依赖、安全、发布，适合多人团队、后端 / 全栈项目，可直接作为团队规范落地。

一、Git 分支协作规范

分支模型（推荐 GitFlow 简化版，中小型团队）

  1. main/master：受保护分支，永远可部署，禁止直接 push；只能 merge/pull request 合并。

  2. develop：开发集成分支，日常功能合并到此。

  3. feature/xxx：功能分支，从 develop 拉出，完成后 PR 回 develop。

  4. hotfix/xxx：线上 bug 修复，从 main 拉出，修复后同时合并 main 与 develop。

  5. release/v1.2.0：版本预发布分支，做测试、bug 修复，完成合并打 tag。

小团队可简化：main + feature/*，通过 PR 合并，不维护长期 develop。

禁止行为

  • 不在 main 直接写代码、强制推送git push -f main

  • 一个分支堆大量无关功能

  • 分支长期不合并、不同步上游代码

日常操作最佳实践

  1. 新建功能分支前，先拉取远端最新代码：git pull origin develop

  2. 功能分支经常 rebase 上游，减少大合并冲突

  3. 一个 PR 只解决一件事：一个功能 / 一个 bug 修复，拒绝巨型 PR

二、Commit 提交信息规范

采用Conventional Commits 约定式提交，方便自动生成 CHANGELOG，看懂历史。

格式：

plaintext

<type>[scope]: <描述>

[可选正文]
[关闭issue: Closes #123]

type 取值：

  • feat：新增功能

  • fix：bug 修复

  • docs：仅文档修改

  • style：格式调整，无业务逻辑改动（空格、格式化）

  • refactor：重构，既不是 bug 也不是新功能

  • perf：性能优化

  • test：增加 / 修改测试用例

  • chore：构建、依赖、脚本、CI 配置

示例：

plaintext

feat(user): 新增手机号登录接口
fix(order): 修复超时订单状态未回滚问题

禁忌：修复bug、更新代码、临时提交这种模糊 commit。

工具：commitlint + husky 强制校验提交格式。

三、代码风格与格式化

  1. 统一格式化工具，不要人肉调格式

    • Java：Google Java Format / spotless

    • JS/TS：Prettier + ESLint

    • Python：black + flake8

    • Go：gofmt

  2. 把格式化集成在：IDE 保存自动格式化 + pre‑commit 钩子，不要放到 PR 评审里争论格式。

  3. 项目提交.editorconfig，统一不同 IDE 换行、缩进、编码。

  4. 禁止个人代码风格偏好，以项目配置为准。

原则：评审只看逻辑，不纠结空格换行。

四、Pull Request / MR 代码评审最佳实践

PR 提交人

  1. PR 尽量小，单 PR 控制 400 行以内，大功能拆成多个小 PR。

  2. 填写清晰 PR 描述：做了什么、为什么改、测试点、关联 issue。

  3. 自己先自查：删除调试代码、打印、注释掉的废弃代码。

  4. 本地自测通过，单元测试写完再提 PR。

  5. 评审意见及时回复；不认同要说明理由，不要直接驳回。

PR 评审人

  1. 先看逻辑正确性、边界、安全、性能，其次可读性。

  2. 给出建设性意见，避免 “写得不好” 这种主观评价；给出示例代码。

  3. 区分：必须修改（bug、安全） / 建议优化（可选）。

  4. 不要拖延评审；重要改动至少 1 人以上 Review。

禁止：大 PR 一次性合并；评审走过场直接点通过。

五、代码注释 & 文档

  1. 代码优先自解释，不要用注释翻译代码

    • ❌ // i加1 i = i +1

    • ✅ 复杂业务逻辑、算法、特殊坑点、为什么这么做写注释。

  2. 接口必须文档：OpenAPI/Swagger，入参、出参、错误码。

  3. README 必须包含：

    • 项目简介

    • 环境依赖

    • 本地如何启动、构建

    • 配置说明

    • 常见问题 FAQ

  4. 复杂业务模块增加doc/目录，流程图、业务规则。

  5. 废弃代码不要注释留在代码库，直接删除，Git 可以回溯历史。

六、依赖管理

  1. 锁定依赖版本：

    • Java：pom 完整版本，mvn dependencyLock

    • Node：package‑lock.json

    • Python：requirements.txt/poetry.lock

  2. 不要直接写 latest，避免构建环境版本漂移。

  3. 定期扫描依赖漏洞：OWASP dependency‑check、npm audit、dependabot 自动 PR 更新依赖。

  4. 内部私有组件统一版本，全团队复用，避免每个项目拷贝一份工具类。

  5. 禁止提交第三方源码进仓库，通过包管理器引入。

七、敏感信息绝对不能提交进代码库

  • ❌ 禁止提交密码、密钥、token、数据库连接串、AK/SK 到 Git

  • ✅ 使用环境变量、配置中心、密钥管理服务 KMS

  • ✅ 示例配置：application-example.yml，本地复制为真实配置文件，加入.gitignore

  • 工具：git-secrets、gitleaks，pre‑commit 检测密钥泄露。

.gitignore 规范

  • 每个项目维护完整 gitignore，IDE 配置、日志、编译产物、本地配置全部忽略；

  • 不要把个人 IDE 文件提交到仓库。

八、测试相关

  1. 核心业务逻辑写单元测试；复杂场景补充集成测试。

  2. CI 流水线执行：编译、单元测试、静态代码扫描，不通过禁止合并。

  3. 不要提交@Test注释掉的测试用例。

九、CI/CD 与流水线

  1. main/develop 分支每次提交自动跑 CI：编译、Lint、单元测试、漏洞扫描。

  2. PR 阶段就触发 CI，有失败不允许合并。

  3. 版本打 Tag 发布，Tag 语义化版本：v主.次.补丁 v1.3.2。

  4. 构建产物（jar、dist、docker 镜像）不要提交 Git，交给流水线产出。

十、团队协作习惯

  1. 避免重复造轮子：通用能力沉淀为公共模块，而不是每个项目复制粘贴。

  2. 重构和业务改动分开 PR：不要同一个 PR 同时改业务又做大规模重构。

  3. 旧技术债务：不要视而不见，登记 issue，分期迭代优化，不要堆积。

  4. 代码所有权是团队共有，不是个人私有，任何人都可以修改，改动需要走评审。

  5. 遇到历史烂代码：能小修就小修，不要无理由大规模重写。

十一、常见踩坑清单

  1. 不要在提交里混入格式化 + 业务逻辑改动，会让 PR 无法 Review；格式化单独一个 commit。

  2. 不要大量合并别人的分支，优先 rebase。

  3. 不要把本地调试硬编码提交。

  4. 不要依赖本地环境能跑，要保证仓库拉出来，按照 README 就能跑通。

精简版团队守则（可以贴在 wiki）

  1. main 分支禁止直接 push，所有改动走 PR/MR。

  2. 一个 PR 只做一件事，尽量小。

  3. commit 信息写清楚做了什么。

  4. 格式化交给工具，不人工纠结格式。

  5. 密钥密码绝不提交仓库。

  6. 复杂逻辑写注释，废弃代码直接删除。

  7. CI 不通过不允许合并。

  8. 评审看逻辑安全，不主观吐槽代码风格。

数据库有效数据备份方案