SoftwareTree/JDX_ReverseEngineeringJSONExample

# JDX 逆向工程 JSON 示例 版权所有 © 2026 Software Tree, LLC。保留所有权利。 ## 概述 本仓库展示了 **JDX ORM** 框架的逆向工程能力，该框架可以从现有的关系数据库架构自动生成 Java 类定义和映射规范。生成的模型类同时兼容 **JDX ORM** 和 **Gilhari ORM**，适用于各种部署场景，包括独立应用程序、微服务以及 MCP（Model Context Protocol）服务器。 本示例使用 **MySQL Sakila 示例数据库**（MySQL 参考数据库）。为了演示如何将关系模式的一个子集逆向工程为 JSON 对象数据模型，模板中指定了三个表：`film`、`film_actor` 和 `film_category`。该工具会检查这些表，检测它们的列、数据类型、可空标志和关系，并生成使用 JDX ORM 和基于 JSON 的对象处理这些表所需的一切。 ## 项目结构 ``` JDX_ReverseEngineeringJSONExample/ ├── config/ │ ├── mysql_sakila_example_template.config # Template file: input to the reverse engineering tool │ ├── mysql_sakila_example_template_config.revjdx # Generated ORM mapping file (output) │ └── JDXDemo.config # Configuration for the JDXDemo GUI ├── Film.java # Generated JSON container class for the film table (output) ├── Film_Actor.java # Generated JSON container class for the film_actor table (output) ├── Film_Category.java # Generated JSON container class for the film_category table (output) ├── bin/ # Compiled .class files (generated after compilation) ├── sources.txt # List of .java files for compilation (auto-generated by compile scripts) ├── compile.bat # Windows: compile the generated Java source files ├── compile.sh # Mac/Linux: compile the generated Java source files ├── setEnvironment.bat # Windows: sets classpath environment variable ├── setEnvironment.sh # Mac/Linux: sets classpath environment variable ├── JDXReverseEngineer.bat # Windows: run the reverse engineering tool ├── JDXReverseEngineer.sh # Mac/Linux: run the reverse engineering tool ├── JDXDemo.bat # Windows: launch the JDXDemo GUI application ├── JDXDemo.sh # Mac/Linux: launch the JDXDemo GUI application └── README.md # This file ``` ## 前提条件 ### 系统要求 - **Java 开发工具包（JDK）：** 8 或更高版本 - **操作系统：** Windows（适用于 `.bat` 文件）或 Linux/macOS（适用于 `.sh` 等效文件） - **数据库：** 安装了 Sakila 示例数据库的 MySQL ### 软件设置 1. **JDX ORM SDK 或 Gilhari SDK 安装：** 确保您的系统上已安装 JDX ORM SDK 或 Gilhari SDK。 2. **环境变量（`JX_HOME`）：** 将 `JX_HOME` 环境变量设置为您的 JDX ORM 或 Gilhari SDK 顶级安装目录： set JX_HOME=C:\path\to\jdx_or_gilhari_home 3. **MySQL JDBC 驱动程序：** 本示例使用 MySQL Connector/J。请更新 `setEnvironment.bat` 中的路径以匹配您的本地 MySQL JDBC 驱动程序位置。当前配置引用： %JX_HOME%\external_libs\\mysql-connector-j-8.0.33.jar 请根据您的环境需要调整此路径。 4. **数据库配置：** 使用您的 MySQL 连接详情更新 `config/mysql_sakila_example_template.config`： - `JDX_DATABASE` URL 和凭据 - `JDBC_DRIVER` 路径（如果与默认值不同） ## 入门 ### 步骤 1：配置数据库连接 编辑 `config/mysql_sakila_example_template.config` 并更新连接字符串： ``` JDX_DATABASE JDX:jdbc:mysql://localhost:3306/sakila;USER=your_username;PASSWORD=your_password;JDX_DBTYPE=MYSQL;DEBUG_LEVEL=5 JDBC_DRIVER com.mysql.jdbc.Driver ``` ### 步骤 2：运行逆向工程工具 执行逆向工程工具以生成类和映射规范： **Windows：** ``` JDXReverseEngineer.bat ``` **Mac/Linux：** ``` chmod +x JDXReverseEngineer.sh # first time only ./JDXReverseEngineer.sh ``` 此命令将： - 读取模板配置文件（`mysql_sakila_example_template.config`） - 连接您的 MySQL 数据库 - 分析指定的表（`film`、`film_actor`、`film_category`） - 生成 Java 模型类 - 创建逆向工程的映射文件（`.revjdx`） ### 步骤 3：编译生成的类 使用提供的批处理脚本编译逆向工程的类： **Windows：** ``` compile.bat ``` **Mac/Linux：** ``` chmod +x compile.sh # first time only ./compile.sh ``` 这两个脚本会自动发现项目目录中的所有 `.java` 文件，将它们写入 `sources.txt`，然后编译到 `bin/`。 它们在类路径中包含必要的 JDX 和外部库。 ### 步骤 4：使用 JDXDemo GUI 探索 启动交互式演示应用程序以探索生成的类并执行 ORM 操作： **Windows：** ``` JDXDemo.bat ``` **Mac/Linux：** ``` chmod +x JDXDemo.sh # first time only ./JDXDemo.sh ``` JDXDemo GUI 允许您： - 查看生成的模型类（例如 `Film`、`Film_Actor` 和 `Film_Category`） - 测试对模型类的数据库查询和操作 - 检查实体之间的关系 - 验证映射规范 ## 配置文件 ### 模板配置（`mysql_sakila_example_template.config`） 此文件定义逆向工程参数： ``` JDX_DATABASE # Database connection string with JDBC URL JDBC_DRIVER # JDBC driver class name JDX_OBJECT_MODEL_PACKAGE # Package name for generated classes JDX_SUPERCLASS_NAME # Superclass for generated model classes JDX_GENERATE_ACCESSOR_METHODS # Whether to generate getter/setter methods JDX_GENERATE_JSON_MAPPINGS # Enable JSON mapping specification generation CLASS [ClassName] TABLE [TableName] # Specify tables to reverse-engineer ``` **关键配置选项：** - `JDX_SUPERCLASS_NAME com.softwaretree.jdx.JDX_JSONObject`：生成的（容器）类继承自 `JDX_JSONObject`，使它们具有 JSON 能力 - `JDX_GENERATE_JSON_MAPPINGS TRUE`：为容器（支持 JSON 的）类生成声明式映射规范 - `JDX_GENERATE_ACCESSOR_METHODS FALSE`：直接字段访问而非 getter/setter 方法（根据需要调整） ### 生成的逆向工程映射（`mysql_sakila_example_template.config.revjdx`） `.revjdx` 文件包含由逆向工程工具创建的完整映射规范，包括： - **虚拟属性：** 映射的数据库列及其 Java 类型 - **主键：** 从表定义派生出的主键属性 - **关系：** 从架构推断的一对一、一对多关系 - **空值处理：** 可空列的 SQLMAP 声明 - **集合类：** 关系的数组或集合定义 示例摘录： ``` CLASS .Film TABLE film VIRTUAL_ATTRIB film_id ATTRIB_TYPE short VIRTUAL_ATTRIB title ATTRIB_TYPE java.lang.String VIRTUAL_ATTRIB description ATTRIB_TYPE java.lang.String PRIMARY_KEY film_id RELATIONSHIP listFilm_Category REFERENCES .ListFilm_Category BYVALUE WITH film_id SQLMAP FOR description NULLABLE ; ``` ### JDXDemo 配置（`config/JDXDemo.config`） 指定在 JDXDemo 应用程序中使用的逆向工程类和映射文件： ``` JDX_ORMFile config/mysql_sakila_example_template.config.revjdx Classes com.softwaretree.jdxmysqlsakilaexample.reversed.json.model.Film ... ``` ## 生成的模型类（容器领域模型） 当 `JDX_GENERATE_JSON_MAPPINGS` 设置为 `TRUE` 时，逆向工程过程会生成简单的 shell（容器）类，这些类对应于基于配置的数据库表的关联实体的领域特定 JSON 对象模型类。 ### 容器领域模型架构 **JDX_JSONObject 基类：** 生成的容器类继承自 `JDX_JSONObject`，它是用作处理领域特定 JSON 对象持久化的基础超类。此超类提供了全面的 ORM 功能，因此容器类保持精简和专注。 **容器领域模型类：** 生成的容器类（例如 `Film.java`、`Film_Category.java`、`Film_Actor.java`）是极简的 shell 类，它们： - 只定义两个构造函数（通常是一个无参构造函数和一个带参构造函数） - 将所有持久化、序列化和 ORM 处理委托给 `JDX_JSONObject` 超类 - 在架构定义（在 `.revjdx` 映射文件中）和容器实现之间保持清晰的分离 **领域特定 JSON 对象：** JDX 和 Gilhari 不需要领域特定 JSON 对象模型类的显式编程定义（例如 ES6 风格的 JavaScript 类）。相反，框架使用这些容器领域模型类的实例以及声明式 ORM 规范（`.revjdx` 文件）来处理所有 JSON 对象数据。这种方法可以实现： - 架构驱动的领域模型管理 - 复杂嵌套 JSON 结构的一致处理 - 关系型和 JSON 表示之间的无缝映射 ### 生成的类 #### Film.java（电影） 表示 `film` 表的容器类，提供包含电影信息（标题、描述、上映年份、租金等）以及与电影分类关系的 JSON 对象的包装器。实际的数据结构和持久化行为在映射规范中定义。 #### Film_Category.java（电影分类） 表示 `film_category` 表的容器类，作为在 JSON 领域模型中将电影链接到分类的中间实体。 #### Film_Actor.java（电影演员） 表示 `film_actor` 表的容器类，作为在 JSON 领域模型中将电影链接到演员的中间实体。 ### 典型的容器类结构 生成的容器类通常如下所示： ``` public class FilmActor extends JDX_JSONObject { // No-argument constructor public FilmActor() { super(); } // Parameterized constructor public FilmActor(String initialJsonData) { super(initialJsonData); } } ``` 容器类是有意保持最小化的，因为所有属性映射、关系处理、JSON 序列化、持久化逻辑和 ORM 操作都由 `JDX_JSONObject` 超类根据声明式映射规范管理。 ## 生成后自定义 逆向工程后，您可以增强生成的类和映射： ### 修改生成的类 - 向生成的类添加自定义业务逻辑或方法 - 在保留 ORM 功能的同时覆盖默认行为 - 添加验证逻辑或计算属性 - 根据需要实现其他接口 ### 调整映射规范 - 删除不必要的属性或关系 - 使属性名称比原始列名称更有意义。例如，将晦涩的表列名 'cid' 映射到语义上有意义的属性名 'customer_id'： ``` VIRTUAL_ATTRIB customer_id ATTRIB_TYPE int SQLMAP FOR customer_id COLUMN_NAME cid ``` - 修改属性类型或空值处理 - 调整集合类型或关系基数 - 添加自定义获取策略或延迟加载提示 **重要提示：** 修改映射文件时，请保留 `.revjdx` 扩展名并保持正确的语法。请参阅 JDX 用户手册以获取详细的映射规范文档。 ## 使用场景 ### 独立应用程序 将生成的类与 JDX ORM 一起用于传统桌面或服务器应用程序。 ### 微服务（Gilhari） 将相同的模型类与 Gilhari ORM 一起部署用于微服务架构，受益于容器化部署和面向服务的设计。 ### MCP 服务器 通过 Gilhari 将生成的类集成到 MCP（Model Context Protocol）服务器中，以实现标准化的模型服务和组合场景。 ## 故障排除 ### 连接问题 - 验证 MySQL 正在运行并在指定的主机和端口可访问 - 检查模板配置中的数据库据 - 确保 MySQL JDBC 驱动程序 JAR 在类路径中 ### 编译错误 - 验证 `JX_HOME` 设置正确 - 检查所有必需的 JAR 文件是否在类路径中 - 确保 `sources.txt` 列出了正确的源文件路径 ### 类加载问题 - 验证 `JDX_OBJECT_MODEL_PACKAGE` 中的包名与生成的类匹配 - 确保编译后的类在 `bin/` 目录中 - 检查 `config/` 目录是否在类路径中 ### 关系映射问题 - 验证数据库架构中存在外键约束 - 检查配置中的表名与数据库表名完全匹配 - 检查生成的 `.revjdx` 文件中的 RELATIONSHIP 定义是否正确 ## 平台特定注意事项 - 如果需要不同的 JDBC 驱动程序，请更新 `setEnvironment.bat` / `setEnvironment.sh`。 ## 高级主题 ### 自定义包名 修改模板配置中的 `JDX_OBJECT_MODEL_PACKAGE` 以将生成的类组织到您首选的包结构中。 ### 使用不同的超类 更改 `JDX_SUPERCLASS_NAME` 以使用自定义基类，但请确保它与 JDX ORM 要求兼容。 ### 逆向工程其他表 在模板配置中添加更多 `CLASS ... TABLE ...` 声明以逆向工程其他数据库表。 ### 增量更新 在架构更改后再次运行逆向工程工具。`.revjdx` 文件将使用更新的映射重新生成。 ## 参考资料 如需全面信息，请参阅以下资源： - **JDX 用户手册：** 参阅"逆向工程"部分以获取详细文档 - **Sakila 数据库：** MySQL 提供了关于 Sakila 示例数据库的综合文档 - **JDX 配置参考：** 官方文档中所有配置选项的详细说明 - **Gilhari ORM 文档：** 使用 Gilhari ORM 部署生成的类的指南 ## 关于 `sources.txt` 的说明 此目录中的 `sources.txt` 文件包含来自开发人员机器的绝对路径，不应直接使用。`compile.bat` 和 `compile.sh` 脚本会在每次编译运行前通过发现当前目录中的 `.java` 文件自动重新生成它。 ## 导入到 Eclipse 逆向工程和编译后，可以使用 *File → Import → Import Existing Projects into Workspace* 将此项目作为现有的 Java 项目导入 **Eclipse IDE**。 ## 支持与贡献 如有问题、意见或建议： - 查阅官方 JDX 和 Gilhari 文档 - 查看本仓库中的配置示例 - 联系开发团队或社区支持 ## 许可证与归属 本示例作为 JDX ORM 和 Gilhari 框架的一部分提供。请参阅 JDX/Gilhari 许可条款以了解使用限制和要求。 Sakila 示例数据库由 MySQL 提供，可在 New BSD 许可证下获取。 **最后更新：** 2026 年 4 月 **JDX 版本：** 05.08（如逆向工程文件中所示）

标签：Gilhari ORM, Homebrew安装, Java类生成, JDX ORM, JSON, JSON对象模型, JS文件枚举, MCP服务器, ORM映射, Sakila数据库, VIRTUAL_ATTRIB, Waymore结果处理, 代码生成, 关系型数据库, 反向工程, 域名枚举, 容器类, 数据库schema, 数据持久层, 映射规范, 模型定义, 渗透测试工具