cobol-java-v3/docs/detailed-design/03-runners.md

03 - runners 编译运行引擎

1. 模块概述

runners 模块负责 COBOL 程序与 Java 程序的编译、运行、覆盖率采集全流程。模块采用策略模式，通过抽象基类 Runner 统一不同语言运行时的接口，对外暴露一致的 compile -> run -> get_coverage 三阶段管线。

核心职责：

职责	说明
COBOL 编译	调用 cobc（COBOL 编译器）将 .cbl 源码编译为可执行文件
Java 编译	调用 mvn package 将 Maven 项目打包为 .jar
运行执行	通过 subprocess 启动编译产物，捕获 stdout/stderr 和返回码
测试数据写入	将 TestCase 列表序列化为 COBOL 二进制 / JSON 格式
覆盖率报告	采集分支覆盖数据（gcov / JaCoCo）并返回量化报告

---

2. 文件清单

runners/
  __init__.py              # 包导出：公开 API 声明
  runner.py                # 抽象基类 Runner + 数据类 BuildResult / RunResult / CoverageReport
  cobol_runner.py          # COBOL 编译·执行器（cobc 管线）
  gixsql_runner.py         # DB COBOL 程序编译·执行器（gixpp + cobc + gixsql 链接）
  native_java_runner.py    # Java 本地运行器（mvn + java -jar）
  spark_java_runner.py     # Spark 运行器（spark-submit）
  data_writer.py           # 测试数据序列化（COBOL 二进制 / Spark JSON / Native JSON）

---

3. 接口定义

3.1 数据类（runner.py）

@dataclass
class BuildResult:
    success: bool            # 编译是否成功
    artifact_path: str = ""  # 编译产物路径（.exe / .jar）
    log: str = ""            # 编译日志（stdout + stderr）

@dataclass
class RunResult:
    success: bool                # 运行是否成功（returncode == 0）
    records: list[dict]          # 运行输出记录（JSON 格式）
    log: str = ""                # 运行日志
    coverage_exec: str = ""      # 覆盖率执行文件路径

@dataclass
class CoverageReport:
    branch_rate: float = 0.0     # 分支覆盖率（0.0 ~ 1.0）
    covered_branches: int = 0    # 已覆盖分支数
    total_branches: int = 0      # 总分支数
    verdict: str = "PASS"        # 判定结果（PASS / FAIL）

3.2 抽象基类（runner.py）

class Runner(ABC):
    @abstractmethod
    def compile(self, source_dir: str) -> BuildResult: ...

    @abstractmethod
    def run(self, artifact: str, input_path: str, output_path: str) -> RunResult: ...

    @abstractmethod
    def get_coverage(self, artifact: str, run_id: str) -> CoverageReport: ...

3.3 CobolRunner（cobol_runner.py）

方法	签名	说明
compile	(src, dialect="ibm", gcov=False) -> BuildResult	旧式编译，-std=ibm-strict，供 orchestrator.py 使用
run	(binary, input_path, output_path) -> RunResult	旧式执行，stdin 管道 stdout
compile_with_links	(src, work_dir, copybook_dirs, sub_objects, gcov) -> BuildResult	新式编译：主程序 + 链接 SUB.o，支持 COPYBOOK 搜索路径和 gcov
run_file_based	(binary, run_dir, input_files, timeout) -> RunResult	新式执行：基于文件的 I/O，将输入文件复制到运行目录后启动程序

3.4 GixsqlCobolRunner（gixsql_runner.py）

方法	签名	说明
preprocess	(src_path, out_dir, copybook_dirs) -> str	gixpp 预处理：COPY 展开、SQL 归一化、格式修正
compile	(pp_path, exe_path, copybook_dirs, extra_srcs) -> GixsqlBuildResult	cobc 编译，链接 gixsql 库
run	(exe_path, work_dir, db_path, ...) -> GixsqlRunResult	执行 DB 程序，设置 SQLite 数据库路径
read_db_tables	(db_path, table_names) -> list[GixsqlTableData]	读取 SQLite 数据库表内容

