Django RESTframework（一）:接口与规范

1.接口

概念：

• 广义的接口：是联系两个物质的媒介，完成信息的交互
• web程序中的接口：联系前台页面与后台数据的媒介

web接口组成

• url：即接口地址

    baidu.com/api/search
    api.baidu.map/search
  

• 请求参数：前台按照约定定的key提供指定类型的数据给后台
• 响应数据：后台与数据库交互后将数据反回给前台

2.restful接口规范

• 接口规范：就是为了采用不同的后台语言，也能使用同样的接口获取到同样的数据
• 如何写接口：接口规范是规范化书写接口的，写接口要写url，响应数据

如果将请求参数也纳入考量范围，那就是在写接口文档

接口组成的两大部分

（1）url

1)用api关键字标识接口url

api.baidu.com | www.baidu.com/api

2)接口数据安全性决定优先选择https协议

3)如果接口有多个版本存在，需要在url中标识体现

api.baidu.com/v1/ | api.baidu.com/v2/

4)接口参数的数据源称之为资源，在url中一般采用 资源复数 形式，一个接口可以概括对该资源的多种操作方式

api.baidu.com/books(推荐) | api.baidu.com.books/pk (推荐)| 
api.baidu.com/delete_book（不推荐）

5)请求方式有多种，用一个url处理如何保证不混乱-通过请求方式标识操作资源方式

/books        get      获取所有
/books        post     增加一个（多个）
/books/pk     delete   删除一个
/books/pk     put      整体更新
/books/pk     patch    局部更新

6. 资源往往涉及数据的各种操作方式 - 筛选、排序、限制

api.baidu.com/books/?search=钢铁&ordering=-price&limit=3

（2）响应数据

1. http请求的响应会有响应状态码，接口用来返回操作的资源数据，可以拥有操作数据结果的状态码:

status :0(操作资源成功) 1（操作资源失败）2（操作资源成功，但是没有匹配结果）

注：资源状态码不像http状态码，一般是后台与前台或是客户约定好的

2）资源的状态码文字提示

message: '操作成功' '账号有误' '密码有误' '用户锁定'

3. 资源本身

results:[]

注：删除资源成功不做任何数据返回(返回空字符串)

4)不能直接返回的资源（子资源、图片、视频等资源），返回该资源的url链接

例子

url: https://api.baidu.com/v1/books
methods:get|post|put|patch|delete|
{
    "status":0,
    "msg":"ok",
    "results":[
            {
                "title":*,
                "price":*,
                "img":"https://*"
            }
        ]
}

3.遵循restful的Django原生接口

• models.py

from django.db import models


class Book(models.Model):
    title = models.CharField(max_length=64)
    price = models.DecimalField(max_digits=5, decimal_places=2)

    class Meta:
        db_table = 'book'
        verbose_name = '书籍'
        verbose_name_plural = verbose_name

    def __str__(self):
        return f"《{self.title}》"

• admin.py

from django.contrib import admin


from . import models

admin.site.register(models.Book)

• views.py

from django.http import JsonResponse
from django.views import View

from . import models


class Book(View):

    def get(self, request, *args, **kwargs):
    # 序列化过程
        pk = kwargs.get('pk')
        # 群查
        if not pk:
            books_qs = models.Book.objects.all()
            books = []
            for book in books_qs:
                book_info = {}
                book_info['title'] = book.title
                book_info['price'] = book.price
                books.append(book_info)
            return JsonResponse({"status": 0, 'msg': "ok", 'results': books}, json_dumps_params={"ensure_ascii": False})
        # 单查
        else:

            book = models.Book.objects.filter(pk=pk).values('title', 'price').first()

            return JsonResponse({"status": 0, 'msg': "ok", 'results': book}, json_dumps_params={"ensure_ascii": False})

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

        # 反序列化过程
        try:
            book_obj = models.Book.objects.create(**request.POST.dict())
            if book_obj:
                return JsonResponse(
                    {"status": 0, 'msg': "ok", 'results': {'title': book_obj.title, 'price': book_obj.price}},
                    json_dumps_params={"ensure_ascii": False})
        except:
            return JsonResponse({"status": 1, 'msg': "参数有误"}, json_dumps_params={"ensure_ascii": False})
        return JsonResponse({"status": 2, 'msg': "新增失败"}, json_dumps_params={"ensure_ascii": False})

• api/url.py

from django.contrib import admin
from django.urls import path,include
from . import views

urlpatterns = [
    path('books/', views.Book.as_view()),
    path('books/<pk>', views.Book.as_view()),

]

• url.py

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include('api.urls'))

]

4.实际业务上常见的十大接口类型

• 六大基础接口：

 获取单个，获取所有, 增加单个， 删除单个，整体更新单个， 局部更新多个

• 十大接口：

 群增，群删，整体群改，局部群改 + [六大基础接口]