尝试以扩展 VS Code 中的代理模式!

在 Visual Studio Code 中学习 Flask 教程

Flask 是一个用于 Web 应用程序的轻量级 Python 框架,它提供了 URL 路由和页面渲染的基础功能。

Flask 被称为“微”框架,因为它不直接提供表单验证、数据库抽象、身份验证等功能。这些功能由称为 Flask 扩展的特殊 Python 包提供。这些扩展与 Flask 无缝集成,看起来就像是 Flask 本身的一部分。例如,Flask 不提供页面模板引擎,但安装 Flask 默认包含了 Jinja 模板引擎。为方便起见,我们通常将这些默认项视为 Flask 的一部分。

在本 Flask 教程中,您将创建一个简单的 Flask 应用,该应用包含三个页面,它们使用一个通用的基础模板。在此过程中,您将体验 Visual Studio Code 的许多功能,包括使用终端、编辑器、调试器、代码片段等。

本 Flask 教程的完整代码项目可以在 GitHub 上找到:python-sample-vscode-flask-tutorial

如果你有任何问题,可以在 Python 扩展讨论问答中搜索答案或提问。

先决条件

要成功完成本 Flask 教程,您必须完成以下操作(这些步骤与通用 Python 教程中的步骤相同):

  1. 安装 Python 扩展

  2. 安装一个 Python 3 版本(本教程是为此版本编写的)。选项包括:

    • (所有操作系统)从 python.org 下载;通常使用页面上首先出现的下载按钮。
    • (Linux)内置的 Python 3 安装效果很好,但要安装其他 Python 包,您必须在终端中运行 sudo apt install python3-pip
    • (macOS)通过 macOS 上的 Homebrew 安装,使用 brew install python3
    • (所有操作系统)从 Anaconda 下载(用于数据科学目的)。
  3. 在 Windows 上,请确保您的 Python 解释器位置已包含在您的 PATH 环境变量中。您可以通过在命令提示符下运行 path 来检查该位置。如果 Python 解释器的文件夹未包含在内,请打开 Windows 设置,搜索“环境”,选择为您的帐户编辑环境变量,然后编辑 Path 变量以包含该文件夹。

为 Flask 教程创建项目环境

在本节中,您将创建一个虚拟环境,并在其中安装 Flask。使用虚拟环境可以避免将 Flask 安装到全局 Python 环境中,并让您精确控制应用程序中使用的库。

  1. 在您的文件系统上,为此教程创建一个文件夹,例如 hello_flask

  2. 在 VS Code 中打开此文件夹,方法是在终端中导航到该文件夹并运行 code .,或者运行 VS Code 并使用文件 > 打开文件夹命令。

  3. 在 VS Code 中,打开命令面板(查看 > 命令面板 或 (⇧⌘P (Windows, Linux Ctrl+Shift+P)))。然后选择 Python: Create Environment 命令,在您的工作区中创建一个虚拟环境。选择 venv,然后选择您想要用来创建它的 Python 环境。

    注意:如果您想手动创建环境,或在环境创建过程中遇到错误,请访问环境页面。

    Flask tutorial: opening the Command Palette in VS Code

  4. 虚拟环境创建完成后,从命令面板运行 终端:创建新终端 (⌃⇧` (Windows, Linux Ctrl+Shift+`))),这将创建一个终端并自动激活虚拟环境(通过运行其激活脚本)。

    注意:在 Windows 上,如果您的默认终端类型是 PowerShell,您可能会看到一个错误,提示无法运行 activate.ps1,因为系统禁用了脚本运行。该错误提供了一个链接,说明如何允许脚本。否则,请使用终端:选择默认配置文件将“命令提示符”或“Git Bash”设置为您的默认终端。

  5. 在 VS Code 终端中运行以下命令,在虚拟环境中安装 Flask:

    python -m pip install flask
    

现在您有了一个自包含的环境,可以编写 Flask 代码了。当您使用终端:创建新终端时,VS Code 会自动激活该环境。如果您打开一个单独的命令提示符或终端,请通过运行 source .venv/bin/activate (Linux/macOS) 或 .venv\Scripts\Activate.ps1 (Windows) 来激活环境。当命令提示符的开头显示 (.venv) 时,您就知道环境已激活。

