FastAPI 核心

FastAPI 官方中文文档：https://fastapi.tiangolo.com/zh/

角色	Java 生态	Python 生态
后端开发框架	SpringBoot	FastAPI
用途	写接口、做管理系统、业务后端	写接口、做 AI 服务、模型部署

一、路由、GET/POST

1.创建并激活一个虚拟环境

2.安装 FastAPI：

复制代码

pip install "fastapi[standard]"

3.在合适的文件夹里新建一个文件，叫GPtest.py。用你的文本编辑器打开它，输入以下代码：

复制代码

from fastapi import FastAPI

app=FastAPI()

#Get
@app.get("/")
def home():
    return {"message":"Hi ai infra"}

@app.get("/user/{user_id}")
def get_user(user_id:int):
    return {"user_id":user_id,"name":"ai infra student"}

#Post
@app.post("/login")
def login(username:str,password:str):
    return {"username":username,"status":"success"}

4.需要用 uvicorn 来运行

复制代码

uvicorn GPtest:app --reload

5.可以http://127.0.0.1:8000/docs 查看自动生成的交互式 API 文档。

6.在交互式 API 文档中测试接口

二、请求体、参数校验、响应模型

代码演示

Pydantic 是一个 Python 数据验证库，它的核心功能是：

定义数据模型（数据结构）

自动类型转换 （比如把字符串 "123" 转成整数 123）

数据校验（检查字段是否缺失、类型是否正确、值是否在范围内）

与 JSON 无缝互转

在 FastAPI 中，Pydantic 被深度集成，用于：

定义请求体（Request Body）的结构

定义响应体（Response Body）的结构

自动生成 API 文档（Swagger UI）

复制代码

from fastapi import FastAPI
from pydantic import BaseModel

app=FastAPI()

#请求体
class UserRequest(BaseModel):
    username:str
    password:str
    age:int

#响应
class UserResponse(BaseModel):
    username:str
    age:int
    status:str

#请求
@app.post("/user",response_model=UserResponse)
def create_user(user:UserRequest):
    return {
        "username":user.username,
        "age":user.age,
        "status":"created"
    }

通过装饰器 @app.post("/user") 把create_user"挂载"到路径 /user 上，告诉 FastAPI：当收到 POST 请求到 /user 时，执行这个函数。

BaseModel说明：

1.定义数据结构

复制代码

class UserRequest(BaseModel):
    username: str
    password: str
    age: int

声明了一个"数据蓝图"：任何符合这个模型的数据必须包含 username（字符串）、password（字符串）、age（整数）。

2.自动类型转换

如果客户端传来的 age 是字符串 "25"，Pydantic 会自动尝试转成整数 25（因为模型中标注为 int）。如果转换失败（比如 "abc"），会抛出清晰的验证错误。

3.自动数据验证

必填字段 ：username, password, age 都没有默认值，所以它们是必填的。如果请求体中缺少某个字段，FastAPI 会自动返回 422 错误，并指出哪个字段缺失。
类型校验 ：如果 age 传了字符串 "abc"，会返回错误：value is not a valid integer。

4.为 FastAPI 提供请求体解析依据

当你写 user: UserRequest 时，FastAPI 知道要从请求的 JSON Body 中读取数据，并使用 UserRequest 模型来解析它。

5. 自动生成 API 文档

FastAPI 会读取 UserRequest 的结构，在 Swagger UI（/docs）中自动生成请求体的 JSON 示例和字段说明，让调用方一目了然。

6.提供 IDE 智能提示

因为 user 参数的类型是 UserRequest，你在函数内部写 user. 时，IDE 会自动弹出 username、password、age 的选项，极大减少拼写错误。

三、文件上传、中间件

3.1文件上传

1.简单的文件上传接口的实现：

复制代码

from fastapi import FastAPI,UploadFile,File
import  shutil

app=FastAPI()

@app.post("/upload")
def upload(file:UploadFile=File(...)):
    with open(file.filename,"wb") as f:
        shutil.copyfileobj(file.file,f)
    return {"filename":file.filename,"status":"ok"}

shutil：Python 标准库，提供高级文件操作
UploadFile：FastAPI 提供的特殊类型，用于处理上传的文件（包含文件名、内容等元数据）。
File(...)：指示 FastAPI 从请求的表单字段 中读取文件数据，... 表示该字段为必填
copyfileobj 会分块读取并写入，内存效率高。

