# dwarfeng-dht

**Repository Path**: dwarfeng/dwarfeng-dht

## Basic Information

- **Project Name**: dwarfeng-dht
- **Description**: DHT 高速数据传输协议支持
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-13
- **Last Updated**: 2026-06-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# dwarfeng-dht

DHT 高速数据传输协议支持。

Data High-speed Transmission for DwArFeng

该项目提供 DHT（Data High-speed Transmission）高速数据传输二进制协议的编解码能力，将带通道、时间和值的数据编码为紧凑的二进制帧，
并支持从二进制帧还原数据，项目基于 `subgrade` 构建。

---

## 特性

1. Subgrade 架构支持。
2. 标准数据结构：`Data`、`GeneralData`（毫秒时间基线 + 毫秒内纳秒偏移）。
3. 面向高速传输场景的 DHT 二进制帧编解码：9 字节协议头、4 字节子包头、大端序字段布局。
4. 通道编解码器映射：通过 `DhtConfig` 维护通道 ID 与 `ValueCodec` 的绑定关系。
5. 内置基础值编解码器：支持字节、短整型、整型、长整型、浮点型、双精度浮点型、布尔、字符串、字符、日期和字节数组。
6. 高速数据分组编码：按通道 ID 与毫秒时间戳聚合数据，同一帧内承载多个纳秒偏移子包。
7. 数据解码还原：从 DHT 帧中还原通道、发生时间、毫秒内纳秒偏移和值。
8. 支持通过 `DhtQosService` 在单处理器和多处理器场景中统一访问 DHT 编解码能力。
9. 支持 Spring XML XSD 命名空间配置。
10. `dwarfeng-dht-api` 模块提供 spring-telqos 集成（`DhtCommand`）。

运行 `dwarfeng-dht-core/src/test` 下的示例以观察核心特性。

| 示例类名                                            | 说明          |
|-------------------------------------------------|-------------|
| com.dwarfeng.dht.node.example.DhtHandlerExample | DHT 编解码流程示例 |

运行 `dwarfeng-dht-api/src/test` 下的示例以观察 API 扩展特性。

| 示例类名                                                   | 说明                                 |
|--------------------------------------------------------|------------------------------------|
| com.dwarfeng.dht.api.integration.example.TelqosExample | Telqos 示例：通过 `dht` 指令操作 DHT QoS 服务 |

## 文档

该项目的文档位于 [docs](./docs) 目录下，包括：

### wiki

wiki 为项目的开发人员为本项目编写的详细文档，包含不同语言的版本，主要入口为：

1. [简介](docs/wiki/zh-CN/Introduction.md) - 镜像的 `README.md`，与本文件内容基本相同。
2. [目录](docs/wiki/zh-CN/Contents.md) - 文档目录。

## 安装说明

1. 下载源码。

   使用 git 进行源码下载。

   ```shell
   git clone git@github.com:DwArFeng/dwarfeng-dht.git
   ```

   对于中国用户，可以使用 gitee 进行高速下载。

   ```shell
   git clone git@gitee.com:dwarfeng/dwarfeng-dht.git
   ```

2. 项目安装。

   进入项目根目录，执行 maven 命令：

   ```shell
   mvn clean source:jar install
   ```

3. 项目引入。

   在项目的 `pom.xml` 中添加如下依赖：

   `dwarfeng-dht-core` 提供核心 DTO、协议工具、值编解码器、Handler 实现和 Spring XSD 支持，为大多数场景的必选依赖：

   ```xml
   <dependency>
       <groupId>com.dwarfeng</groupId>
       <artifactId>dwarfeng-dht-core</artifactId>
       <version>${dwarfeng-dht.version}</version>
   </dependency>
   ```

   如需使用 spring-telqos 命令行集成，可额外引入 `dwarfeng-dht-api`：

   ```xml
   <dependency>
       <groupId>com.dwarfeng</groupId>
       <artifactId>dwarfeng-dht-api</artifactId>
       <version>${dwarfeng-dht.version}</version>
   </dependency>
   ```

4. enjoy it.

## 如何使用