创建并运行一个最小的 Flask 应用

  1. 在 VS Code 中,在您的项目文件夹中创建一个名为 app.py 的新文件,可以使用菜单中的文件 > 新建,按 Ctrl+N,或使用资源管理器视图中的新建文件图标(如下所示)。

    Flask tutorial: new file icon in Explorer View

  2. app.py 中,添加代码以导入 Flask 并创建 Flask 对象的实例。如果您键入以下代码(而不是使用复制粘贴),您可以观察到 VS Code 的 IntelliSense 和自动补全功能:

    from flask import Flask
    app = Flask(__name__)
    
  3. 同样在 app.py 中,添加一个返回内容的函数,在本例中是一个简单的字符串,并使用 Flask 的 app.route 装饰器将 URL 路由 / 映射到该函数:

    @app.route("/")
    def home():
        return "Hello, Flask!"
    

    提示:您可以在同一个函数上使用多个装饰器,每行一个,具体取决于您希望将多少个不同的路由映射到同一个函数。

  4. 保存 app.py 文件 (⌘S (Windows, Linux Ctrl+S))。

  5. 在集成终端中,通过输入 python -m flask run 来运行应用,这将启动 Flask 开发服务器。开发服务器默认会查找 app.py。当您运行 Flask 时,您应该看到类似以下的输出:

    (.venv) D:\py\\hello_flask>python -m flask run
     * Environment: production
       WARNING: Do not use the development server in a production environment.
       Use a production WSGI server instead.
     * Debug mode: off
     * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
    

    如果您看到一个错误,提示找不到 Flask 模块,请确保您已在虚拟环境中运行了 python -m pip install flask,如上一节末尾所述。

    此外,如果您想在不同的 IP 地址或端口上运行开发服务器,请使用 host 和 port 命令行参数,例如 --host=0.0.0.0 --port=80

  6. 要打开您的默认浏览器并访问渲染的页面,请在终端中按住 Ctrl 并单击 http://127.0.0.1:5000/ URL。

    Flask tutorial: the running app in a browser

  7. 请注意,当您访问像 / 这样的 URL 时,调试终端中会出现一条消息,显示 HTTP 请求:

    127.0.0.1 - - [11/Jul/2018 08:40:15] "GET / HTTP/1.1" 200 -
    
  8. 在终端中使用 Ctrl+C 停止应用。

提示:当使用不同于 app.py 的文件名时,例如 webapp.py,您需要定义一个名为 FLASK_APP 的环境变量,并将其值设置为您选择的文件。然后,Flask 的开发服务器会使用 FLASK_APP 的值,而不是默认文件 app.py。更多信息,请参阅 Flask 命令行界面

在调试器中运行应用

调试使您有机会在程序的特定代码行暂停运行。当程序暂停时,您可以检查变量,在“调试控制台”面板中运行代码,以及利用调试页面上描述的其他功能。运行调试器还会在调试会话开始前自动保存任何已修改的文件。

