Django REST framework API开发

最新推荐文章于 2024-05-14 15:45:21 发布

Ayhan_huang

最新推荐文章于 2024-05-14 15:45:21 发布

阅读量4.3k

点赞数 2

分类专栏： Django API 文章标签： django api rest

本文链接：https://blog.csdn.net/Ayhan_huang/article/details/78585815

版权

REST

介绍

RESTful API 设计

实现API的两种方式

FBV 视图函数

urlpatterns = [
    url(r'^user/$', views.user),
    url(r'^user/add/$', views.user_add),
    url(r'^user/edit/(\d+)/$', views.user_edit),
    url(r'^user/del/(\d+)/$', views.user_del),
]

传统的视图函数方式，API接口太多，难以维护。

CBV 视图类

urlpatterns = [
    url(r'user/$', views.UserView.as_view()),  # GET, POST
    url(r'user/(\d+)$', views.UserView.as_view()),  # PUT, DELETE
]

根据请求方式的不同，执行视图类中对应的方法。同样是实现增删改查，url少一半。这也是面向资源编程的方式，特点是url中都是名词。

协议

大神说：API与用户的通信协议，总是使用HTTPs协议

域名

http://api.example.com 尽量使用专用的二级域名
http://www.example.com/api/ 路由分发。如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。

对应前后端分离的项目，可以这样分配：

前端VUE项目使用域名：http://www.example.com

后端API使用域名：http://api.example.com

版本

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

比如：https://www.example.com/api/v1/ v1是版本信息

路径

路径又称”终点”（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

method

GET ：从服务器取出资源（一项或多项）
POST ：在服务器新建一个资源
PUT ：在服务器更新资源（客户端提供改变后的完整资源，全部更新）
PATCH ：在服务器更新资源（客户端提供改变的属性，局部更新）
DELETE ：从服务器删除资源
HEAD：和GET一样，只是只返回响应首部，不返回响应体，用于确认资源的信息
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：删除某个指定动物园的指定动物

状态码

HTTP状态码负责表示客户端HTTP请求的返回结果，标记服务端的处理是否正常，通知出现的错误等工作。

状态码类别

状态码	类别	原因短语
1XX	Informational 信息性状态码	接收的请求正在处理
2XX	Success 成功状态码	请求正常处理完毕
3XX	Redirection 重定向状态码	需要进行附加操作以完成请求
4XX	Client Error 客户端错误状态码	服务器无法处理请求
5XX	Server Error 服务器错误状态码	服务器处理请求出错

常用状态码一览

200 OK：客户端发来的请求在服务端被正常处理了。
201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
204 NO CONTENT ：请求已成功处理，但响应中不包含响应体。比如请求方式为[DELETE]时，表示用户删除数据成功。
206 Partial Content: 服务器成功执行了客户端的范围请求。响应中包含由Content-Range首部字段指定范围的实体内容
301 Moved Permanently: 永久性重定向，请求的资源已被分配了新的URI。应该按Location首部字段提示的URI访问。
302 Found, 303 See Other, 307 Temporary Redirect 都是临时性重定向，请求的资源已被临时分配了新的URI，希望用户本次使用新的URI访问。标准不太统一，每种浏览器可能出现不同的情况，了解即可。
304 Not Modified: 这个比较特殊，和重定向没有关系，表示服务器资源未改变，可直接使用客户端缓存。
400 Bad Request：用户发出的请求报文中存在语法错误，需要修改请求内容后再发送。
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 - [*]：服务器发生错误，可能外web应用存在bug。
503 Service Unavailable: 服务器正忙

状态码有限，可以再约定code，表示更细的状态：

def get(self, request, *args, **kwargs):
    res = {
  'code': 1001, 'error': None}

    try:
        print('do something...')
    except Exception as e:
        res['error'] = str(e)

    return JsonResponse(res, status=500)

错误处理

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

{
    error: "Invalid API key"
}

提供error key，显示详细错误信息

过滤

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

?limit=1：指定返回记录的数量
?offset=10：指定返回记录的开始位置
?page=2$per_page=10：指定第几页，以及每页的记录数
?sortby=name$order=asc：指定返回结果按照哪个属性排序，以及排序顺序
?id=10：指定筛选条件

返回结果

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

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

Hypermedia

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"
}

上面代码表示，服务器给出了提示信息，以及文档的网址。

Django REST framework

通过Django本身也可以实现API设计，只是相对要麻烦些。Django REST framework基于Django进行了丰富，能更方便的实现API设计。

