一、FastAPI 基础概念

• 异步特性（async/await）对我的意义：

  await 是“非阻塞的等待”，而普通函数调用是“阻塞的等待”。

  async 用于定义一个协程函数，调用时不会立即执行，而是返回一个协程对象。两者配合实现非阻塞等待。

  ---

• 如何启动服务（uvicorn main:app --reload）：

  学习了FastAPI服务器的基本配置与调用，使用

  ---

• 自动生成的交互文档路径：

  自动生成的交互文档路径：/docs 和 /redoc，默认在 http://127.0.0.1:8000/docs 可访问，用于在线测试和查看接口定义。这让测试变得方便快捷

  ---

二、路由与参数

• 路径参数（/user/{id}）
  • 作用：让同一个接口能根据不同的输入，返回不同的输出，实现动态交互
  • 类型注解与 Path 校验：description注解，gt/ge，lt/le,max_length/min_length
• 查询参数（?skip=0&limit=10）
  • 作用：用来怎么选，比如排序，分类
  • Query 函数用法：用法与Path 相似
• 请求体（POST 请求携带的数据）
  • 与路径/查询参数的区别：其是为服务器提供数据的

三、数据校验（Pydantic）

• BaseModel 的作用：他能帮助我们自动校验、类型转换和序列化

• 具体写法如下：

  class ChatRequest(BaseModel):
  
  message: str = Field(..., description="用户输入的消息", min_length=1)

• Field 常用参数：

  • ...（必填） / 默认值
  • min_length / max_length
  • gt / lt（数值）

• 请求体自动校验失败时返回的状态码：自动返回 422 Unprocessable Entity 状态码

四、响应处理

• 直接返回 dict / Pydantic 模型

  FastAPI 会自动将返回的字典或 Pydantic 模型对象转换为 JSON 格式，并设置正确的 Content-Type: application/json

• response_model 的作用：限制和格式化服务器返回给客户端的数据

  例如：*@app.post("/chat", response_model=ChatResponse)*

• response_class 与 response_model 的区别：

  model改变了响应的数据结构，而class改变响应的媒体格式，且二者可以同时使用

  ---

• 返回文件（FileResponse）场景：后续拓展

五、与外部 API 交互（以 DeepSeek 为例）

• 为什么要用环境变量存储 API Key：

  安全且高效

  ---

• OpenAI 客户端初始化（base_url 作用）：

  告诉客户端将请求发送到哪个服务器地址

  ---

• 构造 messages 列表的格式：

   messages = [{"role": "user", "content": request.message}]

  这是 OpenAI API 标准的对话消息格式，role 可以是 user、assistant、system。DeepSeek 完全兼容此格式。

• 调用 client.chat.completions.create 的核心参数：

  • model：
  • temperature：
  • max_tokens：
  • 本周并未进行模型具体调优学习，下周进行深入学习

• 异常处理（try...except + HTTPException）：

  捕获异常，并通过

  raise HTTPException(status_code=500, detail=str(e))

  返回异常

  ---

六、前后端交互与 CORS

• 前端 fetch 基本用法（本周仅实践，未深入原理）

  • 方法（method）：POST
  • 请求头（headers）：'Content-Type': 'application/json'
  • 请求体（body 与 JSON.stringify）：将 { message } 转为 JSON 字符串
  • 处理响应（res.ok、res.json()）：检查状态码，解析 JSON

  详细机制将在后续前端课程中学习。

• 错误处理（网络错误、HTTP 错误状态）

  已实现简单的错误提示，但未系统学习。后续会补充。

• CORS 跨域问题

  为了解决浏览器“file://”协议或不同端口导致的跨域限制，在后端添加了 CORSMiddleware，允许所有源。具体原理和配置细节待深入学习。

七、常见问题与解决（踩坑记录）