PostHog Python Dataclass 编写规范：用 `@frozen` 构建安全的内部值对象

PostHog Python Dataclass 编写规范：用@frozen构建安全的内部值对象

【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog

本指南基于 PostHog 仓库中的.agents/skills/writing-dataclasses/SKILL.md（开发者技能规范），系统讲解 PostHog 团队对 Pythondataclass的「家规」：何时应该使用 dataclass 而非元组或dict[str, Any]，为什么统一使用posthog.dataclasses.frozen装饰器，以及如何命名、构造、消费、演进和跨层传递这些对象。读完本文，你将掌握 PostHog 的 dataclass 最佳实践，并能直接套用到自己的项目中，把「静默类型互换」这类运行时 bug 提前变成类型检查错误。

核心动机：消灭静默的同类互换

规范开篇即点明了所有规则背后的唯一目的：值共享同一类型时会被静默互换（silently swapped），而位置型元组（positional tuple）或dict[str, Any]恰恰给了这种互换发生的空间。例如(start, end)、(width, height)、(rows, columns)这样的二元组，两个元素类型完全相同，调用方一旦写反，解释器不会报错，只会产生一个难以追踪的运行时 bug。

而一个具名（named）、冻结（frozen）的 dataclass能把这种互换变成类型检查失败（typecheck failure），而不是运行时错误。文档明确说明：如果某条规则在你的场景下不能服务于这个目的，请在 PR 里说明理由并跳过它——规则服务于意图，而非为规则而规则。

何时用 dataclass，何时不用

规范给出三条清晰的判断标准：

1. 返回或传递 dataclass 而非元组：当两个或以上元素共享同一类型时（如(start, end)、(width, height)、(rows, columns)），或者元组大约有 3+ 个元素、位置化访问伤害可读性时，应当使用 dataclass。而一个小型、元素类型明显不同的元组（如(user, count)）保持原样即可。
2. 优先 dataclass 而非dict[str, Any]：当一组固定的值跨越函数边界时。dict 的键拼写错误只会在运行时失败，而 dataclass 字段拼写错误在类型检查阶段就会暴露。真正动态的键集合才继续使用 dict。
3. NamedTuple不是答案：它仍然支持位置化解包，解决不了互换问题。

选择哪个装饰器：posthog.dataclasses.frozen

装饰器的默认值

PostHog 在 posthog/dataclasses.py 中提供了家规装饰器@frozen，它是标准库@dataclass的封装，默认开启frozen=True, kw_only=True, slots=True，且每个参数都可覆盖：

from posthog.dataclasses import frozen @frozen class BillingPeriod: start: datetime end: datetime @frozen(slots=False) # 类使用了 functools.cached_property class ParsedQuery: ... @frozen(frozen=False) # 构造后确实需要被修改（builder、accumulator） class RunAccumulator: ...

从 posthog/dataclasses.py 的源码可以看到其实现：使用@dataclass_transform(frozen_default=True, kw_only_default=True)标注以便类型检查器理解语义，通过kwargs.setdefault("frozen", True)、setdefault("kw_only", True)、setdefault("slots", True)设置家规默认值，再透传给dataclass(**kwargs)。可覆盖的完整参数包括frozen、kw_only、slots、eq、order、repr、unsafe_hash、match_args、weakref_slot。

三个默认值的意义

• kw_only=True是真正阻止构造期互换的关键：BillingPeriod(start=a, end=b)，永远不写BillingPeriod(a, b)。没有充分理由不要覆盖它。
• slots=True会阻止functools.cached_property和临时属性：需要这些能力时用@frozen(slots=False)覆盖，而不是放弃@frozen。
• frozen=True提供不可变性：冻结实例可哈希，能安全地作为 dict/set 的键。

命名规范

类名要按领域概念命名，而不是按「管道/基础设施」命名：ClickHouseCredentials、BillingPeriod、SnapshotManifestItem。只有函数的产出物真的就是那个概念时才用*Result后缀；内部对象永远不要用*Info、*Data、*Tuple、*Response这类名字。仅在一个模块内部使用的类，用下划线前缀（如_Foo）标明私有性。

在仓库中可以找到大量遵循此规范的实例，例如 posthog/models/organization.py 中的@frozen class BillingPeriod，其current_billing_period方法返回BillingPeriod(start=start, end=end)——正是kw_only关键字构造的写法；posthog/models/identity_provider_config.py、posthog/models/integration/oauth.py 等文件中也都大量使用@frozen。

构造与不变量（invariant）强制

• 在__post_init__中强制不变量：如start <= end、恰好设置一种认证方式、数值在范围内。这样非法实例在构造时就会失败，而不是在后续深层逻辑中才暴露。冻结类上仅在必须归一化（normalize）时使用object.__setattr__，更推荐的做法是直接抛出异常。
• 封闭字符串集合的字段要用Literal[...]或枚举，而不是裸str：注意，收窄现有字段类型可能暴露调用方传入裸str的 mypy 错误——应当修复调用方，而不是把字段重新放宽。
• 冻结 dataclass 可哈希：当键包含两个以上同类型组成部分时，用一个小的 keyed 类作为 dict/set 键，而不是元组。

消费与演进（Evolving）

• 用点号读字段：result.start。永远不要写a, b = result.a, result.b解包成位置局部变量——那会重新引入互换问题。
• 用dataclasses.replace(instance, field=value)演进冻结实例：不要手工逐字段拷贝。
• 多变体时用match/case分发：如case BinaryOp(left=left, right=right):；单一类型的判断则保持普通的isinstance守卫即可。

