1. HTTP接口的意义

二进制接口使用的是java/hessian序列化协议，不能很好的与其他语言通信，虽然hessian也是一种跨语言的通用协议，但很多语言没有很好的实现该协议的产品。

所以为了能够与其他语言进行服务通信，我们实现了http + json的协议实现，利用json原生的跨语言的特性。

2. 原理简图

描述：通过Netty暴露http服务端口，接收到http请求，通过HttpDecoder将其解析为HttpRequest，通过JSONDecoder提取service请求信息，生成Request请求对象，从而adapt到binary协议实现，交由request processor处理，返回Response结果，最终通过JSONEncoder编码为JSON格式数据，再通过HttpEncoder生成HttpResponse返回给Http接口调用方。

3. 协议格式

假定：有服务暴露接口ExampleService，服务名称：http://service.huifu.com/ExampleService/exampleService_1.0.0，定义了服务方法public String sayHello(String message)，则HTTP访问协议描述如下：

请求协议：

NameValueDescription

URL

http://{machine-ip}:{http-port}/rpc.json

HTTP服务的访问地址，注意http端口号为pegasus端口号+1000，即：pegasus配置为8888，http端口就是9888

Method

POST

访问方式，推荐使用POST方式

Encoding

UTF-8

HTTP请求编码

Params

_service

http://service.huifu.com/ExampleService/exampleService_1.0.0

访问的服务名称

_method

sayHello

访问的服务接口方法名称

_param

{"message" : "kitty"}

传递到接口方法的参数值，使用json格式，形如：{"param1" : "value1", "param2" : {"f1" : 1, "f2" : "vvv"}}，其中param1，param2为方法的参数名称，param1为string类型，param2为javabean类型，f1和f2为该javabean的属性名。

如：调用方法为sayHello(String message)，则对应json为{"message":"kitty"}。如果调用方法为：sayHello(RequestDTO userDTO)，RequestDTO中有一个属性为name，则对应的json为{"userDTO":{"name":"kitty"}}。

响应协议：

NameValueDescription

格式

{"type" : "xxx", "result" : "xxx", "error" : "xxx"}

HTTP服务接口的响应内容为JSON格式

type

"service" | "service-exception" | "exception"

"service"：业务处理正常返回

"service-exception"：业务处理抛出异常

"exception"：框架处理抛出异常

result

type = "service"时，服务方法的返回值，为JSON格式

若方法返回值为简单类型：

"result" : "hello world"

若为复杂类型:

"result" : "{"f1" : "v1", "f2" : "v2"}"

error

type = "service-exception" | "exception"时，返回的错误信息，为JSON格式

形如{"type" : "com.huifu.xx.BizException", "message" : "order_no is not supported"}

4. 注意事项

关于服务方法参数名

默认情况下，pegasus通过asm读取服务实现类的方法签名信息，获取方法的参数名，但因重构或其他原因，该方法的参数名有可能被修改，从而导致原有的http接口使用方无法正常调用;

所以推荐在有可能提供http访问的服务方法上通过@Param注解定义参数名，这样就可以防止参数名被修改的情况，如void sayHello(@Param("message") String message)，此时该方法就可以安全地重构为void sayHello(@Param("message") String msg)，而不影响原有调用方;

注意：在使用的过程中发现，通过javassist获取参数名，如果使用javac编译器编译的class文件(maven默认使用)，可能会出现无法读取参数名或读取错误; 我们遇到的几个问题case改用eclipse的ecj编译器后都可以fix，但我们无法去测试覆盖所有的代码case，因此若方法涉及到http调用时，请使用@Param的方式显式提供参数名；

btw: maven使用ecj作为编译器的详细配置如下 (1.0.2中已经使用asm替换javassist，该问题已FIXED)

关于服务传输对象(DTO)的定义

由于使用json格式传递方法参数值，就牵扯到json ==> javabean的转换过程，而这个过程要求能明确地知道所有java对象及其属性的类型，所以在创建服务协议DTO对象时，如果这个对象牵扯到http方式的调用，那么就需要明确定义其类型，比如集合类型或数组，必须有明确的元素类型信息，所以Map, List, Set, Object[]都是无法转换的，必须是Map, List, Set, Order[]等有明确的元素类型声明的集合类和数组，即混合类型的集合http方式不支持;

由于json对象无法表示对象引用，所以在定义DTO时，应避免引用的方式，比如parent下定义了list，child中又定义一个parent引用刚才的parent对象，这种方式不允许。

由于json对象的key一定是string类型，所以对于DTO中的Map，只能是Map, Map, Map, Map，Map这样的Map类型，而Map这种类型则无法通过http接口调用，因为json无法表示这样的key。json转map：{"k1", "v1"} => map {"k1", "v1"}。

对于有Map这种类型的dto，如果又需要通过http方式访问，那么请重构该map类型为List方式，比如List, MapBean中有JavaBean的key和JavaBean类型的value属性，即通过List的方式实现Map，此时可以通过json表示，即[{"key1" : {xxx}, "value1" : {xxx}}, {"key2" : {xxx}, "value2" : {xxx}}]。

关于客户端调用

可以按照正常的http方式访问服务接口，由于目前各语言还没有自己封装的客户端，所以集群方面只能通过前端架设软负载的方式实现，后期考虑各语言封装自己的客户端，内部维护到各服务提供者的http长连接，并定期地通过服务注册中心的http接口更新服务提供者列表信息，搭配定期心跳探测移除不可用的连接，以便最终摒弃软负载。

通过http方式访问服务接口时，需要在客户端设置http请求的超时时间，以便在超过设定的超时时间后，客户端会立即抛出超时异常，并中断这次请求，否则会一直等待服务端返回，一旦服务端业务逻辑处理僵死，将无法返回http响应，并一直维持该http连接，造成资源无法释放;