当前位置：首页 > news >正文

网站维护和建设工作范围营销型网站定制

news 2025/7/8 8:40:47

网站维护和建设工作范围,营销型网站定制,美业网站建设,建设境外网站1. 简介目前 "互联网软件"从用客户端/服务端模式，建立在分布式体系上，通过互联网通讯，具有高延时、高开发等特点。但是软件开发和网络是两个不同的领域，交集很少。要使得两个融合，就要考虑如何在互联网环境…

1. 简介

目前 "互联网软件"从用客户端/服务端模式，建立在分布式体系上，通过互联网通讯，具有高延时、高开发等特点。但是软件开发和网络是两个不同的领域，交集很少。要使得两个融合，就要考虑如何在互联网环境使用软件。

REST 描述了一个架构样式的网络系统，2000 年 Roy Fielding 在他的博士论文中首次提出了 REST，同时他也是HTTP协议（1.0版和1.1版）的主要设计者、Apache服务器软件的作者之一、Apache基金会的第一任主席。

目前主流的三种 Web 服务交互方案：

REST：表现层状态转化
SOAP（Simple Object Access protocol）：简单对象访问协议
XML-RPC

要想理解什么是 REST(Representational State Transfe) 就要理解这里几个词是什么意思。

资源（Resources）

REST的名称"表现层状态转化"中，省略了主语。“表现层"其实指的是"资源”（Resources）的"表现层"。

网络中所谓资源即实体表现的一种，如：文本、图片、音频，视频等。通过调用特定的 URI 来获取相应资源，因此 URI 就成了每一个资源的地址或独一无二的识别符。

表现层（Representation）

“资源"是一种信息实体，它可以有多种外在表现形式。我们把"资源"具体呈现出来的形式，叫做它的"表现层”（Representation）。

如：文本可以以 txt、json、xml 等格式表现，甚至是二进制格式，图片也有 jpg、png 等格式。

URI 只代表资源的实体，不代表它的形式。严格地说，有些网址最后的.html 后缀名是不必要的，因为这个后缀名表示格式，属于"表现层"范畴，而URI应该只代表"资源"的位置。它的具体表现形式，应该在HTTP请求的头信息中用 Accept 和 Content-Type字段指定，这两个字段才是对"表现层"的描述。

状态转化（State Transfer）

众所周知互联网通讯协议 HTTP 协议是无状态的，所有状态都保存在服务器上。因此如果客户端要想操作（获取、删除、更新操作数据），就必须让服务器状态发生改变（State Transfer）而这种状态转化建立在表现层上，所有称为 表现层状态转化。

客户端通过 HTTP 协议可以与服务端进行通信，HTTP 协议中表示操作的四个动作是：

GET：获取资源
POST：新建资源
PUT：更新资源
DELETE：删除资源

客户端用到的手段，只能是HTTP协议。具体来说，就是HTTP协议里面，四个表示操作方式的动词：GET、POST、PUT、DELETE。它们分别对应四种基本操作：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源。

RESTful架构典型的设计误区

1、URI 中包含动词：资源是一种实体，应该用名词，动词应放在 HTTP 协议中。

# 错误，show 为动词
/posts/show/1# 如果要获取可用 get
/posts/1
/get/         # 表示 show

若某些动作用 HTTP 动词表示不了，可用将动作看做一种资源，如：网上付款 URI 设计：

# 错误
POST /accounts/1/transfer/500/to/2# 正确
POST /transaction HTTP/1.1
Host: 127.0.0.1from=1&to=2&amount=500.00

2、在 URI 中加入版本号

# 错误
http://www.example.com/app/1.0/foo
http://www.example.com/app/1.1/foo

不同的版本，可以理解成同一种资源的不同表现形式，所以应该采用同一个U RI。版本号可以在HTTP请求头信息的Accept字段中进行区分（参见 Versioning REST Services）：

# 正确
Accept: vnd.example-com.foo+json; version=1.0
Accept: vnd.example-com.foo+json; version=1.1

然而实际开发中，大多开发人员会将版本号放在 URI 中，因为方便。

总结

什么是 RESTful 架构：

RESTful 是一种在网络上能够开发软件的体系架构
互联网之间通讯是资源的一种交互
每个 URI 代表一种资源，通过特定 URI 可以访问相应资源
资源有不同的表现形式
HTTP 协议无状态
客户端获取服务器资源，需要改变其状态
客户端通过四个HTTP动词，对服务器端资源进行操作，实现"表现层状态转化"

