背景
为了更方便的书写和阐述问题, 文章中按照第一人称的角度书写. 作为一个以 java 为主要开发语言的工程师, 我所描述的都是 java 相关的编码和设计.
工程师的静态输出就是代码和文档, 动态的就是各种应用程序 (App,h5 站点, 微信公众号, 小程序). 动态的先不讨论, 主要讨论静态的.
随意查看一个代码库, 可以看到代码的编写过程, 某些代码可能在现在看来实现很低效和可笑, 但是在当时的技术和时间场景下, 肯定是最优的输出.
也可以在 GitLab 上看看每次的 pull request , 看看当时对这些代码的 codeReview ;
反馈出的问题就是程序的设计非常重要. 而接口是功能的抽象, 相对比较稳定, 对团队来说影响比较大.
**
API 设计原则
先给接口来个简单的定义: 即协议, 约定了请求和响应的参数和格式.
接口设计要求是:
1. 简洁;
2. 考虑到向后兼容;
业界有一些基本的原则:
1 restfull
restfull 是一种设计风格, 一切接口皆是资源.
目前是设计的主流, 思想也非常先进.
2 参数结构化
请求和响应中的参数要结构化, 好处是易读易用.
3 安全
这个怎么重要都不为过, 接口设计必须考虑认证和授权, 保证特定的人只能访问特定的资源.
同时需要注意在日志中不能含有用户和系统的敏感信息.
4 客户端无关
也就是接口要通用, 可以处理不同客户端的请求. 一般在接口设计的时候, 可以带入透传参数, 比如时区, 位置 (省市区), 系统类型, 系统版本, 应用类型, 应用版本等;
5 幂等
即接口的第一次请求的结果和后面 N 次的重试结果要不变, 需要结合场景来保证.
API 设计实践
接口框架选型
有了接口设计的原则, 可以挑选一个可靠的接口框架来支持自己的工作,
一个好的接口框架应该有如下特点:
对访问控制的支持;
自动测试的支持;
请求响应格式和序列化的支持;
日志和日志过滤的支持;
自动生成文档的支持;
对架构和性能的影响较小;
我一般选的 springmvc, 因为平时工作跟 spring 贴合的比较紧, 而且 spring 有各种生态, 适合在不同的行业和公司使用. jersey 也用, 虽然灵活, 但是不具备普遍适用性;
设计中的平衡
1 设定团队的 API 设计和实现模式
API 太自由, 会影响团队的协作, 而共同约定 API 的设计模式和实现模式可以解决这个问题.
2 避免过度设计
要综合考虑向后的兼容性, 但是只实现当前软件当前阶段必须的功能点.
3 谨慎使用 AOP
面向切面编程可以在跟业务无关的垂直领域处理问题, 比如日志, 监控, 解析等; 可以提高代码的重用性和规范性;
但是也有缺点, 比如, 增加了测试和分析的难度, 也对研发人员要求比较高.
所以需要综合考虑.
4 可维护性和性能之间要平衡
接口实现进行封装可以提高可维护性, 但是也会带来性能开销, 所以也是需要综合考虑的.
**
小结
通过本篇文章你可以学到如下内容:
[ ] 接口设计的原则
[ ] 接口设计框架选型要点
[ ] 接口设计过程中的设计实践问题
设计良好的接口, 可以提高软件的复用性, 提高团队的输出效率和质量.
来源: https://www.cnblogs.com/snidget/p/12371410.html