前端诊断接口设计，先统一指标和版本
性能上报接口应先统一指标口径、单位、采样规则和版本，再实现 SDK。清晰的契约能减少服务端解析分支，也让预算告警带上足够的定位上下文。
1. 原始 PerformanceEntry 不能直接作为长期接口
在早期版本中，团队曾经定义过一个极其“宽泛”的性能上报接口。开发者直接把performance.getEntriesByType('resource')的原始数组序列化后往后端扔：
// 导致严重返工的旧版性能上报 API (缺少类型约束与标准口径) export interface LegacyPerformanceReport { pageUrl: string; metrics: any; // 致命伤：使用 any 类型，导致上报格式千奇百怪！ timestamp: number; }如果单位、字段名和版本没有约束，聚合查询会变得困难。应在客户端和服务端同时校验，并为协议变更保留版本字段和兼容期。
2. 确定性设计一：基于 Zod 的 Core Web Vitals 强契约数据模型
要做到接口不返工，第一步必须建立严格的数据模型与运行时 Schema 校验。
我们参照 Google Core Web Vitals 官方标准口径，使用 Zod 重新设计了确定性的性能诊断上报契约：
import { z } from "zod"; // 1. 定义 Core Web Vitals 核心性能指标数据 Schema export const WebVitalsMetricSchema = z.object({ name: z.enum(["CLS", "FCP", "FID", "INP", "LCP", "TTFB"]), value: z.number().min(0), // 必须为非负毫秒数（CLS 为比率数值） rating: z.enum(["good", "needs-improvement", "poor"]), delta: z.number().min(0), id: z.string().uuid(), // 每次采样的唯一跟踪 ID }); // 2. 定义性能预算 (Performance Budget) 配置契约 export const PerformanceBudgetSchema = z.object({ maxLCPMs: z.number().default(2500), maxINPMs: z.number().default(200), maxCLSRatio: z.number().default(0.1), maxBundleSizeKB: z.number().default(500), }); // 3. 全局统一上报 Payload 数据模型 export const PerformanceReportPayloadSchema = z.object({ appId: z.string().min(1), env: z.enum(["development", "staging", "production"]), pageUrl: z.string().url(), metrics: z.array(WebVitalsMetricSchema), budgetViolations: z.array(z.string()).default([]), clientTimestamp: z.number().int().positive(), }); export type PerformanceReportPayload = z.infer<typeof PerformanceReportPayloadSchema>; export type PerformanceBudget = z.infer<typeof PerformanceBudgetSchema>;探针收集后可先用safeParse()校验。生产环境应采样记录校验失败原因，避免大量console输出；服务端也必须再次校验，不能信任客户端数据。
3. 确定性设计二：结构化错误语义与预算超标告警引擎
第二步是建立清晰明确的错误语义（Error Semantics）。
当诊断探针发现页面实际指标突破了设定的性能预算（Performance Budget）时，不能仅仅静默记录，必须抛出带有明确类型标记与定位上下文的结构化异常：
export class PerformanceDiagnosticError extends Error { public readonly code: string; public readonly violationMetric: string; public readonly actualValue: number; public readonly budgetLimit: number; constructor( metricName: string, actualValue: number, budgetLimit: number, message: string ) { super(`[Performance Budget Exceeded] ${metricName}: ${actualValue} (Budget Limit: ${budgetLimit}) - ${message}`); this.name = "PerformanceDiagnosticError"; this.code = "PERF_BUDGET_VIOLATION"; this.violationMetric = metricName; this.actualValue = actualValue; this.budgetLimit = budgetLimit; } } export class PerformanceBudgetEvaluator { private budget: PerformanceBudget; constructor(budget: Partial<PerformanceBudget> = {}) { this.budget = PerformanceBudgetSchema.parse(budget); } public evaluateMetric(metricName: "LCP" | "INP" | "CLS", value: number): void { let limit = 0; if (metricName === "LCP") limit = this.budget.maxLCPMs; if (metricName === "INP") limit = this.budget.maxINPMs; if (metricName === "CLS") limit = this.budget.maxCLSRatio; if (value > limit) { const error = new PerformanceDiagnosticError( metricName, value, limit, `页面当前 ${metricName} 已严重突破性能预算！` ); console.warn(error.message); // 可在此触发日志埋点或透传给 CI 告警通知系统 } } }4. 接口设计要点
写 API 和做雕刻一样，结构定得好，后面才不需要缝缝补补。
- 强 Schema 校验是前提：用 Zod 等工具把性能指标的数据格式、单位与枚举限制死，杜绝 any 类型的滥用。
- 错误语义要具体：明确区分是探针采集失败、网络传输超时，还是真正的性能预算超标。
- 遵循官方口径：紧跟 Core Web Vitals 官方标准，不要自己发明没有根据的性能指标名词。
契约明确，语义清晰，性能诊断才能真正发挥出自动守卫的作用。
)
