API设计中,如何定义你的时间参数和时间相关的返回值可能会是一个潜在的问题,千万不要低估这些问题,它们可能会对你未来的设计和实现造成很大麻烦。
本文提供一些tips可能可以帮助到大家
规则#1 使用ISO-8601作为时间格式
- 使用ISO-8601应该没有太大疑问,毕竟W3C/IETF/XKCD都在使用这个标准。ISO-8601可能完美的支持显示日期、时间以及时区
- ISO-8601有很多优点,包括:
- 自然排序 :天生支持自然排序,无需其他转换工作
- 时区支持:用户的地时区对开发者来说都是必须要考虑的因素,而ISO-8601可以很好的描述时区偏移
- 位置无关:假定给一个日期2/3/4, 这个日期如果你在美国,可能表示时间为Feb 3, 2004,在其他地方,可能表示Mar 2,2004 ,而在ISO 8601的定义中,2004-02-03不会带来任何歧义
- 语言支持:绝大部分的语言都有成熟的库来支持ISO-8601
可以通过LINUX/UNIX控制台快速的看下ISO-8601的格式
![ISO 8601](http://static.oschina.net/uploads/img/201303/24172642_U7vs.png)
规则#2 支持任何时区
在全球化的时代,如果我们的API对外开放,就不能对用户所在的时区做任何假设,而ISO-8601很好的支持了时区的偏移量描述
规则#3 用UTC格式存储时间
很多系统都会使用公司总部所在的时区,而这对于处在地球另一端的用户是比较糟糕的体验
UTC(世界协调时间),是最常见的通用时间存储格式,因为它不代表任何时区,这使得开发者可以基于用户所在的时区方便的进行转换
规则#4 使用UTC时间作为返回时间格式
对于用户不同时区数据的需求,你不需要太多理会,只要告诉你的用户:"你获取的是UTC格式的时间"
规则#5 如果你只需要日期而不是时间的话,不要使用时间
ISO 8601允许我们提供一个日期而不是时间。加入我们有个场景,只需要提供一个日期 2013-03-01, 假设我们用UTC时间2013-03-01T23:59:59来表达,那么,对于中国标准时间(UTC+0800)做时差计算,时间就会是Mar 2,2013 8AM,这可能会带来一些问题。我们可以简单的使用不带任何时间/时区偏移的2013-03-01来描述,这可以避免日期解析带来的误读。当前,大多数存储系统都支持只包含日期的格式
总结
上面提到的一些格式我们放心使用,因为几乎所有的Restful平台都在使用这些格式,不过需要注意的是,作为API提供者,我们需要关心当数据离开我们的平台,用户会基于这些数据做些什么
另外,我们开发的很多应用面向的可能是不同国家和时区的用户,如果你不想针对时间和日期写一大堆转换的代码,那么你需要好好利用这些规则
原文:The 5 laws of API dates and times
原文下面有些回复也很有意思,有兴趣的同学可以看下~