服务端接口设计最佳实践
# 1. 接口参数校验
入参出参校验是每个程序员必备的基本素质，你设计的接口，必须先校验参数，比如入参是否允许为空，入参长度是否符合你的预期长度。这个要养成习惯，日常开发中， 很多低级 bug 都是不校验参数导致的。
比如：你的数据库表字段设置为
varchar(16)，对方传了一个 32 位的字符串过来。如果你不校验参数，插入数据库就直接异常了。
出参也是，比如你定义的接口报文，参数是不为空的，但是你的接口返回参数，没有做校验，因为程序某些原因，直接返回别人一个 null 值。
注意： 在前端有对参数进行校验的前提下，服务端的接口也要进行校验，避免爬虫或者前端漏校验，导致一些低级的错误。
# 2. 修改老接口时，注意接口的兼容条件
很多 bug 都是因为修改了对外接口，但是却不做兼容导致的，关键这个问题多数是比较严重的，可能直接导致系统发版失败，新手程序员很容易犯这个错误。
# 3. 设计接口时，充分考虑接口的可扩展性
要根据实际业务场景设计接口，充分考虑接口的可扩展性。
比如你接到一个需求：是用户添加或修改员工时，需要刷脸，那你是反手提供一个员工管理的提交刷脸信息接口？还是先思考，提交刷脸流程是不是通用流程？比如转账或者一键贴需要接入刷脸的话， 你是否需要重新实现一个接口呢？还是当前业务类型划分模块，复用这个接口就好，保留接口的可扩展性。
# 4. 考虑接口是否需要防重处理
如果前端重复请求，你的逻辑如何处理？是不是考虑接口去重处理。
当然，如果是查询类的请求，其实不用防重。如果是更新修改类的话，尤其金融转账类的，就要过滤重复请求了。简单点，你可以 使用 Redis 防重复请求，同样请求方，一定时间间隔内的相同请求，考虑是否过滤。当然，转账类接口，并发不高的话， 推荐使用数据库防重表，已唯一流水号作为主键或者唯一索引。
# 5. 重点接口，考虑线程池隔离
一些登录、转账交易、下单等重要接口，考虑线程池隔离。如果你所有业务都共用一个线程池，有些业务出 bug 导致线程池阻塞打满的话， 那就悲剧了，所有业务都受影响了。因此，进行线程池隔离，重要业务独立一个线程池，就能更更好的保护重要业务。
# 6. 调用第三方接口要考虑异常和超时处理
如果你调用第三方接口，或者分布式远程服务的话，需要考虑。
- 异常处理
比如：你调别人的接口，如果异常了，怎么处理，是重试还是当做失败还是告警处理。
- 接口超时
没法预估对方接口一般多久超时，一般设置个超时断开时间，以保护你的接口。之前见过一个生产问题， 就是 http 调用不设置超时时间，最后响应方进程假死，请求一直占着线程不释放，当请求量不断打进来，进而拖垮线程池。
- 重试次数
你的接口调失败，需不需要重试？重试几次？需要站在业务角度上思考这个问题。
# 7. 接口实现考虑熔断和降级
当前互联网系统一般是分布式部署的。而分布式系统中，经常会出现某个基础服务不可用，最终导致整个系统不可用的情况。这种现象被称为服务雪崩效应。
A->B->C...中，如果服务C出现问题，比如是因为慢SQL导致调用缓慢，那将导致B也会延迟，从而A也会延迟，堵住的A请求会消耗占用系统的线程、IO等资源，当请求 A 的服务 越来越多，占用的计算机资源也越来越多，最终会导致系统瓶颈出现，造成其他的请求同样不可用，最后导致业务系统奔溃。
为了应对服务雪崩，常见的做法是 熔断和降级，最简单就是加开关控制，当下游系统出问题时，
开关降级，不在调用下游系统，推荐用：阿里开源的 sentinel 或者 Hystrix。
# 8. 日志打印好，接口的关键代码，要有日志保价护航
关键业务代码无论身处何地，都应该有足够的日志保驾护航。比如：你实时转账业务，转个几百万，然后转失败了， 接着客户投诉，然后你还没有打印到日志，想想哪种水中火热的困境下，你却毫无办法……
# 9. 接口的功能定义要具备单一性
单一性是指接口做的事情比较单一、专一。比如一个登陆接口，它做的事情就只是校验账户名密码，
然后返回登录成功以及userId即可。但是如果你为了减少接口交互，把一些注册、一些配置查询等全放到登录接口，就不太妥。
其实，这也是微服务一些思想，接口的功能单一、明确。比如订单服务、积分、商品信息相关的接口都是划分开的。将来拆分微服务的话，是不是就比较简便啦。
# 10. 接口有些场景，使用异步更合理
举个简单的例子，比如你实现一个用户注册的接口。用户注册成功时，发个邮件或者短信去通知用户。这个邮件或者发短信，就更适合异步处理，因为总不能一个通知类的失败，导致注册失败吧。
至于做异步的方式，简单的就是用线程池。还可以使用消息队列，就是用户注册成功后，生产者产生一个注册成功的消息，消费者拉到注册成功的消息，就发送通知。
# 11. 优化接口耗时，远程串行考虑改并行调用
假设我们设计一个 APP 首页的接口，它需要查用户信息，需要查 banner 信息，需要查弹窗信息等等。那你是一个一个接口串行调，还是并行调呢？
如果是串行一个一个查，比如查用户信息 200ms，查 banner 信息 100ms，查弹窗信息 50ms，那一共就耗时 350ms。如果还查其他信息， 那耗时就更大了。这种场景是可以改为并行调用，也就是说查用户信息、查banner信息、查弹窗信息，可以同时发起。
在Java中有个异步编程利器：CompletableFuture，就可以很好的实现这个功能。
# 12. 接口合并或者说考虑批量处理思想
数据库操作或者是远程调用时，能批量操作就不要for循环调用。
# 13. 接口实现过程中，恰当使用缓存
哪些场景适合使用缓存？读多写少且数据时效性要求越低的场景。
缓存用的好，可以承载更多的请求，提升查询效率，减少数据库的压力。
比如一些平时变动很小或者几乎不会变的商品信息，可以放到缓存，请求过来时，先查询缓存，如果没有再查询数据库，并且把数据库的数据更新到缓存。但是 使用缓存增加了需要考虑这些点：缓存和数据库一致性如何保证、集群、缓存击穿、缓存雪崩、缓存穿透等问题。
# 14. 接口考虑热点数据隔离性
瞬时间的高并发，可能会打垮你的系统。可以做一些热点数据的隔离。比如业务隔离、系统隔离、用户隔离、数据隔离等。
- 业务隔离：比如12306的分时段售票，将热点数据分散处理，降低系统负载压力；
- 系统隔离：比如把系统分成了用户、商品、社区三个板块，这三个板块分别使用不同的域名、服务器和数据库，做到从接入层到应用层再到数据层三层完全隔离。
- 用户隔离：重点用户请求到配置更好的机器。
- 数据隔离：使用单独的缓存集群或者数据库服务热点数据。
# 15. 可变参数配置化，比如红包皮肤切换等
例如产品经理提了个红包需求，圣诞节的时候，红包皮肤为圣诞节相关。春节的时候，为春节红包皮肤等。
可变配置，可以通过维护一张配置表，或者通过一些统一配置中心（支持动态更新）。
# 16. 接口考虑幂等性
接口是需要考虑幂等性的，尤其是抢红包、转账这些重要接口。最直观的业务场景，就是用户连续点击两次，你的接口有没hold住，或者消息队列出现重复消费的情况，你的业务逻辑怎么控制？
接口幂等实现方案只要有 8 种：
- select + insert + 主键/唯一索引冲突
- 直接 insert + 主键/唯一索引冲突
- 状态机幂等
- 抽取防重表
- token 令牌
- 悲观锁
- 乐观锁
- 分布式锁
# 17. 读写分离，优先考虑读从库，注意主从延迟问题
我们的数据库都是集群部署的，有主库也有从库，当前一般都是读写分离的。比如你写入数据，肯定是写入主库，但是针对读取实时性要求不高的数据，则优先考虑从库，因为可以分担主库的压力。
注意：如果读取从库的话，需要考虑主从延迟的问题。
# 18. 接口返回的数据量，如果数据量大需要分页
一个接口返回报文，不应该包含过多的数据量，过多的数据量不仅处理复杂，并且数据量传输的压力也非常大。因此，数据量实在太大，可以分页返回，如果是功能不相关的报文， 那应该考虑接口拆分。
# 19. 好的接口实现，离不开 SQL 优化
我们做后端的，写好一个接口，离不开 SQL 优化。
SQL 优化从这几个维度思考：
explain分析 SQL 查询计划（重点关注 type、extra、filtered 字段）show profile分析，了解 SQL 执行的线程的状态以及消耗的时间- 索引优化（覆盖索引、最左前缀原则、隐式转换、order by 以及 group by的优化、join优化）
- 大分页问题优化（延迟关联、记录上一页最大 ID）
- 数据量太大（分库分表、同步到Elasticsearch、用Elasticsearch查询）
# 20. 代码锁的粒度控制好
什么是加锁粒度呢?
其实就是你要锁住的范围是多大，比如你在家上卫生间，你只要锁住卫生间就可以了吧， 不需要将整个家都锁起来不让家人进门吧，卫生间就是你的加锁粒度。
我们写代码时，如果不涉及共享资源，就没必要锁住的。这就好像你上卫生间，不用把整个家都锁住， 锁住卫生间门就可以了。
比如，在业务代码中，有一个 ArrayList 因为涉及到多线程操作，所以需要加锁操作，假设刚好又有 一段比较耗时的操作（代码中的 slowNotShare 方法）不涉及线程安全问题，你会如何加锁呢？
# 21. 接口状态和错误需要统一明确
提供必要的接口调用状态信息。比如你的一个转账接口调用是成功、失败，处理中还是受理成功等，需要明确告诉客户端。如果结果失败，那么具体失败的原因是什么。 这些必要的信息都必须要告诉给客户端，因此需要明确的错误码和对应的描述。同时，尽量对报错信息封装一下， 不要把后端的异常信息完全抛出到客户端。
# 22. 接口要考虑异常处理
实现一个好的接口，离不开优雅的异常处理。对于异常处理，提十个小建议吧。
- 尽量不要使用
e.printStackTrace()，而是使用log打印。因为e.printStackTrace()语句可能会导致内存占满。 catch住异常时，建议尽量打印出具体的exception，有利于更好定位问题。- 不要用一个
Exception捕获所有可能的异常 - 记得使用
finally关闭流资源或者直接使用try-with-resource - 捕获异常与抛出异常必须是完全匹配，或者捕获异常是抛出异常的父类。
- 捕获到的异常，不要忽略它，至少打点日志吧。
- 注意异常对你的代码层次结构的侵染。
- 自定义封装异常，不要丢弃原始异常的信息
Throwable cause。 - 运行时异常
RuntimeException，不应该通过catch的方式处理，而是预先检查，比如：NullPointerException处理。 - 注意异常匹配的顺序，优先捕获具体的异常。
# 23. 优化程序逻辑
优化程序逻辑这块还是挺重要的，也就是说，你实现的业务代码，如果是比较复杂的话，建议把注释写清楚。 还有，代码逻辑尽量清晰，代码尽量高效。
比如，你要使用用户信息的属性，你根据session已经获取到
userId了，然后就把用户信息从数据库查询出来， 使用完后，后面可能又要用到用户信息的属性，有些小伙伴没太想太多， 反手就是把userId再传进去，再查一次数据库……我在项目中，坚果这种代码……直接把用户对象传下来不好嘛……
# 24. 接口实现过程中，注意大文件、大事务、大对象
- 读取大文件时，不要
Files.readAllBytes直接读取到内存中，这样会 OOM 的，建议使用 BufferedReader 一行一行来。 - 大事务导致死锁、回滚时间长、主从延迟等问题，开发中尽量避免大事务。
- 注意一些大对象的使用，因为大对象是直接进入老年代的，可能会触犯 fullGC。
# 25. 你的接口，需要考虑限流
如果你的系统每秒抗住的请求是 1000，如果一秒钟来了十万请求呢？换个角度来说，高并发的时候， 流量洪峰来了，超过系统的承载能力，怎么办呢？
如果不采取措施，所有的请求打过来，系统 CPU、内存、Load 负载飚的很高，最后请求处理不过来，所有的请求都无法正常响应。
针对这种场景，我们可以采用限流方案。就是为了保护系统，多余的请求，直接丢弃。
常见的限流方案有：
- Guava 的
RateLimiter单机版限流 Redis分布式限流- 阿里开源组件
sentinel限流
# 26. 代码实现时，注意运行是异常（比如空指针、下标越界等）
日常开发中，我们需要采取措施规避数组越界，被零整除，空指针等运行时错误。
不严谨的代码有：
String name = list.get(1).getName(); // list 可能越界，因为不一定有 2 个元素
应该采取措施，预防一下数组边界溢出。正例如下：
if(CollectionsUtil.isNotEmpty(list) && list.size() > 1){
String name = list.get(1).getName();
}
# 27. 保证接口安全性
如果你的 API 接口是对外提供的，需要保证接口的安全性。保证接口的安全性有token机制和接口签名。
# 28. 分布式事务，如何保证
分布式事务，就是指事务的参与者、支持事务的服务器、资源服务器以及事务管理器分别位于不同的分布式系统的不同节点上。简单来说， 分布式事务指的就是分布式系统中的事务，它的存在就是为了保证不同数据库节点的数据一致性。
分布式事务的几种解决方案：
- 2PC(二阶段提交)方案、3PC
- TCC(Try、Confirm、Cancel)
- 本地消息表
- 最大努力通知
- seata
# 29. 事务失效的一些经典场景
我们的接口开发过程中，经常需要使用到事务。所以需要避开事务失效的一些经典场景。
- 方法的访问权限必须是 public，其他 private 等权限事务失效。
- 方法被定义成 final 的，这样会导致事务失效。
- 在同一个类中的方法直接给内部调用，会导致事务失效。
- 一个方法如果没交给 Spring 管理，就不会生成 Spring 事务。
- 多线程调用，两个方法不在同一个线程中，获取到的数据库连接不一样的。
- 表的存储引擎不支持事务。
- 如果自己try……catch误吞了异常，事务失效
- 错误的传播特性
# 30. 掌握常见的设计模式
把代码写好，还是需要熟练常用的设计模式，比如策略模式、工厂模式、模板方法模式、观察者模式等等。 设计模式，是代码设计经验的总结。使用设计模式可以可重用代码、让代码更容易被他人理解、保证代码可靠性。
# 31. 写代码时，考虑线程安全问题
在高并发情况下，HashMap 可能出现死循环。因为它是非线程安全的，可以考虑使用使用 ConcurrentHashMap。
所以这个也尽量养成习惯，不要上来反手就是一个new HashMap()；
- HashMap、ArrayList、LinkedList、TreeMap 等都是线程不安全的；
- Vector、Hashtable、ConcurrentHashMap 等都是线程安全的。
# 32. 接口定义清晰易懂，命名规范
我们写代码，不仅仅是为了实现当前的功能，也要有利于后的维护。说到维护，代码不仅仅是写给自己看的， 也是给别人看的。所以接口定义要清晰易懂，命名规范。
# 33. 接口的版本控制
接口要做好版本控制。就是说，请求基础报文，应该包含version接口版本号字段，方便未来做接口兼容。
其实这个点也算接口扩展性的一个体现点吧。
比如客户端APP某个功能优化了，新老版本会共存，这时候我们的version版本号就派上用场了，对version做升级，做好版本控制。
# 34. 注意代码规范问题
注意一些常见的代码坏味道：
- 大量重复代码（抽共用代码，设计模式）
- 方法参数过多（可封装成一个 DTO 对象）
- 方法过长（抽小函数）
- 判断条件太多（优化 if……else）
- 不处理没用的代码
- 不注重代码格式
- 避免过度设计
# 35. 保证接口正确性，其实就是保证更少的 bug
保证接口的正确性，换个角度讲，就是保证更少的 bug。所以接口开发完后，一般需要开发自测一下。 然后的话，接口的正确还体现在，多线程并发的时候，保证数据的正确性等等。比如你做一笔转账交易，扣除余额的时候，可以通过CAS乐观锁的方式保证余额扣减的正确。
如果你是实现秒杀接口，得防止超卖问题吧。你可以使用 Redis 分布式锁防止超卖问题。
# 36. 学会沟通，跟前端沟通，跟产品沟通
我把这一点放到最后，最后沟通是非常非常重要的。比如你开发定义接口时，一定不能上来就自己埋头把接口定义完了， 需要跟客户端先对齐接口，遇到一些难点时，跟技术 Leader 对齐方案。实现需求过程中，有什么问题，及时跟产品沟通。
总之就是，开发接口过程中，一定要沟通好~