实习技术总结（五）接口设计

xulei1998
330 阅读5分钟

本篇介绍了接口设计相关的知识。前后端分离就是指，前后端只通过接口通信，主要按照接口文档。

客户端与服务端如何通信

客户端

  • 用 AJAX 发送请求，接收响应
  • AJAX 就是 XMLHttpRequest 相关 API 的使用

服务端

  • 用 Node.js 接收请求，发送响应
  • 用 Cookie 和 Session 来标记用户

用例图 与 时序图

  • 用例图：梳理功能需求，方便测试，不用管具体实现
  • 时序图：按照时间顺序，展示用户与客户端、服务端的交互，分析接口

举例：用户登录的用例图、时序图 image.png 其中，用户和客户端的交互、客户端向服务端发送请求由前端负责，服务端向客户端返回响应由后端负责。

什么是接口

  • 后端提供给前端调用的 URL 地址，前端去发起请求，请求的东西就是接口，也叫后端接口。
  • 接口文档主要是后端写好，前端使用过程中发现返回的数据不对，反馈给后端来修改。
  • 交互的数据格式主要是 JSON、XML 格式的数据。 上个例子中，客户端与服务端的每一个来回就是请求、响应，每个圆圈就可以看成是一个接口。1 处是 HTML 响应，2、3 处是 JSON 响应，HTML 响应一般不算作接口，JSON、XML 响应都算接口。因此本例中需要处理两个接口，一个验证码接口，一个登录接口。

设计接口

设计接口，其实就是设计请求与响应。

  • 设计请求又分为设计请求地址、请求动词、请求数据（JSON数据）。
  • 设计响应又分为设计响应状态码、响应头Cookie、响应体（JSON数据）。

客户端发送请求 Request

1 请求地址

协议

  • HTTPS 最佳，因为安全 √
  • HTTP 也能用，容易泄密

域名

  • 接口的域名（writingai-test.inner.youdao.com）可以和网页的域名（write.inner.youdao.com）不一致
  • 不同源，跨域请求：使用 CORS

image.png

2 请求动词

  • GET：获取数据
  • POST： 提交数据 不幂等操作
  • DELETE：删除数据
  • PATCH： 局部修改数据
  • PUT：整体替换原有数据
  • 还有 HEAD、OPTIONS 等动词

3 请求数据 Payload

scene & termWord & sign

服务器返回的响应 Response

1 响应状态码 Status Code

  • 200 发送成功
  • 4xx 客户端出现错误
    • 400 客户端发送请求出错（笼统）
    • 404 请求路径有问题
    • 422 请求参数出错（具体）

2 响应头

SetCookie: session_id=xxxx; HttpOnly
  • 后端创建 session，作为服务器和用户之间的会话，session拥有id，将session的id写到响应头 Cookie 里，（为了让下次请求的时候浏览器还会带给服务器）
  • HttpOnly 是为了不允许随便改 session_id

3 响应数据

{
  "code":0,
  "msg":"OK",
  "data":"success"
}
  • 后端设计这些响应数据，前端通过 JSON.parse(response)获取响应数据

接口文档 - 写作术语库相关

功能：新增写作术语库

  • 接口路径：/writing/wordlib/addWord
  • 请求数据类型：POST
  • Request headers 
    参数类型 content-type:application/json
cookie: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  • 参数字段
    参数名称类型是否必须参数说明
    sceneIntegerYES1：点击错误卡片 2：个人中心输入
    termWordStringYES用户所增加的术语词
  • Response
    • 正常返回格式
    {
"code": 0,
"msg": "OK",
"data": "success"
}
    • 异常返回格式
    // 用户输入了某些特殊符号的情况
{
"code": 5001,
"msg": "请输入完整的单词"
}
// 用户添加个人词库的词语字符长度超过50
{
"code": 5001,
"msg": "最多输入五十个字符"
}
// 重复添加
{
"code": 5002,
"msg": "词库中已存在该词，无需添加"
}
...

总结

  • 联调：项目最开始时明确接口地址、前端请求的参数、后端返回的参数，然后两端开始写接口，写的差不多的时候，大家调接口看一下返回的数据，没问题就可以了。
  • 约定接口：后端的数据给前端用，前端明确告诉后端需要哪些数据，约定接口传入的参数，返回的数据格式。
  • 约定接口规范：
    • 当前接口的路径是什么？ 如 /writing/wordlib/addWord
    • 当前接口提交数据的类型是什么? GET / POST / PATCH / DELETE / PUT
    • 参数类型/格式，比如是 json 格式/XML格式
    • 参数字段
    • 返回的成功数据格式
    • 返回的失败数据格式
  • 模拟接口：当后端还没有提供真正的接口时，前端可以编写一个假的接口，当后端真正的开发完成后，前端只需要替换接口。

联调可能遇到的问题

  1. 后端文档不正确。首先需要后端自己确认文档正确，可能存在接口更换文档未更新的情况，也存在假如应该传的字段是‘PSC’，他文档写的是‘PS’。如果出现跨域情况，可以先尝试改一下请求方式，如：post改成get，存在请求方式和文档提供不一的情况。
  2. 返回参数错误。要先确认自己所传参数是否正确，检查无误后可以看一下，后端所需字段值是否合理。如：数据上报格式时要求，文档中不合理的，需要提醒后端确认一下是否正确。
  3. 内部错误。可能是我们传过去的json类型的字符串后端解析有问题，需要和后端确认相应字段是否进行了解析
  4. 签名错误。要先确认前后端的key和方法是否一致，遇到null、undefined、空字符串时，一定要注意，可能存在前端计算时未过滤，后端过滤的情况。
avatar
文章
阅读
粉丝