Skip to main content
Version: Next

http-dubbo

Description#

The http-dubbo plugin can transcode between http and Dubbo (Note: in Dubbo 2.x, the serialization type of the upstream service must be fastjson).

Attributes#

NameTypeRequiredDefaultValid valuesDescription
service_namestringTrueDubbo service name
service_versionstringFalse0.0.0Dubbo service version
methodstringTrueDubbo service method name
params_type_descstringTrueDescription of the Dubbo service method signature
serialization_header_keystringFalseIf serialization_header_key is set, the plugin will read this request header to determine if the body has already been serialized according to the Dubbo protocol. If the value of this request header is true, the plugin will not modify the body content and will directly consider it as Dubbo request parameters. If it is false, the developer is required to pass parameters in the format of Dubbo's generic invocation, and the plugin will handle serialization. Note: Due to differences in precision between Lua and Java, serialization by the plugin may lead to parameter precision discrepancies.
serializedbooleanFalsefalse[true, false]Same as serialization_header_key. Priority is lower than serialization_header_key.
connect_timeoutnumberFalse6000Upstream tcp connect timeout
read_timeoutnumberFalse6000Upstream tcp read_timeout
send_timeoutnumberFalse6000Upstream tcp send_timeout

Enable Plugin#

The example below enables the http-dubbo Plugin on the specified Route:

note

You can fetch the admin_key from config.yaml and save to an environment variable with the following command:

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
curl -i http://127.0.0.1:9180/apisix/admin/routes/1  \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
"uri": "/TestService/testMethod",
"plugins": {
"http-dubbo": {
"method": "testMethod",
"params_type_desc": "Ljava/lang/Long;Ljava/lang/Integer;",
"serialized": true,
"service_name": "com.xxx.xxx.TestService",
"service_version": "0.0.0"
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:20880": 1
}
}
}'

Example usage#

Once you have configured the Plugin as shown above, you can make a request as shown below:

curl --location 'http://127.0.0.1:9080/TestService/testMethod' \
--data '1
2'

How to Get params_type_desc#

Method[] declaredMethods = YourService.class.getDeclaredMethods();
String params_type_desc = ReflectUtils.getDesc(Arrays.stream(declaredMethods).filter(it -> it.getName().equals("yourmethod")).findAny().get().getParameterTypes());

// If there are method overloads, you need to find the method you want to expose.
// ReflectUtils is a Dubbo implementation.

How to Serialize JSON According to Dubbo Protocol#

To prevent loss of precision, we recommend using pre-serialized bodies for requests. The serialization rules for Dubbo's fastjson are as follows:

  • Convert each parameter to a JSON string using toJSONString.
  • Separate each parameter with a newline character \n.

Some languages and libraries may produce unchanged results when calling toJSONString on strings or numbers. In such cases, you may need to manually handle some special cases. For example:

  • The string abc" needs to be encoded as "abc\"".
  • The string 123 needs to be encoded as "123".

Abstract class, parent class, or generic type as input parameter signature, when the input parameter requires a specific type. Serialization requires writing specific type information. Refer to WriteClassName for more details.

Delete Plugin#

To remove the http-dubbo Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.