教程的问题

2022 年 3 月 8 日，作者：Burke Holland，@burkeholland

编写出色的教程并不容易。我应该知道 - 我写过很多教程，但并非每个都大获成功。

事实证明，制作出色的教程不是关于你写了什么，而是关于开发人员是否可以在不必阅读每个字的情况下取得成功。在本文中，我们将了解开发容器如何减少用户可能遇到的错误，以及 Laravel PHP 项目 如何在其自己的教程中优雅地实现这一点，并取得了巨大的效果。

没人阅读

我们自己关于如何在 Visual Studio Code 中使用开发容器的教程长期以来完成率一直很低 - 大约 4 - 6%。

为了弄清楚人们在哪里放弃，我们进行了用户研究，并观察人们尝试完成我们的教程。这...很痛苦。

人们无法完成本教程的原因立即显而易见：没人阅读它。人们直接跳过说明，直接进入操作步骤。不可避免地，他们会卡住，因为他们犯了一个错误，如果他们阅读了说明，他们就不会犯这个错误。

宾夕法尼亚州立大学教授 John M. Carroll 在他的开创性著作《纽伦堡漏斗 - 为实用计算机技能设计极简主义教学》中谈到了这一点。他写道：“[学习者]太忙于学习，以至于无法充分利用教学。这就是理解的悖论。”

我对此深有体会，您可能也是如此。当我在学习教程时，我的眼睛会扫描代码块，因为我试图通过实践来学习。我真的太忙于学习而无法阅读说明。

人们不会阅读您的教程。或者至少不如您希望的那么多。您能做的最好的事情是尽可能消除读者在学习过程中可能出错的地方。一种方法是使用预配置的容器环境完全删除任何环境设置步骤。

容器化的开发环境

任何教程的很大一部分通常都致力于列出先决条件和环境设置。我清楚地记得尝试学习 Ruby on Rails，并将大部分时间花在尝试在 Windows 上正确安装 Ruby 上 - 想知道“gem”到底是什么，以及为什么它们都莫名其妙地丢失了。

容器化开发环境背后的想法是您在 Docker 容器内部进行开发。这使得拥有一个完全可移植、完全配置的开发环境成为可能，您可以随意启动或关闭它。然后，您可以将该环境作为一组配置文件提供给其他人。

但是如何在容器内部进行开发呢？容器不像具有 UI，您可以在其中启动 VS Code。

VS Code 的 开发容器 扩展正是做到了这一点。它既包含将 Docker 容器配置为开发环境的机制，也允许您从 VS Code 连接到该环境。它通过在容器内安装一个小型服务器组件来实现这一点，您的本地 VS Code 与该组件通信。然后，您像在本地一样进行开发，但 VS Code 连接到容器环境而不是您的本地环境。

为了创建容器化的开发环境，您通常必须了解一些关于 Docker 的知识。很多人都了解，但很多人不了解（你看不到我，但我举手了），因此该扩展尝试尽可能地抽象化容器设置过程。我设置了一个新的 Python 容器。向导引导您选择基础镜像和 Python 版本。然后，它让您有机会通过选择器列表向镜像添加其他软件。在本例中，我添加了 Azure CLI、Dotnet CLI 和 PowerShell……

此过程会将 .devcontainer 文件夹添加到此项目，其中包含必要的 Dockerfile。它还添加了一个 devcontainer.json 文件，这是一个用于定义开发容器各个方面的标准，例如应安装哪些扩展、容器构建后应运行哪些设置命令等。由于您可以完全控制环境及其设置，因此您可以自动化几乎所有内容 - 包括依赖项安装、库版本等。

这样，就完全有可能将一个完整的、随时可用的环境交给某人，而无需额外的设置步骤或因 Ruby gems 引起的生存危机。

有些人已经在使用基于开发容器的方法，以便让他们的用户快速启动并运行通常非常复杂的环境。Laravel PHP 框架就是一个很好的例子。

Laravel 解决方案

