01. 课程介绍与第一个接口

1. 课程简介

FastAPI 是一个用于开发 Web API 的 Python 框架。Web API 可以理解为通过网络调用的接口：客户端发送请求，服务端根据请求执行代码，再返回处理结果。

本课程从接口开发的基本概念开始，逐步学习路由、参数、数据校验、响应、异常处理和数据库操作。后续使用 SQLAlchemy 连接 MySQL，围绕商品与商品分类完成增删改查、搜索和分页，并学习查询商品所属分类、统计分类商品数量等联表操作。

本节先准备 Python 开发环境，编写一个返回 JSON 数据的接口，再通过浏览器和接口文档调用它。

2. 适合人群

本课程适合具备 Python 基础、希望开始学习后端接口开发的学习者，不要求已有 FastAPI 或 Web 开发经验。

开始之前，需要能够理解以下 Python 内容：

• 变量、字符串、列表和字典。
• 条件判断与循环。
• 函数定义、参数与返回值。
• 类和对象的基本概念。
• 模块导入与异常处理。

课程名称中的“零基础”指 FastAPI 和接口开发零基础。类型注解、HTTP、数据库与 ORM 等知识将在使用时介绍。

3. 技术栈

本节只安装运行 FastAPI 所需的依赖，数据库相关工具在对应章节再准备。接口调用使用浏览器和 FastAPI 自带的交互式文档。

4. 请求与响应的基本概念

4.1 客户端与服务端

客户端发起请求，服务端处理请求并返回响应。浏览器、手机应用，以及发送 HTTP 请求的 Python 程序，都可以作为客户端。

本节的客户端是浏览器，服务端是本机启动的 FastAPI 应用。

以本节稍后编写的 /hello 接口为例，一次请求与响应的过程如下：

sequenceDiagram
    participant B as 浏览器（客户端）
    participant U as Uvicorn
    participant F as FastAPI 应用
    B->>U: GET /hello
    U->>F: 将请求交给应用
    F->>F: 匹配路由并调用 hello()
    F-->>U: 返回 JSON 响应
    U-->>B: HTTP 200 + JSON 数据

Uvicorn 负责接收网络请求并将其交给应用。FastAPI 负责匹配接口、调用处理函数，并将函数返回的字典转换为 JSON 响应。浏览器通过 HTTP 请求触发服务端的处理函数，再接收返回结果。

4.2 URL、请求方法与路径

假设访问下面的地址：

http://127.0.0.1:8000/hello

直接在浏览器地址栏输入地址并访问，通常发送 GET 请求。GET 用于读取数据，后续新增、修改、删除操作会使用其他请求方法。

服务端需要结合请求方法和路径寻找处理函数。把某个方法、路径与处理函数关联起来的配置，称为路由。

4.3 JSON 数据

JSON 是接口中常用的数据交换格式。例如：

{
  "message": "FastAPI Service is Running"
}

它看起来像 Python 字典，但两者属于不同的表示方式。Python 字典是程序中的对象，JSON 是用于传输或保存的数据格式。JSON 的对象键使用双引号，布尔值使用 true、false，空值使用 null。

5. 软件安装与开发环境配置

以下步骤以 Windows 10/11 和 PowerShell 为例。已经安装相应软件的学习者可以直接检查版本，再继续项目配置。

5.1 安装 Python

Python 解释器负责执行代码，需要单独安装。VS Code 和 Python 扩展不能代替解释器。

本课程采用 Python 3.14.8。打开该版本的发布页面，在 Files 列表中选择安装程序。普通 Intel/AMD 的 64 位电脑选择 Windows installer (64-bit)，ARM 电脑选择 ARM64 安装程序。

也可以直接点击安装 exe：https://www.python.org/ftp/python/3.14.8/python-3.14.8-amd64.exe

使用传统 Windows 安装程序时，按以下步骤操作：

1. 运行下载的安装程序。
2. 勾选 Add python.exe to PATH，使终端可以通过 python 命令找到解释器。
3. 点击 Install Now，按提示完成安装。
4. 关闭安装前已经打开的终端，再重新打开 PowerShell。

