Tio Boot DocsTio Boot Docs
Home
  • java-db
  • api-table
  • Enjoy
  • Tio Boot Admin
  • ai_agent
  • translator
  • knowlege_base
  • ai-search
  • 案例
Abount
  • Github
  • Gitee
Home
  • java-db
  • api-table
  • Enjoy
  • Tio Boot Admin
  • ai_agent
  • translator
  • knowlege_base
  • ai-search
  • 案例
Abount
  • Github
  • Gitee
  • 01_tio-boot 简介

    • tio-boot:新一代高性能 Java Web 开发框架
    • tio-boot 入门示例
    • Tio-Boot 配置 : 现代化的配置方案
    • tio-boot 整合 Logback
    • tio-boot 整合 hotswap-classloader 实现热加载
    • 自行编译 tio-boot
    • 最新版本
    • 开发规范
  • 02_部署

    • 使用 Maven Profile 实现分环境打包 tio-boot 项目
    • Maven 项目配置详解:依赖与 Profiles 配置
    • tio-boot 打包成 FastJar
    • 使用 GraalVM 构建 tio-boot Native 程序
    • 使用 Docker 部署 tio-boot
    • 部署到 Fly.io
    • 部署到 AWS Lambda
    • 到阿里云云函数
    • 使用 Deploy 工具部署
    • 使用Systemctl启动项目
    • 使用 Jenkins 部署 Tio-Boot 项目
    • 使用 Nginx 反向代理 Tio-Boot
    • 使用 Supervisor 管理 Java 应用
    • 已过时
    • 胖包与瘦包的打包与部署
  • 03_配置

    • 配置参数
    • 服务器监听器
    • 内置缓存系统 AbsCache
    • 使用 Redis 作为内部 Cache
    • 静态文件处理器
    • 基于域名的静态资源隔离
    • DecodeExceptionHandler
  • 04_原理

    • 生命周期
    • 请求处理流程
    • 重要的类
  • 05_json

    • Json
    • 接受 JSON 和响应 JSON
    • 响应实体类
  • 06_web

    • 概述
    • 文件上传
    • 接收请求参数
    • 接收日期参数
    • 接收数组参数
    • 返回字符串
    • 返回文本数据
    • 返回网页
    • 请求和响应字节
    • 文件下载
    • 返回视频文件并支持断点续传
    • http Session
    • Cookie
    • HttpRequest
    • HttpResponse
    • Resps
    • RespBodyVo
    • 拦截器
    • 全局异常处理器
    • 异步
    • 动态 返回 CSS 实现
    • 返回图片
    • Transfer-Encoding: chunked 实时音频播放
    • Server-Sent Events (SSE)
    • 接口访问统计
    • 接口请求和响应数据记录
    • 自定义 Handler 转发请求
    • 使用 HttpForwardHandler 转发所有请求
    • 跨域
    • 添加 Controller
    • 常用工具类
    • HTTP Basic 认证
    • Http响应加密
    • 在 Tio-boot 中使用零拷贝发送大文件
    • WebJars
    • JProtobuf
    • Tio-Boot HTTP Speed Test
  • 07_validate

    • 数据紧校验规范
    • 参数校验
  • 08_websocket

    • 使用 tio-boot 搭建 WebSocket 服务
    • WebSocket 聊天室项目示例
  • 09_java-db

    • java‑db
    • 操作数据库入门示例
    • SQL 模板 (SqlTemplates)
    • 数据源配置与使用
    • ActiveRecord
    • Db 工具类
    • 批量操作
    • Model
    • 生成器与 Model
    • 异常处理
    • 数据库事务处理
    • Cache 缓存
    • Dialect 多数据库支持
    • 表关联操作
    • 复合主键
    • Oracle 支持
    • Enjoy SQL 模板
    • 整合 Enjoy 模板最佳实践
    • 多数据源支持
    • 独立使用 ActiveRecord
    • 调用存储过程
    • java-db 整合 Guava 的 Striped 锁优化
    • 生成 SQL
    • 通过实体类操作数据库
    • java-db 读写分离
    • Spring Boot 整合 Java-DB
    • like 查询
    • 常用操作示例
    • Druid 监控集成指南
    • SQL 统计
  • 10_api-table

    • ApiTable 概述
    • 使用 ApiTable 连接 SQLite
    • 使用 ApiTable 连接 Mysql
    • 使用 ApiTable 连接 Postgres
    • 使用 ApiTable 连接 TDEngine
    • 使用 api-table 连接 oracle
    • 使用 api-table 连接 mysql and tdengine 多数据源
    • EasyExcel 导出
    • EasyExcel 导入
    • TQL(Table SQL)前端输入规范
    • ApiTable 实现增删改查
    • 数组类型
    • 单独使用 ApiTable
  • 11_aop

    • JFinal-aop
    • Aop 工具类
    • 配置
    • 配置
    • 独立使用 JFinal Aop
    • @AImport
    • 原理解析
  • 12_cache

    • Caffine
    • Jedis-redis
    • hutool RedisDS
    • Redisson
    • Caffeine and redis
    • CacheUtils 工具类
    • 使用 CacheUtils 整合 caffeine 和 redis 实现的两级缓存
    • 使用 java-db 整合 ehcache
    • 使用 java-db 整合 redis
    • Java DB Redis 相关 Api
    • redis 使用示例
  • 13_认证和权限

    • hutool-JWT
    • FixedTokenInterceptor
    • 使用内置 TokenManager 实现登录
    • 用户系统
    • 重置密码
    • 匿名登录
    • Google 登录
    • 权限校验注解
    • Sa-Token
    • sa-token 登录注册
    • StpUtil.isLogin() 源码解析
    • 短信登录
    • 移动端微信登录实现指南
    • 移动端重置密码
  • 14_i18n

    • i18n
  • 15_enjoy

    • tio-boot 整合 Enjoy 模版引擎文档
    • 引擎配置
    • 表达式
    • 指令
    • 注释
    • 原样输出
    • Shared Method 扩展
    • Shared Object 扩展
    • Extension Method 扩展
    • Spring boot 整合
    • 独立使用 Enjoy
    • tio-boot enjoy 自定义指令 localeDate
    • PromptEngine
    • Enjoy 入门示例-擎渲染大模型请求体
    • Enjoy 使用示例
  • 16_定时任务

    • Quartz 定时任务集成指南
    • 分布式定时任务 xxl-jb
    • cron4j 使用指南
  • 17_tests

    • TioBootTest 类
  • 18_tio

    • TioBootServer
    • 使用 tio-core 在 tio-boot 中构建独立的 TCP 服务器
    • 内置 TCP 处理器
    • 独立启动 UDPServer
    • 使用内置 UDPServer
    • t-io 消息处理流程
    • tio-运行原理详解
    • TioConfig
    • ChannelContext
    • Tio 工具类
    • 业务数据绑定
    • 业务数据解绑
    • 发送数据
    • 关闭连接
    • Packet
    • 监控: 心跳
    • 监控: 客户端的流量数据
    • 监控: 单条 TCP 连接的流量数据
    • 监控: 端口的流量数据
    • 单条通道统计: ChannelStat
    • 所有通道统计: GroupStat
    • 资源共享
    • 成员排序
    • SSL
    • DecodeRunnable
    • 使用 AsynchronousSocketChannel 响应数据
    • 拉黑 IP
    • 深入解析 Tio 源码:构建高性能 Java 网络应用
  • 19_aio

    • ByteBuffer
    • AIO HTTP 服务器
    • 自定义和线程池和池化 ByteBuffer
    • AioHttpServer 应用示例 IP 属地查询
    • 手写 AIO Http 服务器
  • 20_netty

    • Netty TCP Server
    • Netty Web Socket Server
    • 使用 protoc 生成 Java 包文件
    • Netty WebSocket Server 二进制数据传输
    • Netty 组件详解
  • 21_netty-boot

    • Netty-Boot
    • 原理解析
    • 整合 Hot Reload
    • 整合 数据库
    • 整合 Redis
    • 整合 Elasticsearch
    • 整合 Dubbo
    • Listener
    • 文件上传
    • 拦截器
    • Spring Boot 整合 Netty-Boot
    • SSL 配置指南
    • ChannelInitializer
    • Reserve
  • 22_MQ

    • Mica-mqtt
    • EMQX
    • Disruptor
  • 23_tio-utils

    • tio-utils
    • HttpUtils
    • Notification
    • 邮箱
    • JSON
    • 读取文件
    • Base64
    • 上传和下载
    • Http
    • Telegram
    • RsaUtils
    • EnvUtils
    • 系统监控
    • 毫秒并发 ID (MCID) 生成方案
  • 24_tio-http-server

    • 使用 Tio-Http-Server 搭建简单的 HTTP 服务
    • tio-boot 添加 HttpRequestHandler
    • 在 Android 上使用 tio-boot 运行 HTTP 服务
    • tio-http-server-native
    • handler 常用操作
  • 25_tio-websocket

    • WebSocket 服务器
    • WebSocket Client
  • 26_tio-im

    • 通讯协议文档
    • ChatPacket.proto 文档
    • java protobuf
    • 数据表设计
    • 创建工程
    • 登录
    • 历史消息
    • 发消息
  • 27_mybatis

    • Tio-Boot 整合 MyBatis
    • 使用配置类方式整合 MyBatis
    • 整合数据源
    • 使用 mybatis-plus 整合 tdengine
    • 整合 mybatis-plus
  • 28_mongodb

    • tio-boot 使用 mongo-java-driver 操作 mongodb
  • 29_elastic-search

    • Elasticsearch
    • JavaDB 整合 ElasticSearch
    • Elastic 工具类使用指南
    • Elastic-search 注意事项
    • ES 课程示例文档
  • 30_magic-script

    • tio-boot 与 magic-script 集成指南
  • 31_groovy

    • tio-boot 整合 Groovy
  • 32_firebase

    • 整合 google firebase
    • Firebase Storage
    • Firebase Authentication
    • 使用 Firebase Admin SDK 进行匿名用户管理与自定义状态标记
    • 导出用户
    • 注册回调
    • 登录注册
  • 33_文件存储

    • 文件上传数据表
    • 本地存储
    • 使用 AWS S3 存储文件并整合到 Tio-Boot 项目中
    • 存储文件到 腾讯 COS
  • 34_spider

    • jsoup
    • 爬取 z-lib.io 数据
    • 整合 WebMagic
    • WebMagic 示例:爬取学校课程数据
    • Playwright
    • Flexmark (Markdown 处理器)
    • tio-boot 整合 Playwright
    • 缓存网页数据
  • 36_integration_thirty_party

    • tio-boot 整合 okhttp
    • 整合 GrpahQL
    • 集成 Mailjet
    • 整合 ip2region
    • 整合 GeoLite 离线库
    • 整合 Lark 机器人指南
    • 集成 Lark Mail 实现邮件发送
    • Thymeleaf
    • Swagger
    • Clerk 验证
  • 37_dubbo

    • 概述
    • dubbo 2.6.0
    • dubbo 2.6.0 调用过程
    • dubbo 3.2.0
  • 38_spring

    • Spring Boot Web 整合 Tio Boot
    • spring-boot-starter-webflux 整合 tio-boot
    • Tio Boot 整合 Spring Boot Starter
    • Tio Boot 整合 Spring Boot Starter Data Redis 指南
  • 39_spring-cloud

    • tio-boot spring-cloud
  • 40_mysql

    • 使用 Docker 运行 MySQL
    • /zh/42_mysql/02.html
  • 41_postgresql

    • PostgreSQL 安装
    • PostgreSQL 主键自增
    • PostgreSQL 日期类型
    • Postgresql 金融类型
    • PostgreSQL 数组类型
    • PostgreSQL 全文检索
    • PostgreSQL 查询优化
    • 获取字段类型
    • PostgreSQL 向量
    • PostgreSQL 优化向量查询
    • PostgreSQL 其他
  • 43_oceanbase

    • 快速体验 OceanBase 社区版
    • 快速上手 OceanBase 数据库单机部署与管理
    • 诊断集群性能
    • 优化 SQL 性能指南
    • /zh/43_oceanbase/05.html
  • 50_media

    • JAVE 提取视频中的声音
    • Jave 提取视频中的图片
    • /zh/50_media/03.html
  • 51_asr

    • Whisper-JNI
  • 54_native-media

    • java-native-media
    • JNI 入门示例
    • mp3 拆分
    • mp4 转 mp3
    • 使用 libmp3lame 实现高质量 MP3 编码
    • Linux 编译
    • macOS 编译
    • 从 JAR 包中加载本地库文件
    • 支持的音频和视频格式
    • 任意格式转为 mp3
    • 通用格式转换
    • 通用格式拆分
    • 视频合并
    • VideoToHLS
    • split_video_to_hls 支持其他语言
    • 持久化 HLS 会话
  • 55_telegram4j

    • 数据库设计
    • /zh/55_telegram4j/02.html
    • 基于 MTProto 协议开发 Telegram 翻译机器人
    • 过滤旧消息
    • 保存机器人消息
    • 定时推送
    • 增加命令菜单
    • 使用 telegram-Client
    • 使用自定义 StoreLayout
    • 延迟测试
    • Reactor 错误处理
    • Telegram4J 常见错误处理指南
  • 56_telegram-bots

    • TelegramBots 入门指南
    • 使用工具库 telegram-bot-base 开发翻译机器人
  • 60_LLM

    • 简介
    • AI 问答
    • /zh/60_LLM/03.html
    • /zh/60_LLM/04.html
    • 增强检索(RAG)
    • 结构化数据检索
    • 搜索+AI
    • 集成第三方 API
    • 后置处理
    • 推荐问题生成
    • 连接代码执行器
    • 避免 GPT 混乱
    • /zh/60_LLM/13.html
  • 61_ai_agent

    • 数据库设计
    • 示例问题管理
    • 会话管理
    • 历史记录
    • 对接 Perplexity API
    • 意图识别与生成提示词
    • 智能问答模块设计与实现
    • 文件上传与解析文档
    • 翻译
    • 名人搜索功能实现
    • Ai studio gemini youbue 问答使用说明
    • 自建 YouTube 字幕问答系统
    • 自建 获取 youtube 字幕服务
    • 通用搜索
    • /zh/61_ai_agent/15.html
    • 16
    • 17
    • 18
    • 在 tio-boot 应用中整合 ai-agent
    • 16
  • 62_translator

    • 简介
  • 63_knowlege_base

    • 数据库设计
    • 用户登录实现
    • 模型管理
    • 知识库管理
    • 文档拆分
    • 片段向量
    • 命中测试
    • 文档管理
    • 片段管理
    • 问题管理
    • 应用管理
    • 向量检索
    • 推理问答
    • 问答模块
    • 统计分析
    • 用户管理
    • api 管理
    • 存储文件到 S3
    • 文档解析优化
    • 片段汇总
    • 段落分块与检索
    • 多文档解析
    • 对话日志
    • 检索性能优化
    • Milvus
    • 文档解析方案和费用对比
    • 离线运行向量模型
  • 64_ai-search

    • ai-search 项目简介
    • ai-search 数据库文档
    • ai-search SearxNG 搜索引擎
    • ai-search Jina Reader API
    • ai-search Jina Search API
    • ai-search 搜索、重排与读取内容
    • ai-search PDF 文件处理
    • ai-search 推理问答
    • Google Custom Search JSON API
    • ai-search 意图识别
    • ai-search 问题重写
    • ai-search 系统 API 接口 WebSocket 版本
    • ai-search 搜索代码实现 WebSocket 版本
    • ai-search 生成建议问
    • ai-search 生成问题标题
    • ai-search 历史记录
    • Discover API
    • 翻译
    • Tavily Search API 文档
    • 对接 Tavily Search
    • 火山引擎 DeepSeek
    • 对接 火山引擎 DeepSeek
    • ai-search 搜索代码实现 SSE 版本
    • jar 包部署
    • Docker 部署
    • 爬取一个静态网站的所有数据
    • 网页数据预处理
    • 网页数据检索与问答流程整合
  • 65_java-kit-server

    • Java 执行 python 代码
    • 通过大模型执行 Python 代码
    • MCP 协议
    • Cline 提示词
    • Cline 提示词-中文版本
  • 66_manim

    • Teach me anything - 基于大语言的知识点讲解视频生成系统
    • Manim 开发环境搭建
    • 生成场景提示词
    • 生成代码
    • 完整脚本示例
    • 语音合成系统
    • Fish.audio TTS 接口说明文档与 Java 客户端封装
    • 整合 fishaudio 到 java-uni-ai-server 项目
    • 执行 Python (Manim) 代码
    • 使用 SSE 流式传输生成进度的实现文档
    • 整合全流程完整文档
    • HLS 动态推流技术文档
    • manim 分场景生成代码
    • 分场景运行代码及流式播放支持
    • 分场景业务端完整实现流程
    • Maiim布局管理器
    • 仅仅生成场景代码
    • 使用 modal 运行 manim 代码
    • Python 使用 Modal GPU 加速渲染
    • Modal 平台 GPU 环境下运行 Manim
    • Modal Manim OpenGL 安装与使用
    • 优化 GPU 加速
    • 生成视频封面流程
    • Java 调用 manim 命令 执行代码 生成封面
    • Manim 图像生成服务客户端文档
    • manim render help
    • 显示 中文公式
    • manimgl
    • EGL
    • /zh/66_manim/30.html
    • /zh/66_manim/31.html
    • /zh/66_manim/32.html
    • /zh/66_manim/33.html
  • 68_java-llm-proxy

    • 使用tio-boot搭建openai 代理服务
  • 70_tio-boot-admin

    • 入门指南
    • 初始化数据
    • token 存储
    • 与前端集成
    • 文件上传
    • 网络请求
    • 图片管理
    • /zh/70_tio-boot-admin/08.html
    • Word 管理
    • PDF 管理
    • 文章管理
    • 富文本编辑器
  • 71_tio-boot

    • /zh/71_tio-boot/01.html
    • Swagger 整合到 Tio-Boot 中的指南
    • HTTP/1.1 Pipelining 性能测试报告
  • 73_tio-mail-wing

    • tio-mail-wing简介
    • 任务1:实现POP3系统
    • 使用 getmail 验证 tio-mail-wing POP3 服务
    • 任务2:实现 SMTP 服务
    • 数据库初始化文档
    • 用户管理
    • 邮件管理
    • 任务3:实现 SMTP 服务 数据库版本
    • 任务4:实现 POP3 服务(数据库版本)
    • IMAP 协议
    • 任务5:实现 IMAP 服务(数据库版本)
    • IMAP实现讲解
    • IMAP 手动测试脚本
  • 80_性能测试

    • 压力测试 - tio-http-serer
    • 压力测试 - tio-boot
    • 压力测试 - tio-boot-native
    • 压力测试 - netty-boot
    • 性能测试对比
    • TechEmpower FrameworkBenchmarks
    • 压力测试 - tio-boot 12 C 32G
  • 99_案例

    • 封装 IP 查询服务
    • tio-boot 案例 - 全局异常捕获与企业微信群通知
    • tio-boot 案例 - 文件上传和下载
    • tio-boot 案例 - 整合 ant design pro 增删改查
    • tio-boot 案例 - 流失响应
    • tio-boot 案例 - 增强检索
    • tio-boot 案例 - 整合 function call
    • tio-boot 案例 - 定时任务 监控 PostgreSQL、Redis 和 Elasticsearch
    • Tio-Boot 案例:使用 SQLite 整合到登录注册系统
    • tio-boot 案例 - 执行 shell 命令

