编写三高API

如序

已于 2022-05-23 09:45:27 修改

阅读量132

点赞数

分类专栏：其他文章标签： java

于 2022-05-10 09:38:40 首次发布

本文链接：https://blog.csdn.net/u011937566/article/details/123541452

版权

其他专栏收录该内容

2 篇文章 0 订阅

订阅专栏

1 关于API

API，英文名（Application Programming Interface），俗称接口，也叫做通道，负责一个程序系统和其他软件系统的沟通，从本质上来看是预先定义的函数。

1.1 好的API有哪些特性

日常工作中有人会抱怨调用的API不好，那么好的API有什么特性呢？

简单

简单是十分必要的，程序员常喜欢解决复杂问题，这很容易让这些复杂性影响到编写的用户API。保证API的简单需要花费大量工作，面临更多的挑战。而简单的接口会降低学习成本。

比如在批量导入数据时：

简单的接口直接传入批量的数据进行操作（List）
复杂的接口，先让用户把批量数据存在在文件中，通过解析文件批量操作（File）

批量导入数据且没有其他特殊要求，直接传入批量数据会比文件上传更加简洁。

易于理解

即使在没有文档的情况下，用户也能快速使用API，要求接口命名规范且富有含义。

比如在删除项目时：

易于理解的接口，使用全英文命名（动词名词组合规范），接口名、参数名富有含义符合，如（deleteProject）
不易理解的接口，使用无意义的字符命名，如（qwerasdf）

易于理解的接口命名有含义，贴近大众思维，容易理解。

易于使用

易于使用的另一标准，即当用户使用该接口时，不需要再进行二次封装。

比如在新增项目时候，需要先验证用户的权限：

易于使用的接口，会将用户验证和新增项目合在一个接口中（addProjectWithVerify）
不易使用的接口，要求客户端先后调用用户验证接口（verifyUser）和新增项目接口(addProject)

不易使用的接口可能在接口命名上存在缺陷，导致可读性差，客户端难以理解。且两次调用是两次网络IO开销，对性能和稳定性不好，同时客户端也需要考虑回滚的方案。

功能独立

一个接口只负责一个功能，不要返回多余的数据。

比如当前有用户信息 id、name、password、birthday等，前端需要一个用户下拉框（下拉框只需要id和name）：

功能独立的接口，只会返回id和name的列表
功能不独立的接口，会返回全部的用户信息列表，以便于其他地方使用

功能独立的接口保证了接口专一性，功能不独立的接口可能会泄漏更多的信息。

易于扩展

好的接口有良好的扩展性，便于扩展新的实现，向前兼容。

比如新增路由器设备时，当前只有1款路由器设备，但未来会有不同的路由器设备。新增路由器设备时，不同类型的设备处理流程不一样。

易于扩展的接口，会预留设备类型字段，新的设备只需要传入类型和设备信息,如addRouterDevice(Type,Info)
不易于扩展的接口，会写死接口，如addTypeARouterDevice(info)

同样是新增设备，每新增一个设备，不易扩展的接口会新增一个，甚是繁琐。

低延时

好的接口请求耗时较低，网页接口耗时处在2~5S时，用户尚能接受，但超过这个耗时会让用户体验极其差。

比如在拉取新闻列表信息时

低延时的接口，能在2S内返回所有新闻信息
高演示的接口，可能在5~10S内才能呈现所有的新闻信息

低延时的接口，会涉及到预先计算、分级缓存、逻辑优化、查询优化等环节。

高可用性

好的接口能保证可用性。

要保证接口高可用，需要解决以下场景

客户端的请求太多，超出服务端的服务能力，导致服务端不可用。
服务算自身出现异常，或者由于资源有限需要对部分客户端请求故意表现未异常，为了不影响其他服务功能，主动关闭服务的一些功能。
客户端发现服务端出现异常（比如大量超时），主动出击，暂停对服务端的请求。

高安全性

接口一般是供外部使用，因此保证接口的安全显得尤为重要。

保证接口安全性有很多措施，如

优秀完整的文档

1 API常用设计模式

1.1 API是什么

1.2 好的API有哪些特性

易读：见名知意
易用：表现为客户端使用接口时，不需要写二次封装
功能独立：一个接口只负责一个功能，不要返回多余数据
容易扩展：扩展新接口，扩展新实现，向前兼容

api设计原则

专一：一个api的功能应该是单一的，容易理解，也就会更好用
尽可能小：缩小功能范围
尽量少的外部依赖：反例就是，先调用A,再调用B,最后才能使用C
不暴露细节：不暴露内部细节，不必要的接口也尽量不要发布
良好的命名：最好能够做到自描述
良好的文档：接口不只是给自己的，给调用方和后面的维护人员提供方便
考虑性能
设计公共参数和字段
考虑兼容

api设计步骤

1.3 BAT开放接口

1.4 REST&ROA

REST（Representational State Transfer）定义

表示性状态转移，分布式超媒体软件的一种架构风格。
一套简单的设计原则、一种架构风格（或模式），不是一种具体的标准或架构。
基于使用HttP、URI等现有的广泛流行的协议和标准
对Web的本质回归，一种真实描述Web的方式
符合REST原则的架构方式即可称为RESTful

REST风格优点

可以利用缓存Cache来提高响应速度
通讯本身的无状态性可以让不同的服务器的处理一系列请求中的不同请求，提高服务器的扩展性
浏览器即可作为客户端，简化软件需求
相对于其他叠加在HTTP协议之上的机制，REST的软件依赖性更小
不需要额外的资源发现机制
在软件技术演进中的长期的兼容性更好

定义资源路径

http(s)://api.tplink.com.cn/v1/tauc/{networkId}

http(s) 协议
api.tplink.com.cn 域名
v1 版本
tauc/{networkId} 资源名称
{id} 路径参数

以资源的从属关系定义多级路径

DELETE /v1/network/{networkId}/topo/{topoId}

复杂操作，也可以转换为标准HTTP METHOD

POST /v1/network/{networkId}/block block网络

内容协商

方法1，Header增加Content-type、Accept请求头，如"Accept"="application/json"
方法2，增加format请求参数，如/v1/netwokrs?format=json
方法3，包含在路径中，如/v1/networks/{network}.json、/v1/networks/{network}.pb
请求参数尽量使用键值对，而不使用序列化,如GET： /uri.json?param1=value1&param2=value2,POST: 设置Content-Type为application/x-www-form-urlencoded,Http Body内容为键值对，param1=value1&param2=value2