如何将大型 Java 代码库及私有依赖批量迁移到 Node.js/TypeScript？

建议采用什么方案？

建议建立“全项目符号解析 → 依赖图与迁移映射 → 分批生成 TypeScript → 行为对照验证”的流水线。类型和引用由确定性工具管理，方法实现转换和语义差异处理由 LLM 辅助完成。

现有转译器可以纳入评估，但能输出 TypeScript 不代表它能完整迁移这条 Java 执行路径。实际可行性取决于代码使用的 Java 特性、标准库、框架和运行时机制，也取决于私有依赖是否有可迁移的实现。

可以先选一条有代表性的 skill 调用链做试点，覆盖入口、内部依赖和外部交互，再决定哪些部分适合规则转换，哪些需要重写。没有实际源码和依赖清单，无法可靠估计自动化比例。

AST 和转译工具分别能解决什么？

JSweet 官方仓库说明，JSweet 能将 Java 转译为 TypeScript 和 JavaScript，并将 Node.js 列为运行环境之一。可以将它纳入试点，不必因为目标是 Node.js 就直接排除。

评估时，要检查所选版本是否支持项目使用的 Java 语法、Java API、目标模块格式和 TypeScript 工具链。用包含实际私有依赖的模块试编译，并执行行为测试。一个简单类转换成功，不能代表整条依赖链都可用。

如果需要自行建立迁移流水线，JavaParser 与 JavaSymbolSolver可以用于源码分析：前者生成 AST，后者将名称和表达式关联到声明。它们提供分析基础，不会自动完成 Java 到 TypeScript 的语义转换。

迁移中需要区分三个层次：

只读取 import 或按类名搜索文件，无法可靠处理重载、继承、静态导入和跨模块泛型引用。

第一步：还原可构建的 Java 项目和依赖闭包

先确认现有 Java 项目可以在明确的构建配置下运行，并整理：

• 主项目及私有依赖的源码根目录、生成代码目录和 JAR。
• Java 语言级别、编译 classpath、构建配置和注解处理器。
• 配置文件、资源文件、反射注册、服务发现及外部系统访问。
• 每个计划暴露为 skill 的入口、输入、输出和副作用。

即使已经拥有主 JAR 的完整源码，也不能认定所有私有依赖的源码都已齐备。缺少实现的依赖需要单独记录。读取 JAR 中的类型签名有助于解析引用，但不能据此恢复完整业务行为。

建议从 skill 入口计算所需的依赖闭包，并据此确定迁移批次。如果最终要求迁移整个代码库，可以在入口链路稳定后继续扩大范围。反射、配置驱动加载和动态分派可能被静态分析遗漏，需要结合配置、测试和运行记录补充。

第二步：建立符号索引，再生成迁移计划

将所有相关源码根目录和依赖提供给分析器。JavaParser 的符号解析文档介绍了如何通过 CombinedTypeSolver 组合源码、JAR 和 JRE 类型解析来源，以及通过 resolve() 等接口定位声明。

建议为符号分配稳定标识。方法标识至少应包含所属类型、方法名和参数类型，以免重载方法发生冲突。索引还应保存源码位置、继承关系、调用目标、字段访问和未解析引用。

接着建立统一的 Java → TypeScript 映射表，确定：

• Java 包和类对应的 TypeScript 文件及导出名称。
• 重载、内部类、泛型和可空值的表示方式。
• 哪些引用仅用于类型，哪些会产生运行时依赖。
• 哪些 Java API 需要兼容实现或 Node.js 适配器。

尽量保留模块边界和可追踪的目录关系；对于不适合目标语言的结构，可以作明确调整。所有生成任务共用这份映射表，避免各自决定路径和名称。

依赖图也不能直接假定为树。先识别强连通分量，将互相依赖的类组成迁移单元，再按“先依赖、后使用方”的顺序调度。纯类型引用形成的环与运行时初始化环应分别处理，后者还需要检查初始化顺序。

第三步：怎样给 LLM 提供跨文件上下文？

依赖图由分析程序构建，LLM 只接收当前迁移单元所需的上下文，无需在每次请求中重复发送整个仓库。