1. 运行 `dwarfeng-dht-core/src/test` 下的示例以观察核心编解码特性。
2. 运行 `dwarfeng-dht-api/src/test` 下的示例以观察 spring-telqos 运维指令特性。
3. 观察项目结构，将其中的配置运用到其它的 subgrade 项目中。

### 单实例模式

使用 xml 或者配置类生成一个 `DhtHandlerImpl` 实例，并按需生成 `DhtQosHandlerImpl` 与 `DhtQosServiceImpl`。
在项目的 `bean-definition.xml` 中追加配置，示例如下:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!-- 以下注释用于抑制 idea 中 .md 的警告，实际并无错误，在使用时可以连同本注释一起删除。 -->
<!--suppress SpringBeanConstructorArgInspection, SpringXmlModelInspection -->
<beans
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns="http://www.springframework.org/schema/beans"
        xsi:schemaLocation="http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans.xsd"
>

    <!-- 内置 ValueCodec。 -->
    <bean name="integerValueCodec" class="com.dwarfeng.dht.impl.handler.vc.IntegerValueCodec"/>
    <bean name="stringValueCodec" class="com.dwarfeng.dht.impl.handler.vc.StringValueCodec"/>
    <bean name="byteArrayValueCodec" class="com.dwarfeng.dht.impl.handler.vc.ByteArrayValueCodec"/>

    <!-- DHT 配置。 -->
    <bean name="configBuilder" class="com.dwarfeng.dht.stack.struct.DhtConfig.Builder">
        <property name="valueCodecMap">
            <map>
                <entry key="0" value-ref="integerValueCodec"/>
                <entry key="1" value-ref="stringValueCodec"/>
                <entry key="2" value-ref="byteArrayValueCodec"/>
            </map>
        </property>
    </bean>
    <bean name="dhtConfig" factory-bean="configBuilder" factory-method="build"/>

    <!-- DHT 协议处理器。 -->
    <bean name="dhtHandler" class="com.dwarfeng.dht.impl.handler.DhtHandlerImpl">
        <constructor-arg name="config" ref="dhtConfig"/>
    </bean>
</beans>
```

### 多实例模式

使用 xml 或者配置类生成多个 `DhtHandlerImpl` 实例，并通过 `DhtQosHandlerImpl` 统一路由。
在项目的 `bean-definition.xml` 中追加配置，示例如下:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!-- 以下注释用于抑制 idea 中 .md 的警告，实际并无错误，在使用时可以连同本注释一起删除。 -->
<!--suppress SpringBeanConstructorArgInspection, SpringXmlModelInspection -->
<beans
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns="http://www.springframework.org/schema/beans"
        xsi:schemaLocation="http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans.xsd"
>

    <!-- 内置 ValueCodec。 -->
    <bean name="integerValueCodec" class="com.dwarfeng.dht.impl.handler.vc.IntegerValueCodec"/>
    <bean name="stringValueCodec" class="com.dwarfeng.dht.impl.handler.vc.StringValueCodec"/>
    <bean name="byteArrayValueCodec" class="com.dwarfeng.dht.impl.handler.vc.ByteArrayValueCodec"/>

    <!-- DHT 配置。 -->
    <bean name="configBuilder1" class="com.dwarfeng.dht.stack.struct.DhtConfig.Builder">
        <property name="valueCodecMap">
            <map>
                <entry key="0" value-ref="integerValueCodec"/>
                <entry key="1" value-ref="stringValueCodec"/>
                <entry key="2" value-ref="byteArrayValueCodec"/>
            </map>
        </property>
    </bean>
    <bean name="dhtConfig1" factory-bean="configBuilder1" factory-method="build"/>
    <bean name="configBuilder2" class="com.dwarfeng.dht.stack.struct.DhtConfig.Builder">
        <property name="valueCodecMap">
            <map>
                <entry key="3" value-ref="integerValueCodec"/>
                <entry key="4" value-ref="stringValueCodec"/>
                <entry key="5" value-ref="byteArrayValueCodec"/>
            </map>
        </property>
    </bean>
    <bean name="dhtConfig2" factory-bean="configBuilder2" factory-method="build"/>

    <!-- DHT 协议处理器。 -->
    <bean name="dhtHandler1" class="com.dwarfeng.dht.impl.handler.DhtHandlerImpl">
        <constructor-arg name="config" ref="dhtConfig1"/>
    </bean>
    <bean name="dhtHandler2" class="com.dwarfeng.dht.impl.handler.DhtHandlerImpl">
        <constructor-arg name="config" ref="dhtConfig2"/>
    </bean>

    <!-- QoS 处理器：通过构造器注入多个 Handler Bean 组成的 Map。 -->
    <bean name="dhtQosHandler" class="com.dwarfeng.dht.impl.handler.DhtQosHandlerImpl">
        <constructor-arg>
            <map>
                <entry key="dhtHandler1" value-ref="dhtHandler1"/>
                <entry key="dhtHandler2" value-ref="dhtHandler2"/>
            </map>
        </constructor-arg>
    </bean>

    <!-- 服务异常映射器。 -->
    <bean name="mapServiceExceptionMapper" class="com.dwarfeng.subgrade.impl.exception.MapServiceExceptionMapper">
        <constructor-arg index="0">
            <map/>
        </constructor-arg>
        <constructor-arg index="1" value="#{T(com.dwarfeng.subgrade.sdk.exception.ServiceExceptionCodes).UNDEFINED}"/>
    </bean>

    <!-- QoS 服务。 -->
    <bean name="dhtQosService" class="com.dwarfeng.dht.impl.service.DhtQosServiceImpl">
        <constructor-arg index="0" ref="dhtQosHandler"/>
        <constructor-arg index="1" ref="mapServiceExceptionMapper"/>
    </bean>
</beans>
```

