Initiate HTTP requests to access Dubbo services by configuring HTTP-to-Dubbo conversion - Microservices Engine

In distributed microservice scenarios, backend services call each other based on the remote procedure call (RPC) framework. Dubbo is a common RPC framework. For scenarios where a Dubbo service is exposed by calling a RESTful API operation, cloud-native gateways provide the HTTP-to-Dubbo conversion feature. This topic describes how to initiate HTTP requests to access Dubbo services by configuring HTTP-to-Dubbo conversion.

Note

Only Java applications that are developed based on Dubbo are supported.

Procedure

Log on to the MSE console.
In the left-side navigation pane, choose Cloud-native Gateway > Gateways. In the top navigation bar, select a region.
On the Gateways page, find your gateway and click Route Settings in the Actions column. In the upper-right corner of the page that appears, click Previous Version.

In the left-side navigation pane, choose Routes > Route Settings. In the upper-left corner of the page that appears, click Add Route. In the Add Route panel, configure the parameters.

In the Request Information step, specify Route Name and Domain Name, select Prefix Match as the path matching rule, and then click Next.

In the Destination Service step, select Single Service and select the destination service from the Service drop-down list. Then, specify the protocol conversion parameters that are displayed, and click Save and Release.

Protocol conversion parameters

Parameter	Description
Dubbo Service Name	The full name of the Dubbo service.
Service Version	The version of the Dubbo service. If no version is configured for the backend service, this parameter is set to 0.0.0 by default.
Service Group	The group of the Dubbo service. You can leave the parameter empty if no group is configured for the backend service.
Method Mapping Note The mapping rules of a Dubbo method. You can click +Method Mapping to configure multiple method mapping rules. The Method Mapping parameter contains the following configuration items:
Dubbo Method Name	The full name of the Dubbo method.
HTTP Method	The Method parameter in the HTTP request.
Method Match Path	The match path parameter. You must specify this parameter based on the path that you specified for prefix match. For example, if the prefix match path in the Request Information step is `/dubboDemo`, you need to enter the method match path based on the `/dubboDemo` path, such as `/dubboDemo/hello`.
Header Pass-through Type	Specifies whether to pass through HTTP request headers as implicit parameters to the backend Dubbo service based on the Attachment mechanism. Valid values: Pass-through of All Headers No Pass-through Pass-through of Specific Headers: Separate multiple header keys with commas (,). Example: content-length,content-type.
Parameter Mapping	The parameter mapping rule of the Dubbo method. The parameters of the Dubbo method are extracted from the HTTP request. The extracted parameters are in the `key-value` format. You can click + Parameter Mapping to add multiple parameter mapping rules. Input Parameter Location: the location from which the parameters are extracted in an HTTP request. Valid values: Request Parameter: extracted from the Query parameter in the HTTP request. Request Header: extracted from the HTTP request header. Request Path: extracted from the path in the HTTP request. Request Body: extracted from the body of the HTTP request. Extract Key: the key of the current parameter. Backend Parameter Type: the full type name of the current parameter. The following Java types are supported based on specifications: java.lang.String java.lang.Long java.lang.Double java.lang.Boolean java.util.List java.util.Map Custom types, such as org.apache.dubbo.samples.basic.api.DubboTest Important Parameters of the java.util.List, java.util.Map, or a custom type can be extracted only from request bodies.

Examples

This section provides configuration examples to describe how to initiate HTTP requests to access Dubbo services by using HTTP-to-Dubbo conversion.

Dubbo service interface

The following sample code shows the configuration of an interface of the backend Dubbo service.

package com.alibaba.nacos.example.dubbo.service;
import java.util.List;
import java.util.Map;
public interface DemoService {
    String sayHello(String name);
    String echoList(List<String> input);
    String echoMap(Map<String, String> map);
    String echoPerson(Person p);
}

Person is a custom type. The following code shows the definition of Person.

package com.alibaba.nacos.example.dubbo.service;
import java.io.Serializable;
public class Person implements Serializable {
    public String name;
    public String second_name;
    public int age;
}

Example 1: Extract the values of backend parameters of the java.lang.String type from request parameters

Parameter	Description
Dubbo Service Name	com.alibaba.nacos.example.dubbo.service.DemoService
Service Version	1.0.0
Method Mapping
Dubbo Method Name	sayHello
HTTP Method	GET
Method Match Path	/dubboDemo/hello
Header Pass-through Type	Pass-through of All Headers
Parameter Mapping	Input Parameter Location: Request Parameter
	Extract Key: param1
	Backend Parameter Type: java.lang.String

Run the following curl command in the terminal to initiate an HTTP request to verify the result:

curl "http://xxx.xxx.xxx/dubboDemo/hello?param1=abcd"