每次任务建议包含当前源码、直接依赖的目标接口、必要的被调用实现、相关调用方、测试用例和统一的语义转换规则。只提供方法签名有时不够：例如被调用方法会修改参数或依赖隐藏状态，就需要补充实现或行为说明。

下面是自定义任务清单的示意结构，不是某个框架的内置 API；其中类名和路径仅用于说明：

{
  "unitId": "com.example.rules.RuleEngine",
  "sourceFile": "src/main/java/com/example/rules/RuleEngine.java",
  "targetFile": "packages/rules/src/RuleEngine.ts",
  "dependencies": [
    {
      "javaSymbol": "com.example.model.Context",
      "targetFile": "packages/model/src/Context.ts",
      "targetExport": "Context",
      "usage": "type"
    }
  ],
  "contractFiles": ["contracts/rules.d.ts"],
  "testCases": ["fixtures/rules.json"],
  "unresolvedSymbols": []
}

usage 应根据实际使用方式生成。例如类被实例化或用于运行时判断时，就不能标成纯类型依赖。

先生成并审核跨模块契约，再填充实现。如果 LLM 认为接口需要调整，应提交接口变更请求，由编排程序更新映射和受影响的任务。不要让某个迁移任务静默改写其他模块已经依赖的接口。

无法解析的符号应进入待处理清单，不能通过猜测实现、生成空函数或大范围使用 any 来掩盖缺口。

第四步：如何组织批量执行和增量修复？

可以按以下顺序编排：

解析 Java 构建信息和源码
  → 建立符号索引及依赖图
  → 固定目标文件、导出名称和类型契约
  → 按依赖顺序迁移模块或强连通分量
  → 检查类型、imports 和运行时加载
  → 对照 Java 执行相同测试
  → 根据诊断修复当前单元及受影响的调用方

规则明确的声明和 imports 可由生成器统一输出，复杂方法体由 LLM 辅助转换。涉及运行时差异的代码应集中到适配层，避免同一种 Java 行为在多个文件中被实现成不同版本。

每个任务记录输入源码摘要、依赖契约摘要、转换规则版本和输出状态。输入或契约改变时，重新调度受影响的依赖方。这样既便于恢复中断的任务，也能避免无差别重跑整个仓库。

如果目标工程拆成多个 TypeScript 项目，可以考虑使用 Project References，通过 tsc -b 按引用关系构建。Project References 管理构建依赖；运行时 imports、包导出和模块解析仍需正确配置。

哪些语义差异必须专门验证？

优先检查业务实际涉及的差异：

• 数值行为：Java long 不能无条件映射为 number；使用 bigint 时仍需考虑定宽溢出及 JSON 表示。BigDecimal 的精度和舍入规则也需要显式保留。
• 集合与相等性：Java 的 equals()、hashCode() 和集合比较规则，可能与 JavaScript 对象身份比较产生不同结果。
• 重载与初始化：TypeScript 重载签名不会自动保留 Java 的运行时实现；静态字段、构造过程和循环依赖需要检查执行顺序。
• 并发与 I/O：线程、锁、阻塞调用和事务边界需要重新设计，改成 async 并不自动保持原行为。
• 动态机制：反射、注解、依赖注入、序列化和资源加载可能承担业务功能，删除相关语法前应确认用途。

应为这些项目制定明确的迁移规则并配套测试。只追求语法接近，容易留下类型检查无法发现的行为变化。

怎样判断迁移已经完成？

迁移期间，保留 Java 实现作为行为基准。对同一输入分别执行 Java 和 TypeScript，比较输出、错误、状态变化及外部副作用。

先固定时间、随机数和外部依赖等不稳定因素。涉及写库或外部操作时，使用隔离环境或受控替身，避免对照执行产生重复写入。测试应覆盖正常流程、边界值、异常路径，以及实际使用到的动态加载和初始化行为。

编译成功只能证明通过了相应的编译检查。业务验收还需要确认依赖闭包内没有未实现路径、代表性行为对照通过、性能符合实际需求，并验证目标部署环境能够独立运行所需功能。

对这类项目，一个有价值的首个成果是完成从 skill 入口到私有依赖的一条完整迁移链路。它能揭示工具的覆盖范围、语义差异和后续批量迁移的工作量。

备注：内容仅供参考。