API 接口设计规范

概述

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

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

路由定名范例

要求体式格局

要求参数

Query

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

Header

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

Body

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

大众参数

APP 端要求

WEB 端要求

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

平安范例

敏感参数加密处置惩罚

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

其他范例

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

返回参数

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

{
    "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

小结

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

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

引荐浏览

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