一次PHP接口分页字段命名引发的两端争论

我们组上周因为一个分页接口字段命名，前端和后端在群里吵了一下午。

起因很简单，我写了个接口，返回的分页数据结构是 `{"page": 1, "limit": 20, "total": 305}`。前端同事拿到接口文档后，第一时间在群里 @ 我：“这个 `page` 和 `limit` 能不能改成 `pageNum` 和 `pageSize`？我们前端封装好的请求库参数就是这两个名字，你直接用的话我们就不用做数据转换了。”

我当时觉得有点莫名其妙：“`page` 和 `limit` 不是挺语义化的吗？前端拿到数据之后做个映射不就完事了？”

就这么一来一回，争论逐渐从技术细节上升到了工作态度问题。他说我不考虑前端体验，我说他过度封装、不够灵活。说到后面，甚至开始翻旧账，把上个月接口联调时踩的坑都拿出来说了。

现在复盘，其实我们争的根本不是字段该叫什么，而是接口设计到底该由谁主导。

后端的逻辑是：我是数据提供方，分页逻辑在我的 SQL 里写，我定义什么参数你就用什么参数，这没问题。而前端的逻辑是：我们有自己的代码规范，分页请求逻辑已经被封装成通用方法了，你接口参数不一致，我每次都要单独处理，长期看维护成本挺高的。

谁的诉求更合理？其实都合理，但也都暴露了一点问题——我们谁都没有站在对方的使用场景里想问题。

从后端视角看，`page` 和 `limit` 是我从数据库层面自然推导出的参数。比如写 Laravel 的 `paginate(20)`，或者手写 `LIMIT #{limit} OFFSET #{(page-1) * limit}`，这两个字段是离数据库最近的天然命名。响应结构也是跟着查询逻辑走，没想过前端拿数据之后是要拆开重组，还是直接塞进组件里。

从前端视角看，`pageSize` 这种命名其实是 UI 组件领域的一个通用约定。antd 的 Table 组件用的是 `current` 和 `pageSize`，Element UI 的 `el-pagination` 是 `pageSize` 和 `currentPage`。如果后端接口直接用这几个字段，前端理论上可以做到“零转换”地直接对接组件库的数据结构。但如果每个接口风格不一样，今天接口 A 是 `page`/`limit`，明天接口 B 是 `pageIndex`/`pageCount`，那前端就要写一堆无意义的适配代码，纯粹是浪费。

说白了，这不是命名对错的辩论，而是接口契约的共识问题。

后来我仔细想了想，其实这位前端同事提的诉求也不是他的个人偏好，而是他们团队已经形成了前后端接口规范，上面写了分页参数统一用 `pageNum`/`pageSize`。这种情况下，我的接口设计如果再标新立异，确实会给团队协作增加不必要的摩擦。一个接口一个风格，长期下去接口文档就和代码一样，慢慢就变成没人能维护的“屎山”了。

于是我在群里主动说了一句：“行，那我这边改一下，返回参数和请求参数都统一成 `pageNum` 和 `pageSize`。”

他应该是有点意外，过了一会儿回了个：“好的好的，辛苦辛苦。之前说话有点冲，不好意思。”

我说：“没事，都是想把事做好。不过下次可以早点把接口规范文档发我一份，我也就不用凭感觉设计了。”

他说：“是我的锅，我回去把文档整理好发群里。”

事情就这么翻篇了。

现在想想，很多前后端矛盾到最后其实不是技术能力问题，而是沟通时机问题。如果一开始就有明确的接口统一规范，哪怕规范不是最优的，也比争论什么最好强一万倍——技术方案的合理性是在沟通里长出来的，不是在群里争出来的。只要目标是让项目顺利推进，谁改一行代码、谁做一下兼容，真没那么重要。

当然，也不是说后端就要无条件服从前端。如果后端接口设计是真有问题——比如返回了多余的大字段、循环引用了嵌套对象、或者压根分不了页——那代码里该重构的还是得重构。但纯粹是命名风格这类标准化问题，就按团队规范来，没必要较真。**一个团队能顺畅协作的基础，不是每个人都是最强个体，而是大家愿意在同一套契约下保持一致。**

现在再看这个分页参数的命名，它根本不是一个技术问题，而是一个协作默契问题。只要这种默契存在，叫 `page` 还是 `pageNum`，都不重要。