2.访问 `http://localhost:8000/docs` 使用 Swagger UI 手动上传测试接口:

3.2中间件：

概念

中间件是位于 Web 服务器和应用程序之间的一个"钩子"层。每个请求在到达路径函数之前，以及响应离开路径函数之后，都会经过中间件。可以利用中间件来：

添加通用的响应头
记录日志
处理跨域（CORS）
压缩响应
身份验证等

CORSMiddleware 是 FastAPI 提供的一个内置中间件，专门用于处理 CORS（跨域资源共享） 问题。

复制代码

from fastapi.middleware.cors import CORSMiddleware

CORS 是一种浏览器安全机制，叫做"同源策略"。它限制网页只能请求相同源（协议 + 域名 + 端口）的 API。例如：

前端页面运行在 http://localhost:3000
后端 API 运行在 http://localhost:8000

这两个源的端口不同（3000 vs 8000），浏览器会认为它们是不同源 。当前端 JavaScript 尝试用 fetch 或 XMLHttpRequest 调用后端 API 时，浏览器会拦截该请求，并在控制台报错

CORS 机制允许服务器告诉浏览器 ："这个来源（http://localhost:3000）是被允许的，请放行。" 服务器通过在响应头中添加特定字段（如 Access-Control-Allow-Origin）来实现。

CORSMiddleware 的作用就是自动为所有响应添加这些 CORS 响应头，从而让浏览器允许跨域请求。

python 复制代码

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    # 允许 任意来源（任何域名、IP、端口）访问你的 API。
#allow_origins=["*"] 与 allow_credentials=True 一起使用时，浏览器会拒绝携带凭证的请求（规范禁止）。如果要允许凭证，必须指定具体的源
    allow_origins=["*"],
#允许前端请求携带 凭证（如 Cookies、HTTP 认证、客户端证书）。
    allow_credentials=True,
#允许 所有 HTTP 方法（GET、POST、PUT、DELETE 等）。
    allow_methods=["*"],
#允许 所有请求头（例如 Content-Type, Authorization 等）
    allow_headers=["*"],
)

简化版的实际工作流程：

1.前端（http://localhost:3000）向你的后端（http://localhost:8000）发送一个 POST 请求。

2.浏览器检测到跨源，会先发送一个 预检请求（OPTIONS），询问服务器是否允许实际请求。

3.你的 FastAPI 应用收到 OPTIONS 请求，CORSMiddleware 捕获它并返回带有以下响应头的空响应：

python 复制代码

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: *
Access-Control-Allow-Headers: *
Access-Control-Allow-Credentials: true

4.浏览器看到这些头，确认允许，然后发送真正的 POST 请求。

5.你的路径函数正常处理请求，返回数据。CORSMiddleware 也会在响应中添加 Access-Control-Allow-Origin: * 等头。

6.浏览器收到响应后，因为 CORS 头符合要求，会把数据交给前端 JavaScript。

四、统一返回格式

python 复制代码

def resp(code=0, msg="success", data=None):
    return {"code": code, "msg": msg, "data": data}

对比：

python 复制代码

#不使用统一接口函数，会让代码变得臃肿、混乱、难维护
# 接口 A
return {"user": "Alice", "age": 20}

# 接口 B  
return {"status": "ok", "data": {"id": 1}}

# 接口 C
return {"code": 200, "message": "success", "result": [...]}

五、全局异常处理

python 复制代码

from fastapi import HTTPException

@app.get("/error")
def testErro():
    raise HTTPException(status_code=400,detail="参数错误")

一、路由、GET/POST

二、请求体、参数校验、响应模型

代码演示

BaseModel说明：

1.定义数据结构

2.自动类型转换

3.自动数据验证

4.为 FastAPI 提供请求体解析依据

5. 自动生成 API 文档

6.提供 IDE 智能提示

三、文件上传、中间件

3.1文件上传

1.简单的文件上传接口的实现：

2.访问 http://localhost:8000/docs 使用 Swagger UI 手动上传测试接口:

3.2中间件：

概念

简化版的实际工作流程：

四、统一返回格式

五、全局异常处理

2.访问 `http://localhost:8000/docs` 使用 Swagger UI 手动上传测试接口: