滑雪事故如何考验我们的开发实践

# 一场滑雪事故如何检验了我们的开发实践 来源: https://blog.enioka.com/2026/07/03/how-a-skiing-accident-put-our-development-practices-to-the-test/ > 独缺一人，万境皆空。 – 拉马丁 **免责声明**: 本文翻译自一篇法文原文 (https://blog.enioka.com/2026/07/03/comment-une-chute-en-ski-a-permis-de-tester-nos-pratiques-de-developpement/)。因此文中包含一些法文截图。特此提醒。 ## 引言 在 enioka Haute Couture，我们与客户团队携手构建软件。我们带来应用设计和开发活动组织方面的专业知识。 因此，在我们的项目中，通常会组建一个由经验丰富的 Tech Lead 主管的团队，该团队包含客户方的开发人员和 Haute Couture 的开发人员。 这种组织方式旨在创建满足需求、可靠且由客户完全掌握的应用程序。我们在任务结束时移交应用程序的“钥匙”，而不锁定客户（参见 enioka Haute Couture 宣言 (https://haute-couture.enioka.com/en/manifesto)）。 为此，我们倡导通过书面文档促进知识转移的开发方法。 您可能会想：“又来了，又是一篇作者自我吹嘘或美化公司形象的博客文章。” 如果我们相信 medium.com 上的所有文章，那么似乎每个人都在写测试，每个人都在更新文档！然而我们都清楚，现实绝非如此。否则我们早该知道，或者至少能亲眼见到。 老实说，大多数情况下，当一个项目有文档——这本身就不常见——我们顶多会看到下面这样的东西。 顶部文字：“初级开发者：‘我该怎么做？’ 高级开发者：‘去看文档！’ 文档内容：” 底部图片：一张乐高拼装说明书中的示意图。一个三格长的乐高积木漂浮在一底板上方，有两个箭头指向下方指示其应放置的位置。然而，这两个箭头间距过大，指向了横跨四格的位置，使得三格长的积木根本无法按照指示安装。所以，我们不会自夸太多，但确实有过一次相当痛苦的经历，让我们的模式接受了一次突如其来的残酷考验。 ## 技术主管说“消失”就“消失” 2026 年初，我们正在为一位客户的实验室管理应用开展开发任务。 我们组建了一个团队，包括一名来自 enioka Haute Couture 的 Tech Lead 和一名开发者，以及一名客户方的开发者。 经过与利益相关者进行几次工作坊后，设计方案确定，待办事项列表（backlog）初始化，项目按照敏捷流程启动。 冲刺一个接一个地过去，应用程序的基础已经奠定，CI/CD 流水线使我们能够在第一个测试环境中测试和部署应用程序。 然而，应用程序尚未完全定义：某些功能仍在与业务方的工作坊中讨论。一些棘手的问题仍然存在，正在迭代解决。 然后迎来了复活节周末。每个人都去享受长周末，并承诺周二回来时精力充沛。 但周末结束时，灾难降临了：Tech Lead 没有回来。 一张照片显示一名滑雪者仰面躺在雪地上，一条手臂横在身体上。在他们左侧，一名穿着印有“滑雪巡逻”字样夹克的救援人员跪在他们身旁。事故来得快，不仅仅是在进行危险活动时才会发生。它可能在任何项目中、任何时候发生。 想想您的团队中有多少人会去滑雪、骑马、做 DIY 项目，或者只是开车？将这个数字乘以四肢的数量，您就会对有人受伤的概率有个概念！ 在我们的案例中，我们的 Tech Lead 参与了所有这些消遣活动，并且至今四肢健全。 ## 一天之内重新掌控局面 为了应对这一特殊情况，enioka Haute Couture 迅速动员，指派了一名新的 Tech Lead 来承担项目领导职责。由于在假期期间就接到了事故通知，替代人选在一周内就安排好了。 "梗图：《指环王》中的波罗米尔，一脸担忧地说：‘重启项目可不像走个过场那么简单。’"但新的 Tech Lead 不了解项目，没有参加过工作坊，却需要快速上手工作。 幸运的是，项目从一开始就建立了良好的文档实践。新的 Tech Lead，就像团队其他成员一样，可以访问多层文档来理解正在构建的解决方案的复杂性。 ## 项目描述 这是第一级信息。在 enioka Haute Couture，我们有一个内部维基，其中每个项目都描述了以下内容： - 任务的议题、其重要性和预期成果。 - 项目利益相关者、角色和联系信息的识别。 - 沟通渠道。 - 客户提供的工具：电子邮件、知识库、工单管理器、代码仓库。 - 文档入口点。 ## 日志 除了 Tech Lead 维护的日志外，还有一个共享的项目日志，记录了项目的历史。 它回顾了过去和未来的里程碑，以及重要的项目事件（首次交付、事故等）。 我们还记录会议纪要。 ## 架构文档 在设计阶段，我们创建一份架构文档，描述应用程序的工作原理、与外部组件的集成以及内部组织。 这是团队用来理解解决方案的文档。 该文档遵循 C4 模型 (https://c4model.com/) 的形式，从最通用的视角到必要时实现细节的层面来描述解决方案。它还包含其他形式的图表信息： - 数据模型 - 部署图 - 主要流程的状态机 随着项目的进行，这份文档会不断调整和扩展，以反映应用程序的实际情况。 基于“C4 模型”形式的组件图截图。四个角色访问一个 MVC Web 应用程序的界面，该应用程序由视图和控制器组成。一个持久层向 PostgreSQL 存储读取和写入数据。 ## 特定机制的解释 除了架构文档，团队还会制作解释应用程序特殊或非标准部分的文章。例如，认证机制、复杂的业务流程…… 它提供了对组件工作原理的推论性解释，以实现细粒度的理解。 对于这个项目，我们有文章解释了认证部分、面包屑导航的工作原理以及用户操作追踪机制。 文档门户，左侧导航菜单包含法语内容：“Entra ID 配置流程”、“SSO 技术配置”、“屏幕访问摘要”、“测试数据”、“面包屑导航”、“变更历史记录”和“文档生成接口协议”。 ## README 一份介绍性文档列出了为项目做出贡献所需的所有信息。该文档描述了必要的依赖项、常用命令（例如，数据库迁移、测试）、正在使用的命名规则和约定等。 开发实践要么在此文档中描述，要么引用外部资源。 通常，此文档位于代码仓库中，习惯命名为「README」。 它有助于项目入职。在这种情况下，新的 Tech Lead 可以快速在本地运行解决方案。它还结合了解释特定任务的教程。 一份“README”文档摘录，列出了开发依赖项（git、dotnet 等），并提供了设置开发工作站的说明。 ## 教程 某些开发任务可能需要开发团队中并非所有成员都已获得或掌握的知识。 例如，如何在本地机器上启动一个完整的环境，如何调试一个棘手的部分，如何维护代码的某个部分。 这些教程通常由整个团队编写，便于新成员加入项目，并补充已经自动化的元素（docker-compose、.editorconfig 等）。 一份教程摘录，解释了如何使用 Minikube 将应用程序部署到本地 Kubernetes 集群。开发者可以选择运行脚本或手动执行步骤。 ## API 文档 API 文档是根据开发人员在代码结构中编写的文档标签发布的。这是生产代码的参考。 它使用能够从源代码提取信息的工具（docstrings、XmlString、javadoc）生成。根据语言，我们可以选择 Doxygen、DocFx、Sphinx…… 它允许探索解决方案的结构，并在无需阅读代码的情况下查阅某些常量的值和使用方法。 如果构建得当，它还可以指示如何使用结构，从而简化新贡献者的入职过程。 代码文档摘录，解释了如何使用 `CaptureChangements()` 方法。 ## 自动化测试 每次更改都会附带一个或多个测试，以确保足够的代码覆盖率。测试确保开发按预期完成，并防止回归。 现有的测试形式化了可能未在正式描述中体现的行为，或代表了开发人员在本地做出的选择。 因此，当贡献者的更改破坏了某个他们可能不知情的功能时，他们会收到警告。 ## CI/CD 从项目开始就设置自动化，可以轻松执行开发任务和应用程序发布。这样，团队只需按一下按钮就可以打包和部署应用程序。 自动化执行测试、代码质量检查（linting）和静态代码分析，有助于维持预定义的应用程序质量，无论团队成员如何变化。 文档发布也是 CI/CD 流水线中的一个步骤。 代码仓库徽章截图，显示：pipeline 通过、覆盖率 94.59%、最新发布版本 0.49.0。 ## 运维手册 运维手册收集了运行应用程序所需的所有信息。它建立在部署图的基础上，增加了所需设备（虚拟机、数据库等）的名称和地址。 所有维持运行条件的程序都逐步描述。例如，重启、数据库备份和恢复。 这份文档本质上是知识转移文档，因为管理操作通常委托给运维团队或管理服务提供商。 对于新的 Tech Lead 来说，它有助于理解应用程序应如何部署。 Kubernetes 架构图，显示了用户请求通过反向代理和 Ingress 控制器的流程。流量被路由到两个 Web 应用 pod（.NET 和 pgAdmin），然后通过 TCP 端口 5432 与一个在独立命名空间中拥有持久化卷的 PostgreSQL 数据库通信。 ## 待办事项列表 一个组织有序且保持更新的待办事项列表（backlog）也构成了项目临时文档的一部分。 它允许团队成员和业务利益相关者跟踪项目进度，并了解还剩下什么工作要做。按功能领域分解有助于根据优先级组织工作，以交付所需的功能。 在休假之前，最初的 Tech Lead 已经进行了一些 backlog 整理，从而为团队从滑雪假期回来后要做的工作做好了准备。最初的动机是为了减轻他休假归来时的精神负担，但在这种情况下，它还有两个额外的好处： - 对于开发团队来说，可以继续不间断地处理项目。 - 对于新的 Tech Lead 来说，可以清楚地了解还剩下什么工作要做。 ## 结论 当然，我们不会故意伤害我们的同事来测试我们的应变能力。不用，他们自己去滑雪，不需要任何激励。 在这种情况下，虽然特殊，但并非罕见，所有这些文档来源的可获得性使得现场替换成为可能。 对于全新的 Tech Lead 来说，花了一天时间就能掌握项目中最重要的元素。对于团队来说，由于 backlog 已经准备就绪，开发可以在新 Tech Lead 的适应期继续推进。 文档形式的多样性，加上自动化元素和不错的软件质量，使得在不利条件下也能交接项目。尽管负责项目的人员突然离职，但进度没有中断。 因此，项目按原计划继续进行，没有中断，因为相关概念并未仅仅保留在 Tech Lead 的头脑中。它们被共享并以书面形式保存下来。正是这些共同构建并以文档形式发布的内容，提供了让项目能够超越人员变动的弹性。 然而，构建文档是一项吃力不讨好的工作，因为它永远不可能完全详尽。它必须由其他信息来源（如测试、backlog、脚本等）补充。这是团队在构建共同知识遗产方面协作努力的结果。 我们的目标始终是移交“钥匙”，为此，文档是必要的，但还不够。在构建应用程序时投入的精力——通过严谨的设计和清晰组织的代码——也有助于提高解决方案的质量和易于转移性。 因此，实施基于协作和知识共享的开发实践，使我们能够在任何时候移交应用程序遗产——无论是在项目结束时，还是在发生滑雪事故时。