开始之前:请确保您已在上一节末尾通过在终端中使用 Ctrl+C 停止了正在运行的应用。如果您将应用留在一个终端中运行,它将继续占用该端口。因此,当您使用相同的端口在调试器中运行应用时,原始运行的应用会处理所有请求,您将不会在被调试的应用中看到任何活动,并且程序不会在断点处停止。换句话说,如果调试器似乎不起作用,请确保没有其他应用实例仍在运行。

  1. app.py 的内容替换为以下代码,它增加了一个新的路由和函数,您可以在调试器中单步执行:

    import re
    from datetime import datetime
    
    from flask import Flask
    
    app = Flask(__name__)
    
    
    @app.route("/")
    def home():
        return "Hello, Flask!"
    
    
    @app.route("/hello/<name>")
    def hello_there(name):
        now = datetime.now()
        formatted_now = now.strftime("%A, %d %B, %Y at %X")
    
        # Filter the name argument to letters only using regular expressions. URL arguments
        # can contain arbitrary text, so we restrict to safe characters only.
        match_object = re.match("[a-zA-Z]+", name)
    
        if match_object:
            clean_name = match_object.group(0)
        else:
            clean_name = "Friend"
    
        content = "Hello there, " + clean_name + "! It's " + formatted_now
        return content
    

    用于新 URL 路由 /hello/<name> 的装饰器定义了一个 /hello/ 端点,可以接受任何附加值。路由中 <> 内的标识符定义了一个变量,该变量会传递给函数,并可以在您的代码中使用。

    URL 路由是区分大小写的。例如,路由 /hello/<name>/Hello/<name> 是不同的。如果您希望同一个函数处理这两种情况,请为每种变体使用装饰器。

    如代码注释中所述,始终要过滤任意用户提供的信息,以避免对您的应用进行各种攻击。在这种情况下,代码将 name 参数过滤为只包含字母,从而避免了控制字符、HTML 等的注入。(当您在下一节中使用模板时,Flask 会进行自动过滤,您将不需要这段代码。)

  2. hello_there 函数的第一行代码(now = datetime.now())设置一个断点,可以通过以下任何一种方式:

    • 将光标放在该行上,按 F9,或者,
    • 将光标放在该行上,选择运行 > 切换断点菜单命令,或者,
    • 直接点击行号左侧的空白处(悬停时会出现一个褪色的红点)。

    断点在左边距显示为一个红点:

    Flask tutorial: a breakpoint set on the first line of the hello_there function

  3. 切换到 VS Code 中的运行和调试视图(使用左侧活动栏或 ⇧⌘D (Windows, Linux Ctrl+Shift+D))。您可能会看到消息“要自定义运行和调试,请创建 launch.json 文件”。这意味着您还没有一个包含调试配置的 launch.json 文件。如果您点击创建 launch.json 文件链接,VS Code 可以为您创建它:

    Flask tutorial: initial view of the debug panel

  4. 选择该链接,VS Code 将提示您选择调试配置。从下拉列表中选择 Flask,VS Code 将用 Flask 运行配置填充一个新的 launch.json 文件。launch.json 文件包含多个调试配置,每个都是 configuration 数组中的一个独立的 JSON 对象。

  5. 向下滚动并检查名为“Python: Flask”的配置。此配置包含 "module": "flask",,它告诉 VS Code 在启动调试器时使用 -m flask 运行 Python。它还在 env 属性中定义了 FLASK_APP 环境变量,以标识启动文件,默认为 app.py,但允许您轻松指定不同的文件。如果您想更改主机和/或端口,可以使用 args 数组。

    {
        "name": "Python Debugger: Flask",
        "type": "debugpy",
        "request": "launch",
        "module": "flask",
        "env": {
            "FLASK_APP": "app.py",
            "FLASK_DEBUG": "1"
        },
        "args": [
            "run",
            "--no-debugger",
            "--no-reload"
        ],
        "jinja": true,
        "justMyCode": true
    },
    

    注意:如果您配置中的 env 条目包含 "FLASK_APP": "${workspaceFolder}/app.py",请将其更改为 "FLASK_APP": "app.py",如上所示。否则,您可能会遇到类似“无法导入模块 C”的错误消息,其中 C 是您项目文件夹所在的驱动器号。

    注意:一旦创建了 launch.json,编辑器中会出现一个添加配置按钮。该按钮会显示一个要添加到配置列表开头的附加配置列表。(运行 > 添加配置菜单命令执行相同的操作。)

  6. 保存 launch.json (⌘S (Windows, Linux Ctrl+S))。在调试配置下拉列表中,选择 Python: Flask 配置。

    Flask tutorial: selecting the Flask debugging configuration

  7. 通过选择运行 > 开始调试菜单命令,或选择列表旁边的绿色开始调试箭头 (F5) 来启动调试器。

    Flask tutorial: start debugging/continue arrow on the debug toolbar

    观察状态栏颜色变化以指示正在调试:

    Flask tutorial: appearance of the debugging status bar

    一个调试工具栏(如下所示)也会出现在 VS Code 中,包含以下顺序的命令:暂停(或继续,F5),单步跳过(F10),单步进入(F11),单步跳出(⇧F11 (Windows, Linux Shift+F11)),重启(⇧⌘F5 (Windows, Linux Ctrl+Shift+F5))和停止(⇧F5 (Windows, Linux Shift+F5))。有关每个命令的说明,请参阅 VS Code 调试

    Flask tutorial: the VS Code debug toolbar

  8. 输出出现在一个“Python 调试控制台”终端中。按住 Ctrl 并单击该终端中的 http://127.0.0.1:5000/ 链接,以在浏览器中打开该 URL。在浏览器的地址栏中,导航到 http://127.0.0.1:5000/hello/VSCode。在页面渲染之前,VS Code 会在您设置的断点处暂停程序。断点上的小黄箭头表示这是下一行要运行的代码。

    Flask tutorial: VS Code paused at a breakpoint

  9. 使用“单步跳过”来运行 now = datetime.now() 语句。

  10. 在 VS Code 窗口的左侧,您会看到一个变量窗格,显示局部变量(如 now)以及参数(如 name)。其下方是监视调用堆栈断点窗格(详情请参阅 VS Code 调试)。在局部变量部分,尝试展开不同的值。您还可以双击值(或使用 Enter (Windows, Linux F2))来修改它们。但是,更改像 now 这样的变量可能会破坏程序。开发人员通常只在代码没有产生正确值时进行更改以纠正值。

    Flask tutorial: local variables and arguments in VS Code during debugging

  11. 当程序暂停时,调试控制台面板(与“终端”面板中的“Python 调试控制台”不同)可让您试验表达式并使用程序的当前状态尝试代码片段。例如,一旦您单步跳过了 now = datetime.now() 这一行,您可能会尝试不同的日期/时间格式。在编辑器中,选择读取 now.strftime("%A, %d %B, %Y at %X") 的代码,然后右键单击并选择在调试控制台中求值,将该代码发送到调试控制台,并在其中运行:

    now.strftime("%A, %d %B, %Y at %X")
    'Wednesday, 31 October, 2018 at 18:13:39'
    

    提示调试控制台还会显示应用内部的异常,这些异常可能不会出现在终端中。例如,如果您在运行和调试视图的调用堆栈区域看到“在异常处暂停”的消息,请切换到调试控制台以查看异常消息。

  12. 将该行复制到调试控制台底部的 > 提示符处,并尝试更改格式:

    now.strftime("%a, %d %B, %Y at %X")
    'Wed, 31 October, 2018 at 18:13:39'
    now.strftime("%a, %d %b, %Y at %X")
    'Wed, 31 Oct, 2018 at 18:13:39'
    now.strftime("%a, %d %b, %y at %X")
    'Wed, 31 Oct, 18 at 18:13:39'
    
  13. 如果您愿意,可以再单步执行几行代码,然后选择“继续”(F5)让程序运行。浏览器窗口将显示结果:

    Flask tutorial: result of the modified program

  14. 更改代码中的那一行以使用不同的日期时间格式,例如 now.strftime("%a, %d %b, %y at %X"),然后保存文件。Flask 服务器将自动重新加载,这意味着更改将在无需重启调试器的情况下应用。在浏览器上刷新页面以查看更新。

  15. 完成后,关闭浏览器并停止调试器。要停止调试器,请使用停止工具栏按钮(红色方块)或运行 > 停止调试命令 (⇧F5 (Windows, Linux Shift+F5))。

