RESTful服务最佳实践——(十)

本文探讨了日期和时间处理的最佳实践,重点介绍了如何利用ISO8601格式统一日期时间的表示,确保跨系统的兼容性和一致性。同时,文章还提供了在不同编程环境中实现这一格式的具体方法。

摘要生成于 C知道 ,由 DeepSeek-R1 满血版支持, 前往体验 >

日期/时间处理

如果没有妥善地、一致地处理好日期和时间的话,这将成为一个大麻烦。时区问题总是能轻易发生,并且由于日期在JSON中只是字符串的,所以如果格式是未知的、不一致的、未指定的,那么分析日期便成了一个问题。

在接口内部,这些(时间的)服务应该被存储、运行和缓存,例如UTC或GMT时间戳。这将减轻日期和时间上的问题。

Body内容中的时间序列化

有一个简单的方法可以解决这些问题–在字符串中始终用一些相同的格式,包括时间片(带有时区信息)。ISO8601时间点格式是一种不错的解决的方案,它使用了全面提高版的格式,包括小时、分钟、秒以及秒的小数部分(例如yyyy-MM-dd’T’HH:mm:ss.SSS’Z’)。ISO8601被推荐使用于在REST服务body内容(请求和响应均包括)中呈现的所有日期中。

恰巧,对于那些作为搭载在JAVA上的服务系统,DateAdapterJ库使用它的J日期适配器(DateAdapterJ)、ISO8601时间点适配器和HTTP头时间戳适配器(HttpHeadeTimestampAdapter)实现类,很容易就能分别分析和格式化ISO8601的日期、时间点、HTTP1.1头(RFC1123)格式。这些可以从https://github.com/tfredrich/DateAdapterJ上下载。

对于那些创建的基于浏览器的用户界面来说,ECMAScript5规范一开始便包含了JavaScript分析和创造ISO8601日期的内容,所以它该成为我们所说的主流浏览器所遵从的方式。当然,如果你要支持不能分析这些日期的旧版浏览器,JavaStript库或一个有趣的普遍解释也能够做到。关于可以解析和生成ISO8601时间点的JavaStript库的一些例子:

http://momentjs.com/
http://www.datejs.com/

在HTTP头中的时间序列化

然而以上的建议仅对HTTP的请求或相应内容中的JSON和XML内容有效,HTTP规范对HTTP头使用另一种不同的格式。被RFC1123更替的RFC822中指出,HTTP头格式包括了多种日期、时间和日期-时间格式。然而它总是被推荐使用时间戳格式,在你的请求头中看起来像这样结尾:

Sun, 06 Nov 1994 08:49:37 GMT。

不幸的是,它的格式没有考虑毫秒或者秒的十进制小数。Java 简单日期格式(SimpleDataFormat)的区分串是:“EEE, dd MMM yyyy HH:mm:ss ‘GMT’”


原文如下


Date/Time Handling

Dates and timestamps can be a real headache if not dealt with appropriately and consistently. Timezone issues can crop up easily and since dates are just strings in JSON payloads, parsing is a real issue if the format isn’t known, consistent or specified.

Internally, services should store, process, cache, etc. such timestamps in UTC or GMT time. This alleviates timezone issues with both dates and timestamps.

Date/Time Serialization In Body Content

There’s an easy way around all of this—always use the same format, including the time portion (along with timezone information) in the string. ISO 8601 time point format is a good solution, using the fully-enhanced format that includes hours, minutes, seconds and a decimal fraction of seconds (e.g. yyyy-MM-dd’T’HH:mm:ss.SSS’Z’). It is recommended that ISO 8601 be used for all dates represented in REST service body content (both requests and responses).

Incidentally, for those doing Java-based services, the DateAdapterJ library easily parses and formats ISO8601 dates and time points and HTTP 1.1 header (RFC 1123) formats, with its DateAdapter, Iso8601TimepointAdapter and HttpHeaderTimestampAdapter implementation classes, respectively. It can be downloaded at https://github.com/tfredrich/DateAdapterJ.