在新的终端执行：

python --version
pip --version

第一条命令应显示 Python 3.14.8；第二条命令应显示 pip 的版本及安装位置。pip 用于安装 Python 第三方依赖。安装及使用说明可参考 在 Windows 上使用 Python（官方中文）。

如果输入 python 后找不到命令或打开 Microsoft Store，先确认安装时是否勾选 PATH，并重新打开终端。如果电脑已有多个 Python 版本，需要确认本节使用的是 Python 3.14.8，再创建虚拟环境。

配置 pip 的国内镜像：

在文件资源管理器地址栏输入 %AppData%，打开后新建 pip 文件夹（已存在则直接打开）。在 %AppData%/pip 中新建 pip.ini，写入：

[global]
index-url=https://mirrors.aliyun.com/pypi/simple

保存后，在终端执行以下命令，检查 pip 读取到的镜像配置：

python -m pip config get global.index-url

应输出：

https://mirrors.aliyun.com/pypi/simple

如果提示配置项不存在，检查文件是否保存为 %AppData%/pip/pip.ini，而不是 pip.ini.txt。该命令用于验证配置读取，不会安装依赖；后续安装时会使用镜像地址。

5.2 安装 VS Code

VS Code 用于编辑代码、管理文件和打开终端。

1. 打开 VS Code 下载页面，选择对应电脑架构的 Windows 安装程序。
2. 普通个人电脑可使用 User Installer，按安装向导完成安装。
3. 如果安装向导提供 Add to PATH 选项，保持勾选，便于后续使用 code 命令打开项目。
4. 安装完成后启动 VS Code。

5.3 安装 Python 开发扩展

在 VS Code 中按 Ctrl+Shift+X 打开扩展面板，搜索并安装以下扩展，确认发布者为 Microsoft：

Python 扩展可能自动安装关联扩展；已经存在时无需重复安装。Python、编辑器与扩展之间的分工可参考 VS Code Python 入门文档（英文）。

设置Python自动导包和格式化校验，打开 UserSettings 写入配置：

{
  "python.analysis.autoImportCompletions": true,
  "python.languageServer": "Pylance",
  "[python]": {
    "editor.tabSize": 4,  
    "editor.codeActionsOnSave": {
      "source.organizeImports": "explicit",
      "source.fixAll": "explicit"
    },
    "editor.defaultFormatter": "ms-python.black-formatter"
  },
}

5.4 创建并打开项目

在 本地磁盘新建 fastapi-demo 工程文件夹，例如 D:\Course\ fastapi-demo。

在 VS Code 中选择 File > Open Folder（文件 > 打开文件夹），打开刚创建的 fastapi-demo 文件夹。左侧资源管理器的顶层目录应是 fastapi-demo，后续文件都在这个项目中创建。

按 Ctrl+Shift+P 打开命令面板，执行 Terminal: Select Default Profile，选择 PowerShell。再通过 Terminal > New Terminal（终端 > 新建终端）打开终端，确认当前目录是 fastapi-demo。

后续命令均在 VS Code 的 PowerShell 终端中执行，工作目录保持为 fastapi-demo 项目根目录。

5.5 创建虚拟环境

python -m venv .venv

虚拟环境为当前项目提供独立的 Python 解释器和依赖目录，避免不同项目的依赖混在一起。

创建后，项目中会出现 .venv 目录。接下来直接使用该目录中的 Python 安装依赖和运行程序，因此无需先执行激活脚本。

5.6 安装 FastAPI

FastAPI 的官方中文文档包含框架介绍、安装说明和完整教程。学习过程中，可以通过文档查阅参数用法和代码示例。本节先安装 FastAPI，后续结合具体功能逐步阅读相关章节。

在项目根目录新建 requirements.txt，写入本节使用的依赖及版本：

fastapi[standard]==0.124.4

==0.124.4 表示固定 FastAPI 版本。本节采用示例代码已验证的版本；后续新增依赖时，继续在这个文件中填写对应的版本。

