Skip to content

Commit

Permalink
docs: add http-dubbo docs (#11322)
Browse files Browse the repository at this point in the history 
Co-authored-by: Traky Deng <[email protected]>
  • Loading branch information
@ShenFeng312 @kayx23
ShenFeng312 and kayx23 committed Jul 3, 2024
1 parent 6d2de7e commit 4dbecfd
Show file tree
Hide file tree
Showing 4 changed files with 256 additions and 2 deletions.
3 changes: 2 additions & 1 deletion docs/en/latest/config.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -217,7 +217,8 @@
"items": [
"plugins/dubbo-proxy",
"plugins/mqtt-proxy",
"plugins/kafka-proxy"
"plugins/kafka-proxy",
"plugins/http-dubbo"
]
}
]
Expand Down
128 changes: 128 additions & 0 deletions docs/en/latest/plugins/http-dubbo.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
---
title: http-dubbo
keywords:
- Apache APISIX
- API Gateway
- Plugin
- http-dubbo
- http to dubbo
- transcode
description: This document contains information about the Apache APISIX http-dubbo Plugin.
---

<!--
#
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements. See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
-->

## 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

| Name | Type | Required | Default | Valid values | Description |
|--------------------------|---------|----------|---------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| service_name | string | True | | | Dubbo service name |
| service_version | string | False | 0.0.0 | | Dubbo service version |
| method | string | True | | | Dubbo service method name |
| params_type_desc | string | True | | | Description of the Dubbo service method signature |
| serialization_header_key | string | False | | | If `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. |
| serialized | boolean | False | false | [true, false] | Same as `serialization_header_key`. Priority is lower than `serialization_header_key`. |
| connect_timeout | number | False | 6000 | | Upstream tcp connect timeout |
| read_timeout | number | False | 6000 | | Upstream tcp read_timeout |
| send_timeout | number | False | 6000 | | Upstream 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:

```bash
admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
```

:::

```shell
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:

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

## How to Get `params_type_desc`

```java
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](https://github.com/alibaba/fastjson/wiki/SerializerFeature_cn) 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.
3 changes: 2 additions & 1 deletion docs/zh/latest/config.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -201,7 +201,8 @@
"label": "其它协议",
"items": [
"plugins/dubbo-proxy",
"plugins/mqtt-proxy"
"plugins/mqtt-proxy",
"plugins/http-dubbo"
]
}
]
Expand Down
124 changes: 124 additions & 0 deletions docs/zh/latest/plugins/http-dubbo.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
---
title: http-dubbo
keywords:
- Apache APISIX
- API 网关
- Plugin
- http-dubbo
- http to dubbo
description: 本文介绍了关于 Apache APISIX `http-dubbo` 插件的基本信息及使用方法。
---

<!--
#
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements. See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
-->

## 描述

`http-dubbo` 插件可以将 http 请求 encode 为 dubbo 协议转发给上游服务（注意：在 dubbo2.x 时上游服务的序列化类型必须是 fastjson)

## 属性

| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
| ------------------------ | ------- |-----| ------ | ----------- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| service_name | string | 是 | | | dubbo 服务名 |
| service_version | string | 否 | 0.0.0 | | dubbo 服务版本 默认 0.0.0 |
| method | string | 是 | | | dubbo 服务方法名 |
| params_type_desc | string | 否 | | | dubbo 服务方法签名描述，入参如果是 void 可不填写 |
| serialization_header_key | string | 否 | | | 插件会读取该请求头判断 body 是否已经按照 dubbo 协议序列化完毕。如果该请求头的值为 true 则插件不会更改 body 内容，直接把他当作 dubbo 请求参数。如果为 false 则要求开发者按照 dubbo 泛化调用的格式传递参数，由插件进行序列化。注意：由于 lua 和 java 的插件序列化精度不同，可能会导致参数精度不同。 |
| serialized | boolean | 否 | false | [true, false] | 和`serialization_header_key`一样。优先级低于`serialization_header_key` |
| connect_timeout | number | 否 | 6000 | | 上游服务 tcp connect_timeout |
| read_timeout | number | 否 | 6000 | | 上游服务 tcp read_timeout |
| send_timeout | number | 否 | 6000 | | 上游服务 tcp send_timeout |

## 启用插件

以下示例展示了如何在指定路由中启用 `http-dubbo` 插件：

:::note

您可以这样从 `config.yaml` 中获取 `admin_key` 并存入环境变量：

```bash
admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
```

:::

```shell
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:1980": 1
}
}
}'
```

## 测试插件

通过上述命令启用插件后，可以使用如下命令测试插件是否启用成功：

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

## 如何获取 params_type_desc

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

//方法重载情况下需要找自己需要暴露的方法 ReflectUtils 为 dubbo 实现
```

## 如何按照 dubbo 协议使用 json 进行序列化

为了防止精度丢失。我们推荐使用序列化好的 body 进行请求。
dubbo 的 fastjson 序列化规则如下：

- 每个参数之间使用 toJSONString 转化为 JSON 字符串

- 每个参数之间使用换行符 `\n` 分隔

部分语言和库在字符串或数字调用 toJSONString 后结果是不变的这可能需要你手动处理一些特殊情况例如：

- 字符串 `abc"` 需要被 encode 为 `"abc\""`

- 字符串 `123` 需要被 encode 为 `"123"`

抽象类，父类或者泛型作为入参签名，入参需要具体类型时。序列化需要写入具体的类型信息具体参考 [WriteClassName](https://github.com/alibaba/fastjson/wiki/SerializerFeature_cn)

## 删除插件

当你需要禁用 `http-dubbo` 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务。

0 comments on commit 4dbecfd

Please sign in to comment.