在Python开发中，你是否遇到过这些抓狂时刻？
同事写的函数参数类型全靠猜
调试两小时发现传了字符串给数值计算函数
重构代码时不知道函数返回的是列表还是字典

今天教你两招，彻底解决类型混乱问题！让你的代码像带了说明书一样清晰！

一、给函数加"类型标签"：Type Annotations（类型注解）

（1）什么是类型注解？

就像给商品贴标签一样，我们可以给函数参数和返回值打上类型标记：

# 两个整数相加返回整数
def add(a: int, b: int) -> int:
    return a + b

# 判断偶数返回布尔值
def is_even(num: int) -> bool:
    return num % 2 == 0

（2）三大核心优势

1 智能提示黑科技

现代IDE（如PyCharm/VSCode）看到类型标签后：
自动补全方法属性
错误参数波浪线警告
悬停显示函数说明书

2 静态检查神器

配合mypy工具，提前发现类型炸弹：

mypy your_script.py  # 运行检查

在CI/CD流程中加入检查，把bug扼杀在摇篮里！

3 团队协作福音

新同事接手代码时：
"看到参数要求list[float]，再也不用猜半天了！"

（3）高阶用法示范

处理复杂数据结构也不怕：

from typing import List, Tuple

# 处理坐标转换：输入浮点列表，返回元组
def convert_coords(points: List[float]) -> Tuple[float, float]:
    return (points[0]*10, points[1]*10)

二、运行时动态探测：inspect模块黑科技

（1）什么是inspect模块？

Python自带的"代码显微镜"，可以实时分析函数结构：

import inspect

def multiply(a, b):
    return a * b

# 获取函数签名
sig = inspect.signature(multiply)

print("参数信息：")
for name, param in sig.parameters.items():
    print(f"{name}: 类型提示→{param.annotation}")

print("返回类型：", sig.return_annotation)

（2）典型应用场景

自动化测试框架验证参数类型
动态生成API文档
实现智能调试工具

（3）注意事项

没有类型注解时，annotation显示为empty
运行时检查会轻微影响性能

三、实战技巧：选型指南

1. 1. 什么时候用类型注解？
   长期维护的核心模块
   多人协作的中大型项目
   需要提供明确API接口的库
2. 2. 什么时候用inspect？
   编写通用调试工具时
   实现动态代理模式
   快速分析第三方库的接口
3. 3. 避坑指南
   类型注解不是强制约束，不要用来做运行时校验
   过度使用动态探测会影响代码可读性
   复杂类型提示需要Python3.9+版本支持

四、最佳实践案例

案例1：数据校验装饰器

from typing import Callable
from functools import wraps

def validate_types(func: Callable):
    @wraps(func)
    def wrapper(*args, **kwargs):
        # 获取类型提示进行校验
        sig = inspect.signature(func)
        # ...实现参数校验逻辑
        return func(*args, **kwargs)
    return wrapper

@validate_types
def process_data(data: list[float]) -> dict:
    # 自动校验输入参数类型
    return {"result": sum(data)}

案例2：智能API文档生成

def generate_api_doc(func):
    sig = inspect.signature(func)
    doc = f"接口名称：{func.__name__}\n"
    doc += "参数列表：\n"
    for param in sig.parameters.values():
        doc += f"- {param.name}: {param.annotation}\n"
    doc += f"返回类型：{sig.return_annotation}"
    return doc