DataOps-platform/translate_api_documentation.md

System Translate API 使用说明文档

接口概述

translate接口用于将中文节点名称翻译成符合数据库规范的英文名称，主要用于数据建模和表名/字段名的英文化处理。

接口信息

访问路径

POST /api/system/translate

请求头

Content-Type: application/json

输入参数

请求体参数

参数名	类型	必填	描述	示例
node_name	string	是	需要翻译的中文节点名称	"用户数据表"

请求体示例

{
    "node_name": "用户数据表"
}

输出参数

成功响应

字段名	类型	描述
code	integer	响应状态码，成功时为200
message	string	响应消息，成功时为"翻译成功"
data	object	翻译结果数据对象
data.original	string	原始输入的中文名称
data.translated	string	翻译后的英文名称（主要结果）
data.translated_list	array	翻译结果数组（兼容性字段）

错误响应

字段名	类型	描述
code	integer	错误状态码
message	string	错误描述信息
data	null	错误时数据为空

样例代码

cURL 示例

curl -X POST \
  http://localhost:5000/api/system/translate \
  -H 'Content-Type: application/json' \
  -d '{
    "node_name": "用户数据表"
  }'

JavaScript (Fetch API) 示例

// 发送翻译请求
async function translateNodeName(nodeName) {
    try {
        const response = await fetch('/api/system/translate', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
            },
            body: JSON.stringify({
                node_name: nodeName
            })
        });
        
        const result = await response.json();
        
        if (result.code === 200) {
            console.log('翻译成功:', result.data.translated);
            return result.data.translated;
        } else {
            console.error('翻译失败:', result.message);
            return null;
        }
    } catch (error) {
        console.error('请求失败:', error);
        return null;
    }
}

// 使用示例
translateNodeName('用户数据表').then(translated => {
    if (translated) {
        console.log('英文名称:', translated); // 输出: user_data_table
    }
});

Python 示例

import requests
import json

def translate_node_name(node_name):
    """
    调用翻译API
    
    Args:
        node_name (str): 需要翻译的中文名称
        
    Returns:
        str: 翻译后的英文名称，失败时返回None
    """
    url = 'http://localhost:5000/api/system/translate'
    headers = {
        'Content-Type': 'application/json'
    }
    data = {
        'node_name': node_name
    }
    
    try:
        response = requests.post(url, headers=headers, json=data)
        result = response.json()
        
        if result['code'] == 200:
            print(f"翻译成功: {result['data']['translated']}")
            return result['data']['translated']
        else:
            print(f"翻译失败: {result['message']}")
            return None
    except Exception as e:
        print(f"请求失败: {str(e)}")
        return None

# 使用示例
translated_name = translate_node_name('用户数据表')
if translated_name:
    print(f"英文名称: {translated_name}")  # 输出: user_data_table

Java 示例

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.google.gson.Gson;
import com.google.gson.JsonObject;

public class TranslateAPI {
    
    public static String translateNodeName(String nodeName) {
        try {
            // 构建请求体
            JsonObject requestBody = new JsonObject();
            requestBody.addProperty("node_name", nodeName);
            
            // 创建HTTP请求
            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("http://localhost:5000/api/system/translate"))
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(requestBody.toString()))
                .build();
            
            // 发送请求
            HttpClient client = HttpClient.newHttpClient();
            HttpResponse<String> response = client.send(request, 
                HttpResponse.BodyHandlers.ofString());
            
            // 解析响应
            Gson gson = new Gson();
            JsonObject result = gson.fromJson(response.body(), JsonObject.class);
            
            if (result.get("code").getAsInt() == 200) {
                String translated = result.getAsJsonObject("data")
                    .get("translated").getAsString();
                System.out.println("翻译成功: " + translated);
                return translated;
            } else {
                String message = result.get("message").getAsString();
                System.err.println("翻译失败: " + message);
                return null;
            }
        } catch (Exception e) {
            System.err.println("请求失败: " + e.getMessage());
            return null;
        }
    }
    
    // 使用示例
    public static void main(String[] args) {
        String translated = translateNodeName("用户数据表");
        if (translated != null) {
            System.out.println("英文名称: " + translated); // 输出: user_data_table
        }
    }
}

返回状态和编码

HTTP状态码

状态码	描述
200	请求成功
400	请求参数错误
500	服务器内部错误

业务状态码

业务码	描述	场景
200	成功	翻译操作成功完成
400	参数错误	node_name参数为空或格式错误
500	服务器错误	LLM服务调用失败或其他内部错误

响应示例

成功响应

{
    "code": 200,
    "message": "翻译成功",
    "data": {
        "original": "用户数据表",
        "translated": "user_data_table",
        "translated_list": ["user_data_table"]
    }
}

参数错误响应

{
    "code": 400,
    "message": "node_name参数不能为空",
    "data": null
}

服务器错误响应

{
    "code": 500,
    "message": "翻译失败: LLM服务调用超时",
    "data": null
}

使用场景

1. 数据库表名翻译：将中文表名翻译为符合数据库规范的英文表名
2. 字段名翻译：将中文字段名翻译为英文字段名
3. 数据建模：在数据建模过程中自动生成英文标识符
4. 系统集成：为第三方系统提供标准化的英文名称

翻译规则

翻译结果遵循以下规则：

• 使用小写字母
• 多个单词用下划线连接
• 符合PostgreSQL数据库命名规范
• 优先使用简短、准确的英文单词
• "表"字统一翻译为"table"

注意事项

1. 请确保输入的node_name为有效的字符串
2. 翻译结果适用于数据库表名和字段名，符合SQL命名规范
3. 如果翻译服务不可用，接口会返回相应的错误信息
4. 建议在生产环境中实现重试机制以提高可靠性

版本信息

• API版本：v1.0
• 文档版本：1.0.0
• 最后更新：2025年