最新公告
  • 新注册用户请前往个人中心绑定邮箱以便接收相关凭证邮件!!!点击前往个人中心
  • 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 格式

    若有分页数据返回的,格式如下

    1. {
    2. "code": 1,
    3. "showMsg": "success",
    4. "errorMsg": "",
    5. "data": {
    6. "list": [],
    7. "pagination": {
    8. "total": 100,
    9. "currentPage": 1,
    10. "prePageCount": 10
    11. }
    12. }
    13. }

    安全规范

    敏感数据脱敏处理

    用户手机号、用户邮箱、身份证号、支付账号、邮寄地址等要进行脱敏,部分数据加 * 号处理。

    其他规范

    • 属性名命名时,建议使用驼峰命名,首字母小写。
    • 属性值为空时,严格按类型返回默认值。
    • 金额类型/时间日期类型的属性值,如果仅用来显示,建议后端返回可以显示的字符串。
    • 业务逻辑的状态码和对应的文案,建议后端两者都返回。
    • 调用方不需要的属性,不要返回。

    签名设计

    签名验证没有确定的规范,自己制定就行,可以选择使用 对称加密非对称加密单向散列加密 等,分享下原来写的签名验证,供参考。

    日志平台设计

    日志平台有利于故障定位和日志统计分析。

    日志平台的搭建可以使用的是 ELK 组件,使用 Logstash 进行收集日志文件,使用 Elasticsearch 引擎进行搜索分析,最终在 Kibana 平台展示出来。

    幂等性设计

    我们无法保证接口的每一次调用都是有返回结果的,要考虑到出现网络异常的情况。

    举个例子,订单创建时,我们需要去减库存,这时接口发生了超时,调用方进行了重试,这时是否会多扣一次库存?

    解决这类问题有 2 种方案:

    一、服务方提供相应的查询接口,调用方在请求超时后进行查询,如果查到了,表示请求处理成功了,没查到就走失败流程。

    二、调用方只管重试,服务方保证一次和多次的请求结果是一样的。

    对于第二种方案,就需要服务方的接口支持幂等性。

    大致设计思路是这样的:

    • 调用接口前,先获取一个全局唯一的令牌(Token)
    • 调用接口时,将 Token 放到 Header 头中
    • 解析 Header 头,验证是否为有效 Token,无效直接返回失败
    • 完成业务逻辑后,将业务结果与 Token 进行关联存储,设置失效时间
    • 重试时不要重新获取 Token,用要上次的 Token

    小结

    限流设计、熔断设计、降级设计,这些就不多说了,因为大部分都用不到,当用上了基本上也都在网关中加这些功能。

    暂时就想到这么多,规范这东西不是一成不变的,发现有不妥的及时调整吧。

    本站所有文章均由网友分享,仅用于参考学习用,请勿直接转载,如有侵权,请联系网站客服删除相关文章。若由于商用引起版权纠纷,一切责任均由使用者承担
    极客文库 » API 接口设计规范

    常见问题FAQ

    如果资源链接失效了怎么办?
    本站用户分享的所有资源都有自动备份机制,如果资源链接失效,请联系本站客服QQ:2580505920更新资源地址。
    如果用户分享的资源与描述不符怎么办?
    可以联系客服QQ:2580505920,如果要求合理可以安排退款或者退赞助积分。
    如何分享个人资源获取赞助积分或其他奖励?
    本站用户可以分享自己的资源,但是必须保证资源没有侵权行为。点击个人中心,根据操作填写并上传即可。资源所获收益完全归属上传者,每周可申请提现一次。
    如果您发现了本资源有侵权行为怎么办?
    及时联系客服QQ:2580505920,核实予以删除。

    参与讨论

    • 211会员总数(位)
    • 3737资源总数(个)
    • 0本周发布(个)
    • 0 今日发布(个)
    • 869稳定运行(天)

    欢迎加入「极客文库」,成为原创作者从这里开始!

    立即加入 了解更多
    成为赞助用户享有更多特权立即升级