For those creating browser-based UIs, the ECMAScript 5 specification includes parsing and creating ISO8601 dates in JavaScript natively, so it should be making its way into all mainstream browsers as we speak. If you’re supporting older browsers that don’t natively parse those dates, a JavaScript library or fancy regular expression is in order. A couple of sample JavaScript libraries that can parse and produce ISO8601 Timepoints are:

http://momentjs.com/
http://www.datejs.com/

Date/Time Serialization In HTTP Headers

While the above recommendation works for JSON and XML content in the content of and HTTP request or response, the HTTP specification utilizes a different format for HTTP headers. Specified in RFC 822 which was updated by RFC 1123, that format includes various date, time and date-time formats. However, it is recommended to always use a timestamp format, which ends up looking like this in your request headers:

Sun, 06 Nov 1994 08:49:37 GMT

Unfortunately, it doesn’t account for a millisecond or decimal fraction of a second in its format. The Java SimpleDateFormat specifier string is: “EEE, dd MMM yyyy HH:mm:ss ‘GMT’”

### Restful API 设计最佳实践指南 RESTful API 的设计是一个复杂而细致的过程,它不仅涉及技术层面的选择,还关系到用户体验和系统的长期维护性。以下是几个关键方面的总结: #### 1. URL 设计 URL 是 RESTful API 的核心组成部分之一,良好的 URL 结构能够显著提升 API 的可读性和一致性。推荐采用名词作为资源名称,并使用复数形式表示集合[^2]。 例如: ```plaintext GET /users # 获取所有用户列表 POST /users # 创建新用户 GET /users/{id} # 获取指定ID的用户详情 PUT /users/{id} # 更新指定用户的全部信息 PATCH /users/{id} # 部分更新指定用户的信息 DELETE /users/{id} # 删除指定用户 ``` #### 2. 使用标准 HTTP 方法 RESTful API 利用了 HTTP 协议的标准动词来定义不同的操作行为。常见的 HTTP 方法及其用途如下表所示[^4]: | **HTTP Method** | **Description** | |------------------|-----------------------------------| | GET | 请求获取某个资源 | | POST | 提交数据以创建新的子节点或对象 | | PUT | 替换目标资源的所有当前表示 | | DELETE | 删除由 URI 所标识的资源 | | PATCH | 对资源进行部分修改 | #### 3. 状态码的应用 恰当的状态码返回对于客户端理解请求的结果至关重要。下面列举了一些常用的 HTTP 状态码以及它们的意义[^2]: - `200 OK` —— 成功完成请求。 - `201 Created` —— 新资源已成功创建。 - `204 No Content` —— 不返回任何实体主体。 - `400 Bad Request` —— 错误的请求语法或者无法被服务器理解。 - `401 Unauthorized` —— 当前用户未授权访问此资源。 - `403 Forbidden` —— 用户虽经认证但仍无权访问该资源。 - `404 Not Found` —— 请求的资源不存在于服务器上。 - `500 Internal Server Error` —— 通用错误消息,当发生未知内部错误时发送给客户机。 #### 4. 数据格式与媒体类型支持 为了满足不同客户端的需求,建议同时支持多种数据交换格式(如 JSON 和 XML),并通过 Accept 头部字段协商最合适的媒介类型[^1]。 示例代码片段展示了如何设置响应头以便浏览器知道内容是以何种格式呈现出来的: ```http Content-Type: application/json; charset=utf-8 ``` #### 5. 版本控制策略 随着项目的演进,不可避免会引入不兼容的变化。因此,在最初阶段就应该考虑版本管理机制。一种常见做法是在路径中加入版本号,比如 `/v1/resource` 或者利用查询参数 `?version=1` 来区分各个迭代之间的差异[^3]。 #### 6. 缓存优化 合理运用缓存可以有效减少重复计算带来的开销并加快页面加载速度。ETag 和 Last-Modified 这两个头部可以帮助实现条件请求功能,只有在本地副本过期的情况下才会重新下载完整的文件[^4]。 --- ### 总结 综上所述,构建高效的 RESTful API 需要考虑诸多因素,包括但不限于清晰直观的 URL 架构、严格遵守 HTTP 协议规范、精确反馈状态信息等等。遵循以上提到的各项准则有助于打造出既实用又健壮的服务端接口解决方案。
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值