兰 亭 墨 苑

期货 · 量化 · AI · 终身学习

给你一份“可直接套用”的 PRD/技术方案检查表（建议你保存）

2025年12月13日
20 分钟阅读
#202512

互联网工程基本盘（面向“懂一点技术的产品经理”的详述）

你要掌握的不是“能手写所有代码”，而是能在评审/排期/验收时把关键约束说清楚，并能用工程语言把风险提前暴露。下面按你列的四块展开：API 设计、异步任务、数据与埋点、线上稳定性。每块都给你：核心概念、常见坑、PM 该问什么、PRD/验收应写什么。

1) API 设计（REST/JSON、幂等、分页、错误码、鉴权）

1.1 REST/JSON：接口设计的“产品化”

你需要关心的不是 REST 教条，而是：一致性、可理解性、可演进性。

  • 资源建模：用名词表示资源，用动词表示动作
    • 好：GET /orders/{id}、POST /orders、POST /orders/{id}/cancel
    • 容易变烂：POST /getOrder、POST /doCancelOrder
  • HTTP 方法语义（用于减少歧义）
    • GET：只读、可缓存
    • POST：创建/触发动作（非幂等常见）
    • PUT/PATCH：更新（PUT 全量，PATCH 部分）
    • DELETE：删除
  • 版本管理
    • 常见：/v1/... 路径版本；或 header 版本
    • PM 要求：向后兼容策略（新增字段不破坏旧客户端；避免改字段含义）

PM 该问：

  1. 这个 API 面向谁（前端/外部客户/内部服务）？SLA 与稳定性要求不同。
  2. 字段是否有明确含义、单位、枚举值？是否允许为空？默认值是什么？
  3. 是否支持灰度/多版本客户端共存？老客户端多久淘汰？

1.2 幂等：避免“重复提交/重试导致多扣款、多发货”

幂等：同一个请求调用多次，效果等同于调用一次（至少对业务结果而言）。

  • 为什么重要：移动端弱网、网关超时、客户端重发、服务端重试都很常见。
  • 典型高风险场景：支付、下单、发券、发货、创建工单、触发异步任务。

常见实现方式（你不必写代码，但要能要求）

  1. Idempotency-Key（幂等键）
    客户端生成唯一 key，服务端用它做去重（缓存/DB 约束）。
  2. 业务唯一约束
    如“同一用户对同一活动只能领一次券”，用唯一索引保证。
  3. 请求号/去重表
    保存请求状态：处理中/成功/失败，重复请求直接返回历史结果。

PM 在 PRD/验收里要写清：

  • 哪些接口必须幂等（列出清单）
  • 幂等窗口期（例如 24h 去重还是永久去重）
  • 重复请求返回什么（同结果？同订单号？同错误码？）

1.3 分页：避免“数据一多就接口炸了/客户端体验差”

分页是典型的“早期不重视，后期重构很痛”。

两种主流分页：

  • Offset 分页：page=1&pageSize=20
    • 优点：简单
    • 缺点：数据量大时性能差；数据变动会造成“翻页重复/漏数据”
  • Cursor 分页（推荐用于时间线/列表流）：cursor=xxx&limit=20
    • 优点：性能更好、稳定
    • 缺点：实现复杂；产品需要接受“不是跳页而是顺序翻”

PM 该问：

  1. 列表会不会很大（10万+）？是否需要 cursor？
  2. 排序规则是什么（按创建时间？按热度？）是否稳定？
  3. 是否需要“跳到第 N 页”的能力？如果必须跳页，cursor 可能不合适。

验收点：

  • pageSize 上限（防止被拉爆）
  • 返回是否包含 hasMore/nextCursor/total（total 很贵，不一定每次都有）
  • 对新增/删除导致的重复与漏数据是否可接受（需明确）

1.4 错误码：让“失败”可运营、可排障

不要只依赖 HTTP 500/400；要有可机器处理的错误码体系。

建议结构：

  • HTTP 状态码：表达大类（401 未认证、403 无权限、429 限流、5xx 服务端故障）
  • 业务错误码：表达具体原因（如 ORDER_ALREADY_CANCELED）
  • message：给人看的提示（可本地化）
  • trace_id/request_id：便于排障

PM 该问：

  1. 哪些错误可以引导用户自助修复（比如参数不合法/权限不足）？
  2. 哪些错误需要自动重试（超时、依赖服务抖动）？
  3. 哪些错误必须告警（支付失败率飙升、库存锁失败异常增加）？

1.5 鉴权：你要能把“谁能做什么”说清楚

