API 第 1 课：看懂接口类型，跑通你的第一个商品查询

打开购物软件，输入商品编号，页面就能显示名字和价格。背后发生了什么？可以先抓住一条线：客户端发送请求，服务端处理请求，再返回响应。 API 就是程序之间约定好的交互方式。

这一课先认识常见接口方案，再把一份商品服务源码运行在你自己的 Windows 电脑上，亲手查询两件商品。你不需要先会写 Python。第二课才从空文件开始，写出自己的 hello 接口。

先画一张地图：这七个名字各管什么

网上经常把下面七项统称为“API 类型”。入门时可以这样认识它们，但要知道：它们处在不同层次，能够组合使用，并不是一道七选一的题。

例如，商品查询可以使用围绕资源设计的 HTTP 接口；订单进度可以通过 SSE 展示；支付结果可以通过 Webhook 通知后台。它们解决不同问题，可以出现在同一个产品中。本课先动手体验最直观的“发出一次查询，收到一次回答”。

请求里的 GET 是什么意思

HTTP 请求方法表达这次请求的意图。先保留下面这张速查表，不必一口气背完。

这张表不是 SQL 对照表。DELETE 不保证数据库某行被物理删除，POST 也不只代表“新增”。HEAD 没有响应正文，但 Content-Length 可以大于 0：如果发送这个字段，它应对应相同 GET 请求本来会返回的正文长度。详细定义见 HTTP 语义标准与 PATCH 标准。

第一步：下载源码，确认 Python

下载第一集商品演示体验包（ZIP）

文件名是 第一集-商品演示体验包-r01.zip，大小为 7917 字节。它包含真实源码和操作说明，不包含 Python 安装器、数据库或虚拟环境。首次安装依赖需要联网。

本教程面向 Windows，使用 Python 3.11。还没有安装时，打开 Python 官方 Windows 下载页，下载并安装 Python install manager（Python 安装管理器）。它负责下载和管理具体的 Python 版本。安装后重新打开 PowerShell，执行：

py install 3.11

无论是刚安装还是以前装过，都必须检查：

py -3.11 --version

只有看到 Python 3.11.x 才继续。x 代表你安装的实际补丁版本，不是要输入的字母。已经检查成功就不用重装。若找不到 py、找不到 3.11，或 py install 不被识别，先阅读包内的 安装Python.txt 和 Python 官方 Windows 说明，核对旧启动器与新安装管理器的区别，再继续。

第二步：全部解压，在正确的文件夹打开终端

在 ZIP 上点右键，选择“全部解压缩”，放到一个容易找到的短目录。不要在压缩包预览窗口里直接运行。

打开解压后的 第一集-商品演示 文件夹。点击这个文件夹窗口顶部的地址栏，输入 powershell，按回车。这里是文件夹地址栏；稍后输入网址时，用的才是浏览器地址栏。

在打开的终端输入：

Get-ChildItem

输出里应该有这四个文件：product_api.py、initialize_once.py、requirements.txt、constraints.txt。另有两份入门说明和清单文件。如果四个文件没找齐，先检查是否多进或少进了一层文件夹。

下面的命令逐条执行，每条成功后再输入下一条；不要把 PS ...> 提示符一起复制进去。

第三步：创建环境，安装依赖

在这个终端执行：

py -3.11 -m venv .venv

没有报错、重新出现提示符后，再检查刚创建的 Python：

.\.venv\Scripts\python.exe --version

也应该显示 Python 3.11.x。.venv 是这个文件夹专用的环境。后面的命令明确使用它，无需激活环境，也无需修改 PowerShell 执行策略。

安装本课依赖：

.\.venv\Scripts\python.exe -m pip install -r requirements.txt -c constraints.txt

等待下载和安装结束、提示符回来，再执行检查：

.\.venv\Scripts\python.exe -m pip check

预期结果是 No broken requirements found.。有报错就先停在这一步，保留完整输出。

第四步：先准备两条商品，再启动服务

第一次运行时，先创建教学数据：

.\.venv\Scripts\python.exe initialize_once.py --yes

首次成功的 JSON 输出中应包含 "passed": true 和 "row_count": 2。文件夹里会生成 products.sqlite3，保存编号 1 和 2 的商品。

