做在线学习类产品的时候很多产品经理会把注意力放在页面交互、进度条样式、按钮触发逻辑上但真正决定用户学习记录准不准、开发联调顺不顺的往往是那个不起眼的学习记录提交接口。我是在拆解原型设计的第三个模块时才彻底意识到这件事——标题里的 Day03-03 对应的正好是“设计提交学习记录接口”这个主题视频本身只有 5 分 49 秒但信息密度很高从业务规则、字段定义到异常场景基本把接口方案从雏形到可评审的完整路径讲透了。如果你正在做在线教育、知识付费、企业内部培训这类产品或者刚转岗做产品经理、需要在原型阶段输出接口设计这篇文章可以给你一套能直接照搬的落地方法。我会先拆解这个接口背后要解决的业务问题再讲字段与数据结构怎么定然后给出一份可以直接抄作业的接口原型模板最后整理我在设计过程中踩过的坑。接口文档写得好不好直接决定你后续要陪开发加班到几点这句话一点不夸张。1. 先搞清楚学习记录接口到底在解决什么问题1.1 一个学习记录功能的产品需求长什么样学习记录功能在不同产品里的表现差异很大。视频课程要记录用户看到第几分钟下次进来从上次位置续播图文资讯要记录用户读到哪一段方便快速回到未读部分企业培训系统还要统计学习时长作为考核依据。表面上看是“存一条记录”但本质上牵扯到三个核心问题进度怎么算、时长怎么算、完成状态怎么定。我在设计阶段的第一件事不是急着开文档写接口字段而是先跟业务方对齐这三个口径。比如视频学习时长是播放器活跃时长还是页面停留时长用户倍速播放时长按真实时间算还是按视频时间算用户反复拖动进度条进度百分比按最大播放位置记还是按最新位置记这些业务规则不确定接口字段设计了也是白设计后续开发一定会反复找你确认。另一个容易忽略的点是客户端的交互时机。学习记录什么时候触发提交是播放器暂停时、页面退出时、还是定时自动上报不同触发时机对应接口的调用频率和数据精度。如果只在退出时提交一次用户中途崩溃或杀掉 App学习记录就直接丢了。这块业务规则的确认必须放在接口设计之前完成不然做出来的原型经不起评审。1.2 接口设计的三个核心输入业务规则、数据埋点、交互时序我在做接口方案时会先画一张草图把用户从进入学习页面到退出这段时间内所有关键事件列出来。比如视频课程关键事件包括进入课程页、开始播放、播放进度到达 30 秒、暂停、拖动进度条、播放完成、退出页面。每个事件对应是否要触发数据上报触发时携带哪些参数这些参数又对应接口里的哪些字段。这一步其实就是数据埋点设计。很多新手产品经理会忽略它直接照着百度出来的接口文档模板抄一份结果埋点事件和接口字段对不上前端开发做完才发现少传了好几个参数。正确做法是先定义事件再由事件推导接口字段。比如“开始播放”事件需要记录内容 ID、用户 ID、开始时间“暂停”事件需要记录当前进度、已播放时长。把这些事件需要的参数汇总去重就是提交接口的请求参数列表。交互时序也要想清楚。是每 10 秒自动上报一次还是只在暂停和退出时上报自动上报能提高数据准确度但接口调用频率高对服务端压力大事件触发上报调用次数少但用户断网或闪退容易丢数据。我在做第一版设计时选了只在暂停和退出时上报后来发现用户学习途中切后台回来进度没变化才知道还得加一个切后台时的上报事件。这个经验让我意识到交互时序的设计直接影响接口可靠性不能拍脑袋。1.3 为什么产品原型阶段就要介入接口设计很多产品团队的习惯是产品出页面原型开发拿到原型后再自己设计接口。这种流程不是不行但有两个问题。第一开发各自理解业务规则同一套逻辑在不同接口里实现得五花八门比如有的接口用 update 方式覆盖学习记录有的用 insert 方式新增记录导致后续排查数据要对半天。第二产品在原型里标注的交互逻辑比如“进度超过 90% 视为学完”开发可能根本没注意到直接把判断逻辑写到前端服务端记录到的完成状态就跟产品预期不一致。我现在的习惯是原型阶段就把接口方案定出来。不用写后端代码也不用纠结技术实现只要把接口路径、请求方式、参数列表、返回结构这些确定清楚作为产品原型的一部分交付给开发和测试。这样做的好处非常明显开发照着接口文档开发前后端可以并行工作测试照着接口文档写测试用例不用反复问需求业务方也能在评审时直观看到学习记录到底记录了什么减少后续扯皮。2. 原型阶段的接口方案怎么做字段、结构与请求方式2.1 接口原型要包含的五个核心要素在产品原型阶段输出接口设计不是让你把完整的后端接口文档写出来而是把五个核心要素定义清楚。第一是请求路径也就是接口地址一般从业务模块出发命名学习记录模块的路径可以设计成/api/v1/learning-records。第二是请求方式提交学习记录肯定用 POST因为它是新增或更新操作不是查询。第三是请求参数这是最核心的部分要列出每个字段的名称、类型、是否必填、含义说明。第四是返回结构告诉前端接口调用成功或失败后能拿到什么数据。第五是错误码定义常见的异常情况比如参数缺失、学习内容不存在、进度值非法。这五个要素看起来简单但我在实际设计中发现很多初学者最喜欢漏掉的是错误码和异常场景。他们觉得接口正常返回就行了忽略了前端也需要处理失败情况。比如学习记录提交失败后前端要判断是网络问题还是参数问题才能决定是自动重试还是提示用户。错误码定义清楚了前后端对协作效率能提升一大截。2.2 学习记录提交接口的字段设计详解字段设计是接口设计的核心也是最考验产品经理对业务理解深度的地方。我之前整理过一个比较通用的学习记录提交接口字段清单后来在多个在线教育项目里复用基本跑得通。我会把所有参数按业务维度分成四组用户维度、内容维度、学习行为维度、技术辅助维度。用户维度和内容维度比较好理解就是用户 ID 和内容 ID。这里要注意一个问题很多产品内容是有层级关系的比如一个课程下面有多个章节章节下面有多个视频。提交学习记录时字段里是只传视频 ID 还是同时传课程 ID 和章节 ID我建议都传而且设计时要有清晰的字段命名比如course_id、chapter_id、video_id。不为别的就为了后续做数据统计时能灵活聚合不用靠一张内容映射表到处查。学习行为维度是重头戏。duration字段表示本次学习时长单位是秒我习惯用整数型避免浮点运算误差。progress字段表示学习进度取值范围是 0 到 100保留两位小数。completed字段表示本次提交时是否已完成布尔类型。这三个字段要配合起来理解duration 是这次上报累计了多长学习时间progress 是用户现在学到哪个位置completed 是这次学习是否触发了“学完”判定。技术辅助维度容易被忽略但很实用。device字段表示用户使用的设备类型是 iOS、Android 还是 Web 端后续排查问题时很好用。network_type字段表示网络类型是 Wi-Fi 还是移动网络这个字段可以帮助服务端判断是否要控制响应包大小。还有一个scene字段标记本次上报是从哪个场景触发的比如暂停、退出、自动上报、主动同步这个字段在排查问题时价值极大可以说是我个人最推荐加入的字段。2.3 数据结构选型JSON 里的嵌套与表关联学习记录接口的请求体我一般用 JSON 格式。JSON 的好处是结构清晰、可读性强前端构造方便后端解析也方便。但 JSON 内部的数据结构需要仔细考虑是全部字段平铺在最外层还是把同一业务维度的字段放到一个嵌套对象里。我见过不少接口设计把所有字段堆在一层看起来简单但字段多了以后很难维护。比如把用户 ID、课程 ID、视频 ID、学习时长、进度全部作为顶层字段字段数量一旦超过十个读文档的人很难一眼找到自己关心的字段。另一种做法是适当分组比如{ user: { user_id: u_20240301_001 }, content: { content_id: c_101_video_202, content_type: video, course_id: course_101, chapter_id: chapter_01 }, learning: { duration: 120, progress: 67.80, completed: false, started_at: 2024-03-01T10:00:00Z, ended_at: 2024-03-01T10:02:00Z }, context: { scene: exit, device: iOS, network_type: wifi, idempotency_key: a1b2c3d4-1234-5678-9abc-000000000001 } }这种嵌套结构的可读性比平铺好很多但我不建议嵌套层数超过三层太深会导致前端构造和后端解析都比较繁琐。还有一个要注意的地方嵌套对象里不要放不必要的字段每个字段都要有存在的理由不然文档写出来会被开发吐槽。2.4 关联接口设计查询、批量提交与完成标记提交学习记录接口不会孤立存在它通常和查询接口、批量提交接口、完成标记接口一起构成完整的学习记录模块。产品原型阶段最好把关联接口也一并梳理出来形成接口之间的关系网这样开发排期和测试用例设计都更有依据。查询接口一般设计成 GET/api/v1/learning-records/{user_id}/{content_id}返回用户对某个学习内容的最新学习记录用于“继续学习”功能。批量提交接口的设计需要考虑实际场景比如用户离线学习了半个小时客户端缓存了多条记录连网后需要一次性提交。这时设计成 POST/api/v1/learning-records/batch请求体里放一个数组一次性提交多条记录能有效减少网络请求次数。完成标记接口在某些产品里独立存在在另一些产品里由提交接口的completed字段承担。我的建议是如果完成事件需要额外记录完成时间、完成时的得分或附加信息就单独设计一个完成接口如果只是把完成状态降级为一个布尔值直接在提交接口里处理更简洁。接口数量不是越多越好简单够用才是产品设计的核心原则。3. 实操过程把学习记录接口画进原型里3.1 搭建接口原型页面表格让字段一目了然在 Axure、Figma 或者普通的 Markdown 文档里我习惯用表格来呈现接口字段这是目前效率最高的方式。表格的好处是字段名、类型、必填、说明可以纵向对齐开发在实现时不用来回翻需求文档。以提交学习记录接口为例我会把字段表格设计成下面这样这张表我到现在还在用是经过多个项目验证过的通用模板字段名类型必填说明user_idstring是用户唯一标识content_idstring是学习内容唯一标识content_typestring是内容类型video/article/coursecourse_idstring否所属课程 ID可选填chapter_idstring否所属章节 ID可选填durationint是本次学习时长单位秒progressfloat是学习进度范围 0.00 - 100.00completedboolean是本次提交是否完成学习started_atdatetime是本次学习的开始时间ISO 8601 格式ended_atdatetime是本次学习的结束时间scenestring建议触发场景play/pause/exit/auto_syncdevicestring否设备类型iOS/Android/Webnetwork_typestring否网络类型wifi/4g/5gidempotency_keystring建议客户端生成的幂等键防止重复提交这个表格最大的价值在于把“可空”和“建议填写”区分开。必填字段是后端强校验的少了直接报错可空字段是后端不校验、但接收后可以做分析的建议填写字段是业务上需要、但为了避免极端情况不设为硬性必填的。这样设计既保证了接口的健壮性又不会因为字段太严格导致客户端上报失败。3.2 模拟请求和返回让开发一眼看懂数据结构光有字段表格还不够我还要在原型里附上完整的请求示例和返回示例。开发人员看到数据结构示例比自己从字段定义里拼结构要直观得多。这也是我在评审时经常用的手段——直接展示 JSON 示例让开发确认细节。一个完整的请求示例就是上面那段 JSON 代码。返回示例我则会同时设计成功和失败两种{ code: 0, message: success, data: { record_id: rec_20240301_000123, server_time: 2024-03-01T10:02:05Z } }失败返回示例{ code: 40002, message: lesson progress invalid, data: null }成功返回里的record_id很重要它表示服务端真正落库后生成的记录 ID客户端可以把本地记录和服务端记录对应起来。server_time也有用因为客户端时间不一定可靠以服务端时间为准可以避免后续统计时间偏差。把这两个字段放在返回里是我做了好几个项目之后总结出来的最优解。3.3 边界情况与异常处理在设计阶段就把雷排掉接口设计最怕的是只考虑 happy path正常流程跑通了一旦遇到异常场景就各种问题。我在设计学习记录提交接口时会把常见边界情况全部列一遍逐个想清楚应对方案然后补进接口文档里。第一个边界是时间戳格式问题。前端生成的started_at和ended_at必须统一格式否则后端解析会崩。我推荐直接用 ISO 8601 格式带时区信息比如2024-03-01T10:00:00Z避免不同国家用户产生 8 小时时差问题。第二个边界是进度值的合法性。用户最多看到 100不可能出现 120 这样的数字所以后端要校验 progress 只能在 0 到 100 之间超出的直接返回参数错误码。第三个边界是记录 ID 重复。如果客户端网络卡顿用户点了两次提交按钮前后端必须能识别出来这是同一条记录而不是在数据库里插入两条重复数据。处理重复提交的正确方案是幂等性设计。我一般要求客户端每次进入一个新的学习会话时生成一个 UUID 作为idempotency_key整个会话内所有上报都带上这个值。服务端收到请求后先查这个幂等键是否处理过处理过就直接返回成功不重复落库。这个设计能从根上防止学习记录被提交两次导致时长翻倍的问题。3.4 设计评审时的对焦清单接口原型画完之后一定要组织评审。评审不是走个过场而是要把业务规则、字段定义、异常处理全部过一遍。我在评审时有一个习惯就是拿着一份问题清单逐条对确保每个关键决策都被开发确认过而不是默认“大家都应该懂”。评审时我必问的问题包括这个接口路径和命名开发有没有异议必填字段的校验逻辑清不清楚客户端自动重试时的场景标记怎么传如果服务端返回 500前端要不要弹提示学习记录表的唯一索引是按什么字段建的不同业务线之间是否允许字段扩展。这些问题看起来细碎但评审时对焦不清开发实现时就会自由发挥后面联调阶段全是坑。我在一次项目里就吃过亏。当时设计接口时我没有明确让开发确认幂等键的查重逻辑结果开发在实现时只在数据库层面做了一张独立表存幂等键没有和主表做索引关联导致同一用户在弱网环境多次点击提交产生了三条重复记录。后来是用定时任务清洗数据才把记录修正过来那几天加班加得印象深刻。4. 设计过程中踩过的坑问题与排查技巧实录4.1 典型问题速查表学习记录提交接口上线后最常见的问题集中在几个方向。我把这些问题整理成一张速查表每条都对应一个我们在实际项目中真实遇到过的情况可以当作排查手册使用。问题现象可能原因排查思路解决方案学习时长统计翻倍用户退出时重复提交同一条记录检查是否配置了幂等机制设计幂等键服务端按幂等键去重进度回退到 0客户端本地缓存被清理检查上报时机是否过早增加进度本地持久化异常时延迟上报课程显示已学完但实际没看完前端把进度 90% 误判为完成检查 completed 判定逻辑由服务端统一计算完成状态不同时区用户学习时间差 8 小时前后端时间格式不统一检查时间戳是否带时区统一使用 ISO 8601 带时区格式弱网环境下记录丢失网络请求失败且无重试机制检查客户端错误处理逻辑加入本地缓存和自动重试机制这张表里的案例都是真实踩过的坑我每次带新人做学习记录类功能都会直接把这篇文章链接丢给他们。排查问题的效率本质上取决于设计阶段是否考虑了异常场景这条规律在接口设计上尤为明显。4.2 接口幂等性设计产品经理也要懂的技术方案很多产品经理觉得幂等性是后端开发的事跟自己没关系。但实际上幂等性设计直接影响了产品层面的用户体感。如果提交接口不具备幂等性用户在学习过程中反复点击“同步学习进度”按钮就会导致服务端收到多条重复数据最终统计出来的学习时长是实际时长的好几倍。这个功能给到客户那边他们一看时长虚高直接就会质疑产品数据造假影响很坏。所以我在设计学习记录接口时会主动要求接口支持幂等性。具体的实现方式对接产品设计来说只需理解两层逻辑。第一层是客户端每次进入新的学习会话生成唯一标识也就是idempotency_key第二层是服务端收到请求时先查这个唯一标识是否已存在如果存在就直接返回已成功不再插入新数据。这个技术方案不复杂但前端和后端各需要一点代码量产品经理在设计阶段提前讲清楚开发才能后续少走弯路。4.3 工具与协作经验接口文档工具和 Mock 数据在做接口设计时我不建议只用 Axure 画一堆线框图更高效的方式是配合接口文档和 Mock 工具一起使用。现在很多团队用 Apifox、Postman 或者 YApi 来做接口管理和 Mock这些工具可以导入 OpenAPI 格式的接口定义文件自动生成文档页面和 Mock 数据非常方便前后端并行开发。我的经验是接口定义尽量早地落到这些在线工具上不要等开发排期了才开始写。原型阶段的接口字段确定后立刻在工具里建好接口定义好字段和 Mock 规则前端开发就能对照着 Mock 数据直接开发页面了。后端开发也可以基于同一份接口定义去实现服务端代码这样两边接口文档始终一致避免了文档不同步的老大难问题。Mock 数据的设计也有讲究尽量真实一些。比如学习进度字段就用 23.50、67.80 这种带小数的值不要全用 0 和 100返回时间用真实的日期格式错误码的返回也构造几个典型的。这样前端开发过程中能及早暴露数据类型错误而不是等到联调阶段才炸出来。我见过太多因为 Mock 数据太“干净”导致联调时问题井喷的案例了。4.4 设计评审的避坑清单这些细节决定成败最后分享一份我在学习记录接口设计评审时积累的避坑清单。这套清单是从多个项目的评审现场总结出来的每一条背后几乎都有一次加班加点的教训在里面。第一注意字段命名的规范性。不同接口之间的同类字段要统一命名比如用户 ID 不能在 A 接口叫user_id在 B 接口叫uid。第二明确可空字段的默认值。比如network_type如果用户不授权网络权限拿不到默认值是什么要写清楚不然前后端各给各的默认值统计数据就会对不上号。第三删除操作要谨慎。学习记录原则上不做物理删除如果业务上需要移除记录建议用软删除标记保留历史数据方便后续审计。第四接口的扩展性问题。学习记录业务后面大概率会增加新内容类型比如音频、直播回放字段设计时要预留content_type这种枚举字段避免后续加类型导致接口大改。第五服务端返回结构要稳定。返回数据的code、message、data三层结构是所有接口的统一规范不要某个接口特立独行前端又要单独适配一套返回格式。第六所有时间字段都要带时区。这条我已经踩过太多次了每次都要强调。其实做产品原型阶段的接口设计核心并不是让你变成一个技术大牛而是学会用工程思维把业务需求翻译成清晰、可执行、可验证的方案。学习记录提交接口设计一遍下来你自然就会明白所谓“产品感”不是画画线框图就有的而是从这些细得不能再细的字段和逻辑里磨出来的。我在做这个接口设计时反复验证了一个道理接口设计质量最终会通过用户体验和数据准确性体现出来早一点认真对待少很多后来补窟窿的麻烦。