第3章 - 第一个 API

嗨，朋友！我是长安。

这一章我们要正式开始写代码了！说实话，我还记得当年第一次看到 FastAPI 这么简洁的代码就能写出接口时，那种惊喜的感觉。现在，我希望把这份惊喜传递给你！

🎯 本章目标

  • 理解 FastAPI 的基本结构
  • 学会创建 GET 和 POST 接口
  • 理解装饰器的作用
  • 学会使用自动文档

1️⃣ 最简单的 API

让我们从最简单的代码开始，就这么几行：

# main.py
from fastapi import FastAPI

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

# 创建一个 GET 接口
@app.get("/")
def home():
    return {"message": "欢迎来到 FastAPI 世界！"}

代码解释

from fastapi import FastAPI

从 fastapi 库中导入 FastAPI 类。

app = FastAPI()

创建一个 FastAPI 应用实例，这个 app 就是我们的应用。

@app.get("/")

这是一个装饰器，告诉 FastAPI：

  • 当用户访问 / 路径时
  • 使用 GET 方法
  • 执行下面的函数
def home():
    return {"message": "欢迎来到 FastAPI 世界！"}

这是处理请求的函数，返回一个字典，FastAPI 会自动转换成 JSON。

运行测试

uvicorn main:app --reload

访问 http://127.0.0.1:8000，你会看到：

{"message": "欢迎来到 FastAPI 世界！"}

2️⃣ HTTP 方法

HTTP 有多种请求方法，最常用的有：

方法用途示例
GET获取数据获取用户列表
POST创建数据创建新用户
PUT更新数据（全量）更新用户所有信息
PATCH更新数据（部分）只更新用户名
DELETE删除数据删除用户

创建不同方法的接口

from fastapi import FastAPI

app = FastAPI()

# GET - 获取数据
@app.get("/users")
def get_users():
    return {"users": ["张三", "李四", "王五"]}

# POST - 创建数据
@app.post("/users")
def create_user():
    return {"message": "用户创建成功"}

# PUT - 更新数据
@app.put("/users/1")
def update_user():
    return {"message": "用户更新成功"}

# DELETE - 删除数据
@app.delete("/users/1")
def delete_user():
    return {"message": "用户删除成功"}

3️⃣ 返回不同类型的数据

FastAPI 可以返回多种类型的数据：

返回字典（最常用）

@app.get("/dict")
def return_dict():
    return {"name": "张三", "age": 18}

结果：

{"name": "张三", "age": 18}

返回列表

@app.get("/list")
def return_list():
    return [1, 2, 3, 4, 5]

结果：

[1, 2, 3, 4, 5]

返回嵌套数据

@app.get("/nested")
def return_nested():
    return {
        "code": 200,
        "message": "success",
        "data": {
            "users": [
                {"id": 1, "name": "张三"},
                {"id": 2, "name": "李四"}
            ],
            "total": 2
        }
    }

结果：

{
    "code": 200,
    "message": "success",
    "data": {
        "users": [
            {"id": 1, "name": "张三"},
            {"id": 2, "name": "李四"}
        ],
        "total": 2
    }
}

4️⃣ 给 API 添加描述

为了让 API 文档更清晰，我们可以添加描述信息：

from fastapi import FastAPI

# 给应用添加标题和描述
app = FastAPI(
    title="我的第一个 API",
    description="这是一个学习 FastAPI 的示例项目",
    version="1.0.0"
)

@app.get(
    "/",
    summary="首页",
    description="返回欢迎信息"
)
def home():
    """
    这是首页接口
    
    - 无需参数
    - 返回欢迎信息
    """
    return {"message": "欢迎！"}

@app.get(
    "/users",
    summary="获取用户列表",
    description="获取所有用户的列表",
    tags=["用户管理"]  # 给接口分组
)
def get_users():
    """
    获取所有用户
    
    返回用户列表，包含：
    - 用户ID
    - 用户名
    """
    return {"users": ["张三", "李四"]}

访问 http://127.0.0.1:8000/docs 查看效果！

5️⃣ 使用 Tags 分组

当接口很多时，可以用 tags 进行分组：

from fastapi import FastAPI

app = FastAPI()

# 用户相关接口
@app.get("/users", tags=["用户管理"])
def get_users():
    return {"users": []}

