Python uuid.UUID.time 怎样读取 UUIDv7 的毫秒时间戳

如果你拿到的是 Python 3.14 生成的 UUIDv7，读取创建时间不需要自己拆二进制字段：先确认 u.version == 7，再取 u.time。这个属性对 UUIDv7 返回 Unix 时间戳的毫秒整数，转换时除以 1000，并显式指定时区即可。

官方文档：https://docs.python.org/3/library/uuid.html

先确认 Python 版本和 UUID 版本

uuid.uuid7() 属于 Python 3.14 新增 API。旧解释器即使安装了同名第三方包，也不能把第三方行为当成标准库行为。文章中的代码假设解释器版本至少为 3.14，并把 UUID 版本打印出来，便于排查“属性存在但含义不对”的问题。

import sys
import uuid

# 先确认标准库能力和当前对象的 UUID 版本。
if sys.version_info 

这里的版本检查不是多余的装饰。UUID 对象的 version 是布局语义的入口：v7 的时间字段是毫秒，v1 和 v6 使用的是自公历起点计算的 100 纳秒间隔，v4 则是随机 UUID。相同的属性名不能掩盖不同的单位。

用 UUID.time 读取毫秒并转换为 datetime

UUIDv7 的 u.time 是整数，单位是毫秒。最小可用写法如下；使用 UTC 进行转换，再按展示需要转换到业务时区，能把存储和展示的责任分开。

from datetime import datetime, timezone
import uuid

u = uuid.uuid7()
milliseconds = u.time

# UUID.time 是 Unix epoch 起的毫秒数，datetime 需要秒数。
created_at = datetime.fromtimestamp(milliseconds / 1000, tz=timezone.utc)
print(milliseconds)
print(created_at.isoformat())

不要直接把 u.time 传给 fromtimestamp()，否则会把毫秒当成秒，得到远未来的错误日期。也不要省略 tz 后再把结果标成 UTC；无时区的 datetime 无法表达它究竟来自哪个时区。

解析外部 UUID 时先挡住版本误用

实际项目通常不是现场生成 UUID，而是从请求、消息或数据库读出字符串。此时先用 uuid.UUID() 解析，再把 v7 判断放在取时间之前。这样可以把格式错误和版本不适用分成两类处理。

from datetime import datetime, timezone
import uuid

def uuid7_datetime(text: str) -> datetime:
    # 解析失败交给调用方处理，避免把非法标识静默当成当前时间。
    value = uuid.UUID(text)
    if value.version != 7:
        raise ValueError("只有 UUIDv7 才能按毫秒时间字段读取")

    # 返回带 UTC 时区的结果，便于跨服务序列化和比较。
    return datetime.fromtimestamp(value.time / 1000, tz=timezone.utc)

print(uuid7_datetime(str(uuid.uuid7())).isoformat())

如果业务既接受 v4 又接受 v7，建议返回两个明确结果：v4 只作为唯一标识，时间字段记为不可用；v7 才填充 created_at。不要为了“让接口总有时间”而用接收时间代替 UUID 创建时间，这会混淆事件发生和消息到达。

落库和排序时的几个边界

UUIDv7 适合提供大致按时间排序的标识，但它不是完整的业务审计时间。官方实现为跨平台的子毫秒精度差异嵌入了毫秒时间戳和保证同一毫秒内单调性的计数器；这能改善同一进程内的排序体验，却不能替代服务端明确记录的 created_at。

• 需要精确事件时间时，单独保存带时区的 datetime 或数据库时间列。
• 比较时间先统一到 UTC；展示给用户时再转为本地时区。
• 只依据 UUID.time 做分页时，仍要配合唯一的 UUID 作为并列排序键。
• 跨语言生成 UUIDv7 时，确认对方遵循 RFC 9562，并确认传输没有把字符串截断。

常见问题

UUIDv4 能直接读取创建时间吗？

不能。v4 的核心是随机字段，没有可解释的创建时间；应使用独立时间列或消息元数据。

为什么要把毫秒除以 1000？

因为 UUID.time 对 v7 的单位是毫秒，而 datetime.fromtimestamp() 的输入单位是秒。

能不能直接用 UUID 字符串排序当作时间排序？

UUIDv7 的布局支持时间有序特征，但业务分页仍应明确排序字段和并列规则，不能把字符串排序当成审计时间证明。