Python作为动态类型语言，变量和参数的类型不需要提前声明，这带来了开发灵活性的同时，也给代码的阅读和维护带来了一定困扰。尤其是函数逻辑复杂或者多人协作开发时，没有类型标注的函数会让使用者难以快速了解参数要求和返回值类型。Python的类型提示语法就是为了解决这类问题而设计的，它不会在运行时强制校验类型，只是作为代码层面的标注，配合IDE的类型检查功能可以提前发现很多类型相关的潜在问题。
基础类型提示的写法
最基本的函数类型提示是在参数后面添加冒号和类型，在函数定义末尾的冒号前添加->和返回值类型，语法格式如下：
def add(a: int, b: int) -> int:
"""两个整数相加的函数"""
return a + b
# 调用函数时即使传入其他类型，运行时也不会报错，只是类型提示不匹配
result = add(1, 2)
print(result) # 输出3
上面的代码中，a: int表示参数a的预期类型是int，b: int同理，-> int表示函数返回值预期是int类型。IDE会根据这些标注给出对应的代码提示，比如输入add(的时候，会自动提示两个参数都需要int类型。
常用类型的注解写法
除了基础的int、str、float、bool这些内置类型，还有很多常见类型的注解写法需要掌握：
容器类型注解
对于列表、字典、元组等容器类型，需要从typing模块导入对应的泛型类型，标注容器内元素的类型：
from typing import List, Dict, Tuple
def process_data(nums: List[int], info: Dict[str, str]) -> Tuple[bool, str]:
"""
处理数据函数，接收整数列表和字符串键值对字典
返回处理状态和提示信息
"""
if not nums:
return False, "输入列表为空"
total = sum(nums)
return True, f"列表总和为{total}"
# 调用示例
status, msg = process_data([1, 2, 3], {"name": "test"})
print(status, msg) # 输出True 列表总和为6
可选参数和联合类型
如果参数可以是多种类型，或者参数有默认值可能为None，可以使用Union或者Optional来标注：
from typing import Optional, Union
def format_id(user_id: Union[int, str], prefix: Optional[str] = None) -> str:
"""
格式化用户ID，user_id可以是整数或者字符串
prefix是可选的前缀，默认为None
"""
id_str = str(user_id)
if prefix:
return f"{prefix}_{id_str}"
return id_str
print(format_id(123)) # 输出123
print(format_id("abc", "user")) # 输出user_abc
这里的Optional[str]等价于Union[str, None]，表示参数可以是str类型或者None。
类型提示的注意事项
- 类型提示只是标注，Python运行时不会强制校验类型，传入不符合预期的类型也不会直接报错，需要配合mypy等类型检查工具才能发挥作用。
- 如果是Python3.10及以上版本，联合类型可以简化写法，不用导入
Union，直接用int | str的格式即可：def func(a: int | str) -> None: ...。 - 对于自定义的类，也可以直接作为类型标注使用，不需要额外导入：
class User:
def __init__(self, name: str, age: int):
self.name = name
self.age = age
def get_user_name(user: User) -> str:
"""接收User实例，返回用户名称"""
return user.name
u = User("张三", 20)
print(get_user_name(u)) # 输出张三
合理设置函数的类型提示，能够大幅降低代码的维护成本，尤其是在大型项目中，清晰的类型标注可以让新成员更快熟悉代码逻辑，也能减少很多因为类型不匹配导致的隐藏bug。
Python函数类型提示类型注解type_hints修改时间：2026-06-26 05:48:31