2026Technology-Competition/docs/API.md

COBOL → Java/Spark 迁移验证平台 API 文档

版本: v1.0 | 日期: 2026-08-28

---

一、核心模块 API

1.1 cobol_testgen 模块

主入口

from cobol_testgen import main

# 运行测试数据生成
main(cobol_files, output_dir, config=None)

参数说明：

参数	类型	说明
cobol_files	list[str]	COBOL源码文件路径列表
output_dir	str	输出目录路径
config	dict	可选配置参数

FieldTree 类

from cobol_testgen.read import FieldTree

# 解析COBOL源码
tree = FieldTree(copybook_name="example")

# 获取字段列表
fields = tree.flatten()  # 返回 dict[str, Field]

Field 类

from cobol_testgen.read import Field

# 字段属性
field.name      # 字段名
field.level     # 层级
field.pic       # PIC子句
field.usage     # USAGE类型
field.offset    # 偏移量
field.length    # 长度
field.decimal   # 小数位
field.signed    # 是否有符号
field.occurs    # OCCURS次数
field.redefines # REDEFINES字段
field.conditions # 88级条件
field.children  # 子字段

1.2 coverage 模块

from cobol_testgen.coverage import CoverageAnalyzer

# 创建覆盖率分析器
analyzer = CoverageAnalyzer()

# 标记覆盖情况
analyzer.mark_coverage(decision_points, path_assignments)

# 生成HTML报告
analyzer.generate_report(output_path)

1.3 design 模块

from cobol_testgen.design import DesignAnalyzer

# 创建设计分析器
analyzer = DesignAnalyzer()

# 枚举路径
paths = analyzer.enum_paths(field_tree, mode="rule")  # mode: "rule" | "ai"

# 生成测试记录
records = analyzer.generate_records(paths, field_tree)

---

二、编排器 API

2.1 orchestrator 模块（非DB管道）

from orchestrator import Orchestrator

# 创建编排器
orch = Orchestrator(config)

# 运行完整验证流程
result = orch.run(cobol_source, design_doc)

# 返回结果
result.status        # "pass" | "fail"
result.coverage      # 覆盖率百分比
result.test_cases    # 测试用例列表
result.diff_results  # 差异比对结果

2.2 orchestrator_db 模块（DB管道）

from orchestrator_db import OrchestratorDB

# 创建DB编排器
orch = OrchestratorDB(config)

# 运行DB管道验证
result = orch.run(cobol_source, design_doc)

# 返回结果
result.status        # "pass" | "fail"
result.db_coverage   # DB相关覆盖率
result.sql_results   # SQL执行结果

---

三、Runner API

3.1 CobolRunner

from runners import CobolRunner

# 创建COBOL运行器
runner = CobolRunner()

# 编译并运行COBOL程序
result = runner.compile_and_run(source_file, input_data)

# 返回结果
result.output        # 程序输出
result.return_code   # 返回码
result.coverage_data # 覆盖率数据

3.2 JavaRunner

from runners import NativeJavaRunner, SparkJavaRunner

# 创建Java运行器
runner = NativeJavaRunner()  # 或 SparkJavaRunner(spark_master)

# 运行Java程序
result = runner.run(class_path, input_data)

# 返回结果
result.output        # 程序输出
result.return_code   # 返回码

---

四、Comparator API

from comparator import FieldComparator

# 创建字段比对器
comparator = FieldComparator()

# 比对COBOL和Java输出
results = comparator.compare(cobol_output, java_output)

# 返回结果
for result in results:
    result.field_name   # 字段名
    result.cobol_value  # COBOL值
    result.java_value   # Java值
    result.status       # "match" | "mismatch"
    result.diff_type    # 差异类型

---

五、Agents API

5.1 LLMClient

from agents.llm import LLMClient

# 创建LLM客户端
client = LLMClient(model="deepseek-v4-flash", timeout=15)

# 调用LLM
response = client.call(messages, retries=1)

# 参数说明
messages: list[dict]  # 消息列表，格式: [{"role": "system"|"user", "content": "..."}]
retries: int          # 重试次数

5.2 Agent1Parser

from agents.agent1_parser import Agent1Parser

# 创建解析Agent
parser = Agent1Parser(llm_client)

# 解析COBOL COPYBOOK
field_tree = parser.parse(cobol_text)

# 返回FieldTree对象

5.3 Agent2Data

from agents.agent2_data import Agent2Data

# 创建数据生成Agent
agent = Agent2Data(llm_client)

# 生成测试数据
test_suite = agent.design(field_tree, target="boundary", spark_mode=False)

# 返回TestSuite对象

5.4 Agent3Diagnostic

from agents.agent3_diagnostic import Agent3Diagnostic

# 创建诊断Agent
agent = Agent3Diagnostic(llm_client)

# 分析差异
diagnosis = agent.analyze(field_result)

# 返回诊断结果字符串

---

六、数据模型

6.1 TestCase

from data.test_case import TestCase

# 测试用例
tc = TestCase(
    id="TC-001",
    fields={"FIELD1": value1, "FIELD2": value2},
    coverage_targets=["DP-001", "DP-002"]
)

6.2 TestSuite

from data.test_case import TestSuite

# 测试套件
suite = TestSuite(test_cases=[tc1, tc2, tc3])
suite.spark_config  # 可选Spark配置

6.3 FieldResult

from data.diff_result import FieldResult

# 字段比对结果
result = FieldResult(
    field_name="AMOUNT",
    cobol_value="1000",
    java_value="1000",
    status="match"
)

---

七、配置参数

7.1 全局配置

CONFIG = {
    "proc_parser": "rule",      # "rule" | "ai"
    "llm_generator": True,      # 是否使用LLM生成测试数据
    "coverage_target": 0.75,    # 目标覆盖率
    "max_paths": 100,           # 最大路径数
}

7.2 环境变量

变量名	说明	默认值
LLM_API_KEY	LLM API密钥	-
LLM_MODEL	LLM模型名称	deepseek-v4-flash
LLM_API_BASE	LLM API地址	https://api.openai.com/v1
DEEPSEEK_API_KEY	DeepSeek API密钥	-

---

八、错误处理

8.1 常见异常

异常类型	说明	处理方式
FileNotFoundError	文件不存在	检查文件路径
json.JSONDecodeError	JSON解析失败	检查输入格式
LLMError	LLM调用失败	重试或检查API密钥
CompilationError	COBOL编译失败	检查源码语法

8.2 错误恢复

try:
    result = orch.run(cobol_source, design_doc)
except LLMError:
    # 降级到规则引擎
    config["proc_parser"] = "rule"
    result = orch.run(cobol_source, design_doc)
except CompilationError as e:
    # 记录编译错误
    logger.error(f"Compilation failed: {e}")
    result = {"status": "error", "message": str(e)}

---

本文档最后更新：2026-08-28