0226 rest接口设计
背景
为了更方便的书写和阐述问题,文章中按照第一人称的角度书写。作为一个以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 可维护性和性能之间要平衡
接口实现进行封装可以提高可维护性,但是也会带来性能开销,所以也是需要综合考虑的。
**
小结
通过本篇文章你可以学到如下内容:
- [ ] 接口设计的原则
- [ ] 接口设计框架选型要点
- [ ] 接口设计过程中的设计实践问题
设计良好的接口,可以提高软件的复用性,提高团队的输出效率和质量。
原创不易,转载请注明出处。
0226 rest接口设计的更多相关文章
- 数据仓储之DLL层接口设计
一.接口设计 1.1. IBaseRepository.cs public interface IBaseRepository<T> { T Add(T entity); bool Upd ...
- RESTful接口设计原则/最佳实践(学习笔记)
RESTful接口设计原则/最佳实践(学习笔记) 原文地址:http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api 1 ...
- Web API接口设计经验总结
在Web API接口的开发过程中,我们可能会碰到各种各样的问题,我在前面两篇随笔<Web API应用架构在Winform混合框架中的应用(1)>.<Web API应用架构在Winfo ...
- Verilog学习笔记简单功能实现(七)...............接口设计(并行输入串行输出)
利用状态机实现比较复杂的接口设计: 这是一个将并行数据转换为串行输出的变换器,利用双向总线输出.这是由EEPROM读写器的缩减得到的,首先对I2C总线特征介绍: I2C总线(inter integra ...
- 优秀的API接口设计原则及方法(转)
一旦API发生变化,就可能对相关的调用者带来巨大的代价,用户需要排查所有调用的代码,需要调整所有与之相关的部分,这些工作对他们来说都是额外的.如果辛辛苦苦完成这些以后,还发现了相关的bug,那对用户的 ...
- atitit.基于http json api 接口设计 最佳实践 总结o7
atitit.基于http json api 接口设计 最佳实践 总结o7 1. 需求:::服务器and android 端接口通讯 2 2. 接口开发的要点 2 2.1. 普通参数 meth,p ...
- App接口设计
关于APP接口设计 http://blog.csdn.net/gebitan505/article/details/37924711/
- App接口设计原则-b
1.记住密码不是真的让你记住密码,这里仅仅指的是一种自动登录的手段.不管在任何地方,明文存储的密码都是安全隐患,是必须尽量避免的.你可以采用某种方式对用户名.密码以及时间戳(重要)进行签名,再次登录时 ...
- 蓝牙(BLE)应用框架接口设计和应用开发——以TI CC2541为例
本文从功能需求的角度分析一般蓝牙BLE单芯片的应用框架(SDK Framework)的接口设计过程,并以TI CC2541为例说明BLE的应用开发方法. 一.应用框架(Framework) 我们熟知的 ...
随机推荐
- JavaScript(1)---绑定事件、解除绑定事件
JavaScript(1)---绑定事件.解除绑定事件 一.事件概述 1.事件的几个概念 · 事件 指的是文档或者浏览器窗口中发生的一些特定交互瞬间.我们可以通过侦听器(或者处理程序)来预定事件,以便 ...
- 洛谷 P5424 [USACO19OPEN]Snakes
题目链接 题目描述 传说,数千年前圣帕特里克消灭了哞尔兰所有的蛇.然而,蛇们现在卷土重来了!圣帕特里克节是在每年的3月17日,所以Bessie要用彻底清除哞尔兰所有的蛇来纪念圣帕特里克. Bessie ...
- spring-cloud-gateway报错
2019-08-13 09:41:19.216 WARN [-,,,] 10084 --- [ main] ConfigServletWebServerApplicationContext : Exc ...
- 约束路由 用正则表达式约束路由 Constraining a Route Using a Regular Expression 精通ASP-NET-MVC-5-弗瑞曼
- Spring Boot动态注入删除bean
Spring Boot动态注入删除bean 概述 因为如果采用配置文件或者注解,我们要加入对象的话,还要重启服务,如果我们想要避免这一情况就得采用动态处理bean,包括:动态注入,动态删除. 动态注入 ...
- 缓存 ehcache
只是用于自己记录,防止日后忘记,回看所用 第一步:配置ehcahe 缓存 <?xml version="1.0" encoding="UTF-8"?> ...
- springcloud ActiveMQ设置多个并行消费者
还是结合实际项目说把,最近在做跟保险公司和第三方借贷平台对接的项目: 其中需要第三方借贷平台借款并和保险挂对勾,也就是每次借钱的时候可以做一次保: 这里面正常情况下的逻辑场景: 借贷平台:借贷审核通过 ...
- Arduino系列之LCD1602模块使用方法(一)
下面我将简单介绍LCD1602模块的使用方法: 1602液晶显示器(1602 Liquid Crystal Display,此后简称1602 LCD)是一种常见的字符液晶显示器,因其能显示16*2个字 ...
- uml-类图书写指南
说明 类图是最常用的UML图,面向对象建模的主要组成部分.它用于描述系统的结构化设计,显示出类.接口以及它们之间的静态结构和关系. 类图主要产出于面向对象设计的分析和设计阶段,用来描述系统的静态结构. ...
- MyBatis基础_连接池与事务、动态SQL、注解开发
一.MyBatis连接池及事务控制 1.连接池 在实际开发中,都会使用连接池,因为它可以减少获取连接缩消耗的时间.所谓连接池,就是存储数据库连接的容器.连接池中存储一定数量的数据库连接,当线程需要使用 ...