use serde::{Deserialize, Serialize};
use super::response::ApiError;
pub const DEFAULT_PAGE: u64 = 1;
pub const DEFAULT_PAGE_SIZE: u64 = 20;
pub const MAX_PAGE_SIZE: u64 = 50;
#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[non_exhaustive]
pub struct PageRequest {
#[serde(default = "default_page")]
pub page: u64,
#[serde(default = "default_page_size")]
pub page_size: u64,
}
impl Default for PageRequest {
fn default() -> Self {
Self {
page: default_page(),
page_size: default_page_size(),
}
}
}
impl PageRequest {
pub fn verify(page: Option<u64>, page_size: Option<u64>) -> Result<Self, ApiError> {
Self::new(
page.unwrap_or(DEFAULT_PAGE),
page_size.unwrap_or(DEFAULT_PAGE_SIZE),
MAX_PAGE_SIZE,
)
}
pub fn new(page: u64, page_size: u64, max_page_size: u64) -> Result<Self, ApiError> {
let request = Self { page, page_size };
request.validate(max_page_size)?;
Ok(request)
}
pub fn validate(&self, max_page_size: u64) -> Result<(), ApiError> {
if self.page == 0 {
return Err(ApiError::err_invalid_param("页码必须大于或等于 1"));
}
if max_page_size == 0 {
return Err(
ApiError::err_other("服务端分页配置无效").with_error("max_page_size 必须大于 0")
);
}
if self.page_size == 0 || self.page_size > max_page_size {
return Err(ApiError::err_invalid_param(format!(
"每页数量必须在 1 到 {max_page_size} 之间"
)));
}
self.offset()
.map(|_| ())
.ok_or_else(|| ApiError::err_invalid_param("分页参数过大,请缩小页码或每页数量"))
}
#[must_use]
pub fn offset(&self) -> Option<u64> {
self.page.checked_sub(1)?.checked_mul(self.page_size)
}
pub fn offset_i64(&self) -> Result<i64, ApiError> {
self.offset()
.and_then(|offset| i64::try_from(offset).ok())
.ok_or_else(|| ApiError::err_invalid_param("分页偏移量超出数据库支持范围"))
}
pub fn page_size_i64(&self) -> Result<i64, ApiError> {
i64::try_from(self.page_size)
.map_err(|_| ApiError::err_invalid_param("每页数量超出数据库支持范围"))
}
}
#[derive(Clone, Debug, Serialize)]
#[non_exhaustive]
#[must_use = "分页结果应返回给调用方或继续处理"]
pub struct Page<T> {
pub items: Vec<T>,
pub total: u64,
pub page: u64,
pub page_size: u64,
pub total_pages: u64,
}
impl<T> Page<T> {
pub const fn new(items: Vec<T>, total: u64, request: PageRequest) -> Self {
let total_pages = if total == 0 || request.page_size == 0 {
0
} else {
1 + (total - 1) / request.page_size
};
Self {
items,
total,
page: request.page,
page_size: request.page_size,
total_pages,
}
}
#[must_use]
pub const fn is_empty(&self) -> bool {
self.items.is_empty()
}
#[must_use]
pub fn into_items(self) -> Vec<T> {
self.items
}
}
const fn default_page() -> u64 {
DEFAULT_PAGE
}
const fn default_page_size() -> u64 {
DEFAULT_PAGE_SIZE
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn request_validates_bounds_and_calculates_offset() {
let request = PageRequest::new(3, 20, 100).unwrap();
assert_eq!(request.offset(), Some(40));
assert_eq!(request.offset_i64().unwrap(), 40);
assert_eq!(request.page_size_i64().unwrap(), 20);
assert_eq!(PageRequest::new(0, 20, 100).unwrap_err().code, 400_001);
assert_eq!(PageRequest::new(1, 101, 100).unwrap_err().code, 400_001);
assert!(PageRequest::new(u64::MAX, 2, 100).is_err());
}
#[test]
fn verify_applies_defaults_and_default_limit() {
let defaults = PageRequest::verify(None, None).unwrap();
assert_eq!(defaults.page, DEFAULT_PAGE);
assert_eq!(defaults.page_size, DEFAULT_PAGE_SIZE);
let maximum = PageRequest::verify(Some(2), Some(MAX_PAGE_SIZE)).unwrap();
assert_eq!(maximum.page, 2);
assert_eq!(maximum.page_size, MAX_PAGE_SIZE);
assert_eq!(maximum.offset(), Some(MAX_PAGE_SIZE));
}
#[test]
fn verify_rejects_zero_and_oversized_values_with_api_error() {
for error in [
PageRequest::verify(Some(0), Some(20)).unwrap_err(),
PageRequest::verify(Some(1), Some(0)).unwrap_err(),
PageRequest::verify(Some(1), Some(MAX_PAGE_SIZE + 1)).unwrap_err(),
] {
assert_eq!(error.code, 400_001);
}
assert_eq!(
PageRequest::verify(Some(1), Some(MAX_PAGE_SIZE + 1))
.unwrap_err()
.msg,
"每页数量必须在 1 到 50 之间"
);
}
#[test]
fn page_calculates_total_pages_without_overflow() {
let request = PageRequest::new(1, 20, 100).unwrap();
let page = Page::<()>::new(Vec::new(), u64::MAX, request);
assert_eq!(page.total_pages, 922_337_203_685_477_581);
}
}