如何把一个接口设计好

结合参考文档，梳理自己在工作中遇到的情况

• 后端思想篇：设计好接口的36个锦囊

文章目录

• • • 1. 接口定义清晰易懂，命名规范
    • 2. 接口参数校验
    • 3. 修改老接口时，注意接口的兼容性
    • 4. 好的接口实现，离不开SQL优化
    • 5. 接口的版本控制
    • 6. 注意代码规范问题
    • 7. 日志打印好，接口的关键代码，要有日志保驾护航
    • 8. 接口有些场景使用异步更合理
    • 9. 学会沟通，跟前端沟通，跟产品沟通，跟Leader沟通
    • 10. 保证接口的正确性，开发完后要自测
    • 11. 接口实现过程中，注意大文件、大事务、大对象
    • 12. 接口需要考虑限流
    • 13. 保证接口的安全性
    • 14. 代码实现时，注意运行时异常(比如空指针、下标越界等)
    • 15. 接口需要考虑异常处理
    • 16. 接口的功能定义要具备单一性
    • 17. 设计接口时，充分考虑接口的可扩展性
    • 18. 考虑接口是否需要防重处理
    • 19. 接口考虑幂等性
    • 20. 接口状态和错误需要统一明确
    • 21. 优化程序逻辑
    • 22. 调用第三方接口要考虑异常和超时处理
    • 23. 可变参数配置化，比如红包皮肤切换等
    • 24.接口合并或者考虑批量处理思想
    • 25. 接口注意返回的数据量，如果数据量大需要分页
    • 26. 分布式事务，如何保证（暂未解决）
    • 27. 接口实现考虑熔断和降级（暂未解决）
    • 28. 优化接口耗时，远程串行考虑改并行调用（未遇到）
    • 29. 接口实现过程中，恰当使用缓存(未遇到)
    • 30. 接口考虑热点数据隔离性（未遇到）
    • 31. 重点接口，考虑线程池隔离（未遇到）
    • 32. 读写分离，优先考虑读从库，注意主从延迟问题（未遇到）
    • 33. 代码锁的粒度控制好（未遇到）
    • 34. 事务失效的一些经典场景（未遇到）
    • 35. 掌握常用的设计模式 (未遇到)
    • 36. 考虑线程安全问题（未遇到）

1. 接口定义清晰易懂，命名规范

增删改查
delete
add
modify
get/list

2. 接口参数校验

• 使用正则表达式校验用户名、密码、电话号码等
• 对于入参为空判定；
• 对入参长度确认。如数据库字段设置为varchar(16)，传入的字符串为32位，直接插入会导致插入异常；
• 对于出参校验。有些参数不能为空，如果直接返回null值，对方接收后处理会直接报错，resp.getData().getEquipment().getList(0)

3. 修改老接口时，注意接口的兼容性

• 在接口中添加新的参数，启用旧的参数，不能将旧的参数马上去掉，可以在参数或方法前添加@Deperated，在前端更新后，再将这些参数去掉；

4. 好的接口实现，离不开SQL优化

• 微服务中各个服务控制自己对应的表，实现业务隔离，方便管理和后期扩展
• 一条查询语句最多不超过3张表关联
• 善用explain分析SQL查询计划（重点关注type、extra、filtered字段），该加索引的加索引
• 会用show profile分析，了解查询语句具体执行了多长时间
• 索引优化，索引并不是越多越好
• 数据量太大（分库分表等）

5. 接口的版本控制

关于接口的版本，可以使用maven包中的版本管理来控制，而不需要在接口参数中写v1，v2等

6. 注意代码规范问题

• 保证代码的可读性，将代码中重复的模块抽离出来，将一些复杂的实现抽出方法

• 方法的参数不要冗余

  25种代码坏味道总结+优化示例

7. 日志打印好，接口的关键代码，要有日志保驾护航

