Web API接口规范与测试方法

目录

• 1.Web API接口
  • 1.1接口的四大特点
  • 1.2接口文档的编写：YApi
  • 1.3接口测试工具：Postman
• 2.接口规范(restful)
  • 2.1URL设计
    • 2.1.1 数据的安全保障(https)
    • 2.1.2 接口特征表现
    • 2.1.3 多数据版本共存
    • 2.1.4 数据即是资源
    • 2.1.5 资源操作由请求方式决定
  • 2.2响应状态码
    • 2.2.1 正常响应
    • 2.2.2 重定向响应
    • 2.2.3 客户端异常
  • 2.2.4 服务器异常
  • 2.3 响应结果
    • 2.3.1 响应数据要有状态码、状态信息以及数据本身
      • 数据状态码：
      • 数据状态信息
• 3.CBV（as_view()） 源码分析
• 4.使用pycharm查看一个py文件的成员
• 5.Pycharm debug窗口的使用

1.Web API接口

接口：规定了提交请求参数的请求方式、访问其可以获取相应的反馈数据的url链接，四部分：url链接 + 请求方式 + 请求参数 + 响应数据。

1.1接口的四大特点

• url：长得像返回数据的url链接

  • https://api.map.baidu.com/place/v2/search

• 请求方式：get、post、put、patch、delete

  • 采用get方式请求上方接口

• 请求参数：json或xml格式的key-value类型数据

  • ak：6E823f587c95f0148c19993539b99295
  • region：上海
  • query：肯德基
  • output：json

• 响应结果：json或xml格式的数据

  • 上方请求参数的output参数值决定了响应数据的格式

  • {
        "status":0,
        "message":"ok",
        "results":[
            {
                "name":"肯德基(罗餐厅)",
                "location":{
                    "lat":31.415354,
                    "lng":121.357339
                },
                "address":"月罗路2380号",
                "province":"上海市",
                "city":"上海市",
                "area":"宝山区",
                "street_id":"339ed41ae1d6dc320a5cb37c",
                "telephone":"(021)56761006",
                "detail":1,
                "uid":"339ed41ae1d6dc320a5cb37c"
            }
            ...
            ]
    }
    

1.2接口文档的编写：YApi

YApi是去哪网大前端技术中心的一个开源可视化接口管理平台。

YApi项目可以搭建在任何本地或云服务器上，完成后台项目开发时的接口编写。为开发、测试等人员提供可视化的接口预览。

去哪同时在网上提供了YApi的测试网站：http://yapi.demo.qunar.com/，我们可以通过测试网站了解YApi是如何进行接口的编写的

• 访问测试网站

• 创建接口项目

• 创建接口

• 编写接口

1.3接口测试工具：Postman

Postman是一款接口调试工具，是一款免费的可视化软件，同时支持各种操作系统平台，是测试接口的首选工具。

Postman可以直接从官网：https://www.getpostman.com/downloads/下载获得，然后进行傻瓜式安装。

• 工作面板

• 简易的get请求

• 简易的post请求

• 案例：请求百度地图接口

2.接口规范(restful)

RESTful（Representational State Transfer）是目前较为流行的Web API 的设计规范，特点：简单、易上手。

2.1URL设计

2.1.1 数据的安全保障(https)

• url链接一般都采用https协议进行传输

  注：采用https协议，可以提高数据交互过程中的安全性

2.1.2 接口特征表现

接口用来操作数据，与网址(操作页面)有区别，所以用特定的关键字表示接口。

• 用api关键字标识接口url：

  • https://api.baidu.com
  • https://www.baidu.com/api

  注：看到api代表该请求url链接是完成前后台数据交互的。

2.1.3 多数据版本共存

• 如果一个资源存在多版本结果，在url链接中要用特定符号来兼容多版本共存如v1,v2

  • https://api.baidu.com/v1
  • https://api.baidu.com/v2

  注：url链接中的v1、v2就是不同数据版本的体现

2.1.4 数据即是资源

• 接口一般都是完成前后台数据的交互，交互的数据我们称之为资源

  • https://api.baidu.com/users
  • https://api.baidu.com/books
  • https://api.baidu.com/book

  注：一般提倡用资源的复数形式，在url链接中尽量不要出现操作资源的动词，错误示范：https://api.baidu.com/delete-user

