Python FastAPI 入门指南：从零构建第一个 API 接口

建议采用第一种方式，方便调试。启动后访问 http://127.0.0.1:8000，将看到返回的 JSON 数据：

此时，第一个 Web 接口已正常运行。

三、自动文档功能

FastAPI 的核心优势之一是自动生成接口文档。无需编写任何文档代码，只需访问：

http://127.0.0.1:8000/docs

你会看到 Swagger UI 界面。这是根据代码自动生成的接口文档。以往需要手动填写 URL 和参数进行测试，现在可以直接在网页上点击 Try it out，填入参数即可执行。

四、参数接收方式

后端开发的核心流程是：接收数据 -> 处理数据 -> 返回结果。FastAPI 主要支持两种参数传递方式。

1. 路径参数 (Path Parameters)

场景：查询特定 ID 的资源，例如 /student/5。

from fastapi import FastAPI
import uvicorn

app = FastAPI()

@app.get("/student/{student_id}")
def get_student(student_id: int):
    return {
        "学生 ID": student_id,
        "类型": str(type(student_id))
    }

if __name__ == "__main__":
    uvicorn.run(app="main:app", host="127.0.0.1", port=8088)

注意函数参数中的 student_id: int。如果你访问 /student/5，FastAPI 会自动转换；如果访问 /student/abc，则会报错提示类型不匹配。这就是类型检查的作用。

2. 查询参数 (Query Parameters)

场景：类似搜索功能，例如 /search?keyword=python&page=1。

在 FastAPI 中，未出现在路径中的函数参数默认为查询参数。

from fastapi import FastAPI
import uvicorn

app = FastAPI()

@app.get("/search")
def search_data(keyword: str, page: int = 1):
    return {
        "你搜的词": keyword,
        "当前页码": page
    }

if __name__ == "__main__":
    uvicorn.run(app="main:app", host="127.0.0.1", port=8088)

访问 /search?keyword=apple 会返回默认页码 1；若添加 &page=5，则返回指定页码。

五、数据模型验证

处理复杂数据（如注册信息）时，逐个定义参数较为繁琐。FastAPI 引入 Pydantic 来定义数据的结构。

from fastapi import FastAPI
import uvicorn
from pydantic import BaseModel

app = FastAPI()

# 定义数据模型
class UserInfo(BaseModel):
    username: str
    password: str
    age: int = 18
    is_student: bool = True

@app.post("/register")
def register(user: UserInfo):
    if user.age < 18:
        return {"message": "未成年人禁止注册", "code": 400}
    return {
        "message": "注册成功",
        "用户": user.username,
        "身份": "学生" if user.is_student else "社会人"
    }

if __name__ == "__main__":
    uvicorn.run(app="main:app", host="127.0.0.1", port=8088)

测试该 POST 接口时，打开 /docs 页面，找到 /register，点击 Try it out，修改 Request body 中的 JSON 数据并执行。FastAPI 会自动解析 JSON 并映射到 user 变量，无需手动编写解析逻辑。

六、总结

掌握以下内容，即可胜任基础的 FastAPI 开发：

1. 安装：使用 pip 安装 fastapi 和 uvicorn。
2. 启动：理解 uvicorn 作为 ASGI 服务器的作用。
3. 文档：利用 /docs 自动生成接口文档进行调试。
4. 参数：通过类型提示约束路径和查询参数。
5. 模型：使用 BaseModel 处理复杂的 POST 数据。

FastAPI 不仅能提升编码效率，还能通过类型系统保证代码的健壮性与规范性。