PostgreSQL 日期类型

  • 1. 核心概念:数据库中的时间存储
    • 1.1. 数据类型:TIMESTAMP WITH TIME ZONE
    • 1.2. 创建示例表
  • 2. 后端(Java)数据处理
    • 2.1. Java 类型映射关系
    • 2.2. 存储数据:使用 OffsetDateTime
    • 2.3. 查询数据:理解 java.sql.Timestamp 的返回类型
    • 2.4. 处理常见输入格式
  • 3. 前后端参数传递的最佳实践
    • 3.1. 创建接口:前端传递毫秒时间戳
    • 3.2. 查询接口:后端返回毫秒时间戳
  • 总结

在现代 Web 应用开发中,正确处理日期和时间,尤其是涉及不同时区的场景,是一个至关重要的环节。本文将以 PostgreSQL 的 TIMESTAMP WITH TIME ZONE 类型为核心,详细介绍如何在 Java 后端以及前后端数据交互中进行高效、准确的处理。

1. 核心概念:数据库中的时间存储

在开始之前,我们首先要理解 PostgreSQL 是如何处理带时区的时间戳的。

1.1. 数据类型:TIMESTAMP WITH TIME ZONE

在 PostgreSQL 中,TIMESTAMP WITH TIME ZONE (或其别名 TIMESTAMPTZ) 是存储时间点的首选类型。它的一个关键特性是:它并不会在数据库中存储时区信息本身。

