Flutter ListView分页API搜索异常：仅显示首页且无法加载后续页

一、后端WiController 排查点 #

• 分页参数传递错误：检查搜索接口是否正确接收前端的page（或offset）参数。如果Controller里硬编码了page=1，或者前端滚动时没递增页码，后续请求永远返回第一页数据，前端会一直处于加载状态（因为数据没更新，判断为未加载完成）。
• 搜索条件丢失：确认滚动加载的请求是否携带了搜索关键词。如果只传分页参数、没带搜索词，后端会返回全量数据的分页，40万+数据的分页查询极容易超时，直接导致页面一直加载。
• 响应结构不完整：检查返回的分页数据是否包含total（总匹配条数）、currentPage、dataList这些必要字段。前端如果无法判断是否还有下一页，会一直触发加载请求，停不下来。
• 接口超时：大表无索引的搜索+分页查询（比如limit offset）会极慢，直接导致请求超时。比如select * from wi where name like '%xxx%' limit 10 offset 300000，这种语句会扫描百万级数据，超时后前端一直显示加载中。

二、WiRepository 排查点 #

• 索引缺失：确认搜索字段（比如关键词匹配的字段）是否建立了全文索引或普通索引。没有索引的话，大表模糊查询会直接拉垮性能，请求超时是必然的。
• 分页方式不合理：offset分页在大数据量下性能极差，赶紧换成游标分页——比如基于id或时间戳做范围查询：select * from wi where name like '%xxx%' and id > lastId limit 10，避免offset带来的全表扫描问题。
• 查询条件拼接错误：检查Repository里的搜索条件是否正确，比如有没有漏加like的通配符，或者搜索条件被后续逻辑覆盖，导致分页请求的搜索逻辑失效，返回全量数据引发超时。

三、SearchWi 前端页面排查点 #

• 参数传递不全：滚动触发加载时，必须把搜索关键词+最新的分页参数一起传给后端。很多时候前端只更新了页码，但没带搜索词，直接导致后端返回非搜索结果的分页，甚至数据量过大超时。
• 重复请求未拦截：一定要设置loading状态变量，请求开始时设为true，结束后设为false。如果滚动时多次触发请求，并发请求会阻塞，页面一直显示加载中。
• 下一页判断逻辑错误：前端要根据后端返回的total和currentPage计算是否还有下一页——比如currentPage * pageSize >= total时，就停止触发加载。判断逻辑错了，会一直发无效请求，加载状态永远不结束。
• 超时未处理：给请求设置合理的超时时间，并且捕获超时错误。如果后端请求超时，前端没做处理，会一直卡在加载状态，连错误提示都没有。

四、快速定位问题的步骤 #

1. 用Postman直接调用后端接口，模拟前端请求（比如keyword=xxx&page=2&size=10），看能不能正常返回数据、响应时间多久。如果接口超时或返回错误，问题肯定在后端。
2. 查后端日志，看生成的SQL语句是否正确、执行时间多长。如果SQL执行超过3秒，基本就是数据库查询性能问题，优先优化索引或分页方式。
3. 开浏览器控制台，看滚动加载的请求参数和响应结果。如果请求里没带搜索词、或者页码一直是1，就是前端参数传错了；如果响应是504超时，就是后端性能问题。

内容的提问来源于stack exchange，提问作者Keroppiiiii