01.4.1.5 文档、协作与交付节奏
所属:全栈开发面试题库 / 01 计算机基础与通用工程 / 01.4 工程素养 / 01.4.1 工程素养
01.4.1.5-001 项目文档体系包含哪些部分?
一句话结论
项目文档体系包括需求与验收标准、技术设计、接口契约、部署运维说明、变更记录与知识库;文档按使用对象分层,核心是让新成员与协作者快速理解系统,且随代码同步维护。
概念解释
- 需求/设计:业务目标、方案取舍。
- 接口/数据:契约、模型、约定。
- 运维:部署、配置、监控、应急预案。
原理流程
- 按使用角色梳理文档类型。
- 明确各文档存放位置与更新责任人。
- 代码变更同步更新对应文档。
代码或图示
需求/验收 → 技术设计 → 接口契约 → 数据模型
→ 部署运维/监控告警 → 变更记录/FAQ
常见误区
- 文档一次性写完不再更新:与代码脱节后比无文档更误导。
- 所有细节都写进文档:代码自解释部分不必重复,文档聚焦决策与边界。
追问
- 文档放哪?答:与代码同仓库的 docs 目录或团队知识库,按模块组织,链接可追溯。
- 谁维护文档?答:作者对自己模块文档负责,评审检查文档是否同步。
01.4.1.5-002 README 与代码内文档写什么?
一句话结论
README 写项目定位、快速启动、目录结构、关键命令与依赖说明;代码内文档写公共接口契约、复杂逻辑动机与约束;面向使用者的说明放 README,面向维护者的细节放代码注释与模块文档。
概念解释
- README:入口级信息,新人可快速跑起来。
- 接口文档:参数、返回、错误码、示例。
- 模块文档:职责、边界、扩展方式。
原理流程
- README 补定位、启动、命令、结构。
- 公共 API 写契约与示例。
- 复杂逻辑补动机与约束注释。
代码或图示
README:项目简介 / 环境要求 / 启动步骤 / 目录 / 常用命令
代码内:接口契约 / 复杂算法 / 约定与坑位
常见误区
- README 只写项目名:缺少启动与命令信息,新人上手成本高。
- 代码注释复述代码:应解释为什么与约束边界。
追问
- 内部模块要不要 README?答:职责复杂、跨团队使用的模块需要;简单模块靠代码与接口文档即可。
- 文档过期怎么发现?答:onboarding 反馈、评审检查、定期梳理链接有效性。
01.4.1.5-003 常见 Git 分支策略有哪些?
一句话结论
常见策略有 trunk-based(主干开发 + 短分支 + 特性开关)、GitFlow(长期 develop/feature/release/hotfix 分支)与 GitHub Flow(主干 + 短功能分支);按发布频率、团队规模与版本维护需求选择,策略需配套分支命名与合并规则。
概念解释
- trunk-based:主干始终可发布,分支生命周期短。
- GitFlow:分支角色完整,适合多版本并行维护。
- GitHub Flow:主干 + 功能分支,合并即部署。
原理流程
- 按发布节奏与版本维护需求选策略。
- 约定分支命名与合并/发布规则。
- 流水线按分支触发对应环境部署。
代码或图示
trunk:main ← 短 feature 分支 → 合并 → 发布
GitFlow:develop ← feature;release 分支;hotfix 回主干
GitHub Flow:main ← feature 分支 → 合并部署
常见误区
- 照搬复杂流程到小团队:分支维护成本高于收益。
- 分支长期不合并:积累冲突与集成风险。
追问
- 长期版本维护用哪种?答:GitFlow 类策略支持 release/hotfix 分支;高频发布服务更适合 trunk-based。
- 特性开关和分支策略关系?答:开关让未完成功能不进入主干,配合短分支降低集成风险。
01.4.1.5-004 merge 和 rebase 怎么取舍?
一句话结论
merge 保留分支历史并生成合并提交,历史呈网状;rebase 把提交搬到目标分支之后,历史线性但改写 commit hash;本地未推送的提交可用 rebase 整理,已共享到公共分支的提交不要 rebase,避免影响他人。
概念解释
- merge:双父提交,保留完整历史。
- rebase:重放提交,哈希变化。
- 安全边界:公共分支已推送提交禁止改写。
原理流程
- 本地开发分支整理用 rebase 保持线性。
- 合并到主干按团队策略用 merge 或 squash。
- 冲突在 rebase 中逐个解决并
--continue。
代码或图示
git merge main # 保留历史,生成合并提交
git rebase main # 本地提交重放到 main 之后
git pull --rebase # 拉取时变基,避免无意义合并提交
常见误区
- 对公共分支 rebase:他人基于旧提交开发,历史分叉难协调。
- rebase 冲突反复硬推:应先理解冲突来源再解决。
追问
- rebase 冲突怎么处理?答:逐个提交解决,
git rebase --continue;放弃用--abort回到变基前。 - squash merge 适用什么场景?答:把功能分支多个调试提交压缩为一个清晰主干提交。
01.4.1.5-005 Git 怎么回滚?reset、revert、reflog 怎么用?
一句话结论
reset 移动分支指针撤销提交,分 soft(保留暂存区)、mixed(保留工作区)、hard(丢弃修改);revert 生成反向提交,不改写历史,适合已推送的公共分支;误删历史用 reflog 找回指针。
概念解释
- soft:撤销提交,改动留在暂存区。
- mixed:撤销提交与暂存,改动留工作区。
- hard:丢弃提交与工作区修改(危险)。
- revert:反向提交,历史安全。
原理流程
- 判断提交是否已推送共享。
- 本地未推送用 reset 调整。
- 公共分支用 revert 新增反向提交。
- 误操作经 reflog 定位恢复。
代码或图示
git reset --soft HEAD~1 # 撤销提交,保留暂存区
git reset --mixed HEAD~1 # 撤销提交与暂存,保留工作区
git reset --hard HEAD~1 # 丢弃提交与修改(危险)
git revert <commit> # 生成反向提交,安全
git reflog # 查看 HEAD 移动历史找回提交
常见误区
- 公共分支 reset --hard 后强推:他人本地历史被破坏。
- 依赖 reflog 长期保存:reflog 有保留期限,重要恢复应尽快固化分支。
追问
- 找回被删分支怎么做?答:
git reflog找到提交哈希,git branch <名> <哈希>重建分支。 - revert 多个连续提交怎么处理?答:逐段 revert 或 revert 范围,注意提交顺序与依赖。
01.4.1.5-006 提交信息怎么写?
一句话结论
提交信息遵循统一格式:类型前缀(feat/fix/refactor/docs/test/chore)+ 简短主题说明动机与内容,必要时正文补充背景、影响与关联单号;一个提交完成一件事,便于回溯与回滚。
概念解释
- 类型:新功能、修复、重构、文档、测试、杂务。
- 主题:一句话说明做了什么与为什么。
- 正文:背景、边界、关联需求/缺陷单号。
原理流程
- 按改动类型选前缀。
- 主题写清动机与内容。
- 复杂改动补正文与关联单号。
代码或图示
feat(order): 支持优惠券叠加计算
- 叠加规则:满减优先于折扣
- 关联需求:ORDER-123
常见误区
- 信息写“更新代码/修复 bug”:无法回溯变更意图。
- 一个提交混杂功能与重构:回滚与评审困难。
追问
- 提交信息要写性能数据吗?答:有取舍或基准结论时可在正文说明,常规改动不必。
- 调试提交怎么处理?答:推送前整理为清晰提交,公共历史保持可读。
01.4.1.5-007 协作冲突怎么解决?
一句话结论
冲突源于同一文件相近位置的并行修改;解决时先理解双方改动意图,保留有效变更、去除重复,编译测试通过后再提交;频繁冲突说明模块边界或分工需调整。
概念解释
- 冲突标记:
<<<<<<<、=======、>>>>>>>。 - 解决:逐段比对双方改动。
- 验证:解决后编译、跑测试确认。
原理流程
git status查看冲突文件。- 打开冲突段比对双方意图。
- 合并有效变更,移除标记。
- 编译测试后提交。
代码或图示
git status
# 编辑冲突段,保留双方有效改动
git add <file>
git commit
常见误区
- 直接选某一方版本:可能丢失另一方有效改动。
- 解决后不跑测试:冲突合并引入编译/行为问题。
追问
- 冲突文件太多怎么办?答:拆分任务减少同文件并行修改,模块边界重新划分。
- 二进制文件冲突怎么处理?答:按来源确认保留版本,必要时重新生成,避免直接合并。
01.4.1.5-008 CI/CD 流水线一般包含哪些环节?
一句话结论
典型流水线:提交触发 → 代码检查(lint/格式/类型)→ 单元与集成测试 → 构建产物 → 安全扫描 → 推送制品仓库 → 部署测试环境 → 集成/回归测试 → 审批 → 生产灰度/发布 → 监控与回滚;流水线可重复、幂等,失败快速反馈。
概念解释
- CI:集成、检查、测试、构建。
- CD:部署、发布、监控、回滚。
- 幂等:同一产物多环境部署,不在环境内重复构建。
原理流程
- 代码提交触发流水线。
- 静态检查与测试门禁。
- 构建制品并扫描,推送仓库。
- 分环境部署,审批后发布并监控。
代码或图示
提交 → lint/type-check → 单元/集成测试 → 构建镜像
→ 安全扫描 → 制品仓库 → 测试环境部署 → 回归测试
→ 审批 → 生产灰度/发布 → 监控/回滚
常见误区
- 流水线在每个环境重新构建:产物不一致,应一次构建多环境部署。
- 失败不阻断:门禁失效,问题流入后续环节。
追问
- CI 构建慢怎么优化?答:缓存依赖、并行任务、增量构建、拆分慢测试定时跑。
- 流水线密钥怎么管理?答:用 CI 变量/密钥管理服务,不进代码库与日志。
01.4.1.5-009 构建产物与多环境部署怎么管理?
一句话结论
构建产物(镜像/包)版本化、不可变,一次构建在开发、测试、预发、生产各环境部署;环境差异通过配置注入,不修改产物;部署记录可追溯,支持按版本回滚。
概念解释
- 不可变产物:构建后内容不随环境改动。
- 配置分离:环境变量/配置中心注入差异。
- 版本追溯:制品版本与发布记录对应。
原理流程
- 流水线构建带版本标识的制品。
- 推送制品仓库统一管理。
- 各环境拉取同一制品,注入配置部署。
- 发布记录绑定制品版本。
代码或图示
构建:app:1.2.3(不可变)
测试环境 → 注入测试配置
预发环境 → 注入预发配置
生产环境 → 注入生产配置
回滚:切回上一版本制品
常见误区
- 生产环境手工改代码/配置:产物不可追溯,回滚困难。
- 环境配置打进制品:换环境需重新构建,易不一致。
追问
- 数据库变更怎么随产物管理?答:迁移脚本随制品版本管理,按顺序执行并支持回滚,与应用版本配套。
- 配置敏感项怎么注入?答:密钥管理/环境变量,不落制品镜像与代码库。
01.4.1.5-010 常见发布策略有哪些?
一句话结论
蓝绿部署(两套环境切换)、金丝雀/灰度(小流量逐步放量)、滚动发布(逐批次替换实例);选择取决于回滚速度要求、流量风险与资源成本,关键链路配套监控对比与自动回滚条件。
概念解释
- 蓝绿:新旧两套并行,切流切换,回滚快。
- 金丝雀:少量用户先体验,逐步扩大。
- 滚动:分批替换老实例,资源占用小。
原理流程
- 按风险与资源选择发布策略。
- 部署新版本并接入小流量。
- 观察指标对比新旧版本。
- 达标扩大,异常回滚。
代码或图示
蓝绿:Green 运行 → Blue 就绪 → 切流 → 回滚切回
金丝雀:1% → 10% → 50% → 100%(指标异常即回滚)
滚动:实例 1/N 替换 → 逐批完成
常见误区
- 发布无监控对比:问题不能及时发现。
- 灰度批次一步到位:失去逐步验证意义。
追问
- 回滚怎么做最快?答:蓝绿切流最快;滚动/金丝雀回退到上一版本实例与配置。
- 数据库变更怎么配合发布?答:向后兼容变更先行,应用切换后再清理旧结构,分步可逆。
01.4.1.5-011 版本号与变更记录怎么维护?
一句话结论
版本号遵循语义化版本(主版本.次版本.修订号),变更记录按版本记录新增、修复、变更与兼容提示;每次发布更新变更日志,便于追溯版本差异与回滚依据。
概念解释
- 主版本:不兼容变更。
- 次版本:向下兼容的功能新增。
- 修订号:向下兼容的缺陷修复。
原理流程
- 按变更类型确定版本号。
- 发布前更新变更日志。
- 制品版本与日志、发布记录对应。
代码或图示
版本:1.2.3(主 1 / 次 2 / 修订 3)
变更记录:
## 1.2.3
### 新增:xxx
### 修复:xxx
### 变更:xxx
常见误区
- 版本号随意递增:无法从版本判断兼容风险。
- 变更记录只写“更新”:缺少差异信息。
追问
- 预发布版本怎么编号?答:加预发布标识(如 alpha/beta/rc),具体规则按团队约定。
- 变更记录谁写?答:随提交累积,发布时整理归档。
01.4.1.5-012 多环境怎么管理?
一句话结论
环境分开发、测试、预发、生产,职责清晰:开发联调、测试验证、预发贴近生产、生产对外服务;环境配置与数据隔离,部署流水线按环境递进,生产变更走审批与灰度。
概念解释
- 开发:日常联调,数据可随意。
- 测试:自动化与功能验证。
- 预发:同构生产配置与数据量级。
- 生产:真实流量与数据。
原理流程
- 定义各环境用途与准入标准。
- 配置与数据按环境隔离。
- 流水线逐级部署,生产审批发布。
- 环境差异定期核对。
代码或图示
开发 → 测试 → 预发 → 生产
配置:环境变量/配置中心注入
数据:隔离 + 脱敏,生产数据不流入低环境
常见误区
- 预发与生产配置不一致:预发验证结论不可靠。
- 低环境使用生产真实敏感数据:隐私合规风险。
追问
- 环境依赖中间件怎么管理?答:测试用容器化/共享实例,预发贴近生产规格,避免环境漂移。
- 生产配置变更流程?答:变更前评审、备份配置、灰度生效、观察指标,可快速回退。
01.4.1.5-013 跨团队协作与接口怎么对齐?
一句话结论
跨团队先对齐接口契约、职责边界、排期与验收标准,明确对接人;接口变更走通知与版本管理,联调前用契约/ Mock 并行开发,问题升级路径事先约定。
概念解释
- 契约:字段、类型、错误码、SLA。
- 边界:谁提供什么、依赖谁的排期。
- 沟通:对接人、评审节点、升级路径。
原理流程
- 梳理上下游依赖与对接人。
- 评审接口契约与验收标准。
- 并行开发,按契约联调。
- 变更同步双方,风险提前升级。
代码或图示
依赖梳理 → 契约评审(字段/错误码/SLA/排期)
→ Mock 并行开发 → 契约联调 → 变更通知/版本管理
常见误区
- 联调前无契约:字段与语义理解不一致,返工多。
- 接口变更不通知:消费方被动跟随,线上故障。
追问
- 对方排期延期怎么办?答:提前识别依赖阻塞,评估替代方案并同步项目计划。
- 接口文档谁维护?答:提供方维护,消费方评审确认,变更双向同步。
01.4.1.5-014 日常沟通节奏有哪些?
一句话结论
常见节奏包括每日站会(同步进展/阻塞)、需求与方案评审、周会/迭代回顾、故障复盘;会议聚焦决策与阻塞,结论形成任务与责任人,避免无议程例会占用开发时间。
概念解释
- 站会:进展、计划、阻塞三件事。
- 评审:方案与代码质量把关。
- 回顾:流程与协作改进。
原理流程
- 按项目节奏约定会议类型与时长。
- 会前准备材料,会中决策记录。
- 会后任务跟踪闭环。
代码或图示
站会:昨天/今天/阻塞
评审:需求 / 方案 / 代码
回顾:迭代成果 / 问题 / 改进项
常见误区
- 站会变成详细汇报:应简短同步阻塞与计划。
- 会议结论无任务跟踪:决策停留在口头。
追问
- 分布式团队怎么对齐?答:异步文档 + 固定同步会议,关键决策留书面记录。
- 阻塞问题怎么升级?答:站会识别后约定跟进人与时限,超时升级。
01.4.1.5-015 任务拆解与看板怎么跟踪?
一句话结论
任务拆成可独立交付、有验收标准的单元,按待办/进行中/评审/完成在看板可视化;每日更新状态,阻塞项显式标注,负责人与期限明确,避免任务堆积在个人手中。
概念解释
- 粒度:1–3 天可完成、可验收。
- 流转:待办 → 进行 → 评审 → 完成。
- 可视化:阻塞、积压、进度一目了然。
原理流程
- 需求拆分为任务并写验收标准。
- 认领后更新看板状态。
- 阻塞标注并协调资源。
- 完成验收后关闭。
代码或图示
待办 → 进行中 → 评审 → 完成
阻塞:单独标注,附原因与协助需求
每张卡:负责人 / 期限 / 验收标准 / 关联需求
常见误区
- 任务拆得过粗:无法并行与验收。
- 看板状态不更新:进度信息失真。
追问
- 看板 WIP 限制是什么?答:限制进行中任务数,促使完成再领新任务,减少上下文切换。
- 跨团队任务怎么跟踪?答:明确对接人,任务状态双向同步,依赖节点设检查点。
01.4.1.5-016 迭代规划与范围控制怎么做?
一句话结论
迭代规划按优先级与容量确定本期范围,明确目标与验收标准;需求变更走评估流程,调整范围/排期/质量取舍;迭代内不随意插入未评估需求,保护交付节奏。
概念解释
- 优先级:业务价值与风险排序。
- 容量:团队历史产能与可用人力。
- 变更:评估影响后决策取舍。
原理流程
- 收集需求并排优先级。
- 按容量规划迭代目标与任务。
- 变更评估范围、排期、成本。
- 迭代回顾修正估算基线。
代码或图示
需求池 → 优先级排序 → 容量匹配 → 本期范围/验收标准
插入新需求:评估影响 → 取舍(范围/排期/质量)→ 更新计划
常见误区
- 迭代中不断插需求:交付节奏被打断,质量下降。
- 范围承诺无缓冲:估算偏差直接挤压测试与修复时间。
追问
- 高优先级紧急需求怎么处理?答:评估顶替范围或追加排期,不默认挤占质量时间。
- 迭代目标怎么定?答:可衡量的业务/交付结果,而非任务罗列。
01.4.1.5-017 日志规范有哪些要求?
一句话结论
日志结构化输出,包含 traceId、用户/业务标识、耗时与结果;分级使用 ERROR/WARN/INFO/DEBUG,异常打印堆栈;不记录敏感信息,避免循环内大量日志与大对象输出;按天滚动并按合规周期留存。
概念解释
- 结构化:固定字段或 JSON,便于检索聚合。
- 分级:ERROR 需告警,WARN 关注,INFO 关键流程,DEBUG 仅开发。
- 脱敏:密码、令牌、证件号等不进日志。
原理流程
- 入口/出口打点记录关键上下文。
- 异常记录堆栈与业务标识。
- 按级别输出,敏感字段脱敏。
- 采集归集并按周期留存。
代码或图示
字段:traceId / userId / 业务标识 / 耗时 / 结果 / 异常堆栈
级别:ERROR 告警 · WARN 关注 · INFO 流程 · DEBUG 调试
禁忌:敏感信息 / 循环刷屏 / 大对象全量输出
常见误区
- 日志只打“成功/失败”无上下文:排查无法串联。
- 异常吞掉不打堆栈:根因无法定位。
追问
- 日志太多影响性能怎么办?答:异步 appender、采样、降低级别,热点路径避免同步重 IO。
- 日志怎么串联请求?答:traceId + MDC 透传,跨线程/跨服务传递上下文。
01.4.1.5-018 发布前质量门禁检查什么?
一句话结论
发布门禁包含:测试通过(单元/集成/回归/核心 E2E)、静态检查与安全扫描通过、变更文档与接口契约更新、监控告警就位、回滚方案明确、数据库迁移可逆;门禁不通过不进入生产发布。
概念解释
- 质量:测试覆盖与缺陷状态。
- 安全:依赖漏洞、敏感信息、权限校验。
- 可回滚:版本制品、配置回退、迁移可逆。
原理流程
- 流水线自动跑测试与扫描门禁。
- 人工核对文档、监控、回滚预案。
- 确认数据库变更兼容可逆。
- 审批后按策略发布并观察。
代码或图示
□ 单元/集成/回归/E2E 通过
□ 静态检查/安全扫描通过
□ 文档/接口契约已更新
□ 监控告警已接入
□ 回滚方案与版本制品就绪
□ 数据库迁移兼容可逆
常见误区
- 门禁只看测试通过:监控、回滚、文档缺失会在故障时放大影响。
- 紧急发布跳过门禁:应记录缺口并事后补齐,高风险变更不可省略。
追问
- 灰度观察哪些指标?答:错误率、P95/P99 延迟、业务成功率、资源水位,与旧版本对比。
- 回滚条件怎么定?答:错误率/延迟超阈值、核心业务失败、告警触发即回滚,不等待人工判断。