阶段 1：HTTP / FastAPI

englightened

389人浏览 · 2026-04-23 09:19:13

englightened · 2026-04-23 09:19:13 发布

阶段 1：编程与服务基础

HTTP / FastAPI 核心笔记

1. HTTP 基础

1.1 HTTP 是什么

HTTP（HyperText Transfer Protocol）是客户端和服务端之间进行数据通信的协议。

在后端开发里，最常见的通信模式是：

客户端发送 HTTP 请求
服务端接收请求并处理
服务端返回 HTTP 响应

例如：

浏览器访问网页
前端调用后端接口
后端调用模型 API
服务之间的接口调用

1.2 请求与响应

请求（Request）

一个 HTTP 请求通常包含：

请求方法（Method）
URL
请求头（Headers）
请求体（Body）

响应（Response）

一个 HTTP 响应通常包含：

状态码（Status Code）
响应头（Headers）
响应体（Body）

1.3 URL 的基本结构

示例：

https://api.example.com/users/123?active=true

组成：

https：协议
api.example.com：域名
/users/123：路径（path）
?active=true：查询参数（query params）

1.4 常见 HTTP 方法

GET

用于获取资源。

典型特点：

一般用于查询
参数通常放在 URL 中
不应该用于修改数据

示例：

GET /users/123

POST

用于创建资源或提交数据。

典型特点：

请求体里通常有 JSON 数据
常用于创建、提交、触发操作

示例：

POST /chat

PUT

通常用于整体更新资源。

示例：

PUT /users/123

PATCH

通常用于部分更新资源。

示例：

PATCH /users/123

DELETE

用于删除资源。

示例：

DELETE /users/123

1.5 GET 和 POST 的核心区别

GET

主要用于获取数据
参数通常出现在 URL 中
更符合“只读操作”语义

POST

主要用于提交数据
数据通常在请求体中
常用于创建、触发复杂操作

必须记住

查询通常用 GET
提交或创建通常用 POST
不要用 GET 去做本质上会修改数据的事情

1.6 状态码

状态码用于表示这次请求处理结果。

2xx：成功

200 OK：请求成功
201 Created：创建成功
204 No Content：成功但没有返回内容

4xx：客户端错误

400 Bad Request：请求参数错误
401 Unauthorized：未认证
403 Forbidden：无权限
404 Not Found：资源不存在
422 Unprocessable Entity：请求数据格式合法但校验失败（FastAPI 很常见）

5xx：服务端错误

500 Internal Server Error：服务端内部错误
502 Bad Gateway
503 Service Unavailable

1.7 常见请求头

`Content-Type`

表示请求体或响应体的数据类型。

最常见：

Content-Type: application/json

`Authorization`

用于传认证信息，例如 token。

Authorization: Bearer xxx

`Accept`

告诉服务端客户端希望接收的数据格式。

1.8 JSON Body

现代接口中，请求体最常见的是 JSON。

例如：

{
  "question": "什么是RAG？",
  "top_k": 3
}

在 Python 中通常对应：

{
    "question": "什么是RAG？",
    "top_k": 3
}

1.9 查询参数 / 路径参数 / 请求体

路径参数

参数写在 URL 路径中。

/users/123

这里 123 是路径参数。

查询参数

参数写在 ? 后面。

/users?active=true&page=2

请求体

通常用于 POST/PUT/PATCH，放较复杂的数据。

{
  "name": "Tom",
  "age": 20
}

区分原则

标识某个资源：路径参数
过滤、分页、查询条件：查询参数
提交复杂结构化数据：请求体

1.10 HTTP 的工程意义

后端服务的本质之一，就是：

接收 HTTP 请求
解析参数
执行业务逻辑
返回 HTTP 响应

所以 HTTP 是后端开发、FastAPI、模型 API 调用、RAG 服务封装的基础。

1.11 难点与易错点

不要混淆路径参数和查询参数

/users/123：路径参数
/users?id=123：查询参数

不要把 GET 和 POST 语义乱用

GET 适合查询
POST 适合提交数据

状态码不是随便返回的

成功返回 2xx
参数问题一般是 4xx
服务端异常一般是 5xx

JSON Body 和表单不是一回事

当前阶段重点掌握 JSON Body 即可。

1.12 必须记住

HTTP 是客户端和服务端通信协议
请求由：方法 + URL + 请求头 + 请求体组成
响应由：状态码 + 响应头 + 响应体组成
GET 查数据，POST 提交数据
路径参数、查询参数、请求体要分清
JSON 是现代接口最常见的数据格式

