首页 > 脚本专栏 > python > python显式声明类型参数使用

python中的显式声明类型参数使用方式

2025-08-18 09:11:39 作者：Allocator

文章探讨了Python 3.10+版本中类型注解的使用,指出FastAPI官方示例强调显式声明参数类型,通过|操作符替代Union/Optional,可提升代码规范性和IDE提示效果,帮助规避类型错误,成为框架设计中的最佳实践

背景

笔者在用fastapi编写ai rest service的时候发现官方的sample code函数参数都带上了类型参数. 以往笔者做python开发都不习惯带类型参数，认为它是一门弱类型语言，不强制带类型参数本质上是为了开发效率.fastapi的官方文档却强调函数定义是要显式带参数类型，于是笔者就详细研究了python显式声明参数类型的语法以及其带来的好处.

python函数显式声明的类型汇总

显示类型语法要分版本，笔者这里选择3.10+版本，是现在主流的版本.

基本类型

str，int，float等python基本类型，最常见的显式参数类型

def test1(a: int， b: str， c: float):
  print("a is: " + str(a) + " b is: " + str(b) + " c is: " + str(c))

集合类型

list，dict，set，tuple. 集合类型都有内部参数类型，这个等价于我们熟悉的java语言里面的泛型

def test2(a: list[str]， b: set[float]， c: dict[str， int]， d: tuple[str， str]):
  print(f"a is: {a} ")
  print(f"b is {b}")
  print(f"c is {c}")
  print(f"d is {d}")


if __name__ == '__main__':
  test2([1，2]， {3，4}， {'a':1，'b':2}， ('a'，'b'))

这个也比较简单，即便平时编码不习惯显示添加类型参数，此类声明语法也很直观.

Optional and Union(python3.10版本之前)

Optional和Union需要详细讲解一下，这两个类型在python 3，10版本之前使用比较多. 首先是union 表示当前入参可以是Union后面方括号指定的多类型中的一种，表示此参数可以支持多种类型，比如下例子:

from typing import Union
def test_union(a: Union[str， int]):
  if isinstance(a， str):
    print(f'a is str {a}')
  elif isinstance(a， int):
    print(f'a is int {str(a)}')

if __name__ == '__main__':
  test_union('abc')
  test_union(1)

输出：

a is str abc
a is int 1

表示参数a可以是str类型或者int类型

另一种情况，当union只有两个类型，且其中一个类型为None

def test_union2(a: Union[str， None]):
  if a is None:
    print("a is none")
  else:
    print(a.upper())


if __name__ == '__main__':
  test_union2(a = None)

这种情况表明入参a 要么是str类型，要么可以为None，而且这种特殊情况下Union[str， None]就可以被Optional[str]替代.

from typing import Optional
def test_optional(a: Optional[str]):
  print(a)

if __name__ == '__main__':
  test_optional(a=None)

我们可以看作Optional是Union的一个特例.在3.10+版本后其实都可以不用从typing包引入Optional和Union两种类型，在3.10+版本用一个|操作符就可以代替Union，比如下面这个例子:

def test_310(a: str|None):
  print(a)
  print(type(a))


if __name__ == '__main__':
  test_310(a='10')
  test_310(a=None)
  test_310(20)

可见在vscode里面这里即便声明了类型参数可能是str，但是int类型也可以传递进来.

来看下面一个有意思的case.

这里定义一个可以为None类型的参数，调用的时候不赋值

def test_default(a: str|None):
  print(a)


if __name__ == '__main__':
  test_default()

结果运行报错

test_default() missing 1 required positional argument: 'a'

注意语法a: str|None 以及 a: Optional[str] 或者 Union[str，None] 只是代表参数可以为None但是并不代表参数有默认值

所以此类语法只是表示当前参数类型可以是None，但并不表示存在None的默认值.如果需要调用函数时不传递参数，那么无论采用什么语法，在函数定义的时候还是需要给定默认值None.

自定义类类型

类型参数还可以是自定义类，或者自定义类的集合类型

class A:
  def __init__(self， val):
    self.val = val
  def test(self):
    print(self.val)

def test_a(a: A):
  a.test()

if __name__ == '__main__':
  a = A('123')
  test_a(a)

自定义类型作为集合中元素类型

def test_a_list(a: list[A]):
  for item in a:
    item.test()


if __name__ == '__main__':
  a = [A('123')， A('234')]
  test_a_list(a)

显示声明类型的好处

python是弱类型语言，本质上是不需要去定义其变量类型或者参数的类型的.但是有些框架的源码里面都有类型参数的声明，不禁让人思考这样做带来了什么好处.

看如下的例子:

无显式声明vscode没有方法提示：

有显式声明vscode存在方法提示：

在vscode里面如果显式声明参数类型，当掉用此参数则可以提示此类型具备的方法，如果没有显式声明参数类型则不会提示此类型具备的方法.

其次，显示声明参数类型是一种更规范的做法，它可以避免一些潜在的因为类型没显式声明而带来的编码问题，这也能理解为什么fastapi的官方doc会提及到python的类型，且在官方的sample code里面都有显示声明参数类型.所以将此作为一个最佳实践也不为过.

总结

以上为个人经验，希望能给大家一个参考，也希望大家多多支持脚本之家。