Laravel 是一个用于 PHP 的开源 MVC 框架。它是全面的，因为它还包括诸如对象关系映射器 (ORM)、直接数据库访问、打包系统等。Laravel 可以做很多事情。为了体验它，您真的需要在开始时至少有一个数据库。通常，这需要用户不仅安装 PHP，还要安装数据库 - 通常是 MySQL。当用户只是想试用您的框架时，这是一个重要的要求。

Laravel 通过容器化开发环境和一个名为 Sail 的工具来解决这个问题。要从头开始使用 Laravel、MySQL Server 和 Redis Cache，您只需运行一个命令……

    curl -s "https://laravel.build/example-app?with=mysql,redis" | bash

这将创建一个新项目，其中包含 docker-compose 文件。此文件设置了三个容器 - 应用程序容器、MySQL 容器和 Redis 容器。您不必了解任何关于容器或这三个服务的信息。Sail 为您抽象化了所有这些。然后，您执行 Sail 命令来启动环境……

    ./vendor/bin/sail up

示例应用程序只是运行。无需安装 PHP。无需 Laravel。没有依赖项解析步骤。只有立即的成功。

我指定我们的项目具有 MySQL Server 和 Redis Cache，因此当项目启动时，我们实际上得到了三个容器。我们可以使用 VS Code 的 Docker 扩展 看到这一点。

这些容器联网在一起，以便我们可以从应用程序容器调用 MySQL 或 Redis 缓存容器。

如果您将交互式终端连接到 sail-8.1/app 容器，您将在 /var/www/html 文件夹中看到您的项目。Docker 将您机器上的项目“挂载”到容器中，因此您在开发时所做的任何更改都会在您刷新时反映在应用程序中。

添加开发容器

还添加了对 开发容器 扩展的支持。要向此项目添加正确的开发容器配置，您可以搭建相同的项目并添加 &devcontainer 标志。

    curl -s "https://laravel.build/example-app?with=mysql,redis&devcontainer" | bash

请注意，如果您想向现有的 Sail/Laravel 项目添加开发容器，您可以通过运行 php artisan sail:install --devcontainer 来实现。

这将创建相同的项目配置，但将包括一个 .devcontainer 文件夹。VS Code 将自动检测到该文件夹，并提示您在容器中重新打开项目，从而跳过所需的 sail up 步骤。

VS Code 连接到容器，因此您是在容器环境内部而不是本地环境进行开发。您会知道这一点，因为 VS Code 左下角的远程指示器会告诉您……

在容器内部而不是外部进行开发有一些明显的优势。

开发上下文镜像应用程序上下文

连接到容器后，您正在开发的上下文与应用程序运行的上下文相同。因此，您的终端将成为容器的终端……

开发容器扩展还为您提供了更完整的正在发生情况的视图，例如转发了哪些端口 - 以防您忘记应用程序在哪里运行。

Laravel 应用程序自动启动，应用程序日志被管道传输到容器日志。由于您可能想查看应用程序中正在发生的事情，因此开发容器扩展在 VS Code 中提供了一个新视图，您可以在其中查看所有正在运行的容器，以及连接以流式传输容器日志。

自动化开发环境设置

最佳的开发者体验将包括编辑器的自定义设置。这包括编辑器本身的设置，以及需要添加到开箱即用体验中的任何扩展或其他支持。

对于 VS Code 和 Laravel，扩展在 devcontainer.json 中建议，但被注释掉，因此不会自动安装。这允许用户从一组已识别的扩展中进行选择，而不必去寻找配置编辑器的正确方法。

    ...
    "extensions": [
        // "mikestead.dotenv",
        // "amiralizadeh9480.laravel-extra-intellisense",
        // "ryannaddy.laravel-artisan",
        // "onecentlin.laravel5-snippets",
        // "onecentlin.laravel-blade"
    ],

少读多做

人们不阅读。这应该没问题。Laravel 的教程不一定比其他教程短，但重要的是，如果您跳到代码并只运行命令，它就可以工作。开发容器使这成为可能。现在，如果我们能弄清楚如何为我们自己的将 Docker 容器用作 Visual Studio Code 的开发环境 教程制作一个开发容器就好了……

编码愉快！

Burke Holland (@burkeholland)