FastAPI入门教程：HTTP基础与API开发实战

在这里插入图片描述

【个人主页：玄同765】

大语言模型（LLM）开发工程师｜中国传媒大学·数字媒体技术（智能交互与游戏设计） 深耕领域：大语言模型开发 / RAG知识库 / AI Agent落地 / 模型微调 技术栈：Python / LangChain/RAG（Dify+Redis+Milvus）| SQL/NumPy | FastAPI+Docker ️ 工程能力：专注模型工程化部署、知识库构建与优化，擅长全流程解决方案 专栏传送门：LLM大模型开发 项目实战指南、Python 从真零基础到纯文本 LLM 全栈实战、​​​​​从零学 SQL + 大模型应用落地、大模型开发小白专属：从 0 入门 Linux&Shell 「让AI交互更智能，让技术落地更高效」 欢迎技术探讨/项目合作！ 关注我，解锁大模型与智能交互的无限可能！

HTTP协议作为互联网通信的核心标准，为Web服务提供了基础框架。本文将深入讲解HTTP协议的特点、URL的组成结构，以及FastAPI框架中路径参数的使用方法，同时分析GET和POST请求的区别，并通过一个学生信息管理的API接口实例，展示如何利用FastAPI构建实用的Web服务。

HTTP协议特点

HTTP协议是客户端与服务器之间通信的标准协议，具有以下核心特点：

(1) 基于TCP/IP协议

http协议是基于TCP/IP协议之上的应⽤层协议。

(2) 基于请求－响应模式

HTTP协议规定,请求从客⼾端发出,最后服务器端响应该请求并 返回。换句话说,肯定是先从客⼾端开始建⽴通信的,服 务器端在没有 接收到请求之前不会发送响应

(3) ⽆状态保存

HTTP是⼀种不保存状态,即⽆状态(stateless)协议。HTTP协议 ⾃⾝不对请求和响应之间的通信状态进⾏保存。也就是说在HTTP这个 级别,协议对于发送过的请求或响应都不做持久化处理。

使⽤HTTP协议,每当有新的请求发送时,就会有对应的新响应产 ⽣。协议本⾝并不保留之前⼀切的请求或响应报⽂的信息。这是为了更快地处理⼤量事务,确保协议的可伸缩性,⽽特意把HTTP协议设计成 如此简单的。

(4) 短连接

HTTP1.0默认使⽤的是短连接。浏览器和服务器每进⾏⼀次HTTP操作，就建⽴⼀次连接，任务结束就中断连接。

HTTP/1.1起，默认使⽤⻓连接。要使⽤⻓连接，客⼾端和服务器的HTTP⾸部的Connection都要设置为keep-alive， 才能⽀持⻓连接。

HTTP⻓连接，指的是复⽤TCP连接。多个HTTP请求可以复⽤同⼀个TCP连接，这就节省了TCP连接建⽴和断开的消耗。

URL组成部分

URL（统一资源定位符）是标识互联网上资源位置的字符串，由以下几部分组成：

完整的URL示例如下：

http://example.com:8080/api/students?class=A1#section1

URL的各部分通过特定符号分隔：

• 方案后跟冒号和两个正斜杠（://）
• 主机名后可跟冒号和端口号（:8080）
• 路径以单正斜杠开始（/api/students）
• 查询字符串以问号开头（?class=A1）
• 片段标识以井号开头（#section1）

URL的方案和主机部分通常不区分大小写，但路径和查询字符串是区分大小写的。因此，在设计API接口时，应保持路径的一致性，通常以小写形式指定整个URL。

路径参数详解

路径参数是URL路径中动态部分的标识符，用于在API设计中传递资源标识。在FastAPI中，路径参数通过大括号{}包裹在URL路径中定义，如/students/{student_id}。

路径参数与查询参数的区别：

路径参数是URL路径的一部分，用于标识特定资源，通常与资源层级相关。例如，/students/123中的123标识特定学生资源。

查询参数是附加在URL路径后的键值对，用于过滤或补充请求信息。例如，/students?class=A1中的class=A1用于筛选特定班级的学生。

在FastAPI中定义路径参数时，需要同时声明参数类型，这使得FastAPI能够自动进行参数验证和类型转换。例如：

@app.get("/students/{student_id}")
def get_student(student_id: int):
# 处理逻辑