2. RESTful API 设计指南

2.1 协议

API与用户的通信协议，总是使用HTTPs协议。

2.2 域名

1、应该尽量将 API 部署在专用域名之下，(这中情况会存在跨域问题)

https://api.example.com

2、如果确定 API 很简单，不会有进一步扩展，可以考虑放在主域名下。

https://example.org/api/

2.3 版本（Versioning）

应该将 API 的版本号放入 URL。

https://api.example.com/v1/

另一种做法是，将版本号放在HTTP头信息中，但不如放入URL方便和直观。Github采用这种做法。

2.4 路径（Endpoint）

路径又称"终点"（endpoint），表示 API 的具体网址。

在 RESTful 架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以 API 中的名词也应该使用复数。

举例来说，有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。

https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees

2.5 HTTP动词

对于资源的具体操作类型，由 HTTP 动词表示。常用的 HTTP 动词有下面五个（括号里是对应的SQL命令）：

GET（SELECT）：从服务器取出资源（一项或多项）。
POST（CREATE）：在服务器新建一个资源。
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
DELETE（DELETE）：从服务器删除资源。

不常用的 HTTP 动词：

HEAD：获取资源的元数据。
OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。

下面是一些例子。

GET /zoos：列出所有动物园
POST /zoos：新建一个动物园
GET /zoos/ID：获取某个指定动物园的信息
PUT /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息）
PATCH /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息）
DELETE /zoos/ID：删除某个动物园
GET /zoos/ID/animals：列出某个指定动物园的所有动物
DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物

2.6 过滤信息（Filtering）

如果记录数量很多，服务器不可能都将它们返回给用户。API 应该提供参数，过滤返回结果。

下面是一些常见的参数：

# 指定返回记录的数量
https://api.example.com/v1/zoos?limit=10# 指定返回记录的开始位置
https://api.example.com/v1/zoos?offset=10# 指定第几页，以及每页的记录数
https://api.example.com/v1/zoos?page=2&per_page=100# 指定返回结果按照哪个属性排序，以及排序顺序
https://api.example.com/v1/zoos?sortby=name&order=asc# 指定筛选条件
https://api.example.com/v1/zoos?animal_type_id=1

参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。比如，GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。

2.7 状态码（Status Codes）

服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的HTTP动词）。

200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
204 NO CONTENT - [DELETE]：用户删除数据成功。
400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

状态码的完全列表参见这里。

2.8 错误处理（Error handling）

如果状态码是4xx，就应该向用户返回出错信息。一般来说，返回的信息中将 error 作为键名，出错信息作为键值即可。

{error: "Invalid API key"
}

2.9 返回结果

针对不同操作，服务器向用户返回的结果应该符合以下规范。

GET /collection：返回资源对象的列表（数组）
GET /collection/resource：返回单个资源对象
POST /collection：返回新生成的资源对象
PUT /collection/resource：返回完整的资源对象
PATCH /collection/resource：返回完整的资源对象
DELETE /collection/resource：返回一个空文档

2.10 Hypermedia API

RESTful API最好做到 Hypermedia，即返回结果中提供链接，连向其他 API方法，使得用户不查文档，也知道下一步应该做什么。

比如，当用户向 api.example.com的根目录发出请求，会得到这样一个文档。

{"link": {"rel":   "collection https://www.example.com/zoos","href":  "https://api.example.com/zoos","title": "List of zoos","type":  "application/vnd.yourformat+json"
}}

上面代码表示，文档中有一个 link 属性，用户读取这个属性就知道下一步该调用什么API了。rel表示这个API与当前网址的关系（collection关系，并给出该collection的网址），href表示API的路径，title表示API的标题，type表示返回类型。

Hypermedia API的设计被称为HATEOAS。Github的API就是这种设计，访问api.github.com会得到一个所有可用API的网址列表。

{"current_user_url": "https://api.github.com/user","authorizations_url": "https://api.github.com/authorizations",// ...
}从上面可以看到，如果想获取当前用户的信息，应该去访问`api.github.com/user`，然后就得到了下面结果。
{"message": "Requires authentication","documentation_url": "https://developer.github.com/v3"
}