1. 需求分析与交互设计的几个关键决策看到“3.23筛选排序”这个标题你可能觉得这不过是个普通需求给列表页加点筛选条件、排个序能有多复杂但接手这个迭代之后我才发现光是需求梳理和交互决策就够开三次会。实际情况是业务方抱怨“列表没法用”已经很久了——旧版的后台列表只有分页、没有筛选几千条数据堆在一起找一条记录全靠肉眼扫描。这次3.23迭代的核心目标就是把筛选排序做成一件真正好用的事而不是“能用”。一开始我以为是纯前端活把几个下拉框接到接口上前后端联调完就算完事。真做起来才发现筛选排序牵涉到的细节远超想象筛选维度怎么定、排序字段支持哪些、条件叠加时是AND还是OR、筛选状态要不要同步到URL、后端查询走不走索引、分页会不会出现重复数据。每一项背后都有决策每一个决策背后都有理由这篇文章就把整个过程的思路和踩过的坑完整记录下来。1.1 先梳理旧版的问题明确重构方向任何功能重构第一步不是急着写代码而是搞清楚现状到底差在哪。我们先把旧版列表的问题逐条列出来再用这些问题反向推导需求。旧版痛点主要集中在以下几点筛选维度只有简单的关键词搜索业务方想按内容类型、状态、发布时间范围来筛选完全没有入口。排序固定按创建时间倒序想按点击量、浏览量、更新时间排序无法实现。排序和筛选没有任何状态保持每次翻页刷新后条件全部丢失用户操作路径被迫重来。交互反馈缺失点击排序后没有明显的状态提示用户不知道当前到底按什么排的。数据量大的时候页面加载明显卡顿接口没有做分页优化一次拉取全部数据。这些问题列完之后需求方向就清晰了做一个筛选维度丰富、排序字段可选、状态可保持、交互反馈明确的列表模块。与此同时还要考虑现有的数据规模和未来的增长空间接口端必须把筛选和排序下沉到数据库层不能靠前端内存过滤。1.2 筛选维度怎么定优先满足高频场景筛选维度的设计是最容易失控的环节。需求方恨不得把二十几个字段全部做成筛选条件但真正高频使用的往往只有五六个。筛选条件太多交互会变得臃肿查询性能也会跟着下降。我们的处理方法是先拿后台最近三个月的用户操作日志统计列表页用户关注度最高的字段再结合业务方的核心诉求来确定维度。最终确定的筛选维度分成了几类维度类型设计理由内容类型枚举单选用户最常按类型来找内容单选即可覆盖发布状态枚举单选区分草稿、待审核、已发布、已下架来源渠道枚举多选用户需要同时筛选多个来源进行对比发布时间范围日期区间按时间区间过滤是后台高频操作标签关键词文本模糊匹配支持按标题或标签关键词快速定位这个表看似普通但每一行背后都有取舍。比如来源渠道用多选是因为业务方需要同时对比几个渠道的数据差异发布时间范围用区间而非单独的起止时间是为了更贴近“看某个时间段内容”的真实场景。筛选维度不是越多越好也不是越少越好而是要在“够用”和“不冗余”之间找平衡。1.3 交互形态的选型抽屉还是下拉筛选条件的交互呈现方式也是需要决策的点。常见方案有两种一种是全部平铺在列表页顶上简单直接但占用页面高度条件一多就显得乱另一种是收进抽屉里点击“筛选”按钮后从右侧滑出页面清爽但多了一步操作。我们最终选了抽屉式。原因有三点第一筛选维度有五项如果全部平铺页面上半屏全是筛选条件表格的展示空间被严重压缩第二筛选操作本身是低频动作用户大多数时候是在浏览列表不需要让筛选工具长期占用视线第三抽屉式可以承载更复杂的条件组合和更清晰的布局后续如果新增筛选维度扩展成本也更低。但抽屉式有一个必须注意的坑筛选条件入口变深之后用户可能会忽略筛选功能的存在。我们通过两个细节来弥补——一是在列表页标题栏常驻显示当前的筛选条件总数比如“已选 2 项筛选”二是在表格上方保留当前筛选条件的标签形式回显并且每个标签都带关闭按钮让用户对“当前列表是怎么被过滤的”一目了然。1.4 排序字段的选择与默认排序逻辑排序字段的选择同样不能拍脑袋。我们把列表里所有可见字段枚举了一遍再结合业务使用方式来确定排序白名单。最终支持排序的字段包括发布时间、更新时间、点击量、收藏量。这几个字段基本覆盖了用户的核心诉求找新内容看发布时间找改动过的内容看更新时间衡量内容受欢迎程度看点击量和收藏量。排序方向统一采用“优先降序”的约定时间类字段默认倒序排列因为新数据最相关量级类字段默认也降序因为要看的是最高值。这里要注意一个容易被忽略的点排序方向需要和业务语义自然匹配。比如点击量排序用户默认期望是点击量最高排在前面所以默认降序是符合直觉的如果我们默认升序用户大概率会觉得功能是坏的。排序还有一个关键的默认规则当用户没有主动选择任何排序字段时列表必须有一个合理的默认排序。我们默认按发布时间倒序排列同时为了保证分页稳定还加了一个隐藏的次要排序条件主键倒序这样即使同一时间发布了多条内容分页也不会出现顺序错乱的情况。这个细节在后面问题排查部分还会展开讲。2. 前端实现与交互细节落地的完整过程需求定清楚之后进入前端开发阶段。这个阶段的教训是筛选排序的前端工作量不在于写几个组件而在于状态管理、请求时序和交互细节的把控。我把这个过程拆成了四个部分来讲状态管理设计、防抖与请求竞态处理、URL状态同步、异常兜底。2.1 用一个统一的查询对象管理筛选状态前端最容易犯的错误是每个筛选组件各自维护自己的状态比如下拉框用自己的局部变量、日期选择器又是一套状态。这样带来的问题是当用户点击“筛选”按钮时需要把所有组件的数据重新收集一遍再组装成请求参数逻辑分散且容易漏字段。我们的做法是在页面顶层维护一个统一的查询对象 query结构大致如下const query { pageNo: 1, pageSize: 20, contentType: , status: , channels: [], publishStart: , publishEnd: , keyword: , sortField: publishTime, sortOrder: desc };所有筛选组件的值变更时不直接修改自身状态而是调用统一的更新方法去更新这个 query 对象再触发数据请求。这样整个页面的“当前筛选条件是什么”“当前排序是什么”“当前在第几页”都集中在一个对象里逻辑清晰排查问题也方便。更新方法的核心思想是纯函数更新每次变更都返回一个新的 query 对象而不是在原对象上做修改。这样有几个好处方便做状态回退、方便写测试、也方便后续加上“撤销操作”这类增强功能。比如把 query 对象每次变更前的快照推到历史栈用户点击浏览器前进后退时也能恢复对应的筛选状态这个能力在这个版本里没做但为后续扩展留下了空间。2.2 处理请求竞态防抖、请求序号与加载态筛选排序场景中请求竞态问题是特别容易被忽视又特别致命的坑。用户快速点击筛选、切换排序、翻页时前端连续发出去多个请求。由于网络环境不稳定后发出去的请求可能先返回先发出去的请求反而后返回最后渲染到页面的数据其实不是用户想要的那份。解决思路有三个层面。第一是防抖筛选条件变更时不立即发起请求而是等待 300ms 确认用户停止操作后再请求。比如用户拖动日期范围、连续切换筛选条件时防抖可以防止大量无效请求打爆后端。第二是请求序号机制维护一个自增的请求序号每次发起新请求时记录序号响应返回时只有当序号是最新的才渲染否则直接丢弃。这个机制能在更大程度上保证最终展示的数据是最近一次操作的结果。第三是 loading 状态的合理控制请求进行中给表格区域加蒙层或加载动画防止用户看到旧数据误以为操作已生效。但要注意不建议每次筛选都清空整个表格再显示加载态那样会造成页面闪烁体验反而更差。我们用的是半透明蒙层叠加在原表格上加载完成后替换数据视觉上更平滑。2.3 筛选条件同步到 URL刷新不掉状态这个需求来自一个使用场景用户费了半天劲设置好筛选条件不小心按了浏览器刷新结果所有条件全部重置之前的筛选白搭了。如果筛选条件是低频操作用户还能接受但在我们的场景里运营人员每天会反复使用相同的筛选组合状态丢失每次都是在浪费工作时间。因此我们实现了筛选条件与 URL 参数的同步。思路是query 对象里的非空字段全部序列化到 URL 查询参数中每次 query 变更后更新浏览器地址栏页面初始化时从 URL 参数解析出初始 query再发起数据请求。伪代码大致长这样// 将 query 同步到 URL function syncQueryToURL(query) { const params new URLSearchParams(); if (query.contentType) params.set(contentType, query.contentType); if (query.status) params.set(status, query.status); if (query.channels.length) params.set(channels, query.channels.join(,)); if (query.publishStart) params.set(publishStart, query.publishStart); if (query.publishEnd) params.set(publishEnd, query.publishEnd); if (query.sortField ! publishTime) params.set(sortField, query.sortField); if (query.sortOrder ! desc) params.set(sortOrder, query.sortOrder); window.history.pushState({}, , ${location.pathname}?${params.toString()}); } // 从 URL 解析出初始 query function parseQueryFromURL() { const params new URLSearchParams(location.search); return { pageNo: 1, pageSize: 20, contentType: params.get(contentType) || , status: params.get(status) || , channels: params.get(channels) ? params.get(channels).split(,) : [], publishStart: params.get(publishStart) || , publishEnd: params.get(publishEnd) || , sortField: params.get(sortField) || publishTime, sortOrder: params.get(sortOrder) || desc }; }实现时要注意默认值的字段不写入 URL这样 URL 不会无意义地膨胀也保持了地址的整洁。同步 URL 使用 pushState 而不是直接跳转避免触发无谓的页面路由刷新。这一步做完之后用户刷新页面、复制链接分享给同事筛选状态都能完整保留这个体验升级带来的正向反馈非常明显。2.4 异常兜底与空状态的细节处理筛选排序还有一类细节容易被忽略但直接影响观感——那就是异常和空状态。筛选条件组合出来的结果为零页面不能白花花一片什么都没有必须给用户一个明确的解释。我们的空状态设计是显示“没有符合条件的内容”同时提供两个可选操作一个是“清空筛选条件”一个是“调整筛选条件后重试”。后者的效果目前来看比较好因为用户可以直接从当前状态出发继续操作。接口异常的情况同样需要处理。常见的错误类型有后端超时、参数校验不通过、接口 500 等。我们统一在请求层做了错误拦截当接口返回错误时不直接清空列表数据而是保留原来的数据同时在页面顶部弹出错误提示条告知用户“数据加载失败请稍后重试”。这样做的原因是筛选条件本身是正确的只是暂时请求失败了保留原列表数据可以让用户在等待期间仍然能回看已有内容不至于眼前一空。3. 后端接口设计与数据层查询优化筛选排序这个功能前端做得再顺滑如果后端接口设计不合理性能和可扩展性都会出问题。这个章节重点讲接口参数定义、动态查询构造和索引设计三个部分每一个都来自实际开发中被坑过之后的复盘。3.1 接口参数定义字段清晰扩展友好后端接口的请求参数应该尽量和前端 query 对象保持结构一致避免后端做额外的字段映射。我们最终的接口请求参数定义如下{ pageNo: 1, pageSize: 20, contentType: article, status: published, channels: [channel_a, channel_b], publishStart: 2025-01-01 00:00:00, publishEnd: 2025-03-23 23:59:59, keyword: 技术, sortField: publishTime, sortOrder: desc }这里有几个设计要点。第一所有参数统一使用小驼峰命名前后端共用同一套字段名减少联调时字段不一致导致的低级问题。第二channels 使用数组传值后端直接接收数组避免前端把多个值拼接成逗号字符串后再由后端拆分。第三分页参数集中放在列表查询接口里而不是单独拆一个分页接口降低整体复杂度。排序参数的安全性要格外重视。我们不会直接把 sortField 拼进 SQL 排序子句而是维护一个排序字段白名单后端只对白名单内的字段进行排序映射。这个设计能有效避免无法预料的排序行为也能防止用户传入异常字段导致数据库报错。3.2 动态查询构造条件拼接与防注入后端拿到筛选参数后需要动态构造查询语句。我们使用的是 MyBatis通过if标签动态拼 SQL。核心逻辑是每个筛选条件单独判断是否传值有值才拼到 WHERE 子句里。select idqueryContentList resultTypeContent SELECT * FROM content WHERE deleted 0 if testquery.contentType ! null and query.contentType ! AND content_type #{query.contentType} /if if testquery.status ! null and query.status ! AND status #{query.status} /if if testquery.channels ! null and query.channels.size() 0 AND channel IN foreach collectionquery.channels itemchannel open( separator, close) #{channel} /foreach /if if testquery.keyword ! null and query.keyword ! AND (title LIKE CONCAT(%, #{query.keyword}, %) OR tag LIKE CONCAT(%, #{query.keyword}, %)) /if ORDER BY choose when testquery.sortField publishTimepublish_time/when when testquery.sortField updateTimeupdate_time/when when testquery.sortField clickCountclick_count/when when testquery.sortField collectCountcollect_count/when otherwisepublish_time/otherwise /choose choose when testquery.sortOrder ascASC/when otherwiseDESC/otherwise /choose , id DESC /select这里坚持使用参数绑定#{}的方式传值而不是${}字符串拼接。参数绑定会让数据库引擎把传入值当作参数处理从源头避免了SQL注入风险。排序字段用choose/when做白名单映射而不是直接拼接用户传入的字段名这也是后端排序安全的关键一步。最后在排序条件末尾固定追加, id DESC这个技巧是为了保证排序的唯一性确保分页稳定后面会专门讲。3.3 索引设计等值条件优先排序字段要谨慎筛选排序功能上线前我们对查询进行了 explain 分析发现不加索引的情况下全表扫描的耗时在数据量达到十万行之后会明显恶化。索引设计遵循了几个原则等值筛选条件的字段优先建索引范围查询字段放在联合索引的靠后位置排序字段参与索引时要格外谨慎。我们的最终索引设计是这样的ALTER TABLE content ADD INDEX idx_type_status (content_type, status), ADD INDEX idx_publish_time (publish_time), ADD INDEX idx_update_time (update_time), ADD INDEX idx_channel (channel);设计逻辑如下content_type 和 status 是等值筛选属于高频查询条件放在同一个联合索引里查询时可以先通过这两个字段快速缩小范围。publish_time 和 update_time 分别是排序字段单独建索引即可需要说明的是如果某个排序字段同时是高频筛选范围条件比如时间范围查询可以考虑把排序字段放在范围查询字段后面作为联合索引的末尾。但我们的核心场景是时间范围查询与排序的叠加时间字段在 WHERE 和 ORDER BY 中同时出现时单独的索引在某些情况下并不能完全优化排序更依赖的是数据库提前排序后 limit 的数据量大小。对于大批量数据必要条件是通过索引或分区先过滤到较小范围再排序效果会好很多。另外channel 字段虽然也是筛选条件但它的区分度cardinality不高取值范围有限。这种低区分度字段单独建索引效果通常不好甚至可能让查询优化器放弃索引。考虑到渠道通常与其他条件组合使用我们没有为它单独建独立的索引而是留在后续需要时再组合设计避免过度索引给写入带来额外成本。3.4 稳定排序与分页一致性的底层逻辑分页排序容易出现两个看似无关但体验极差的问题翻页时数据重复或者漏掉数据。根因是排序条件不唯一。比如按发布时间倒序排列时如果同一秒内有十条内容发布了这十条记录之间没有明确的先后顺序数据库在不同查询请求之间可能返回不同顺序用户翻页时就会看到同一行重复出现或某些行被跳过。解决方案就是排序条件的唯一化。做法是在用户选择的排序字段后面追加一个全局唯一的字段作为辅助排序比如主键倒序。上面 SQL 中的, id DESC就是干这个用的。这样组合排序后任何两条数据之间的顺序都是确定且唯一分页结果自然就稳定了。这里有一个细节值得强调辅助排序字段的顺序要放在最后。如果用户选择的排序字段值相同主键排序才开始起作用如果用户选择的排序字段本身已经能区分所有记录主键排序不会干扰原有顺序。这个规则在任何排序场景下都适用是稳定分页的通用做法。4. 常见问题与排查技巧实录功能上线之后我们陆续遇到了几个线上问题每一个都不算难但排查过程和学习到的经验很有价值。我把这些问题整理成一个速查表希望对碰到类似情况的人有帮助。问题现象可能原因排查思路解决方法列表排序顺序看起来是乱序排序字段有 NULL 或脏数据检查数据中该字段是否大量为空对 NULL 值指定排序策略如排到最后翻页时出现重复或漏数据排序条件不唯一查看 SQL 排序子句是否只有用户选的字段追加主键作为辅助排序组合筛选后查询变慢索引未命中或筛选维度无索引支撑执行 explain 查看查询执行计划按筛选条件重新设计联合索引日期筛选不生效前后端日期格式不一致对比请求参数中日期格式与接口定义统一为 yyyy-MM-dd HH:mm:ss某个筛选维度选了没效果后端接口漏掉该参数的查询条件查看后端日志确认参数是否到达补全动态 SQL 中的条件拼接排序切换后表格短暂无数据请求竞态或加载态处理不当检查请求序号机制是否生效增加请求序号校验4.1 排序字段的 NULL 值导致列表顺序错乱上线后第一个线上问题就是排序顺序不对。业务方反馈“按更新时间排序列表忽前忽后感觉完全没有顺序”。排查下来发现很多老数据的 update_time 字段为 NULL数据库在排序时默认把 NULL 值放在最前面数据库不同行为不同导致大量无更新时间的数据长期占据列表顶部真正更新过的内容沉在最下面。解决措施有两个层面。数据层面我们做了一次历史数据的批量更新把 NULL 的 update_time 都回填为记录创建时间保证该字段不为空。查询层面在排序规则里显式指定 NULL 值策略比如把 NULL 值排到最后ORDER BY update_time IS NULL, update_time DESC, id DESC这个写法首先按“是否为 NULL”排序非 NULL 的排前面再按时间倒序排列。这个调整之后排序结果符合业务直觉问题解决。类似的处理思路也适用于其他可空字段排序的场景核心原则是提前想清楚 NULL 值应该落在排序结果的什么位置。4.2 多条件组合后索引失效的排查上线一段时间后运营反馈某类组合查询“特别慢”页面基本卡死。我第一时间用 explain 查了执行计划发现一个典型问题筛选条件包含 channel 字段按渠道筛选时数据库选择了全表扫描而不是走索引。原因在于 channel 字段的区分度太低查询优化器认为通过索引回表的成本比直接扫描还高因此主动放弃了索引。解决思路是调整索引策略。我们最终在联合索引里加入了 content_type 与 channel 的组合让高频的组合筛选能借助联合索引快速定位。另外一个思路是强制指定索引但这种方法不够优雅而且一旦数据分布变化强制索引可能适得其反。更合理的做法是在索引命中情况不理想时考虑通过给数据表加冗余字段来提高区分度或者对筛选字段进行归一化处理。4.3 前端传参格式不一致导致的筛选失效开发联调阶段前后端关于渠道多选参数的传法产生了分歧。前端按习惯把多个渠道拼成了字符串 channel_a,channel_b 传给后端后端接收时按逗号拆分但有一个特殊渠道名称里恰好包含逗号导致拆分后渠道数量变多筛选结果错误。这个问题属于典型的参数格式不一致。我们的处理办法是统一多值参数的传法前端直接传数组后端接收数组类型彻底避免字符串拆分带来的边界问题。如果使用场景要求必须传字符串那就需要约定一个安全的分隔符并且在数据层面限制用户输入的字符范围。我的经验是能用数组就尽量用数组字符串拼接多值参数是个隐雷早晚会踩。4.4 特殊字符对查询结果的影响关键词筛选遇到特殊字符也会出问题。用户输入搜索关键词带百分号%时由于我们用的是 LIKE 模糊匹配百分号本身在 SQL 中表示通配符直接拼接会导致查询结果异常。比如用户搜“100%纯棉”匹配到的结果可能远超预期。解决办法是在动态 SQL 中对关键词里的特殊字符% 和 _进行转义或者在查询前把它们替换掉。最简单可靠的方式是使用数据库提供的转义函数或者用代码层先做字符替换const safeKeyword keyword.replace(/[%_]/g, \\$);处理过后LIKE 查询中的特殊字符被当作普通字符匹配搜索结果符合预期。这类问题在关键词搜索场景里非常普遍测试用例里一定要覆盖特殊字符输入。5. 上线前的测试要点与回归建议筛选排序功能的测试范围比想象中大很多。我们最初以为把功能测试用例写全了就行结果上线前补了两轮回归才把边界情况覆盖完整。这里分享一套比较实用的测试思路不只是这个项目、任何带筛选排序的模块都可以参考。5.1 测试用例设计的核心维度单个筛选条件的基础验证每个筛选维度单独使用时结果是否正确。比如只选内容类型、只选状态、只填关键词逐项验证。多条件组合验证两个或三个条件组合查询重点是验证组合逻辑是 AND 而不是 OR。最容易出错的场景是同时选择来源渠道和关键词两个条件必须同时满足。排序与筛选组合验证在筛选条件下切换排序字段确认排序只在筛选后的结果集内生效。分页边界验证翻到最后一页、每页最后一条数据、快速连续翻页、筛选条件改变后重新从第一页加载。空值与脏数据验证造几条关键字段为 NULL 或异常值的数据确认列表不会崩溃、排序不会乱。空结果集验证组合条件查无数据时页面展示是否友好是否提供合理的回退操作。这些用例看起来琐碎但每一个都有真实翻车案例。我们曾经在一个测试环境下没有覆盖空值数据上线后被 NULL 字段坑了一回也曾经因为没测快速切换排序漏掉了请求竞态导致显示错乱的问题。5.2 与线上真实数据对齐进行验证新功能要验证效果最直接的方式是拿线上真实数据来做对比。我们把功能测试环境的数据同步为生产数据的脱敏副本然后用同一组筛选条件分别在旧接口和新接口上查询逐条对比结果集。这个方法帮助我们发现了一个潜在的数据差异多个字段的值存在前后端格式不一致的情况两端解析同一数据结果不同。具体对比方法很简单把筛选条件固定成几组核心场景在测试环境里调用新旧两个接口导出结果集对比行数和内容。行数一致不代表内容完全一致还要抽样核对字段值。这个方法虽然原始但效果最好能发现很多未被注意到的数据质量问题。5.3 上线后的灰度策略与监控上线节奏同样需要控制。我们没有直接全量切换而是先让部分用户先行体验新版本的筛选排序功能观察一段时间确认稳定后再放开全量。灰度期间重点监控三个指标接口响应时间、错误率、慢查询数量。如果一个查询的响应时间超过几百毫秒就要怀疑索引是否命中或查询是否需要继续优化。慢查询日志是监控重点任何新增排序字段都可能引发新的慢查询。有一次灰度期间我们发现某类渠道筛选的查询变慢定位到是索引选择问题紧急优化后才继续扩大放量。没有灰度策略直接全量切换这种问题就会直接影响所有用户的使用体验所以上线前的计划和灰度步骤很重要不是流程繁琐而是在保护功能质量。最后分享一点实际经验筛选排序这个功能第一眼看上去不起眼做起来才知道它贯穿了需求梳理、交互设计、前端状态管理、后端查询优化、索引设计、异常处理、上线验证的完整链路。做完这次迭代我最大的体会是越是基础的功能越考验对细节的把控能力。一个排序字段的 NULL 值策略、一个前端请求竞态、一个后端排序白名单任何一环没想清楚最终都会以线上问题的方式爆发出来。如果你想在其他项目里复用这套方案不需要照搬我们的代码结构但下面这几个原则是完全通用的筛选维度按真实使用频率来定不要贪多前端用一个查询对象统一管理状态防止状态散落后端排序字段永远走白名单映射分页排序必须追加主键保证唯一性筛选条件同步到 URL刷新不丢状态。按照这些原则来做即使系统语言和框架不同也能做出稳定好用的筛选排序功能。最后再分享一个小技巧功能开发完成后建议用生产环境数据脱敏的副本跑一遍从头到尾的操作流程从第一页翻到最后一页切换所有筛选条件组合这个过程能帮你发现一堆哪怕测试用例都覆盖不到的真问题。花两小时做一次真实环境验证抵得上写两百条测试用例。