带时区CSV数据日期范围筛选异常问题求最佳实践

核心问题根源 #

你当前的错误在于：将目标年份的起始/结束日期直接转成UTC后作为筛选边界，但AEST（UTC+10）时区的2021年1月1日0点，对应UTC的2020年12月31日14点。用>= 2021-01-01 UTC作为起始条件，自然会漏掉AEST时区2021年1月1日0点到14点之间的记录。同理，如果直接用<= 2021-12-31 UTC作为结束条件，会漏掉AEST时区2021年12月31日14点到24点之间的记录（这些记录转成UTC是2022年1月1日）。

正确解决方案 #

方案1：在原始时区（AEST）内完成筛选 #

保留CSV日期的AEST时区信息，直接在该时区下构造筛选范围，避免跨时区转换带来的边界误差。

from zoneinfo import ZoneInfo
import pandas as pd
from fastapi import FastAPI

app = FastAPI()

# 提前读取并预处理CSV（实际项目中可按需优化加载逻辑）
df = pd.read_csv("transactions.csv", parse_dates=["Date"])
# 确保Date字段绑定AEST时区（如果CSV日期无时区标记，手动指定）
df["Date"] = df["Date"].dt.tz_localize(ZoneInfo("Australia/Sydney"))

@app.get("/transactions/{year}")
def get_yearly_transactions(year: int):
    # 构造AEST时区的筛选范围：从目标年1月1日0点开始，到下一年1月1日0点结束
    start_date = pd.Timestamp(f"{year}-01-01", tz=ZoneInfo("Australia/Sydney"))
    end_date = pd.Timestamp(f"{year+1}-01-01", tz=ZoneInfo("Australia/Sydney"))
    
    # 用>= start_date + < end_date的组合，完整覆盖目标年份所有时间
    filtered_df = df[(df["Date"] >= start_date) & (df["Date"] < end_date)]
    
    return filtered_df.to_dict(orient="records")

方案2：转换到UTC后，计算正确的UTC边界 #

如果必须在UTC下处理，先计算出AEST目标年份对应的UTC时间范围，再进行筛选。

from zoneinfo import ZoneInfo
import pandas as pd
from fastapi import FastAPI

app = FastAPI()

df = pd.read_csv("transactions.csv", parse_dates=["Date"])
df["Date"] = df["Date"].dt.tz_localize(ZoneInfo("Australia/Sydney"))
# 提前将CSV日期转成UTC
df["Date_UTC"] = df["Date"].dt.tz_convert(ZoneInfo("UTC"))

@app.get("/transactions/{year}")
def get_yearly_transactions(year: int):
    # 先在AEST下定义范围，再转成UTC
    aest_start = pd.Timestamp(f"{year}-01-01", tz=ZoneInfo("Australia/Sydney"))
    aest_end = pd.Timestamp(f"{year+1}-01-01", tz=ZoneInfo("Australia/Sydney"))
    
    utc_start = aest_start.tz_convert(ZoneInfo("UTC"))
    utc_end = aest_end.tz_convert(ZoneInfo("UTC"))
    
    # 同样用>= + <的组合筛选UTC时间
    filtered_df = df[(df["Date_UTC"] >= utc_start) & (df["Date_UTC"] < utc_end)]
    
    return filtered_df.to_dict(orient="records")

最佳实践总结 #

• 统一时区比较：永远不要在不同时区的时间之间直接做范围判断，要么保留原始时区，要么统一转换到单一明确的时区（如UTC）后再处理。
• 用开区间结束边界：对于“全年”“全月”这类周期筛选，不要用<= 周期最后一天，而是用< 下一个周期的第一天，这样能完美覆盖周期内的最后一秒记录，避免边界遗漏。
• 明确时区约定：在接口文档中明确说明用户输入的年份对应的时区（比如本场景是AEST），避免跨时区用户请求时产生歧义。
• 保留时区元数据：处理日期时始终携带时区信息，不要使用 naive datetime（无时区标记的日期时间），防止隐性的时区转换错误。

内容的提问来源于stack exchange，提问作者mdkb