基于 Django REST Framework 实现业务 api 并自动文档化-白红宇

使用MySql替换SQL

业务场景下，还是需要使用扩展性较好的Mysql等主流数据库，SQL只适合入门调试使用。

为Django项目创建数据库

create database rouboinfo default charset utf8 collate utf8_general_ci;复制代码

配置Django项目的数据库信息

## settings.pyDATABASES = {    'default': {        'ENGINE': 'django.db.backends.mysql',        'NAME': 'rouboinfo',        'USER': 'root',        'PASSWORD': 'junjian11',        'HOST': '127.0.0.1'    }}复制代码

## top __init__.pyimport pymysqlpymysql.install_as_MySQLdb()复制代码

初始化数据库

python manage.py makemigrationspython manage.py migrate复制代码

观察mysql内的数据库是否初始化完成

mysql> use rouboinfo;Reading table information for completion of table and column namesYou can turn off this feature to get a quicker startup with -ADatabase changedmysql> show tables;+----------------------------+| Tables_in_rouboinfo        |+----------------------------+| auth_group                 || auth_group_permissions     || auth_permission            || auth_user                  || auth_user_groups           || auth_user_user_permissions || django_admin_log           || django_content_type        || django_migrations          || django_session             |+----------------------------+10 rows in set (0.00 sec)复制代码

Django ORM 实践

Django通过自定义Python类的形式来定义具体的模型，每个模型的物理存在方式就是一个Python的类Class，每个模型代表数据库中的一张表，每个类的实例代表数据表中的一行数据，类中的每个变量代表数据表中的一列字段。Django通过模型，将Python代码和数据库操作结合起来，实现对SQL查询语言的封装。也就是说，你可以不会管理数据库，可以不会SQL语言，你同样能通过Python的代码进行数据库的操作。Django通过ORM对数据库进行操作，奉行代码优先的理念，将Python程序员和数据库管理员进行分工解耦。

ORM（Object-Relational Mapping) 即对象-关系映射，从效果上看，实现了一个可在编程语言里直接使用的虚拟对象数据库。这种思想在很多架构设计中都有体现，android开发中常用的GreenDao就是一个轻量的ORM设计。

设计model（即数据库结构）

因为Django的model机制是ORM的一种实践，所以说，设计了model，就设计了数据库结构。这里我们只演示一个记录设备启动次数的api接口所需的基本字段。

from django.db import modelsclass DeviceReport(models.Model):    """    收集设备相关的统计数据    report_id        自增id作为主键    report_type        上报类型，比如启动上报：open    report_time        上报时间戳    device_id        可以描述设备的id    ip_address        公网ip地址       """    report_id = models.IntegerField(primary_key=True)    report_type = models.CharField(max_length=100)    report_time = models.DateTimeField(auto_now_add=True)    device_id = models.CharField(max_length=200)    ip_address = models.CharField(max_length=50)复制代码

生效数据库 在每次修改model之后，都需要进行迁移和生效动作，毕竟我们修改了数据库结构了。

» python manage.py makemigrations rouboapi                  Migrations for 'rouboapi':  rouboapi/migrations/0001_initial.py    - Create model DeviceReport» python manage.py migrate                                  Operations to perform:  Apply all migrations: admin, auth, contenttypes, rouboapi, sessionsRunning migrations:  Applying rouboapi.0001_initial... OK复制代码

执行成功后，会生成rouboapi_devicereport的表。

实现序列化器

我们使用Django REST framework 提供的序列化器简化代码。

from rest_framework import serializersfrom rouboapi.models import DeviceReportclass DeviceReportSerializer(serializers.HyperlinkedModelSerializer):    """    序列化上报接口数据    """    class Meta:        model = DeviceReport        fields = ('report_id', 'report_type', 'report_time', 'device_id', 'ip_address')复制代码

实现视图

先使用APIView来简化代码，目前还没研究清楚如果使用ViewSets实现单一的get接口（其他接口不能实现的）的方法。

from rouboapi.serializers import DeviceReportSerializerfrom rest_framework.views import APIViewfrom rest_framework.response import Responsefrom rest_framework import statusclass DeviceReport(APIView):    """    上报设备信息, 无需鉴权    """	   authentication_classes = []    permission_classes = []    def get(self, request, format=None):        serializer = DeviceReportSerializer(data=request.data)        if serializer.is_valid():            serializer.save()            return Response(serializer.data, status=status.HTTP_200_OK)        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)复制代码

接口测试

浏览器访问：，出现REST默认界面，作为接口访问时，加入format=json参数即可。

检查数据库的变化：

mysql> select * from rouboapi_devicereport;+-------------+----------------------------+-----------+------------+| report_type | report_time                | device_id | ip_address |+-------------+----------------------------+-----------+------------+| open        | 2018-08-28 11:54:08.724136 | testid    | 127.0.0.1  || open        | 2018-08-28 11:55:06.205909 | testid    | 127.0.0.1  || open        | 2018-08-28 11:55:08.746301 | testid    | 127.0.0.1  |+-------------+----------------------------+-----------+------------+复制代码

文档化

Api接口文档化功能是Django REST Framework提供的一大特色功能，操作也简单。

pip install coreapi pygments markdown复制代码

安装上面依赖包后，只要修改urls.py文件即可：

from django.conf.urls import urlfrom . import viewsfrom rest_framework.documentation import include_docs_urlsAPI_TITLE = 'roubo api documentation'API_DESCRIPTION = 'roubo api server for rouboinfo'urlpatterns = [    url(r'v1/report/$', views.DeviceReport.as_view(), name='DeviceReport'),    url(r'docs/', include_docs_urls(title=API_TITLE, description=API_DESCRIPTION, authentication_classes=[], permission_classes=[]))]复制代码

查看样式，包含交互式的接口测试功能。

完成

哔哔哔。