# dns-java-springboot-starter（dnsjava改）

**Repository Path**: conmi/dns-java-spring-boot-starter

## Basic Information

- **Project Name**: dns-java-springboot-starter（dnsjava改）
- **Description**: 基于dnsjava实现的springboot starter
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-01
- **Last Updated**: 2026-09-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# dns-java-springboot-starter

[English](README_EN.md) | **中文（默认）**

> **代码移植**：本项目的 Spring Boot Starter 封装代码由 AI 模型 **deepseek-v4-flash** 移植编写。

## 简介

DNS over Java（dnsjava，`org.xbill.DNS`）Spring Boot Starter — 基于 Spring Boot 的自动配置组件。

**源码来源**：本 Starter 内嵌的 dnsjava 源码来自官方仓库 [`https://github.com/dnsjava/dnsjava.git`](https://github.com/dnsjava/dnsjava.git)（3.6.x），保留 `org.xbill.DNS` 包名，按服务端场景裁剪后内嵌维护。

**环境要求**：JDK 17+（内嵌 dnsjava 3.6.x 源码子集经验证兼容 JDK 17/21/25），Spring Boot 3.4.x。

与官方 `dnsjava:dnsjava` 的区别：本 Starter **内嵌 dnsjava 源码**（保留 `org.xbill.DNS` 包名），
不通过 Maven 依赖引用外部 dnsjava 包，独立可维护，并针对 Spring Boot 服务端场景做了裁剪与优化：

- 剔除平台无关代码：`tools/`（CLI 工具）、`spi/` + `sun/net/spi/nameservice`（JVM 解析器集成）、`dnssec/`、`lookup/`（响应式会话 API）、`android/`（Android 桩）
- 剔除 JNA 平台依赖：Windows `IPHlpAPI` / `WindowsResolverConfigProvider`、Android `AndroidResolverConfigProvider`，仅保留服务端通用的 DNS 配置探测（resolv.conf / JNDI / JVM / 属性）
- 外部依赖最小化：仅 `slf4j-api` + `lombok`（编译期）+ Spring Boot 自动配置

自动装配内容：

- `Resolver` Bean（`SimpleResolver` / `ExtendedResolver` / `DohResolver` 三种后端，按配置优先级二选一）
- `Cache` Bean（共享 DNS 缓存，可选）
- `DnsLookupOperations` 门面类（类型化 A/AAAA/TXT/PTR 查询 + 流式 builder）

## 快速开始

### 安装

```bash
# 构建并安装到本地 Maven 仓库
mvn clean install
```

或直接运行项目根目录的 `install.sh`（Linux/macOS）或 `install.bat`（Windows）。

### Maven 引入

```xml
<dependency>
    <groupId>io.gitee.conmi</groupId>
    <artifactId>dns-java-springboot-starter</artifactId>
    <version>0.1.0</version>
</dependency>
```

### 基础配置

在 `application.yml` 中配置：

```yaml
dnsjava:
  enabled: true                    # 是否启用（默认 true）
  resolver:
    enabled: true                  # 是否创建 Resolver Bean（默认 true）
    mode: SYSTEM                   # SYSTEM=系统探测 | SERVERS=指定服务器列表
    servers:                       # mode=SERVERS 时必填，host:port 或 host（默认 53）
      - 8.8.8.8:53
      - 114.114.114.114:53
    timeout: 10s                   # 查询超时（默认 10s）
    tcp: false                     # 是否强制走 TCP
    ignore-truncation: false
    search-path: []                # 搜索路径，如 corp.example.
    ndots: 0                       # 0=不覆盖 dnsjava 全局值
    edns:
      version: 0                   # 0=启用 EDNS0，-1=禁用
      payload-size: 0              # 0=使用 dnsjava 默认 1280
      flags: 0
    tsig:
      enabled: false
      algorithm: hmac-sha256.
      name:
      secret:                      # base64 编码
  cache:
    enabled: true                  # 是否创建共享 Cache Bean（默认 true）
    max-entries: 0                 # 0=使用 dnsjava 默认 50000
    max-cache-seconds: 0
    max-n-cache-seconds: 0
  doh:
    enabled: false                 # 启用后 DoH 解析器替换 Resolver Bean
    uri-template: https://dns.google/dns-query
    max-concurrent-requests: 100
    idle-connection-timeout: 0s
```

### 在项目中使用

```java
import io.gitee.conmi.dnsjava.spring.boot.dns.DnsLookupOperations;
import org.springframework.stereotype.Service;

@Service
public class MyBusinessService {

    private final DnsLookupOperations dns;

    public MyBusinessService(DnsLookupOperations dns) {
        this.dns = dns;
    }

    public void resolve(String host) {
        dns.lookupA("example.com").forEach(addr -> log.info("A: {}", addr));
        dns.lookupTXT("example.com").forEach(text -> log.info("TXT: {}", text));
        dns.lookupPTR(InetAddress.getByName("1.1.1.1"))
                .ifPresent(name -> log.info("PTR: {}", name));
        // 任意类型
        dns.lookup(host, Type.MX).run().forEach(rec -> log.info("MX: {}", rec));
    }
}
```

### 直接注入底层 Bean

```java
@Autowired
private Resolver resolver;          // SimpleResolver / ExtendedResolver / DohResolver

@Autowired(required = false)
private Cache cache;                // dnsjava.cache.enabled=false 时为 null
```

## 配置项说明

| 配置项                              | 类型     | 默认值 | 说明                                  |
| ----------------------------------- | -------- | ------ | ------------------------------------- |
| `dnsjava.enabled`                   | Boolean  | `true` | 是否启用整个自动配置                  |
| `dnsjava.resolver.enabled`          | Boolean  | `true` | 是否创建 Resolver Bean                |
| `dnsjava.resolver.mode`             | Enum     | `SYSTEM` | 后端选择：SYSTEM / SERVERS           |
| `dnsjava.resolver.servers`          | List     | `[]`   | SERVERS 模式下的 DNS 服务器列表       |
| `dnsjava.resolver.timeout`          | Duration | `10s`  | 查询超时                              |
| `dnsjava.resolver.search-path`      | List     | `[]`   | 搜索路径                              |
| `dnsjava.cache.enabled`             | Boolean  | `true` | 是否创建共享 Cache Bean               |
| `dnsjava.doh.enabled`               | Boolean  | `false` | 是否使用 DoH 解析器                  |
| `dnsjava.doh.uri-template`          | String   | `null` | DoH URI 模板（启用时必填）            |

## 禁用 Starter

```yaml
dnsjava:
  enabled: false
```

## 目录结构

```
dns-java-springboot-starter/
├── pom.xml
├── README.md
├── install.sh / install.bat
├── src/main/java/
│   ├── org/xbill/DNS/...         # 内嵌 dnsjava 源码（保留原包名）
│   └── dnsjava/spring/boot/
│       ├── autoconfigure/
│       │   ├── DnsjavaAutoConfiguration.java
│       │   └── DnsjavaProperties.java
│       └── dns/
│           ├── DnsLookupOperations.java
│           └── DnsLookupResponse.java
├── src/main/resources/META-INF/spring/
│   └── org.springframework.boot.autoconfigure.AutoConfiguration.imports
└── src/test/java/...              # 35 个测试（12 门面 + 23 自动配置）
```

## 许可证

本项目为**双许可证**结构：

- **自有代码**（`io.gitee.conmi.dnsjava.spring.boot` 包、测试、构建脚本与文档）：[Apache License 2.0](LICENSE)
- **内嵌 dnsjava 源码**（`org.xbill.DNS` 包及其子包）：保留原 [BSD 3-Clause](NOTICE) 许可证与版权声明

BSD-3-Clause 与 Apache-2.0 兼容，两者在本仓库中共存。第三方组件声明详见 [NOTICE](NOTICE)。