IT教程 ·

API 接口设计规范

概述

这篇文章分享 API 接口设想范例,目标是供应给研发职员做参考。

范例是死的,人是活的,愿望本身定的范例,不要被打脸。

路由定名范例

行动 前缀 备注
猎取 get get{XXX}
猎取 get get{XXX}List
新增 add add{XXX}
修正 update update{XXX}
保留 save save{XXX}
删除 delete delete{XXX}
上传 upload upload{XXX}
发送 send send{XXX}

要求体式格局

要求体式格局 形貌
GET 猎取数据
POST 新增数据
PUT 更新数据
DELETE 删除数据

要求参数

Query

url?背面的参数,寄存要求接口的参数数据。

Header

要求头,寄存大众参数、requestId、token、加密字段等。

Body

Body 体,寄存要求接口的参数数据。

大众参数

APP 端要求

参数 申明 备注
network 网络 WIFI、4G
operator 运营商 中国联通/挪动
platform 平台 iOS、Android
system 体系 ios 13.3、android 9
device 装备型号 iPhone XR、小米9
udid 装备唯一标示
apiVersion API 版本号 v1.1、v1.2

WEB 端要求

参数 申明 备注
appKey 受权Key 字符串

挪用方需向效劳方请求 appKey(要求时运用) 和 secretKey(加密时运用)。

平安范例

敏感参数加密处置惩罚

登录暗码、付出暗码,需加密后传输,发起运用非对称加密

其他范例

  • 参数定名范例 发起运用驼峰定名,首字母小写。
  • requestId 发起照顾唯一标示追踪问题。

返回参数

参数 范例 申明 备注
code Number 效果码 胜利=1
失利=-1
未登录=401
无权限=403
showMsg String 显现信息 体系忙碌,稍后重试
errorMsg String 错误信息 便于研发定位问题
data Object 数据 JSON 花样

如有分页数据返回的,花样以下

{
    "code": 1,
    "showMsg": "success",
    "errorMsg": "",
    "data": {
        "list": [],
        "pagination": {
            "total": 100,
            "currentPage": 1,
            "prePageCount": 10
        }
    }
}

平安范例

敏感数据脱敏处置惩罚

用户手机号、用户邮箱、身份证号、付出账号、邮寄地点等要举行脱敏,部份数据加 * 号处置惩罚。

其他范例

  • 属性名定名时,发起运用驼峰定名,首字母小写。
  • 属性值为空时,严厉按范例返回默认值。
  • 金额范例/时候日期范例的属性值,假如仅用来显现,发起后端返回能够显现的字符串。
  • 营业逻辑的状况码和对应的案牍,发起后端两者都返回。
  • 挪用方不需要的属性,不要返回。

署名设想

署名考证没有肯定的范例,本身制订就行,能够挑选运用 对称加密非对称加密单向散列加密 等,分享下原来写的署名考证,供参考。

  • Go 署名考证
  • PHP 署名考证

日记平台设想

日记平台有利于毛病定位和日记统计剖析。

日记平台的搭建能够运用的是 ELK 组件,运用 Logstash 举行网络日记文件,运用 Elasticsearch 引擎举行搜刮剖析,终究在 Kibana 平台展现出来。

幂等性设想

我们没法保证接口的每一次挪用都是有返回效果的,要考虑到涌现网络非常的状况。

举个例子,定单建立时,我们需要去减库存,这时候接口发生了超时,挪用方举行了重试,这时候是不是会多扣一次库存?

处理这类问题有 2 种计划:

一、效劳方供应响应的查询接口,挪用方在要求超时后举行查询,假如查到了,示意要求处置惩罚胜利了,没查到就走失利流程。

二、挪用方尽管重试,效劳方保证一次和屡次的要求效果是一样的。

关于第二种计划,就需要效劳方的接口支撑幂等性。

大抵设想思绪是如许的:

  1. 挪用接口前,先猎取一个全局唯一的令牌(Token)
  2. 挪用接口时,将 Token 放到 Header 头中
  3. 剖析 Header 头,考证是不是为有用 Token,无效直接返回失利
  4. 完成营业逻辑后,将营业效果与 Token 举行关联存储,设置失效时候
  5. 重试时不要从新猎取 Token,用要上次的 Token

小结

限流设想、熔断设想、降级设想,这些就不多说了,由于大部份都用不到,当用上了基本上也都在网关中加这些功用。

临时就想到这么多,范例这东西不是原封不动的,发现有不妥的实时调解吧。

引荐浏览

  • 一线手艺管理者究竟在管什么事?
  • 一个人被选拔,不仅仅是才能,而是信托

参与评论