顺序很重要：先初始化，再启动。只启动服务不会自动填入两条商品。如果提示数据库已存在、拒绝重复初始化，先核对自己是否做过这一步，保留现有数据库。

然后启动：

.\.venv\Scripts\python.exe -m uvicorn product_api:app --host 127.0.0.1 --port 8004

看到 Application startup complete. 和 Uvicorn running on http://127.0.0.1:8004，并且没有报错退出，才继续。日志顺序可能不同。

此时终端不出现新的提示符是正常的。 服务正在这个窗口里运行。保持窗口打开，先不要按 Ctrl+C。

第五步：打开测试页，真正发送两次请求

打开浏览器，在浏览器顶部地址栏输入：

http://127.0.0.1:8004/docs

127.0.0.1 和常见的 localhost 都指向你自己的电脑。这里访问的是你刚启动的服务，只有你自己的服务运行后才可用。

页面标题应为“第一集独立商品练习”。这是 FastAPI 生成的 Swagger 测试页，无需另装测试软件。

1. 找到 GET /api/products/{id}，点击展开。
2. 点击 Try it out。
3. 在 id 输入框填 1。填写参数还没有发出请求。
4. 点击 Execute，向下查看响应。
5. 核对 Request URL 末尾是 /api/products/1，响应 Code 为 200，正文包含：

{
  "id": 1,
  "name": "示例笔记本",
  "price_cents": 1200,
  "category": "文具"
}

price_cents 的单位是分，1200 分就是 12 元。200 是这次请求成功的 HTTP 状态码，还要结合正文核对是否查到了预期商品。

接着回到 id 输入框，将 1 改成 2，再次点击 Execute。输入框改了，旧响应仍可能留在下方；只有重新发送，才能检查新结果。

这次应看到新的 Request URL 末尾为 /api/products/2，Code 为 200，正文是“示例水杯”，id 为 2，price_cents 为 2800，也就是 28 元。本课先完成查询，页面中的 POST 留到后续学习。

第六步：停止，以及下次怎么用

回到运行服务的终端，实际按一次 Ctrl+C。等到 Application shutdown complete、Finished server process 和 PowerShell 提示符回来，再关闭窗口。

下次进入同一个文件夹，用相同方式打开 PowerShell。只要环境和数据库还在，直接执行第四步的启动命令即可，无需重建环境、重装依赖或再次初始化。

卡住时，先把现场说清楚

不要连续粘贴后续命令。给 AI 或向老师求助时，提供“卡在哪一步、完整命令、完整报错、当前文件夹、Python 版本”，并注明“请先判断原因，保留已有数据库”。发送前去掉密码、令牌和私人文件信息。

路径过长就重新解压到短目录；找不到 py 就先解决 Python 安装和 3.11 检查；8004 端口被占用，就先检查自己是否已经打开了一个服务窗口。不要盲目删除数据库、结束不认识的进程或关闭安全设置。浏览器打不开时，先回终端看服务是否启动成功。

做到哪里，才算这课跟上了

请自己逐项确认：能区分七种方案的大致用途；能找到解压后的源码；能检查 Python、准备环境和数据；能保持服务运行；能发出两次请求，分别读懂笔记本与水杯的结果；能停下服务，并知道下次怎样启动。

再试着回答三个问题：只把编号改成 2，为什么页面仍可能显示笔记本？关掉服务窗口后，本地网址为什么打不开？SSE 与 Webhook 为什么可以出现在同一个系统里？

跟着复制完成一次，还不等于已经独立掌握。 完成上述操作并确认每一步都能跟上，才进入下一课。第二课我们从空文件写 hello，把今天体验过的“请求与响应”变成自己写出的代码。

小注：安装界面与版本显示可能随本机环境变化，以实际版本检查和命令结果为准。体验包 SHA-256：492742b6f914edc39182349252bba6a544d02cc1f02bafbb22954fa8900c3be0。

可选体验：SSE / WebSocket 通信演示

视频里教师提前打开的“通信演示页”，现在也提供独立源码。想亲手点按钮，可以下载下面这份补充包；只想先认识接口方案，也可以继续观看，后续课程会逐步编写这些接口。

