域名管理接口

域名管理相关的 API 接口。

获取域名列表

获取系统中的域名列表，支持分页和搜索。

请求

GET /api/domain/list?page=1&pageSize=20&keyword=example
Authorization: Bearer {token}

查询参数：

参数	类型	必填	说明
page	int	❌	页码，默认 1
pageSize	int	❌	每页数量，默认 20
keyword	string	❌	搜索关键词
status	string	❌	状态筛选：enabled/disabled

响应

成功响应（200）：

{
  "code": 200,
  "data": {
    "list": [
      {
        "id": 1,
        "name": "example.local",
        "description": "示例域名",
        "status": "enabled",
        "record_count": 10,
        "created_at": "2025-01-15T10:30:00Z",
        "updated_at": "2025-01-15T10:30:00Z"
      }
    ],
    "total": 100,
    "page": 1,
    "pageSize": 20
  }
}

获取域名详情

获取单个域名的详细信息。

请求

GET /api/domain/:id
Authorization: Bearer {token}

路径参数：

参数	类型	必填	说明
id	int	✅	域名 ID

响应

成功响应（200）：

{
  "code": 200,
  "data": {
    "id": 1,
    "name": "example.local",
    "description": "示例域名",
    "status": "enabled",
    "record_count": 10,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

创建域名

创建新的域名。

请求

POST /api/domain/create
Authorization: Bearer {token}
Content-Type: application/json

请求体：

{
  "name": "newdomain.local",
  "description": "新域名描述",
  "status": "enabled"
}

参数说明：

参数	类型	必填	说明
name	string	✅	域名名称
description	string	❌	域名描述
status	string	❌	状态，默认 enabled

响应

成功响应（200）：

{
  "code": 200,
  "message": "创建成功",
  "data": {
    "id": 2,
    "name": "newdomain.local",
    "description": "新域名描述",
    "status": "enabled",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

错误响应（400）：

{
  "code": 400,
  "message": "域名已存在"
}

更新域名

更新域名信息。

请求

PUT /api/domain/update/:id
Authorization: Bearer {token}
Content-Type: application/json

路径参数：

参数	类型	必填	说明
id	int	✅	域名 ID

请求体：

{
  "name": "updated.local",
  "description": "更新后的描述",
  "status": "enabled"
}

响应

成功响应（200）：

{
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": 1,
    "name": "updated.local",
    "description": "更新后的描述",
    "status": "enabled",
    "updated_at": "2025-01-15T11:00:00Z"
  }
}

删除域名

删除域名及其所有解析记录。

请求

DELETE /api/domain/delete/:id
Authorization: Bearer {token}

路径参数：

参数	类型	必填	说明
id	int	✅	域名 ID

响应

成功响应（200）：

{
  "code": 200,
  "message": "删除成功"
}

错误响应（403）：

{
  "code": 403,
  "message": "域名下存在解析记录，无法删除"
}

批量导入域名

通过 CSV 文件批量导入域名。

请求

POST /api/domain/import
Authorization: Bearer {token}
Content-Type: multipart/form-data

请求体：

参数	类型	必填	说明
file	file	✅	CSV 文件

CSV 格式：

name,description,status
example1.local,描述1,enabled
example2.local,描述2,enabled

响应

成功响应（200）：

{
  "code": 200,
  "message": "导入成功",
  "data": {
    "total": 10,
    "success": 10,
    "failed": 0
  }
}

导出域名

导出域名列表为 CSV 文件。

请求

GET /api/domain/export?format=csv
Authorization: Bearer {token}

查询参数：

参数	类型	必填	说明
format	string	❌	格式：csv/json，默认 csv
ids	string	❌	指定域名 ID，逗号分隔

响应

成功响应（200）：

文件下载响应，Content-Type 为 text/csv 或 application/json。

批量操作

批量启用/禁用/删除域名。

请求

POST /api/domain/batch
Authorization: Bearer {token}
Content-Type: application/json

请求体：

{
  "action": "enable",
  "ids": [1, 2, 3]
}

参数说明：

参数	类型	必填	说明
action	string	✅	操作：enable/disable/delete
ids	array	✅	域名 ID 列表

响应

成功响应（200）：

{
  "code": 200,
  "message": "批量操作成功",
  "data": {
    "total": 3,
    "success": 3,
    "failed": 0
  }
}

使用示例

cURL 示例

# 设置 Token
TOKEN="your_jwt_token"

# 获取域名列表
curl -s "http://localhost:8085/api/domain/list?page=1&pageSize=10" \
  -H "Authorization: Bearer $TOKEN" | jq

# 创建域名
curl -s -X POST "http://localhost:8085/api/domain/create" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"test.local","description":"测试域名"}' | jq

# 更新域名
curl -s -X PUT "http://localhost:8085/api/domain/update/1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description":"更新后的描述"}' | jq

# 删除域名
curl -s -X DELETE "http://localhost:8085/api/domain/delete/1" \
  -H "Authorization: Bearer $TOKEN" | jq

Python 示例

import requests

class DNSGoDomainAPI:
    def __init__(self, base_url, token):
        self.base_url = base_url
        self.headers = {'Authorization': f'Bearer {token}'}
    
    def list_domains(self, page=1, page_size=20, keyword=None):
        params = {'page': page, 'pageSize': page_size}
        if keyword:
            params['keyword'] = keyword
        
        response = requests.get(
            f'{self.base_url}/api/domain/list',
            headers=self.headers,
            params=params
        )
        return response.json()
    
    def get_domain(self, domain_id):
        response = requests.get(
            f'{self.base_url}/api/domain/{domain_id}',
            headers=self.headers
        )
        return response.json()
    
    def create_domain(self, name, description='', status='enabled'):
        data = {
            'name': name,
            'description': description,
            'status': status
        }
        response = requests.post(
            f'{self.base_url}/api/domain/create',
            headers={**self.headers, 'Content-Type': 'application/json'},
            json=data
        )
        return response.json()
    
    def update_domain(self, domain_id, **kwargs):
        response = requests.put(
            f'{self.base_url}/api/domain/update/{domain_id}',
            headers={**self.headers, 'Content-Type': 'application/json'},
            json=kwargs
        )
        return response.json()
    
    def delete_domain(self, domain_id):
        response = requests.delete(
            f'{self.base_url}/api/domain/delete/{domain_id}',
            headers=self.headers
        )
        return response.json()

# 使用示例
api = DNSGoDomainAPI('http://localhost:8085', 'your_token')

# 列出域名
domains = api.list_domains(keyword='example')
print(domains)

# 创建域名
result = api.create_domain('newdomain.local', '新域名')
print(result)

相关文档

• 域名管理 - 了解域名管理功能
• 解析记录接口 - 管理域名下的解析记录