RESTful规范

时间:2019-12-30 大道至诚人气:0

RESTful规范(建议)

RESTful规范(建议)

一、最原始的接口开发

这种方式虽然可以实现接口的开发，但是一个表的处理就需要4个url，当表单多的时候，需要写大量的url，这样不利于开发，并不是接口开发的最好方法

#url路由分配
urlpatterns = [
    path('get_order/', views.get_order),
    path('add_order/', views.add_order),
    path('del_order/', views.del_order),
    path('update_order/', views.update_order)
]
# 视图函数处理
def get_order(request):
    return HttpResponse(' ')

def add_order(request):
    return HttpResponse(' ')

def del_order(request):
    return HttpResponse(' ')

def update_order(request):
    return HttpResponse(' ')

二、优化接口开发(FBV)

根据request中method的不同，来执行对应的方法，返回值给前端，这一种开发优化了上一种开发方式

# 把原来的四条合并为一条
urlpatterbs = [
    path('order/', views.order),
]
# 视图函数中通过判断request方法来进行对应的处理
def order(request):
    if request.method == 'GET':
        return HttpResponse("获取一条或者多条订单")
    elif request.method == 'POST':
        return HttpResponse("增加一条订单")
    elif request.method == 'PUT':
        return HttpResponse("更新一条订单")
    elif request.method == 'DELETE':
        return HttpResponse("删除一条订单")

三、进一步优化，基于CBV模式来开发(CBV)

在FBV基础上进一步优化，CBV开发模式下继承了FBV中的路由简化，同时也改进了视图函数，开发人员不需要再对request方法进行判断，直接可以开发。

#url中的路由分配， 使用CBV模式的时候由于需要调用dispatch方法，必须在url中的视图后添加as_view()方法
urlpatterns = [
    path('order1/', views.Order.as_view()),
]

# 基于CBV模式进行接口的开发
from django.views import View
from django.utils.decorators import method_decorator

@method_decorator(csrf_exempt, name='dispatch')
class Order(View):
    def get(self, request, *args, **kwargs):
        return HttpResponse("获取一条或者多条订单")
    
    def post(self, request, *args, **kwargs):
        return HttpResponse("增加一条订单")
    
    def put(self, request, *args, **kwargs):
        return HttpResponse("更新一条订单")
    
    def delete(self, request, *args, **kwargs):
        return HttpResponse("删除一条订单")

四、RESTful规范

RESTful规范是一种网络架构风格，它结构清晰、符合标准、易于理解、扩展方便，所以正得到越来越多网站的采用。但是是否遵循该规范以及如何遵循该规范需要根据具体的业务需求来决定。深入理解RESTful规范

RESTful API设计
- HTTPs规范。API与用户通信协议，总是使用HTTPs协议，这个协议比HTTP更加安全
- 域名规范：
  - 方式一：把www.换成api. 例如：正常的子域名是https://www.baidu.com，如果使用api接口，可以把子域名设置成https://api.baidu.com进行区分。但是需要注意的是，这种方式需要开发者自己来解决跨域请求的问题。
  - 方式二：同一个域名，在url设置上进行区分，在域名后添加api，例如：正常的url是https://www.baidu.com，API接口的url可以设置成https://www.baidu.com/api/，这种设置由于域名是同一个域名，不存在跨域请求的问题，使用更加的方便。
- 版本规范。程序的开发过程中会不断的升级，每一次升级都是一个版本，所以开发者需要给程序添加版本用于区分。添加的方式有两种：
  - 方式一：把版本号添加到url后，例如设置https://www.baidu.com/api/v1/，v1既是开发的版本号。
  - 方式二：把版本好添加到请求头上
    
    一般情况下使用的是第一种方式
- 路径规范。面向资源编程：把网络上的任何内容都看作是资源，对资源进行增、删、改、查操作。基于面向资源，API接口url设置上尽量使用名词来设置，可以写复数形式。例如：设置https://www.baidu.com/api/v1/source/，注意：source为名词，如果设置成get_source则是动词形式的。
- method规范。
  - GET: 从服务器上获取一项或多项资源
  - PUT: 在服务器上更新资源(客户端提供改变后的完整资源)
  - PATCH: 在服务器上更新资源(客户端提供改变的属性)
  - DELETE: 从服务器上删除资源
  - POST: 在服务器上新建一个资源
- 过滤规范。通过在url上传参的形式传递搜索条件，例如：设置https://www.baidu.com/api/v1/source/?name=李明&age=23
- 状态码规范。常用的状态码如下：
  - 200 OK 服务器返回用户请求的数据，该操作是幂等的
  - 201 CREATED 新建或者修改数据成功
  - 204 NOT CONTENT 删除数据成功
  - 400 BAD REQUEST 用户发出的请求有问题，该操作是幂等的
  - 401 Unauthoried 表示用户没有认证，无法进行操作
  - 403 Forbidden 用户访问是被禁止的
  - 422 Unprocesable Entity 当创建一个对象时，发生一个验证错误
  - 500 INTERNAL SERVER ERROR 服务器内部错误，用户将无法判断发出的请求是否成功
  - 503 Service Unavailable 服务不可用状态，多半是因为服务器问题，例如CPU占用率大，等等
    
    Note
    在实际的项目开发中，可能会出现很多的情况，虽然现有的status_code已经有很多，但并不能包括所有的情况，所以，需要把status_code与code相结合来使用，code由开发者自己定义值和所代表的情况，当然status_code和code都可单独使用。
- 错误处理规范。状态码为4xx时需要返回错误信息提示，默认error为返回的字典中的key，当然也可以自己定义。例如：{ error: 'Invalid API key' }
- 返回结果规范。针对不同的操作返回不同的结果。这些结果应该符合restful规范：
  - GET/collection: 返回资源对象的列表(数组)
  - GET/collection/resource: 返回单个资源对西那个
  - POST/collection: 返回新生成的资源对象
  - PUT/collection/resource: 返回更新后的完整的资源对象
  - PATCH/collection/resource: 返回更新后的完整资源对象
  - DELETE/collection/resource: 删除后返回一个空文档
    
    Note
    resource一般指的是数据中的pk值
- Hypermedia API规范。RESTful API最好做到Hypermedia，即返回的结果中提供链接，连向其他API的方法，使得用户不查文档也知道下一步做什么。例如：
```
  { 
      "link": {
          "rel": "collection https://www.example.com/zoos",
          "href": "https://api.example.com/zoos",
          "title": "List of zoos",
          "type": "application/vnd.yourformat+json"
      }

  }
```

加载全部内容