• 特殊的接口可以出现动词，因为这些接口一般没有一个明确的资源，或是动词就是接口的核心含义

  • https://api.baidu.com/place/search
  • https://api.baidu.com/login

• 群资源操作，一般还有额外的限制条件，如排序、限制调试、分页等等，如：

  • https://api.baidu.com/v1/books/?ordering=-price&limit=3

2.1.5 资源操作由请求方式决定

• 操作资源一般都会涉及到增删改查，我们提供请求方式来标识增删改查动作

• get:获取单个或多个资源

  • https://api.baidu.com/books - get请求：获取所有书
  • https://api.baidu.com/books/1 - get请求：获取主键为1的书

• post：新增单个或多个资源

  • https://api.baidu.com/books - post请求：新增一本书
    单增，提交单个数据字典，完成单增，返回单个结果对象
    群增，提供多个数据字典的数组，完成群增，返回多个结果对象

• put：整体修改单个或多个资源

  • https://api.baidu.com/books/1 - put请求：整体修改主键为1的书，完成单改，返回单个结果对象

  • https://api.baidu.com/books/ 整体修改多个数据，提供多个数据字典的数字(数据字典要包含主键)，完成群改，返回多个结果对象

• patch：局部修改单个或多个资源，修改方式与put完全相同，不同的是操作的资源如果有多个k-v键值对，put请求返回的字典包含所有数据，而patch请求返回的数据则可以是字典中任意的(可选择，指定的一个或多个)键值对。

• delete：删除单个或多个资源，

单删，不需要提供额外数据，完成单删，不做任何资源返回(一般我们会返回结果信息：成功|失败)

• https://api.baidu.com/books/1 删除主键为1的书

多删，提供多个资源主键数据，完成群删，不做任何资源返回(一般我们会返回结果信息：成功|失败)

• https://api.baidu.com/books/(pk)/

2.2响应状态码

网络状态码和网络状态信息捆绑出现，不要额外设置

2.2.1 正常响应

• 响应状态码2xx
  • 200：常规请求
  • 201：创建成功

2.2.2 重定向响应

• 响应状态码3xx
  • 301：永久重定向
  • 302：暂时重定向

2.2.3 客户端异常

• 响应状态码4xx
  • 403：请求无权限
  • 404：请求路径不存在
  • 405：请求方法不存在

2.2.4 服务器异常

• 响应状态码5xx
  • 500：服务器异常

2.3 响应结果

2.3.1 响应数据要有状态码、状态信息以及数据本身

数据状态码：

'''
0:成功
1:失败     1xx：具体失败信息(要在接口文档中明确写出)
2:无数据   2xx：具体无数据信息(要在接口文档中明确写出)
'''

数据状态信息

数据状态信息一般不仅仅是对数据状态码的解释，更多是对结果的描述，给前台开发者阅读的。

{
    "status": 0,
    "msg": "ok",
    "results":[
        {
            "name":"肯德基(罗餐厅)",
            "location":{
                "lat":31.415354,
                "lng":121.357339
            },
            "address":"月罗路2380号",
            "province":"上海市",
            "city":"上海市",
            "area":"宝山区",
            "street_id":"339ed41ae1d6dc320a5cb37c",
            "telephone":"(021)56761006",
            "detail":1,
            "uid":"339ed41ae1d6dc320a5cb37c"
        }
        ...
        ]
}

数据结果(常量、数组、字典)，如果有子资源(图片、音频、视频)，返回资源的url链接。

{
    "status": 0,
    "msg": "ok",
    "results":[
        {
            "name":"肯德基(罗餐厅)",
            "img": "https://image.baidu.com/kfc/001.png"
        }
        ...
        ]
}

3.CBV（as_view()） 源码分析

Django项目启动，启动入口为manage.py，先加载settings文件，settings文件通过字符串反射的方法加载配置文件的属性和方法，如果我们在配置文件中将某个app注释掉在其他app中也没有导入该app的文件，那么该app在启动时将不被项目加载（也不会被编译）。

CBV的路由层：

from . import views
from django.conf.urls import url

urlpatterns = [

    url(r'^books/$',views.BookView.as_view()),
    url(r'^books/(?P<pk>d+)/$',views.BookView.as_view()),

]