相反,它的工作机制如下:

  1. 当您插入一个带有时区信息的时间值时(例如 2024-07-08 15:00:00+08:00),PostgreSQL 会根据该时区将其转换为 UTC (Coordinated Universal Time) 时间。
  2. 数据库中实际存储的是这个 UTC 时间戳。
  3. 当您查询这个值时,PostgreSQL 会根据您当前数据库会话的 timezone 设置,将存储的 UTC 时间转换回该时区的时间进行显示。

这种机制确保了所有时间点在数据库中都以一个统一的标准(UTC)存储,从而避免了时区混乱。

1.2. 创建示例表

让我们在 PostgreSQL 中创建一个用于演示的 activity 表,其中包含开始和结束时间字段。

CREATE TABLE activity(
  id BIGINT NOT NULL,
  title VARCHAR(256),
  start_time TIMESTAMP WITH TIME ZONE,
  end_time TIMESTAMP WITH TIME ZONE,
  PRIMARY KEY (id)
);

2. 后端(Java)数据处理

在 Java 后端,我们推荐使用 Java 8 引入的 java.time API 来处理日期和时间,因为它提供了更强大、更清晰的时区支持。

2.1. Java 类型映射关系

PostgreSQL 类型推荐 Java 类型JDBC 默认映射类型
TIMESTAMP WITH TIME ZONEjava.time.OffsetDateTimejava.sql.Timestamp
  • OffsetDateTime: 现代 Java API 的一部分,它精确地表示了一个带有时区偏移量(如 +08:00)的日期和时间,非常适合与 TIMESTAMPTZ 对应。
  • java.sql.Timestamp: 一个遗留的 JDBC 类型,它不直接包含时区信息,在处理时容易引发混淆。