再在项目根目录的终端执行 下面的指令激活虚拟环境：

 .\.venv\Scripts\Activate.ps1

左侧出现绿色的的 (.venv) 表示当前的虚拟环境已激活

pip install -r requirements.txt

fastapi[standard] 安装 FastAPI 及其标准可选依赖，其中包含运行服务所需的 Uvicorn。-m pip 表示使用当前指定的 Python 执行 pip，确保依赖安装到项目虚拟环境；-r requirements.txt 表示从文件读取依赖列表并安装。

本节文件创建完成后的项目结构如下：

fastapi-demo/
├── .venv/
├── requirements.txt
└── app/
    ├── __init__.py
    └── main.py

app 目录及其中的文件在下一步新建，用于存放应用代码；requirements.txt 保留在项目根目录。虚拟环境的创建和使用方式可参考 FastAPI 虚拟环境文档（官方中文）。安装完成后，后续编辑 app/main.py 时，from fastapi import FastAPI 应能正常识别；如果仍有无法解析导入的提示，重新检查所选解释器。

6. 编写第一个接口

6.1 创建应用与路由

在项目根目录新建 app 文件夹，在其中创建空文件 __init__.py，将该目录明确标记为 Python 包。再新建 app/main.py，写入以下完整代码：

from fastapi import FastAPI

# 创建应用对象，后续通过 app 注册接口。
app = FastAPI()

# 将 GET 方法和根路径 / 关联到下面的函数。
@app.get("/")
def root():
    """不接收参数，返回服务运行中的字典数据"""
    return {"message": "FastAPI Service is Running"}

这段代码包含三个步骤：

1. from fastapi import FastAPI：导入创建应用所需的类。
2. app = FastAPI()：创建应用对象。启动服务时，需要指定这个对象。
3. @app.get("/")：注册 GET 请求的根路径，匹配的请求由 root 函数处理。

@app.get("/") 是装饰器写法。此处先理解为给函数登记一个接口入口：客户端请求 GET / 时，FastAPI 会调用它。函数名 root 不决定访问路径，路径由装饰器中的 "/" 决定。

root 是普通 Python 函数，返回一个字典。FastAPI 会把返回值转换为 JSON 响应。入门阶段先使用 def 编写接口，异步函数在后续相关内容中再介绍。

6.2 启动服务

确认终端位于 fastapi-demo 项目根目录，不要切换到 app 目录，执行：

.\.venv\Scripts\python.exe -m uvicorn app.main:app --reload

app.main:app 表示“从 app 包的 main 模块中取出 app 对象”。冒号左侧的 app 是包名，右侧的 app 是代码中创建的 FastAPI 应用对象，两者作用不同。如果目录、文件名或变量名改变，启动参数也需要相应调整。

简写技巧： 如果需要在同一个终端多次执行命令，可以先激活虚拟环境，再直接使用 uvicorn。在项目根目录执行下面两条命令；与前面的完整命令任选一种方式即可。

.\.venv\Scripts\Activate.ps1
uvicorn app.main:app --reload

激活成功后，终端提示符通常会出现 (.venv)，当前终端会优先查找虚拟环境中的命令。因此也可以写成 python -m uvicorn app.main:app --reload。这些简写的前提是当前终端已激活项目虚拟环境，且环境中已安装 Uvicorn；仅在 VS Code 中选择解释器，不等于手动打开的每个终端都已激活。

如果 PowerShell 提示不允许执行激活脚本，继续使用前面的完整命令即可。停止服务后，可执行 deactivate 退出虚拟环境；新建终端时需要重新确认激活状态。

启动成功后，终端会显示服务地址 http://127.0.0.1:8000。保持终端运行，在浏览器打开该地址，应得到：

{
  "message": "FastAPI Service is Running"
}

浏览器的排版可能不同，但 message 字段及其值应一致。接口没有返回 HTML 页面，因此看到的是 JSON 数据。

6.3 增加第二个路径

在 app/main.py 末尾追加以下代码：

