Total = NewType(“Total“, int)

Total = NewType("Total", int) 是使用 typing.NewType 创建了一个带语义的类型别名。以下是对它的分析：

1. NewType 的作用

NewType 是 Python 类型系统的一部分，用于创建与原生类型兼容但具有更强语义信息的类型。它不会改变原生类型的运行时行为，但在类型检查和文档说明中非常有用。

2. 具体定义

Total = NewType("Total", int)

• Total 是一个基于 int 的新类型

• 它表示一个整数值，但带有特定的语义：在这里表示“总记录数”

• 从类型检查的角度看，Total 是 int 的子类型

3. 应用场景

在代码中，Total 用于表示查询结果的总记录数。例如：

async def list(self, ...) -> Tuple[Total, List[ModelType]]:
    total = await query.count()
    ...
    return total, data

4. 优点

• 语义清晰：明确标识了返回值的含义，而不仅仅是int

• 类型安全：在静态类型检查工具（如 mypy）中，Total 和普通 int 被视为不同类型，避免误用

• 代码可读性：通过类型名称直接传达语义信息，减少注释需求

5. 使用示例

from typing import NewType

# 定义 Total 类型
Total = NewType("Total", int)

# 函数返回 Total 类型
def calculate_total(items: List[int]) -> Total:
    return Total(sum(items))

# 调用函数
total: Total = calculate_total([1, 2, 3])

6. 与普通类型的区别

• 类型检查：

  from typing import NewType
  
  Total = NewType("Total", int)
  
  def set_total(t: Total) -> None:
      pass
  
  # 错误：类型检查会报错
  set_total(123)  # Argument 1 to "set_total" has incompatible type "int"; expected "Total"
  
  # 正确：显示类型转换
  set_total(Total(123))
  

• 运行时行为： NewType 不会改变运行时的类型，Total(123) 的运行时类型仍然是 int。

7. 总结

Total = NewType("Total", int) 是一种类型注解技巧，用于增强代码的语义表达能力和可维护性。它特别适合在分页逻辑中标识总记录数，使代码更清晰易懂，同时与静态类型检查工具配合使用时提供更强的类型安全保障。