2.2. 存储数据:使用 OffsetDateTime

以下示例展示了如何使用 OffsetDateTime 创建一个时间点,并将其存入数据库。

package com.litongjava.website.service;

import java.time.Instant;
import java.time.OffsetDateTime;
import java.time.ZoneId;

import org.junit.Test;

import com.litongjava.db.activerecord.Db;
import com.litongjava.db.activerecord.Row;
import com.litongjava.tio.boot.postgresql.demo.config.DbConfig;
import com.litongjava.tio.utils.environment.EnvUtils;
import com.litongjava.tio.utils.snowflake.SnowflakeIdUtils;

import lombok.extern.slf4j.Slf4j;

@Slf4j
public class ActivityServiceTest {

  @Test
  public void addActivity() {
    // 1. 初始化数据库连接
    EnvUtils.load();
    new DbConfig().config();

    // 2. 获取当前服务器的系统时区
    ZoneId zoneId = ZoneId.systemDefault(); // 例如: Asia/Shanghai

    // 3. 创建一个基于当前时间的 OffsetDateTime 对象
    Instant startInstant = Instant.now();
    OffsetDateTime startTime = startInstant.atZone(zoneId).toOffsetDateTime();

    // 4. 创建一个24小时后的结束时间
    Instant endInstant = startInstant.plus(1, java.time.temporal.ChronoUnit.DAYS);
    OffsetDateTime endTime = endInstant.atZone(zoneId).toOffsetDateTime();

    // 5. 构建记录并保存
    Row row = new Row().set("id", SnowflakeIdUtils.id())
        //
        .set("title", "Test Activity").set("start_time", startTime).set("end_time", endTime);

    boolean save = Db.save("activity", row);
    log.info("save result:{}", save);
    // 底层执行的SQL: 
    // insert into "activity"("id", "title", "start_time", "end_time") values(?, ?, ?, ?)
  }
}