2. FastAPI 基础

2.1 FastAPI 是什么

FastAPI 是 Python 的现代 Web 框架，适合开发：

后端 API
AI 服务接口
RAG 服务
Agent 服务
内部工具平台

它的优势：

语法简洁
类型标注友好
自动生成接口文档
参数校验强
非常适合和 Pydantic 结合

2.2 最小 FastAPI 应用

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def root():
    return {"message": "hello"}

核心组成

app = FastAPI()：创建应用
@app.get("/")：定义一个 GET 路由
def root()：处理请求的函数
return {...}：返回 JSON 响应

2.3 路由（Route）是什么

路由就是：

什么请求方法
对应哪个路径
由哪个函数处理

例如：

@app.get("/users")
def get_users():
    return ["Tom", "Alice"]

@app.post("/chat")
def chat():
    return {"answer": "ok"}

必须记住

@app.get() 处理 GET 请求
@app.post() 处理 POST 请求
@app.put() 处理 PUT 请求
@app.delete() 处理 DELETE 请求

2.4 路径参数

@app.get("/users/{user_id}")
def get_user(user_id: int):
    return {"user_id": user_id}

请求：

GET /users/123

{"user_id": 123}

要点

路径中用 {} 定义参数
函数参数名要对应
类型标注会帮助自动转换和校验

2.5 查询参数

@app.get("/search")
def search(q: str, page: int = 1):
    return {"q": q, "page": page}

请求：

GET /search?q=rag&page=2

要点

没在路径里的普通函数参数，默认会被识别为查询参数
可以设置默认值
类型标注会做基本转换

2.6 请求体（Request Body）

处理复杂 JSON 数据时，通常使用 Pydantic 模型。

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class ChatRequest(BaseModel):
    question: str
    top_k: int = 3

@app.post("/chat")
def chat(req: ChatRequest):
    return {
        "question": req.question,
        "top_k": req.top_k
    }

请求体：

{
  "question": "什么是RAG？",
  "top_k": 5
}

2.7 响应体

FastAPI 默认会把 Python 的 dict / list 自动转成 JSON 响应。

@app.get("/ping")
def ping():
    return {"message": "pong"}

也可以返回列表：

@app.get("/users")
def get_users():
    return [
        {"id": 1, "name": "Tom"},
        {"id": 2, "name": "Alice"}
    ]

2.8 Pydantic：数据校验核心

FastAPI 和 Pydantic 经常一起使用。

`BaseModel`

用于定义请求体或响应体的数据结构。

from pydantic import BaseModel

class UserCreate(BaseModel):
    name: str
    age: int

作用：

规定字段结构
自动校验类型
自动生成文档
提高接口可靠性

2.9 字段校验

可以使用 Field 做更细粒度约束。

from pydantic import BaseModel, Field

class UserCreate(BaseModel):
    name: str = Field(min_length=1, max_length=50)
    age: int = Field(ge=0, le=120)

常见约束

min_length / max_length
ge：大于等于
le：小于等于
default
description

2.10 严格模式（基础认知）

默认情况下，Pydantic 会尝试做类型转换。

例如：

传入字符串数字，可能会被自动转成整数

如果希望更严格，可以使用更严格的类型约束，例如：

StrictInt
StrictStr

示例：

from pydantic import BaseModel, StrictInt

class Data(BaseModel):
    top_k: StrictInt

核心理解

默认模式更方便
严格模式更安全
面试里常考“是否允许自动类型转换”这类理解点

2.11 FastAPI 的自动文档

FastAPI 会自动生成文档页面，常见有：

Swagger UI
ReDoc

这也是它非常适合做接口开发和调试的原因之一。

工程意义

方便联调
方便测试
方便查看参数和响应结构

2.12 状态码设置

默认成功一般返回 200。

也可以手动指定：

from fastapi import FastAPI, status

app = FastAPI()

@app.post("/users", status_code=status.HTTP_201_CREATED)
def create_user():
    return {"message": "created"}

2.13 常见异常处理

可以通过抛出 HTTPException 返回明确错误。

from fastapi import HTTPException

@app.get("/users/{user_id}")
def get_user(user_id: int):
    if user_id != 1:
        raise HTTPException(status_code=404, detail="User not found")
    return {"id": 1, "name": "Tom"}

核心理解

业务校验失败时，不要直接让程序崩溃
应该返回明确状态码和错误信息

2.14 请求处理的完整链路

一个 FastAPI 接口的处理流程通常是：

