HTTP+json格式接口的描述
前端通过HTTP协议发出请求(Ajax请求)，调用这样的语句“$.get("api/queryOrder?status=1")”，可以用参数status表示只取指定状态的记录，后端响应，返回JSON格式的数据，并以数组(...)等格式展示，数组(...)每一项为一条记录，包括了整型的id, 浮点型的总价total等的记录属性（数据类型）。
1.前端HTTP发请求（GET请求/Ajax请求）
GET api/queryOrder?status=1 //应用层定义网址中，queryOrder是调用名，status是调用函数，参数通过urlencoded方式传递
2.后端服务器响应
200 OK // 200表示成功响应
[{id:1, dscr:"order 1", total:100}, {id:2, dscr:"order 2", status:1}] // 返回数据 {id ,dscr,total}
描述接口有的2P（Protocol/Prototype）攻略
- 协议（Protocol）：调用方和被调用方是怎样交互的，比如基于HTTP协议，请求参数用urlencoded格式，返回内容用JSON格式；
- 原型（Prototype）：描述的是一个请求的内容，调用名称，参数和返回内容是什么含义，以及类型。
它们分别描述了交互的方式与内容。
实例：spring boot微服务架构开发接口
1.前期协商
接口开发前，由接口开发方和接口调用方定义接口规范，接口规范确定后同步到wiki。接口开发方和接口调用方根据接口规范双向开展工作。
2.接口开发方
@Path("/***")
@Produces(MediaType.APPLICATION_JSON)
public class ***Resource {
@GET
public ApiResponse list(@QueryParam("***") String ***, @DefaultValue("1") @QueryParam("***") int ***) {
List<***DTO> *** = new ArrayList<>();
......
return ApiResponseBuilder.ok().entity(***).build();
}
}
3.list方法返回数据格式为ApiResponse实体，通过@Produces(MediaType.APPLICATION_JSON)注解，将实体转为json返回
ApiResponse实体内容：
public class ApiResponse {
public static final Object EMPTY = "";
private int status;
private String message;
private Object entity = EMPTY;
/**
*
*/
public static class ApiResponseBuilder{
private ApiResponse apiResponse;
public ApiResponseBuilder(ApiResponse resp){
this.apiResponse = resp;
}
public static ApiResponseBuilder ok(){
return status(HttpServletResponse.SC_OK).msg("ok");
}
public static ApiResponseBuilder status(int status){
ApiResponse resp = new ApiResponse();
resp.setStatus(status);
return new ApiResponseBuilder(resp);
}
public ApiResponseBuilder msg(String msg){
this.apiResponse.setMessage(msg);
return this;
}
public ApiResponseBuilder entity(Object entity){
this.apiResponse.setEntity(entity);
return this;
}
public ApiResponse build(){
return apiResponse;
}
}
public int getStatus() {
return status;
}
public void setStatus(int status) {
this.status = status;
}
public String getMessage() {
return message;
}
public void setMessage(String message) {
this.message = message;
}
public Object getEntity() {
return entity;
}
public void setEntity(Object entity) {
this.entity = entity;
}
}
4.接口调用方
在application.properties配置下接口调用的url地址，代码级别，我们通过org.springframework.web.client.RestTemplate发起接口调用。
@Value(value = "${url}")
private String url;
RestTemplate temp = new RestTemplate();
String json = temp.getForObject(url, String.class, "***");
JsonNode root = ***.getJsonNode(json);
Entity entity = ***.getEntityFromJsonNode(root);
5.总结
以接口规范为基础，开发方和调用方都依赖接口规范，这样可以很大程度的减小接口开发方和调用方的耦合关系，同时使用spring boot微服务架构，可以方便的部署接口高可用集群。
实例：WebService接口开发和调用
1.Web Service基本概念
WebService是一种可以接收从Internet上的其它系统中传递过来的请求，轻量级的独立的通讯技术。依据Web Service规范实施的应用之间， 无论它们所使用的语言、 平台或内部协议是什么， 都可以相互交换数据。通过SOAP在Web上提供的软件服务，使用WSDL文件进行说明，并通过UDDI进行注册，用于开发分布式的互操作的应用程序。Web Service为整个企业甚至多个组织之间的业务流程的集成提供了一个通用机制。
2.Web Service 的四大部分
XML：(Extensible Markup Language)扩展型可标记语言。面向短期的临时数据处理、面向万维网络，是Soap的基础。
Soap：(Simple Object Access Protocol)简单对象存取协议。是XML Web Service 的通信协议，它是用于交换XML（标准通用标记语言下的一个子集）编码信息的轻量级协议。当用户通过UDDI找到你的WSDL描述文档后，他通过可以SOAP调用你建立的Web服务中的一个或多个操作。SOAP是XML文档形式的调用方法的规范，它可以支持不同的底层接口，像HTTP(S)或者SMTP。它有三个主要方面：XML-envelope为描述信息内容和如何处理内容定义了框架，将程序对象编码成为XML对象的规则，执行远程过程调用(RPC)的约定。SOAP可以运行在任何其他传输协议上。例如，你可以使用 SMTP，即因特网电子邮件协议来传递SOAP消息，这可是很有诱惑力的。在传输层之间的头是不同的，但XML有效负载保持相同。
WSDL：(Web Services Description Language) WSDL 文件是一个 XML 文档，用于说明一组 SOAP 消息以及如何交换这些消息。大多数情况下由软件自动生成和使用。
UDDI (Universal Description, Discovery, and Integration) 是一个主要针对Web服务供应商和使用者的新项目。在用户能够调用Web服务之前，必须确定这个服务内包含哪些商务方法，找到被调用的接口定义，还要在服务端来编制软件，UDDI是一种根据描述文档来引导系统查找相应服务的机制。UDDI利用SOAP消息机制（标准的XML/HTTP）来发布，编辑，浏览以及查找注册信息。它采用XML格式来封装各种不同类型的数据，并且发送到注册中心或者由注册中心来返回需要的数据。
3.Web Service 的调用原理
实现一个完整的Web服务包括以下步骤：
◆ Web服务提供者设计实现Web服务，并将调试正确后的Web服务通过Web服务中介者发布，并在UDDI注册中心注册； （发布）
◆ Web服务请求者向Web服务中介者请求特定的服务，中介者根据请求查询UDDI注册中心，为请求者寻找满足请求的服务； （发现）
◆ Web服务中介者向Web服务请求者返回满足条件的Web服务描述信息，该描述信息用WSDL写成，各种支持Web服务的机器都能阅读；（发现）
◆ 利用从Web服务中介者返回的描述信息生成相应的SOAP消息，发送给Web服务提供者，以实现Web服务的调用；（绑定）
◆ Web服务提供者按SOAP消息执行相应的Web服务，并将服务结果返回给Web服务请求者。（绑定）
4.Web Service调用的3种方式
1). httpget ：不可传结构化数据
2). httppost ：不可传结构化数据
3). httpsoap ：可传结构化数据，最终也是使用 HTTP 传送 XML
5.Web Service 的2种类型
1.SOAP Webservice：SOAP用来描述传递信息的格式，WSDL 用来描述如何访问具体的接口，UDDI用来管理，分发，查询webService 。
2.RESTful Webservice：RESTful 简化了 web service 的设计，它不再需要 WSDL ，也不再需要 SOAP 协议，而是通过最简单的 http 协议传输数据 ( 包括 xml 或 json) 。既简化了设计，也减少了网络传输量（因为只传输代表数据的 xml 或 json ，没有额外的 xml 包装）。
区别：
REST是一种架构风格，其核心是面向资源；而webService底层SOAP协议，主要核心是面向活动；
REST
REST即表述性状态传递（英文：Representational State Transfer，简称REST），它是一种针对网络应用的设计和开发方式，可以降低开发的复杂性，提高系统的可伸缩性。REST通常基于使用HTTP，URI，和XML（标准通用标记语言下的一个子集）以及HTML（标准通用标记语言下的一个应用）这些现有的广泛流行的协议和标准。
最轻量级的应用协议就是Http协议。Http协议所抽象的get,post,put,delete就好比数据库中最基本的增删改查，而互联网上的各种资源就好比数据库中的记录，对于各种资源的操作最后总是能抽象成为这四种基本操作，在定义了定位资源的规则以后，对于资源的操作通过标准的Http协议就可以实现，开发者也会受益于这种轻量级的协议。
REST专门针对网络应用设计和开发方式，以降低开发的复杂性，提高系统的可伸缩性。REST提出设计概念和准则为：
- 1. 网络上的所有事物都可以被抽象为资源(resource)
- 2. 每一个资源都有唯一的资源标识(resource identifier)，对资源的操作不会改变这些标识
- 3. 所有的操作都是无状态的
REST简化开发，其架构遵循CRUD原则，该原则告诉我们对于资源(包括网络资源)只需要四种行为：创建，获取，更新和删除就可以完成相关的操作和处理。我们可以通过统一资源标识符（Universal Resource Identifier，URI）来识别和定位资源，并且针对这些资源而执行的操作是通过 HTTP 规范定义的。其核心操作只有GET,PUT,POST,DELETE。由于REST强制所有的操作都必须是stateless的，这就没有上下文的约束，如果做分布式，集群都不需要考虑上下文和会话保持的问题。极大的提高系统的可伸缩性。
SOAP webService有严格的规范和标准，包括安全，事务等各个方面的内容，同时SOAP强调操作方法和操作对象的分离，有WSDL文件规范和XSD文件分别对其定义。