在这个例子中,即使我们的服务器时区是 Asia/Shanghai (+08:00),OffsetDateTime 对象也会被 JDBC 驱动正确解析,并以 UTC 形式存入 PostgreSQL。

2.3. 查询数据:理解 java.sql.Timestamp 的返回类型

当我们从数据库中查询数据时,一个常见的现象是,即使我们期望得到 OffsetDateTime,但 JDBC 驱动默认返回的却是 java.sql.Timestamp。

  @Test
  public void listActivity() {
    // 初始化数据库连接...
    
    // 查询所有记录
    List<Row> records = Db.findAll("activity");
    
    // 打印结果
    for (Row row : records) {
      Object startTimeObj = row.get("start_time");
      if (startTimeObj != null) {
        log.info("Key: start_time, Value: {}, Class: {}", startTimeObj, startTimeObj.getClass().getName());
      }
    }
  }

输出结果示例:

Key: start_time, Value: 2025-03-15 08:51:53.685, Class: java.sql.Timestamp

这是框架或驱动的问题吗?

不是问题,而是标准的默认行为。 大多数 JDBC 驱动为了保持向后兼容性,会将数据库的 TIMESTAMP 相关类型默认映射为 java.sql.Timestamp。

最佳实践:在应用程序中接收到 java.sql.Timestamp 对象后,应立即将其转换为现代的 OffsetDateTime 或 ZonedDateTime 对象,以便进行更安全、更明确的时区相关操作。

