PostHog 后端编码规范全解析:结构化日志、测试金字塔与数据类工程实践
PostHog 后端编码规范全解析:结构化日志、测试金字塔与数据类工程实践
导读
本文以 PostHog 仓库中的 后端编码规范文档 为骨架,系统梳理该团队在 Python/Django 后端开发中的一整套可落地的工程约定:从基于 django-structlog 的结构化日志、异常上报与日志安全红线,到以"测试即永久负债"为出发点的测试金字塔与测试取舍决策框架,再到 @frozen 数据类、HogQL 查询纪律与开源/企业版代码的边界判断。读完本文,你将掌握一套可直接复制到任意 Python 后端团队的后端编码规范模板,并了解 PostHog 是如何通过配置文件和自动化测试(ratchet)把这些规范"焊死"进代码库的。
一、日志规范:为每一个动作留下可追踪的痕迹
1.1 基本原则:每条动作都要有日志
规范的第一条原则是:应用中的每一个预期与非预期动作都应该有日志,并且使用合适的日志级别。日志不是可选项,而是理解应用行为、定位线上事故的第一手证据。
同时,Python 异常在 PostHog 中"几乎总是会自动被捕获,无需额外埋点",但自定义异常——例如外部服务请求失败、查询报错、Celery 任务失败——需要显式调用 capture_exception() 来追踪(其实现见 posthog/exceptions_capture.py)。
从 capture_exception 的实现源码 可以看到它的实际行为:它会把 ClickHouse 查询标签(query tags)、当前上下文(ambient_exception_properties)、调用点显式传入的 additional_properties 以及 Celery 任务信息(任务名、重试次数)合并为 properties,交给 posthoganalytics.capture_exception 上报到 PostHog 自身的产品中,并同步用 logger.exception 输出一条含 event_id 的结构化日志;若未配置 API key(如本地开发),则退化为纯本地 logger.exception 输出。这意味着"异常上报"和"日志记录"在 PostHog 内部是打通的一体化链路。
1.2 日志级别:选对严重程度
日志级别(log level / severity)用于表达一条日志消息的重要程度,规范给出了四个级别的明确语义:
| 级别 | 适用场景 |
|---|---|
DEBUG |
诊断问题、排障所需的信息;或在测试环境中运行时确认一切正常 |
INFO |
标准日志级别,表示"某件事发生了" |
WARN |
发生了意外情况,但代码可以继续工作 |
ERROR |
应用遇到问题,导致一个或多个功能无法正常工作 |
1.3 结构化日志:用 django-structlog 记录"事件",而不是"散文"
PostHog 的默认日志库是 django-structlog。它的核心思想是结构化日志(structured logging):不要在日志里写难以解析、难以保持一致格式的散文(prose),而是记录在特定上下文中发生的事件(event),让机器可解析、可检索、可聚合。
官方示例的写法如下:
import structlog
logger = structlog.get_logger(__name__)
logger.debug("event_sent_to_kafka", event_uuid=str(event_uuid), kafka_topic=topic)
它会产生类似如下的输出:
2021-10-28T13:46:40.099007Z [debug] event_sent_to_kafka [posthog.api.capture] event_uuid=017cc727-1662-0000-630c-d35f6a29bae3 kafka_topic=default
可以看到,这条日志包含理解应用行为所需的全部信息:ISO 时间戳、日志级别、事件名、产生日志的模块(posthog.api.capture),以及键值对形式的上下文(event_uuid、kafka_topic)。
源码级佐证:在 posthog/settings/logs.py 中可以看到这套结构化日志管线的完整配置:
- 通过
foreign_pre_chain处理器链,把structlog的标准库事件转换为含时间戳(TimeStamper(fmt="iso"))、logger 名、日志级别、PID/TID(见add_pid_and_tid)、以及 OpenTelemetry 分布式追踪上下文(见add_otel_trace_context)的统一格式; - 提供
default(彩色控制台渲染,ConsoleRenderer(colors=DEBUG),开发环境带颜色)与json(JSONRenderer,适合生产采集)两种 formatter; - 通过
LOGGING_FORMATTER_NAME环境变量切换输出格式; DEFAULT_LOG_LEVEL默认在测试环境(TEST)为ERROR、其余为INFO,并可通过DJANGO_LOG_LEVEL覆盖;- 对噪音较大的三方库做了专门的降噪处理,例如
kafka.conn设为WARN、boto3/botocore设为WARN,而django.server、django.utils.autoreload在开发环境直接接入nullhandler 屏蔽。
这意味着开发者写日志时只需要关心"事件名 + 结构化字段",渲染、关联、采样全部由框架层解决。
1.4 为你的模块启用 INFO 日志
一个常见的坑:默认情况下,大多数 posthog.* logger 只输出 WARNING 及以上级别,这保证了生产日志的干净,但也意味着你的 logger.info() 调用不会出现。
正确做法是把它加入 posthog/settings/logs.py 的 LOGGING["loggers"] 配置:
"loggers": {
# ... existing loggers ...
"posthog.tasks.my_module": {"level": "INFO", "handlers": ["console"], "propagate": False},
}
注意:在代码里调用 logger.setLevel(logging.INFO) 对 structlog 不生效——必须像上面这样写配置项。从 logs.py 的现有配置可以看到,仓库中有大量模块正是以这种方式显式开启 INFO 日志,例如 posthog.tasks.alerts、posthog.tasks.email、posthog.auth.mfa、posthog.security.command_exec_audit、posthog.api_queries_budget 等;其中部分高频 INFO 模块(如 posthog.tasks.hypercache_verification、products.web_analytics.dags.cache_warming)还特意配置为"INFO 进 stdout、WARNING 及以上进 stderr"(借助 console_stdout_info + console_stderr_warning 两个 handler 与 MaxLevelFilter),避免流式采集器把正常 INFO 误标为错误。
另外,Celery 任务的生命周期事件(task_started、task_succeeded 等)由 django-structlog 自动以 INFO 级别记录,且已默认启用,无需手工处理。
1.5 日志安全红线
规范明确要求:不要记录敏感信息。以下内容永远不能出现在日志里:
- 授权令牌(authorization tokens)
- 密码(passwords)
- 财务数据(financial data)
- 健康数据(health data)
- 个人身份信息 PII(Personal Identifiable Information)
这一点不仅写在规范里,也体现在代码层的自动化校验中(详见下文"数据类与敏感字段"一节中 field(repr=False) 的强制机制)——PostHog 通过测试确保敏感字段不会经由 repr() 泄漏到日志与 traceback 里。
二、测试规范:让每个测试都"挣得"它的位置
2.1 测试是共享的、永久的负债
规范的开篇观点非常鲜明:测试套件是一种共享的、永久的负债——每个测试都会在每一次 PR 上永远运行,消耗 CI 时间、可能 flake(偶发失败)并阻塞无关工作,而且随着系统演进,它是别人必须持续维护的代码。
因此,评估一个新测试要从两个独立的维度出发:
- 价值(value):它能否捕获我们真实会犯的回归错误?
- 成本(cost):它在测试金字塔上处于多低的位置?
原则是"最大化价值、最小化成本"。这绝不意味着少写测试,而是意味着:删掉那些抓不到任何问题的测试,并把其余测试尽可能压到金字塔底部。
基础要求包括:
- 所有新包和大多数重要的新功能都应配套单元测试;
- 重要功能应配套集成测试和/或端到端测试;
- 分析相关的查询应配套快照测试(snapshot tests),便于评审时查看差异;
- pytest 一律使用
assert x == y而非self.assertEqual(x, y)风格——这是 pytest 官方文档推荐的做法,且失败时输出信息更丰富; - 优先写具体断言,如
assert ['x', 'y'] == response.json()["results"],而不是assert len(response.json()["results"]) == 2。原因有二:失败的输出要能直接告诉你如何修复;断言要尽可能具体,使得"代码坏了但测试仍通过"成为不可能。
2.2 自问一:这个测试值得存在吗?
写测试之前,先用一句话回答:"这个测试捕获了哪个现有测试尚未捕获的真实回归?"
要明确指出会破坏的 bug、代码路径和输入。像"提高覆盖率""这是好实践""这个函数存在"这类回答不算数。好的回答长这样:"如果某人让 parse_filters 丢掉 team_id 子句,这个测试会失败"。
规范还给出了四类典型的低价值测试,要能识别它们,转而扩展现有测试(或干脆删掉被测代码):
- 琐碎/框架行为测试:getter、setter、常量、测试 Django 保存了一行、DRF 序列化了一个字段——你测试的是别人的代码,不是你的;
- 变更探测器测试(change-detector tests):断言哪些私有方法被调用、mock 与当前实现一一对应。这类测试每次重构都会挂,却抓不到真正的 bug。正确做法是通过公共接口断言可观察行为(返回值、持久化状态、发出的事件、HTTP 响应),而不是断言产生该行为的内部编排;
- 冗余覆盖:一个新测试若只是已有测试的变体,应当做成
@parameterized用例(Python)或test.each行(Jest),而不是新建测试函数; - 追逐覆盖率:一行未覆盖的代码是"信息"而非"缺陷"——不要只是为了移动覆盖率数字而加测试。
2.3 自问二:为什么不能把它并入现有测试?
接着回答第二个问题:"为什么这不能作为已覆盖最近行为的那个测试的一个用例?"
挣得了覆盖 ≠ 挣得了新的测试函数。默认做法是给现有测试扩展一个参数化用例,只有当你能够说明为什么扩展行不通(不同的 setup、不同的单元、或者根本没有相关的现有测试)时,才写独立测试。
注意:扩展是为了消除重复,而不是为了省 setup 时间——因为参数化用例同样会为自己的 setUp 跑一次。把同一行为的各种变体折叠进去,但不要给一个已经通过的测试挂上不相关的断言。
2.4 把测试压向金字塔底部
PostHog 的测试金字塔每一层大约比下一层慢/容易 flake 一个数量级:
pure function → kea logic test → Django TestCase → ClickHouse-backed test → Playwright e2e
cheapest most expensive
目标是一个比例,而不是一个上限:底部有大量测试,顶部只有极少数。想要更多覆盖?就加在底部。
当一个逻辑很难廉价测试时,这是一个设计信号:把它抽取成纯函数(或 kea logic),直接测试它,而不是临时搭起数据库、请求和渲染环境。向上一级升级是最后手段,而不是默认选择。
具体规则:
- 用
TestCase而不是TransactionTestCase,除非你确实需要后者。TransactionTestCase在测试之间 flush 数据库而不是回滚事务——显著更慢,而且是跨测试干扰的常见来源。对于transaction.on_commit的副作用,使用self.captureOnCommitCallbacks(execute=True);需要 ClickHouse 不是切换的理由(ClickhouseTestMixin本身就运行在普通的TestCase上)。 - 只 mock 真正的边界:网络、外部 API、时钟、队列。不要 mock 自己的内部辅助函数——那是变更探测器测试的温床。
- 前端:只要行为在 logic 里,就优先写 kea logic 测试(
logic.actions/logic.values),而不是完整组件渲染;不要对大段渲染树做快照,改为断言具体字段。 - 保持确定性与隔离:不用
time.sleep或任意等待(用time_machine.travel(..., tick=False),或等待真实条件);不访问真实网络或外部服务;测试必须能按任意顺序通过。不要留下没有一行原因说明和关联 issue 的@skip/xfail/.only。 - 绝对日期是定时炸弹:夹具里的固定日期只有在真实时钟停在你留下它的位置时才有意义。任何把该日期与
now进行比较的测试——年龄、时间窗口、"是否最近"标志、过期判断——今天能过,几周后会在每个开放分支上失败。解决方案:把进程时钟固定到同一时刻(time_machine.travel(..., tick=False),或jest.useFakeTimers()配合jest.setSystemTime()),或者把夹具写成相对now。注意:时钟固定只覆盖进程内读时钟的代码;进程之外的(如 ClickHouse TTL、S3 生命周期规则)仍然走真实时钟。
2.5 快速的开发者(单元)测试
一个良好的单元测试应当:
- 一次只聚焦一个用例;
- 每个测试只有最小化的断言集合;
- 能很好地自我解释;
- 帮助你理解系统;
- 善用参数化测试,用一系列输入展示行为;
- 帮助我们确信"不可能之事不可表示"(impossible is unrepresentable);
- 帮助我们确信系统会按预期工作。
2.6 集成测试
- 集成测试应确保功能在运行中的系统里正常工作;
- 它们带来更大的信心(避免了"只测了一个 mock"的错误),但更慢;
- 它们对变更的脆弱性通常更低,因为测试的层级更高(例如测试 Django API 而不是其中使用的某个类)。
2.7 临时迁移测试
数据迁移(data migration)需要专门的迁移测试来保护发布流程。规范给出的生命周期是:
- 在迁移已跑过所有受支持环境、回滚窗口已关闭、且不再有任何受支持升级依赖旧数据状态之后,删除这个迁移测试;
- 删除过期迁移测试时,直接删除而不是标记为 skipped;迁移文件本身保留——全新 schema 的 CI 会继续校验迁移链可正常应用;
- 迁移工具、迁移安全校验、可复用的回填(backfill)系统,以及仍可手动运行的回填,它们的测试应当保留。
三、数据类规范:用 @frozen 消灭"元组交换"事故
3.1 什么时候用 dataclass 而不是 tuple
当返回或传递多个值时,优先使用小型 dataclass 而不是 tuple,尤其是:
- 两个或以上元素类型相同时(调用方可能悄悄互换它们,比如
(start, end)时间戳或(username, password)凭据); - 元素约 3 个及以上时,位置访问会伤害可读性。
3.2 使用团队默认装饰器 @frozen
PostHog 提供了一套"house-default"(团队默认)装饰器:
from posthog.dataclasses import frozen
@frozen
class BillingPeriod:
start: datetime
end: datetime
@frozen 一次性施加三个默认:frozen=True(不可变、可哈希)、kw_only=True(仅关键字构造,同类型字段无法错位传递)、slots=True(省内存、属性访问可防拼写错误)。
源码级佐证:其实现见 posthog/dataclasses.py——核心就是 kwargs.setdefault("frozen", True)、kwargs.setdefault("kw_only", True)、kwargs.setdefault("slots", True) 之后交给标准库 dataclass 包装。因为使用的是 setdefault,每一个 flag 都可以按类覆盖:
@frozen(slots=False):当类需要functools.cached_property时;- 显式
@dataclass(frozen=False, ...):当确实需要一个刻意可变的 builder 时。
3.3 消费约定:点号访问,禁止回退为位置解包
规范要求用点号访问结果(result.field),不要把 dataclass 再解包回位置局部变量(a, b = result.a, result.b)——那会重新制造 dataclass 之所以存在就是为了消灭的交换风险。
3.4 命名与敏感字段
- 用领域概念命名 dataclass(如
ClickHouseCredentials、BillingPeriod),永远不要用*Info/*Data/*Tuple这类后缀;只有当函数的结果本身就是这个"概念"时才使用*Result后缀; - 敏感字段必须标记
field(repr=False),确保凭据不会泄漏进日志、traceback 和 pytest 断言差异里。
3.5 强制机制:把规范变成 CI 红线
规范不只是纸面约定,而是有自动化的"棘轮(ratchet)"机制在执行:
- 在 posthog/test/repo_invariants/test_dataclass_defaults.py 中,通过 AST 扫描
posthog、ee、products、common四个目录,任何不带显式frozen=选择的新裸@dataclass都会让该测试失败(已有的旧用法被记录在 baseline 文件里豁免)。它给出的错误信息会明确引导你"优先使用posthog.dataclasses.frozen,或显式传frozen="; - 同样的,posthog/test/repo_invariants/test_dataclass_secret_fields.py 会扫描名字像凭据的字段(
secret、password、access_token、api_key、signing_key等 15 类 token),强制它们必须带field(repr=False),否则测试失败——真正做到了"敏感信息进不了repr(),也就进不了日志"; - 此外还有
prefer-frozen-dataclasses这个 semgrep 规则在编辑器/CI 层面直接内联标记违规用法。
四、ClickHouse 查询规范:产品代码永远用 HogQL
规范非常硬核:产品代码中始终使用 HogQL,而不是原始 ClickHouse 查询(raw queries)。原因有三:
- 数据安全:HogQL 自动把查询作用域限制在当前团队(team),防止意外的跨团队数据访问。直接查询多个团队的数据再在代码里拆分是危险的——即使现在正确,未来任何改动都可能引入数据泄露;
- 一致性:HogQL 正确且一致地处理属性访问、person 映射等 PostHog 特有的关注点;
- 查询归属:如果确实有正当理由直接查询 ClickHouse,务必用正确的产品标签(product tag)和 ClickHouse 用户来标记查询,保证查询可归属、可审计。
唯一可能正当化 raw 查询的场景是跨团队查询,但即便如此,也请先考虑替代方案:
- 能否改用 PostgreSQL 探测所需信息?(例如通过团队设置检查功能使用情况)
- 能否先用一条简单 ClickHouse 查询拿到 team IDs,再逐团队跑 HogQL 查询拿实际数据?
- 能否复用现有的跨团队基础设施(如 usage reports)?
五、开源还是企业版?ee 的边界判断
PostHog 默认开源(MIT),但新增功能时需要考虑应该用 MIT 许可证还是企业版(Enterprise edition)许可证。ee 目录下的所有代码都受不同的许可证覆盖。有一个关键的方向性约束:
从
ee挪到开源容易,反向则难。
因此判断要谨慎。另外,所有开源代码会被复制到 posthog-foss 仓库(ee 代码被剥离),所以你必须考虑:当 ee 的 import 不可用时,你的代码是否仍能工作。这要求开发者在编写开源代码时保持对 ee 依赖的最小化与可替代性。
结语:从规范到工程文化
PostHog 这份后端编码规范最值得借鉴的地方,在于它把"约定"升级成了"机制":日志用 django-structlog 统一结构化、异常用 capture_exception() 打通上报链路、测试以"价值/成本"双轴决策并以金字塔压底、数据类用 @frozen 默认值配合 repo_invariants 棘轮测试与 semgrep 规则强制落地、查询一律走 HogQL 保障租户隔离。文中所有配置与实现均可直接对照仓库源码继续深入:日志配置、异常上报、@frozen 实现、数据类棘轮测试 与 敏感字段测试。对于任何希望让后端代码库"可观测、可测试、可维护"的团队,这套规范本身就是一份高质量的实施蓝图。