Feathers 后台列表分页契约怎么定

后台开发里最常见的接口，就是列表页。可也正因为它太常见，团队很容易在 2021 年这种快速迭代环境里把它写成“每个模块各有一套参数”。等到前端页面一多，分页契约不统一的代价就会开始出现。

Feathers 本身已经有一套查询习惯，用得好可以帮我们把这层边界先收住。

分页参数要先达成共识

无论最终是沿用 Feathers 的 limit、skip 风格，还是在网关层再包一层 page 语义，都应该尽量全站统一。最怕的是用户模块按页码，文章模块按偏移量，日志模块又自定义一套名字。

后台不是不能有特殊接口，但基础列表最好说同一种语言。

排序和筛选字段要有白名单

一旦把任意字段排序、任意字段模糊搜索直接暴露出去，Sequelize 查询很快就会失控。更稳的做法是先定义允许筛选和排序的字段集合，再把前端传入参数映射到 ORM 查询。

这一步既是安全控制，也是性能控制。

分页返回结构也别每个模块自己发挥

前端最希望拿到的是稳定结构，比如总数、当前页数据、是否还有下一页。如果某些接口返回 { list, total }，另一些返回 { rows, count }，页面层就会不断写适配逻辑。

后台接口真正节省时间的地方，往往就在这些看似不起眼的一致性上。

大列表要提早考虑默认排序

没有默认排序的分页接口，随着数据量增长会越来越不可预测。内容后台里最常见的默认值一般是更新时间或发布时间倒序，这至少能让用户和程序都知道“第一页代表什么”。

分页契约不只是参数长什么样，也包括结果排序有没有稳定含义。

小结

Feathers 后台列表一旦把分页、排序和筛选白名单统一起来，后续前后端协作会轻松很多。对 2021 年追求快速交付的内部系统来说，这种稳定契约特别值钱。