Python函数内部定义类的返回值类型注解方案（兼容3.7及新版本）

Python 3.7 解决方案 #

由于函数定义时的返回值注解会先于内部类解析，类型检查器无法识别尚未定义的ReturnUser，可以通过以下两种方式解决：

1. 延迟设置函数返回值注解 #

通过修改函数的__annotations__属性，在内部类定义完成后再设置返回值类型：

from typing import List
from dataclasses import dataclass

def get_users():
    @dataclass
    class ReturnUser:
        first_name: str
        last_name: str
    
    # 类定义完成后设置返回值注解
    get_users.__annotations__["return"] = List[ReturnUser]
    
    return [
        ReturnUser("John", "Doe"), 
        ReturnUser("Jane", "Doe")
    ]

2. 使用ForwardRef声明前向引用 #

显式标记尚未定义的类型，之后替换为实际类：

from typing import List, ForwardRef
from dataclasses import dataclass

# 声明前向引用
ReturnUserRef = ForwardRef("ReturnUser")

def get_users() -> List[ReturnUserRef]:
    @dataclass
    class ReturnUser:
        first_name: str
        last_name: str
    
    # 替换为实际类型
    get_users.__annotations__["return"] = List[ReturnUser]
    
    return [
        ReturnUser("John", "Doe"), 
        ReturnUser("Jane", "Doe")
    ]

新版本Python（3.7+）优化方案 #

从Python 3.7开始，可通过from __future__ import annotations开启注解延迟解析特性——注解会以字符串形式存储，直到运行时才解析，此时可直接在返回值注解中使用尚未定义的内部类名称：

from __future__ import annotations
from typing import List
from dataclasses import dataclass

def get_users() -> List[ReturnUser]:
    @dataclass
    class ReturnUser:
        first_name: str
        last_name: str
    
    return [
        ReturnUser("John", "Doe"), 
        ReturnUser("Jane", "Doe")
    ]

• Python 3.11及以后版本中，该延迟解析特性成为默认行为，无需手动导入from __future__ import annotations即可直接使用上述写法。

无论采用哪种方案，调用方都能正常访问返回实例的first_name、last_name属性，类型检查器也能正确推断属性类型，同时ReturnUser仅在函数内部可见，符合你的需求。

内容的提问来源于stack exchange，提问作者Joe Jasinski