之前有人问我FastAPI 项目上手先看哪儿。我一般不会直接甩教程链接而是让他把一个最简单接口从请求到响应的完整过程讲清楚。原因很简单FastAPI 再花哨核心也就干两件事——把 HTTP 请求变成 Python 对象把 Python 返回值变成 HTTP 响应。你真正理解这两件事后面接数据库、做鉴权、部署上线都是往这个骨架里填肉。这篇文章不打算讲 Hello World而是把请求解析、响应模型、异常处理、联调和压测里最常见的问题挨个过一遍。我会尽量用实际项目里的代码写法来举例同时说明为什么要这么写。新手看完能少踩一半以上的坑老手也可以对照检查一下自己的接口是不是把 FastAPI 的样式用足了。1. 为什么我只推荐先啃“请求和响应”这两块很多初学者学 FastAPI 的时候先冲进 ORM、JWT、异步任务这些高阶话题结果一联调就露馅参数取不到、返回字段多了一堆、前端说 422、后端说明明是 200。这些问题的根源几乎全在请求和响应这一层没理解透。1.1 一次请求在 FastAPI 里经历了什么FastAPI 本身并不直接处理 TCP 连接它跑在 Uvicorn 这种 ASGI 服务器上。整个流程大概是浏览器或客户端发出 HTTP 请求Uvicorn 把原始字节流收下来。ASGI 协议把请求拆成 scope请求元数据和 receive/send 通道消息收发。FastAPI 根据你在路由函数里写的类型注解把 scope 中的 path、query、headers以及 body 里的 JSON 解析成 Python 类型。路由函数执行返回一个 Python 对象。FastAPI 把返回值序列化成 JSON组装成 ASGI response交给 Uvicorn 发回客户端。所以你在路由函数里写order_id: intFastAPI 就会把 URL 里的字符串123转成 Python 的int。如果前端传了abcFastAPI 不会让这个字符串碰你的函数而是直接返回 422 校验错误。这个行为和手写if not isinstance(...)完全不是一个量级。1.2 用类型注解管住参数比手写 if 判断省事太多我接触过的不少老项目参数校验是这样的def get_order(): order_id request.args.get(order_id) if not order_id: return {code: 1, msg: order_id is required} try: order_id int(order_id) except ValueError: return {code: 1, msg: order_id must be int}这套代码没有错但每个接口都要重复写一遍而且错误响应格式每个接口可能还不一样。FastAPI 的思路是你在函数签名里把约束声明出来剩下的校验、类型转换、错误响应生成全部交给框架。app.get(/orders/{order_id}) def get_order( order_id: int Path(..., title订单ID), ): return {order_id: order_id}前端传/orders/abcFastAPI 自动返回 JSON 形式的 422detail里明确告诉你order_id没有通过 int 校验。你不用再去翻前端传的是“空字符串”还是“null”框架已经把边界堵住了。2. 请求侧拆解路径参数、查询参数、请求体、请求头一个接口的参数来源看起来简单实际混在一起时很容易让人迷糊。我见过一个同事在GET请求里硬塞一个 body然后问我为什么 Postman 里收不到。HTTP 语义和 FastAPI 的参数声明是绑在一起的搞混了就出现各种 422。2.1 参数从哪来一个接口四种来源来看一个稍微完整点的例子from fastapi import FastAPI, Query, Path, Header from pydantic import BaseModel app FastAPI() class OrderItem(BaseModel): sku_id: str quantity: int 1 app.get(/orders/{order_id}) def get_order( order_id: int Path(..., title订单ID), source: str Query(web, description渠道来源), x_trace_id: str | None Header(defaultNone, convert_underscoresTrue), ): return { order_id: order_id, source: source, trace_id: x_trace_id, } app.post(/orders) def create_order(order: OrderItem): return {sku_id: order.sku_id, quantity: order.quantity}这里order_id来自 URL 路径source来自?sourcewap这种查询参数x_trace_id来自请求头X-Trace-Idorder来自请求体 JSON。你把四种来源放在同一个函数里FastAPI 依然能各归各位。有个细节Header默认会把参数名里的下划线转成中划线所以函数里写x_trace_id匹配的请求头是X-Trace-Id。这个行为很贴心因为 HTTP 头里下划线的兼容性很差很多代理服务器会直接忽略带下划线的 header。要是你非要用convert_underscoresFalse就得保证客户端发送的 header 名和函数参数名完全一致容易埋坑不建议改。2.2 文件上传和表单请求和 JSON 请求体不是一回事很多人一写上传接口就踩坑明明文档里写的是UploadFile前端发过来却报 422。本质上是因为上传接口用的是multipart/form-data不是application/json。FastAPI 处理这两种格式用的是不同的解析器。from fastapi import FastAPI, File, UploadFile, Form app.post(/upload) async def upload_file( file: UploadFile File(...), note: str Form(), ): content await file.read() return {filename: file.filename, size: len(content), note: note}注意用的时候必须先安装python-multipart否则 FastAPI 会在启动时直接报错。UploadFile和bytes的区别在于UploadFile是流式读入适合大文件带filename和content_type属性bytes是直接把内容全部读进内存小文件随便用大文件建议避免。记住了文件走multipart/form-data表单字段走Form(...)就不会把前端传的 JSON 和文件混在一起。2.3 参数顺序和默认值Python 语法先绕晕一批人写路由函数时大家容易忽略 Python 本身的语法限制——有默认值的参数不能出现在无默认值参数前面。def get_order( verbose: bool Query(False), order_id: int Path(...), # 这行会报错 ): ...Path(...)里的...表示“没有默认值但必须传”放在默认参数后面Python 解释器直接拒绝。解决办法是把必传参数往前放或者用关键字参数。实际项目里我建议必传的路径参数、必传的请求体放前面可选的查询参数、可选的请求头放后面。这样代码读起来也舒服。另外一个常见坑是可变默认值def get_orders(tags: list[str] []): # 不推荐 ...Pydantic 在 FastAPI 里会主动帮你规避部分情况但自己写代码时还是要用Query(default[])这种形式明确表达“默认是一个空列表”。在 Python 里直接写[]作为默认值容易在别处留下可变对象共享的隐患这个习惯越早改越好。3. 响应侧设计response_model 才是真正的接口契约很多接口的返回到处都是return {code: 0, data: {...}}短时间看挺灵活项目一大了就失控有人往data里塞了数据库的created_at有人把password_hash当成password返回了。响应侧一定要有“出口校验”FastAPI 提供的方案就是response_model。3.1 为什么不直接 return dict不直接返回 dict 的原因有两个一是内部字段容易泄漏二是返回结构不可控。看这个例子from datetime import datetime from pydantic import BaseModel, ConfigDict class OrderOut(BaseModel): sku_id: str quantity: int created_at: datetime | None None model_config ConfigDict(from_attributesTrue) app.post(/orders, response_modelOrderOut, status_code201) def create_order(order: OrderItem): return { sku_id: order.sku_id, quantity: order.quantity, internal_note: 这个字段别给前端看, created_at: datetime.utcnow(), }函数里明明返回了internal_note但response_modelOrderOut会把响应过滤成只包含OrderOut里声明的字段。这个约束同时还会生成 OpenAPI 文档前端直接看 Swagger UI 就知道返回长什么样。相比之下裸dict就像没写合同就签单后面怎么扯皮的都有。from_attributesTrue也很关键。如果你的返回数据来自 ORM 对象比如sqlalchemy查出来的userFastAPI 可以直接做response.model_validate(user)。但前提是你允许 Pydantic 读取对象属性。实际项目里响应模型和 ORM 模型最好分开别让数据库表结构直接暴露给前端。3.2 字段过滤和响应状态码除了response_modelPydantic 模型还支持response_model_exclude、response_model_include和response_model_exclude_unset这些配置。用的最多的是exclude_unsetapp.get(/orders, response_modellist[OrderOut], response_model_exclude_unsetTrue) def list_orders(): ...它的含义是如果某个字段在构造响应时没有手动指定值就别出现在响应里。这个特性适合做“可选字段按需返回”。不过要注意exclude_unset和数据库字段默认值容易互相干扰。比如 ORM 返回的created_at可能因为属性读取路径不同而没被显式设置结果被过滤掉。遇到这种情况优先自查模型定义而不是盲目加更多 exclude 参数。状态码也是响应的一部分。创建资源返回201删除资源返回204这不仅是规范也是前端判断逻辑的一部分。FastAPI 里直接用status_code201或者from fastapi import status; status_codestatus.HTTP_201_CREATED都行。别总让所有接口默认 200否则前端看状态码看不出这是一个“创建成功”还是“查询成功”。3.3 自定义响应头和 JSONResponse有时候需要在响应里带自定义 header比如缓存标记、追踪 ID、分页信息。FastAPI 允许往路由函数里注入一个Response对象from fastapi import Response app.get(/orders/{order_id}) def get_order(order_id: int, response: Response): response.headers[X-Process-Time] 12ms return {order_id: order_id}这个Response参数不会影响你的函数返回值它只是接管响应元数据。实际项目里可以用它做耗时统计、打 traceID非常方便。如果你需要完全自定义响应结构可以直接返回JSONResponsefrom fastapi.responses import JSONResponse app.get(/custom) def custom(): return JSONResponse( status_code200, content{code: 0, data: {name: fastapi}}, headers{X-Custom: 1}, )但我不建议整个项目到处直接返回JSONResponse因为这样会绕过response_model的出口校验。最好只把JSONResponse用在异常处理器、第三方回调、文件下载这些特殊场景。正常业务接口还是声明模型让 FastAPI 统一处理。4. 异步、依赖注入与异常让请求响应链路更稳请求和响应不只是“进参数、出 JSON”如何组织代码同样影响链路稳定性。这里聊三个实战里躲不开的话题异步函数、依赖注入、异常处理。4.1 async def 还是 def选错会拖慢整个服务FastAPI 支持async def和普通def混用但它们的执行方式不同async def跑在事件循环里适合 I/O 密集型异步操作比如httpx.AsyncClient、asyncio.sleep、异步数据库驱动。普通def会被 FastAPI 扔进线程池执行适合requests、time.sleep、同步数据库驱动这类阻塞型调用。新手最容易犯的错是在async def里写同步阻塞代码import time app.get(/bad) async def bad_route(): time.sleep(2) # 这是阻塞操作 return {ok: True}这个time.sleep会直接卡住事件循环不只是这个请求慢其他所有并发请求都得陪着等。如果这个接口是压测重点服务几乎会像冻住一样。正确做法是把它改成普通def让 FastAPI 丢到线程池里处理app.get(/good) def good_route(): time.sleep(2) return {ok: True}给一个判断标准如果你的依赖里用到requests、psycopg2、sqlalchemy同步 session就用普通def如果已经用httpx.AsyncClient、asyncpg、aiosqlite就用async def。混用没关系但别在异步函数里偷偷放阻塞调用。4.2 依赖注入把重复逻辑从每个函数里抠出来“请求头里拿 token、解析 token、查用户”这段逻辑如果每个接口都复制一遍早晚会出现不一致。FastAPI 的Depends就是为这个设计的from fastapi import Depends, Request, HTTPException def get_current_user(request: Request): auth request.headers.get(Authorization, ) if not auth.startswith(Bearer ): raise HTTPException(status_code401, detailmissing token) token auth[7:] user fake_decode_user(token) if user is None: raise HTTPException(status_code401, detailinvalid token) return user app.get(/me) def read_me(user: dict Depends(get_current_user)): return {user: user}依赖函数和路由函数一样可以声明自己的参数包括Request、Header、查询参数等。FastAPI 会递归解析这个依赖。这样做的好处是鉴权逻辑只写一遍后续其他接口只需要Depends(get_current_user)。同时依赖里 raise 出的异常也会走统一的异常处理不会打乱响应结构。项目目录变大后我会把依赖按业务分层api/deps.py放通用鉴权schemas/user.py放 Pydantic 模型routers/v1/user.py放路由。FastAPI 的自动文档能帮你把接口分组但代码组织还得靠人。请求参数、响应模型、依赖函数各归其位后面加需求时才不会在文件里满屏找“这个接口到底写在哪儿”。4.3 异常处理让错误响应也“有结构”业务异常最怕乱抛有人返回{msg: failed}有人返回{error: xx}前端解析逻辑写得很痛苦。FastAPI 里可以自定义异常处理器把错误响应的结构统一起来。class BizError(Exception): def __init__(self, message: str, code: str BIZ_ERROR): self.message message self.code code from fastapi.responses import JSONResponse app.exception_handler(BizError) async def biz_error_handler(request: Request, exc: BizError): return JSONResponse( status_code400, content{code: exc.code, message: exc.message}, ) app.get(/check) def check(): raise BizError(余额不足, codeNOT_ENOUGH_BALANCE)这样无论哪里抛出BizError前端拿到的都是固定结构联调时省下大量“对字段”的时间。HTTPException也可以继续用它适合框架层面的 404、401 这类错误。自定义异常则更适合表达业务规则比如库存不够、订单已支付。有一点要注意在处理请求时如果await一个耗时操作异常响应也会变慢。建议给外部 API 调用设置超时比如httpx.AsyncClient(timeout5)。很多线上“响应超时”问题不是 FastAPI 本身慢而是后端某个环节没设超时请求悬挂在那里最终拖垮整个服务。5. 联调和压测中常见的问题我替你趟过的坑最后聊一些“非典型”问题。这些问题单看代码没问题但联调时就是让你抓狂。我把它们单独列出来是因为它们比语法错误更容易消耗时间。5.1 前端报“请求被阻断”或 422先查 Content-Type有段时间我们前端同事一直反馈接口报 422日志里detail提示字段缺失。查来查去发现是fetch请求没有写请求头fetch(/orders, { method: POST, body: JSON.stringify({ sku_id: A1001, quantity: 2 }), })服务端收到的是text/plain;charsetUTF-8FastAPI 根本不会把它当成 JSON 解析。伸手就能解决fetch(/orders, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ sku_id: A1001, quantity: 2 }), })如果是文件上传反而不能手动设置Content-Type要让浏览器自动带上multipart/form-data; boundary...。否则后端解析文件时会因为缺少 boundary 而失败。记住一个原则JSON 请求明确写application/json文件上传别手贱去指定 Content-TypeForm 表单交给 axios 或 fetch 自己处理。还有编码问题。application/json默认就是 UTF-8但如果你直接读request.body()然后用decode(gbk)中文字段就会出现乱码。FastAPI 在正常情况下不需要你手动处理它已经按 UTF-8 解好了。只有当你接某个特别老的客户端发送非 UTF-8 编码时才需要特殊处理。我的建议是统一 UTF-8别为旧系统给 FastAPI 加“编码兼容层”那是在给未来埋雷。5.2 CORS 中间件跨域问题的标准解法本地开发时前端跑在 5173后端跑在 8000浏览器经常直接拦下响应终端报blocked by CORS policy。这个不是 FastAPI 的 bug是浏览器安全机制在起作用。标准解法是加 CORSMiddlewarefrom fastapi.middleware.cors import CORSMiddleware app.add_middleware( CORSMiddleware, allow_origins[ http://localhost:5173, https://admin.example.com, ], allow_credentialsTrue, allow_methods[*], allow_headers[*], )一个容易踩的坑allow_credentialsTrue时allow_origins不能写[*]。浏览器的规则是“如果带 cookie 凭证来源不能是通配符”否则即使 FastAPI 返回了Access-Control-Allow-Origin: *浏览器依然会拦截。实际项目里把具体的域名写进去比用通配符安全得多也更容易排查问题。5.3 压测时怎么看响应内容别只看吞吐量和错误率很多同学用 JMeter 压测只看聚合报告里的 TPS 和 Error%一旦发现错误率先看是不是服务器崩了。其实在压测阶段最该做的是打开“查看结果树”逐个看请求的响应体。JMeter 里添加“查看结果树”监听器响应数据那一栏选Text你就能直接看到接口返回的 JSON。这比在代码里打日志更直观特别是定位 422 的时候响应体里的detail字段会告诉你到底哪个参数校验失败。如果你压的是网关或反向代理还需要确认你看到的是不是最终的后端响应别被中间层的错误页误导。另一个习惯是压测前先确认响应Content-Type。有时候接口返回了 JSON但 Content-Type 是text/plain前端解析就失败。FastAPI 默认返回application/json但如果你自己 wrap 了一层 Response就可能改变这个头。用 JMeter 的响应断言去校验Content-Type和关键业务字段比事后看日志高效得多。压测时如果出现大量超时也别急着怪 FastAPI。先看是不是依赖了外部接口而没设超时再看是不是线程池被某个同步阻塞任务占满了。FastAPI 在异步模型下性能不差但代码里只要有一两个async def中写了阻塞调用整体吞吐量就会被拖下来。压测不是把并发数调大就行要配合后台观察 CPU、内存和数据库连接池才能找到真正的瓶颈。最后分享一个我的习惯我现在写新接口第一步不是写路由函数而是先在schemas.py里把入参模型和出参模型定义出来。入参模型用BaseModel声明字段和校验规则出参模型用response_model挂在路由上然后才开始写业务逻辑。这样做的好处是文档、调试、联调三方看到的都是同一份契约前端也能提前通过 Swagger UI 对接口。等这个习惯变成肌肉记忆后你会发现 FastAPI 最难的地方不是语法而是你愿不愿意在动手前先把“请求和响应”想清楚。请求和响应理顺了剩下的数据库、缓存、消息队列都只是为了让这两件事跑得更快、更稳。