Example 2: Extract the values of backend parameters of the java.lang.String type from request headers

Parameter	Description
Dubbo Service Name	com.alibaba.nacos.example.dubbo.service.DemoService
Service Version	1.0.0
Method Mapping
Dubbo Method Name	sayHello
HTTP Method	GET
Method Match Path	/dubboDemo/hello
Header Pass-through Type	Pass-through of All Headers
Parameter Mapping	Input Parameter Location: Request Header
	Extract Key: param1
	Backend Parameter Type: java.lang.String

Run the following curl command in the terminal to initiate an HTTP request to verify the result:

curl "http://xxx.xxx.xxx/dubboDemo/hello" -H "param1: abcd"

Example 3: Extract the values of backend parameters of the java.lang.String type from request paths

Note

If Input Parameter Location is set to Request Path, you must specify the path in the Method Match Path field.

Parameter	Description
Dubbo Service Name	com.alibaba.nacos.example.dubbo.service.DemoService
Service Version	1.0.0
Method Mapping
Dubbo Method Name	sayHello
HTTP Method	GET
Method Match Path	/dubboDemo/hello/{param1=*}
Header Pass-through Type	Pass-through of All Headers
Parameter Mapping	Input Parameter Location: Request Path
	Extract Key: param1
	Backend Parameter Type: java.lang.String

Run the following curl command in the terminal to initiate an HTTP request to verify the result:

curl "http://xxx.xxx.xxx/dubboDemo/hello/abcd"

Example 4: Extract the values of backend parameters of the java.lang.String type from request bodies

Parameter	Description
Dubbo Service Name	com.alibaba.nacos.example.dubbo.service.DemoService
Service Version	1.0.0
Method Mapping
Dubbo Method Name	sayHello
HTTP Method	POST
Method Match Path	/dubboDemo/hello
Header Pass-through Type	Pass-through of All Headers
Parameter Mapping	Input Parameter Location: Request Body
	Extract Key: param1
	Backend Parameter Type: java.lang.String

Run the following curl command in the terminal to initiate an HTTP request to verify the result:

curl "http://xxx.xxx.xxx/dubboDemo/hello/" -X POST -d '{"param1": "abcd"}'

Example 5: Extract the values of backend parameters of the java.util.List type from request bodies

Important

Parameters of the java.util.List type can be extracted only from request bodies.

Parameter	Description
Dubbo Service Name	com.alibaba.nacos.example.dubbo.service.DemoService
Service Version	1.0.0
Method Mapping
Dubbo Method Name	echoList
HTTP Method	POST
Method Match Path	/dubboDemo/echolist
Header Pass-through Type	Pass-through of All Headers
Parameter Mapping	Input Parameter Location: Request Body
	Extract Key: param1
	Backend Parameter Type: java.util.List

Run the following curl command in the terminal to initiate an HTTP request to verify the result:

curl "http://xxx.xxx.xxx/dubboDemo/echolist/" -X POST -d '{"param1": ["abc", "def", "ghi"]}'

Example 6: Extract the values of backend parameters of the java.util.Map type from request bodies

Important

Parameters of the java.util.Map type can be extracted only from request bodies.

Parameter	Description
Dubbo Service Name	com.alibaba.nacos.example.dubbo.service.DemoService
Service Version	1.0.0
Method Mapping
Dubbo Method Name	echoMap
HTTP Method	POST
Method Match Path	/dubboDemo/echomap
Header Pass-through Type	Pass-through of All Headers
Parameter Mapping	Input Parameter Location: Request Body
	Extract Key: param1
	Backend Parameter Type: java.util.Map

Run the following curl command in the terminal to initiate an HTTP request to verify the result:

curl "http://xxx.xxx.xxx/dubboDemo/echomap/" -X POST -d '{"param1": {"key1": "value1", "key2": "value2", "key3": "value3"}}'

Example 7: Extract the values of backend parameters of a custom type from request bodies

Important

Parameters of a custom type can be extracted only from request bodies.

Parameter	Description
Dubbo Service Name	com.alibaba.nacos.example.dubbo.service.DemoService
Service Version	1.0.0
Method Mapping
Dubbo Method Name	echoPerson
HTTP Method	POST
Method Match Path	/dubboDemo/echoperson
Header Pass-through Type	Pass-through of All Headers
Parameter Mapping	Input Parameter Location: Request Body
	Extract Key: param1
	Backend Parameter Type: com.alibaba.nacos.example.dubbo.service.Person

Run the following curl command in the terminal to initiate an HTTP request to verify the result:

curl "http://xxx.xxx.xxx/dubboDemo/echoperson/" -X POST -d '{"param1": {"name": "Tom", "second_name": "John", "age": 21}}'