兰 亭 墨 苑

标题 *

URL 别名 *

内容 * (支持 Markdown 格式) ## 互联网工程基本盘（面向“懂一点技术的产品经理”的详述） 你要掌握的不是“能手写所有代码”，而是能在评审/排期/验收时把关键约束说清楚，并能用工程语言把风险提前暴露。下面按你列的四块展开：**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 知识库/内容生成/搜索问答”），把以上四块转成一份**你项目可直接用的接口草案 + 埋点表 + 指标口径 + 告警阈值建议**。你现在的场景是哪一种？

配图 (可多选)

标签