接口设计主要包括哪几个方面_接口中可以包含哪些内容

接口设计的16个原则 　　接口设计需要考虑哪些方面 　　  　　接口的命名。 　　请求参数。 　　支持的协议。 　　TPS、并发数、响应时长。 　　数据存储。DB选型、缓存选型。 　　是否需要依赖于第三方。 　　接口是否拆分。 　　接口是否需要幂等。 　　防刷。 　　接口限流、降级。 　　负载均衡器支持。 　　如何部署。 　　是否需要服务治理。 　　是否存在单点。 　　接口是否资源包、预加载还是内置。 　　是否需要本地缓存。 　　是否需要分布式缓存、缓存穿透怎么办。 　　是否需要白名单。 　　  　　当我们设计接口，我们或多或少都会有上面列举的一些考虑，我们只有想的更多才能让让我们的接口更加完善，我个人觉得100%完美的接口是不存在，只有适合才是最重要。 　　接口设计原则 　　原则一：必须符合Restful，统一返回格式，约定业务层错误编码，每个编码可以携带可选的错误信息。 　　原则二： 命名必须规范、优雅。 　　原则三：单一性。 　　单一性是指接口要做的事情应该是一个比较单一的事情，比如登陆接口，登陆完成应该只是返回登陆成功以后一些用户信息即可，但很多人为了减少接口交互，返回一大堆额外的数据。 　　比如有人设计一个用户列表接口，接口他返回每一条数据都是包含用户了一大堆跟另外无关的数据，结果一问，原来其他无关的数据是他下一步想要的，想达成数据的懒加载。 　　原则四：可扩展。 　　接口扩展性，是指设计接口的时候多想想多种情况，多考虑各个方面，其实我觉得单独将扩展性放在这里也是不妥的，感觉说的跟单一性有点相反的意思，其实这个不是这个意思。 　　这边的扩展性是指我们的接口充分考虑客户端，想想他们是如何调用的，他要怎样使用我的代码，他会如何扩展我的代码，不要把过多的工作写在你的接口里面，而应该把更多的主动权交给客户程序员。 　　如不同的列表数据接口，我们不可能将每个列表都写成一个接口。 还有一点，我这里特别想指出来的是很多开发人员为了省事（姑且只能这么理解），将接口设计当成只是 app 页面展示。 　　这些人将一个页面展示就用一个接口实现，而不考虑这些数据是不是属于不同的模块、是不是属于不同的展示范畴、结果下次视觉一改，整个接口又得重写，不能复用。 　　原则五：必须有文档。 　　良好的接口设计，离不开清晰的接口文档表述。文档表述一定要足够详细 　　原则六：产品心。 　　为什么我说要有产品心？因为我觉得很多人忽略了这一点。我来说一下假如开发一个app，如果一开始连个交互文档给你都没有的话，你怎么设计接口？ 　　所以我觉得作为一个服务端后台开发人员应该要有产品心，特别是对于交互文档应该好好理解，因为这些都会对我们的接口设计有很大的影响。 　　我在设计接口的时候就很常发现很多交互文档根本就走不通，产品没有考虑到位，交互文档缺失，这时候作为一个开发要主动推动，完善。 　　原则七：第三方服务接口数据能缓存就缓存。 　　原则八：第三方服务需要做降级。 　　原则九：建议消除单点。 　　原则十：接口粒度要小。 　　原则十一：客户端能处理的逻辑就不要给服务端处理，减少服务端压力。 　　原则十二：资源预加载。 　　原则十三：不要过度设计。 　　原则十四：缓存尽量不要穿透。 　　原则十五：接口能缓存就缓存。 　　原则十六：思辨大于执行 　　如何保证接口的高可用、高性能 　　上面也列举很多需要考虑和设计的原则，其实还有很多方面，我这边也不是特别全面。 　　居于上面列举的这些考虑点，其实这边说服务是更恰当，能把上面说的点做好，其实接口也是比较可靠，如何设计以及保证接口的高可用和高性能。可以思考一下以下几个 point 　　高性能：如果我们发现这个接口tps和响应时间没有达到我们的要求怎么办。 　　A：数据存储方面：我们会想数据库有没有分库、分表、有没有做主从，有没有读写分离、字段是否有加索引、是否存在慢 sql，数据库引擎是否选用合适、是不是用了事务； 　　其次我们会想到是不是引用了分布式缓存、缓存 key 大小是否合适，失效时间是否设置合理，会不会大量缓存穿透、有没有引入本地缓存。 　　B：业务方面：是否有大量的计算、能否异步处理。是否需要引入线程池或者 MQ 来异步处理任务。有没有必要将接口进行垂直拆分和水平拆分、将接口粒度变小。 　　C：其他方面：nginx 层面做缓存、加机器、用 ssd，资源放 cdn，多机房部署、资源文件预加载。 　　高可用：如何保证服务高可用，需要从几个维度来实现： 　　A：消除单点，基于高可用第二位。 　　B：能做集群的全部做集群。譬如 Redis 集群、mysql集群、MongoDB副本集。 　　C：能做读写分离的都做读写分离。 　　D：异地多机房部署，接入 GSLB 　　E：必须有限流、降级机制。 　　F：监控。高可用的保证，基于第一位。 　　下图是从一个基本的请求出发来梳理需要涉及到各个段，以及各个端能做的事情。谈谈接口服务，但不局限于接口本身。 　　
　　客户端：资源预加载、限制请求、数据上报。我这边就拿客户端来举个例子。接口服务所依赖的资源包或者一些公共配置预加载在本地，减少接口的交互，通过请求配置文件是否更新，code是否是304等来； 　　接口做一些请求限制，比如抢红包、抢券等，单位时间内N次只请求一次等；接口失败数据上报来；这就是客户端可以做到的对接口有帮助的事情 　　GSLB/HttpDNS：多机房部署、流量切换、域名劫持，一般技术和业务比较成熟的公司这一层。 　　资源文件放CDN。 　　负载均衡器：lVS+Nginx是互联网常用的做负载均衡，可以实现四层/七层负载均衡；这里除了可以分流、转发以外，我们用的更多的基于令牌桶限流、缓存。 　　本地缓存。本地缓存能减少我们访问DB或者分布式缓存，本地缓存推荐使用guava，guava里面有很多特性很好用，例如基于令牌桶的限流；当缓存失效时只穿透一个请求去访问后端。 　　线程池。 　　模块拆分。将一个项目按功能模块拆分，一个接口也可以按业务粒度进行拆分。 　　数据中心。提供数据支撑，譬如黑名单。 　　数据库。加索引、分库、分表、读写分离 　　分布式缓存。数据分片、拆分大key，并做集群，采用分布式锁 　　MQ。做接口拆分利器，异步操作。 　　其他服务。限流、防刷以及降级（特别是第三方服务，保证第三方服务down掉不要影响我们自身的服务）。在这里也需要考虑做第三方数据的缓存或者持久化，譬如实名认证、身份证认证等。 　　监控。监控永远是必须的，能让你第一时间知道接口服务是否ok 　　个人小分享 　　1）接口Restful，统一返回格式，约定业务层错误编码，每个编码可以携带可选的错误信息 　　在前司，客户端和服务之间是有统一的数据返回格式，约定各层的编码，可以通过编码位数以及编码就可以看出是那一层出问题。 　　我觉得这对我们定位问题以及维护来说具有莫大的意义，并对异常也进行捕捉，封装成对应的 code，我之前阅读一些人的代码发现其项目根本没有做这一层，因为简单而不做我觉得有失所望。 　　2）采用 hybird 模式 　　采用 hybird 模式涉及到资源预加载的问题，在很多项目里面都大量使用，譬如前司的生活服务，就采用了 hybird 模式，先将资源文件（包含图片、前端页面）打包放到服务器并通过版本号进行管理，并通过一个总的配置文件来管理，如果是H5页面可以进行模板预先设计，down到本地。 　　配置文件格式： 　　  *文件1*        name：xxx        url：http:xxxx        md5：xxxx   *文件2*        name：zzz        url：http：zzzz        md5：zzz 　　客户端每次启动应用或者定时请求总的配置文件，通过http code是否是304判断是否需要下载这个总的配置文件，如果code是200，那么下载这个配置，比较那个文件发生变化，并将其下载。这样的好处： 　　减少接口的交互； 　　资源预加载，节省流量，打开页面更加流畅，对于服务端来说字需要返回数据json串就行，而不需要其他，减少服务端压力； 　　方便开发人员，资源管理更加简洁，比如做活动需要的h5页面，只需要前端上传对应的h5资源包到服务端，不需要通过后端开发人员就可以搞定。 　　虽然这个原理很简单，但是现在很多app还是没有做这个，都是通过填写一个url，加载网页的方式去打开，体验性太不友好。 　　3）客户端 　　客户端跟服务端就是接口请求的关系，很多时候需要要求客户端做一些数据缓存的工作以及一些检验工作。在前司已经好几次给客户端的同学坑过了，客户端同学接口乱调用，死循环调用。 　　一次是做一个关于事件提醒的功能，需要每天定时调用调用服务端一个接口，结果客户端的同学写了一个 bug 导致请求每隔一两秒就调用一次，导致服务器这边此接口 pv 翻了N倍，而且这个 bug 通过测试同学很难测试出来； 　　还有一次发现服务端一段时间以后 UV 不见涨，但是PV却涨的很猛，定位发现是客户端同学A图省事在一个方法里面调用了N个接口，也就是模板方法。 　　因为版本更新，同学B需要做一个新的功能，然后也调用了A同学的接口导致，从而导致PV上升，其实B同学完全不需要调用这么多接口。这些都是真实案例，所以这里需要有一个监控接口异常的机制。 　　4）思辨大于执行 　　写到这里觉得这个非常重要，思辨大于执行，意味着我们不是一股脑就去干，也不是不去干，我们做事情需要思考、辨别；从而让事情更高效、更好、更有力的执行。接口设计也一样，需要我们去思辨。 　　5）本地缓存、分布式缓存以及异步 　　缓存在前司主要分为客户端缓存、CDN缓存、本地缓存（guava）、Redis缓存。 　　在MZ早期是接口是采用 DB+本地缓存的方式提供数据，但这种模式DB压力大，接口吞吐量小，本地缓存多机难一致性、更新不及时问题。 　　为了解决这些问题，引入分布式缓存，并通过 Task 将业务数据刷到 Redis，接口只访问 redis，不会访问 DB，及时 DB 故障也不会影响功能。 　　不同的业务系统系统通过 MQ 来解耦，多机房不是通过 MQ 来实现数据的一直。 　　比如，评论，先通过写 Redis，写 MQ 来实现数据在多机房同步，再通过 task 将 Redis 中评论同步到 DB 中。 　　接口设计涉及方方面面，这边也只谈到一个大概，虽然有点泛泛而谈，希望此拙文对你有所启示。 　　6）数据库 　　数据库分库分表，一般都是通过 userId 或者 imei 或者 mac 地址来分表，单表数据量控制在500w以内，这需要我们提前估算好数据量，尽量避免数据的迁移。 　　在前司，数据库一般都是采用 mysql+MongoDB 两种，MySQL存储用户的用户数据，MongoDB 存储业务数据，就像阅读和生活服务里面的业务数据就存储在 MongoDB 里面。 　　在数据库这层，我们主要也是通过主从模式、读写分离、分库、分表来实现数据的可用性。 　　7）业务 　　业务尽可能拆分、独立部署、将项目按业务划分、按功能划分等。譬如生活服务，我们当时主要拆分成管理后台 admin、任务 task、活动、web、数据展示模块。 　　8）数据中心 　　每个大一点的公司都有数据部门，我们这边可以通过数据中心的数据分析来达到我们需要的数据。 　　比如黑名单，推广效果、活动数据。我们可以通过这些完善我们的接口功能。之前在前司做了个数据处理后异步加载到 Redis 来实现数据利用的项目。