发表于: 2018-04-25 23:58:40
1 659
今天完成的事情:
1.更改接口格式,满足接口规范:
2.总结深度思考的1~14
明天计划的事情
完成剩下的深度思考总结
使用postman验证接口
遇到的问题:
收获:
关于Http开发的常识
深度思考
1.什么是restful?rest的请求方法有哪些,有什么区别?
restFul是符合rest架构风格的网络API接口,完全承认Http是用于标识资源。restFul URL是面向资源的,可以唯一标识和定位资源。 对于该URL标识的资源做何种操作是由Http方法决定的。 rest请求方法有4种,包括get,post,put,delete.分别对应获取资源,添加资源,更新资源及删除资源.
2.为什么要用Rest风格,如果不用Rest的话,接口应该怎么定义,在使用Rest风格之前,大家都是用什么方式写接口的?
REST是一种针对网络应用的设计和开发方式,可以降低开发的复杂性,提高系统的可伸缩性。REST提出了一些设计概念和准则:
1.网络上的所有事物都被抽象为资源(resource);
2.每个资源对应一个唯一的资源标识(resource identifier);
3.通过通用的连接器接口(generic connector interface)对资源进行操作;
4.对资源的各种操作不会改变资源标识;
5.所有的操作都是无状态的(stateless)。
REST之所以能够简化开发,是因为其引入的架构约束,对REST的实现把controller中的方法限制在7个:index、show、new、edit、create、update和destory,这实际上就是对CURD的实现。更进一步讲,大部分网络应用)使用HTTP作为generic connector interface,HTTP则把对一个url的操作限制在了4个之内:GET、POST、PUT和DELETE。
REST之所以能够提高系统的可伸缩性,是因为它强制所有操作都是stateless的,这样就没有context的约束。同时,它令系统可以有效地使用pool。REST对性能的另一个提升来自其对client和server任务的分配:server只负责提供resource以及操作resource的服务,而client要根据resource中的data和representation自己做render。这就减少了服务器的开销。
REST风格之前的接口:
SOAP简单对象访问协议是在分散或分布式的环境中交换信息的简单的协议,是一个基于XML的协议,SOAP最早是针对RPC的一种解决方案,简单对象访问协议,很轻量,同时作为应用协议可以基于多种传输协议来传递消息(Http,SMTP等)。但是随着SOAP作为WebService的广泛应用,不断地增加附加的内容,使得现在开发人员觉得SOAP很重,使用门槛很高。在SOAP后续的发展过程中,一系列协议的制定,增加了SOAP的成熟度,也给SOAP增加了负担。
3.了解maven的module。
随着技术的飞速发展和各类用户对软件的要求越来越高,软件本身也变得越来越复杂,然后软件设计人员开始采用各种方式进行开发,于是就有了我们的分层架构,分模块开发,来提高代码的清晰和重用。针对于这一特性,maven也给予了相应的配置。
我们在开发过程中,创建了2个以上的模块,每个模块都是一个独立的maven项目,在开始的时候我们可以独立的编译和测试运行每个模块,但是随着项目的不断变大和复杂化,我们期望能够使用简单的操作来完成编译等工作,这时的Maven给出了聚合的配置方式。
所谓聚合,顾名思义,就是把多个模块或项目聚合到一起,我们可以建立一个专门负责聚合工作的Maven项目。所有用Maven的管理的真实的项目都应该是分模块的,每个模块都对应着一个pom.xml的。它们之间通过继承和聚合(也称作多模块,多模块)相互关联
Maven的多模块项目,适用于一些比较大的项目,通过合理的模块拆分,实现代码的复用,便于维护和管理。尤其是一些开源框架,也是采用多模块的方式,提供插件集成,用户可以根据需要配置指定的模块。
项目层次的划分替代包层次的划分的好处:
(1)方便重用,如果你有一个新的摆动项目需要用到的应用-DAO和应用程序服务,添加对它们的依赖即可,你不再需要去依赖一个WAR。而有些模块,如应用程序,UTIL ,完全可以渐渐进化成公司的一份基础工具类库,供所有项目使用。这是模块化最重要的一个目的。
(2)由于你现在划分了模块,每个模块的配置都在各自的的pom.xml里,不用再到一个混乱的纷繁复杂的总的POM中寻找自己的配置。
(3)如果你只是在应用-DAO上工作,你不再需要建立整个项目,只要在应用-DAO目录运行MVN命令进行建立即可,这样可以节省时间,尤其是当项目越来越复杂,建越来越耗时后。
(4)某些模块,如APP-util的被所有人依赖,但你不想给所有人修改,现在你完全可以从这个项目结构出来,做成另外一个项目,SVN只给特定的人访问,但仍提供罐子给别人使用。
4.什么是http协议?Get和post请求有什么区别?http请求content-Type有几种,有什么区别?http适合什么场景?http状态码有哪些?
HTTP协议:客户端和服务器交互需要制定一套标准的协议规范(HTTP其中的一种)
http协议架构清晰,分为请求报文和响应报文两部分 分别针对客户端和服务器 对应的端根据对应的报文部分按照要求完成操作就可以实现交互,使用广泛,特点:短连接,(客户端请求成功之后自动断开) 单向:客户端向服务器发送请求
Get:要求服务器将URL定位的资源放在响应报文的数据部分,回送给客户端 特点:请求格式比较固定 服务器url地址?请求的参数 get请求一般数据都是直接追加到url后面不用写到请求数据部分,那么长度就会受到限制 一般最多只能识别1024个字符,数据暴漏在url后面不安全
POST:请求的数据放到了对应的请求数据区里面所以相比较get请求要安全,同时长度不会像get请求一样有对应的限制
Content-Type
MediaType,即是Internet Media Type,互联网媒体类型;也叫做MIME类型,在Http协议消息头中,使用Content-Type来表示具体请求中的媒体类型信息。
[html] view plain copy
类型格式:type/subtype(;parameter)? type
主类型,任意的字符串,如text,如果是号代表所有;
subtype 子类型,任意的字符串,如html,如果是号代表所有;
parameter 可选,一些参数,如Accept请求头的q参数, Content-Type的 charset参数。
例如: Content-Type: text/html;charset:utf-8;
常见的媒体格式类型如下:
text/html : HTML格式
text/plain :纯文本格式
text/xml : XML格式
image/gif :gif图片格式
image/jpeg :jpg图片格式
image/png:png图片格式
以application开头的媒体格式类型:
application/xhtml+xml :XHTML格式
application/xml : XML数据格式
application/atom+xml :Atom XML聚合格式
application/json : JSON数据格式
application/pdf :pdf格式
application/msword : Word文档格式
application/octet-stream : 二进制流数据(如常见的文件下载)
application/x-www-form-urlencoded : <form encType=””>中默认的encType,form表单数据被编码为key/value格式发送到服务器(表单默认的提交数据的格式)
另外一种常见的媒体格式是上传文件之时使用的:
multipart/form-data : 需要在表单中进行文件上传时,就需要使用该格式
Socket适用场景:网络游戏,银行交互,支付。
http适用场景:公司OA服务,互联网服务。
HTTP状态码
状态码都是三位数字 ,第一位表示状态类别,共分五种,如下:
1xx表示通知消息的,如请求收到了或正在进行处理
2xx表示成功,如接受或知道了
3xx表示重定向,表示要完成请求还必须采取进一步的行动
4xx表示客户端的差错,如请求中有错误的语法或不能完成
5xx表示服务器的差错,如服务器失效无法完成请求
5.什么是tcp/ip协议?TCP的三次握手指的是什么,为什么一定要三次握手,而不是四次或者是两次?
TCP/IP也称"国际协议簇", 即不仅指 TCP/IP协议本身,而且包括与其有关的协议。 TCP为传输控制协议,IP为网际协议,是网络层最重要的协议。采用TCP/IP协议通过互联网传送信息可减少网络中的传输阻塞,方便大批量的数据在网上传输,从而提高网络的传输效率。
TCP/IP协议族中包括上百个互为关联的协议,其中有:
Telnet(Remote Login): 提供远程登录功能;
FTP (FileTransfer Protocol):远程文件传输协议,允许用户将远程主机上的文件拷贝到自己的计算机上;
SMTP (Simple Messagetransfer Protocol):简单信息传输协议,主要用于传输电子邮件;
NFS(Network File Server):网络文件服务器,可使多台计算机透明地访问彼此的目录 ;
UDP ( User DatagramProtocol):用户数据包协议。
为什么需要采用三次握手?
主要是为了防止两次握手情况下已失效的连接请求报文段突然又传送到服务端,而产生的错误。
举例如下:
客户A向服务器B发出TCP连接请求,第一个连接请求报文在网络的某个节点长时间滞留,A超时后认为报文丢失,于是再重传一次连接请求,B收到后建立连接。数据传输完毕后双方断开连接。而此时,前一个滞留在网络中的连接请求到达了服务端B,而B认为A又发来连接请求,若采用的是“两次握手”,则这种情况下B认为传输连接已经建立,并一直等待A传输数据,而A此时并无连接请求,因此不予理睬,这样就造成了B的资源白白浪费了;但此时若是使用“三次握手”,则B向A返回确认报文段,由于是一个失效的请求,因此A不予理睬,建立连接失败。第三次握手的作用:防止已失效的连接请求报文段突然又传送到了服务器。
6.什么是WEBService,实现WEBService有哪些框架,为什么WEBService经常被认为太重了,只有银行和大型国企才会使用的更多有一些?
WebService是什么
Web service是一种通过网络来获取的计算机服务功能。
比较流行几个框架:
Apache Axis1、Apache Axis2、Codehaus XFire、Apache CXF、Apache Wink、Jboss RESTEasy、sun JAX-WS(最简单、方便)、阿里巴巴 Dubbo
Web服务现在所面对的主要的局限性:
- 内部功能实现的限制
- 匹配合适的Web服务
- 通用的实现 vs. 定制的实现
- 服务发布的粒度
- Web服务持续支持的保证
如果开发者能够开发出必要的代码,那么Web服务将会成为商业上的一个可行的选择。这也许意味着对于开发者、设计者和部署者的高要求。由于目前,Web服务是一门新技术,开发人员、设计人员、部署人员都没有被完善地培训和培养,开发Web服务毕竟承担着高额的风险。同时,也许公司的Web服务需求太复杂了,无法用一般提供的服务解决。并且他们也不能找到能够提供需求定制的公司。如果公司在这样的情况下,Web服务也许不再是答案了。
而对于第2和第3个问题,"我们提供或匹配什么类型的Web服务�D�D一般的还是定制的?",这个问题应该说并没有一个比较完善的答案。它依赖域你将发布和使用的Web服务的种类。一些服务是为了通用性的目的,如清算帐目服务,而其他的一些服务则可能面对更加细分的的市场。同样,如果你有一个服务程序,并且你想作为Web服务发布,你准备发布多少?你的新的应用程序准备多大程度上依赖于Web服务?
Web服务的粒度依赖于应用设计的程度。另外一个可能是更严重的局限是:Web服务能否是连续的工作,它的可靠性如何保证。你如何保证你的Web服务将一直可用?什么程度的"停工"是可以接受的?一个响应要花费多长时间?一定程度上来说,这些问题可以被严格的服务管理模块来处理,以实时地核查Web服务的质量。也许会出现一些提供Web服务可靠性管理的中介服务,以通过Web服务连接的方式来测试Web服务的可靠性。
只有大型国企和银行能够满足开发的稳定性
7.Spring MVC和Struts的区别是什么,为什么更倾向于使用Spring MVC?
1、Struts2是类级别的拦截, 一个类对应一个request上下文,SpringMVC是方法级别的拦截,一个方法对应一个request上下文,而方法同时又跟一个url对应,所以说从架构本身上SpringMVC就容易实现restful url,而struts2的架构实现起来要费劲,因为Struts2中Action的一个方法可以对应一个url,而其类属性却被所有方法共享,这也就无法用注解或其他方式标识其所属方法了。
2、由上边原因,SpringMVC的方法之间基本上独立的,独享request response数据,请求数据通过参数获取,处理结果通过ModelMap交回给框架,方法之间不共享变量,而Struts2搞的就比较乱,虽然方法之间也是独立的,但其所有Action变量是共享的,这不会影响程序运行,却给我们编码 读程序时带来麻烦,每次来了请求就创建一个Action,一个Action对象对应一个request上下文。
3、由于Struts2需要针对每个request进行封装,把request,session等servlet生命周期的变量封装成一个一个Map,供给每个Action使用,并保证线程安全,所以在原则上,是比较耗费内存的。
4、 拦截器实现机制上,Struts2有以自己的interceptor机制,SpringMVC用的是独立的AOP方式,这样导致Struts2的配置文件量还是比SpringMVC大。
5、SpringMVC的入口是servlet,而Struts2是filter(这里要指出,filter和servlet是不同的。以前认为filter是servlet的一种特殊),这就导致了二者的机制不同,这里就牵涉到servlet和filter的区别了。
6、SpringMVC集成了Ajax,使用非常方便,只需一个注解@ResponseBody就可以实现,然后直接返回响应文本即可,而Struts2拦截器集成了Ajax,在Action中处理时一般必须安装插件或者自己写代码集成进去,使用起来也相对不方便。
7、SpringMVC验证支持JSR303,处理起来相对更加灵活方便,而Struts2验证比较繁琐,感觉太烦乱。
8、Spring MVC和Spring是无缝的。从这个项目的管理和安全上也比Struts2高(当然Struts2也可以通过不同的目录结构和相关配置做到SpringMVC一样的效果,但是需要xml配置的地方不少)。
9、 设计思想上,Struts2更加符合OOP的编程思想, SpringMVC就比较谨慎,在servlet上扩展。
10、SpringMVC开发效率和性能高于Struts2。
11、SpringMVC可以认为已经100%零配置。
8.web.xml里的主要配置都包括什么,都代表什么含义,比如怎么加载Spring 配置的?
一、web.xml文件的特点(规则):
必须有且只有一个根节点,大小写敏感,标签不嵌套,必须配对。
二、web.xml文件的作用:
web.xml文件是用来初始化配置信息:比如Welcome页面、servlet、servlet-mapping、filter、listener、启动加载级别等。
当你的web工程没用到这些时,你可以不用web.xml文件来配置你的Application。
三、web.xml能做的事情:
在web.xml的模式(Schema)文件中定义了多少种标签元素,web.xml中就可以出现它的模式文件所定义的标签元素,它就能拥有定义出来的那些功能。
而且web.xml的模式文件中定义的标签并不是定死的,模式文件也是可以改变的,一般来说,随着web.xml模式文件的版本升级,里面定义的功能会越来越复杂,也即标签元素的种类会越来越多,但有些是不常用的,我们只需记住一些常用的就可以了。
2.知识剖析
下面列出web.xml文件中的主要标签及其含义:
一、欢迎页面
访问一个网站时,默认看到的第一个页面就叫欢迎页,一般情况下是由首页来充当欢迎页的。一般情况下,我们会在web.xml中指定欢迎页。
但web.xml并不是一个Web的必要文件,没有web.xml,网站仍然是可以正常工作的。只不过网站的功能复杂起来后,web.xml的确有非常大用处,所以,默认创建的动态web工程在WEB-INF文件夹下面都有一个web.xml文件。
二、命名和定制URL
为Servlet和JSP文件命名并定制URL,其中定制URL是依赖命名的,命名必须在定制URL前。
三、定制初始化参数
定制servlet、JSP、Context的初始化参数,然后可以在servlet、JSP、Context中获取这些参数值。
四、设置过滤器
Servlet中的过滤器Filter是实现了javax.servlet.Filter接口的服务器端程序,主要的用途是过滤字符编码、做一些业务逻辑判断等。其工作原理是,只要你在web.xml文件配置好要拦截的客户端请求,它都会帮你拦截到请求,此时你就可以对请求或响应(Request、Response)统一设置编码,简化操作;同时还可进行逻辑判断,如用户是否已经登陆、有没有权限访问该页面等等工作。它是随你的web应用启动而启动的,只初始化一次,以后就可以拦截相关请求,只有当你的web应用停止或重新部署的时候才销毁。
五、设置监听器
Servlet的监听器Listener,它是实现了javax.servlet.ServletContextListener 接口的服务器端程序,它也是随web应用的启动而启动,只初始化一次,随web应用的停止而销毁。主要作用是: 做一些初始化的内容添加工作、设置一些基本的内容、比如一些参数或者是一些固定的对象等等。
3.常见问题
1.web.xml 文件中一般包括 servlet, spring, filter, listener的配置。那么他们是按照一个什么顺序加载呢?
加载顺序与他们在web.xml 文件中的先后顺序无关。先 listener >> filter >> servlet >> spring
2.url-pattern配置为"/"和"/*"的区别
1、"/"可以匹配所有url,包括带扩展名的,一般只用在过滤器上。
例如:会匹配.jsp,会出现返回jsp视图时再次进入spring的DispatcherServlet
类,导致找不到对应的controller所以报404错。
2、而"/"很多人理解成不能拦截带扩展名的,这种理解是错误的!它其实也能拦截“.js”,“.css”,".png"等静态资源的访问。
例如:不会匹配到.jsp,即.jsp不会进入spring的 DispatcherServlet类 。看官方文档可知,它是tomcat的默认servlet,当其他的url-pattern匹配不上时都会走这个servlet。它除了能够处理静态资源还能够处理HTTP缓存请求,媒体(音频/视频)数据流和文件下载简历。所以如果我们的项目中配置了"/",会覆盖掉tomcat中的default servlet。
所以当springMVC的前端控制器配置为“/”时,需要在主配置文件中配置放行静态资源。
第一种:
<!-- 放行静态资源 -->
<mvc:resources location="/js/" mapping="/js/**"/>
<mvc:resources location="/css/" mapping="/js/**"/>
<mvc:resources location="/images/" mapping="/js/**"/>
第二种:
<mvc:default-servlet-handler />
9.Annotation和XML两种配置的差别,为什么更喜欢使用Annotaion来配置Spring MVC?
注解与XML配置的区别
注解:是一种分散式的元数据,与源代码紧绑定。
xml:是一种集中式的元数据,与源代码无绑定。因此注解和XML的选择上可以从两个角度来看:分散还是集中,源代码绑定/无绑定。
注解的缺点:
1、很多朋友比如在使用spring注解时,会发现注解分散到很多类中,不好管理和维护;这个其实要借助工具,我目前使用的是IDEA,它在这方面表现的非常好;当然现在还有Spring的STS,也是不错的;
所以借助工具,能解决这个问题;
2、注解的开启/关闭必须修改源代码,因为注解是源代码绑定的,如果要修改,需要改源码,这个有这个问题,所以如果是这种情况,还是使用XML配置方式;比如数据源;
3、注解还一个缺点就是灵活性,比如在之前翻译的Spring Framework 4.0 M1: WebSocket
支持;在实现复杂的逻辑上,没有XML来的更加强大;注解就是要么用,要么不用,比如之前的jpa bean
validation,要么全,要么没;遇到这种情况很痛苦;
4、还一种就是约定大于配置,但是在处理一些复杂的情况下,注解还是需要的(如Spring的数据验证/数据绑定注解很强大);
5、通用配置还是走XML吧,比如事务配置,比如数据库连接池等等,即通用的配置集中化,而不是分散化,如很多人使用@Transactional来配置事务,在很多情况下这是一种太分散化的配置;
6、XML方式比注解的可扩展性和复杂性维护上好的多,比如需要哪些组件,不需要哪些;在面对这种情况,注解扫描机制比较逊色,因为规则很难去写或根本不可能写出来;注解的好处:
1、XML配置起来有时候冗长,此时注解可能是更好的选择,如jpa的实体映射;注解在处理一些不变的元数据时有时候比XML方便的多,比如springmvc的数据绑定,如果用xml写的代码会多的多;
2、注解最大的好处就是简化了XML配置;其实大部分注解一定确定后很少会改变,所以在一些中小项目中使用注解反而提供了开发效率,所以没必要一头走到黑;
3、注解相对于XML的另一个好处是类型安全的,XML只能在运行期才能发现问题。注解也好,XML也好,我们还是需要一些开关/替换机制来控制特殊需求,以改变那种要么全部 要么没有的方案。
还一种呼声就是约定大于配置,这种方案可能在某些场景下是最优的,但是遇到一些复杂的情况可能并不能解决问题,所以此时注解也是一个不错的方案。尤其在使用springmvc时,好处是能体会的出的。
不管使用注解还是XML,做的事情还是那些事情,但注解和XML都不是万能的,满足自己的需求且已一种更简单的方式解决掉问题即可
就像探讨一下技术问题,很多人都带有很强的个人喜好来评判一个东西的好坏,这种探讨没有任何意义,我们最终的目的是解决方案,所以我们应该探讨的是能不能解决问题,能不能以更容易理解的方式解决问题,能不能更简单的解决问题。不管是约定大于配置、注解还是XML配置也好,没有哪个是最优的,在合适的场景选择合适的解决方案这才是重要的。就像设计模式一样:是对特定环境中重复出现的特定问题的一个经过前人验证了的解决方案。
10.使用Annotaion的时候需要有哪些配置,他的加载过程是怎么样的?
不是程序本身,可以对程序作出解释(其实这一点,和注释很像)可以被其他程序(比如:编译器)读取(注解信息处理流程,是注解和注释的重大区别,如果没有注解信息处理流程,则注解毫无意义)
Annotation的格式:
注解是以”@注释名”在代码中存在的,还可以添加一些参数值,例如SuppressWarnings(value=”all”)
Annotation在哪里使用
可以附加在package、class、mehod、field等上面,相当于给它们添加了额外的辅助信息,我们可以通过反射机制实现对这些元数据的访问
11.什么是Filter,什么是Interceptor,他们的区别是什么,和AOP又是什么关系?
Filter(过滤器)与Interceptor(拦截器)和Spring AOP
Filter过滤器:拦截web访问url地址。
Interceptor拦截器:拦截以 .action结尾的url,拦截Action的访问。
Spring AOP拦截器:只能拦截Spring管理Bean的访问(业务层Service)
12.生成Json有几种方式,他们之间的好处和坏处分别是什么,为什么推荐使用JsonTaglib来处理Json?
一、json-lib json-lib最开始的也是应用最广泛的json解析工具,json-lib
不好的地方确实是依赖于很多第三方包,在http://Json.org网站上,Java可以使用的解析Json的组件就有21种之多。这里以使用org.json解析JSON为例。在读本文之前,读者有必要了解一下JSON的结构,这里不作介绍。首先下载org.json源码,下载地址:https://github.com/douglascrockford/JSON-java,点Downloads,Windows系统就选zip吧。当然你也可以用Git,只是我不太习惯那玩意。下载完后解压,在你的项目里新建一个名为org.json的包,把除README和Test.java以外的所有文件放入该包内(Eclipse只要拖进去就可以),现在我们就可以用org.json解析JSON.为了以后方便,你也可以把org.json这个包打成jar,在要用的项目上导入就行。
String s = "{\"person\":{\"name\":\"张三\",\"age\":20}}"; JSONObject jsonObj = new JSONObject(s); JSONObject result = jsonObj.getJSONObject("person"); System.out.println("姓名:"+result.getString("name")+" 年龄:"+result.getInt("age")); s="{\"persons\":[\"张三\",\"李四\",\"王五\"]}"; jsonObj = new JSONObject(s);JSONArray; jsonarr=jsonObj.getJSONArray("persons"); for(int i=0;i<jsonarr.length();i++) { System.out.println(jsonarr.getString(i)); }
二、开源的Jackson 相比json-lib框架,Jackson所依赖的jar包较少,简单易用并且性能也要相对高些。
而且Jackson社区相对比较活跃,更新速度也比较快。
Jackson对于复杂类型的json转换bean会出现问题,一些集合Map,List的转换出现问题。
Jackson对于复杂类型的bean转换Json,转换的json格式不是标准的Json格式三、Google的Gson
Gson是谷歌公司研发的。应用主要为toJson与fromJson两个转换函数,无依赖,不需要例外额外的jar,能够直接跑在JDK上。而在使用这种对象转换之前需先创建好对象的类型以及其成员才能成功的将JSON字符串成功转换成相对应的对象。
类里面只要有get和set方法,Gson完全可以将复杂类型的json到bean或bean到json的转换,是JSON解析的神器。
Gson在功能上面无可挑剔,但是性能上面比FastJson有所差距。
四、阿里的Fastjson
Fastjson是一个Java语言编写的高性能的JSON处理器,由阿里巴巴公司开发。
无依赖,不需要例外额外的jar,能够直接跑在JDK上。
FastJson在复杂类型的Bean转换Json上会出现一些问题,可能会出现引用的类型,导致Json转换出错,需要制定引用。
FastJson采用独创的算法,将parse的速度提升到极致,超过所有json库。
JsonTaglib该种方式,需要做如下操作,方可以轻松在jsp中使用标签:
1)将json-taglib.jar放入工程的lib下。
2)在jsp页面中做如下声明,即写入如下代码:
这样就可以在jsp中使用标签了。
13.一份规范的接口文档应该包括什么内容,衡量接口(API)设计好和坏的准则是什么?
1.背景介绍
什么是接口文档?
在项目开发中,web项目的前后端分离开发,APP开发,需要由前后端工程师共同定义接口,编写接口文档,之后大家都根据这个接口文档进行开发,到项目结束前都要一直维护。
2.知识剖析
为什么要写接口文档?
1、项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发
2、项目维护中或者项目人员更迭,方便后期人员查看、维护
接口规范是什么?
首先接口分为四部分:方法、uri、请求参数、返回参数
1、方法:新增(post) 修改(put) 删除(delete) 获取(get)
2、uri:以/a开头,如果需要登录才能调用的接口(如新增、修改;前台的用户个人信息,资金信息等)后面需要加/u,即:/a/u;中间一般放表名或者能表达这个接口的单词;
get方法,如果是后台通过搜索查询列表,那么以/search结尾,如果是前台的查询列表,以/list结尾
3、请求参数和返回参数,都分为5列:字段、说明、类型、备注、是否必填
字段是类的属性;
说明是中文释义;
类型是属性类型,只有String、Number、Object、Array四种类型;
备注是一些解释,或者可以写一下例子,比如负责json结构的情况,最好写上例子,好让前端能更好理解;
是否必填是字段的是否必填。
4、返回参数结构有几种情况:
1、如果只返回接口调用成功还是失败(如新增、删除、修改等),则只有一个结构体:code和message两个参数;
2、如果要返回某些参数,则有两个结构体:1是code/mesage/data,2是data里写返回的参数,data是object类型;
3、如果要返回列表,那么有三个结构体,1是code/mesage/data,data是object,里面放置page/size/total/list
4个参数,其中list是Arrary类型,list里放object,object里是具体的参数。3.常见问题
衡量接口(API)设计好和坏的准则是什么?
4.解决方案
单词拼写要准确,接口一旦发布就不能改了,要保持兼容性,拼写错误也不能改了,所以要仔细检查拼写,否则会被同行嘲笑很多年。
方法名称是否可以自描述,即看到方法的名字就能知道方法的作用、看到参数名就知道需要传递什么样的数据(比如getUserById(String
userId))API一定要便于使用者理解,这样才是广泛传播的基础。如果有些API需要用户掌握特定的概念、定义,那么就要保持这个API的一致性,不能轻易的改变API,否则会给使用者带来很大的麻烦。
接口参数验证必不可少,同时异常等返回信息得全面,让调用者明确异常原由;
14.Http的Header里面包含哪些字段,每个字段都有哪些含义?
HTTP首部字段根据实际用途被分为以下4种类型:
1、通用首部字段
请求报文和响应报文两方都会使用的首部。
2、请求首部字段
从客户端向服务器端发送请求报文时使用的首部。补充了请求的附加内容、客户端信息、响应内容相关优先级等信息。
3、响应首部字段
从服务器端向客户端返回报文时使用的首部。补充了响应的附加内容,也会要求客户端附加额外的内容信息。
4、实体首部字段
针对请求报文和响应报文的实体部分使用的首部。补充了资源内容更新时间等与实体有关的信息。
HTTP/1.1规范定义了如下47种首部字段
通用首部字段(9个)
首部字段名 说明
Cache-Control 控制缓存的行为
Connection 逐跳首部、连接的管理
Date 创建报文的日期时间
Program 报文指令
Trailer 报文末端的首部一览
Transfer-Encoding 指定报文主体的传输编码方式
Upgrade 升级为其他协议
Via 代理服务器的相关信息
Warning 错误通知
请求首部字段(19个)
首部字段名 说明
Accept 用户代理可处理的媒体类型
Accept-Charset 优先的字符集
Accept-Encoding 优先的内容编码
Accept-Language 优先的语言(自然语言)
Authorization Web认证信息
Expect 期待服务器的特定行为
From 用户的电子邮箱地址
Host 请求资源所在的服务器
If-Match 比较实体标记(ETag)
If-Modified-Since 比较资源的更新时间
If-None-Match 比较实体标记(与If-Match相反)
If-Range 资源未更新时发送实体Byte的范围请求
If-Unmodified-Since 比较资源的更新时间(与If-Modified-Since相反)
Max-Forwards 最大传输逐跳数
Proxy-Authorization 代理服务器要求客户端的认证信息
Range 实体的字节范围请求
Referer 对请求中的URI的原始获取方
TE 传输编码的优先级
User-Agent HTTP客户端程序的信息
响应首部字段(9个)
首部字段名 说明
Accept-Ranges 是否接受字节范围请求
Age 推算资源创建经过时间
Content-Disposition 可以控制返回的资源是下载还是预览(图片)
ETag 资源的匹配信息
Location 令客户端重定向至指定URI
Proxy-Authenticate 代理服务器对客户端的认证信息
Retry-After 对再次发起请求的时机要求
Server HTTP服务器的安装信息
Vary 代理服务器缓存的管理信息
WWW-Authenticate 服务器对客户端的认证信息
实体首部字段(10个)
首部字段名 说明
Allow 资源可支持的HTTP方法
Content-Encoding 实体主体试用的编码方式
Content-Language 实体主体的自然语言
Content-Length 实体主体的大小(单位:字节)
Content-Location 替换对应资源的URI
Content-MD5 实体主体的报文摘要
Content-Range 实体主体的位置范围
Content-Type 实体主体的媒体类型
Expires 实体主体过期的日期时间
Last-Modified 资源的最后修改日期时间
评论