前端工程化系列(一)——设计RESTful风格API

1. REST

REST(Representational State Transfer,表征性状态转移)。其与技术无关,是一种软件架构风格

REST的六大特点:

客户端/服务器(Client/Server)

C/S架构中的关注点分离:

  • 服务端专注数据存储,提升了简单性;
  • 前端专注用户界面,提升了可移植性;

无状态(Stateless)

所有的用户会话信息均保存在客户端,每次请求必须包含所有信息,不能依赖上下文信息;
服务端不用保存会话信息,提升了简单性、可靠性、可见性。

缓存(Cache)

所有服务端响应都要被标记为可缓存或不可缓存。其可以减少前后端交互,提升性能。

统一接口(Uniform Interface)

接口设计尽可能统一通用,提升了简单性、可见性。

接口与实现解耦,使前后端可以独立开发迭代。

分层系统(Layered System)

每一层只能了解相邻的一层。

其他层包括:安全层、负载均衡、缓存层等等。

按需代码(Code ON Demand)

客户端可以下载运行服务端传来的代码(如JS);

其可以减少一些功能,简化客户端。

2. 统一接口限制

REST是资源的表述,资源可以是可以命名的事物,其可以是实体,也可以是抽象的概念(均用名词形式表述)。

每一个资源都可以通过URI(Uniform Resource Identifier,统一资源标识符)被唯一标识。

通过表述操作资源

表述为REST中的Representational,即资源在外界的具体呈现,因此资源可以有多种表述形式(如:JSON、XML等等),在客户端和服务端之间传输的是资源的表述。

资源的表述通常包括数据和描述数据的元数据。例如:HTTP头中的“Content-Type”为描述数据的元数据,告知客户端资源的表述形式。

因此客户端不能直接操作(如:SQL)服务端资源,应该通过表述(如:JSON)来操作服务端资源。

自描述信息

每个消息(请求或响应)必须提供足够的信息让接受者理解。如:

  • 媒体类型(application/json、application/xml)
  • HTTP方法(GET进行查询、POST进行新增、DELETE进行删除)
  • 是否缓存(Cache-Control)

3. RESTful API

RESTful 的核心思想就是,客户端发出的数据操作指令都是"动词 + 宾语"的结构。比如,GET /articles这个命令,GET是动词,/articles是宾语。

GitHub RESTful API 简介

设计规范:

  • API与客户端的通信协议,尽量使用HTTPS协议;
  • 尽量将API部署在专用域名上(存在跨域问题);
  • 可设置API版本;
  • URL路径中,尽可能使用名词表示;
  • 五种常见的请求方法;
  • 通过URL上传递参数来传递搜索条件;
  • 状态码(请求返回状态码);
  • 错误处理(请求返回错误信息);
  • 返回值(针对不同请求返回不同返回值);
  • Hypermedia API;

4. 设计请求

其中动词通常为五种HTTP方法,对应对资源进行CURD操作:

  • GET:读取(Read)
  • POST:新建(Create)
  • PUT:更新(Update)
  • PETCH:部分更新(Update)
  • DELETE:删除(Delete)

URL设计:

  • URI使用名词,尽量使用复数,如:用户使用/users
  • URI使用嵌套表示关联关系,如:用户admin的信息/user/admin/info
  • 避免多级URL,除第一级,其他级别用查询字符串来进行表达;
  • 可以使用_或者-使URI可读性更好;
  • 可以使用/来表示资源的层级关系;
  • 可以使用?过滤资源;
  • 可以使用,;或者...表示同级资源的关系;

5. 设计响应

响应部分主要由三部分组成:

  • 返回状态码
  • 返回信息描述
  • 返回值
{
	code:integer,
	message:string,
	data:object
}

code状态码

常见HTTP状态码:

  • 200:请求成功
  • 301:资源被永久转移到其它URL
  • 404:请求的资源不存在
  • 500:内部服务器错误
分类区间分类描述
1xx100~199相关信息:服务器收到请求
2xx200~299操作成功:操作被成功接收并处理
3xx300~399重定向:需要进一步操作完成请求
4xx400~499客户端错误,请求包含错误或无法完成请求
5xx500~599服务器错误,服务器在请求的过程中发生了错误

API不要1xx状态码

2xx

表示操作成功,不同方法可以返回不同的状态码:

  • GET:200 OK
  • POST:201 Created
  • PUT:200 OK
  • PATCH:200 OK
  • DELETE:204 No Content

201表示生成了新的资源;204表示资源不存在;202表示服务器收到请求,但还未进行处理,会在未来再处理,通常用于异步操作。

3xx

API用不到301状态码(永久重定向)和302状态码(暂时重定向,307也是这个含义),因为它可以由应用级别返回,浏览器可以直接跳转,API级别可以不考虑这两种情况。

API主要用到的是303状态码,它与302、307的含义一样,也就是“暂时重定向”,区别在于302和307用于PUT请求,而303用于POST、PUT和DELETE请求。收到303以后,浏览器不会自动跳转,而由用户自己决定下一步选择。

4xx

客户端错误:

  • 400:服务器不理解客户端的请求,未做任何处理;
  • 401:用户未提供身份验证凭据,或者没有通过身份验证;
  • 403:用户通过了身份验证,但不具备访问资源所需的权限;
  • 404:所请求的资源不存在或不可用;
  • 405:用户已通过身份验证,但是所用的HTTP方法不在他的权限范围之内;
  • 410:所请求的资源,已从此地址转移,不可再用;
  • 415:客户端要求返回的格式不对;
  • 422:客户端上传的附件无法处理,导致请求失败;
  • 429:客户端的请求次数超过限制;

5xx

API不会向用户透露服务器的详细信息,所以只需要两个状态码:

  • 500:客户端请求有效,但是服务器处理时发生了意外;
  • 503:服务器无法处理请求,一般用于网站维护时;

message 返回信息描述

建议将此信息与状态码进行一一对应,便于维护。

data 返回值

通常使用JSON格式,返回数据体。

  • 0
    点赞
  • 1
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

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

抵扣说明:

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

余额充值