3.5 NativeJavaRunner（native_java_runner.py）

方法	签名	说明
compile	(source_dir) -> BuildResult	Maven 打包，输出 target/program.jar
run	(artifact, input_path, output_path) -> RunResult	java -jar 执行，解析 stdout JSON 行
get_coverage	(artifact, run_id) -> CoverageReport	检查 jacoco.exec 是否存在，返回覆盖率

3.6 SparkJavaRunner（spark_java_runner.py）

方法	签名	说明
compile	(source_dir) -> BuildResult	Maven 打包，输出 target/program.jar
run	(artifact, input_path, output_path) -> RunResult	spark-submit 执行，读取 part-* 输出文件
get_coverage	(artifact, run_id) -> CoverageReport	返回固定 0.80 覆盖率（Spark 无原生覆盖率集成）

3.7 DataWriter（data_writer.py）

方法	签名	说明
write_cobol_binary	(cases, out)	将 TestCase 列表写为 COBOL 二进制格式（大端序 int64 / float64 / ASCII）
write_spark_json	(cases, cfg, d)	写 Spark 输入 JSON（part-00000.json），key 字段加序号后缀
write_native_json	(cases, out)	写 Native JSON（每行一个 JSON 对象）

---

4. 编译流程

4.1 COBOL 编译（cobol_runner.py）

旧式编译流程

.cbl 源文件
    |
    v
cobc -x -std=ibm-strict [-o 输出路径] [-g] [--coverage] 源文件
    |
    v
BuildResult(success, artifact_path, log)

• 默认超时 30 秒
• gcov=True 时追加 --coverage 参数生成 .gcno 文件

新式编译流程（带链接）

.cbl 源文件 + SUB*.o 对象文件
    |
    v
cobc -x -g [--coverage] [-I COPYBOOK路径...] -o 输出.exe 源文件 SUB1.o SUB2.o ...
    |
    v
BuildResult(success, exe_path, log)

• 默认超时 120 秒
• 工作目录切换至 work_dir（确保 .gcno 产出位置正确）
• 不使用 -std=ibm-strict，依赖默认方言

4.2 DB COBOL 编译（gixsql_runner.py）

DB 程序编译采用 gixpp + cobc 两阶段管线：

原始 .cbl 源文件
    |
    v -- _normalize_source()
    |   1. 剥离注释行（避免日文注释中的 EXEC SQL 被误匹配）
    |   2. EXEC SQL INCLUDE SQLCA -> COPY SQLCA
    |   3. EXEC SQL CONNECT TO 'literal' -> CONNECT TO :WS-GIX-CONN USER :WS-GIX-USR
    |   4. COPY REPLACING 内联展开（Python 侧）
    |   5. ALL COPY 展开（替代 cobc -E）
    |   6. 关键字间多空格压缩
    |   7. DIVISION/SECTION 头部列位置修正（Area A，列 8 起）
    |   8. SELECT ... FROM ... INTO -> SELECT ... INTO ... FROM（gixpp 要求 INTO 在前）
    |   9. CURRENT TIMESTAMP -> CURRENT_TIMESTAMP（SQLite 后端兼容）
    |  10. DB2 schema 限定表名去限定（SCHEMA.TABLE -> TABLE）
    v
_norm.cbl（规范源文件）
    |
    v -- preprocess()
    |   gixpp -i _norm.cbl -o _pp.cbl -e [-I COPYBOOK路径...]
    |   将 EXEC SQL 块转换为 GIXSQL 调用序列
    v
_pp.cbl（预处理后源文件）
    |
    v -- compile()
    |   1. _patch_sql_identifiers()：DB2 连字符标识符 -> 下划线（SQLite 兼容）
    |   2. _patch_sqlcode_normalize()：SQLite 约束错误码映射为 DB2 标准码
    |   3. cobc -x -L gixsql库路径 -K GIXSQL*函数 -l gixsql [-I COPYBOOK...] -o exe pp.cbl
    v
