本文基于 FastAPI 官方文档《Python 类型提示简介》整理编写，帮助初学者快速理解 Python 类型注解的核心概念及其在 FastAPI 中的实际应用。
什么是类型提示？
Python 从 3.5 版本开始支持类型提示（Type Hints），也叫类型注解。它是一种可选的特殊语法，用来声明变量或函数参数的类型。它的核心价值在于让编辑器和开发工具更好地理解你的代码，从而提供智能补全和类型检查。
FastAPI 的整个框架都建立在 Python 类型提示之上 —— 这是它最显著的特点：你不需要学习任何新的语法或框架特定的写法，只需要标准的现代 Python 即可。
动机：为什么需要类型提示？
假设你正在从头编写一个简单的函数：
def get_full_name(first_name, last_name):
full_name = first_name.title() + " " + last_name.title()
return full_name
当你输入 first_name. 然后按下 Ctrl+Space 尝试触发自动补全时，编辑器一脸茫然 —— 它不知道 first_name 是什么类型，自然也没办法告诉你有哪些方法可以调用。你只能凭记忆去猜是 upper、uppercase、capitalize 还是 title。
现在我们给参数加上类型提示：
def get_full_name(first_name: str, last_name: str):
full_name = first_name.title() + " " + last_name.title()
return full_name
改动只有一个：在参数后加上 : str。就这么一行改动，编辑器立刻"聪明"了起来。再次按下 Ctrl+Space，所有字符串相关的方法都会出现在补全列表中。这就是类型提示最直观的价值 —— 更好的编辑器体验。
还有一个更实用的例子：
def get_name_with_age(name: str, age: int):
name_with_age = name + " is this old: " + age # 编辑器会标红这里！
return name_with_age
因为编辑器知道 age 是 int 类型，而 name 是 str 类型，它会立刻提醒你：不能直接用 + 拼接字符串和整数。你需要改成 str(age) 才能正确运行。这就是类型提示的另一个核心价值 —— 及早发现错误。
基础类型声明
Python 支持所有标准类型的声明：
def get_items(
item_a: str, # 字符串
item_b: int, # 整数
item_c: float, # 浮点数
item_d: bool, # 布尔值
item_e: bytes, # 二进制数据
):
return item_a, item_b, item_c, item_d, item_e
这些类型名本身就是 Python 内置的，不需要额外导入，写起来非常自然。
泛型类型：让容器也带上类型
Python 的容器类型（list、tuple、set、dict）可以进一步声明"里面装的是什么类型"，这被称为泛型。写法是把内部类型放在方括号 [] 中。
列表
def process_items(items: list[str]):
for item in items:
print(item) # 编辑器知道 item 是 str
这表示 items 是一个列表，里面的每个元素都是字符串。当你遍历时，编辑器也知道 item 的类型是 str，会给出字符串方法的补全。
元组和集合
def process_items(
items_t: tuple[int, int, str], # 三元组：两个 int 加一个 str
items_s: set[bytes], # 每个元素都是 bytes 的集合
):
return items_t, items_s
tuple 的泛型写法可以指定每个位置的具体类型，而 set 只需要指定一个类型（因为集合中所有元素类型相同）。
字典
def process_items(prices: dict[str, float]):
for item_name, item_price in prices.items():
print(item_name) # 编辑器知道是 str
print(item_price) # 编辑器知道是 float
字典需要两个类型参数：第一个是键的类型，第二个是值的类型。dict[str, float] 表示键是字符串、值是浮点数的字典。
联合类型：一个变量可以有两种类型
有些情况下，一个变量可能是 int 也可能是 str。用竖线 | 连接两个类型即可：
def process_item(item: int | str):
print(item)
这被称为联合类型，表示 item 可以是 int 或 str 中的任意一种。
在 FastAPI 里最常见的联合类型用法是可选参数：
def say_hi(name: str | None = None):
if name is not None:
print(f"Hey {name}!")
else:
print("Hello World")
str | None 表示 name 可以是字符串，也可以是 None。配合 = None 作为默认值，这个参数就变成了可选的。FastAPI 中大量使用了这种模式来定义可选的查询参数。
类也可以作为类型
不仅基础类型，你自定义的类也可以直接用作类型提示：
class Person:
def __init__(self, name: str):
self.name = name
def get_person_name(one_person: Person):
return one_person.name # 编辑器知道 Person 有 name 属性
当编辑器看到 one_person: Person，它会知道这个变量是 Person 类的实例，从而提供 name、以及其他属性和方法的自动补全。
Pydantic 模型：类型提示的终极应用
Pydantic 是一个 Python 数据验证库，它将类型提示发挥到了极致。定义一个数据模型，就是声明一个带有类型注解的类：
from datetime import datetime
from pydantic import BaseModel
class User(BaseModel):
id: int
name: str = "John Doe"
signup_ts: datetime | None = None
friends: list[int] = []
然后你只需要这样使用：
external_data = {
"id": "123",
"signup_ts": "2017-06-01 12:22",
"friends": [1, "2", b"3"],
}
user = User(**external_data)
print(user.id) # 123 (自动从字符串转成了整数)
print(user.signup_ts) # datetime.datetime(2017, 6, 1, 12, 22)
print(user.friends) # [1, 2, 3] (自动转了类型并去重)
Pydantic 会自动完成数据验证、类型转换、默认值填充，并且全程享受编辑器的类型提示支持。FastAPI 完全建立在 Pydantic 之上，你在 FastAPI 里定义的所有请求体、查询参数、响应模型，本质上都是 Pydantic 模型。
类型提示在 FastAPI 中的作用
在 FastAPI 中，用类型提示声明参数，框架会自动帮你完成以下事情：
- 数据转换：把请求中的字符串自动转成你声明的
int、float、datetime等类型 - 数据验证：当数据不符合类型要求时，自动返回清晰的错误信息给客户端
- 编辑器支持：全程享受 IDE 的自动补全和类型检查
- 自动文档：基于类型声明自动生成 OpenAPI 文档和交互式 API 页面
你用标准的 Python 类型声明一次，FastAPI 就帮你完成所有这些工作 —— 不需要额外的装饰器、配置文件，也不需要学习新的 DSL。
写在最后
类型提示是 Python 生态正在快速普及的一项特性，而 FastAPI 是最能体现其价值的框架之一。即使你暂时不用 FastAPI，学会类型提示也能显著提升日常 Python 开发的效率和质量 —— 代码更清晰、编辑器更智能、bug 更少。
如果你已经准备好动手实践，建议从 FastAPI 的官方教程 - 用户指南开始，那里有大量真实场景下的类型提示应用示例，能帮你快速上手。
转载自 CSDN-专业IT技术社区
原文链接：https://blog.csdn.net/2401_89111612/article/details/163283815
