Feathers.js 分页与查询参数约定

Feathers.js 很适合做资源型接口，但只要后台系统开始出现列表页、筛选器和搜索框，params.query 很快就会从一小块对象膨胀成谁都不敢碰的入口。

我在 2021 年做这类接口时，一个很深的感受是: 与其后面不停修分页 bug，不如一开始就把查询参数约定定住。

先把列表接口的公共字段统一

最常见也最值得统一的，其实就几类:

• 页码或偏移量
• 每页条数
• 排序字段与方向
• 关键词搜索
• 状态、分类、时间区间这类业务筛选

如果不同 service 各玩各的命名，前端调用成本会迅速变高。

默认值要比“完全自由”更有价值

很多人喜欢把查询完全交给调用方控制，但后台项目里更稳的方式通常是:

• 给每页条数一个默认值
• 给最大分页大小设上限
• 没传排序时走稳定排序

这样可以避免导出式大查询直接把数据库打满，也能避免列表在翻页过程中顺序飘来飘去。

搜索条件最好先做白名单

Feathers 把查询对象透传得很方便，但方便也意味着更容易失控。尤其是接 ORM 时，如果前端把任意字段都能拼进来，后面很容易出现:

• 业务不允许的字段被筛选
• 排序字段越传越多
• 查询条件和索引完全不匹配

所以我更倾向于在 hook 里先做一次查询字段白名单转换，把前端习惯用的参数名翻成后端内部认可的条件。

分页返回结构要稳定

前端真正依赖的不是“有没有查到数据”，而是总数、当前页、还有没有下一页这些元信息。如果每个 service 返回结构都不一样，列表组件复用几乎不可能顺手。

Feathers 自带的分页形态已经够用了，关键是别在不同接口上随意改壳。

小结

Feathers.js 的查询参数本身不复杂，复杂的是团队有没有提前约定它的边界。把分页、排序、筛选字段和默认值先统一好，后面的中后台列表才不会越做越难维护。