Python使用FastAPI从零构建首个Web API

目标与前置准备

本教程的目标是在本地环境中成功运行一个基于 FastAPI 的 Web 服务，实现基础路由响应、参数传递与数据校验。为确保开发顺利，请确认终端满足以下条件：

• Python 版本：需 Python 3.7 及以上。运行 python --version 核对。
• 基础语法：熟悉函数定义、字典操作与基础控制流。

打开终端，执行以下命令安装核心依赖：

pip install fastapi
pip install "uvicorn[standard]"

第1步：创建项目入口文件

在项目根目录新建 main.py。该文件将作为应用的统一入口，负责注册路由与实例化服务：

from fastapi import FastAPI

# 创建应用实例
app = FastAPI()

# 绑定 GET / 路由
@app.get("/")
def read_root():
    return {"message": "欢迎来到 FastAPI 的世界！"}

第2步：启动本地服务

FastAPI 自身仅包含路由逻辑，需借助 Uvicorn 提供异步服务器能力。在 main.py 同级目录下打开终端：

uvicorn main:app --reload

main 对应文件名（不带扩展名），app 为代码中的变量名，--reload 开启热重载以支持开发期即时生效。终端显示 Uvicorn running on http://127.0.0.1:8000 即表示启动成功，此时访问该地址将返回定义的 JSON 响应。

第3步：验证自动文档功能

利用 FastAPI 的类型推导特性，无需额外编写说明即可自动生成调试界面。浏览器访问 http://127.0.0.1:8000/docs 可查看 Swagger UI 面板，点击 “Try it out” 直接测试接口返回值。如需更换渲染风格，可切换至 /redoc 查看。

第4步：接收路径与查询参数

在实际业务中，通常需要通过 URL 传递标识或筛选条件。修改 main.py 追加以下逻辑：

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "query_string": q}

大括号内的 {item_id} 用于捕获路径变量，声明 : int 后框架会自动执行类型转换，非法字符将触发 422 错误而非服务崩溃。q 未绑定路径占位符时，默认解析为 URL 查询参数（如 ?q=apple）。

第5步：处理 POST 请求与数据校验

提交结构化数据（如用户注册或订单创建）推荐使用 POST 方法。FastAPI 内置 Pydantic 库，可通过定义模型自动完成反序列化与字段校验：

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = None

@app.post("/items/")
def create_item(item: Item):
    return {"item_name": item.name, "item_price": item.price, "status": "创建成功"}

当客户端 Payload 缺失必填字段或类型不符时，框架会自动拦截并返回详细的报错提示，彻底替代繁琐的手动判断逻辑。

常见问题排查

1. 服务无响应：切勿使用 python main.py 直接运行脚本。必须通过 uvicorn main:app --reload 调用 ASGI 服务器启动进程。
2. 文档无法展示参数约束：若接口未声明类型提示（如 def read_item(item_id):），类型推断失效会导致自动生成文档缺失校验规则。始终为参数附加明确类型注解。
3. 路由命中异常：FastAPI 严格按代码书写顺序匹配路由。若先写 @app.get("/users/{user_id}") 再写 @app.get("/users/me")，访问后者会被误判为路径参数。**修正策略**：将固定静态路径置于动态路径参数上方。

总结

至此已完成首个 FastAPI 服务的搭建，掌握了路由映射、参数提取与模型校验的核心链路。结合官方文档对依赖注入、后台任务及 WebSocket 的进阶实践，可逐步支撑复杂业务场景。以上就是使用FastAPI从零构建首个Web API的详细内容，更多关于Python后端框架与接口开发的资料请关注本站其它相关文章！