提示:为了更容易地重复导航到特定 URL,如 http://127.0.0.1:5000/hello/VSCode,可以使用 print 语句输出该 URL。该 URL 会出现在终端中,您可以使用 Ctrl+click 在浏览器中打开它。

转到定义和速览定义命令

在使用 Flask 或任何其他库时,您可能希望检查这些库本身的代码。VS Code 提供了两个方便的命令,可以直接导航到任何代码中类和其他对象的定义:

  • 转到定义从您的代码跳转到定义对象的代码。例如,在 app.py 中,右键单击 Flask 类(在 app = Flask(__name__) 行中),然后选择转到定义(或使用 F12),这将导航到 Flask 库中的类定义。

  • 速览定义 (⌥F12 (Windows Alt+F12, Linux Ctrl+Shift+F10),也在右键上下文菜单中),与此类似,但它直接在编辑器中显示类定义(在编辑器窗口中留出空间以避免遮挡任何代码)。按 Escape 关闭速览窗口或使用右上角的 x

    Flask tutorial: peek definition showing the Flask class inline

使用模板渲染页面

到目前为止,您在本教程中创建的应用仅从 Python 代码生成纯文本网页。虽然可以在代码中直接生成 HTML,但开发人员会避免这种做法,因为它会使应用面临跨站脚本(XSS)攻击的风险。例如,在本教程的 hello_there 函数中,有人可能会想在代码中使用类似 content = "<h1>Hello there, " + clean_name + "!</h1>" 的方式来格式化输出,其中 content 中的结果会直接提供给浏览器。这种开放性允许攻击者在 URL 中放置恶意 HTML(包括 JavaScript 代码),这些代码最终会进入 clean_name,从而在浏览器中运行。

