时间戳验证秒级与毫秒级的区分与应用引言三个真实事故接口签名对不上服务端用 Java 生成签名客户端用 PHP 验签。Java 的System.currentTimeMillis()返回 13 位毫秒PHP 的time()返回 10 位秒两边拿着不同长度的时间戳各自验签永远对不上。订单时间倒退 52 年前端 JSDate.now()返回 13 位毫秒后端接口文档写的是秒级时间戳数据入库时被当成秒直接存进BIGINT查询时转时间一看——1970 年。缓存刚设置就过期RedisSETEX的过期时间被传成了毫秒而 Redis 要的是秒缓存有效期直接缩水 1000 倍。这些事故的根源只有一个Unix 时间戳是数字但秒级和毫秒级是两种不同的东西。数字本身不会告诉你它的单位混用了也不会报错——只是结果错得离谱。本文先讲透秒级与毫秒级的本质区别再对照 ValidX 的Timestamp注解源码与测试用例给出如何在一进系统就把单位钉死的完整方案。说明文中 ValidX 相关内容对照 v1.2.0 源码Timestamp注解、TimestampValidator与测试用例TimestampValidatorTest核实表格行为均可复现。一、Unix 时间戳基础1.1 定义Unix 时间戳是从1970-01-01 00:00:00 UTC起经过的时间计数。它是个绝对数值与任何时区无关——同一时刻北京、纽约、伦敦拿到的都是同一个时间戳。1.2 单位与位数单位当前时代位数例子2023-11-14 22:13:20 UTC秒10 位1700000000毫秒13 位1700000000000微秒16 位1700000000000000纳秒19 位1700000000000000000位数判断法只在当前时代成立10 位 秒、13 位 毫秒。10 位秒级时间戳的上限是9999999999对应2286-11-20——在那之前位数判断法都有效。1.3 各语言/平台的默认单位混乱的源头语言 / 平台常用取时间方式单位位数JavaSystem.currentTimeMillis()毫秒13JavaInstant.now().getEpochSecond()秒10PHPtime()秒10JavaScriptDate.now()毫秒13Pythontime.time()秒浮点10.xxxGotime.Now().Unix()/.UnixMilli()秒 / 毫秒10 / 13MySQLUNIX_TIMESTAMP()秒10RedisTTL/SETEX过期时间秒10同一个当前时间不同技术栈拿到的是不同单位的数字——这就是跨端集成时时间戳必出问题的根本原因。1.4 2038 问题32 位有符号整数能表示的最大秒级时间戳是2147483647对应2038-01-19 03:14:07 UTC。之后会溢出。虽然 Java 的long是 64 位没有此问题但存量系统C 程序、嵌入式、老数据库若仍用 32 位int存秒2038 年就是它们的千年虫。二、秒与毫秒为什么会混数量级灾难2.1 混淆的两个方向错误方向结果具体表现毫秒当成秒时间放大 1000 倍当前时间戳1700000000000被当秒 → 公元 55879 年远超范围秒当成毫秒时间缩小 1000 倍1700000000被当毫秒 →1970-01-20 17:33:20比真实时间晚了 52 年第二种尤其隐蔽结果是合法的时间1970 年 1 月不像第一种会明显爆掉。订单时间倒退回 1970 年、统计口径全乱、对账永远差 1000 倍都是它。2.2 典型事故场景接口签名/防重放timestamp字段单位不统一 → 签名永远验不过或重放防护形同虚设支付回调回调里的time是秒你按毫秒存 → 对账对不上缓存过期SETEX key 300000传了毫秒 3000005 分钟 × 60 × 1000 的数值却按秒解释→ 缓存 3.5 天才过期数据库迁移datetime转BIGINT时单位没统一 → 历史数据全部错位。三、Timestamp 注解深度解析3.1 注解定义Timestamp// 秒或毫秒均可privateStringcreateTime;Timestamp(unitTimestampUnit.SECONDS)// 仅秒级10 位privateStringcreateTimeSec;Timestamp(unitTimestampUnit.MILLISECONDS)// 仅毫秒级13 位privateStringcreateTimeMs;unit有三种取值默认ANYTimestampUnit接受范围典型场景SECONDS10 位秒缓存过期、接口签名、Redis TTLMILLISECONDS13 位毫秒业务时间、订单时间、日志时间ANY10 位或 13 位第三方数据格式不确定时3.2 双类型支持String 与 Long注解同时支持String和LongInteger等其他Number也会转成Long处理TimestampprivateStringcreateTimeStr;// 1700000000 / 1700000000000Timestamp(unitTimestampUnit.MILLISECONDS)privateLongcreateTimeLong;// 1700000000000L3.3 验证规则两层把关String 类型——正则 位数 范围三连正则^\d$要求纯数字字母、空格、小数点、负数符号全部拒绝位数检查SECONDS必须 10 位、MILLISECONDS必须 13 位、ANY两者均可位数对了再Long.parseLong验证数值范围上限秒9999999999、毫秒9999999999999。Long 类型——直接范围判断unit通过条件SECONDS0 ≤ value ≤ 9999999999MILLISECONDS9999999999 value ≤ 9999999999999ANY0 ≤ value ≤ 9999999999999注意 Long 的MILLISECONDS判定必须大于秒的上限 9999999999用数值范围区分单位而不是位数。3.4 实测行为表来自项目测试用例输入ANYSECONDSMILLISECONDS170000000010 位秒✅✅❌170000000000013 位毫秒✅❌✅0000000000最小秒✅✅❌9999999999最大秒✅✅❌1700000000011 位❌❌❌1700000000000014 位❌❌❌1700000abc含字母❌❌❌ 1700000000 含空格❌❌❌1700000000.0小数❌❌❌-1700000000负数❌❌❌1700000000LLong 秒✅✅❌1700000000000LLong 毫秒✅❌✅-1LLong 负数❌❌❌null/✅ 放行✅ 放行✅ 放行与 ValidX 其他格式注解一致null和空串放行必填请叠加NotNull/NotEmpty。四、链式 API 用法动态数据Map、JSON、单个参数用链式方式就地校验ValidXvalidatorValidX.init().field(时间戳).isTimestamp(1700000000);// 默认 ANYValidXvalidator2ValidX.init().field(创建时间).isTimestamp(1700000000000,Timestamp.TimestampUnit.MILLISECONDS);// 指定毫秒ValidXvalidator3ValidX.init().field(过期时间).isTimestamp(1700000000L,Timestamp.TimestampUnit.SECONDS);// 指定秒if(!validator.isValid()){thrownewBusinessException(validator.getErrorMessage());}方法签名publicValidXisTimestamp(Objectvalue);// ANYpublicValidXisTimestamp(Objectvalue,Timestamp.TimestampUnitunit);// 指定单位五、秒级与毫秒级如何选择与转换5.1 选择标准看精度需求需求推荐单位理由接口签名、防重放秒精度到秒足够且 10 位数更直观、跨端更不容易混缓存过期、TTL秒Redis 等组件原生用秒订单/业务时间毫秒同一秒内多笔操作需要区分先后日志、埋点毫秒或微秒定位问题需要高精度时序跨系统传输统一约定并校验单位本身无优劣混用才是灾难5.2 转换公式与代码秒 → 毫秒× 1000 毫秒 → 秒÷ 1000整数除法// 当前时间longsecondsInstant.now().getEpochSecond();// 10 位longmillisSystem.currentTimeMillis();// 13 位// 互相转换longmillisFromSecseconds*1000;longsecFromMillismillis/1000;// 毫秒部分被丢弃// 时间戳 → 可读时间注意指定时区LocalDateTimedtLocalDateTime.ofInstant(Instant.ofEpochMilli(millis),ZoneId.systemDefault());5.3 时区时间戳的天然优势时间戳是绝对时刻本身不含时区。同一个1700000000在北京显示2023-11-15 06:13:20在纽约显示2023-11-14 17:13:20——都是对的因为它是同一时刻。跨时区系统交换时间用时间戳而不是yyyy-MM-dd HH:mm:ss字符串可以从根上消灭时区 bug。字符串时间带时区规则最容易出错。5.4 数据库存储列类型用BIGINT禁止用INT32 位存秒有 2038 问题全表统一单位要么全秒、要么全毫秒用校验在入口钉死与datetime混用要小心datetime带时区语义取决于数据库会话时区时间戳不带两者互转时先对齐时区。六、电商场景落地6.1 订单创建接口钉死毫秒级publicclassOrderCreateDTO{NotBlankprivateStringorderNo;NotNullTimestamp(unitTimestamp.TimestampUnit.MILLISECONDS,message下单时间必须是毫秒级时间戳)privateLongcreateTime;}前端Date.now()传 13 位毫秒后端严格校验——前端传秒级或 11 位直接 400单位问题在入口解决而不是等数据进库后错乱。6.2 支付回调验签 防重放回调参数里的timestamp用于防重放用秒级 时间窗口判断publicvoidhandlePayCallback(PayNotifyDTOnotify){// 1. 校验时间戳格式秒级ValidXvalidatorValidX.init().field(回调时间戳).isTimestamp(notify.getTimestamp(),Timestamp.TimestampUnit.SECONDS);if(!validator.isValid()){thrownewBusinessException(回调时间戳格式错误);}// 2. 防重放与服务器时间偏差超过 5 分钟拒绝longnowInstant.now().getEpochSecond();if(Math.abs(now-notify.getTimestamp())300){thrownewBusinessException(回调时间戳过期可能存在重放攻击);}// 3. 验签签名中通常也包含 timestamp...}6.3 优惠券有效期秒级 范围判断publicclassCouponDTO{NotNullTimestamp(unitTimestampUnit.SECONDS,message生效时间必须是秒级时间戳)privateLongstartTime;NotNullTimestamp(unitTimestampUnit.SECONDS,message失效时间必须是秒级时间戳)privateLongendTime;}6.4 秒杀/限流时间窗口// 时间窗口按秒对齐避免毫秒抖动导致窗口错位longwindowInstant.now().getEpochSecond()/10;// 每 10 秒一个窗口redis.incr(seckill:window:window);七、最佳实践清单入口钉死单位所有对外接口的timestamp字段一律用Timestamp(unit ...)校验接收方定义清楚只要秒或只要毫秒跨端文档写明单位接口文档里时间戳必须标注秒级10 位还是毫秒级13 位这是大多数混用的根源优先用秒级做跨系统传输位数少、直观、与 Redis/MySQL 等组件原生对齐业务精度不足时再升级毫秒数据库用BIGINT且全表统一禁止INT2038 问题单位全表一致混用时加迁移脚本一次性对齐转换留痕秒↔毫秒转换只发生在明确定义的边界如 Controller/Service 转换层别散落在业务代码里时间戳不带时区传输首选跨时区系统交换时间用时间戳别用yyyy-MM-dd HH:mm:ss字符串必填显式声明Timestamp放行null/空串必填加NotNull/NotEmpty防重放配时间窗口签名校验时用|now - timestamp|限窗口并拒绝未来时间戳。总结Unix 时间戳是绝对时刻的数字秒10 位与毫秒13 位是两种不同单位混用不会报错但结果错得离谱时间倒退 52 年 / 放大 1000 倍不同技术栈默认单位不同Java 毫秒、PHP 秒、JS 毫秒、MySQL 秒跨端集成必须约定并校验单位ValidXTimestamp支持 String/Long 双类型unit三种取值SECONDS/MILLISECONDS/ANY用正则 位数 范围三层把关负数、非数字、位数不对一律拒绝单位本身无优劣统一 校验才是关键入口钉死单位数据库BIGINT全表一致跨端文档写明时间戳无时区跨时区系统传输用时间戳从根上消灭时区 bug。ValidX 是基于 Jakarta Bean Validation 规范的 Java 验证库注解与链式 API 双模式内置 100 验证规则其中时间类注解 10 种。项目地址github.com/vipxieliang/validx
时间戳验证秒级与毫秒级的区分与应用引言三个真实事故接口签名对不上服务端用 Java 生成签名客户端用 PHP 验签。Java 的System.currentTimeMillis()返回 13 位毫秒PHP 的time()返回 10 位秒两边拿着不同长度的时间戳各自验签永远对不上。订单时间倒退 52 年前端 JSDate.now()返回 13 位毫秒后端接口文档写的是秒级时间戳数据入库时被当成秒直接存进BIGINT查询时转时间一看——1970 年。缓存刚设置就过期RedisSETEX的过期时间被传成了毫秒而 Redis 要的是秒缓存有效期直接缩水 1000 倍。这些事故的根源只有一个Unix 时间戳是数字但秒级和毫秒级是两种不同的东西。数字本身不会告诉你它的单位混用了也不会报错——只是结果错得离谱。本文先讲透秒级与毫秒级的本质区别再对照 ValidX 的Timestamp注解源码与测试用例给出如何在一进系统就把单位钉死的完整方案。说明文中 ValidX 相关内容对照 v1.2.0 源码Timestamp注解、TimestampValidator与测试用例TimestampValidatorTest核实表格行为均可复现。一、Unix 时间戳基础1.1 定义Unix 时间戳是从1970-01-01 00:00:00 UTC起经过的时间计数。它是个绝对数值与任何时区无关——同一时刻北京、纽约、伦敦拿到的都是同一个时间戳。1.2 单位与位数单位当前时代位数例子2023-11-14 22:13:20 UTC秒10 位1700000000毫秒13 位1700000000000微秒16 位1700000000000000纳秒19 位1700000000000000000位数判断法只在当前时代成立10 位 秒、13 位 毫秒。10 位秒级时间戳的上限是9999999999对应2286-11-20——在那之前位数判断法都有效。1.3 各语言/平台的默认单位混乱的源头语言 / 平台常用取时间方式单位位数JavaSystem.currentTimeMillis()毫秒13JavaInstant.now().getEpochSecond()秒10PHPtime()秒10JavaScriptDate.now()毫秒13Pythontime.time()秒浮点10.xxxGotime.Now().Unix()/.UnixMilli()秒 / 毫秒10 / 13MySQLUNIX_TIMESTAMP()秒10RedisTTL/SETEX过期时间秒10同一个当前时间不同技术栈拿到的是不同单位的数字——这就是跨端集成时时间戳必出问题的根本原因。1.4 2038 问题32 位有符号整数能表示的最大秒级时间戳是2147483647对应2038-01-19 03:14:07 UTC。之后会溢出。虽然 Java 的long是 64 位没有此问题但存量系统C 程序、嵌入式、老数据库若仍用 32 位int存秒2038 年就是它们的千年虫。二、秒与毫秒为什么会混数量级灾难2.1 混淆的两个方向错误方向结果具体表现毫秒当成秒时间放大 1000 倍当前时间戳1700000000000被当秒 → 公元 55879 年远超范围秒当成毫秒时间缩小 1000 倍1700000000被当毫秒 →1970-01-20 17:33:20比真实时间晚了 52 年第二种尤其隐蔽结果是合法的时间1970 年 1 月不像第一种会明显爆掉。订单时间倒退回 1970 年、统计口径全乱、对账永远差 1000 倍都是它。2.2 典型事故场景接口签名/防重放timestamp字段单位不统一 → 签名永远验不过或重放防护形同虚设支付回调回调里的time是秒你按毫秒存 → 对账对不上缓存过期SETEX key 300000传了毫秒 3000005 分钟 × 60 × 1000 的数值却按秒解释→ 缓存 3.5 天才过期数据库迁移datetime转BIGINT时单位没统一 → 历史数据全部错位。三、Timestamp 注解深度解析3.1 注解定义Timestamp// 秒或毫秒均可privateStringcreateTime;Timestamp(unitTimestampUnit.SECONDS)// 仅秒级10 位privateStringcreateTimeSec;Timestamp(unitTimestampUnit.MILLISECONDS)// 仅毫秒级13 位privateStringcreateTimeMs;unit有三种取值默认ANYTimestampUnit接受范围典型场景SECONDS10 位秒缓存过期、接口签名、Redis TTLMILLISECONDS13 位毫秒业务时间、订单时间、日志时间ANY10 位或 13 位第三方数据格式不确定时3.2 双类型支持String 与 Long注解同时支持String和LongInteger等其他Number也会转成Long处理TimestampprivateStringcreateTimeStr;// 1700000000 / 1700000000000Timestamp(unitTimestampUnit.MILLISECONDS)privateLongcreateTimeLong;// 1700000000000L3.3 验证规则两层把关String 类型——正则 位数 范围三连正则^\d$要求纯数字字母、空格、小数点、负数符号全部拒绝位数检查SECONDS必须 10 位、MILLISECONDS必须 13 位、ANY两者均可位数对了再Long.parseLong验证数值范围上限秒9999999999、毫秒9999999999999。Long 类型——直接范围判断unit通过条件SECONDS0 ≤ value ≤ 9999999999MILLISECONDS9999999999 value ≤ 9999999999999ANY0 ≤ value ≤ 9999999999999注意 Long 的MILLISECONDS判定必须大于秒的上限 9999999999用数值范围区分单位而不是位数。3.4 实测行为表来自项目测试用例输入ANYSECONDSMILLISECONDS170000000010 位秒✅✅❌170000000000013 位毫秒✅❌✅0000000000最小秒✅✅❌9999999999最大秒✅✅❌1700000000011 位❌❌❌1700000000000014 位❌❌❌1700000abc含字母❌❌❌ 1700000000 含空格❌❌❌1700000000.0小数❌❌❌-1700000000负数❌❌❌1700000000LLong 秒✅✅❌1700000000000LLong 毫秒✅❌✅-1LLong 负数❌❌❌null/✅ 放行✅ 放行✅ 放行与 ValidX 其他格式注解一致null和空串放行必填请叠加NotNull/NotEmpty。四、链式 API 用法动态数据Map、JSON、单个参数用链式方式就地校验ValidXvalidatorValidX.init().field(时间戳).isTimestamp(1700000000);// 默认 ANYValidXvalidator2ValidX.init().field(创建时间).isTimestamp(1700000000000,Timestamp.TimestampUnit.MILLISECONDS);// 指定毫秒ValidXvalidator3ValidX.init().field(过期时间).isTimestamp(1700000000L,Timestamp.TimestampUnit.SECONDS);// 指定秒if(!validator.isValid()){thrownewBusinessException(validator.getErrorMessage());}方法签名publicValidXisTimestamp(Objectvalue);// ANYpublicValidXisTimestamp(Objectvalue,Timestamp.TimestampUnitunit);// 指定单位五、秒级与毫秒级如何选择与转换5.1 选择标准看精度需求需求推荐单位理由接口签名、防重放秒精度到秒足够且 10 位数更直观、跨端更不容易混缓存过期、TTL秒Redis 等组件原生用秒订单/业务时间毫秒同一秒内多笔操作需要区分先后日志、埋点毫秒或微秒定位问题需要高精度时序跨系统传输统一约定并校验单位本身无优劣混用才是灾难5.2 转换公式与代码秒 → 毫秒× 1000 毫秒 → 秒÷ 1000整数除法// 当前时间longsecondsInstant.now().getEpochSecond();// 10 位longmillisSystem.currentTimeMillis();// 13 位// 互相转换longmillisFromSecseconds*1000;longsecFromMillismillis/1000;// 毫秒部分被丢弃// 时间戳 → 可读时间注意指定时区LocalDateTimedtLocalDateTime.ofInstant(Instant.ofEpochMilli(millis),ZoneId.systemDefault());5.3 时区时间戳的天然优势时间戳是绝对时刻本身不含时区。同一个1700000000在北京显示2023-11-15 06:13:20在纽约显示2023-11-14 17:13:20——都是对的因为它是同一时刻。跨时区系统交换时间用时间戳而不是yyyy-MM-dd HH:mm:ss字符串可以从根上消灭时区 bug。字符串时间带时区规则最容易出错。5.4 数据库存储列类型用BIGINT禁止用INT32 位存秒有 2038 问题全表统一单位要么全秒、要么全毫秒用校验在入口钉死与datetime混用要小心datetime带时区语义取决于数据库会话时区时间戳不带两者互转时先对齐时区。六、电商场景落地6.1 订单创建接口钉死毫秒级publicclassOrderCreateDTO{NotBlankprivateStringorderNo;NotNullTimestamp(unitTimestamp.TimestampUnit.MILLISECONDS,message下单时间必须是毫秒级时间戳)privateLongcreateTime;}前端Date.now()传 13 位毫秒后端严格校验——前端传秒级或 11 位直接 400单位问题在入口解决而不是等数据进库后错乱。6.2 支付回调验签 防重放回调参数里的timestamp用于防重放用秒级 时间窗口判断publicvoidhandlePayCallback(PayNotifyDTOnotify){// 1. 校验时间戳格式秒级ValidXvalidatorValidX.init().field(回调时间戳).isTimestamp(notify.getTimestamp(),Timestamp.TimestampUnit.SECONDS);if(!validator.isValid()){thrownewBusinessException(回调时间戳格式错误);}// 2. 防重放与服务器时间偏差超过 5 分钟拒绝longnowInstant.now().getEpochSecond();if(Math.abs(now-notify.getTimestamp())300){thrownewBusinessException(回调时间戳过期可能存在重放攻击);}// 3. 验签签名中通常也包含 timestamp...}6.3 优惠券有效期秒级 范围判断publicclassCouponDTO{NotNullTimestamp(unitTimestampUnit.SECONDS,message生效时间必须是秒级时间戳)privateLongstartTime;NotNullTimestamp(unitTimestampUnit.SECONDS,message失效时间必须是秒级时间戳)privateLongendTime;}6.4 秒杀/限流时间窗口// 时间窗口按秒对齐避免毫秒抖动导致窗口错位longwindowInstant.now().getEpochSecond()/10;// 每 10 秒一个窗口redis.incr(seckill:window:window);七、最佳实践清单入口钉死单位所有对外接口的timestamp字段一律用Timestamp(unit ...)校验接收方定义清楚只要秒或只要毫秒跨端文档写明单位接口文档里时间戳必须标注秒级10 位还是毫秒级13 位这是大多数混用的根源优先用秒级做跨系统传输位数少、直观、与 Redis/MySQL 等组件原生对齐业务精度不足时再升级毫秒数据库用BIGINT且全表统一禁止INT2038 问题单位全表一致混用时加迁移脚本一次性对齐转换留痕秒↔毫秒转换只发生在明确定义的边界如 Controller/Service 转换层别散落在业务代码里时间戳不带时区传输首选跨时区系统交换时间用时间戳别用yyyy-MM-dd HH:mm:ss字符串必填显式声明Timestamp放行null/空串必填加NotNull/NotEmpty防重放配时间窗口签名校验时用|now - timestamp|限窗口并拒绝未来时间戳。总结Unix 时间戳是绝对时刻的数字秒10 位与毫秒13 位是两种不同单位混用不会报错但结果错得离谱时间倒退 52 年 / 放大 1000 倍不同技术栈默认单位不同Java 毫秒、PHP 秒、JS 毫秒、MySQL 秒跨端集成必须约定并校验单位ValidXTimestamp支持 String/Long 双类型unit三种取值SECONDS/MILLISECONDS/ANY用正则 位数 范围三层把关负数、非数字、位数不对一律拒绝单位本身无优劣统一 校验才是关键入口钉死单位数据库BIGINT全表一致跨端文档写明时间戳无时区跨时区系统传输用时间戳从根上消灭时区 bug。ValidX 是基于 Jakarta Bean Validation 规范的 Java 验证库注解与链式 API 双模式内置 100 验证规则其中时间类注解 10 种。项目地址github.com/vipxieliang/validx
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
