首页
/ 正文

第一个 FastAPI 应用（一文讲透）

更新时间: 2025-04-14 23:30:11

💡一则或许对你有用的小广告

欢迎加入小哈的星球 ，你将获得：专属的项目实战 / 1v1 提问 / Java 学习路线 / 学习打卡 / 每月赠书 / 社群讨论

新项目:《从零手撸：仿小红书（微服务架构）》 正在持续爆肝中，基于 Spring Cloud Alibaba + Spring Boot 3.x + JDK 17...，点击查看项目介绍 ;演示链接： http://116.62.199.48:7070 ;

《从零手撸：前后端分离博客项目（全栈开发）》 2 期已完结，演示链接： http://116.62.199.48/ ;

截止目前，星球内专栏累计输出 90w+ 字，讲解图 3441+ 张，还在持续爆肝中.. 后续还会上新更多项目，目标是将 Java 领域典型的项目都整一波，如秒杀系统, 在线商城, IM 即时通讯，权限管理，Spring Cloud Alibaba 微服务等等，已有 3100+ 小伙伴加入学习，欢迎点击围观

前言：为什么选择 FastAPI？

在当今互联网时代，API（应用程序编程接口）已成为连接不同系统的核心桥梁。无论是移动应用、Web 应用还是物联网设备，都需要通过 API 实现数据交互。而 FastAPI 作为 Python 领域的后起之秀，凭借其高性能、易读性和开发者友好性，迅速成为构建 API 的首选框架。

FastAPI 的核心优势在于：

基于 Python 3.7+ 的现代特性，如类型提示（Type Hints），极大提升了代码的可读性和可维护性；
自动文档生成，开发者无需额外编写说明文档，用户可通过交互式界面直接测试 API；
异步支持，在处理高并发场景时，性能远超传统框架；
简洁直观的代码风格，让新手也能快速上手。

本篇文章将通过一个实际案例，带领读者从零开始构建第一个 FastAPI 应用，涵盖基础功能实现、参数处理、数据验证等核心知识点，帮助读者掌握构建现代 API 的核心技能。

环境准备：搭建开发环境

安装 FastAPI 和 Uvicorn

FastAPI 本身是一个轻量级框架，需要配合 ASGI 服务器运行。推荐使用 uvicorn 作为开发服务器：

pip install fastapi uvicorn

工具推荐

代码编辑器：VS Code、PyCharm 等支持调试和代码补全的工具；
API 测试工具：Postman 或 Swagger UI（FastAPI 内置支持）；
虚拟环境：建议使用 python -m venv 创建独立环境，避免依赖冲突。

第一个 FastAPI 应用：Hello World

步骤 1：创建基础文件

新建一个名为 main.py 的文件，输入以下代码：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    return {"message": "Hello FastAPI!"}

步骤 2：启动应用

在终端中运行：

uvicorn main:app --reload

访问 http://localhost:8000，你会看到自动生成的交互式文档界面。点击 GET / 接口，点击 Try it out，即可看到返回的 JSON 响应。

代码解析

FastAPI() 实例化应用对象；
@app.get("/") 定义根路径的 GET 请求处理函数；
async def 标记异步函数（FastAPI 默认支持异步）。

扩展功能：路径操作与参数处理

路径操作的丰富性

FastAPI 支持 HTTP 方法的装饰器，如 @app.get()、@app.post()、@app.put()、@app.delete()。例如，创建一个查询用户信息的接口：

@app.get("/users/{user_id}")
async def read_user(user_id: int):
    return {"user_id": user_id, "name": "John Doe"}

访问 http://localhost:8000/users/123，将返回包含用户 ID 的 JSON 数据。

路径参数 vs 查询参数

FastAPI 可以同时处理两种参数类型：

路径参数（Path Parameters）

直接嵌入在 URL 路径中的参数，如 /users/{user_id}。

查询参数（Query Parameters）

附加在 URL 后的键值对，如 /items?skip=0&limit=10：

from fastapi import Query

@app.get("/items/")
async def read_items(skip: int = 0, limit: int = Query(10, ge=1, le=100)):
    return {"skip": skip, "limit": limit}

此处 Query 用于定义参数的默认值、最小值（ge）和最大值（le）。

数据验证与序列化：Pydantic 的强大支持

FastAPI 内置了 Pydantic 库，用于数据验证和序列化。通过类型注解和模型定义，可以实现自动化的数据校验。

示例：定义用户模型

from pydantic import BaseModel

class User(BaseModel):
    id: int
    name: str
    email: str = None
    is_active: bool = True

接收 POST 请求数据

@app.post("/users/")
async def create_user(user: User):
    return {"user_id": user.id, "name": user.name}

当发送 POST 请求时，FastAPI 会自动验证数据格式。例如，若缺少 id 字段，会返回 422 错误：

curl -X POST "http://localhost:8000/users/" -H "Content-Type: application/json" -d '{"name": "Alice"}'

响应结果：

{
  "detail": [
    {
      "loc": ["body", "id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

异步编程：释放 FastAPI 的高性能潜能

FastAPI 的异步能力使其在处理高并发时表现优异。通过 async 和 await 关键字，可以轻松实现非阻塞 I/O 操作。

同步 vs 异步示例

同步代码：

import time

@app.get("/sync/")
def read_sync():
    time.sleep(2)
    return {"status": "Sync done"}

异步代码：

import asyncio

@app.get("/async/")
async def read_async():
    await asyncio.sleep(2)
    return {"status": "Async done"}

当多个请求同时访问 /async/ 时，FastAPI 会并发处理，而 /sync/ 则会逐个阻塞执行。

依赖注入：模块化的代码设计

依赖注入（Dependency Injection）是 FastAPI 的重要特性，用于解耦代码和复用逻辑。

示例：验证用户权限

async def get_current_user(token: str = Depends(oauth2_scheme)):
    user = get_user_from_token(token)
    if not user:
        raise HTTPException(status_code=401, detail="Invalid token")
    return user

@app.get("/protected/")
async def protected_endpoint(current_user: User = Depends(get_current_user)):
    return {"user": current_user.name}

此处 get_current_user 是一个依赖函数，被多个接口复用，实现了权限验证的集中管理。

错误处理与日志记录：完善应用健壮性

自定义异常处理

from fastapi import Request
from fastapi.responses import JSONResponse

@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=422,
        content={"detail": "Validation failed", "errors": exc.errors()},
    )

集成日志

使用 Python 标准库 logging 模块记录请求信息：

import logging

logging.basicConfig(level=logging.INFO)

@app.get("/log/")
async def log_endpoint():
    logging.info("Received a GET request to /log/")
    return {"status": "Logged"}

部署与扩展：从开发到生产环境

部署选项

FastAPI 可以部署在多种服务器上，如：

Uvicorn + Gunicorn：组合使用实现负载均衡；
Docker 容器化：通过 Dockerfile 封装环境；
云服务：AWS、Azure 等平台提供一键部署方案。

示例：Dockerfile 配置

FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["uvicorn", "main:app", "--host", "0.0.0.0"]

结论：迈向更复杂的 API 开发

通过本篇文章的实践，读者已经掌握了从环境搭建到部署的全流程。FastAPI 的类型提示、自动文档、异步支持等特性，使其成为构建现代 API 的理想选择。

建议读者接下来尝试：

实现分页查询和数据库集成；
学习 OAuth2 认证和 JWT 实现；
探索 FastAPI 的 WebSocket 和 GraphQL 支持。

记住，构建第一个 FastAPI 应用只是起点，持续实践和探索将帮助你掌握更多高级技巧，最终开发出高效、可靠的 API 系统。