鉴权不是“加个登录”那么简单，而是权限模型与安全边界。

常见方式：

  • 用户登录态（cookie/session/token）
  • 服务间鉴权（mTLS、签名、JWT、AK/SK）
  • RBAC（角色权限）、ABAC（基于属性，如部门/数据归属）
  • 对 AI 场景还要强调：数据权限 + 输出权限 + 操作审计

PM 必备清单：

  • 资源归属：数据属于谁？是否跨租户？
  • 最小权限：默认不可见、按需授权
  • 审计：关键操作要留痕（谁在何时访问/导出/删除）

2) 异步任务（队列、重试、幂等、死信）

2.1 为什么要异步

当一个请求里包含：耗时长、依赖多、可并行、可延后，就适合异步：

  • 发邮件/短信、生成报表、视频转码、批量导入、AI 生成长内容、批量 embedding 等。

PM 要明确：

  • 用户是否需要“立刻得到结果”？还是“提交后可查询进度”？
  • 可接受的时延（秒级/分钟级/小时级）
  • 失败如何通知用户（站内信/邮件/重试后再告知）

2.2 队列与重试：可靠性的核心

队列：把“提交任务”和“执行任务”解耦，提升吞吐与稳定性。

重试策略（必须产品化）

  • 重试次数与间隔：常用指数退避（1s、2s、4s、8s…）
  • 可重试与不可重试的错误分类：
    • 可重试：超时、临时网络故障、下游 5xx
    • 不可重试：参数非法、权限不足、余额不足（重试没意义）
  • 任务超时与取消：用户取消后是否继续跑？资源怎么回收？

PM 该问：

  1. 这类任务是否可能重复投递？重复执行是否会产生坏结果？（=> 幂等）
  2. 失败率多少触发告警？积压多少算事故？（=> 可观测+容量）
  3. 用户如何查看状态？（=> 状态机与可查询）

2.3 幂等与“至少一次投递”的现实

很多消息队列提供的是至少一次（可能重复），因此消费者必须幂等。

常见任务状态机（PM 能读懂、能写进 PRD）

  • PENDING 已创建待执行
  • RUNNING 执行中
  • SUCCEEDED 成功
  • FAILED_RETRYING 失败待重试
  • FAILED 终态失败
  • CANCELED 取消

验收点：

  • 重复提交同一任务不会产生多份结果/多次扣费
  • 失败重试不会造成资源泄漏或越滚越大

2.4 死信队列（DLQ）：让“怎么都失败的任务”可治理

死信：重试到上限仍失败的消息，进入 DLQ，等待人工/脚本处理。

PM 要求：

  • DLQ 有管理后台/报警，能看到失败原因、payload、失败次数
  • 有“重放/修复后重试”的机制（运营/工程可操作）
  • 记录任务关联用户/订单，便于补偿

3) 数据与埋点（事件模型、指标口径、漏斗、AB）

这是 PM 最该掌握的一块：它决定你能不能用数据闭环驱动迭代。

3.1 事件模型：把“用户行为”变成结构化数据

**事件（event）**通常包含：

  • event_name：如 search_submit
  • user_id / device_id / session_id
  • timestamp
  • properties：query、入口、实验分组、页面、商品类目等

关键：事件要能还原路径、能做漏斗、能做归因。

PM 常犯错：

  • 只埋“曝光/点击”，缺少关键上下文（入口、实验组、query）
  • 字段命名混乱、版本迭代随意，导致口径崩坏
  • 没有 user_id 贯通（只靠 device_id 导致跨端断裂）

PM 该输出的埋点文档应包含：

  • 事件列表（触发时机、是否必埋、是否去重）
  • 字段字典（类型、枚举、是否必填、示例）
  • 采样策略（全量还是抽样）
  • 延迟要求（实时/小时级/天级）

3.2 指标口径：同一个指标只能有一个定义

指标的成功在于“可比较”。口径不统一，团队会陷入无休止争论。

例：转化率到底是？

  • 点击到下单？还是曝光到支付？是否去重？窗口期 24h 还是 7d？

PM 要求：

  • 指标定义（分子/分母）
  • 去重规则（按用户/按 session/按订单）
  • 时间窗口（自然日/滚动 24h）
  • 过滤条件（剔除风控用户？剔除内部员工？）
  • 数据源与延迟（实时看板还是 T+1）

3.3 漏斗：用来定位“掉在哪里”

漏斗是连续步骤：A→B→C。
要能解释“掉”的原因，需要每一步埋点可追踪且有上下文。