### XSD 配置

可以使用 `dht` 命名空间装配 `DhtConfig`、`DhtHandler`、`DhtQosHandler` 与 `DhtQosService`。
在项目的 `application-context-dht.xml` 中追加配置，示例如下:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!-- 以下注释用于抑制 idea 中 .md 的警告，实际并无错误，在使用时可以连同本注释一起删除。 -->
<!--suppress SpringBeanConstructorArgInspection, SpringXmlModelInspection -->
<beans
        xmlns:dht="http://dwarfeng.com/schema/dwarfeng-dht"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns="http://www.springframework.org/schema/beans"
        xsi:schemaLocation="http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans.xsd
        http://dwarfeng.com/schema/dwarfeng-dht
        http://dwarfeng.com/schema/dwarfeng-dht/dwarfeng-dht.xsd"
>

    <!-- 内置 ValueCodec。 -->
    <bean name="integerValueCodec" class="com.dwarfeng.dht.impl.handler.vc.IntegerValueCodec"/>
    <bean name="stringValueCodec" class="com.dwarfeng.dht.impl.handler.vc.StringValueCodec"/>
    <bean name="byteArrayValueCodec" class="com.dwarfeng.dht.impl.handler.vc.ByteArrayValueCodec"/>

    <dht:config config-name="dhtConfig">
        <dht:channel-value-codec channel-id="0" value-codec-ref="integerValueCodec"/>
        <dht:channel-value-codec channel-id="1" value-codec-ref="stringValueCodec"/>
        <dht:channel-value-codec channel-id="2" value-codec-ref="byteArrayValueCodec"/>
    </dht:config>
    <dht:handler/>
    <dht:qos/>
</beans>
```

`config` 元素可通过 `config-name` 指定 `DhtConfig` 的 bean 名称，
并通过 `channel-value-codec` 子元素配置通道 ID 与 `ValueCodec` 的映射。

`channel-value-codec` 元素可通过 `channel-id`、`value-codec-ref`、`value-codec-class`
指定通道 ID、已有值编解码器引用或值编解码器实现类。

`handler` 元素可通过 `handler-name`、`config-ref` 指定处理器 bean 名称和配置引用。

`qos` 元素可通过 `qos-handler-name`、`qos-service-name`、`sem-ref`
指定 QoS 处理器 bean 名称、QoS 服务 bean 名称和 `ServiceExceptionMapper` 引用。

### 任意数量的实例模式

自行设计 `DhtHandler` 的工厂类，调用相关工厂方法生成 `DhtHandlerImpl` 实例。