REST API返回日期的正确方式：自定义格式还是时间戳？主数据API疑问

两种常见实现方式 #

方式一：格式化字符串返回 #

通过@JsonFormat注解指定日期格式，将Date类型序列化为可读字符串：

@JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy.MM.dd HH:mm:ss")
protected Date changeDate;

返回结果示例：

"validFrom": "2021.12.31 22:00:00"

这种方式直观易读，客户端无需额外转换就能理解日期含义，对接成本低。也可通过调整注解参数或使用Date、XmlGregorianCalendar等类型实现其他自定义格式。

方式二：时间戳数值返回 #

直接返回Date类型对应的毫秒级时间戳：

private Date startDateConcern;

返回结果示例：

"startDateConcern": 1185746400000

这种方式精度高、无时区歧义，适合需要日期计算的场景，但可读性差，客户端需自行转换为可读格式，容易让不熟悉时间戳的对接方产生困惑。

主数据API的选型建议 #

主数据API需兼顾可读性与易用性，对接的客户端技术栈和开发人员水平参差不齐，因此更推荐方式一（格式化字符串返回）。

若担心时区问题，可在格式中加入时区标识，比如将pattern设为"yyyy-MM-dd HH:mm:ss z"，明确时区信息，避免跨时区场景下的日期误解。如果有高精度计算需求，也可考虑同时返回格式化字符串和时间戳，但会增加接口复杂度，需结合实际业务场景权衡。

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