下载第一集通信演示补充包 r01（ZIP）

它与前面的商品包分别运行：商品服务继续使用 8004，通信演示使用 8005。补充包不使用数据库，不需要初始化，也不要清空商品包的数据。

从下载到打开通信页

1. 下载后右键 ZIP → 全部解压缩，再打开里面的“第一集-通信演示”文件夹。确认这一层有 communication_api.py、demo.html、requirements.txt 和 constraints.txt。
2. 在文件夹窗口顶部地址栏输入 powershell，按回车。在新开的 PowerShell 输入 Get-ChildItem 并回车，再核对文件名。这个位置与浏览器的网址栏不同。
3. 按下面的顺序，一行一行执行；每条正常结束后再继续。这里沿用商品包的 Python 3.11 安装前提，不需要再换一个 Python 版本。

py -3.11 --version
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe --version
.\.venv\Scripts\python.exe -m pip install -r requirements.txt -c constraints.txt
.\.venv\Scripts\python.exe -m pip check

版本命令应返回 Python 3.11.x。安装需要联网；看到 No broken requirements found. 后，才继续启动。若找不到 Python 或安装报错，保留完整命令、报错、当前目录与版本，可以请 AI 协助排查，不要反复重置商品数据。

1. 仍在这个目录执行整行启动命令：

.\.venv\Scripts\python.exe -m uvicorn communication_api:app --host 127.0.0.1 --port 8005 --no-use-colors

看到 Application startup complete.，并核对运行地址末尾是 :8005。保持这个服务窗口打开；它没有回到普通提示符是正常现象。

1. 打开浏览器，按 Ctrl+L 选中最上方的网址栏，输入完整地址并回车：

http://127.0.0.1:8005/demo

127.0.0.1 指你当前这台电脑自己。要先在本机启动服务，再打开页面；只抄地址不会连到教师的电脑。

你应该看到什么

SSE： 在“2. SSE”栏点一次“开始 AI 分析动画”，四行“开始分析／午饭支出较高／交通支出保持稳定／分析完成”依次到达。它们是预设文字，不是实际调用 AI 分析账本。页面收到第4条后关闭这条 EventSource 接入。

WebSocket： 在“3. WebSocket”栏先点“建立连接”，看到“连接成功”；再点“发送消息”，核对默认文字和回声。不要重连，把输入框改成“谢谢”再发送，应继续追加这条消息和对应回声。这是同一连接的回声实验，尚未实现两个人聊天、聊天室或广播。

下次使用时进入同一目录，直接执行启动命令即可。结束学习时，在通信演示的服务窗口按 Ctrl+C，等退出日志和提示符出现；不需要停止仍在使用的8004商品服务。详细步骤和可选的临时端口网络自检入口都在包内“先看我”说明中。

本补充包：10,204字节；SHA256：34c6ade283d05dc5007e3527555fa0cb6db66743634fea63c98555c0d2cde175。本页的通信演示用于观察第一集的两种交互方式；后续正课再逐步实现、测试并解释相应代码。

学习卡与六道场景练习

下载第一集学习卡与场景题（ZIP）

这份资料对应视频结尾的复盘和独立练习，不需要启动服务。下载完成后，右键 ZIP 选择“全部解压缩”，打开解压后的“学习资料”文件夹：

1. 先打开 第一集学习卡.md，对照交互方案地图和 HTTP 请求方法地图。
2. 打开 handouts/worksheets/EP01-六个场景题.md，先自己写条件、方案和理由。课堂示范 X 不计入六道独立题。
3. 完成后再打开 handouts/answers/EP01-场景题评分参考.md，逐项比较判断依据；48 分只是课程参考分流线，不代替是否真正理解的判断。
4. 技术依据与教学边界.md 汇总技术出处和本集学习范围。Markdown 文件可用已有阅读器查看，也可用记事本打开；文件间的相对链接需在完整解压后使用。

本集先学会从业务条件判断接口方案，并体验商品查询；下一集才从空文件编写 hello。是否每一步都能跟上、能否独立解释选择，需要你实际跟做和作答确认。