密钥保护：field(repr=False)

秘密字段必须标记field(repr=False)，防止它们通过repr()泄露进 traceback 和日志。同时永远不要对这类 dataclass 调用asdict()输出到日志——那会重新暴露repr=False隐藏的内容。

跨层传递：Preserve Whole Object

当函数参数与调用方已持有的 dataclass 字段一一对应时，应该接受整个 dataclass 而不是解包后的字段。这会阻止同类型的形参被逐层位置化传递（threaded through several layers），这正是 Fowler 所说的 Preserve Whole Object 模式。

规范给出了三条按优先级排列的例外（carve-outs）：

1. 不变量优先于镜像（Invariants win over mirroring）：永远不要把更宽的类型传给需要更窄类型的被调用方。如果 dataclass 有url: str | None而辅助函数需要str，就保留str参数（或在边界收窄类型）；不要接受 dataclass 后再加运行时ValueError——那等于把类型检查换成守卫子句，与初衷背道而驰。
2. 线上（wire）签名保持原样：Temporal@activity.defn/@workflow.run与 celery 任务边界接受什么就接受什么；其背后的辅助函数才接受 dataclass。
3. 作为请求体的 facade 契约同样是 wire 签名：facade/contracts.py中由DataclassSerializer和@validated_request支撑的契约，就是 HTTP 请求体、OpenAPI schema、以及客户端发送的形状。产品的logic可以接受自己的契约，只要字段与 logic 所需一一对应，就不要预先构建并行的内部 DTO。只有出现真正的分歧时才拆分内部参数对象：wire 携带了 logic 忽略的死字段/废弃字段、logic 需要 wire 不接受的值、或 logic 需要 wire 无法承诺的不变量。拆分点位于facade/api.py——它是唯一的进程内调用方。

仓库中的 facade 契约实践

PostHog 的每个产品模块都遵循「facade 契约」模式。以 products/access_control/backend/facade/contracts.py 为例：该文件明确注释为「Stable, framework-free frozen dataclasses that define what this product exposes to the rest of the codebase. No Django/DRF imports here.」——即用@dataclass(frozen=True)定义稳定的、不依赖框架的输出/输入 DTO（如PropertyAccessControlRule、PropertyAccessControlState），并通过field(default_factory=list)提供可变容器默认值，枚举字段使用PropertyAccessLevel枚举类型而非裸str。

结合 products/architecture.md 可以看到整个模式的全貌：facade 是产品唯一的公共接口，facade/api.py定义公共接口，展示层（DRF）位于 facade 之上、在契约表面之外。规范要求 facade 契约默认使用pydantic.dataclasses.dataclass(frozen=True)，以便在构造时完成校验。

由什么来强制这些规则

规范由三层机制共同保证：

1. 阻塞性棘轮（blocking ratchet）

posthog/test/repo_invariants/test_dataclass_defaults.py 是一个基于 AST 的测试：扫描posthog、ee、products、common四个根目录下的所有.py文件，找出「未声明frozen=选择的裸@dataclass」，并与基线文件dataclass_frozen_baseline.txt对比——每个文件超过基线数量即 CI 失败。已有裸@dataclass被基线「祖父条款」豁免，随迁移逐步清理。

关键细节：

• @dataclass(frozen=False)显式声明可变性是通过的——棘轮要求的是明确的选择，而非强制不可变；
• 如果只是移动了已有裸@dataclass代码，用python posthog/test/repo_invariants/test_dataclass_defaults.py重新生成基线，而不是给装饰器加上frozen=False；
• 不要给自己没动过的裸@dataclass添加frozen=False——棘轮按文件计数与基线比对，未变化的计数能通过，而这次编辑只是在别人的文件里制造噪音（churn）。

2. 建议性 semgrep 规则（advisory）

• .semgrep/rules/devex/prefer-frozen-dataclasses.yaml：标记「裸@dataclass未声明frozen=选择」，级别 WARNING（信息性，不阻塞）。它排除**/migrations/**与**/.semgrep/**，并特意排除了无法导入posthog.dataclasses的独立 PEP 723 脚本包**/packages/pr-approval-agent/**。规则还智能地区分：从pydantic.dataclasses导入的@dataclass（有自己的校验语义）不会被误报。真正需要豁免时，在类行上加# nosemgrep: prefer-frozen-dataclasses -- <reason>。
• .semgrep/rules/devex/tuple-return-prefer-dataclass.yaml：标记函数返回类型为tuple[$T, $T]（两个同类型元素可被静默互换）或tuple[$A, $B, $C, ...]（3+ 元素需位置化读取）的注解，提示改用@frozen具名字段。既有发现同样被祖父豁免，只有新增的才阻塞 CI。

3. 代码评审（review）

规则之外的一切，最终靠 review 把关——这正是规范开头「如果某条规则在你的场景下不适用，请在 PR 中说明并跳过」的文化前提。

快速自查清单

在提交 dataclass 相关代码前，对照以下清单：

这套规范的直接收益是：PostHog 数千个 Python 文件共享的内部值对象——无论是计费周期、凭据配置，还是各产品 facade 的输入输出 DTO——都能以「类型系统可验证」的方式传递，把互换类缺陷消灭在 CI 阶段。

【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog