日期与时间

日期与时间数据回答的是几种不同问题。 时间点（instant） 标识时间线上的一个位置。民用时间（civil time）提供2026-11-01 01:30这样的日历字段， 时区（time zone） 则提供把这些字段映射到时间线的规则。

时长回答经过了多久。日历运算回答的是另一个问题，例如“当地明天的同一时刻”或“下个月最后一天”。这些含义在普通日期恰好一致，所以错误设计可能一直显得正确，直到月末或时钟切换进入生产环境。

Unix纪元（Unix epoch） 为时间戳系统提供共同的数值起点。只要单位和时间尺度明确，从该起点开始的计数就能标识时间点。但这个数字不会记住来源时区、用户输入的日历说法，也不会说明规则变化后日程是否应保留当地钟表时间。

审计日志、预订系统、令牌过期、账期、重复任务、年龄判断、遥测和用户界面都会遇到这些区别。已经完成的付款通常需要时间点。生日通常只需要日历日期，不带时间和时区。

每天09:00开门的商店需要当地时钟字段与指定时区。必须在五秒后超时的请求需要时长与单调时钟。一个泛化的timestamp字段无法同时说明这四种契约。

选择表示形式之前，先说清领域值：

这种区分能避免有损往返。如果把生日变成UTC午夜，在UTC以西展示时可能得到前一天。如果纽约预约只保存-04:00，这个值既无法应用冬季规则，也无法采用以后的时区数据库变更。

真正困难的不是格式化，而是决定转换上下文由谁提供，以及本地字段有歧义或无效时该怎么办。这个策略应属于数据契约，不能藏在碰巧负责解析的辅助函数里。

时间点与民用字段

时间点本身没有年、月、小时或星期几。这些字段是通过日历和时区规则集得到的投影视图。UTC是一种实用的零偏移投影，但UTC表示仍是时间点的显示方式，不是时间点中多存了一份状态。

民用时间的方向相反。年、月、日、时、分等字段描述日历和钟表显示的内容。要把它们解析为时间点，还需要日历、指定时区或固定偏移；遇到切换边界时，有时还要明确选择。

两个方向的行为不同：

把时间点投影到时区只会产生一个结果，因为时间点已经确定应采用哪条规则。本地字段则可能解析出零个、一个或两个候选时间点。如果API只暴露local_time与zone，却不说明解析策略，业务决定就仍是隐式的。

偏移与指定时区

+08:00这样的偏移只描述与UTC的一个数值关系。它附在完整本地日期时间字段上时，足以标识一个时间点，却不能描述过去或未来的规则变化。

Europe/Paris或America/New_York这样的IANA时区名标识一套持续维护的历史和规则。具体偏移取决于所考察的时间点。政府可以修改规则，所以已部署应用也会依赖某个时区数据库版本。

CST这样的缩写不适合作为交换标识符。不同地区会复用同一组字母，短标签也可能随季节改变。需要地区规则时使用IANA标识符；传输时间点时则带上明确的数值偏移。

夏令时（daylight saving time） 是规则变化的一个原因，却不是唯一原因。历史偏移变更与政府决策也会形成切换。代码应根据时区规则推理，不能假定每次切换都是熟悉的一小时季节调整。

空缺、重叠与fold

时钟向前拨时，一段本地时间会被跳过。落在空缺中的本地值没有对应时间点。时钟向后拨时，一段时间会重复，其中每个本地值都对应两个时间点。

Python的zoneinfo.ZoneInfo把IANA规则应用于感知型datetime对象。发生重叠时，datetime.fold用0选择切换前偏移，用1选择切换后偏移。只有两种解释确实不同时，这个标记才有意义。

通过构造器或replace(tzinfo=...)附加ZoneInfo，不会验证本地字段是否存在。即使字段位于空缺中，Python也会创建感知型对象。如果输入起点是民用字段，就必须先规定空缺策略，再通过UTC往返验证，或者使用能直接暴露解析结果的日程库。

感知型值与简单型值

Python把带有可用偏移信息的datetime称为感知型（aware），否则称为简单型（naive）。简单型值本身无法可靠承诺它表示UTC、宿主本地时间还是尚未解析的民用值。含义只存在于外围代码中，很容易丢失。

获取当前UTC时间点时使用datetime.now(UTC)，不要使用返回简单型结果且已经弃用的datetime.utcnow()。在边界处把外部时间点解析为感知型值。只有日期的值用date保存；未解析的本地日程则使用明确包含时区和策略的结构。

replace(tzinfo=zone)会给现有字段换标签，不会把一个时间点从某个时区移到另一个时区。astimezone(zone)保持时间点不变，只改变投影字段，因此两个操作不能互换。

时长与日历运算

经过时长可以用秒、纳秒或timedelta表示，具体取决于系统所需精度。跨越地区时钟变化时，如果要增加恰好经过的24小时，应在UTC时间线上运算，再把结果投影到展示时区。

日历运算处理字段和规则。“明天中午”会推进本地日期并保留中午，即使时间线上只经过23或25小时。“一个月后”还需要溢出规则，因为目标月份可能没有原来的日期数字。

Python算术有一条容易踩坑的同区规则。给本地感知型datetime加timedelta时，会保留同一tzinfo并进行字段运算；两个感知型值共享同一个tzinfo时，相减会忽略各自偏移。需求若是实际经过时间，应先把两个端点转为UTC，或者相减各自的时间戳。

进程内超时不要使用挂钟读数。网络时间同步或操作员可能调整系统时间，使连续两次UTC读数发生跳跃。time.monotonic()不会倒退，也没有民用时间含义，而区间测量恰好需要这种性质。

存储与边界

对于已记录事件，可以用明确规定格式且带已知偏移的RFC 3339文本，或者单位写入契约的整数纪元值跨服务传输。必须验证语法、范围、精度与单位。只叫timestamp的裸整数很容易产生秒与毫秒混淆。

如果后续行为取决于地区规则，就要单独保存指定时区。日历服务可能需要原始本地字段、IANA时区、选定的重叠或空缺策略，以及解析后的时间点。同时保留时间点有利于排序和审计，又不会丢掉日程意图。

格式化属于展示边界。明确传入区域设置与时区，不要继承宿主默认值。格式化输出供人阅读，通常不是稳定的交换格式，也不应被反向解析成领域数据。

数据库类型各不相同。有的保留时间点，有的保留不带时区的字段，timestamp之类名称的含义也取决于具体产品。把数据库值映射为语言类型前，应先阅读数据库类型与驱动转换的准确契约。

下面的示例使用Python 3.14标准库中的datetime、zoneinfo和time模块。所有输出均由Python 3.14.3配合本地IANA时区数据实际生成。

投影一个时间点

发布时刻带有明确的UTC偏移，因此标识一个时间点。每次调用astimezone()都保持该时间点不变，只改变它的民用投影。

纽约的01:30是时钟回拨当天的第一次出现，所以fold为0。上海在这个时间点没有重叠。两行仍然都对应纪元秒1793511000。

对于已加载的规则集，这个方向是确定的：先有时间点，再做投影。逆向解析则需要策略，因为经过一小时后，纽约会再次显示01:30。

解析重复的本地时间

下面的程序构造同一组纽约钟表字段的两种解释。fold改变所选偏移，因此也改变UTC时间点。

from datetime import UTC, datetime
from zoneinfo import ZoneInfo


new_york = ZoneInfo("America/New_York")
first = datetime(2026, 11, 1, 1, 30, tzinfo=new_york, fold=0)
second = datetime(2026, 11, 1, 1, 30, tzinfo=new_york, fold=1)

for candidate in [first, second]:
    print(
        f"fold={candidate.fold} "
        f"offset={candidate.utcoffset()} "
        f"utc={candidate.astimezone(UTC).isoformat()}"
    )

print(f"same wall fields: {first.replace(tzinfo=None) == second.replace(tzinfo=None)}")
print(f"elapsed: {(second.timestamp() - first.timestamp()) / 3600:.0f} hour")

fold=0 offset=-1 day, 20:00:00 utc=2026-11-01T05:30:00+00:00
fold=1 offset=-1 day, 19:00:00 utc=2026-11-01T06:30:00+00:00
same wall fields: True
elapsed: 1 hour

这种特殊的负timedelta输出分别表示UTC−04:00与UTC−05:00。移除tzinfo后，两组字段相等，但时间戳相差一小时。预订系统必须明确选择、拒绝或询问，不能直接采用库的默认值。

不能只根据小时推断fold。它只有与具体日期和时区组合、且规则确实产生重叠时才有意义。如果以后重建必须回到同一次出现，就要持久化解析后的时间点或明确选择。