验收点：

  • 漏斗每步事件都能串起来（同一 session 或同一业务 id）
  • 能分维度看（渠道、城市、机型、实验组、新老用户）
  • 能定位异常（某机型转化骤降）

3.4 A/B 实验：避免“拍脑袋上线”

你需要会设计最基本的实验体系：

核心要素：

  • 实验单元：按用户还是按设备？（影响污染）
  • 分桶方式：稳定、可复现（同用户始终同组）
  • 主指标 & 护栏指标（guardrail）
    • 主指标：你要提升什么（转化、留存、满意度）
    • 护栏：不能变差的（崩溃率、延迟、投诉率、成本）
  • 样本量与实验周期：至少覆盖工作日/周末差异

AI 功能特别要加：

  • 质量指标（准确率、引用正确率、人工评分）
  • 成本指标（token/次、平均延迟、失败率）
  • 风险指标（幻觉率、违规输出率）

4) 线上稳定性（日志/指标/追踪、告警、容量与限流）

这部分决定“能不能上线、敢不敢扩量”。

4.1 三大可观测性：Logs / Metrics / Traces

日志 Logs：记录“发生了什么”

  • 关键：结构化日志（JSON）、包含 request_id/trace_id/user_id
  • AI 场景要加：模型名、token 输入输出、耗时、检索命中文档数、缓存命中

指标 Metrics：用数字趋势看健康

  • QPS、P95/P99 延迟、错误率、超时率
  • 队列积压、重试次数、DLQ 数量
  • 成本：token/s、每请求成本、缓存命中率

链路追踪 Traces：定位“慢在哪里”

  • 一个请求经过网关、服务、DB、向量库、LLM，各段耗时清楚

PM 该问：

  1. 线上出问题时，能在 10 分钟内定位到哪一段慢/错吗？
  2. 有没有按接口/渠道/实验组拆分的指标？
  3. AI 调用失败时，是模型问题、网络问题、还是数据检索问题？

4.2 告警：让问题“可被及时发现”

告警不是越多越好，关键是可行动（actionable）。

  • 告警阈值：错误率 > X%、P99 延迟 > Y、DLQ > N、队列积压 > M
  • 分级：P0（全挂/资金风险）、P1（核心路径受损）、P2（局部异常）
  • 告警必须带：影响范围、开始时间、最近变更、trace/sample

PM 在事故复盘要推动：

  • 是否有 SLO（例如 99.9% 可用性、P95<500ms）
  • 是否有 runbook（处理手册）
  • 是否做到“变更可追踪”（发布版本、配置变更、模型版本）

4.3 容量与限流：防止“流量一来全挂”

容量规划：估算峰值并做压测/预案

  • 峰值 QPS、并发数、单请求耗时、资源占用
  • 依赖服务容量（DB、向量库、LLM 接口配额）

限流与降级（PM 必须写进方案）

  • 限流：每用户/每 IP/每 API key；超过返回 429
  • 降级策略：
    • 关闭非核心功能（如推荐理由、二次重排）
    • 只返回检索结果不生成（RAG 降级）
    • 切换小模型或模板回复
    • 进入“排队模式”（异步返回）

验收点：

  • 明确“核心路径”优先级（哪些必须保，哪些可牺牲）
  • 限流后用户体验与提示文案
  • 是否支持灰度：小流量先跑、逐步放量

给你一份“可直接套用”的 PRD/技术方案检查表（建议你保存）

API

  • 资源路径、方法、请求/响应示例、字段字典
  • 幂等策略（哪些接口、key、窗口期、重复返回）
  • 分页方案（offset/cursor、上限、排序稳定性）
  • 错误码表（可重试/不可重试）
  • 鉴权与权限边界、审计需求

异步任务

  • 任务状态机、进度查询、取消策略
  • 重试次数/间隔/错误分类
  • 幂等与去重策略
  • DLQ 与重放机制、告警阈值

数据与实验

  • 埋点事件清单与字段字典、采样、延迟
  • 指标口径（分子/分母/去重/窗口/过滤）
  • 漏斗定义与分群维度
  • AB：分桶、主指标、护栏指标、周期、样本量估算思路

稳定性

  • Logs/Metrics/Traces 最小集
  • SLO 与告警策略、runbook
  • 容量规划、压测、限流与降级、灰度发布

如果你愿意，我可以结合你正在做的具体功能（例如“AI 客服/RAG 知识库/内容生成/搜索问答”），把以上四块转成一份你项目可直接用的接口草案 + 埋点表 + 指标口径 + 告警阈值建议。你现在的场景是哪一种？