VSCode Pylance对FastAPI响应类型转换报错问题求助

问题场景 #

使用VSCode + 微软默认Python扩展（Pylance）开发Python 3.12 FastAPI项目，按FastAPI规范用类型注解指定接口返回模型，代码能正常返回对应结果，但Pylance报返回类型不兼容错误。

模型代码 #

class PetBase(SQLModel):
    name: str

class Pet(PetBase, table=True):
    id: str

class PetOutgoing(PetBase):
    id: str

接口代码 #

@router.get("/{pet_id}")
def retrieve_one(pet_id: str) -> PetOutgoing:
    pet: Pet = get_pet_by_id(pet_id)
    return pet

Pylance错误提示 #

Expression of type "Pet" is incompatible with return type "PetOutgoing"
  "Pet" is incompatible with "PetOutgoing" PylancereportReturnType
(variable) pet: Pet

问题原因与解决方法 #

核心原因 #

Pylance是静态类型检查工具，只识别类的继承关系和类型定义，无法感知FastAPI运行时的自动转换逻辑：

• Pet和PetOutgoing虽同继承自PetBase且字段完全一致，但二者是独立的类，没有继承或类型兼容关系，静态检查时判定类型不匹配。
• FastAPI是在运行时通过响应模型机制自动将Pet实例转换为符合PetOutgoing结构的数据，但这个过程Pylance静态检查无法识别。

解决方法 #

有三种可行方案：

1. 显式转换类型
   将Pet实例转为PetOutgoing对象，让静态检查通过：

   @router.get("/{pet_id}")
   def retrieve_one(pet_id: str) -> PetOutgoing:
       pet: Pet = get_pet_by_id(pet_id)
       return PetOutgoing(**pet.dict())
   

2. 添加类型忽略注释
   若不想显式转换，可通过注释告知Pylance忽略该类型检查：

   @router.get("/{pet_id}")
   def retrieve_one(pet_id: str) -> PetOutgoing:
       pet: Pet = get_pet_by_id(pet_id)
       return pet  # type: ignore[return-value]
   

3. 调整类继承关系
   让Pet继承自PetOutgoing，静态检查会判定Pet是PetOutgoing的子类，自然兼容：

   class PetBase(SQLModel):
       name: str
   
   class PetOutgoing(PetBase):
       id: str
   
   class Pet(PetOutgoing, table=True):
       pass
   

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