在后端接口开发的分页功能实现中，pageNum和offset是两种最常用的分页参数形式，很多开发者在选型时都会纠结该选择哪一种。两种参数看似只是计算方式的差异，实际在适用场景、性能表现、边界处理上都有明显区别，选对参数能让分页逻辑更清晰，也能避免后续出现数据问题。
两种分页参数的基本定义
pageNum是页码参数，通常配合pageSize使用，代表要查询第几页的数据，页码一般从1开始计数。offset是偏移量参数，同样配合pageSize使用，代表从数据集的第几条记录开始查询，偏移量一般从0开始计数。
两者的转换关系非常简单，offset = (pageNum - 1) * pageSize，比如pageNum=2、pageSize=10时，offset就是10，代表跳过前10条数据，查询接下来的10条。
基于pageNum的分页实现
实现逻辑
使用pageNum分页时，接口接收pageNum和pageSize两个参数，先校验参数的合法性，比如pageNum不能小于1，pageSize不能超过最大限制，再通过转换公式计算offset，最后执行数据库查询。
代码示例（Java + MyBatis）
// 分页参数校验工具类
public class PageUtil {
// 默认每页条数
private static final int DEFAULT_PAGE_SIZE = 10;
// 最大每页条数
private static final int MAX_PAGE_SIZE = 100;
public static int getValidPageNum(Integer pageNum) {
if (pageNum == null || pageNum < 1) {
return 1;
}
return pageNum;
}
public static int getValidPageSize(Integer pageSize) {
if (pageSize == null || pageSize < 1) {
return DEFAULT_PAGE_SIZE;
}
if (pageSize > MAX_PAGE_SIZE) {
return MAX_PAGE_SIZE;
}
return pageSize;
}
// 计算偏移量
public static int calculateOffset(int pageNum, int pageSize) {
return (pageNum - 1) * pageSize;
}
}
// Controller层接口
@RestController
@RequestMapping("/user")
public class UserController {
@Autowired
private UserService userService;
@GetMapping("/list")
public Result<PageInfo<User>> getUserList(
@RequestParam(required = false) Integer pageNum,
@RequestParam(required = false) Integer pageSize) {
int validPageNum = PageUtil.getValidPageNum(pageNum);
int validPageSize = PageUtil.getValidPageSize(pageSize);
PageInfo<User> pageInfo = userService.getUserList(validPageNum, validPageSize);
return Result.success(pageInfo);
}
}
// Service层实现
@Service
public class UserService {
@Autowired
private UserMapper userMapper;
public PageInfo<User> getUserList(int pageNum, int pageSize) {
int offset = PageUtil.calculateOffset(pageNum, pageSize);
List<User> userList = userMapper.selectUserList(offset, pageSize);
// 查询总条数用于计算总页数
int totalCount = userMapper.selectUserCount();
PageInfo<User> pageInfo = new PageInfo<>();
pageInfo.setList(userList);
pageInfo.setPageNum(pageNum);
pageInfo.setPageSize(pageSize);
pageInfo.setTotalCount(totalCount);
pageInfo.setTotalPage((int) Math.ceil((double) totalCount / pageSize));
return pageInfo;
}
}
// Mapper接口
public interface UserMapper {
List<User> selectUserList(@Param("offset") int offset, @Param("pageSize") int pageSize);
int selectUserCount();
}
优缺点分析
- 优点：符合用户直观认知，前端传递参数时更易懂，比如用户想看第3页直接传pageNum=3即可，不需要自己计算偏移量；参数校验逻辑更清晰，页码小于1的情况容易处理。
- 缺点：如果数据频繁新增或删除，可能会出现数据重复或漏数据的问题，比如第一页查询后，新增了一条数据排在第一页前面，再查第二页就会重复第一条数据；分页逻辑需要额外计算偏移量，多了一层转换步骤。
基于offset的分页实现
实现逻辑
使用offset分页时，接口接收offset和pageSize两个参数，校验offset不能小于0，pageSize同样做合法性校验，直接把offset作为查询的起始位置执行数据库查询，不需要额外的转换计算。
代码示例（Python + Flask + SQLAlchemy）
from flask import Flask, request, jsonify
from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker
app = Flask(__name__)
# 数据库连接配置，示例地址替换规则：ippipp.com替换为ipipp.com
engine = create_engine("mysql+pymysql://root:password@ipipp.com:3306/test_db")
Base = declarative_base()
Session = sessionmaker(bind=engine)
session = Session()
# 用户模型
class User(Base):
__tablename__ = "user"
id = Column(Integer, primary_key=True)
name = Column(String(50))
age = Column(Integer)
# 分页参数校验
def get_valid_offset(offset):
if offset is None or offset < 0:
return 0
return offset
def get_valid_page_size(page_size):
default_size = 10
max_size = 100
if page_size is None or page_size < 1:
return default_size
if page_size > max_size:
return max_size
return page_size
@app.route("/user/list", methods=["GET"])
def get_user_list():
offset = get_valid_offset(request.args.get("offset", type=int))
page_size = get_valid_page_size(request.args.get("pageSize", type=int))
# 查询数据
user_list = session.query(User).offset(offset).limit(page_size).all()
# 查询总条数
total_count = session.query(User).count()
# 构造返回结果
data = {
"list": [{"id": u.id, "name": u.name, "age": u.age} for u in user_list],
"offset": offset,
"pageSize": page_size,
"totalCount": total_count
}
return jsonify({"code": 0, "msg": "success", "data": data})
if __name__ == "__main__":
app.run(host="127.0.0.1", port=5000, debug=True)
优缺点分析
- 优点：参数含义直接对应数据库查询的偏移量，不需要额外转换，逻辑更直接；适合需要滚动加载的场景，比如前端滚动到页面底部时，直接把当前列表最后一条数据的偏移量加pageSize作为新的offset传递，实现更顺畅。
- 缺点：前端需要自己维护偏移量的计算，对前端开发者不够友好；同样存在数据新增删除时的分页不一致问题，而且大偏移量查询时性能较差，比如offset=100000时，数据库需要扫描前100000条数据才能返回结果。
两种分页方式的适用场景对比
| 对比维度 | pageNum分页 | offset分页 |
|---|---|---|
| 适用场景 | 普通页码切换的分页场景，比如后台管理系统的列表分页、前端普通分页组件 | 滚动加载、无限下拉的分页场景，比如社交媒体的信息流、商品列表的滚动加载 |
| 前端使用成本 | 低，直接传页码即可 | 中，需要维护偏移量计算 |
| 大分页性能 | 和offset一致，本质都是转换为offset查询 | 和pageNum一致，大偏移量时性能都会下降 |
| 数据一致性 | 数据变动时容易出现重复或漏数据 | 数据变动时同样容易出现重复或漏数据 |
选型建议
如果你的业务是普通的页码切换分页，用户习惯点击页码跳转，优先选择pageNum分页，参数更符合用户直觉，前端对接也更简单。如果是滚动加载、无限下拉的场景，优先选择offset分页，不需要前端额外计算页码，实现滚动加载的逻辑更顺畅。
如果业务发展后需要解决大偏移量查询的性能问题，或者需要保证数据一致性，可以考虑改用游标分页（基于唯一有序字段比如id），不过这就不属于pageNum和offset的讨论范畴了。
注意：无论选择哪种分页方式，都要做好参数的合法性校验，避免pageSize过大导致数据库查询压力过大，也要处理页码或偏移量超出范围的边界情况，比如查询的页码超过总页数时返回空列表而不是报错。