指标口径即代码：把 47 页 Wiki 口径搬进 metric-as-code 并上 CI 校验

站在指标体系落地的视角，讲一次把「散落在 Wiki 和群聊里的指标口径」收敛成结构化定义、用 git 版本化、并在 CI 里做口径冲突检测的完整落地。重点是「口径 = 五要素」这个模型，以及一套可复现的 YAML schema + 校验脚本。

一、现象与背景

接手一个 B 端 SaaS 的数据团队，指标口径的「真相」散落在 47 个 Wiki 页面 + 6 个业务群聊里。接手第一周就撞上典型场景：同一个「月活跃用户（MAU）」，增长、产品、客服三个团队给出的数字分别是 231 万 / 214 万 / 198 万，差了 16%，没人说得清谁对。

更糟的一次事故：产品方把 MAU 的口径从「当月登录过」悄悄改成「当月打开 App 且停留 > 30 秒」，但只在自己团队的看板里改了 SQL。结果是 12 张看板数字一夜跳变，业务方连续投诉了 3 天，最后靠翻 3 个月的群聊记录才拼出旧口径。

根因很直白：口径没有被当成一种「可校验、可 diff、可回滚」的资产，它只是自然语言。

二、原理与根因

一个指标口径，本质上由五个要素唯一确定，缺一个就会漂移：

1. 度量（measure）：count / sum / distinct_count …
2. 去重键（dedup_key）：按 user_id 还是 device_id 去重；
3. 过滤条件（filters）：排除测试号、剔除机器人流量等；
4. 维度（dimensions）：按渠道 / 版本 / 地域切分；
5. 时间窗口（time_window）：自然日还是业务日、是否滚动 30 天。

「月活」之所以三版数字，就是第 2、3、5 项各不相同：有人按 device_id 去重（换设备就翻倍），有人没排除测试号，有人用「自然月」有人用「滚动 30 天」。

而 Wiki 是自然语言，有三个致命缺陷：无法校验（写错没人发现）、无法 diff（改了什么看不知道）、无法 CI（改完直接生效，没有拦截点）。把口径留在文档里，等于把「源代码」放在聊天记录里。

三、具体做法（可复现）

第一步：每个指标写成一个结构化定义文件，目录即指标字典。

# metrics/mau.yaml
name: mau
version: v3
owner: growth-data
measure: distinct_count
dedup_key: user_id          # 显式锁定，不写 device_id
filters:
  - "env != 'test'"
  - "app_open_duration_sec > 30"
dimensions: [channel, app_version, region]
time_window:
  type: rolling_days
  days: 30
source_table: dws_user_active_di
effective_date: "2026-03-01"
sunset_date: null           # 口径下线日期
aliases: [月活, 月活跃用户, MonthlyActiveUsers]

第二步：用 git 版本化，所有口径变更走 PR，diff 直接可见。

第三步：CI 里跑 schema 校验 + 口径冲突检测，关键检测项：

• 同名不同义：name 相同但五要素不一致 → 直接 fail；
• 同义不同名：aliases 交叉但 name 不同 → 警告；
• 被引用但已下线：看板 SQL 里引用了 sunset_date 已过去的口径 → fail；
• 去重键缺失：measure=distinct_count 但没写 dedup_key → fail。

校验脚本核心片段（Python，约 60 行，只贴骨架）：

import yaml, glob, sys
from collections import defaultdict

def load_all():
    out = []
    for f in glob.glob("metrics/*.yaml"):
        with open(f) as fh:
            m = yaml.safe_load(fh)
            m["_file"] = f
            out.append(m)
    return out

def five_tuple(m):
    return (m["measure"], m["dedup_key"],
            tuple(sorted(m["filters"])),
            tuple(m["dimensions"]), m["time_window"])

def check(ms):
    errs, warns = [], []
    by_name = defaultdict(list)
    for m in ms:
        by_name[m["name"]].append(m)
        if m["measure"] == "distinct_count" and not m["dedup_key"]:
            errs.append(f'{m["_file"]}: distinct_count 缺少 dedup_key')
    for name, group in by_name.items():
        if len({five_tuple(m) for m in group}) > 1:
            errs.append(f"同名不同义: {name} 存在多种口径")
    # aliases 冲突
    alias_map = defaultdict(list)
    for m in ms:
        for a in m["aliases"]:
            alias_map[a].append(m["name"])
    for a, names in alias_map.items():
        if len(set(names)) > 1:
            warns.append(f"同义不同名: alias={a} -> {names}")
    return errs, warns

if __name__ == "__main__":
    errs, warns = check(load_all())
    for w in warns: print("WARN", w)
    if errs:
        for e in errs: print("FAIL", e)
        sys.exit(1)

落地后，CI 单轮跑完 约 12 秒（早期全量扫 47 个文件约 40 秒，缓存后降到 12 秒）。口径变更必须先在 PR 里把五要素 diff 出来，review 通过才合入。

四、踩过的坑与反直觉之处

• 以为「加个版本号」就够了：v1、v2 同时被引用，看板不知道用哪个。必须强制 effective_date + sunset_date，并让 CI 检测「被引用但已下线」，否则版本化只是换了个地方乱。
• 去重键是最常被漏的一项：UV 用 device_id 还是 user_id，口径里没写死，换设备 / 清缓存就翻倍。这条我们靠 CI 的 distinct_count 必须有 dedup_key 硬拦截。
• 时间窗口不是「自然月」：金融类业务日按凌晨 2 点切换，跨天订单归到哪一天，口径里必须写 type + 切换点，否则月底数字对不上。
• 别名造成 recall 重复命中：「月活 / MAU / 月活跃用户」三个别名指向同一指标，检索和看板匹配时命中两次，必须把 aliases 收敛进同一条目。

五、结论与可复用清单

口径漂移的根因是「口径是自然语言，不是资产」。把口径收敛成五要素、git 版本化、CI 强校验，是成本最低、收益最确定的一步。

可复用清单：

1. 每个指标一个 YAML 文件，目录即指标字典；
2. 五要素缺一不可：measure / dedup_key / filters / dimensions / time_window；
3. effective_date + sunset_date 强制成对出现；
4. CI 四道闸：同名不同义 fail、去重键缺失 fail、下线仍被引用 fail、同义不同名 warn；
5. aliases 收敛进同一条目，避免检索重复命中；
6. 所有口径变更走 PR，diff 可见后才合入。

一句话：把口径当代码管，漂移就少了一大半。