Python跨文件自定义类型管理：通用准则与循环导入解决方案

• 拆分类型层级，从根源避免循环依赖
  把自定义类型按依赖关系分层：

  • 纯基础类型（只依赖typing或内置类型，不关联任何业务模型），比如ActionCodes这类基于Literal/Union的约束型类型，单独放在base_types.py里，所有业务模型文件都可以安全导入这个文件。
  • 依赖业务模型的复合类型（比如包含某个Pydantic模型的Union/List），要么放在model_dependent_types.py里（确保这个文件只单向导入模型文件，模型文件导入基础类型），要么直接和依赖的模型放在同一文件，避免双向导入。

• 用延迟导入或字符串注解绕过循环
  如果某些类型必须引用业务模型，又不想拆分到模型文件，两种实用方法：

  • 局部导入：不在文件顶部导入模型，而是在类型定义的局部作用域里导入

    # types.py
    from typing import Union
    
    def get_product_or_id_type():
        from entity_models import ProductModel
        return Union[ProductModel, int]
    

  • 字符串注解：Pydantic支持用字符串形式引用未导入的模型，运行时会自动解析

    # types.py
    from typing import Union
    ProductOrId = Union["ProductModel", int]
    

• 用类型包统一对外暴露，隐藏内部结构
  把types.py改成types包，内部按层级拆分文件后，在types/__init__.py里统一导入所有类型：

  # types/__init__.py
  from .base_types import ActionCodes, StatusTypes
  from .model_dependent_types import ProductOrId, OrderItemList
  

  其他模块只需要从这个包导入，比如from types import ActionCodes, ProductOrId，既保持了单一数据源的感知，又隔离了内部文件的依赖关系。

• 避免类型与业务模型强耦合
  自定义类型优先做值约束（比如限定可选字符串、数值范围），不要把完整业务模型塞进类型别名里。如果需要结合模型逻辑，优先用Pydantic的字段约束或模型继承实现，比如在模型里直接定义action: ActionCodes，而不是创建包含模型和类型的复合Union类型。

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