把想法,变成一个真能调用的接口
前面四个阶段解决了「模型怎么用、Agent 怎么转」,这一阶段解决最后一环:怎么把它变成一个别人(前端、同事、定时任务)能调用的服务。从一次 HTTP 请求的完整旅程开始,到路由、参数校验、异步并发、依赖注入、测试与部署,每章都有可在本机运行的示例,不需要联网、不需要 API 密钥。
按 6 个模块、L1~L5 难度自己测一遍,10 题一组即答即批,适合学完几章之后查漏补缺。 链接:https://myimage.cn/fastapi/
全部章节
第 1 章 Web 服务到底在干什么
1.1 一次请求的完整旅程
你在浏览器里敲下一个网址,到页面显示出来,中间发生了 5 件事:① DNS 把域名解析成 IP;② TCP 建立连接;③ HTTPS 还要再做一次 TLS 握手加密;④ 浏览器按 HTTP 格式发出请求;⑤ 服务器回一段响应。
你写 FastAPI 代码时,只关心第 ④ 步的「收到什么、返回什么」。但把报文抓出来看一眼,会省掉很多困惑 —— 比如「为什么我的 POST 没生效」(多半是请求体没被读全)、「为什么中文乱码」(多半是没设 Content-Type 或 charset)。
import socket
import threading
from http.server import BaseHTTPRequestHandler, HTTPServer
class Hello(BaseHTTPRequestHandler):
"""一个最小的 HTTP 服务:收到 GET 就回一段文本"""
def do_GET(self):
body = b"hello from stdlib http server"
self.send_response(200) # 状态码 200 = 成功
self.send_header("Content-Type", "text/plain; charset=utf-8")
self.send_header("Content-Length", str(len(body)))
self.end_headers() # 空行,表示请求头结束
self.wfile.write(body)
def log_message(self, *args):
pass # 屏蔽默认日志,保持输出干净
# 起一个真实的服务;端口填 0 表示让操作系统分配一个空闲端口
server = HTTPServer(("127.0.0.1", 0), Hello)
port = server.server_address[1]
threading.Thread(target=server.serve_forever, daemon=True).start()
# 用最原始的 socket 手写一个 HTTP 请求,看看协议长什么样
sock = socket.create_connection(("127.0.0.1", port))
sock.sendall(b"GET /hello HTTP/1.1\r\nHost: 127.0.0.1\r\nConnection: close\r\n\r\n")
raw = b""
while True: # 一次 recv 可能只拿到一半,要读到连接关闭为止
chunk = sock.recv(4096)
if not chunk:
break
raw += chunk
raw = raw.decode("utf-8")
sock.close()
server.shutdown()
# 把响应报文拆成三部分:状态行、响应头、响应体
head, _, body = raw.partition("\r\n\r\n")
print("--- 状态行 ---")
print(head.splitlines()[0])
print("--- 响应头(挑两行看)---")
for line in head.splitlines()[1:]:
if line.startswith(("Content-Type:", "Content-Length:")):
print(line)
print("--- 响应体 ---")
print(body)
# 输出:
# --- 状态行 ---
# HTTP/1.0 200 OK
# --- 响应头(挑两行看)---
# Content-Type: text/plain; charset=utf-8
# Content-Length: 29
# --- 响应体 ---
# hello from stdlib http server注意:这个例子只用标准库,不需要装任何东西。它用「裸 socket」而不是 requests,就是为了让 HTTP 的报文结构暴露出来 —— 后面用 FastAPI 时,这些细节都由框架替你处理了。
1.2 方法、路径、状态码:最小词汇表
REST 接口基本就是三样东西的组合:方法(做什么)+ 路径(对谁)+ 状态码(成没成)。
| 方法 | 语义 | 典型用法 |
|---|---|---|
| GET | 读取,不改数据 | 查列表、查详情 |
| POST | 创建 / 触发一件事 | 新建订单、调用一次模型 |
| PUT | 整体替换 | 覆盖一份完整资源 |
| PATCH | 局部修改 | 只改其中几个字段 |
| DELETE | 删除 | 删一条记录 |
| 状态码 | 含义 | 什么时候返回 |
|---|---|---|
| 200 | 成功 | GET / PUT / DELETE 正常完成 |
| 201 | 已创建 | POST 创建成功 |
| 400 | 请求有问题 | 参数格式不对 |
| 401 / 403 | 没登录 / 没权限 | 鉴权失败 |
| 404 | 找不到 | 路径不存在或资源不存在 |
| 422 | 参数校验不过 | FastAPI 的招牌:类型不对、缺必填字段 |
| 429 | 请求太频繁 | 被限流 |
| 500 | 服务器内部错误 | 代码抛了没接住的异常 |
最该记住的一条:400 和 422 都是「客户端的错」,500 才是「服务器的错」。参数没校验就丢给业务代码,最后变成 500,是新手接口最容易犯的错。
1.3 请求体与 JSON:数据怎么传
GET 的参数通常放在 URL 后面(查询字符串),POST 的数据放在请求体里,格式一般是 JSON。关键细节:服务器靠 Content-Length 知道要读多少字节 —— 不按它读,就会出现「字段是空的」「偶尔解析失败」这种玄学问题。
import json
import threading
from http.server import BaseHTTPRequestHandler, HTTPServer
from urllib.request import Request, urlopen
class Echo(BaseHTTPRequestHandler):
"""收到 JSON 就原样回显,并告诉你它被解析成了什么类型"""
def do_POST(self):
length = int(self.headers.get("Content-Length", 0)) # 先拿到要读多少字节
raw = self.rfile.read(length) # 再读满,否则数据是残缺的
data = json.loads(raw.decode("utf-8")) # JSON 文本 -> Python 对象
out = json.dumps({"got": data, "type": type(data).__name__}, ensure_ascii=False)
body = out.encode("utf-8")
self.send_response(200)
self.send_header("Content-Type", "application/json; charset=utf-8")
self.send_header("Content-Length", str(len(body)))
self.end_headers()
self.wfile.write(body)
def log_message(self, *args):
pass
server = HTTPServer(("127.0.0.1", 0), Echo)
threading.Thread(target=server.serve_forever, daemon=True).start()
# 用标准库客户端发一个 JSON 请求
req = Request(
"http://127.0.0.1:%d/echo" % server.server_address[1],
data=json.dumps({"name": "图片工具", "size": 3}).encode("utf-8"),
headers={"Content-Type": "application/json"},
method="POST",
)
with urlopen(req) as resp:
print("状态码:", resp.status)
print("响应:", resp.read().decode("utf-8"))
server.shutdown()
# 输出:
# 状态码: 200
# 响应: {"got": {"name": "图片工具", "size": 3}, "type": "dict"}注意 ensure_ascii=False:不加它,中文会被转义成 \u56fe\u7247,虽然语义一样,但人看不舒服、字节数还变多。
1.4 【本章小结】
| 你学到了什么 | 关键记忆点 |
|---|---|
| 一次请求的旅程 | DNS → TCP → TLS → HTTP 请求 → 响应 |
| HTTP 报文结构 | 状态行 + 头部 + 空行 + 响应体 |
| 方法语义 | GET 读、POST 建、PUT 替、PATCH 改、DELETE 删 |
| 状态码分工 | 4xx 是客户端错,5xx 是服务端错 |
| 读请求体 | 先读 Content-Length,再读满那么多字节 |
| 中文 JSON | ensure_ascii=False |
第 2 章 把函数变成接口
2.1 路由的思路:URL + 方法 → 函数
写接口本质上只有一句话:「某个方法 + 某个路径」对应「一个处理函数」。Web 框架做的事,就是在你写函数的时候,顺手把这个映射关系记下来,收到请求时再查表找到对应函数。
FastAPI 用装饰器来表达这个映射,一个装饰器 = 一条路由:
@app.get("/items") # 收到 GET /items → 调用 list_items()
@app.post("/items") # 收到 POST /items → 调用 create_item()
@app.get("/items/{id}") # 收到 GET /items/7 → 调用 read_item(id=7)
框架内部做的事(伪代码):
路由表 = {("GET", "/items"): list_items, ("POST", "/items"): create_item, ...}
收到请求 -> 查表 -> 找到函数 -> 调用 -> 把返回值序列化成 JSON -> 发回
这是伪代码,不需要运行,只用来说明一件事:装饰器就是「往路由表里加一行」。收到请求时框架查这张表,找到函数、调用、把返回值转成 JSON 发回去。
所以「接口写不出来」通常不是框架难,而是你还没想清楚「有哪些方法、哪些路径、参数从哪来、返回什么」。建议先在纸上写这四行,再动手写代码。
2.2 第一个 FastAPI 服务
FastAPI 的心智模型很简单:一个 FastAPI() 实例 + 若干个装饰器函数 + 一个 uvicorn 进程。装好之后三行就能跑起来。
# 需要先安装:pip install fastapi uvicorn
# 本机未安装 fastapi 时直接运行会报 ModuleNotFoundError: No module named 'fastapi'
from fastapi import FastAPI
app = FastAPI() # 1. 创建一个应用实例,所有路由都挂在它身上
@app.get("/") # 2. 装饰器声明:GET / 这个请求走下面的函数
def read_root():
return {"message": "服务已启动"} # 3. 返回 dict,FastAPI 自动转成 JSON 并设好 Content-Type
# 实测输出(用 TestClient 在进程内发一次 GET /,按终端打印原样记录):
# GET / -> 状态码: 200 响应体: {'message': '服务已启动'}
#
# 浏览器访问 http://127.0.0.1:8000/ 看到的是同一份数据的 JSON 形式:
# {"message":"服务已启动"}运行后你会看到:终端出现 Application startup complete.,浏览器打开 http://127.0.0.1:8000/ 显示 {"message":"服务已启动"}。上面代码里的三行注释对应三件事:建应用 → 声明路由 → 返回字典,你一个 JSON 都没手写,框架全包了。
把上面存成 main.py,然后在终端跑:
uvicorn main:app --reload
# 下面是本机真实启动日志(进程号每台机器不同,不是示意):
# INFO: Will watch for changes in these directories: ['项目目录']
# INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
# INFO: Started reloader process [23540] using StatReload
# INFO: Started server process [16784]
# INFO: Waiting for application startup.
# INFO: Application startup complete.
# 浏览器打开 http://127.0.0.1:8000/ 会看到:
# {"message":"服务已启动"}
上面这段是本机真实启动日志(进程号每台机器不同)。main:app 里的 main 是文件名、app 是变量名,两处名字必须对得上——这是「一启动就 ImportError」的头号原因。--reload 只在开发期用,上线一定要去掉。
两个参数要记牢:
main:app里的main是文件名、app是变量名,两处名字必须对得上,这是「启动就报 ImportError」的头号原因;--reload表示改代码自动重启,开发期一直开着,上线要关掉。
2.3 三种参数:路径参数、查询参数、请求体
这是初学阶段最容易混的地方。判断方法只有一条:看参数在函数签名里的「位置」和「有没有默认值」。
| 参数种类 | 长什么样 | 怎么传 |
|---|---|---|
| 路径参数 | 在路径里用 {} 声明 | /items/7 → 路径里的 7 |
| 查询参数 | 函数参数但没出现在路径里 | /search?q=猫&limit=5 |
| 请求体 | 整个参数是一个 Pydantic 模型 | 请求体里的一段 JSON |
# 需要先安装:pip install fastapi uvicorn
from fastapi import FastAPI
from pydantic import BaseModel, Field
app = FastAPI()
class Item(BaseModel):
"""请求体的「形状声明」:字段名、类型、默认值、取值范围都写清楚"""
name: str = Field(min_length=1) # 必填,至少 1 个字符
count: int = Field(default=1, ge=1, le=100) # 可选,默认 1,范围 1~100
@app.get("/items/{item_id}") # 路径参数
def read_item(item_id: int): # 写了类型,框架就自动帮你校验和转换
return {"item_id": item_id, "type": type(item_id).__name__}
@app.get("/search") # 查询参数
def search(q: str, limit: int = 10): # 没默认值 → 必传;有默认值 → 可选
return {"q": q, "limit": limit}
@app.post("/items") # 请求体
def create_item(item: Item): # 参数是 Pydantic 模型 → 从请求体解析并校验
return {"name": item.name, "count": item.count}
# 实测输出(TestClient 真发请求,按终端打印的状态码 / 响应体原样摘录):
# GET /items/20 -> 200 {'item_id': 20, 'type': 'int'}
# GET /items/abc -> 422 detail: int_parsing, loc: ['path', 'item_id']
# GET /search?q=海报&limit=3 -> 200 {'q': '海报', 'limit': 3}
# GET /search(漏传 q) -> 422 detail: missing, loc: ['query', 'q']
# POST /items {"name":"头像","count":2} -> 200 {'name': '头像', 'count': 2}
# POST /items {"name":"","count":2} -> 422 detail: string_too_short
# POST /items {"name":"头像","count":999} -> 422 detail: less_than_equal
#
# 读法:路径里的 "20" 被自动转成了整数 int(不是字符串);
# 所有不合法的输入都被挡在业务函数之外,统一返回 422,并指出错在哪个字段。小白提示:上面每一行都是本机真发请求得到的结果。最值得看的是
GET /items/20:URL 里的"20"被自动转成了整数int,因为函数签名写了item_id: int。而传abc、漏传q、count超范围,全部被拦在业务函数之外返回422,并精确指出错在哪个字段。这就是「声明即校验」。
写完这三条路由,访问 /docs 你会发现:FastAPI 自动生成了交互式文档,每个接口都能直接点「Try it out」发请求。这是它比同类框架省事最多的地方之一。
2.4 【本章小结】
| 你学到了什么 | 关键记忆点 |
|---|---|
| 路由的本质 | 方法 + 路径 → 一个函数 |
| 三件套 | FastAPI() + 装饰器 + uvicorn |
| 启动命令 | uvicorn main:app --reload |
| 路径参数 | 写在路径的 {} 里 |
| 查询参数 | 函数参数、但不在路径里 |
| 请求体 | 参数是 Pydantic 模型 |
| 自动文档 | 访问 /docs |
第 3 章 参数校验与错误处理
3.1 为什么必须校验
接口是公开的门面:任何人都能往里塞奇怪的东西。少了校验,会出现三种典型故障:
- 类型错:前端传了字符串
"3",代码直接参与乘法得到乱七八糟的结果; - 越界:传了
count=-1或size=999999,直接把服务压垮; - 缺字段:传了
{},代码data["name"]直接抛 KeyError,最后变成 500。
校验的本质是把「不确定的外部输入」在入口处挡掉,转换成「确定的内部数据」。这是所有 Web 框架都内置它的原因。
def validate_age(age):
"""校验年龄:必须是整数,且落在允许区间内。返回 (是否通过, 说明)"""
if isinstance(age, bool) or not isinstance(age, int):
# 注意:Python 里 bool 是 int 的子类,True 会被当成 1,这里要单独挡掉
return False, "age 必须是整数"
if not 0 < age <= 150:
return False, "age 必须在 1~150 之间"
return True, "ok"
for value in [20, "20", True, 0, 200]:
ok, msg = validate_age(value)
print(f"{value!r:>7} -> {'通过' if ok else '拒绝'}({msg})")
# 输出:
# 20 -> 通过(ok)
# '20' -> 拒绝(age 必须是整数)
# True -> 拒绝(age 必须是整数)
# 0 -> 拒绝(age 必须在 1~150 之间)
# 200 -> 拒绝(age 必须在 1~150 之间)这段纯 Python 的校验函数,就是 Pydantic 在做的事的手写版。框架做的是同一件事,只是快得多、还顺带生成文档。
3.2 Pydantic 模型:把规则写成声明
# 需要先安装:pip install fastapi pydantic
# 本机未安装 pydantic 时运行会报 ModuleNotFoundError: No module named 'pydantic'
from typing import Literal
from pydantic import BaseModel, Field, field_validator
class ImageTask(BaseModel):
"""一个图片处理任务的请求体模型"""
size: int = Field(default=1024, ge=64, le=8192) # 范围 + 默认值
format: Literal["jpg", "png", "webp"] = "jpg" # 枚举值:只能三选一
keep_meta: bool = False # 布尔开关
tags: list[str] = Field(default_factory=list) # 列表,默认空列表
@field_validator("size")
@classmethod
def size_must_be_even(cls, v):
"""自定义规则:边长必须是偶数(方便像素对齐)"""
if v % 2 != 0:
raise ValueError("size 必须是偶数")
return v
# 合法数据 -> 直接得到一个带类型保证的对象
task = ImageTask(size=800, format="png", tags=["头像"])
print("size =", task.size, type(task.size).__name__)
print("format =", task.format)
print("tags =", task.tags)
print("默认值 keep_meta =", task.keep_meta)
# 输出:
# size = 800 int
# format = png
# tags = ['头像']
# 默认值 keep_meta = False上面这段需要 pip install pydantic。模型里最常用的四种写法记住就够:Field(ge=, le=) 管范围、Literal[...] 管枚举、default_factory 管可变默认值、@field_validator 管自定义规则。
3.3 错误响应:让调用方看得懂
校验失败时,FastAPI 默认返回 422,响应体里会精确指出「哪个字段、哪一行、期望什么类型」。而业务上的错误(比如「这个订单不存在」)要靠你自己抛:
# 需要先安装:pip install fastapi uvicorn
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
count: int = 1
@app.post("/items")
def create_item(item: Item):
if item.name == "已存在":
# 抛 HTTPException:FastAPI 会把它转成对应的状态码 + JSON 响应
raise HTTPException(status_code=409, detail="同名商品已存在")
if item.count > 100:
raise HTTPException(status_code=400, detail="单次最多创建 100 个")
return {"name": item.name, "count": item.count}
# 实测输出(TestClient 真发三次 POST,按终端打印原样摘录):
# {"name":"头像","count":2} -> 200 {'name': '头像', 'count': 2}
# {"name":"已存在","count":1} -> 409 {'detail': '同名商品已存在'}
# {"name":"批量","count":999} -> 400 {'detail': '单次最多创建 100 个'}
#
# 读法:409 / 400 是你在业务代码里主动抛的,响应体就是你写的 detail;
# 而字段类型不对时框架自己返 422,根本不会进到函数里。上面是三次真实请求的结果。区分一下:409 / 400 是你在业务代码里主动 raise 的,响应体就是你写的 detail;而字段格式不对时,框架自己返回 422,压根不会执行到函数里。
约定俗成的一套错误码:400 参数不合法、401 没登录、403 没权限、404 资源不存在、409 状态冲突、422 字段校验失败、500 未知异常。不要用 200 携带一个 {"success": false} 来表达失败 —— 那会让监控、重试、前端拦截全部变复杂。
兜底:最后一定要有一个全局异常处理器,把没接住的异常统一转成 500 + 统一 JSON 结构,并且把真实堆栈写进日志、不要返回给客户端(否则等于把内部路径和代码结构告诉别人)。
3.4 【本章小结】
| 你学到了什么 | 关键记忆点 |
|---|---|
| 为什么校验 | 把不确定的外部输入挡在门外 |
| bool 是 int 的子类 | 校验布尔值时要单独处理 |
| Pydantic 常用写法 | Field(ge/le)、Literal、default_factory、field_validator |
| 业务错误 | raise HTTPException(status_code=..., detail=...) |
| 别用 200 表示失败 | 状态码是给机器看的契约 |
| 500 的处理 | 统一兜底 + 堆栈只进日志 |
第 4 章 异步、并发与后台任务
4.1 async/await 到底解决什么
先纠正一个常见误解:async 不是「更快的 Python」,而是「等待的时候不占着位置」。
假设接口要做三件事:调模型、等 2 秒、再调一次数据库。同步写法里,这 2 秒里 CPU 什么都干不了,这个线程就白占着;异步写法里,这 2 秒里事件循环可以去处理别的请求。当你的瓶颈是「等网络」而不是「算数据」时,异步能让一个进程扛住成百上千个并发连接。
import asyncio
import time
async def fetch(name, delay):
"""模拟一次耗时的网络请求:等待期间把执行权交还给事件循环"""
await asyncio.sleep(delay)
return f"{name} 完成,用时 {delay}s"
async def main():
t0 = time.perf_counter()
# gather 让三个任务「同时」开始,而不是一个跑完再跑下一个
results = await asyncio.gather(
fetch("任务A", 0.30),
fetch("任务B", 0.30),
fetch("任务C", 0.30),
)
cost = time.perf_counter() - t0
for r in results:
print(r)
print(f"总耗时约 {cost:.1f}s")
asyncio.run(main())
# 输出:
# 任务A 完成,用时 0.3s
# 任务B 完成,用时 0.3s
# 任务C 完成,用时 0.3s
# 总耗时约 0.3s
如果改成串行的 for 循环依次 await,总耗时会是 0.9s —— 差的这 0.6 秒就是并发的价值。
4.2 def 还是 async def:选择规则
| 函数类型 | 框架怎么执行 | 适合写什么 |
|---|---|---|
async def | 放进事件循环 | 内部要 await 网络/数据库的接口 |
普通 def | 丢到线程池执行 | 纯 CPU 计算、阻塞式第三方库 |
最容易踩的坑:在
async def函数里调用了一个阻塞的同步库(比如老的requests、同步的数据库驱动、time.sleep),整个事件循环会被卡住,所有并发请求一起变慢。判断标准很简单:这个调用会「等」吗?会等就必须用异步版,或者丢进线程池。
4.3 后台任务:先返回,再慢慢做
很多 Agent 接口是「慢活」:要跑模型、要跑十几步工具链。用户不该在浏览器里干等两分钟。标准做法是立刻返回一个任务 ID,后台继续跑,前端轮询或用回调取结果。
# 需要先安装:pip install fastapi uvicorn
from fastapi import BackgroundTasks, FastAPI
app = FastAPI()
def run_agent(job_id: str):
"""后台真正干的活:调用模型、执行工具链(这里用 sleep 模拟)"""
import time
time.sleep(3)
print(f"[后台] 任务 {job_id} 已完成")
@app.post("/jobs")
def create_job(tasks: BackgroundTasks):
# 先把响应立刻返回给调用方
tasks.add_task(run_agent, "job-001") # 挂一个后台任务
return {"job_id": "job-001", "status": "accepted"}
# 实测输出(TestClient 触发一次 POST /jobs,按终端打印原样记录):
# 状态码: 200
# 响应体: {'job_id': 'job-001', 'status': 'accepted'}
# [后台] 任务 job-001 已完成
#
# 注意:TestClient 在测试里会等后台任务跑完才结束,所以接口耗时约 1 秒;
# 真正的 uvicorn 服务会先把上面那个 JSON 发给客户端,再慢慢跑后台任务。小白提示:响应体里的
"status": "accepted"是关键:它表示「我收下了,但还没做完」。用户不用在浏览器干等,前端拿job_id轮询即可。注意输出里的额外说明:TestClient测试时会等后台任务结束,真实 uvicorn 服务才是真正「先返回、后执行」。
等价的纯标准库写法(用线程模拟后台任务),更容易看清楚「先返回、后执行」这件事:
import threading
import time
print_lock = threading.Lock() # 保证多个线程的打印不会互相穿插
def slow_job(job_id, delay):
"""模拟一个耗时任务(比如调用大模型接口)"""
time.sleep(delay)
with print_lock:
print(f"[后台] 任务 {job_id} 已完成")
def handle_request(req_id, delay):
"""模拟接口处理:先返回响应,再让任务在后台继续跑"""
threading.Thread(target=slow_job, args=(req_id, delay), daemon=True).start()
return f"已受理请求 {req_id},任务在后台执行"
# 三个任务耗时不同,完成顺序才是确定的(否则并发打印会挤在一起)
for i, delay in enumerate([0.5, 0.6, 0.7], start=1):
print(handle_request(i, delay))
time.sleep(0.9) # 主线程先歇一下,等后台线程把话说完
# 输出:
# 已受理请求 1,任务在后台执行
# 已受理请求 2,任务在后台执行
# 已受理请求 3,任务在后台执行
# [后台] 任务 1 已完成
# [后台] 任务 2 已完成
# [后台] 任务 3 已完成
注意:
BackgroundTasks适合「几十秒内做完、失败也无所谓」的任务。如果是几分钟起步、要重试、要保证不丢,就该上 Celery / RQ 之类的正经任务队列,别拿后台线程扛大事。
4.4 【本章小结】
| 你学到了什么 | 关键记忆点 |
|---|---|
| async 的意义 | 等待时不占位,提升并发承载 |
| gather | 让多个任务同时开始 |
| def vs async def | 会等 → 异步;纯计算 → 同步或线程池 |
| 最常见的坑 | 在 async 里调用阻塞库 |
| 后台任务 | 先返回任务 ID,再后台执行 |
| 什么时候上队列 | 长任务、要重试、不能丢 |
第 5 章 工程化:结构、配置与依赖注入
5.1 项目结构:一个函数变成一个项目
单文件写三个接口没问题,但要上生产就得拆。推荐的分法是按「职责」而不是按「类型」分:
my_service/
├─ main.py # 只做一件事:创建 app、挂载路由
├─ routers/
│ ├─ items.py # 只放路由和参数,不写业务逻辑
│ └─ agent.py # Agent 相关接口
├─ schemas/
│ └─ item.py # Pydantic 模型:请求体、响应体
├─ services/
│ └─ item_service.py # 纯业务逻辑,不认识 FastAPI
├─ core/
│ ├─ config.py # 配置(环境变量 / .env)
│ └─ deps.py # 依赖注入的定义
├─ tests/
│ └─ test_items.py # 自动化测试
└─ .env # 本地配置(不进版本库)
这棵树不需要运行,它是目录结构示意。按「职责」分而不是按「文件类型」分:routers/ 只管接口进出,schemas/ 只管数据形状,services/ 放纯业务逻辑,core/ 放配置和依赖,tests/ 放测试。这样以后换框架,只动 routers/ 就行。
为什么 services 层不能 import FastAPI:因为业务逻辑写完后应该能不启动服务直接测。这样单元测试快、也不需要起进程。
5.2 配置与密钥:别把密钥写进代码
模型 API Key、数据库密码这类东西,只能从环境变量读,写死在代码里等于把密码贴在墙上。
import os
import tempfile
def load_dotenv(path):
"""极简 .env 读取:KEY=VALUE 一行一个,# 开头是注释。真实项目用 python-dotenv"""
if not os.path.exists(path):
return {}
conf = {}
with open(path, encoding="utf-8") as f:
for line in f:
line = line.strip()
if not line or line.startswith("#"):
continue
key, _, value = line.partition("=")
conf[key.strip()] = value.strip().strip('"')
return conf
# 造一个临时的 .env,模拟真实项目里的配置文件
tmp = tempfile.NamedTemporaryFile("w", suffix=".env", delete=False, encoding="utf-8")
tmp.write("# 应用配置\nAPP_NAME=图片工具服务\nAPP_DEBUG=true\nAPI_KEY=\"demo-key-not-real\"\n")
tmp.close()
conf = load_dotenv(tmp.name)
# 环境变量优先级更高:同名时用系统环境覆盖文件里的值
conf.update({k: v for k, v in os.environ.items() if k.startswith("MYAPP_")})
print("APP_NAME =", conf.get("APP_NAME"))
print("APP_DEBUG =", conf.get("APP_DEBUG"))
print("API_KEY 前 4 位 =", conf.get("API_KEY", "")[:4])
print("环境变量覆盖了几项 =", len([k for k in os.environ if k.startswith("MYAPP_")]))
os.unlink(tmp.name) # 清理临时文件
# 输出:
# APP_NAME = 图片工具服务
# APP_DEBUG = true
# API_KEY 前 4 位 = demo
# 环境变量覆盖了几项 = 0三条纪律:① .env 不进版本库;② 启动时缺关键配置就直接报错退出,别用默认值悄悄跑起来;③ 日志里永远不要打印密钥(打印时截断)。
5.3 依赖注入:把「共用的东西」抽出来
每个接口都要「拿数据库连接」「读当前用户」「拿模型客户端」,如果每个函数都自己 new 一遍,测试时就没法替换。依赖注入(DI)的思路是:依赖由外面传进来,函数只负责用。
def get_db():
"""真实实现:返回数据库连接"""
return "真实数据库连接"
def get_service(db=None):
"""业务函数不自己创建依赖,而是从外面拿进来"""
db = db or get_db() # 没传就用默认实现
return f"Service 使用 {db}"
# 正常调用:用真实实现
print(get_service())
# 测试调用:直接塞一个假实现进去,不用改业务代码
print(get_service("测试用假连接"))
# 输出:
# Service 使用 真实数据库连接
# Service 使用 测试用假连接FastAPI 里的写法更进一步 —— 用 Depends 声明依赖,框架帮你注入并缓存:
# 需要先安装:pip install fastapi uvicorn
from fastapi import Depends, FastAPI, Header
app = FastAPI()
def get_token(authorization: str = Header(default="")):
"""一个依赖:从请求头里取出令牌"""
return authorization.replace("Bearer ", "").strip()
def get_current_user(token: str = Depends(get_token)):
"""依赖可以依赖另一个依赖,形成一串「准备流程」"""
return f"用户-{token or '匿名'}"
@app.get("/me")
def read_me(user: str = Depends(get_current_user)):
# user 是框架注入进来的,这里不用关心它从哪来
return {"user": user}
# 实测输出(TestClient 真发两次 GET,按终端打印原样摘录):
# 不带任何请求头 -> 200 {'user': '用户-匿名'}
# Authorization: Bearer abc123 -> 200 {'user': '用户-abc123'}
#
# 读法:get_token 先取出令牌,get_current_user 再依赖它算出用户名,
# 最后框架把 user 注入 read_me。整条链子你一次都没手写调用。小白提示:上面两次请求的差别只在一个请求头。
get_token取令牌 →get_current_user依赖它算用户名 → 框架把user注入read_me,整条链子你一次都没手写调用。测试时还能用dependency_overrides把整条链换成假实现。
5.4 【本章小结】
| 你学到了什么 | 关键记忆点 |
|---|---|
| 项目分层 | routers / schemas / services / core / tests |
| services 不 import 框架 | 业务逻辑要能脱离服务直接测 |
| 配置来源 | 环境变量 > .env > 默认值 |
| 密钥纪律 | 不写死、不打印、缺失就报错 |
| 依赖注入 | 依赖从外面传,测试时可替换 |
| Depends | 依赖还能依赖依赖 |
第 6 章 从原型到上线
6.1 自动化测试:改代码不慌
没有测试的接口服务,改一处坏三处。接口测试要测三件事:正常返回、参数不对时返回 422、业务异常时返回你定的状态码。
def check(name, got, want):
"""一个极简断言:相等算通过,不等就打印出来"""
ok = got == want
print(f"{'PASS' if ok else 'FAIL'} {name}: got={got!r} want={want!r}")
return ok
def add(a, b):
return a + b
def divide(a, b):
if b == 0:
raise ValueError("除数不能为 0")
return a / b
results = []
results.append(check("add(2, 3)", add(2, 3), 5))
results.append(check("divide(10, 2)", divide(10, 2), 5.0))
try:
divide(1, 0)
results.append(check("divide(1, 0) 应报错", "没有报错", "ValueError"))
except ValueError as e:
print(f"PASS divide(1, 0) 抛出 ValueError: {e}")
results.append(True)
print("---")
print(f"通过 {sum(results)} / {len(results)}")
# 输出:
# PASS add(2, 3): got=5 want=5
# PASS divide(10, 2): got=5.0 want=5.0
# PASS divide(1, 0) 抛出 ValueError: 除数不能为 0
# ---
# 通过 3 / 3真实项目用 pytest 写起来更短(pip install pytest):
# 需要先安装:pip install pytest fastapi httpx
# 放到 tests/test_items.py,终端执行 pytest -q 就能跑
from fastapi.testclient import TestClient
from main import app
client = TestClient(app) # TestClient 直接调用应用,不需要真的起服务
def test_create_item_ok():
r = client.post("/items", json={"name": "头像", "count": 2})
assert r.status_code == 200
assert r.json() == {"name": "头像", "count": 2}
def test_create_item_missing_field():
r = client.post("/items", json={}) # 少传 name
assert r.status_code == 422 # 校验失败
# 实测输出(存成 tests/test_items.py,终端执行 pytest -q,末尾几行):
# .. [100%]
# 2 passed, 1 warning in 0.28s
#
# 两个点代表两个测试都通过;耗时与 warning 随机器 / 依赖版本变化,
# 关键是 "2 passed"。本机环境:fastapi 0.162.5 / pytest 9.2.0。上面是本机 pytest -q 的真实结果:两个点代表两个测试都通过,结论 2 passed。不同环境可能多一行 warning 提示(取决于 starlette / httpx 版本),只要最后是 2 passed 就没问题。TestClient 直接在进程里调用应用,不需要真的把服务跑起来。
6.2 自动生成的接口文档
FastAPI 启动后自带三个地址,不用另外写文档:
| 地址 | 内容 | 给谁看 |
|---|---|---|
/docs | Swagger UI,网页上直接点按钮发请求 | 开发、前端、测试 |
/redoc | ReDoc,排版更适合阅读 | 给别人看文档 |
/openapi.json | 机器可读的接口描述 | 代码生成 SDK、网关、契约测试 |
有了 /openapi.json,前端可以自动生成类型定义、测试可以自动做接口契约校验。前提是你的返回类型要写清楚:给接口加一个 response_model,返回的数据就会自动带上文档和校验。
6.3 部署:把服务跑起来
FROM python:3.12-slim
WORKDIR /app
# 先装依赖:这一层单独缓存,改代码时不用重装
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
# 不要用 root 跑应用
RUN useradd -m appuser
USER appuser
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "2"]
小白提示:这是 Dockerfile,本机没有 Docker,无法实测运行,所以这里不编造输出。正常执行
docker build -t my-service .时,终端会逐层打印Step 1/8 : FROM ...直到Successfully tagged my-service:latest。把依赖安装单独放一层,是为了改代码时不用重装一遍依赖。
# 开发模式:自动重载
uvicorn main:app --reload
# 生产模式:多进程,不要 --reload
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4
# 容器化
docker build -t my-service .
docker run -d -p 8000:8000 --env-file .env my-service
# uvicorn main:app --reload 的实际终端输出(本机真实日志,仅把目录与进程号略写):
# INFO: Will watch for changes in these directories: ['你的项目目录']
# INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
# INFO: Started reloader process [23540] using StatReload
# INFO: Started server process [16784]
# INFO: Waiting for application startup.
# INFO: Application startup complete.
#
# 看到 "Application startup complete." 就说明服务真的起来了。
# docker build / docker run 两行本机没有 Docker,未实测;
# 正常执行时 build 会逐层打印 Step 1/8 ...,run 会回一行容器 ID。第一段的 uvicorn 日志是本机真实输出;Docker 两行因本机没装 Docker 未实测,只说明正常执行时该看到什么。生产环境记住三条:加 --host 0.0.0.0、去掉 --reload、用 --workers N 开多进程。
services:
api:
build: .
ports:
- "8000:8000"
env_file:
- .env
restart: unless-stopped
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/docs')"]
interval: 30s
timeout: 3s
retries: 3
这是 docker-compose 配置,同样需要 Docker 才能跑,本机未实测。写好后在同目录执行 docker compose up -d,正常会看到 Network ... Creating 和 Container api Started;docker compose ps 里 STATUS 会显示 Up (healthy),那个 healthy 就来自上面配的 healthcheck。
三个必须记住的点:①
--host 0.0.0.0才能被容器外访问;② 不要用reload上线;③ 一定要有健康检查(/docs或专门的/health),否则编排系统不知道服务是不是活着。
6.4 【本章小结】
| 你学到了什么 | 关键记忆点 |
|---|---|
| 接口测试 | 正常、422、业务异常三条线都要测 |
| 测试替身 | TestClient 不用真起服务 |
| 自动文档 | /docs、/redoc、/openapi.json |
| 部署方式 | Docker + uvicorn 多进程 |
| 健康检查 | 要有 /health 或 /docs 探活 |
学完这一阶段你能做什么:把前面阶段写的 Prompt 逻辑、Agent 循环、RAG 检索全部包成一个 真正能被调用的 HTTP 服务 —— 前端能接、定时任务能跑、别人不用看你代码就知道怎么用。按学习路线下一步是阶段 02「大模型与 Prompt」(模块 ③④),而不是编号上的 06先让模型稳定输出、能接进程序,再往后走;「框架与 MCP」排在第 6 步,别按编号跳过去。