基本使用

settings

INSTALLED_APPS = [
    # ...
    'rest_framework',
]

路由

urlpatterns = [
    url(r'user/$', views.UserView.as_view()),  # GET, POST
    url(r'user/(?P<pk>\d+)/$', views.UserView.as_view()),  # PUT, DELETE
]

视图

from rest_framework.views import APIView
from django.http import JsonResponse

class UsersView(APIView):
    def dispatch(self, request, *args, **kwargs):
        """请求到来之后，首先执行dispatch方法，dispatch方法根据请求方式的不同，反射执行 get/post/put等方法"""
        return super().dispatch(request, *args, **kwargs)

    def get(self, request, *args, **kwargs):

        res = {
            'code': '10001',
            'data': [],  # 字典元素
            'error': None
        }

        # return HttpResponse(json.dumps(res), status=200, content_type='application/json')
        # 如果是HttpResponse，需要手动json, 并且指定content_type
        return JsonResponse(res, status=200)

    def post(self, request, *args, **kwargs):
        pass

    def put(self, request, *args, **kwargs):
        pk = kwargs.get('pk')  # 获取url命名分组传参
        pass

    def delete(self, request, *args, **kwargs):
        pass

生命周期

中间件
路由系统
- .as_view() 方法：return csrf_exempt(view)

CBV视图类

执行dispatch方法

二次封装request

def initialize_request(self, request, *args, **kwargs):
    parser_context = self.get_parser_context(request) # 

    return Request(
        request,
        parsers=self.get_parsers(),  # 解析器
        authenticators=self.get_authenticators(),  # 认证
        negotiator=self.get_content_negotiator(),  # 选择器
        parser_context=parser_context  # 字典：view和参数
    )

try:

获取版本，认证，权限，节流

def initial(self, request, *args, **kwargs):
        """
        Runs anything that needs to occur prior to calling the method handler.
        """
        self.format_kwarg = self.get_format_suffix(**kwargs)

        # Perform content negotiation and store the accepted info on the request
        # 根据用户请求选择
        neg = self.perform_content_negotiation(request)
        request.accepted_renderer, request.accepted_media_type = neg

        # Determine the API version, if versioning is in use.
        # 获取版本信息，和处理版本的类的对象
        version, scheme = self.determine_version(request, *args, **kwargs)
        request.version, request.versioning_scheme = version, scheme

        # Ensure that the incoming request is permitted
        # 认证
        self.perform_authentication(request)
        # 权限
        self.check_permissions(request)
        # 控制访问次数（每天访问10次）
        self.check_throttles(request)

根据请求方法反射执行 GET/POST/DELETE…

except:
- 处理异常
返回响应

版本

查看源码可知，Django REST framework一共支持5种版本控制方式：

AcceptHeaderVersioning
URLPathVersioning
NamespaceVersioning
HostNameVersioning
QueryParameterVersioning

导入及使用方式：

from rest_framework.versioning import URLPathVersioning

class TestView(APIView):
    versioning_class = URLPathVersioning  # 指定版本
    pass

版本控制中通用的settings全局配置：

REST_FRAMEWORK = {
    # 'DEFAULT_VERSION': 'v1', # 默认版本
    # 'ALLOWED_VERSIONS': ['v1', 'v2'], # 允许的版本
}

下面介绍其中两种比较常用获取版本的方式。

基于查询字符串传参

settings配置

REST_FRAMEWORK = {
    'VERSION_PARM': 'version' # 配置从URL中获取值的key
}

urls配置

urlpatterns = [
    url(r'test', views.TestView.as_view(), name='test')
]

CBV

from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework.versioning import QueryParameterVersioning


class TestView(APIView):
    versioning_class = QueryParameterVersioning  # 指定版本

    def get(self, request, *args, **kwargs):
        # 获取版本
        print(request.version)

        # 获取版本管理的类
        print(request.versioning_scheme)

        # 反向生成url
        reverse_url = request.versioning_sch

最低0.47元/天解锁文章

Ayhan_huang

关注

2
点赞
踩
11

收藏

觉得还不错? 一键收藏
0
评论
Django REST framework API开发

REST介绍RESTful API 设计实现API的两种方式FBV 视图函数urlpatterns = [ url(r'^user/$', views.user), url(r'^user/add/$', views.user_add), url(r'^user/edit/(\d+)/$', views.user_edit), url(r'^user/del/(\d+
复制链接

扫一扫