一个更好的做法是完全将 HTML 移出代码,使用模板,这样您的代码只关心数据值,而不关心渲染。

  • 模板是一个 HTML 文件,其中包含代码在运行时提供的值的占位符。模板引擎负责在渲染页面时进行替换。因此,代码只关心数据值,而模板只关心标记。
  • Flask 的默认模板引擎是 Jinja,它在您安装 Flask 时会自动安装。该引擎提供了灵活的选项,包括自动转义(以防止 XSS 攻击)和模板继承。通过继承,您可以定义一个具有通用标记的基础页面,然后在此基础上构建具有页面特定附加内容的其他页面。

在本节中,您将使用模板创建一个单页面。在接下来的部分中,您将配置应用以提供静态文件,然后为应用创建多个页面,每个页面都包含一个来自基础模板的导航栏。

  1. hello_flask 文件夹内,创建一个名为 templates 的文件夹,这是 Flask 默认查找模板的地方。

  2. templates 文件夹中,创建一个名为 hello_there.html 的文件,其内容如下。此模板包含两个名为 "name" 和 "date" 的占位符,由成对的花括号 {{}} 分隔。如您所见,您也可以直接在模板中包含格式化代码:

    <!DOCTYPE html>
    <html>
        <head>
            <meta charset="utf-8" />
            <title>Hello, Flask</title>
        </head>
        <body>
            {%if name %}
                <strong>Hello there, {{ name }}!</strong> It's {{ date.strftime("%A, %d %B, %Y at %X") }}.
            {% else %}
                What's your name? Provide it after /hello/ in the URL.
            {% endif %}
        </body>
    </html>
    

    提示:Flask 开发人员通常使用 flask-babel 扩展进行日期格式化,而不是 strftime,因为 flask-babel 会考虑区域设置和时区。

  3. app.py 中,在文件顶部附近导入 Flask 的 render_template 函数:

    from flask import render_template
    
  4. 同样在 app.py 中,修改 hello_there 函数以使用 render_template 加载模板并应用命名值(并添加一个路由以识别没有名称的情况)。render_template 假定第一个参数相对于 templates 文件夹。通常,开发人员会将模板命名为与使用它们的函数相同,但名称匹配不是必需的,因为您总是在代码中引用确切的文件名。

    @app.route("/hello/")
    @app.route("/hello/<name>")
    def hello_there(name = None):
        return render_template(
            "hello_there.html",
            name=name,
            date=datetime.now()
        )
    

    您可以看到代码现在变得简单得多,只关心数据值,因为标记和格式化都包含在模板中。

  5. 启动程序(在调试器内部或外部,使用 ⌃F5 (Windows, Linux Ctrl+F5)),导航到 /hello/name URL,并观察结果。

  6. 另外,尝试使用像 <a%20value%20that%20could%20be%20HTML> 这样的名称导航到 /hello/name URL,以查看 Flask 的自动转义功能。 "name" 值在浏览器中显示为纯文本,而不是渲染成一个实际的元素。

提供静态文件

静态文件有两种类型。第一种是像样式表这样的文件,页面模板可以直接引用。这类文件可以存放在应用的任何文件夹中,但通常放在 static 文件夹内。

第二种类型是您希望在代码中处理的文件,例如当您想实现一个返回静态文件的 API 端点时。为此,Flask 对象包含一个内置方法 send_static_file,它会生成一个包含应用 static 文件夹内静态文件的响应。

以下各节演示了这两种类型的静态文件。

在模板中引用静态文件

  1. hello_flask 文件夹中,创建一个名为 static 的文件夹。

  2. static 文件夹中,创建一个名为 site.css 的文件,其内容如下。输入此代码后,还可以观察 VS Code 为 CSS 文件提供的语法高亮,包括颜色预览:

    .message {
        font-weight: 600;
        color: blue;
    }
    
  3. templates/hello_there.html 中,在 </head> 标签之前添加以下行,这将创建对样式表的引用。

    <link rel="stylesheet" type="text/css" href="{{ url_for('static', filename='site.css')}}" />
    

    这里使用的 Flask 的 url_for 标签,为文件创建了适当的路径。由于它可以接受变量作为参数,url_for 允许您根据需要以编程方式控制生成的路径。

  4. 同样在 templates/hello_there.html 中,用以下标记替换 <body> 元素的内容,该标记使用 message 样式而不是 <strong> 标签(并且如果您只使用没有名称的 hello/ URL,也会显示一条消息):

    {%if name %}
        <span class="message">Hello there, {{ name }}!</span> It's {{ date.strftime("%A, %d %B, %Y at %X") }}.
    {% else %}
        <span class="message">What's your name? Provide it after /hello/ in the URL.</span>
    {% endif %}
    
  5. 运行应用,导航到 /hello/name URL,并观察到消息以蓝色呈现。完成后停止应用。

