如何在Java中创建兼容Outlook Calendar API的日期格式

阿华AIGC实验室

2026-5-15

解决Microsoft Graph API日历事件的日期格式序列化问题

这个问题我之前对接Graph API时也踩过坑！核心原因是你的DateTimeTimeZone类中dateTime字段的序列化方式不符合Outlook API的要求：默认情况下，Date类型会被序列成毫秒时间戳，但API需要的是yyyy-MM-dd'T'HH:mm:ss.SSS'Z'格式的ISO 8601字符串，所以才会触发RequestBodyRead错误。

下面分两种常用的序列化库（Gson/Jackson）给出具体修复方案，还有一种更直接的字段类型修改方式：

方案一：全局配置Gson序列化规则（推荐）

如果你的Retrofit用的是Gson作为JSON转换器，只需要自定义Gson的日期格式化规则，让它把Date类型转成API要求的格式：

创建自定义Gson实例：

Gson gson = new GsonBuilder()
    // 指定符合API要求的日期格式，注意末尾的'Z'是固定时区标识
    .setDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'")
    .create();

在Retrofit构建时绑定这个Gson实例：

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://graph.microsoft.com/v1.0/")
    .addConverterFactory(GsonConverterFactory.create(gson))
    .build();

这样所有Date类型的字段都会自动转成正确的字符串格式，不用单独处理每个字段。

方案二：全局配置Jackson序列化规则

如果用的是Jackson转换器，配置方式类似：

配置ObjectMapper禁用时间戳序列化，指定日期格式：

ObjectMapper objectMapper = new ObjectMapper();
// 关闭默认的时间戳序列化
objectMapper.configure(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS, false);
// 设置符合要求的日期格式
objectMapper.setDateFormat(new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"));
// 确保时区是UTC，和API要求的Z时区匹配
objectMapper.setTimeZone(TimeZone.getTimeZone("UTC"));

绑定到Retrofit：

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://graph.microsoft.com/v1.0/")
    .addConverterFactory(JacksonConverterFactory.create(objectMapper))
    .build();

方案三：直接修改字段类型为String（快速临时方案）

如果不想改动全局序列化配置，也可以把DateTimeTimeZone中的dateTime字段类型从Date改成String，然后在构造对象时手动格式化日期：

// 1. 定义DateTimeTimeZone类
public class DateTimeTimeZone {
    private String dateTime; // 把Date改成String
    private String timeZone;

    // getter和setter
}

// 2. 构造事件时手动格式化日期
SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'");
sdf.setTimeZone(TimeZone.getTimeZone("UTC")); // 必须设置UTC时区，否则格式会不匹配
String formattedStartTime = sdf.format(new Date());

DateTimeTimeZone start = new DateTimeTimeZone();
start.setDateTime(formattedStartTime);
start.setTimeZone("UTC"); // 记得设置时区字段，API必填

// 然后把这个start对象传入Event实例即可