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连接,造成资源无法释放;