loveyu-kit 0.2.0

面向 Axum 项目的可组合 API 工具库
Documentation
//! 与具体数据库无关的分页值对象。

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 {
    /// 从 1 开始的页码。
    #[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 {
    /// 补齐缺省值并使用工具库默认上限校验分页参数。
    ///
    /// `page` 缺省时使用 [`DEFAULT_PAGE`],`page_size` 缺省时使用
    /// [`DEFAULT_PAGE_SIZE`],每页数量不得超过 [`MAX_PAGE_SIZE`]。
    ///
    /// # Errors
    ///
    /// 页码或每页数量为 0、每页数量超过 50,或偏移量溢出时返回
    /// [`ApiError::err_invalid_param`]。
    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,
        )
    }

    /// 创建并校验分页参数。
    ///
    /// # Errors
    ///
    /// 页码、每页数量、服务端上限或偏移量非法时返回参数错误。
    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)
    }

    /// 校验分页参数。
    ///
    /// # Errors
    ///
    /// 页码、每页数量、服务端上限或偏移量非法时返回参数错误。
    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("分页参数过大,请缩小页码或每页数量"))
    }

    /// 返回 SQL 查询可使用的偏移量;溢出时返回 `None`。
    #[must_use]
    pub fn offset(&self) -> Option<u64> {
        self.page.checked_sub(1)?.checked_mul(self.page_size)
    }

    /// 返回 `SQLx` 等数据库接口常用的有符号偏移量。
    ///
    /// # Errors
    ///
    /// 偏移量溢出 `u64` 或无法表示为 `i64` 时返回参数错误。
    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("分页偏移量超出数据库支持范围"))
    }

    /// 返回 `SQLx` 等数据库接口常用的有符号每页数量。
    ///
    /// # Errors
    ///
    /// 每页数量无法表示为 `i64` 时返回参数错误。
    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);
    }
}