当客户端访问/students/5时，FastAPI会自动将5转换为整数类型并传递给student_id参数。如果访问/students/abc，FastAPI会返回422错误，提示参数类型不匹配。

GET与POST请求的区别

HTTP协议定义了多种请求方法，其中GET和POST是最常用的两种，它们在功能和使用场景上有显著区别：

请求方法：GET用于获取资源信息，POST用于提交数据到服务器。

数据传递方式：GET请求的参数通过URL的查询字符串传递，而POST请求的参数通过请求体（body）传递。

数据可见性：GET请求的参数可见于浏览器地址栏，可能被记录或分享；POST请求的参数在请求体中，相对隐蔽。

数据长度限制：GET请求的URL长度有限制（通常不超过2048字符），不适合传递大量数据；POST请求没有此限制。

幂等性：GET请求是幂等的（多次相同请求返回相同结果），而POST请求不是幂等的（多次提交可能导致多次创建资源）。

适用场景：

• GET：用于获取数据，如查询学生信息、获取列表等。
• POST：用于提交数据，如创建新学生记录、提交表单等。

在FastAPI中，可以通过装饰器@app.get()和@app.post()分别定义GET和POST请求的处理函数。

学生信息管理API实例

项目初始化

首先，创建一个FastAPI应用的基本结构：

from fastapi import FastAPI

app = FastAPI()

# 模拟学生信息存储
students = {
    1: {"id": 1, "name": "张三", "class": "A1", "age": 18, "score": 95},
    2: {"id": 2, "name": "李四", "class": "A1", "age": 19, "score": 88},
    3: {"id": 3, "name": "王五", "class": "B2", "age": 20, "score": 75},
    4: {"id": 4, "name": "赵六", "class": "B2", "age": 18, "score": 92}
}

学生ID查询接口

使用路径参数通过学生ID查询学生信息：

@app.get("/students/{student_id}")
def get_student_by_id(student_id: int):
    """根据学生ID获取学生信息"""
    student = students.get(student_id)
    if student:
        return student
    return {"error": "学生ID不存在"}

接口说明：

• 路径：/students/{student_id}，其中student_id是一个整数类型的路径参数。
• 请求方法：GET，用于获取特定学生的信息。
• 功能：根据提供的学生ID，从模拟的字典存储中检索对应的学生信息。如果ID不存在，返回错误信息。

班级查询接口

使用路径参数通过班级名称查询学生信息：

@app.get("/classes/{class_name}/students")
def get_students_by_class(class_name: str):
    """根据班级名称获取所有学生信息"""
    class_students = [
        student for student in students.values()
        if student["class"] == class_name
    ]
    if class_students:
        return class_students
    return {"error": "班级不存在或无学生"}

接口说明：

• 路径：/classes/{class_name}/students，其中class_name是一个字符串类型的路径参数。
• 请求方法：GET，用于获取特定班级的所有学生信息。
• 功能：根据提供的班级名称，从模拟的字典存储中筛选并返回该班级的所有学生信息。如果班级不存在或无学生，返回错误信息。

运行与测试

启动应用：

uvicorn main:app --reload

测试接口：

1. 学生ID查询：
   • 访问http://127.0.0.1:8000/students/1，应返回ID为1的学生信息。
   • 访问http://127.0.0.1:8000/students/5，应返回错误信息。
2. 班级查询：
   • 访问http://127.0.0.1:8000/classes/A1/students，应返回班级A1的所有学生信息。
   • 访问http://127.0.0.1:8000/classes/C3/students，应返回错误信息。
3. 自动文档：
   • 访问http://127.0.0.1:8000/docs，可查看自动生成的交互式API文档，包含所有接口的详细说明和测试界面。

结论

本文介绍了HTTP协议的核心特点、URL的组成结构，以及FastAPI框架中路径参数的使用方法。通过GET和POST请求的区别分析，展示了如何根据实际需求选择合适的HTTP方法。最后，通过一个学生信息管理的API实例，演示了如何在FastAPI中定义和实现路径参数接口。

FastAPI的路径参数功能简化了API开发流程，通过类型提示提供了自动的数据验证，减少了开发错误。结合HTTP协议的基础知识，可以构建出高效、易用且可靠的Web服务。

通过实践这些示例，开发者可以快速掌握FastAPI的核心功能，并将其应用于实际项目中，构建出高性能的API服务。