这里as_view是BookView的基类的方法，当项目启动时as_view都做了哪些事情呢，来看as_view的源码：

    @classonlymethod
    def as_view(cls, **initkwargs):#类方法，所以可以类名.方法名()调用
        """
        Main entry point for a request-response process.
        """
       # 项目刚启动时initkwargs为空，不走下面的循环
        for key in initkwargs:
            if key in cls.http_method_names:
                raise TypeError("You tried to pass in the %s method name as a "
                                "keyword argument to %s(). Don't do that."
                                % (key, cls.__name__))
            if not hasattr(cls, key):
                raise TypeError("%s() received an invalid keyword %r. as_view "
                                "only accepts arguments that are already "
                                "attributes of the class." % (cls.__name__, key))
		
        # 请求来了完成响应的函数
        #wsgi协议将浏览器发过来的数据拆分后放入request
        def view(request, *args, **kwargs):
            self = cls(**initkwargs)
            #类实例化的对象
            
            #利用反射添加get请求，get和head一样
            if hasattr(self, 'get') and not hasattr(self, 'head'):
                self.head = self.get
            # 为对象添加属性
            self.request = request
            self.args = args #无名分组参数
            self.kwargs = kwargs # 有名分组的参数 
            
            #将执行结果返回到前台
            return self.dispatch(request, *args, **kwargs)
        #下面两句的作用：将请求调用view的信息保存在view对象中
        view.view_class = cls
        #将类名添加到view的名称空间
        view.view_initkwargs = initkwargs
		#将as_view携带的参数添加到名称空间
        
        # take name and docstring from class
        update_wrapper(view, cls, updated=())

        # and possible attributes set by decorators
        # like csrf_exempt from dispatch
        update_wrapper(view, cls.dispatch, assigned=())
        
        #返回请求调用的函数地址，进行路由绑定
        return view

    def dispatch(self, request, *args, **kwargs):
        # Try to dispatch to the right method; if a method doesn't exist,
        # defer to the error handler. Also defer to the error handler if the
        # request method isn't on the approved list.
        if request.method.lower() in self.http_method_names:
            handler = getattr(self, request.method.lower(), self.http_method_not_allowed)
        else:
            handler = self.http_method_not_allowed
        return handler(request, *args, **kwargs)

dispatch方法

    def dispatch(self, request, *args, **kwargs):
        # Try to dispatch to the right method; if a method doesn't exist,
        # defer to the error handler. Also defer to the error handler if the
        # request method isn't on the approved list.
        #通过反射的方式判断请求的方法是否存在，如果存在就加()调用，不存在就报错
        if request.method.lower() in self.http_method_names:
            handler = getattr(self, request.method.lower(), self.http_method_not_allowed)
        else:
            handler = self.http_method_not_allowed
        return handler(request, *args, **kwargs)

4.使用pycharm查看一个py文件的成员

5.Pycharm debug窗口的使用

5.1 操作步骤：

5.1.1添加断点：直接在标记处点击鼠标左键即可。（删除断点只需再点击断点处即可）

5.1.2Debug下运行代码：先对需要找bug的部分代码打断点，然后点击工作栏的瓢虫，就进入了debug模式。

5.1.3按照所需调试进行代码调试。Debug的调试方式如下所示：

分别为：

1.show execution point (Alt+F10) 显示当前所有断点

2.step over(F8) 单步调试。

若函数A内存在子函数a时，不会进入子函数a内执行单步调试，而是把子函数a当作一个整体，一步执行。

3.step into(F7) 单步调试。

若函数A内存在子函数a时，会进入子函数a内执行单步调试。

4.step into my code(Alt + Shift +F7) 执行下一行但忽略libraries（导入库的语句）

5.force step into(Alt + Shift +F7) 执行下一行忽略lib和构造对象等 （目前感觉没什么用）

6.step out（Shift+F8）当目前执行在子函数a中时，选择该调试操作可以直接跳出子函数a，而不用继续执行子函数a中的剩余代码。并返回上一层函数。

7.run to cursor(Alt +F9) 直接跳到下一个断点

9.临时禁用断点，可以将断点全部禁用

10.快速查看与取消断点

11.在debug窗口查看所有变量的名称空间