Timestamp ts = row.getTimestamp("start_time");
if (ts != null) {
  // 转换为 OffsetDateTime,并假设数据库连接返回的是系统默认时区的时间
  OffsetDateTime startTime = ts.toInstant().atOffset(ZoneOffset.UTC); 
  // 或者转换为特定时区的时间
  // ZonedDateTime zonedStartTime = ts.toInstant().atZone(ZoneId.of("Asia/Shanghai"));
}

新增getOffsetDateTime

OffsetDateTime startTime = row.getOffsetDateTime("start_time");

2.4. 处理常见输入格式

在实际业务中,后端服务经常需要处理来自前端或其他服务的不同格式的时间数据。

场景一:处理字符串(如 2025-03-01 00:28:03)

当收到一个不含时区信息的日期字符串时,直接使用 Timestamp.valueOf() 会将其解析为服务器默认时区的时间点。

  @Test
  public void testParseString() {
    // 初始化数据库连接...
    
    String timeString = "2025-03-01 00:28:03";
    
    // Timestamp.valueOf() 会使用JVM的默认时区来解析这个字符串
    Timestamp timestamp = Timestamp.valueOf(timeString);
    
    Row row = Row.by("id", SnowflakeIdUtils.id()).set("start_time", timestamp);
    Db.save("activity", row);
  }

