No Comments

API接口设计规范

概述

这篇文章分享 API 接口设计规范，目的是提供给研发人员做参考。
规范是死的，人是活的

路由命名规范

参考RESTful设计规范：RESTful 是目前最流行的 API 设计规范，用于 Web 数据接口的设计。

版本号

版本号通常使用v1,v2表示。在代码中表现通常以模块形式存在。
例如模块目录：api/modules/v1

URL设计

RESTful的核心思想就是，客户端发出的数据+操作指令都是“动词+宾语”的结构，比如GET /articles这个命令，GET是动词，/articles是宾语，动词通常就有5种HTTP请求方法，对应CRUD操作，根据 HTTP 规范，动词一律大写。

# GET：读取（Read）
# POST：新建（Create）
# PUT：更新（Update）
# DELETE：删除（Delete）

有些客户端只能使用GET和POST这两种方法。服务器必须接受POST模拟其他三个方法（PUT、PATCH、DELETE）。这时，客户端发出的 HTTP Header 请求，要加上X-HTTP-Method-Override属性，告诉服务器应该使用哪一个动词，覆盖POST方法。

# 使用POST模拟PUT方法
POST /api/Person/4 HTTP/1.1  
X-HTTP-Method-Override: PUT

关于多级URL参数问题

# GET /authors/12/categories/2 这种不利于扩展，语义也不明确
# GET /authors/12?categories=2 这种主、次参数分开的写法比较容易理解

请求参数

查询参数(Query)
url?后面的参数，存放请求接口的参数数据。

请求头(Header)
请求头，存放公共参数、requestId、token、加密字段等。

请求体(Body)
Body 体，存放请求接口的参数数据。

APP请求的公共参数

  • Authorization 授权参数
  • Version 此次请求API的版本号
  • Platform 平台，iOS、Android、H5
  • DeviceInfo 设备信息，包括系统版本号，设备型号等
  • Network 网络，WIFI、4G
  • DeviceId 设备ID，设备唯一识别号

常用动词

  • 获取 get
  • 列表 list
  • 新增 add
  • 修改 update
  • 保存 save
  • 删除 delete
  • 上传 update

安全规范

  • 敏感参数脱敏。手机号，邮箱，身份证，支付账号，邮寄地址 等中间使用*处理

返回参数

{
     "httpcode": 200,    // http状态码
     "err": 0,           // 业务错误码，业务相关
     "msg": "消息内容",   // 错误消息，与业务相关的错误提示
     "data": []          // 返回数据
     "popup": [{          // 一次性弹窗信息，一般用在任务系统中，临时通知等
         "type": "other",   // 弹窗类型
         "content": {},     // 弹窗内容json
     }]
}

前端处理接口返回数据

  • [全局]先对返回的数据做过滤处理，例如过滤收尾空格等。
  • [全局]判断是否存在httpcode与msg字段，如果存在先判断httpcode==200，如果存在就继续处理，如果不存在就说明http消息错误，直接弹出msg的内容，并终止解析json。
  • [全局]判断是否存在err字段是否等于特殊错误码，如果匹配特殊状态码就让程序执行对应操作。特殊操作有升级 强制升级 跳转登录 跳转注册 跳转认证 等。建议前端专门用一个文件统一整理特殊状态码 的操作，也许后期会扩展特殊状态码。
  • [全局]显示弹窗信息，弹窗信息不阻碍其他信息的显示。
  • [局部]判断err==0，如果成立则解析data中的数据并展示，如果err != 0则显示错误信息。错误显示凡是目前比较常用的有，弹出提示，顶部横条提示，翻页底部提示。注意，无需在前端判断接口中有哪些err可用，遇到错误直接用通用方式（特殊展现方式除外）展示即可，方便后端扩展错误码。

后端返回格式注意事项

  • 返回值中不允许出现(null)值，因为ios与安卓处理null时会有差异，可能导致其被解释为null字符串。
  • 关于布尔值，最好使用0与1代替
  • 列表数据，当查询为空时，返回的应该是空数组[]
  • 详情数据，当查询为空时，返回的应该是空对象{}
  • 前端需要哪些字段后端就返回哪些字段，设计api接口时尽量让前端自己选择需要返回的数据，这样更通用。

采坑记录

  • 后端返回 true/false 前端解析成字符串了，建议后端用 0或1返回布尔值
  • 前端在处理删除数据时闪退了，原因是前端未做空对象和空数组的兼容问题，后端未按正确的结果返回空对象或是空数组，建议前端针对空对象和空数组做个优化。

最后更新于  2022-04-06 14:50:45  并被添加「」标签，已有 421 位童鞋阅读过。

本站使用「署名 4.0 国际」创作共享协议，可自由转载、引用，但需署名作者且注明文章出处

此处评论已关闭