@app.post("/users", tags=["用户管理"])
def create_user():
    return {"message": "创建成功"}

# 商品相关接口
@app.get("/products", tags=["商品管理"])
def get_products():
    return {"products": []}

@app.post("/products", tags=["商品管理"])
def create_product():
    return {"message": "创建成功"}

在文档中，接口会按 tags 分组显示，非常清晰！

6️⃣ 完整示例

from fastapi import FastAPI

app = FastAPI(
    title="FastAPI 学习示例",
    description="第3章 - 第一个 API",
    version="1.0.0"
)

# 模拟数据库
fake_users_db = [
    {"id": 1, "name": "张三", "age": 20},
    {"id": 2, "name": "李四", "age": 25},
    {"id": 3, "name": "王五", "age": 30},
]

@app.get("/", tags=["首页"])
def home():
    """首页接口"""
    return {
        "message": "欢迎使用 FastAPI！",
        "docs": "访问 /docs 查看 API 文档"
    }

@app.get("/users", tags=["用户管理"], summary="获取用户列表")
def get_users():
    """获取所有用户列表"""
    return {
        "code": 200,
        "data": fake_users_db,
        "total": len(fake_users_db)
    }

@app.get("/users/{user_id}", tags=["用户管理"], summary="获取单个用户")
def get_user(user_id: int):
    """根据 ID 获取单个用户"""
    for user in fake_users_db:
        if user["id"] == user_id:
            return {"code": 200, "data": user}
    return {"code": 404, "message": "用户不存在"}

@app.post("/users", tags=["用户管理"], summary="创建用户")
def create_user():
    """创建新用户"""
    return {"code": 200, "message": "用户创建成功"}

@app.delete("/users/{user_id}", tags=["用户管理"], summary="删除用户")
def delete_user(user_id: int):
    """删除指定用户"""
    return {"code": 200, "message": f"用户 {user_id} 删除成功"}

7️⃣ 使用自动文档

FastAPI 自动生成两种文档：

Swagger UI（推荐）

访问：http://127.0.0.1:8000/docs

特点：

  • 可以直接在页面上测试接口
  • 界面美观，交互友好
  • 支持填写参数并发送请求

ReDoc

访问：http://127.0.0.1:8000/redoc

特点：

  • 文档风格更正式
  • 适合作为 API 文档分享
  • 只读，不能测试

📝 小结

本章我们学习了：

  1. ✅ FastAPI 的基本结构
  2. ✅ 创建 GET、POST、PUT、DELETE 接口
  3. ✅ 返回不同类型的数据
  4. ✅ 给 API 添加描述和分组
  5. ✅ 使用自动文档

🏃 下一步

现在你已经会创建基本的接口了，但是接口还不能接收参数。下一章我们学习如何处理路径参数！

👉 第4章 - 路径参数

💪 练习题

  1. 创建一个图书管理的 API，包含以下接口：

    • GET /books - 获取所有图书
    • GET /books/{book_id} - 获取单本图书
    • POST /books - 添加图书
    • DELETE /books/{book_id} - 删除图书

  2. 给所有接口添加 tags 和描述

  3. 访问 /docs 页面，测试你创建的接口

参考答案
from fastapi import FastAPI

app = FastAPI(title="图书管理系统")

fake_books = [
    {"id": 1, "title": "Python入门", "author": "张三"},
    {"id": 2, "title": "FastAPI实战", "author": "李四"},
]

@app.get("/books", tags=["图书管理"], summary="获取所有图书")
def get_books():
    """获取图书列表"""
    return {"books": fake_books}

@app.get("/books/{book_id}", tags=["图书管理"], summary="获取单本图书")
def get_book(book_id: int):
    """根据ID获取图书"""
    for book in fake_books:
        if book["id"] == book_id:
            return book
    return {"message": "图书不存在"}

@app.post("/books", tags=["图书管理"], summary="添加图书")
def create_book():
    """添加新图书"""
    return {"message": "添加成功"}

@app.delete("/books/{book_id}", tags=["图书管理"], summary="删除图书")
def delete_book(book_id: int):
    """删除图书"""
    return {"message": f"图书 {book_id} 删除成功"}
最近更新:
Contributors: 王长安