从代码提供静态文件

  1. static 文件夹中,创建一个名为 data.json 的 JSON 数据文件,其内容如下(这些是无意义的示例数据):

    {
      "01": {
        "note": "This data is very simple because we're demonstrating only the mechanism."
      }
    }
    
  2. app.py 中,添加一个带有路由 /api/data 的函数,该函数使用 send_static_file 方法返回静态数据文件:

    @app.route("/api/data")
    def get_data():
        return app.send_static_file("data.json")
    
  3. 运行应用并导航到 /api/data 端点,以查看静态文件是否已返回。完成后停止应用。

创建多个扩展基础模板的模板

由于大多数 Web 应用不止一个页面,并且这些页面通常共享许多公共元素,因此开发人员会将这些公共元素分离到一个基础页面模板中,其他页面模板可以扩展该模板(这也称为模板继承)。

此外,由于您可能会创建许多扩展相同模板的页面,因此在 VS Code 中创建一个代码片段会很有帮助,您可以用它快速初始化新的页面模板。代码片段可以避免繁琐且容易出错的复制粘贴操作。

以下各节将逐步介绍此过程的不同部分。

创建基础页面模板和样式

Flask 中的基础页面模板包含一组页面的所有共享部分,包括对 CSS 文件、脚本文件等的引用。基础模板还定义了一个或多个标签,扩展基础模板的其他模板应该覆盖这些标签。块标签在基础模板和扩展模板中都由 {% block <name> %}{% endblock %} 界定。

以下步骤演示了如何创建基础模板。

  1. templates 文件夹中,创建一个名为 layout.html 的文件,其内容如下,其中包含名为“title”和“content”的块。如您所见,该标记定义了一个简单的导航栏结构,其中包含指向主页、关于和联系页面的链接,您将在后面的部分创建这些页面。每个链接再次使用 Flask 的 url_for 标签在运行时为匹配的路由生成链接。

    <!DOCTYPE html>
    <html>
        <head>
            <meta charset="utf-8" />
            <title>{% block title %}{% endblock %}</title>
            <link rel="stylesheet" type="text/css" href="{{ url_for('static', filename='site.css')}}" />
        </head>
    
        <body>
            <div class="navbar">
                <a href="{{ url_for('home') }}" class="navbar-brand">Home</a>
                <a href="{{ url_for('about') }}" class="navbar-item">About</a>
                <a href="{{ url_for('contact') }}" class="navbar-item">Contact</a>
            </div>
    
            <div class="body-content">
                {% block content %}
                {% endblock %}
                <hr/>
                <footer>
                    <p>&copy; 2018</p>
                </footer>
            </div>
        </body>
    </html>
    
  2. 将以下样式添加到 static/site.css 中,位于现有的 "message" 样式下方,然后保存文件。请注意,本演练不试图演示响应式设计;这些样式只是生成一个相当有趣的结果。

    .navbar {
        background-color: lightslategray;
        font-size: 1em;
        font-family: 'Trebuchet MS', 'Lucida Sans Unicode', 'Lucida Grande', 'Lucida Sans', Arial, sans-serif;
        color: white;
        padding: 8px 5px 8px 5px;
    }
    
    .navbar a {
        text-decoration: none;
        color: inherit;
    }
    
    .navbar-brand {
        font-size: 1.2em;
        font-weight: 600;
    }
    
    .navbar-item {
        font-variant: small-caps;
        margin-left: 30px;
    }
    
    .body-content {
        padding: 5px;
        font-family:'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
    }
    

您可以在此时运行该应用,但由于您没有在任何地方使用基础模板,也没有更改任何代码文件,因此结果与上一步相同。完成其余部分以查看最终效果。

创建代码片段

