FastAPI （第三章 核心功能）

任务：第一步

• 扩展第一个 FastAPI 应用，添加路径参数。
• 理解路径操作的基本概念。
• 测试新端点并查看自动文档。

---

详细讲解：第一步

1. 路径操作基础

• 什么是路径操作：
  • 在 FastAPI 中，路径操作（Path Operation）是指通过特定的 HTTP 方法（GET、POST 等）和路径（URL）定义的 API 端点。
  • 例如，@app.get("/") 定义了一个 GET 方法的根路径端点。
• HTTP 方法：
  • FastAPI 支持常见的 HTTP 方法：GET（读取）、POST（创建）、PUT（更新）、DELETE（删除）等。
  • 在“第一步”中，我们主要关注 GET 方法。
• 路径：
  • 路径是 URL 中的部分，例如 /items 或 /users/123。
  • 路径可以是静态的（如 /items），也可以包含动态参数（如 /items/{item_id}）。

2. 路径参数（Path Parameters）

• 什么是路径参数：
  • 路径参数是 URL 路径中的动态部分，用 {} 包裹，例如 /items/{item_id}。
  • FastAPI 会从路径中提取参数值，并传递给函数。
• 类型注解：
  • FastAPI 使用 Python 类型注解来定义参数类型，例如 item_id: int。
  • FastAPI 会自动将路径中的字符串转换为指定类型（例如将 "123" 转为整数 123）。
  • 如果类型不匹配（例如 /items/abc 传入非整数），FastAPI 会返回 422 错误（验证失败）。
• 示例代码：

  from fastapi import FastAPI
  
  app = FastAPI()
  
  @app.get("/items/{item_id}")
  def read_item(item_id: int):
      return {"item_id": item_id}
  

• 代码解析：
  • @app.get("/items/{item_id}")：定义一个 GET 端点，路径为 /items/{item_id}。
  • item_id: int：路径参数 item_id 应为整数，FastAPI 会自动转换。
  • return {"item_id": item_id}：返回一个字典，包含提取的参数值。
• 运行与测试：
  • 运行：uvicorn main:app --reload。
  • 访问：http://127.0.0.1:8000/items/123。
    • 预期响应：{"item_id": 123}。
  • 访问：http://127.0.0.1:8000/items/abc。
    • 预期响应：{"detail":[{"loc":["path","item_id"],"msg":"value is not a valid integer","type":"type_error.integer"}]}（422 错误）。

3. 自动文档更新

• Swagger UI：
  • 访问：http://127.0.0.1:8000/docs。
  • 新端点 /items/{item_id} 会自动出现在文档中。
  • 点击端点，输入 item_id（例如 123），点击 “Execute” 测试。
• 参数类型：
  • 文档会显示 item_id 的类型为整数（integer）。
  • 如果输入非整数，Swagger UI 会提示错误。
• ReDoc：
  • 访问：http://127.0.0.1:8000/redoc。
  • 同样会显示新端点，格式更适合静态文档。

4. 路径参数的更多用法

• 多个路径参数：
  • 可以定义多个路径参数，例如 /users/{user_id}/items/{item_id}。
  • 示例：

    @app.get("/users/{user_id}/items/{item_id}")
    def read_user_item(user_id: int, item_id: int):
        return {"user_id": user_id, "item_id": item_id}
    

  • 测试：http://127.0.0.1:8000/users/1/items/100。
    • 响应：{"user_id": 1, "item_id": 100}。
• 字符串类型参数：
  • 路径参数不仅限于整数，也可以是字符串。
  • 示例：

    @app.get("/users/{username}")
    def read_user(username: str):
        return {"username": username}
    

  • 测试：http://127.0.0.1:8000/users/alice。
    • 响应：{"username": "alice"}。
• 路径参数的顺序：
  • FastAPI 按照路径的定义顺序匹配。
  • 例如，先定义 /items/{item_id}，再定义 /items/me，FastAPI 会优先匹配 /items/me。
  • 示例：

    @app.get("/items/me")
    def read_me():
        return {"message": "This is me"}
    
    @app.get("/items/{item_id}")
    def read_item(item_id: int):
        return {"item_id": item_id}
    

  • 测试：
    • /items/me：{"message": "This is me"}。
    • /items/123：{"item_id": 123}。

5. 实践任务

• 修改代码：
  • 在 main.py 中，保留之前的 / 端点，添加一个新端点 /items/{item_id}。
  • 完整代码：

    from fastapi import FastAPI
    
    app = FastAPI()
    
    @app.get("/")
    def read_root():
        return {"message": "Hello, FastAPI"}
    
    @app.get("/items/{item_id}")
    def read_item(item_id: int):
        return {"item_id": item_id}
    

• 运行与测试：
  • 运行：uvicorn main:app --reload。
  • 测试以下 URL：
    • http://127.0.0.1:8000/items/123（应返回 {"item_id": 123}）。
    • http://127.0.0.1:8000/items/abc（应返回 422 错误）。
• 探索文档：
  • 访问 http://127.0.0.1:8000/docs，找到 /items/{item_id} 端点。
  • 使用 Swagger UI 测试，输入不同值（整数和非整数），观察响应。
• 额外挑战：
  • 添加一个端点 /users/{username}，返回 {"username": username}。
  • 测试：http://127.0.0.1:8000/users/alice。
  • 添加一个端点 /users/me，返回 {"message": "This is the current user"}，并测试路径匹配顺序。

6. 常见问题与调试

• 路径参数未提取：
  • 错误：item_id 值为 None 或未定义。
  • 解决：检查路径是否正确定义（{item_id}），确保函数参数名与路径参数名一致。
• 类型转换失败：
  • 错误：value is not a valid integer。
  • 解决：确认输入值是否符合类型（例如 item_id 应为数字），或将类型改为 str。
• 路径冲突：
  • 如果定义了 /items/me 和 /items/{item_id}，但顺序错误，可能导致匹配问题。
  • 解决：将更具体的路径（/items/me）放在更通用路径（/items/{item_id}）之前。

---