数据模型

API统一响应体

DataResponse是Blade框架中用于封装网络请求响应的核心数据类。它提供了一种标准化的响应格式，包含请求是否成功、响应代码、消息和数据等信息。

字段定义

DataResponse<T>类包含以下字段：

字段详细说明

字段	类型	必填	默认值	描述
successful	Boolean	是	false	请求是否成功执行的标志
code	Int	是	-	响应状态码，遵循 HTTP 状态码规范
message	String	否	""	响应的描述性消息
data	T?	否	null	实际的响应数据，泛型类型

响应格式示例

成功响应示例

{
  "successful": true,
  "code": 200,
  "message": "请求成功",
  "data": {
    "id": 1,
    "name": "blade",
    "email": "blade@example.com"
  }
}

失败响应示例

{
  "successful": false,
  "code": 400,
  "message": "参数错误：用户名不能为空",
  "data": null
}

扩展函数

框架提供了丰富的扩展函数，简化 DataResponse 的创建：

成功响应扩展函数

• toSuccess(): 创建成功响应，默认使用 OK 状态码
• toSuccess(message: String): 创建带自定义消息的成功响应
• toSuccessWithMessage(message: String): 创建带自定义消息的无数据成功响应

失败响应扩展函数

• toFailure(code: Int, message: String): 创建指定状态码和消息的失败响应
• toFailure(responseCode: ResponseCode): 使用枚举状态码的失败响应
• toFailure(responseCode: ResponseCode, message: String): 带自定义消息的枚举状态码失败响应

条件响应扩展函数

• toSuccessIf(condition: Boolean, errorMessage: () -> String): 条件成功/失败响应
• toSuccessIf(condition: Boolean, errorCode: ResponseCode): 条件成功/失败响应（枚举状态码）

分页响应模型 PageVo

PageVo是Blade框架中用于封装分页查询结果的基础响应实体。

字段定义

PageVo<T>类包含以下字段：

字段详细说明

字段	类型	必填	默认值	描述
pageNum	Int	是	0	当前页码，主要给 web 端做分页校验
total	Int	是	0	总数据量
list	List<T>	是	emptyList()	分页数据列表

使用场景

PageVo 主要用于以下场景：

• 查询列表数据并进行分页展示
• Web 前端的分页组件数据源
• 移动端的分页加载

使用示例

// 创建分页响应
val pageVo = PageVo(
    pageNum = 1,
    total = 100,
    list = listOf("item1", "item2", "item3")
)

兼容性

PageVo支持多种集合类型，包括ArrayList、MutableList和不可变列表等。

ComplexPageParam 复杂分页参数模型

模型定义

ComplexPageParam 是一个复杂的分页查询参数模型，支持排序和过滤功能。

字段详细说明

字段	类型	必填	默认值	描述
pageNum	Int	否	1	要获取的页面的编号
pageSize	Int	否	10	每页的项目数量，最大值为 200
sort	List<SortRequest>	否	emptyList()	排序请求列表
filters	T	是	-	过滤器实体，泛型类型

排序功能

SortRequest 结构

data class SortRequest(
    val field: String,      // 要排序的字段
    val order: SortDirection // 排序方向
)

SortDirection 枚举

• ASC / asc: 升序排列
• DESC / desc: 降序排列

JSON 参数示例

{
  "pageNum": 1,
  "pageSize": 10,
  "sort": [
    {
      "field": "createdTime",
      "order": "desc"
    },
    {
      "field": "name",
      "order": "asc"
    }
  ],
  "filters": {
    "status": "active",
    "name": "John",
    "age": 30
  }
}

参数验证与限制

• pageSize 会被自动限制在 1-200 范围内 以防大面积查询
• 超出范围时自动调整为边界值
• 支持各种过滤器类型（字符串、对象、Map 等）

状态码约定

ResponseCode 接口

所有状态码都实现 ResponseCode 接口：

HTTP 状态码映射

状态码范围	描述	示例状态码
200-299	成功响应	OK(200)
400-499	客户端错误	BAD_REQUEST(400), UNAUTHORIZED(401), FORBIDDEN(403)
500-599	服务器错误	SERVER_ERROR(500), REMOTE_SERVER_ERROR(501)
600-659	应用特定错误	LOGIN_FAILED(600), LOGIN_TIMEOUT(601)

自定义业务状态码

开发者可以创建自定义业务状态码：

object BusinessResponseCode {
    val USER_NOT_FOUND = ResponseCode.Default(1001, "用户不存在")
    val INVALID_PASSWORD = ResponseCode.Default(1002, "密码错误")
    val ACCOUNT_LOCKED = ResponseCode.Default(1003, "账户已锁定")
}