因为您将在下一节中创建的三个页面都扩展了 layout.html,所以创建一个代码片段来初始化一个带有对基础模板正确引用的新模板文件可以节省时间。代码片段从单一来源提供一致的代码片段,避免了从现有代码中复制粘贴时可能引入的错误。

  1. 在 VS Code 中,选择 文件 > 首选项 > 配置用户代码片段

  2. 在出现的列表中,选择 html。如果您之前创建过代码片段,该选项可能会在列表的现有代码片段部分显示为“html.json”。

  3. 在 VS Code 打开 html.json 后,在现有的大括号内添加以下条目(此处未显示的解释性注释描述了细节,例如 $0 行如何指示 VS Code 在插入代码片段后放置光标的位置):

    "Flask Tutorial: template extending layout.html": {
        "prefix": "flextlayout",
        "body": [
            "{% extends \"layout.html\" %}",
            "{% block title %}",
            "$0",
            "{% endblock %}",
            "{% block content %}",
            "{% endblock %}"
        ],
    
        "description": "Boilerplate template that extends layout.html"
    },
    
  4. 保存 html.json 文件 (⌘S (Windows, Linux Ctrl+S))。

  5. 现在,每当您开始键入代码片段的前缀时,例如 flext,VS Code 都会将该代码片段作为自动完成选项提供,如下一节所示。您还可以使用插入代码片段命令从菜单中选择一个代码片段。

有关代码片段的更多信息,请参阅创建代码片段

使用代码片段添加页面

有了代码片段,您就可以快速创建主页、关于和联系页面的模板。

  1. templates 文件夹中,创建一个名为 home.html 的新文件,然后开始输入 flext,您会看到代码片段作为自动补全出现:

    Flask tutorial: autocompletion for the flextlayout code snippet

    当您选择补全时,代码片段的代码会出现,光标位于代码片段的插入点:

    Flask tutorial: insertion of the flextlayout code snippet

  2. 在 "title" 块的插入点处,写入 Home,在 "content" 块中,写入 <p>Visual Studio Code Flask 教程的主页。</p>,然后保存文件。这些行是扩展页面模板中唯一的部分:

  3. templates 文件夹中,创建 about.html,使用代码片段插入样板标记,在“title”和“content”块中分别插入 About us<p>Visual Studio Code Flask 教程的关于页面。</p>,然后保存文件。

  4. 重复上一步,创建 templates/contact.html,在两个内容块中使用 Contact us<p>Visual Studio Code Flask 教程的联系页面。</p>

  5. app.py 中,为 /about/ 和 /contact/ 路由添加函数,这些函数引用它们各自的页面模板。同时修改 home 函数以使用 home.html 模板。

    # Replace the existing home function with the one below
    @app.route("/")
    def home():
        return render_template("home.html")
    
    # New functions
    @app.route("/about/")
    def about():
        return render_template("about.html")
    
    @app.route("/contact/")
    def contact():
        return render_template("contact.html")
    

运行应用

所有页面模板都准备好后,保存 app.py,运行应用,并打开浏览器查看结果。在页面之间导航,以验证页面模板是否正确地扩展了基础模板。

Flask tutorial: app rendering a common nav bar from the base template

注意:如果您没有看到最新的更改,您可能需要对页面进行硬刷新以避免看到缓存的文件。

可选活动

以下各节描述了在使用 Python 和 Visual Studio Code 时可能会有帮助的其他步骤。

为环境创建一个 requirements.txt 文件

当您通过源代码控制或其他方式共享您的应用代码时,复制虚拟环境中的所有文件是没有意义的,因为接收者总是可以自己重新创建环境。

因此,开发人员通常会从源代码控制中省略虚拟环境文件夹,而是使用 requirements.txt 文件来描述应用的依赖项。

虽然您可以手动创建该文件,但您也可以使用 pip freeze 命令根据已激活环境中安装的确切库来生成该文件:

  1. 使用 Python: Select Interpreter 命令选择您想要的环境后,运行 Terminal: Create New Terminal 命令 (⌃⇧` (Windows, Linux Ctrl+Shift+`))) 打开一个已激活该环境的终端。

  2. 在终端中,运行 pip freeze > requirements.txt 在您的项目文件夹中创建 requirements.txt 文件。

任何收到项目副本的人(或任何构建服务器)只需运行 pip install -r requirements.txt 命令即可在原始环境中重新安装软件包。(但是,接收者仍需要创建自己的虚拟环境。)