客户端发 HTTP 请求
FastAPI 根据路由匹配到处理函数
解析路径参数 / 查询参数 / 请求体
使用 Pydantic 做校验
执行业务逻辑
返回 JSON 响应

2.15 FastAPI 为什么适合 AI 应用

场景 1：封装模型接口

@app.post("/chat")
def chat(req: ChatRequest):
    ...

场景 2：封装 RAG 服务

@app.post("/ask")
def ask(req: AskRequest):
    ...

场景 3：封装 Agent 服务

@app.post("/agent/run")
def run_agent(req: AgentRequest):
    ...

原因

接口定义直观
参数类型清晰
校验方便
和 typing / Pydantic 配合非常自然

2.16 难点与易错点

路径参数、查询参数、请求体容易混

要明确：

写在路径里的：路径参数
普通函数参数：常常是查询参数
Pydantic 模型：通常表示请求体

GET 请求通常不该承载复杂请求体

当前阶段先建立这个常识：

查询用 GET
提交复杂 JSON 用 POST

返回值必须可序列化

FastAPI 常见返回值应为：

dict
list
基础类型
Pydantic 模型

校验失败通常是 422

FastAPI/Pydantic 自动校验失败时，经常返回 422。

不要忽视错误处理

参数不合法
资源不存在
服务内部异常

都应有明确返回。

2.17 必须记住

FastAPI 是现代 Python Web 框架
一个接口本质上就是一个路由函数
@app.get() / @app.post() 要分清
路径参数、查询参数、请求体要分清
Pydantic BaseModel 用于定义和校验数据结构
Field 可做字段约束
HTTPException 用于返回明确错误
FastAPI 默认会把 dict/list 转成 JSON

3. HTTP + FastAPI 的整体理解

3.1 从协议到框架

HTTP 解决什么问题

客户端和服务端如何通信

FastAPI 解决什么问题

用 Python 快速实现 HTTP API

所以可以理解为：

HTTP 是规则
FastAPI 是实现这些规则的工具

3.2 一个典型接口的本质

例如：

class ChatRequest(BaseModel):
    question: str

@app.post("/chat")
def chat(req: ChatRequest):
    return {"answer": f"你问的是：{req.question}"}

这个接口本质上做了：

通过 HTTP 接收 POST 请求
从 JSON Body 中解析数据
校验字段结构
执行业务逻辑
返回 JSON 响应

这就是后续所有 AI 接口的基本模型。

4. 面试高频问法

4.1 GET 和 POST 的区别是什么

回答要点：

GET 主要用于查询资源
POST 主要用于提交数据或创建资源
GET 参数通常在 URL 中
POST 通常通过请求体传复杂数据
语义上，GET 更偏只读，POST 更偏写入或触发操作

4.2 路径参数和查询参数的区别

回答要点：

路径参数通常用于标识具体资源，例如 /users/123
查询参数通常用于过滤、排序、分页，例如 /users?page=2&active=true

4.3 FastAPI 为什么适合做 AI 应用接口

回答要点：

开发速度快
类型标注友好
Pydantic 校验强
自动文档方便联调
很适合封装模型、RAG、Agent 服务

4.4 Pydantic 的作用是什么

回答要点：

定义数据结构
校验请求数据
约束字段类型与范围
提高接口稳定性
让接口文档更清晰

4.5 为什么 FastAPI 中经常返回 422

回答要点：

因为请求数据虽然格式上是合法 HTTP 请求，但字段类型、缺失项或约束不满足 Pydantic 校验
所以 FastAPI 会返回 422 Unprocessable Entity

5. 当前必须掌握的重点

HTTP 请求和响应的基本结构
GET / POST / PUT / DELETE 的基本语义
状态码的含义，尤其是 200 / 201 / 400 / 404 / 422 / 500
路径参数、查询参数、请求体的区别
FastAPI 路由的基本写法
Pydantic BaseModel 的基本使用
Field 做字段约束的基本方法
HTTPException 的基本使用
知道 FastAPI 自动文档的意义

AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

最高赢取价值万元大奖，仓颉生态创新开发挑战赛开启！

AtomGit开源社区

AtomGit 首发开源｜光轮智能发布全球首个十万小时级全模态人类行为开源数据集 EgoSuite-Open100K

AtomGit开源社区

昇腾 0 Day 支持 Hunyuan4-preview，770B MoE 旗舰模型开源即适配

AtomGit开源社区

所有评论(0)

查看更多评论

englightened

@englightened

已为社区贡献6条内容