Path Operations
8 methods路径操作装饰器与依赖、异常、参数校验核心 API。
@app.get(path)注册一个 GET 路由处理函数。
Parameters
| Name | Type | Description |
|---|---|---|
| path | str | URL 路径,可含 {param} |
Returns
装饰器 — 包装后的路由函数
Example
fastapi
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
async def read_item(item_id: int):
return {"item_id": item_id}@app.post(path)注册一个 POST 路由处理函数,用于创建资源。
Parameters
| Name | Type | Description |
|---|---|---|
| path | str | URL 路径 |
Returns
装饰器 — 包装后的路由函数
Example
fastapi
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
price: float
@app.post("/items/")
async def create_item(item: Item):
return itemFastAPI()创建 FastAPI 应用实例,可指定标题、版本等元信息。
Returns
FastAPI — 应用实例
Example
fastapi
from fastapi import FastAPI
app = FastAPI(title="My API", version="1.0.0")
@app.get("/")
async def root():
return {"message": "hello"}Depends(dependency)声明依赖项,框架自动解析并注入其返回值。
Parameters
| Name | Type | Description |
|---|---|---|
| dependency | Callable | 依赖函数或可调用对象 |
Returns
依赖对象 — 由框架解析后注入
Example
fastapi
from fastapi import Depends, FastAPI
app = FastAPI()
def common_params(q: str | None = None, skip: int = 0, limit: int = 10):
return {"q": q, "skip": skip, "limit": limit}
@app.get("/items/")
async def list_items(commons: dict = Depends(common_params)):
return commonsHTTPException(status_code, detail)抛出 HTTP 异常,立即终止请求并返回指定状态码与详情。
Parameters
| Name | Type | Description |
|---|---|---|
| status_code | int | HTTP 状态码,如 404 |
| detail | any | 返回给客户端的错误详情 |
Returns
HTTPException — 抛出后终止请求
Example
fastapi
from fastapi import FastAPI, HTTPException
app = FastAPI()
@app.get("/items/{item_id}")
async def read_item(item_id: int):
if item_id < 1:
raise HTTPException(status_code=404, detail="Item not found")
return {"item_id": item_id}BaseModelPydantic 模型基类,用于定义请求体/响应体的数据结构与校验规则。
Returns
BaseModel 子类 — 数据模型
Example
fastapi
from pydantic import BaseModel, Field
from fastapi import FastAPI
app = FastAPI()
class User(BaseModel):
name: str
age: int = Field(0, ge=0)
@app.post("/users")
async def create_user(user: User):
return userQuery(default) / Path(default)为查询参数或路径参数添加校验与元数据。
Parameters
| Name | Type | Description |
|---|---|---|
| default | any | 默认值,使用 ... 表示必填 |
Returns
参数对象 — 用于函数签名中声明约束
Example
fastapi
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/search")
async def search(
q: str | None = Query(default=None, min_length=3, max_length=50)
):
return {"q": q}BackgroundTasks.add_task(func, *args)向后台任务队列添加函数,响应返回后再异步执行。
Parameters
| Name | Type | Description |
|---|---|---|
| func | Callable | 待执行的后台函数 |
| args | tuple | 传给函数的位置参数 |
Returns
None — 任务加入队列,响应后执行
Example
fastapi
from fastapi import FastAPI, BackgroundTasks
app = FastAPI()
def send_email(to: str, body: str):
print(f"mail to {to}: {body}")
@app.post("/notify/{email}")
async def notify(email: str, tasks: BackgroundTasks):
tasks.add_task(send_email, email, "Welcome!")
return {"status": "queued"}