Developer Handbook:前端团队公司级开发实践手册——密钥管理、Git 工作流与协作规范
Developer Handbook:前端团队公司级开发实践手册——密钥管理、Git 工作流与协作规范
本文基于 developer-handbook 仓库中的 Company practices 页面展开,系统讲解 Apptension/Flairs 技术手册中面向前端工程师的三类公司级实践:基于 Keeper、aws-vault 与 One-Time Secret 的密钥管理,覆盖 PR 规范、分支保护、squash merge 与 Git 托管平台(GitHub/Bitbucket)的协作流程,以及 Slack、Confluence、Jira 等日常沟通规范。读完后你可以将这份 24 项自检清单直接用于团队入职培训或个人技能对标,并理解其中每项要求在仓库不同文档层级中的分布与演进。
一、"Company practices" 在手册中的定位
developer-handbook 是一个"观点鲜明(opinionated)"的开发者成长指南,README 将其组织为三大板块:Technical Stack(生产环境实际使用的技术与概念清单)、Technical Guide(按 Junior→Regular→Senior 划分的进阶学习路线)、Technical Onboarding Checklist(入职前两周的能力清单)。Company practices 是 Frontend Developer 技术栈目录中的第一个条目,与 Backend/DevOps/Mobile 三个角色各自名下的 "Company best practices" 页面内容一一对应。
从源码结构看,Frontend 版页面 内部所有锚点链接(如 #security、#git、#communication)都指向 Mobile 版规范页,即四份页面共用同一套规范正文,Mobile 版是事实上的"规范源(canonical)"。全页正文仅 24 条 checklist,分为三大块:
| 章节 | 覆盖工具 | 条目数 |
|---|---|---|
| Security(安全) | Keeper Security、aws-vault、One-Time Secret | 3 |
| Git | Git 核心工作流、GitHub、Bitbucket | 13 |
| Communication(沟通) | Slack、Confluence、Small Improvements、Jira、Email | 8 |
下文按原页面骨架逐节展开,并补充每项要求的落地操作与仓库内证据。
二、安全实践:三类场景的密钥管理
Security 章节回答一个核心问题:秘密值(secret values)在"公司内部分给同事"和"分享给公司外部"两种场景下,分别用什么工具、遵守什么规则。原页面为每条能力都标注了官方文档参考资料(Keeper 官方用户指南、One-Time Secret 帮助中心文章等),此处将要点内化为操作说明。
2.1 Keeper Security:内部同事间共享秘密值
对应清单条目:"You know how to share secret values with other employees."(你知道如何与其他员工共享秘密值。)
Keeper 是企业级密码/密钥保险库。落地要点:
- 数据库密码、API Key、证书等一律登记在 Keeper 中,而不是写在聊天记录、PR 描述或代码注释里;
- 共享粒度以"文件夹(folder)/记录(record)"为单位:把新同事加入项目对应文件夹即可获得授权范围内的全部秘密值,避免逐条复制粘贴;
- 共享时可设置过期时间,人员变动后回收权限,配合审计日志追溯访问记录。
2.2 aws-vault:命令行切换 AWS 用户身份
对应清单条目:"You know how to use the command line to switch between users."(你知道如何通过命令行在用户之间切换。)
aws-vault 的作用是把"长期 Access Key"替换为"临时凭证":登录一次后,终端内按需为不同 profile 获取短期 AWS 凭证。"在用户之间切换"即通过 profile 参数切换身份,常用命令(以下为该工具的通用用法,非本仓库定义的内容):
# 查看本机已配置的 profile
aws-vault list
# 以指定 profile 身份执行 AWS CLI 命令(最典型的"切换用户"方式)
aws-vault exec dev-ops -- aws s3 ls
# 为 SSO 登录的 profile 打开浏览器完成认证
aws-vault login dev-ops
# 注册一个新的 profile(交互式选择 provider/region)
aws-vault add staging
要点:日常操作尽量使用 aws-vault exec <profile> -- <命令> 这种"单次会话、临时凭证"的模式,避免把长期凭证固化到本地配置文件中;在多个环境(dev/staging/prod)之间切换时只改 profile 名,不改凭证文件。
2.3 One-Time Secret:向公司外部共享秘密值
对应清单条目:"You know how to share secret values externally."(你知道如何对外部方共享秘密值。)
One-Time Secret 提供"一次性秘密"链接:值被读取一次或超过设定有效期后链接即失效。适用场景:
- 向第三方合作方的开发/运维人员临时交付 API Key、Webhook 密钥、部署 token;
- 交付后立即通知对方核对,链接销毁后不留第二份副本;
- 严禁替代方式:不要把秘密值放进 PR 描述、GitHub Issue、邮件正文或普通即时消息里——这些渠道都会被归档,且没有"阅后即焚"能力。
三种工具的职责边界可概括为:内部共享用 Keeper(可管理、可审计),临时外部交付用 One-Time Secret(阅后即焚),命令行场景的身份切换用 aws-vault(临时凭证)。
三、Git 工作流实践
Git 是整页条目最多的一节(13 条),可拆成"日常 8 条核心规范 + GitHub 3 条 + Bitbucket 2 条"。
3.1 日常 Git 工作流 8 条核心规范
| 清单条目(原文) | 落地要点 |
|---|---|
| You create pull requests with proper name and description | PR 标题建议 类型/短名: 一句话说明(如 feature/user-profile: 支持头像上传);描述应包含背景、方案、自测方式与关联工单,让 reviewer 不看沟通记录也能理解改动 |
| You squash merge your pull requests | 合并一律使用 Squash Merge,使 develop/master 上每个功能只留一个语义完整的 commit;原页面为此附了 squash merge 利弊的参考文章 |
| You understand the pros and cons of git rebase vs git merge | rebase 得到线性历史、适合"本地提交追平上游";merge 保留真实拓扑。已推送到共享分支的提交不要 rebase(会改写他人历史) |
| You name your commits properly | 标题行建议 50 字符以内、祈使句,采用 type(scope): subject 形式,如 fix(auth): refresh expired token;正文说明动机与影响(原页面附 commit 命名参考文章) |
| You review PRs carefully and leave your comments | Review 是清单能力而非走过场:关注正确性、边界条件、可维护性与测试覆盖,并留下可执行的评论 |
| You know how to configure rules in a repository for merging to specific branches (master, develop) | 在托管平台的"受保护分支(protected branch)"中为 master/develop 配置:要求至少 N 个 review 通过、要求 CI 状态检查通过、限制可直推人员(可勾选"包含管理员") |
| You add proper label in pull requests | 用 label(如 feature/bugfix/docs/refactor)给 PR 分类,便于筛选、统计与发布说明生成 |
| You create your branches under the proper folder (feature, fix, hotfix) | 分支名带"文件夹前缀":feature/xxx(新功能)、fix/xxx(缺陷修复)、hotfix/xxx(线上紧急修复),在 PR 列表与 diff 工具里一眼可辨性质 |
以一个功能为例的完整流程示意(命令为通用示例,具体分支基线以团队约定为准):
# 1. 从 develop 出发,按 feature 文件夹命名规范建分支
git checkout -b feature/user-profile develop
# 2. 开发过程中保持提交信息符合命名规范
git commit -m "feat(profile): add avatar upload"
# 3. 提交 PR 前追平上游,保持 rebase 的线性历史
git pull --rebase origin develop
git push -u origin feature/user-profile
# 4. 在平台上:加 label、指派 reviewer;CI 全绿 + review 通过后
# 选择 Squash & merge 合入 develop
3.2 GitHub 三项能力
- 创建并引用 Issue:会用
#123这类引用语法在 PR/commit 描述中关联 Issue,使"改动—问题"双向可追踪; - 确认 build check 失败:PR 的 Checks 区域出现红色 ✗ 时,能进入 CI 日志定位失败步骤(lint、test、build),而不是简单重跑;
- 创建 GitHub Wiki 页面:把项目级文档(架构说明、操作手册)沉淀到 Wiki,而不是只留在聊天记录里。
3.3 Bitbucket 两项能力
- 确认 build check 失败:与 GitHub 同理,在 Bitbucket 的 pipeline/branch status 中定位失败原因;
- 在 commit 中引用 Jira 工单:commit 消息携带工单号(如
[ABC-123] fix: correct date formatting),使代码提交与 Jira 工单自动关联、可追溯。具体前缀格式以团队约定为准,原页面只要求掌握"可引用"这一能力。
四、沟通实践:五类工具的使用规范
Communication 章节共 8 条,覆盖状态同步、知识沉淀、目标管理与工单流转。
4.1 Slack(2 条)
- 状态使用:"You use Slack statuses in line with company policy (remote working, vacationing, in a meeting, etc)"——远程办公、休假、会议中都要设置对应状态,让协作方不用猜测你的可用性;
- 组织管理:"You know how to create groups and channels"——能创建公共 channel(项目/技术讨论)与私有 group(敏感信息小范围同步),并维护成员归属。
4.2 Confluence(1 条)
"You know how to create Confluence pages"——把设计评审结论、事故复盘、技术方案等长文档写入 Confluence 页面而非群聊,保证知识可检索、可更新。
4.3 Small Improvements(2 条)
- "You know how to give praise and add talk topics to a 1:1 meeting"——会向同事表达认可,并把想谈的话题提前加入 1:1 议程;
- "You know how to create goals and mark them as complete"——能创建个人成长目标并在达成后标记完成,使 1:1 沟通有明确抓手。
4.4 Jira(1 条)
"You know how to create tickets and write comments"——会建工单并写清可执行的描述(背景/步骤/预期),评论用于同步进展而非倾倒日志。
4.5 Email(2 条)
- "You can configure local email client"——能配置本地邮件客户端(收/发协议、账号);
- "You can configure email signatures"——能配置统一的公司邮件签名。
五、级别演进:同一套实践在 Onboarding 与 Technical Guide 中的分布
仓库中同一批条目在 Junior/Regular/Senior 三个入职清单和技术进阶指南里按级别裁剪,这本身就是手册"分级培养"思路的体现。以 Frontend 角色为例(依据各文件实际内容):
| 文档层级 | 覆盖的 Company practices 条目 | 证据位置 |
|---|---|---|
| Junior 入职清单 | 仅 Git 3 条(PR 规范、squash merge、commit 命名)+ Slack 状态 1 条,共 4 条 | Onboarding/Junior/Frontend Developer.md |
| Regular 入职清单 | 增加 Security 2 条(Keeper、One-Time Secret)+ Git 至 5 条(新增 PR review、分支合并规则)+ Bitbucket 1 条,共 9 条 | Onboarding/Regular/Frontend Developer.md |
| Senior 入职清单 | 与 Regular 清单同构(Security 2 + Git 5 + Bitbucket 1 + Slack 1) | Onboarding/Senior/Frontend Developer.md |
| Regular→Senior 进阶指南 | 完整 24 条:含 aws-vault、PR label、分支文件夹、GitHub 3 条、Confluence、Small Improvements、Jira、Email | Technical Guide/Regular to Senior/Frontend Developer.md |
两点从仓库结构可以确认的观察:
- Junior 的及格线是"自己交付规范化"——先把 PR、commit、squash merge 做对,再逐步扩展到 review 他人代码与分支保护配置;
- aws-vault 与 label/分支文件夹条目在 Frontend 的 Junior/Regular/Senior 入职清单中均未出现,只在 Regular→Senior 进阶指南 与 Technical Stack 规范页 中出现——可以推断公司把"命令行切换云用户身份"与"分支体系化管理"视为向 Senior 进阶时补全的能力,而非入职首周内容。
六、24 条完整清单速查
供团队对照使用的全量条目(与 规范页 一致):
Security:① 会向同事共享秘密值(Keeper);② 会用命令行切换 aws-vault 用户;③ 会向外部方共享秘密值(One-Time Secret)。
Git:④ PR 有规范名称与描述;⑤ 使用 squash merge;⑥ 理解 rebase 与 merge 的利弊;⑦ 规范命名 commit;⑧ 认真 review PR 并留评论;⑨ 会配置仓库对 master/develop 的合并规则;⑩ PR 添加合适 label;⑪ 分支建在正确文件夹下(feature/fix/hotfix);⑫ 会创建并引用 GitHub Issue;⑬ 会排查 GitHub build check 失败;⑭ 会创建 GitHub Wiki 页面;⑮ 会排查 Bitbucket build check 失败;⑯ 会在 commit 中引用 Jira 工单。
Communication:⑰ Slack 状态符合公司政策;⑱ 会创建 Slack 群组与频道;⑲ 会创建 Confluence 页面;⑳ 会在 Small Improvements 中点赞并为 1:1 添加话题;㉑ 会创建目标并标记完成;㉒ 会创建 Jira 工单并写评论;㉓ 会配置本地邮件客户端;㉔ 会配置邮件签名。
该页面由 Flairs 与 Apptension 团队共同维护(页脚标注 © 2020 Flairs Sp. z o.o.),仓库 CONTRIBUTING 说明欢迎通过 pull request 扩充或修改上述要求,由技术团队评审后合入主文档;发现问题则提交到 Issues。若你正在为自己的团队编写类似的手册,这页"工具名 + 一句话能力描述"的 checklist 组织方式(每项可勾选、可溯源到具体工具)也值得直接参考。