签入脚本

api/v1/common.go

@@ -0,0 +1,72 @@
+package v1
+
+// ============================== 公共基础模块 ==============================
+
+// PageReq 分页公共参数
+// 对应前端分页契约：pageNo/pageSize
+type PageReq struct {
+	PageNo   int `json:"pageNo"   dc:"页码，从1开始，默认1"`     // 页码，从1开始
+	PageSize int `json:"pageSize" dc:"每页条数，默认10，最大500"` // 每页条数
+}
+
+// GetPageNo 获取页码
+// 页码小于等于0时返回默认值1
+func (p *PageReq) GetPageNo() int {
+	if p.PageNo <= 0 {
+		return 1
+	}
+	return p.PageNo
+}
+
+// GetPageSize 获取每页条数
+// 每页条数小于等于0时返回默认值10，超过500时按500截断
+func (p *PageReq) GetPageSize() int {
+	if p.PageSize <= 0 {
+		return 10
+	}
+	if p.PageSize > 500 {
+		return 500
+	}
+	return p.PageSize
+}
+
+// Offset 计算SQL LIMIT偏移量
+// 偏移量 = (页码 - 1) × 每页条数
+func (p *PageReq) Offset() int {
+	return (p.GetPageNo() - 1) * p.GetPageSize()
+}
+
+// IdsReq 批量删除入参
+// 通用批量操作请求体，携带待操作的ID列表
+type IdsReq struct {
+	Ids []int64 `json:"ids" v:"required#请选择要操作的记录" dc:"ID列表"` // ID列表
+}
+
+// IdRes 通用返回ID结构
+// 各模块新增等接口共用的返回结果
+type IdRes struct {
+	Id int64 `json:"id"` // 主键ID
+}
+
+// PageData 统一分页壳
+// 对应前端分页契约：records/total/size/current/pages
+type PageData[T any] struct {
+	Records []T `json:"records"` // 当前页记录列表
+	Total   int `json:"total"`   // 总记录数
+	Size    int `json:"size"`    // 请求的每页条数
+	Current int `json:"current"` // 请求页码
+	Pages   int `json:"pages"`   // 总页数
+}
+
+// NewPageData 构造分页壳
+// records 为空时输出空数组而非 null，pages 按总记录数与每页条数计算得出
+func NewPageData[T any](pageNo, pageSize, total int, records []T) *PageData[T] {
+	if records == nil {
+		records = []T{}
+	}
+	pages := 0
+	if pageSize > 0 {
+		pages = (total + pageSize - 1) / pageSize
+	}
+	return &PageData[T]{Records: records, Total: total, Size: pageSize, Current: pageNo, Pages: pages}
+}