@app.get("/hello")
def hello():
    """不接收参数，返回包含中文问候的字典。"""
    return {"message": "你好，FastAPI"}

保存后，等待开发服务完成重新加载，访问 http://127.0.0.1:8000/hello，应得到：

{
  "message": "你好，FastAPI"
}

现在应用中有两个 GET 接口，分别对应 / 和 /hello。访问不同路径，会调用不同的处理函数。

下面的图展示这两个接口如何匹配请求。图中只讨论 GET 请求；完整的路由匹配同时考虑请求方法和路径。

flowchart TD
    A["收到 GET 请求"] --> B{"请求路径"}
    B -->|/| C["调用 root()"]
    B -->|/hello| D["调用 hello()"]
    B -->|未注册的路径| E["返回 404"]
    C --> F["返回服务运行消息"]
    D --> G["返回中文问候"]

@app.get("/hello") 将 GET 方法、/hello 路径与 hello 函数关联起来。即使将函数改名，只要装饰器中的方法和路径不变，接口的访问地址就不变。图中的未注册路径指应用没有对应入口的路径，例如 /products。

7. 使用交互式接口文档

保持服务运行，在浏览器打开：

http://127.0.0.1:8000/docs

FastAPI 默认提供基于 Swagger UI 的交互式文档。当前页面应列出 GET / 和 GET /hello。接口和文档的基本行为可参考 FastAPI 第一个接口文档（官方中文）。

调用 /hello 的步骤如下：

1. 展开 GET /hello。
2. 点击 Try it out。
3. 点击 Execute。
4. 查看 Server response 中的状态码和响应体。

正确调用后，状态码应为 200，响应体包含中文问候。状态码用于表示请求处理结果，200 表示本次请求成功。

接口文档本身也是客户端，点击执行后会实际向正在运行的服务发送 HTTP 请求。后续需要提交 JSON 数据时，可以继续通过这个页面操作。

8. 常见问题

8.1 提示找不到 FastAPI 或 Uvicorn

优先确认安装依赖和启动服务时使用的是否都是 .venv\Scripts\python.exe。系统 Python 与项目虚拟环境可能安装了不同的依赖。

8.2 提示无法导入 app.main 模块

确认项目根目录中存在 app/main.py 和空的 app/__init__.py，终端位于 fastapi-demo 项目根目录，代码中的应用对象名为 app。本节的启动参数应为 app.main:app。

8.3 端口已经被占用

如果此前已经启动同一服务，可以在对应终端按 Ctrl+C 停止它。如果需要同时运行另一个服务，可以选择未占用的端口，例如 8001：

.\.venv\Scripts\python.exe -m uvicorn app.main:app --reload --port 8001

此时访问地址也应改为 http://127.0.0.1:8001，文档地址为 http://127.0.0.1:8001/docs。

8.4 访问路径后返回 404

本节只注册了 / 和 /hello。如果访问 /products，会得到 404 和 Not Found 提示，因为当前还没有该路径对应的接口。

8.5 修改后没有看到新内容

确认文件已保存，服务使用了 --reload，且终端没有显示代码错误。重新加载完成后，再刷新浏览器。

如果 /docs 中的界面资源没有正常加载，而普通接口可以访问，可检查浏览器对文档页面外部静态资源的网络访问情况。

9. 本节检查

完成本节后，应能够确认以下结果：

• 项目使用独立的 .venv 虚拟环境。
• Python 和 VS Code 已安装，VS Code 已选择项目虚拟环境，并配置 Python 扩展、PowerShell 终端与保存时格式化。
• app/main.py 中包含 app 对象和两个 GET 接口。
• 访问 / 和 /hello 可以得到对应的 JSON 数据。
• 在 /docs 中能够调用接口，看到 200 状态码和响应体。
• 能解释 app.main:app、@app.get() 和字典返回值分别起什么作用。

停止服务时，在运行 Uvicorn 的终端按 Ctrl+C。下一节在当前项目中继续学习路径参数、查询参数和类型校验。