🎬 HoRain云小助手：个人主页

 🔥 个人专栏: 《Linux 系列教程》《c语言教程》

⛺️生活的理想，就是为了理想的生活!

---

⛳️ 推荐

前些天发现了一个超棒的服务器购买网站，性价比超高，大内存超划算！忍不住分享一下给大家。点击跳转到网站。

专栏介绍

专栏名称	专栏介绍
《C语言》	本专栏主要撰写C干货内容和编程技巧，让大家从底层了解C，把更多的知识由抽象到简单通俗易懂。
《网络协议》	本专栏主要是注重从底层来给大家一步步剖析网络协议的奥秘，一起解密网络协议在运行中协议的基本运行机制！
《docker容器精解篇》	全面深入解析 docker 容器，从基础到进阶，涵盖原理、操作、实践案例，助您精通 docker。
《linux系列》	本专栏主要撰写Linux干货内容，从基础到进阶，知识由抽象到简单通俗易懂，帮你从新手小白到扫地僧。
《python 系列》	本专栏着重撰写Python相关的干货内容与编程技巧，助力大家从底层去认识Python，将更多复杂的知识由抽象转化为简单易懂的内容。
《试题库》	本专栏主要是发布一些考试和练习题库（涵盖软考、HCIE、HRCE、CCNA等）

目录

⛳️ 推荐

专栏介绍

一、请求处理

1. 路径参数

2. 查询参数

3. 请求体

4. 其他请求类型

二、响应处理

1. 响应类型

2. 状态码设置

3. 响应模型

4. 异常处理

三、关键注意事项

---

FastAPI 通过自动解析请求参数并灵活构建响应简化了 API 开发流程。其核心机制包括：路径参数、查询参数、请求体等输入处理方式，以及JSON 响应、自定义状态码、异常处理等输出控制手段。开发者只需关注业务逻辑，框架会自动完成数据校验、序列化及文档生成。

---

一、请求处理

1. 路径参数

通过 URL 路径中的动态部分传递参数，自动进行类型转换与校验：

• 直接在路径中用 {} 定义，如 /items/{item_id}。
• 支持通过 Path 添加额外校验规则（如范围、长度）：

  from fastapi import Path
  
  @app.get("/items/{item_id}")
  def read_item(item_id: int = Path(..., gt=0, description="ID 必须大于 0")):
      return {"item_id": item_id}
  

  • gt=0 限制参数值必须 大于 0，否则返回 422 验证错误。

2. 查询参数

位于 URL ? 之后的键值对，无需路径装饰器显式声明：

• 可设置默认值（可选参数）或省略默认值（必填参数）：

  @app.get("/search")
  def search(q: str, limit: int = 10):  # q 为必填，limit 默认 10
      return {"query": q, "limit": limit}
  

• 通过 Query 添加校验（如长度、正则）：

  from fastapi import Query
  
  @app.get("/users")
  def get_users(keyword: str = Query(..., min_length=2, max_length=10)):
      return {"keyword": keyword}
  

  • min_length=2 要求参数 至少 2 个字符。

3. 请求体

用于提交复杂数据（如 JSON），需通过 Pydantic 模型定义结构：

• 定义模型并自动校验：

  from pydantic import BaseModel
  
  class ItemCreate(BaseModel):
      name: str
      price: float = Field(..., gt=0)  # 价格必须 **大于 0**
  
  @app.post("/items")
  def create_item(item: ItemCreate):
      return item
  

• 若数据格式错误（如价格为负数），框架自动返回 422 错误及具体原因。

4. 其他请求类型

• 请求头/ Cookie：通过 Header、Cookie 注入参数。
• 文件上传：使用 UploadFile 处理 multipart/form-data 请求。
• 原始请求对象：通过 Request 类获取完整请求信息（如客户端 IP）。

---

二、响应处理

1. 响应类型

• 默认 JSON 响应：直接返回字典或 Pydantic 模型，自动序列化。
• 自定义响应：
  • JSONResponse：手动控制状态码、响应头等：

    from fastapi.responses import JSONResponse
    
    @app.get("/custom")
    def custom_response():
        return JSONResponse(
            content={"msg": "自定义内容"},
            status_code=201,  # **显式设置状态码**
            headers={"X-Custom": "value"}
        )
    

  • FileResponse：返回文件下载；StreamingResponse：处理大文件流。

2. 状态码设置

• 推荐使用 status 模块常量，避免硬编码数字：

  from fastapi import status
  
  @app.post("/items", status_code=status.HTTP_201_CREATED)
  def create_item():
      return {"msg": "资源已创建"}
  

  • HTTP_201_CREATED 表示 资源创建成功，比直接写 201 更清晰可读。
• 动态设置状态码：通过 response 参数修改：

  from fastapi import Response
  
  @app.get("/user/{id}")
  def get_user(id: int, response: Response):
      if not user_exists(id):
          response.status_code = status.HTTP_404_NOT_FOUND
          return {"detail": "用户不存在"}
      return {"user": "data"}
  

  • 注意：仅修改元数据，仍需返回业务数据。

3. 响应模型

通过 response_model 强制规范返回结构：

class UserOut(BaseModel):
    id: int
    name: str
    # 自动过滤多余字段（如数据库模型中的 password）

@app.get("/users/{id}", response_model=UserOut)
def get_user(id: int):
    return db.query(User).filter(User.id == id).first()

• 作用：确保输出格式统一，避免前端因字段变动出错；自动同步至 API 文档。

4. 异常处理

• 抛出 HTTP 异常：

  from fastapi import HTTPException
  
  @app.get("/items/{id}")
  def read_item(id: int):
      if item_not_found(id):
          raise HTTPException(
              status_code=404,
              detail="**资源未找到**",
              headers={"X-Error": "Item ID 无效"}
          )
  

• 自定义异常处理器：

  @app.exception_handler(UnicornException)
  async def unicorn_exception_handler(_, exc):
      return JSONResponse(
          status_code=418,
          content={"message": f"自定义错误：{exc.name}"}
      )
  

  • 适用于业务逻辑中的特定错误类型。

---

三、关键注意事项

1. 请求体只能读取一次：若在中间件中读取了 request.body()，需缓存结果供后续使用，否则接口函数无法解析数据。
2. response 参数的正确用法：仅用于设置 Cookie 或头信息，不可直接返回 response 对象，否则会覆盖自动序列化逻辑。
3. 文档自动生成：所有参数和响应定义会自动同步至 /docs（Swagger UI），无需手动维护文档。

通过合理组合上述机制，开发者能高效构建类型安全、文档完备、符合 REST 规范的 API 服务。实际开发中，建议优先使用 Pydantic 模型管理数据，并通过 status 模块管理状态码，以提升代码可维护性。

❤️❤️❤️本人水平有限，如有纰漏，欢迎各位大佬评论批评指正！😄😄😄

💘💘💘如果觉得这篇文对你有帮助的话，也请给个点赞、收藏下吧，非常感谢!👍 👍 👍

🔥🔥🔥Stay Hungry Stay Foolish 道阻且长,行则将至,让我们一起加油吧！🌙🌙🌙