跳到主要内容

接口管理

介绍​

接口管理对于后端人员业务逻辑开发、前后端联调以及测试人员的接口测试等环节都至关重要，一个好的接口管理平台及开发规范不但能有效提高团队协作与项目交付效率，也可以在项目开发初期尽可能对系统方案设计进行完善，提升系统可维护性与拓展性。

基于 YApi 的接口设计与开发流程​

我们公司大部分项目使用『YApi』进行接口设计与文档管理，大家可以访问『纸贵 YApi 平台』并自行注册账户，当参与在建项目时让项目负责人将自己加入对应项目组，即可编辑与查看接口文档。

我们的接口设计与开发流程为：

  1. 架构师与后端开发人员根据原型及需求讨论定义 API
  2. 后端开发人员为 API 添加 mock 数据
  3. 前端开发人员使用 YApi mock server 提供的 mock 数据调试接口进行页面开发（注：在线调试需要在 Chrome 下安装对应插件，通过 Postman 等接口调试工具则可以直接调用对应 mock 接口地址）
  4. 测试人员在接口测试环境可以导出 mock 数据并结合自动化测试流程进行测试
  5. 后端开发人员接口完成后，前端与测试人员将 mock 接口更换为实际接口服务地址并进行联调
  6. 开发与测试过程中增加、删除或修改接口直接在 YApi 上进行并通知对应负责人员进行修改与调试

RESTful API 设计规范​

我们的项目往往涉及多位开发人员进行协同开发，因个人开发习惯与规范不同，往往对接口的定义方式有所差异，不利于整体项目管理与后期维护与迭代。

我们推荐采用『RESTful API 设计规范』，该仓库对当前比较流行的 RESTful API 设计规范进行了整理，提供了一些常用的规范与最佳实践，供开发人员参考。

常用规范示例​

Endpoint​

规范​

  • URL 的命名全部小写
  • 统一使用 - 进行连接
  • URL 中的资源命名必须为名词且为复数形式

示例​

  • https://api.example.com/zoos
  • https://api.example.com/animals
  • https://api.example.com/zoos/{zoo}/animals
  • https://api.example.com/animal-types

HTTP 动词​

使用​

  • GET - SELECT 获取资源
  • POST - CREATE 新建资源
  • PUT - UPDATE 更新资源
  • DELETE - DELETE 删除资源

惯例​

  • 通常我们不使用 DELETE，而是使用 PUT 更新状态为已删除
  • 部分接口更新操作可以采用 POST 而无需新增一个 PUT 接口

过滤结果​

常用过滤条件​

  • ?limit=10 指定返回记录的数量
  • ?pageNo=1&pageSize=10 指定第几页，以及每页的记录数。
  • ?sortby=name&order=asc 指定返回结果按照哪个属性排序，以及排序顺序。
  • ?id=1 指定筛选条件

鉴权​

  • Access Token 鉴权
  • Basic Auth 鉴权

返回值​

我们需要选取并定义合适状态码，不能都返回 200

查找成功​

HTTP/1.1 200 ok
Content-Type: application/json
Server: example.com
{
    "code": 0,
    "msg": "success",
    "data": {
        "username": "username"
    }
}

查找失败​

HTTP/1.1 200 ok
Content-Type: application/json
Server: example.com
{
    "code": -1,
    "msg": "该活动不存在",
}

错误返回​

{
    "code": 500,
    "msg": "错误信息",
}