注意:这种方式存在歧义,因为字符串本身没有时区信息。如果可能,应要求输入方提供带有时区或偏移量(如 ISO 8601 格式 2025-03-01T00:28:03+08:00)的字符串。

场景二:处理长整型时间戳(如 1743157717000)

使用从 Epoch (1970-01-01 00:00:00 UTC) 开始的毫秒数来表示时间,是一种跨平台、无歧义的通用方法。

  @Test
  public void testParseLongTimestamp() {
    // 初始化数据库连接...
    
    // 毫秒时间戳 (通常来自前端的 Date.now())
    long timeMillis = 1743157717000L;
    
    // 将毫秒时间戳转换为 Timestamp 对象
    Timestamp timestamp = new Timestamp(timeMillis);
    
    Row row = Row.by("id", SnowflakeIdUtils.id()).set("start_time", timestamp);
    Db.save("activity", row);
  }

这种方式非常可靠,因为它直接代表了一个精确的 UTC 时间点。

3. 前后端参数传递的最佳实践

为了确保时间数据在前端和后端之间传递的准确性,推荐使用 毫秒级时间戳(Long) 作为标准格式。

3.1. 创建接口:前端传递毫秒时间戳

前端通过 API 创建活动时,应将用户选择的日期时间转换为毫秒时间戳后发送给后端。

