时间查询String格式支持说明.md 4.45 KB

Raw Blame History Permalink



时间查询@JsonFormat注解支持说明


功能概述

后端用户查询接口使用 @JsonFormat 注解统一处理时间格式，简化了时间参数的处理逻辑，确保时间格式的一致性。


修改内容


1. DTO类修改

文件: UserQueryReq.java

修改前:

private LocalDateTime startTime;
private LocalDateTime endTime;


修改后:

/**
 * 开始时间（创建时间范围查询）
 */
@JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
private LocalDateTime startTime;

/**
 * 结束时间（创建时间范围查询）
 */
@JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
private LocalDateTime endTime;


2. 查询条件构建简化

文件: SysUserServiceImpl.java

修改前:

// 开始时间：创建时间 >= 开始时间
if (StringUtils.isNotEmpty(queryReq.getStartTime())) {
    LocalDateTime startTime = parseDateTime(queryReq.getStartTime());
    if (startTime != null) {
        wrapper.ge(SysUser::getCreateTime, startTime);
    }
}


修改后:

// 开始时间：创建时间 >= 开始时间
if (queryReq.getStartTime() != null) {
    wrapper.ge(SysUser::getCreateTime, queryReq.getStartTime());
}


支持的时间格式


1. 标准格式


2025-09-23 - 日期格式（推荐）
时区：GMT+8（中国标准时间）


2. @JsonFormat注解优势


自动格式验证
时区自动转换
代码简洁
性能优化


功能特点


1. 自动格式处理


Jackson自动处理时间格式转换
统一的时区处理（GMT+8）
无需手动解析时间字符串


2. 代码简化


移除了复杂的时间解析逻辑
减少了代码维护成本
提高了代码可读性


3. 性能优化


利用Jackson的高效序列化/反序列化
减少自定义解析逻辑
更好的内存管理


使用示例


1. API调用示例

# 标准日期格式（推荐）
curl -X GET "http://localhost:8083/api/system/user/list?startTime=2025-09-23&endTime=2025-09-24"


2. 前端时间选择器

// 前端生成的时间格式（yyyy-MM-dd）
const startTime = "2025-09-23"
const endTime = "2025-09-24"

// API调用
const params = {
  startTime: startTime,
  endTime: endTime,
  pageNum: 1,
  pageSize: 10
}


3. 数据库查询

-- 实际执行的SQL查询
SELECT * FROM t_sys_user 
WHERE del_flag = '0' 
AND create_time >= '2025-09-23 00:00:00' 
AND create_time <= '2025-09-23 23:59:59'
ORDER BY create_time DESC;


错误处理


1. 格式错误处理

// 解析失败时的处理
if (startTime == null) {
    // 记录日志但不中断查询
    System.err.println("时间格式解析失败: " + queryReq.getStartTime());
    // 跳过该查询条件
}


2. 空值处理

// 空值检查
if (StringUtils.isNotEmpty(queryReq.getStartTime())) {
    // 只有非空时才进行解析
}


3. 时区处理

// 时区信息移除
if (dateTimeStr.endsWith("Z") || dateTimeStr.contains("+") || dateTimeStr.contains("-")) {
    String localTimeStr = dateTimeStr.replaceAll("[+-]\\d{2}:\\d{2}$", "").replace("Z", "");
    return LocalDateTime.parse(localTimeStr, formatter);
}


性能考虑


1. 格式化器缓存


使用静态格式化器数组
避免重复创建格式化器对象
按使用频率排序


2. 解析优化


按常用格式优先尝试
快速失败机制
避免不必要的字符串操作


3. 内存管理


及时释放临时对象
避免字符串拼接
使用高效的字符串操作


测试建议


1. 格式测试

// 测试各种时间格式
String[] testFormats = {
    "2025-09-23T10:06:13.293Z",
    "2025-09-23T10:06:13",
    "2025-09-23",
    "2025-09-23 10:06:13",
    "2025/09/23"
};

for (String format : testFormats) {
    LocalDateTime result = parseDateTime(format);
    System.out.println(format + " -> " + result);
}


2. 边界测试


测试极端时间值
测试格式错误的时间
测试空值和null值


3. 性能测试


测试大量时间解析的性能
测试并发解析的安全性
测试内存使用情况


注意事项


时区一致性: 确保前后端时区设置一致

格式验证: 前端应验证时间格式的正确性

性能监控: 监控时间解析的性能影响

日志记录: 记录解析失败的情况便于调试


相关文件


UserQueryReq.java - 查询请求DTO

SysUserServiceImpl.java - 服务实现类

API接口文档.md - API文档更新