日历意图与经过时间

这个示例中的纽约在3月8日早晨向前拨钟。一项操作保留下一个日期的当地中午，另一项操作则推进恰好经过的24小时。

from datetime import UTC, datetime, timedelta
from zoneinfo import ZoneInfo


new_york = ZoneInfo("America/New_York")
start = datetime(2026, 3, 7, 12, 0, tzinfo=new_york)

# 日历意图保留 12:00；经过时间意图保留 24 小时。
same_wall_time_tomorrow = start + timedelta(days=1)
after_twenty_four_hours = (
    start.astimezone(UTC) + timedelta(hours=24)
).astimezone(new_york)

print(f"start:    {start:%Y-%m-%d %H:%M %z}")
print(f"calendar: {same_wall_time_tomorrow:%Y-%m-%d %H:%M %z}")
print(f"elapsed:  {after_twenty_four_hours:%Y-%m-%d %H:%M %z}")
print(f"calendar seconds: {same_wall_time_tomorrow.timestamp() - start.timestamp():.0f}")
print(f"elapsed seconds:  {after_twenty_four_hours.timestamp() - start.timestamp():.0f}")

start:    2026-03-07 12:00 -0500
calendar: 2026-03-08 12:00 -0400
elapsed:  2026-03-08 13:00 -0400
calendar seconds: 82800
elapsed seconds:  86400

日历结果只经过了82,800秒，因为本地时钟跳过一小时。经过时间结果显示为13:00，比起始钟点晚一小时。两者没有哪个总是正确；具体需求决定选择。

代码用时间戳比较经过时间。如果改写为(after_twenty_four_hours - start).total_seconds()，得到的会是同区钟表字段差，本例中这些显示字段相差25小时。这个结果回答了另一个问题。

构造单调截止时间

截止时间可以保存为单调时钟的一次读数。注入时钟能让测试取得准确读数，也不会误把日历时间戳当作区间控制依据。

import time


class SequenceClock:
    def __init__(self, readings):
        self._readings = iter(readings)

    def __call__(self):
        return next(self._readings)


def make_deadline(timeout_seconds, clock=time.monotonic):
    expires_at = clock() + timeout_seconds

    def remaining():
        return max(0.0, expires_at - clock())

    return remaining


# 注入时钟，让截止时间测试保持确定性。
clock = SequenceClock([100.0, 101.25, 106.0])
remaining = make_deadline(5.0, clock)

print(f"remaining: {remaining():.2f}")
print(f"remaining: {remaining():.2f}")

remaining: 3.75
remaining: 0.00

这些数值读数不能转换为日期，也不应作为通用时间戳序列化给另一个进程。它们只对当前运行时中兼容时钟测出的差值有意义。这种窄契约能防止民用时间校正延长或缩短超时。

max()截断让已过期预算返回零，而不是负值。真实等待循环仍要把当前剩余预算传给每次阻塞操作，并在预算归零时停止。

把简单型值当成UTC

修复方法： 对表示时间点的输入要求明确偏移，并在边界处转为感知型值。未解析的民用输入应单独建模，不能只靠注释或变量名说明其时区契约。

把重贴标签当成转换

修复方法： 要保持已有时间点时使用astimezone()。只有明确要把字段解析成当地民用时间时才使用replace(tzinfo=...)，随后还要处理空缺与重叠。

把偏移存成时区

修复方法： 把IANA时区标识符与重复字段一起存储，并规定时区规则数据库升级如何影响未来日期。解析后的传输时间戳仍要带明确偏移，保证每次传输的时间点没有歧义。

让库替你决定切换策略

修复方法： 通过UTC往返检测零个或两个候选项，再应用有名称的产品策略：拒绝、向前移动、选较早、选较晚，或者询问用户。为每个支持日程的时区测试真实切换点。

混用日历运算与经过时间运算

修复方法： 用操作名称与测试写明语义选择，例如expires_after_hours或next_local_occurrence。测试切换点、月末、闰日和反向移动时，同时断言当地字段与时间线差值。

使用挂钟计时

修复方法： 经过时间与截止值使用time.monotonic()或time.monotonic_ns()。日志需要民用时间戳时另行记录UTC时间点，不要把单调时钟读数转换成日期。

• Python datetime文档
• Python zoneinfo文档
• Python time.monotonic()文档
• IANA时区数据库理论
• RFC 3339：互联网中的日期与时间