Python FastAPI 入门教程：从零跑通第一个接口

启动服务有两种常见方式。

一种是直接在代码里保留 if __name__ == "__main__": 这段入口，然后运行 main.py。

另一种是在终端里执行：

uvicorn main:app

如果你只是本地试验，我更推荐第一种写法，方便直接调试。

服务启动后，访问 http://127.0.0.1:8000，如果看到类似下面的返回，就说明第一个接口已经跑通了：

{"message":"Hello World"}

FastAPI 的自动文档

FastAPI 最让人印象深刻的地方之一，就是它会根据代码自动生成接口文档。你不用额外写 Swagger 配置，也不用手动维护一份文档和代码同步。

启动项目后，直接访问：

http://127.0.0.1:8000/docs

你会看到一个可交互的 Swagger UI 页面。接口、参数、请求体、返回值都能直接在页面里试，这对开发调试非常友好。很多时候，接口还没接上前端，我就会先在这个页面里把请求流程验证一遍。

接收数据的两种常见方式

后端开发最常做的事，说白了就是三步：接收数据、处理数据、返回结果。FastAPI 在接收数据这件事上做得很顺手，常见场景主要分两类：路径参数和查询参数。

路径参数

路径参数通常出现在'根据某个 ID 查详情'这种场景里。比如请求某个学生的信息，URL 可能长这样：/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 会把 5 自动转换成整数；如果你传的是 /student/abc，它会直接报错，因为这已经不符合 int 的约束了。对新手来说，这种'在入口处就帮你挡住错误'的体验特别省心。

查询参数

查询参数更像搜索场景，例如：/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)

这里 page: int = 1 表示 page 有默认值。也就是说：

• 访问 /search?keyword=apple 时，page 会自动取默认值 1。
• 访问 /search?keyword=apple&page=5 时，page 会变成 5。

这种写法非常适合做分页、筛选、排序这类接口。

用 Pydantic 定义数据模型

当接口参数变多以后，把所有字段一股脑堆进函数签名里会很乱。更好的方式，是把这些字段收拢成一个数据模型。FastAPI 依赖 Pydantic 来做这件事，它能帮你定义数据结构，并自动完成校验和解析。

比如注册接口，前端通常会提交用户名、密码、年龄、是否学生等信息。这个时候，用模型来描述请求体会清晰很多：

from fastapi import FastAPI
import uvicorn
from pydantic import BaseModel

# 1. 定义请求体模型
class UserInfo(BaseModel):
    username: str
    password: str
    age: int = 18
    is_student: bool = True

app = FastAPI()

# 2. 在接口中直接接收模型
@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)

这段代码的思路很直接：前端传来的 JSON 会被 FastAPI 自动转换成 UserInfo 对象，你在函数里可以直接通过 user.username、user.age 这种方式取值，不需要自己手动解析 JSON。

测试这个 POST 接口时，最省事的方法就是打开 /docs，找到 /register，点击 Try it out，修改请求体，再点 Execute。整个过程非常直观，连调试工具都省了不少。

小结

到这里，你已经把 FastAPI 最基础、也最关键的骨架搭起来了：

• 会安装 FastAPI 和 Uvicorn
• 会启动一个最小接口
• 知道如何接收路径参数和查询参数
• 会用 BaseModel 处理 POST 请求体
• 会通过 /docs 快速测试接口

如果你是刚接触 Python Web 开发，FastAPI 很适合拿来做第一个正式框架。它的语法干净，类型提示清楚，自动文档也能帮你省掉很多重复劳动。等你把这些基础内容跑顺了，后面接数据库、做登录注册、做权限控制，都会顺畅很多。