Java to TypeScript Parser

一个强大的自动化工具，用于解析Java REST控制器并生成对应的TypeScript接口定义。特别适用于Spring Boot项目的前后端类型同步。

✨ 主要特性

• 🔍 智能扫描 - 递归扫描Java项目，自动发现Controller、VO、Entity文件
• 📋 注解解析 - 支持Spring Boot注解（@RequestMapping、@PostMapping等）
• 🔗 类型推断 - 自动解析@RequestBody和响应体类型，包含import依赖分析
• 📝 接口生成 - 生成标准的TypeScript接口定义和类型声明
• 🛠️ 服务类生成 - 自动生成API调用的辅助函数和服务类
• 📦 泛型支持 - 完整支持Java泛型转换（如RspVO<T>、List<T>）
• 🎯 路径优化 - 智能合并baseUrl和methodUrl，生成完整API路径
• 📁 目录解析 - 支持指定目录解析，灵活适配不同项目结构

🚀 快速开始

全局安装（推荐）

npm install -g java-to-ts-parser

安装后可以在任何地方使用：

# 使用完整命令
java-to-ts-parser parse -i /path/to/java/project -o ./generated

# 使用简短命令
j2ts parse -i /path/to/java/project -o ./generated

本地安装

npm install java-to-ts-parser

本地安装后使用npx：

npx java-to-ts-parser parse -i /path/to/java/project -o ./generated

📖 使用方法

命令行接口

1. 解析整个Java项目

# 解析指定项目到指定输出目录
java-to-ts-parser parse -i /path/to/java/project -o ./generated

# 使用默认输入路径（上级目录）
java-to-ts-parser parse -o ./generated

# 解析当前目录的上级目录（最常用）
java-to-ts-parser parse

2. 解析指定目录

# 解析项目中的特定模块
java-to-ts-parser parse -i /java/project -d src/main/java/com/company/account

# 直接解析指定目录（绝对路径）
java-to-ts-parser parse-dir -d /absolute/path/to/account/module -o ./generated

3. 运行示例

# 使用当前项目作为示例运行
java-to-ts-parser example

4. 查看帮助

java-to-ts-parser --help
java-to-ts-parser parse --help

编程方式使用

const JavaToTSParser = require('java-to-ts-parser');

async function parseJavaProject() {
  const parser = new JavaToTSParser('/path/to/java/project', './output');
  
  // 解析整个项目
  await parser.parse();
  
  // 或者解析指定目录
  await parser.parseDirectory('/path/to/specific/directory');
  
  // 使用优化版本（推荐）
  await parser.parseDirectoryOptimized('/path/to/specific/directory');
}

parseJavaProject();

🏗️ 支持的Java注解和类型

Spring Boot注解

• @RestController - REST控制器标识
• @RequestMapping - 基础路径映射
• @PostMapping - POST请求映射
• @GetMapping - GET请求映射
• @PutMapping - PUT请求映射
• @DeleteMapping - DELETE请求映射
• @RequestBody - 请求体参数
• @Entity - JPA实体类

Java类型转换

| Java类型 | TypeScript类型 | 说明 | |---------|---------------|------| | String | string | 字符串类型 | | Integer/int | number | 整数类型 | | Long/long | number | 长整型 | | Double/double | number | 双精度浮点 | | Float/float | number | 单精度浮点 | | Boolean/boolean | boolean | 布尔类型 | | Date | string | 日期（ISO字符串） | | LocalDateTime | string | 本地日期时间 | | LocalDate | string | 本地日期 | | BigDecimal | number | 大数字 | | List<T> | T[] | 数组类型 | | Map<K,V> | Record<string, V> | 映射类型 |

文件类型识别

• *Controller.java - Spring Boot控制器
• *VO.java - 值对象（Value Object）
• *.java - 普通Java类/实体类

📁 输出目录结构

generated/
├── api/                    # Controller对应的API接口
│   ├── AccountController.ts
│   ├── UserController.ts
│   └── ...
├── interfaces/             # VO类对应的TypeScript接口
│   ├── LoginReqVO.ts
│   ├── AccountRespVO.ts
│   └── index.ts
├── entities/              # Entity类对应的接口
│   ├── Account.ts
│   ├── User.ts
│   └── index.ts
├── common/                # 通用类型定义
│   └── RspVO.ts
└── index.ts              # 统一导出文件

📄 生成文件示例

输入：Java VO类

package com.company.account.vo.req;

public class LoginReqVO {
    private String vaCounterUserId;
    private String password;
    
    // getters and setters...
}

输出：TypeScript接口

// 自动生成的TypeScript接口
// 源文件: LoginReqVO.java
// 包名: com.company.account.vo.req
// 生成时间: 2025-09-09T10:00:00.000Z

export interface LoginReqInterface {
  vaCounterUserId: string;
  password: string;
}

export type LoginReqVO = LoginReqInterface;

输入：Java Controller

@RestController
@RequestMapping(value = "/accounts/external")
public class AccountExternalController {
    
    @PostMapping(value = "/doLogin")
    public RspVO<Void> doLogin(@RequestBody LoginReqVO request) {
        // implementation...
    }
    
    @PostMapping(value = "/getAccount") 
    public RspVO<AccountRespVO> getAccount(@RequestBody GetAccountReqVO request) {
        // implementation...
    }
}