GixsqlBuildResult(success, exe_path, log)

4.3 Java 编译（native_java_runner.py / spark_java_runner.py）

两个 Java Runner 共享相同的 Maven 编译流程：

source_dir/pom.xml
    |
    v
mvn -B package -f pom.xml
    |
    v
source_dir/target/program.jar
    |
    v
BuildResult(success, artifact_path, log)

• 默认超时 120 秒
• 使用 -B（batch mode）避免交互式提示
• 产物固定为 target/program.jar

---

5. 运行流程

5.1 COBOL 执行

旧式执行（stdin 到 stdout）

input_path（二进制数据）
    |
    v subprocess.run([binary], input=data, capture_output=True)
    |
    v stdout 写入 output_path
    |
    v RunResult(success)

• 超时 30 秒
• 无输出记录解析（仅写入文件）

新式执行（基于文件）

input_files: {assign_name: source_path}
    |
    v 复制输入文件到 run_dir
    |
    v subprocess.run([binary], cwd=run_dir, capture_output=True)
    |
    v RunResult(success, log)

• 超时 60 秒（可配置）
• 工作目录为 run_dir，程序通过 ASSIGN 名读取文件
• 日志截断至 2000 字符

5.2 DB COBOL 执行（gixsql_runner.py）

exe_path + db_path（SQLite 数据库）
    |
    v 部署 DLL 到 exe_dir（libgixsql.dll, libgixsql-sqlite.dll 等）
    |
    v 复制输入文件到 work_dir
    |
    v subprocess.run([exe], cwd=work_dir, env={GIXSQL_DB_PATH: db_path})
    |
    v GixsqlRunResult(success, returncode, db_path, log)
    |
    v read_db_tables(db_path, table_names) -> 读取数据库输出

• 超时 30 秒（可配置）
• 环境变量 GIXSQL_DB_PATH 指向 SQLite 数据库
• DLL 部署策略：优先 lib_path，回退到 gixpp bin 目录
• returncode 0 或 1 均视为成功（COBOL STOP RUN 返回码差异）

5.3 Java 执行

NativeJavaRunner

input_path（JSON 文件）
    |
    v java -jar artifact（stdin 输入）
    |
    v 解析 stdout JSON 行 -> records 列表
    |
    v RunResult(success, records, log)

• 超时 60 秒
• 每行一个 JSON 对象

SparkJavaRunner

input_path（JSON 文件）
    |
    v spark-submit --class Main --master local[*]
    |   --conf spark.input.path=...
    |   --conf spark.output.path=...
    |   --conf spark.input.format=json
    |   --conf spark.output.format=json
    |   artifact
    |
    v 读取 output_path/part-* 文件 -> records 列表
    |
    v RunResult(success, records, log)

• 超时 300 秒（5 分钟）
• 输入输出格式通过 spark conf 配置
• 输出文件自动 glob 匹配 part-*

---

6. 错误处理

6.1 编译失败

场景	处理方式	返回值
cobc 编译错误	捕获 returncode != 0	BuildResult(success=False, log=stdout+stderr)
cobc 超时	捕获 TimeoutExpired	BuildResult(success=False, log="Compile timeout")
gixpp 预处理失败	捕获 returncode != 0，抛出 RuntimeError	raise RuntimeError("gixpp failed")
Maven 编译错误	捕获 returncode != 0	BuildResult(success=False, log=stdout+stderr)

6.2 运行时异常

场景	处理方式	返回值
COBOL 程序异常终止	捕获 returncode != 0	RunResult(success=False, log=stdout+stderr)
COBOL 程序超时	捕获 TimeoutExpired	RunResult(success=False, log="Run timeout")
DB 程序 returncode 1	视为成功（COBOL 语义差异）	GixsqlRunResult(success=True)
Java 程序异常	捕获 returncode != 0	RunResult(success=False, log=stdout+stderr)
Spark 程序超时	捕获 TimeoutExpired（300s）	RunResult(success=False, log="Run timeout")
DLL 未找到	运行时加载失败，日志记录	GixsqlRunResult(success=False, log=...)

