列表接口查不到数据返回空数组，详情接口返回 null，前端空状态为什么还老白屏？

结论先说：列表接口查不到数据，返回空数组 [] 并把 total 同步为 0；按 ID 查详情查不到，返回 null 或明确错误码，不要返回空对象；字段没填用 null 表示未知，错误场景走错误码。按 2026 年常见交付习惯，空值形态一旦固定，就不宜在同一个接口里有时 null、有时 []。前端判空封装和接口文档示例要一起做，白屏和联调返工通常来自空值漂移，而不是前端水平。

为什么列表返回 []、详情返回 null，前端还会判错？

前端判空一般先看有没有数据，再决定渲染空状态还是列表。问题常出在同一个字段有时 null 有时 []：写 data.length 会在 null 上出错，写 if(data) 又会把 [] 当真值，空列表可能一直显示加载中。多端消费时，App、小程序、Web 的兜底写法不同，后端形态不统一，各端就容易各自补逻辑。

从交付经验看，字段在 10~30 个以内时，口头约定还能撑一阵；调用方超过两个端、接口进入长期维护后，空值漂移带来的返工明显增加。经验区间是：每轮联调因判空产生 0~2 次修改较常见，提前把空值语义写进契约，通常能压到 0~1 次。

先分清四种空：列表空、对象空、字段空、错误空

空值讨论容易混，是把“列表没数据”“对象不存在”“字段没填”“请求失败”都叫空。它们的语义不同，返回形态也不该混用。

1. 列表空：集合查询无结果，返回 []，total 为 0，消费方按长度渲染空状态。
2. 对象空：按 ID 查详情查不到，返回 null 或明确错误码，不建议返回空对象。
3. 字段空：字段没有值，用 null 表示未知或未填；除非业务上等价，不要用空字符串冒充。
4. 错误空：超时、无权限、参数错，走错误码与提示，不要返回空数组让前端以为查完了。

这样划分的原因是消费动作不同：列表空渲染空状态，对象空跳 404 或提示不存在，字段空显示占位符，错误空要重试或提示。混在一起，前端只能猜。

列表、详情、更新接口分别怎么约定

同样是没数据，不同接口的关注点不同。列表接口重点是分页组件稳定；详情接口重点是区分查不到和服务异常；更新接口重点是避免把“没传”误判成“清空”。2026 年较常见的做法是按接口语义分别约定，而不是全局一个配置改到底。

• 列表接口：list 返回 []，total 返回 0，当前页无数据是正常业务结果，HTTP 状态仍可用 200。
• 详情接口：查不到可返回 data 为 null，并带业务错误码；也可用 404，但要在文档里固定，不要一半接口用 404、一半用 null。
• 更新接口：字段没传通常表示不更新，传 null 才表示清空；这条规则要写进接口文档，否则前后端对 null 的理解会打架。
• 嵌套列表：对象里的子列表没数据也返回 []，避免 data 为 null 时再取 list 的二次判空。

可核对对比：空数组与 null 的落地差异

下面按常见交付场景对比，不作为固定标准，只用来核对取舍。成本用经验区间描述，避免拍脑袋定死。

• 集合字段返回 []：前端可直接按长度渲染，循环安全；代价是文档要说明 [] 不等于没有这个字段，Mock 要覆盖空列表。
• 单个对象返回 null：能表达不存在，调用方需要先判断再取属性；代价是各端都要处理 null，漏判会引起报错。
• 混用 null 和 []：短期省事，长期让多端各自兜底；经验区间是联调返工 1~3 次、线上空状态问题 0~2 次较常见。
• 统一契约加前端判空封装：前期多花约半天到一天，后续每轮联调通常能省 0~1 次判空修改，多端收益更明显。

这组对比的核心不是谁更好，而是让调用方能用同一套判断处理同类字段。调用方越多、接口生命周期越长，统一形态的收益越明显。

交付现场：约束下的做法与代价

在一个预算紧、周期短的项目里，常见约束是后端用默认序列化配置、前端两个端并行开发、测试环境数据少。若没人统一空值规则，前端会各自写兜底，空列表页偶发白屏，返工往往要重新发版。更稳的做法是先做三件事：接口文档补空列表、空对象、字段缺失三个示例；前端统一走 safeArray 一类判空工具；联调验收把空数据当正常用例跑。代价是前期多花约半天到一天对齐，收益是后面通常能省 0~2 轮改稿和解释成本。这个经验区间不是承诺值，而是交付中较常见的范围。

适用与不适用边界

空值契约适合前后端分离、多端复用、对外开放接口、列表和分页较多的系统。按 2026 年常见交付习惯，只要接口调用方超过一个，或者前后端由不同人维护，就值得把列表空返回 []、对象空返回 null 写进文档。它带来的价值是减少判空分叉，让空状态、错误状态、无权限状态各自可识别。

反过来，内部一次性脚本、单人维护的小工具、字段固定且只服务一个页面的接口，不一定需要专门设计空值协议。这类场景把规则写得太细，沟通成本可能高于收益。边界可以记成：空值规则不是越多越好，而是调用方越多、生命周期越长，越值得固定；只服务一个消费方且随时可改的接口，可以先用最简单的方式跑通。

常见问题

列表接口没数据返回 [] 还是 null？

建议返回 []，同时 total 为 0。这样前端可以直接按长度渲染空状态，循环也不会因为 null 出错；关键是同一接口保持一致。

详情接口查不到数据，返回 null 还是 404？

两种都能用，但要在文档里固定。返回 null 时配业务错误码，返回 404 时前端按异常处理，避免一半接口一种写法。

前端判空写 if(data) 为什么有时会漏？

空数组在 JavaScript 里是真值，if(data) 会进入有数据分支，但 length 为 0，列表可能一直显示加载中。判空要按类型分开写。

后端框架默认把空集合序列化成 null，要不要全局改？

先看调用方数量。多端或对外开放接口，建议在序列化配置和文档里统一空集合形态；内部单端接口可先按现状，改前用空数据用例验证影响。

返回空数组会不会让前端误以为有数据？

一般不会，空数组长度是 0，前端应按长度渲染空状态。真正容易误判的是把错误响应当成空数组返回，错误场景应走错误码。

如果正在联调列表或分页接口，可以先做一件事：把无数据、无权限、超时三种返回各写一个示例进文档，再让前端按示例跑空数据分支。适用边界是调用方较多、接口会长期维护的系统；临时脚本或单端小工具不必照搬。把空值形态固定下来，后面 2026 年的迭代和老接口兼容会省不少解释成本。