输出：TypeScript API接口

// 自动生成的API接口 (优化版本)
// 源文件: AccountExternalController.java
// Controller: AccountExternalController
// 基础路径: /accounts/external
// 生成时间: 2025-09-09T10:00:00.000Z

import type { LoginReqVO } from '../interfaces/LoginReqVO';
import type { GetAccountReqVO } from '../interfaces/GetAccountReqVO';
import type { AccountRespVO } from '../interfaces/AccountRespVO';
import type { RspVO } from '../common/RspVO';

export interface AccountExternalControllerAPI {
  // POST /accounts/external/doLogin
  doLogin(request: LoginReqVO): Promise<RspVO<void>>;
  
  // POST /accounts/external/getAccount
  getAccount(request: GetAccountReqVO): Promise<RspVO<AccountRespVO>>;
}

export const AccountExternalControllerRoutes = {
  doLogin: {
    method: 'POST' as const,
    url: '/accounts/external/doLogin'
  },
  getAccount: {
    method: 'POST' as const,
    url: '/accounts/external/getAccount'
  }
} as const;

// API调用辅助函数
export class AccountExternalControllerService {
  private baseURL: string;
  private httpClient: any;

  constructor(baseURL: string, httpClient: any) {
    this.baseURL = baseURL;
    this.httpClient = httpClient;
  }

  async doLogin(request: LoginReqVO): Promise<RspVO<void>> {
    return this.httpClient.post(`${this.baseURL}/accounts/external/doLogin`, request);
  }

  async getAccount(request: GetAccountReqVO): Promise<RspVO<AccountRespVO>> {
    return this.httpClient.post(`${this.baseURL}/accounts/external/getAccount`, request);
  }
}

⚙️ 配置选项

命令行参数

| 参数 | 简写 | 说明 | 默认值 | |-----|-----|------|-------| | --input | -i | Java项目根目录路径 | ../ | | --output | -o | 输出目录路径 | ./generated | | --directory | -d | 指定要解析的具体目录 | - |

配置文件 (config.json)

项目根目录可以包含config.json文件进行更详细的配置：

{
  "input": "../",
  "output": "./generated",
  "javaFilePatterns": {
    "controllers": "**/*Controller.java",
    "voClasses": "**/*VO.java"
  },
  "typeMapping": {
    "String": "string",
    "Integer": "number",
    "Date": "string"
  }
}

🔧 高级用法

1. 批量处理多个模块

# 处理账户模块
java-to-ts-parser parse-dir -d /project/account-service -o ./generated/account

# 处理用户模块  
java-to-ts-parser parse-dir -d /project/user-service -o ./generated/user

# 处理订单模块
java-to-ts-parser parse-dir -d /project/order-service -o ./generated/order

2. 集成到构建流程

在package.json中添加脚本：

{
  "scripts": {
    "generate-types": "java-to-ts-parser parse -i ../backend -o ./src/types",
    "build": "npm run generate-types && next build"
  }
}

3. 与前端项目集成

// 在React/Vue项目中使用生成的类型
import { AccountExternalControllerAPI, LoginReqVO, RspVO } from './generated';
import axios from 'axios';

const api: AccountExternalControllerAPI = {
  async doLogin(request: LoginReqVO): Promise<RspVO<void>> {
    const response = await axios.post('/accounts/external/doLogin', request);
    return response.data;
  }
};

🛠️ 开发指南

本地开发

# 克隆项目
git clone https://github.com/okevinok/JavaParseCli.git
cd JavaParseCli

# 安装依赖
npm install

# 运行测试
npm test

# 本地测试CLI
node package/cli.js parse --help

项目结构

java-to-ts-parser/
├── package/
│   ├── cli.js              # 命令行接口
│   ├── index.js            # 主入口文件
│   ├── JavaParser.js       # Java代码解析器
│   └── TypeScriptGenerator.js # TypeScript生成器
├── config.json            # 默认配置
├── package.json           # NPM包配置
└── README.md             # 项目文档

🤝 贡献指南

欢迎贡献代码！请先阅读 贡献指南。

1. Fork 项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

📝 更新日志

v1.0.0

• ✨ 初始版本发布
• 🔍 支持Java Controller和VO类解析
• 📦 支持泛型类型转换
• 🛠️ 生成TypeScript接口和API服务类
• 📁 支持目录级别的精确解析

❓ 常见问题

Q: 如何处理自定义Java类型？

A: 工具会自动扫描项目中的所有Java文件，并解析import语句来找到自定义类型的定义。

Q: 支持Lombok注解吗？

A: 支持。工具可以解析使用@Data等Lombok注解的类。

Q: 如何处理复杂的泛型类型？

A: 工具支持嵌套泛型，如RspVO<List<AccountVO>>会被转换为RspVO<AccountVO[]>。

Q: 生成的代码可以直接在项目中使用吗？

A: 是的，生成的TypeScript代码遵循最佳实践，可以直接在TypeScript/JavaScript项目中使用。

📄 许可证

本项目基于 MIT 许可证开源。

🔗 相关链接

• GitHub仓库
• NPM包
• 问题反馈
• 更新日志

如果这个工具对你有帮助，请给个 ⭐️ 支持一下！