6.3 Gixsql 专用处理

机制	说明
SQL 标识符归一化	DB2 连字符标识符自动转换为下划线（EMP-MASTER -> EMP_MASTER）
SQLCODE 映射	SQLite 约束错误码（-1555/-2067/-19）映射为 DB2 标准码（-803）
Schema 限定去限定	SCHEMA.TABLE -> TABLE（SQLite 无 schema 概念）
CURRENT TIMESTAMP	DB2 CURRENT TIMESTAMP -> SQLite CURRENT_TIMESTAMP
DLL 自动部署	运行前将 gixsql DLL 复制到 exe_dir 确保加载器找到

6.4 日志截断

所有 Runner 的日志均截断至固定长度以避免内存溢出：

Runner	日志截断长度
CobolRunner（旧式）	无截断（完整 stdout+stderr）
CobolRunner（新式）	2000 字符
GixsqlCobolRunner	500-1000 字符
NativeJavaRunner	无截断（完整 stdout+stderr）
SparkJavaRunner	无截断（完整 stdout+stderr）

---

7. 设计特点

7.1 双轨架构

CobolRunner 维护两套接口：

• 旧式接口（compile + run）：供 orchestrator.py 使用，兼容现有调用链
• 新式接口（compile_with_links + run_file_based）：支持非 DB 程序的文件 I/O 和 SUB.o 链接

两套接口互不干扰，通过不同方法名区分。

7.2 Gixsql 预处理管线

GixsqlCobolRunner 的预处理是模块中最复杂的部分：

1. Python 侧 COPY 展开：替代 cobc -E，解决 gixpp ESQL 解析器对 COPY REPLACING 伪文本的兼容问题
2. SQL 归一化：处理 DB2 与 SQLite 的语法差异（标识符、时间函数、schema 限定符）
3. SQLCODE 映射：注入代码将 SQLite 特定错误码转换为 DB2 标准码，确保 IF SQLCODE = -803 分支可达

7.3 DLL 部署策略

gixsql 运行时需要多个 DLL（libgixsql.dll, libgixsql-sqlite.dll 等）。部署策略：

1. 优先从 lib_path 复制
2. 若不存在，回退到 gixpp bin 目录
3. 检查文件大小避免重复复制

7.4 DataWriter 格式

格式	字节序	数值类型	字符串处理
COBOL 二进制	大端序（Network Byte Order）	int64 (>q) / float64 (>d)	ASCII，右补空格至 10 字节
Spark JSON	N/A	JSON 数字	UTF-8，key 字段加序号后缀
Native JSON	N/A	JSON 数字	UTF-8，每行一个 JSON 对象

---

8. 依赖关系

runners/
  runner.py          -> 无外部依赖
  cobol_runner.py    -> runners.runner, subprocess, pathlib
  gixsql_runner.py   -> runners.runner（仅类型引用），subprocess, sqlite3, pathlib, logging
  native_java_runner.py -> runners.runner, subprocess, json, shutil, pathlib
  spark_java_runner.py  -> runners.runner, subprocess, json, shutil, pathlib
  data_writer.py     -> data.test_case.TestCase, struct, json, pathlib

外部工具依赖：

工具	用途	使用者
cobc	COBOL 编译器	CobolRunner, GixsqlCobolRunner
gixpp	COBOL EXEC SQL 预处理器	GixsqlCobolRunner
mvn	Java 构建工具	NativeJavaRunner, SparkJavaRunner
java	Java 运行时	NativeJavaRunner
spark-submit	Spark 提交工具	SparkJavaRunner
libgixsql.dll	gixsql 运行时库	GixsqlCobolRunner（运行时链接）
libgixsql-sqlite.dll	SQLite 后端驱动	GixsqlCobolRunner（运行时加载）