> [日志打印的15个建议](https://mp.weixin.qq.com/s?__biz=Mzg3NzU5NTIwNg==&mid=2247494838&idx=1&sn=cdb15fd346bddf3f8c1c99f0efbd67d8&chksm=cf22339ff855ba891616c79d4f4855e228e34a9fb45088d7acbe421ad511b8d090a90f5b019f&token=162724582&lang=zh_CN&scene=21#wechat_redirect)

8. 接口有些场景使用异步更合理

比如推送消息，并不是及时返回，则需要采用异步进行处理

9. 学会沟通，跟前端沟通，跟产品沟通，跟Leader沟通

- 和产品反复沟通几次，一定要明确需求
- 方案设计完成后，先写方案设计文档，和组里的人过一下，大家初步达成一致后，再进行开发
- 遇到技术难点，及时跟技术leader反映，自己在这里可能需要时间克服，有风险；
- 如果需要紧急发布，一定要提前和leader沟通，确认风险范围，leader把控会更加全面些，确认好问题并且达成一致后，再采取行动

10. 保证接口的正确性，开发完后要自测

接口开发完成后要进行自测，功能测试、边界测试
> [Redis分布式锁](https://mp.weixin.qq.com/s?__biz=Mzg3NzU5NTIwNg==&mid=2247488142&idx=1&sn=79a304efae7a814b6f71bbbc53810c0c&chksm=cf21cda7f85644b11ff80323defb90193bc1780b45c1c6081f00da85d665fd9eb32cc934b5cf&token=162724582&lang=zh_CN&scene=21#wechat_redirect)

11. 接口实现过程中，注意大文件、大事务、大对象

• 大文件处理：对于接口中的图片、文件等占用较大内存的，不要直接传送到服务当中，使用对象存储，返回链接地址给客户端，由客户端直接上传到对象存储中。

12. 接口需要考虑限流

如发送短信功能，同一个手机号一天内只能发送有限条
> 4中经典限流算法讲解

13. 保证接口的安全性

> [加签验证](https://mp.weixin.qq.com/s?__biz=Mzg3NzU5NTIwNg==&mid=2247488022&idx=1&sn=70484a48173d36006c8db1dfb74ab64d&chksm=cf21cd3ff8564429a1205f6c1d78757faae543111c8461d16c71aaee092fe3e0fed870cc5e0e&token=162724582&lang=zh_CN&scene=21#wechat_redirect)

14. 代码实现时，注意运行时异常(比如空指针、下标越界等) 15. 接口需要考虑异常处理

> [接口异常处理的十个建议](https://mp.weixin.qq.com/s?__biz=Mzg3NzU5NTIwNg==&mid=2247488009&idx=1&sn=7c27849c67476143660e3ea0dcdfae3d&scene=21#wechat_redirect)

16. 接口的功能定义要具备单一性 17. 设计接口时，充分考虑接口的可扩展性 18. 考虑接口是否需要防重处理 19. 接口考虑幂等性

>  **幂等性**：计算机科学中，幂等表示一次和多次请求某一个资源应该具有同样的副作用，或者说，多次请求所产生的影响与一次请求执行的影响效果相同。

> [聊聊幂等设计](https://mp.weixin.qq.com/s?__biz=Mzg3NzU5NTIwNg==&mid=2247497427&idx=1&sn=2ed160c9917ad989eee1ac60d6122855&chksm=cf2229faf855a0ecf5eb34c7335acdf6420426490ee99fc2b602d54ff4ffcecfdab24eeab0a3&token=1260947715&lang=zh_CN&scene=21#wechat_redirect)

20. 接口状态和错误需要统一明确 21. 优化程序逻辑 22. 调用第三方接口要考虑异常和超时处理 23. 可变参数配置化，比如红包皮肤切换等 24.接口合并或者考虑批量处理思想 25. 接口注意返回的数据量，如果数据量大需要分页 26. 分布式事务，如何保证（暂未解决）

> 分布式事务：就是指事务的参与者、支持事务的服务器、资源服务器以及事务管理器分别位于不同的分布式系统的不同节点之上。简单来说，分布式事务指的就是分布式系统中的事务，它的存在就是为了保证不同数据库节点的数据一致性。

> [分布式事务详解](https://mp.weixin.qq.com/s?__biz=Mzg3NzU5NTIwNg==&mid=2247498358&idx=1&sn=aa6c7ceb61b73267d68d1b4fb7ccc2ed&scene=21#wechat_redirect)

27. 接口实现考虑熔断和降级（暂未解决） 28. 优化接口耗时，远程串行考虑改并行调用（未遇到）

> [异步编程利器](https://mp.weixin.qq.com/s?__biz=Mzg3NzU5NTIwNg==&mid=2247490456&idx=1&sn=95836324db57673a4d7aea4fb233c0d2&chksm=cf21c4b1f8564da72dc7b39279362bcf965b1374540f3b339413d138599f7de59a5f977e3b0e&token=1260947715&lang=zh_CN&scene=21#wechat_redirect)

29. 接口实现过程中，恰当使用缓存(未遇到) 30. 接口考虑热点数据隔离性（未遇到） 31. 重点接口，考虑线程池隔离（未遇到） 32. 读写分离，优先考虑读从库，注意主从延迟问题（未遇到） 33. 代码锁的粒度控制好（未遇到） 34. 事务失效的一些经典场景（未遇到） 35. 掌握常用的设计模式 (未遇到) 36. 考虑线程安全问题（未遇到）