前端请求体 (JSON):

{
  "title": "New Year's Eve Party",
  "start_time": 1735660800000,  // 对应 UTC 2025-01-01 00:00:00
  "end_time": 1735675200000     // 对应 UTC 2025-01-01 04:00:00
}

在 JavaScript 中,可以通过 date.getTime() 或 Date.now() 轻松获取。

后端处理: 后端接收到 long 类型的 start_time 和 end_time 后,可以直接按 2.4. 场景二 的方式将其转换为 Timestamp 或 OffsetDateTime 对象并存入数据库。

3.2. 查询接口:后端返回毫秒时间戳

当后端向前端返回数据时,同样应将数据库中的时间字段转换为毫秒时间戳。

后端响应体 (JSON):

{
  "code": 1,
  "ok": true,
  "msg": "Success",
  "data": {
    "id": "399895750549155840",
    "title": "New Year's Eve Party",
    "start_time": 1735660800000,
    "end_time": 1735675200000
  }
}

为什么推荐使用毫秒时间戳?

  • 无歧义:它是一个绝对值,与时区无关,代表了 UTC 时间线上的一个精确点。
  • 易于处理:几乎所有编程语言和平台都原生支持从毫秒时间戳创建日期对象。前端 JavaScript 可以直接使用 new Date(timestamp) 来创建本地时区的日期对象并进行展示。
  • 避免格式化问题:避免了在字符串格式化和解析过程中可能出现的时区错误。

总结

  1. 数据库层:使用 TIMESTAMP WITH TIME ZONE (TIMESTAMPTZ) 类型,它会将所有时间自动转换为 UTC 进行存储,确保数据的一致性。
  2. Java 后端:
    • 优先使用 java.time.OffsetDateTime 或 ZonedDateTime 进行业务逻辑处理。
    • 警惕 JDBC 驱动默认返回 java.sql.Timestamp 的行为,并及时将其转换为现代日期时间对象。
    • 能够灵活处理字符串和长整型等不同格式的时间输入。
  3. 前后端交互:强烈推荐使用 毫秒级时间戳(Long) 作为数据交换格式,它简单、可靠且无歧义,是处理跨时区应用的最佳实践。
Edit this page
Last Updated:
Contributors: Tong Li
Prev
PostgreSQL 主键自增
Next
Postgresql 金融类型