1. 需求拆解“我的学习计划”到底要返回什么在做某学习平台的接口开发时我接到过一个“查询我的学习计划”的分页列表需求。当时第一反应觉得这活很轻一张计划表一个用户ID过滤一个 limit完事。但真正走到联调和上线后才发现这个“简单的”列表接口最容易踩的坑几乎全在需求定义不够清晰的地方。1.1 一个计划列表接口背后的表结构学习计划这类业务在设计上通常不是一张表而是拆成“计划主表”和“计划明细表”。主表保存用户学习计划的基本信息计划名称、开始日期、结束日期、计划状态、创建时间。明细表保存该计划内的细分任务比如某一天要学习哪个知识点、哪个章节、完成任务的状态等。列表接口返回的是主表信息叠加少量统计字段比如任务总数、已完成数、完成率让前端在列表页直接展示进度条。两个关键字段——任务总数和已完成任务数我强烈建议直接冗余在主表里而不是在查询时去明细表里实时 count。为什么呢列表接口一次要返回一页比如20条计划记录如果每一条都去明细表聚合统计就是20次子查询数据量稍涨响应时间就会变得非常难看。真实业务里明细数据的变更频率远高于列表展示频率完全可以在更新明细的同一个事务里把主表冗余字段同步维护好。查询侧变轻了写入侧多花一点点成本这是列表接口性能设计里最划算的一笔账。主表字段大概长这样plan_id、user_id、plan_name、start_date、end_date、status、task_total、task_done、create_time。状态字段用 tinyint0 表示未开始1 表示进行中2 表示已完成。很多人喜欢用字符串状态查询写起来直观但存储成本和索引效率都不如整型后端维护一份枚举映射就够了。1.2 列表接口和详情接口的边界划分“查询我的学习计划”从产品形态上是一个列表页卡片流用户能看到自己名下所有计划的简要信息点进某一个计划后才会触达“计划详情”接口查看每天的任务明细。这两个接口的边界应当非常清晰但新同学经常犯的毛病是在列表接口里把明细也一股脑带出来。我见过一个接口列表查询结果里嵌套了该计划全部任务明细一条计划对应几十条明细一页数据返回几千行 JSON前端列表页其实只用了计划名称、日期和进度明细完全没用上白白拖慢了首屏。这是典型的“接口职责不清”。所以我在拆需求时一般会问自己三个问题这个页面真正需要展示的最小字段集合是什么哪些字段是点击之后才需要的统计数据能不能通过主表冗余字段提前准备好这三个问题想明白SQL 基本上就定了。接口路径设计上建议用资源视角比如GET /api/v1/study-plans/mine分页参数放在 query string 里路径里不写死页码。前端如果要加“只看进行中”的筛选就传一个可选的 status 参数默认不传返回全部状态。对查询接口要始终保持只读语义不要在 GET 请求里做任何写入操作也别让查询接口依赖请求体传参。2. 分页参数设计契约先行别让前后端反复改分页参数是接口联调里最容易被来回扯皮的部分。前端和后端各自有各自的使用习惯文档里不写清楚联调时就要一句一句地试错。我建议在开发之前就把它作为接口契约的一部分明确下来。2.1 pageNum/pageSize 还是 offset/limit主流的参数风格有两种一种是面向页面展示的pageNum页码从 1 开始加pageSize每页条数另一种是更贴近数据流习惯的offset起始偏移量加limit返回条数。大多数前端表格组件默认用的是前一种例如组件库里常见的 current-page 和 page-size 概念跟 pageNum、pageSize 天然对应。如果是普通业务系统我推荐直接采用 pageNum/pageSize前端组件拿到的值可以直接传省去一次转换沟通成本最低。但如果是开放平台 API面向第三方开发者offset/limit 的表达更接近数据库习惯语义直白文档也好写。两种方法没有本质优劣关键是要统一。我更想强调的是“页码从 0 开始还是从 1 开始”这个细节它才是分页 bug 的第一大来源。我自己就吃过亏后端按 pageNum 从 1 开始写前端以为从 0 开始第一页传 0后端算出 offset 是负数最后做了容错才没翻车更常见的情况是前端传页码 2后端按从 0 开始的逻辑处理成第二页数据前端页面上看到的却是第三页内容。页码偏移的偏差特别隐蔽因为首屏第一页数据大多是对的一到翻页就错位。下面是我常用的两种风格对比风格参数示例首屏请求适用场景注意点pageNum/pageSizepageNum1pageSize10页码传 1前端表格组件约定页码从 1 开始计算 offset 时减 1offset/limitoffset0limit10偏移量传 0开放 API、数据流约定 offset 从 0 开始语义与数据库一致2.2 偏移量计算与合法值校验如果采用 pageNum 从 1 开始的约定后端拿到参数后统一换算成数据库的 limit 语法offset (pageNum - 1) * pageSize。这个计算本身很简单真正容易出问题的是边界值处理。我建议对分页参数做一层防御性处理pageNum 小于 1 时按 1 处理而不是直接抛参数错误pageSize 小于 1 时按默认值 10 处理pageSize 超过上限时按上限 50 或 100 处理pageNum 超过总页数时返回一个空 list 但 total 保留真实值。这套策略在接口文档里写清楚前端调用方即使传了奇怪的边界值也不会出现 400 报错或者页面白屏。页大小必须设上限这个很多人会忽略。不限制 pageSize 的接口前端一个误操作就传 pageSize10000数据库一次性要返回上万行网络传输和前端渲染都会被拖垮甚至可能直接把服务端连接池打满。即便接口是内部使用也要做好兜底。还有一点响应体里要把实际生效的 pageNum 和 pageSize 回传。比如前端传了 pageSize500后端按上限 100 截断如果响应里不回传真实值前端就会按 500 去计算总页数导致分页组件计算出一堆空白页。这个回传动作是联调阶段最省心的做法。2.3 排序稳定性翻页不重不漏的关键分页列表最隐蔽的一个坑是“翻页重复”和“翻页丢数据”。表现很迷惑第一页数据正常第二页里有几条是第一页见过的另几条从头到尾都没出现过。很多人会怀疑是 SQL 写重了或者前端渲染有缓存但真正的根源常常出在排序上。单字段排序order by start_date desc看起来没问题但如果同一天创建的计划很多start_date 相同数据库返回顺序就不稳定了。执行两次相同的查询可能返回顺序不同MySQL 在没有明确次序要求时最终顺序会受执行计划、数据分布影响。这就导致第一页末尾的记录在用户翻到第二页时又出现在第二页开头形成重复或遗漏。解决办法是加第二排序字段用主键 id 打破平局order by start_date desc, id desc。id 绝对唯一整个排序就完全确定了。这个细节值得优先写进开发规范因为它直接影响分页接口正确性还决定后面能不能顺利做游标翻页。3. SQL实现与性能基线count查询和列表查询的关系列表接口的每一次请求数据库层面通常要做两件事查当前页的数据查满足条件的总条数。两者缺一不可前者负责页面内容后者负责分页组件能显示多少页。3.1 两条SQL的业务正确性常规实现用两条 SQL一条查列表一条查总数select id, plan_name, start_date, end_date, status, task_total, task_done from study_plan where user_id ? order by start_date desc, id desc limit #{offset}, #{pageSize};select count(*) from study_plan where user_id ?;看起来简单但这两条 SQL 的过滤条件必须完全一致。前端如果传了status1列表 SQL 要加 status 条件count SQL 也必须同步加前端如果按日期范围筛选两边都要带相同范围条件。我曾经在联调时遇到 total 和列表对不上的问题排查了半个多小时最后发现就是 count 语句漏加了一个状态过滤导致总数一直偏大前端分页组件计算出来的空白页比实际多出好几页。总数计算的 SQL 写法也有讲究。统一用count(*)不要用count(id)更不要用count(某个可空字段)。count(字段)会忽略该字段为 NULL 的行一旦字段可空统计结果就和真实行数对不上了。count(*)和count(1)在 MySQL 里性能差别微乎其微选一个顺手的标准写法并坚持即可。3.2 索引设计一次explain搞定慢查询学习计划表的核心查询模式是“按用户查计划并按时间排序”所以最有价值的索引不是单列 user_id而是复合索引alter table study_plan add index idx_user_start (user_id, start_date, id);如果业务上高频按状态过滤可以再评估是否需要(user_id, status, start_date, id)的复合索引但不要在每个查询场景上都单独建索引索引不是越多越好写入成本和存储成本都在那里。用 explain 验证时重点看四列type 至少要达到 ref说明索引等值匹配生效key 显示的是实际使用的索引如果显示 NULL 就是没用上索引rows 越小越好Extra 里千万不要出现Using filesort一旦出现说明排序没有走索引数据量大时排序会导致明显的性能劣化。复合索引的列顺序有个常用原则等值条件的列放前面排序条件的列放后面。user_id 是等值匹配放在最左start_date 用于排序放在其后id 作为唯一性收尾。数据库可以沿着索引顺序读取数据既过滤了用户又拿到了正确排序省掉了一次内存排序。3.3 深翻页问题的三种解法limit offset, pageSize的写法在 offset 很小的时候没有问题但 offset 越大越糟糕。比如limit 90000, 10MySQL 要先把前 90010 行都读出来然后丢弃前 90000 行只返回最后 10 行。这是一种越翻越慢的线性退化百万级数据下深翻页可以把几十毫秒的查询拖到几秒钟。三种常用解法如下方案核心思路优点适用场景限制翻页深度只允许访问前 N 页超出返回提示实现成本为零保护数据库最简单用户只关心最近数据的业务延迟关联先查主键 ID再回表取完整行减少回表开销offset 消耗集中在索引offset 较大但仍需 pageNum 翻页游标翻页用上一页最后一条记录的排序键继续向后取响应速度稳定不受翻页深度影响无限滚动、加载更多交互延迟关联的 SQL 写法大概是select t.id, t.plan_name, t.start_date, t.end_date, t.status from study_plan t inner join ( select id from study_plan where user_id ? order by start_date desc, id desc limit #{offset}, #{pageSize} ) tmp on t.id tmp.id order by t.start_date desc, t.id desc;游标方案的查询条件大致是where user_id ? and (start_date, id) (?, ?) order by start_date desc, id desc limit #{pageSize};业务上如果将来要做“加载更多”的无限滚动游标方案是更契合的。学习计划这类数据特点就是用户只关心最近的一批计划很少有人真的翻到几百页之后。与其絞尽脑汁优化深翻页不如直接限定最大可翻页数把不合理的访问挡在 SQL 之外。4. 出参规范与联调细节total、空列表、时间格式数据库查询完成接口返回值也不是随手拼出来的。分页接口的出参设计直接影响前端分页组件能不能正常工作也决定了联调阶段要反复沟通多少次。4.1 统一响应体与分页元数据的命名我习惯使用的统一响应结构大致是这样{ code: 0, message: success, data: { list: [], total: 102, pageNum: 1, pageSize: 10 } }data 内部list 是当前页记录数组total 是满足过滤条件的总条数pageNum 和 pageSize 回传本次请求实际生效的分页参数。这里最关键的是全项目统一字段命名不要这个列表接口叫 list另一个接口叫 records另一个叫 rowstotal 也别一会 totalCount 一会 total。命名不一致带来的问题是前端每接一个接口就要写一套解析逻辑稍不注意就拿到 undefined。我建议在项目里定一个简单的分页出参规范分页接口一律返回 list total pageNum pageSize前端可以把解析逻辑抽成公共函数所有列表页复用。一次规范化能省掉后面无数次沟通。4.2 空数据与null的区别列表接口没有任何数据时最容易出现两个问题list 返回 nulltotal 返回 null。前端拿 null 去遍历列表会直接报错分页组件拿到 null 的总数可能把分页条整个隐藏用户看到的就是一个空白页面且没有更多操作入口。所以空数据的语义要定死list 永远返回数组没有数据返回[]total 永远返回数字没有数据返回0。前端不需要为空值单独做防御。这种做法虽然在后端看起来多写了两行判断但对前端调用方来说是极大的信任基础。时间格式是另一个高频雷区。Java 后端使用 LocalDateTime 时默认序列化出来的格式可能带T比如2025-01-01T10:00:00前端如果不处理页面上会直接出现一个奇怪的 T 字符。我通常会在全局序列化配置里把日期统一格式化为yyyy-MM-dd HH:mm:ss并在文档里写明所有时间字段均为该格式不在个别接口里搞特例。日期时间序列化一旦每接口不同前端就要每个页面单独适配消耗非常大。4.3 联调现场常见的三类“对不上”第一类total 和 list 对不上比如总数明明有 50 条当前页只查到 3 条。最可能的原因就是 count 和 list 的过滤条件不一致排查方法很简单把两条 SQL 复制到数据库客户端里手动执行一遍对比 where 条件。第二类前端拿到的页码和请求页码对不上常见于后端对超界参数做了“截断”或“重定向”但没有在响应里告知实际生效值。比如前端请求第 100 页后端查不到数据返回空 list 而不返回真实把 pageNum 截断后的值前端就以为数据清空了。回传实际生效页码能直接解决这个问题。第三类时间字段解析不一致。同一份数据有的页面显示正常有的页面显示 NaN往往是前端不同页面用了不同的日期解析方式。问题最终还是要回到全局格式统一上把序列化格式和文档对齐这类问题可以从根上消失。把这些约定在项目文档里写清楚联调阶段至少能节省一半的沟通成本。5. 上线前的自查清单权限、缓存与压测接口写完、联调通过并不意味着可以直接上线。分页查询接口在上线前还要过一遍权限、性能和缓存检查这几项经常是问题隐藏最深的地方。5.1 “我的”两个字是安全边界“查询我的学习计划”里的“我的”二字是接口语义里最重要的边界它要求服务端只能返回当前登录用户的数据。实现上用户 ID 必须从服务端登录态上下文取得而不是信任前端传过来的参数。我之前接手过一个历史接口后端直接读请求参数里的 userId 来查学习计划前端页面上有个用户切换功能顺手就把当前选中用户传给了后端。后来安全测试人员把 userId 改成另一个人的值重新请求接口就返回了那个人的学习计划列表这就是典型的水平越权。修复方式不复杂删除 userId 参数统一从登录态上下文取值。但这类问题一旦不检查就会成为一直埋着的漏洞。同样值得检查的还有查询参数的白名单。status 这类筛选字段如果允许任意传值后端至少要做枚举校验不在取值范围内的参数直接按默认处理避免前端把查询条件污染成意料之外的状态值。这个动作虽然放在拦截器里也可以但在接口内部先做一次校验最直接。5.2 数据量增大后怎么做基线压测开发环境里只有几百条计划数据接口怎么测都很快性能问题只有到了接近真实规模的数据量才暴露。我验证性能时的做法是把建表结构和线上数据分布导入测试环境用脚本生成百万级数据再拿并发工具做一次简单的压测观察三个核心指标平均响应时间、P99 响应时间、每秒请求处理数。压测里最容易暴露两类问题。一类是 count 查询慢。count(*) 看起来轻量但如果没有可用索引MySQL 也要全表扫描估算。让 count 命中覆盖索引explain 里 Extra 变成 Using index速度会提升一个量级。另一类是深翻页慢这个在 3.3 节已经给了处理思路。还有一点容易被忽略列表查询接口是只读的不需要开启事务。在查询方法上加Transactional反而会扩大事务边界长事务可能带来锁和快照的额外开销。查询方法不加事务这也是我上线前会检查的一个点。5.3 线上慢查询日志与缓存策略上线之后不要急着关电脑先观察两三天慢查询日志。如果学习计划列表接口频繁出现在慢日志里第一步是用 explain 看执行计划。常见的原因是在查询条件里对索引字段用了函数比如where date(start_date) ?这会导致索引失效改写为范围条件start_date ? and start_date ?就能让索引生效。读多写少的数据适合加缓存学习计划就是典型场景。我常用的策略很朴素把“当前用户的第 N 页列表”整体缓存起来key 用用户 ID 加页码比如study_plan:list:{userId}:{pageNum}。用户创建新计划或更新计划状态时把该用户的列表缓存统一失效。这个方案命中率不算极致但胜在实现简单、失效逻辑清楚。缓存开关要设计成可配置万一线上出现数据不一致可以快速关闭缓存回源数据库而不是紧急发版改代码。我自己做完这个接口之后的体会是分页查询接口“能跑通”和“能上线”完全是两件事难的不是 SQL 本身而是把“我的”这个语义落对把排序做稳定把出参规范定清楚再给数据库留好后路。最后再分享一个小习惯列表接口上线前手动执行一次 explain 并把结果截图留档下次性能出问题时直接对比当时的基线排查速度会快很多。