Python dataclass 怎样用 kw_only 阻止位置参数

如果一个 dataclass 的配置字段很多，继续依赖位置顺序很容易把 timeout、retry 传反。Python 3.10 起可以用 kw_only 把生成的 __init__ 参数改成关键字专用：调用方必须写出字段名，位置参数会直接失败。

官方地址：https://docs.python.org/3/library/dataclasses.html

需要所有字段都禁止位置传参时使用 @dataclass(kw_only=True)；只想保留少量稳定的位置参数时，使用 KW_ONLY 作为分隔点。它约束的是生成构造器的调用形式，不会自动检查业务值。

用 @dataclass(kw_only=True) 把字段统一改为关键字参数

先把数据对象的配置项全部设为关键字专用。下面的 name、timeout 和 retry 都必须按名称传入，字段顺序变化不会悄悄改变调用含义。

from dataclasses import dataclass

@dataclass(kw_only=True)
class RequestPolicy:
    # 所有字段都要求调用方写出参数名，避免位置错位
    name: str
    timeout: float = 3.0
    retry: int = 2

policy = RequestPolicy(name="search", timeout=1.5, retry=3)
# 位置参数会触发 TypeError，而不是静默套用错误顺序
# RequestPolicy("search", 1.5, 3)

这里的保护发生在构造调用层。timeout 仍可能是负数，retry 仍可能超出业务上限；这些值要在 __post_init__ 或业务校验器中另行检查。

用 KW_ONLY 分隔稳定的位置字段和可选配置

如果已有代码把第一个字段作为稳定的位置参数，不必一次性改掉全部调用。导入 KW_ONLY，放入一个通常命名为下划线的伪字段；它本身不会成为数据字段，后面的字段会变成关键字专用。

from dataclasses import dataclass, KW_ONLY

@dataclass
class Client:
    # id 是旧调用中稳定的位置参数
    id: str
    _: KW_ONLY
    # 这些配置必须显式写名，迁移时更安全
    timeout: float = 3.0
    region: str = "cn"

client = Client("order-17", timeout=2.0, region="ap")
# Client("order-17", 2.0, "ap") 会因关键字边界而失败

一个 dataclass 中只能声明一个 KW_ONLY 伪字段。它的字段名通常写成 _，因为 dataclasses 会忽略这个伪字段；不要把它当成实例属性来读取。

检查继承、参数重排与 __match_args__ 影响

继承场景要特别注意：生成的构造器会先放普通参数，再放关键字专用参数。字段在类定义中的视觉顺序不等于最终签名顺序，Python 需要把关键字参数放在 * 之后。

from dataclasses import dataclass, KW_ONLY
import inspect

@dataclass
class Base:
    id: str
    _: KW_ONLY
    timeout: float = 3.0

@dataclass
class Job(Base):
    # 子类新增的普通字段仍在星号之前
    name: str = "sync"
    retry: int = 1

print(inspect.signature(Job))
# 关键字专用字段不会进入 __match_args__
print(Job.__match_args__)

在这种写法下，签名会把 id、name、retry 作为普通参数，再把 timeout 放到关键字区域。kw_only 字段也不会进入 __match_args__，因此不要依赖位置模式去匹配这些配置项。

用签名检查和最小调用完成迁移验证

迁移旧类时先检查签名，再逐个改调用点。只要看到星号，后面的参数就必须使用 name=value 形式；如果调用来自反序列化或工厂函数，也要同步改成关键字字典。

import inspect

signature = inspect.signature(RequestPolicy)
print(signature)
# 迁移检查只关注参数种类，不把类型校验误当成 kw_only 的职责
assert signature.parameters["timeout"].kind is inspect.Parameter.KEYWORD_ONLY

# 最小成功调用：关键字名清晰，默认值仍然可用
assert RequestPolicy(name="search").retry == 2

相关问题

kw_only 会校验字段值是否合法吗？

不会。它只改变调用语法；范围、格式、跨字段约束仍需在 __post_init__ 或业务层实现。

KW_ONLY 能在同一个类里写两次吗？

不能。单个 dataclass 重复声明多个 KW_ONLY 伪字段会触发错误，保留一个分隔点即可。

关键字专用字段还能用于模式匹配吗？

它们不会进入 __match_args__ 的位置匹配元组；需要匹配配置时应使用具名属性或显式条件。