Visual Studio Code 中的 Flask 教程

Flask 是一個輕量級的 Python Web 應用框架，它提供了 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. 在終端中導航到該資料夾，然後執行 `code .` 來在 VS Code 中開啟該資料夾，或者執行 VS Code 並使用“檔案” > “開啟資料夾”命令。

3. 在 VS Code 中，開啟命令面板（“檢視” > “命令面板”或（⇧⌘P (Windows、Linux Ctrl+Shift+P)））。然後選擇“Python: Create Environment”命令來在你的工作區建立虛擬環境。選擇 `venv`，然後選擇要用於建立它的 Python 環境。

   注意：如果你想手動建立環境，或者在環境建立過程中遇到錯誤，請訪問“環境”頁面。

   

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 中，使用“檔案” > “新建”選單、按 Ctrl+N 鍵，或使用資源管理器檢視中的新建檔案圖示（如下所示），在專案資料夾中建立一個名為 `app.py` 的新檔案。

   

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+click 單擊 `http://127.0.0.1:5000/` URL。

   

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/` 使用的裝飾器定義了一個端點 `/hello/`，該端點可以接受任何附加值。路由中 `<` 和 `>` 內的識別符號定義了一個變數，該變數將傳遞給函式並在你的程式碼中使用。

   URL 路由區分大小寫。例如，路由 `/hello/` 與 `/Hello/` 不同。如果你希望同一個函式處理兩者，請為每個變體使用裝飾器。

   如程式碼註釋中所述，始終過濾任意使用者提供的資訊以避免對你的應用進行各種攻擊。在本例中，程式碼會過濾 `name` 引數，使其只包含字母，從而避免注入控制字元、HTML 等。（當你使用下一節中的模板時，Flask 會進行自動過濾，你將不需要這段程式碼。）

2. 在 hello_there 函式的第一行程式碼 (now = datetime.now()) 處設定一個斷點，方法如下任選其一：

   • 將游標放在該行上，按 F9，或者，
   • 將游標放在該行上，選擇執行 > 切換斷點選單命令，或者，
   • 直接點選行號左側的空白處（當滑鼠懸停在那裡時會出現一個褪色的紅點）。

   斷點在左邊距顯示為一個紅點：

   

3. 切換到 VS Code 中的“執行和除錯”檢視（使用左側活動欄或 ⇧⌘D (Windows、Linux Ctrl+Shift+D)）。你可能會看到訊息“To customize Run and Debug create a launch.json file”。這意味著你還沒有包含除錯配置的 `launch.json` 檔案。如果你點選“建立 launch.json 檔案”連結，VS Code 可以為你建立它。

   

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** 配置。

   

7. 透過選擇執行 > 啟動除錯選單命令，或選擇列表旁邊的綠色啟動除錯箭頭 (F5) 來啟動偵錯程式：

   

   觀察狀態列顏色變化，表示正在除錯：

   

   VS Code 中還會出現一個除錯工具欄（如下所示），其中包含按順序排列的命令：暫停（或繼續，F5）、逐過程（F10）、逐語句（F11）、跳出（⇧F11 (Windows、Linux Shift+F11)）、重啟（⇧⌘F5 (Windows、Linux Ctrl+Shift+F5)）和停止（⇧F5 (Windows、Linux Shift+F5)）。請參閱 VS Code 除錯以瞭解每個命令的說明。

   

8. 輸出顯示在“Python 除錯控制檯”終端中。按 Ctrl+click 單擊該終端中的 `http://127.0.0.1:5000/` 連結，在瀏覽器中開啟該 URL。在瀏覽器的位址列中，導航到 `http://127.0.0.1:5000/hello/VSCode`。在頁面渲染之前，VS Code 會在設定的斷點處暫停程式。斷點上的小黃箭頭表示下一行要執行的程式碼。

   

9. 使用“單步跳過”來執行 now = datetime.now() 語句。

10. 在 VS Code 視窗的左側，您會看到一個變數窗格，其中顯示了局部變數（如 now）以及引數（如 name）。其下方是監視、呼叫堆疊和斷點窗格（詳見VS Code 除錯）。在區域性變數部分，嘗試展開不同的值。您還可以雙擊值（或使用 Enter (Windows, Linux F2)）來修改它們。然而，更改像 now 這樣的變數可能會破壞程式。開發人員通常只在程式碼最初沒有產生正確值時才進行更改以糾正值。

    

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) 讓程式執行。瀏覽器視窗將顯示結果：

    

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。

  

使用模板渲染頁面

到目前為止，本教程中建立的應用僅從 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. 嘗試導航到 `/hello/name` URL，使用一個像 `<a%20value%20that%20could%20be%20HTML>` 這樣的名字，以檢視 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` 中，在 `` 標籤之前新增以下行，它建立了一個對樣式表的引用。

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

   這裡使用的 Flask url_for 標籤會建立檔案的正確路徑。由於它可以接受變數作為引數，因此 `url_for` 允許你按需以程式設計方式控制生成的路徑。

4. 同樣在 `templates/hello_there.html` 中，將 `` 元素的內容替換為以下標記，該標記使用 `message` 樣式而不是 `` 標籤（並且當你僅使用不帶名字的 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，並觀察到訊息以藍色呈現。完成後停止應用。