2.Restful规范

restful规范是一套主流的API规范，目的是将前后端统一规范。节省二者的沟通成本, 提高开发效率,常见的规范有以下9种

1.https协议

在实际项目部署中，使用https协议代替http，目的是为了让接口更加安全

当然https在项目开发中是不相关的

2.域名

对于后端的开发人员，在实现接口的时候，尽可能在域名上加上api的标识，如：

https://api.example.com
https://www.example.com/api/

 

 

 

3.版本

对于后端开发人员，API要体现出来版本，便于后期进行版本的管理

https://api.example.com/v1/
https://v1.api.example.com/
https://www.example.com/api/?version=1.1
或者放在请求头中
...

 

4.路径

restful规范中认为网络上的一切都是资源，针对资源可以进行增删改查的操作。URL重要使用名词，使用请求方法进行动作上的区分

https://api/users/v1/             GET方法           用户列表
https://api/users/v1/            POST方法          添加用户
https://api/users/(\d+)/v1/       GET方法           获取单条数据
https://api/users/(\d+)/v1/       DELETE方法        删除单条数据
https://api/users/(\d+)/v1/       PUT方法           更新单条全部数据
https://api/users/(\d+)/v1/       PATCH方法           更新单条局部数据

 

5.请求方法

根据方法不同进行不同的操作

GET：   在服务器获取资源（一项或者多项）
POST：  在服务器新建一个资源
PUT：   在服务器上更新资源
PATCH： 在服务器上局部更新资源
DELETE：在服务器上删除资源

 

6.搜索条件

在URL中通过参数的形式携带搜索条件，常用GET方法

https://api.example.com/v1/users?limit=10                指定返回的数据数量
https://api.example.com/v1/users?offset=10               返回指定记录的其实位置
https://api.example.com/v1/users?page=2&per_page=10      指定第几页以及每页的数量

 

 

7.相应数据

针对不同的操作，服务器响应的结果是有所不同的

URL	方法	描述	返回的数据
/users/	GET	获取数据列表	[{’name‘:'victor'},{'name':'大山'}]
/users/	POST	添加数据	返回新添加的数据对象{’name‘:'victor'},
/users/(\d+)/	GET	获取单条数据	{’name‘:'victor'}
/users/(\d+)/	DELETE	删除数据	返回一个空对象
/users/(\d+)/	PUT	更新数据	返回更新后的数据{’name‘:'victor'}
/users/(\d+)/	PATCH	局部更新	返回更新后的数据{’name‘:'victor'}

 

 

 

 

 

当然上面也不会是绝对的，每个公司都会根据自己的业务需求进行适当的调整

8.状态码

API接口除了数据以外，还会携带一些状态码，表示请求的状况，状态码也是公司自行设定的

{
    code：400，
    error:'xxx'
}

 

9.错误处理

当后端响应请求的时候，如果发生错误，也需要将错误返回给客户端

{
    code：400，
    error:'xxx'
}

 

10.案例

该案例仍然是使用Django的写法

路由：

from django.contrib import admin
from django.urls import path
from student import views
urlpatterns = [
    path('admin/', admin.site.urls),
    path('users/<str:version>/students', views.showUsers),
    path('users/<str:version>/students/<int:pk>', views.showUsers),
]

 

视图函数

from django.shortcuts import render
from django.http import JsonResponse


# Create your views here.
def showUsers(request, version, pk=None):
    # 获取版本
    print(version)
    # 没有用户ID
    if not pk:
        if request.method == "GET":
            print('获取用户列表')
            data = {
                'code': 0,
                'data': [
                    {
                        'id': 1, 'name': 'kunmzhao'
                    },
                    {
                        'id': 2, 'name': 'victor'
                    },
                    {
                        'id': 3, 'name': '大山'
                    },
                ]
            }
        elif request.method == "POST":
            # 从请求体中获取数据，添加导数据库
            data = {
                'code': 0,
                'data': {'id': 4, 'name': 'jerry'}
            }
        else:
            data = {
                'code': 100,
                'error': '请求错误'
            }
    else:
        if request.method == "GET":
            # 获取pk对应的用户数据
            data = {
                "code": 0,
                "data": [{"id": 3, "name": 'kunmzhao'}],
            }
        elif request.method == "DELETE":
            # 删除指定pk下的用户
            data = {
                "code": 0,
            }
        elif request.method == 'PUT':
            # 更新数据到数据库
            data = {
                "code": 0,
                "data": [{"id": 4, "name": 'sunny'}],
            }
        elif request.method == "PATCH":
            # 更新数据到数据库
            data = {
                "code": 0,
                "data": [{"id": 5, "name": 'wind'}],
            }
        else:
            data = {
                "code": 400,
                "error": "请求错误",
            }
    return JsonResponse(data)

 

在上面的案例中我们使用的是Django中的FBV写法，使用CBV写法如下

路由

from django.urls import path
from web import views

urlpatterns = [
    path("api/<str:version>/students/", views.Users.as_view()),
    path("api/<str:version>/students/<int:pk>", views.Users.as_view()),
]

 

视图

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


class Users(View):
    def get(self,request, version, pk=None):
        if not pk:
            # 获取用户列表
            info = {
                "code": 0,
                "data": [{"id": 1, "name": 'kunmzhao'}],
            }
            return JsonResponse(info)
        # 获取pk对应的用户数据
        info = {
            "code": 0,
            "data": [{"id": 3, "name": 'victor'}],
        }
        return JsonResponse(info)

    def post(self, request,version):
        # 新增用户，将用户添加到数据库中
        info = {
            "code": 0,
            "data": [{"id": 2, "name": 'victor'}],
        }
        return JsonResponse(info)

    def delete(self, request,version,pk):
        # 删除指定pk下的用户
        info = {
            "code": 0,
        }
        return JsonResponse(info)

    def put(self, request,version,pk):
        # 更新数据到数据库
        info = {
            "code": 0,
            "data": [{"id": 4, "name": 'sunny'}],
        }
        return JsonResponse(info)

    def patch(self, request, version, pk):
        # 更新数据到数据库
        info = {
            "code": 0,
            "data": [{"id": 5, "name": 'wind'}],
        }
        return JsonResponse(info)