注意pip freeze 会列出您在当前环境中安装的所有 Python 包,包括您当前未使用的包。该命令还会列出具有确切版本号的包,您可能希望将其转换为范围以获得未来更大的灵活性。有关更多信息,请参阅 pip 命令文档中的需求文件

重构项目以支持进一步开发

在本 Flask 教程中,所有的应用代码都包含在一个 app.py 文件中。为了便于进一步开发和分离关注点,将 app.py 的各个部分重构到不同的文件中是很有帮助的。

  1. 在您的项目文件夹中,为应用创建一个文件夹,例如 hello_app,以将其文件与项目级文件(如 requirements.txt 和 VS Code 存储设置和调试配置文件的 .vscode 文件夹)分开。

  2. statictemplates 文件夹移动到 hello_app 中,因为这些文件夹肯定包含应用代码。

  3. hello_app 文件夹中,创建一个名为 views.py 的文件,其中包含路由和视图函数:

    from flask import Flask
    from flask import render_template
    from datetime import datetime
    from . import app
    
    @app.route("/")
    def home():
        return render_template("home.html")
    
    @app.route("/about/")
    def about():
        return render_template("about.html")
    
    @app.route("/contact/")
    def contact():
        return render_template("contact.html")
    
    @app.route("/hello/")
    @app.route("/hello/<name>")
    def hello_there(name = None):
        return render_template(
            "hello_there.html",
            name=name,
            date=datetime.now()
        )
    
    @app.route("/api/data")
    def get_data():
        return app.send_static_file("data.json")
    
  4. 在 `hello_app` 文件夹中,创建一个名为 `__init__.py` 的文件,内容如下:

    import flask
    app = flask.Flask(__name__)
    
  5. 在 `hello_app` 文件夹中,创建一个名为 `webapp.py` 的文件,内容如下:

    # Entry point for the application.
    from . import app    # For application discovery by the 'flask' command.
    from . import views  # For import side-effects of setting up routes.
    
  6. 打开调试配置文件 launch.json 并更新 env 属性,如下所示,使其指向启动对象:

    "env": {
        "FLASK_APP": "hello_app.webapp"
    },
    
  7. 删除项目根目录下的原始 app.py 文件,因为其内容已移动到其他应用文件中。

  8. 您的项目结构现在应该类似于以下内容:

    Flask tutorial: modified project structure with separate files and folders for parts of the app

  9. 再次在调试器中运行应用,确保一切正常。要在 VS Code 调试器之外运行应用,请在终端中执行以下步骤:

    1. FLASK_APP 设置环境变量。在 Linux 和 macOS 上,使用 export set FLASK_APP=webapp;在 Windows 上,如果您使用 PowerShell,请使用 $env:FLASK_APP=webapp,如果您使用命令提示符,请使用 set FLASK_APP=webapp
    2. 导航到 hello_app 文件夹,然后使用 python -m flask run 启动程序。

使用容器工具扩展为 Flask 应用创建容器

容器工具扩展可以轻松地从 Visual Studio Code 构建、管理和部署容器化应用程序。如果您有兴趣学习如何为本教程中开发的 Flask 应用创建 Python 容器,请查看 容器中的 Python 教程,它将引导您完成如何:

  • 创建一个描述简单 Python 容器的 Dockerfile 文件。
  • 构建、运行并验证 Flask 应用的功能。
  • 调试在容器中运行的应用程序。

如果你有任何问题,可以在 Python 扩展讨论问答中搜索答案或提问。

后续步骤

恭喜您完成在 Visual Studio Code 中使用 Flask 的本演练!

本教程的完整代码项目可以在 GitHub 上找到:python-sample-vscode-flask-tutorial

由于本教程仅涉及页面模板的皮毛,请参阅 Jinja2 文档以获取有关模板的更多信息。模板设计器文档包含了模板语言的所有细节。您可能还想查看官方 Flask 教程以及 Flask 扩展的文档。

要在生产网站上试用您的应用,请查看教程使用 Docker 容器将 Python 应用部署到 Azure 应用服务。Azure 还提供了一个标准容器,即 Linux 上的应用服务,您可以从 VS Code 内部向其部署 Web 应用。

您可能还想查看 VS Code 文档中与 Python 相关的以下文章: