设计文档总览

设计目标

forge-ddl 解决一个常见痛点：业务实体 POJO 与数据库表结构两张皮。

传统做法是先写 SQL 建表，再用 ORM 注解（MyBatis Plus @TableName、JPA @Entity）把字段一一对应，每加一列都要改两边。本框架反其道而行：

以注解后的 POJO 为「单一事实来源」，由框架在启动时反射解析、生成元数据，后续阶段可基于元数据自动产出 DDL。

分阶段路线

阶段	目标	状态
① 注解扫描	定义注解 + 启动扫描 + 元数据入注册中心	✅ 已完成（本文档覆盖范围）
② SQL 生成	基于 ModelDefinition 渲染 CREATE TABLE 语句	🚧 规划中
③ DDL 执行	比对线上 schema、生成增量变更并执行	🚧 规划中
④ 继承与组合	ABSTRACT 模型继承、PROXY 模型组合	🚧 规划中

本章接下来 4 篇文档全部围绕「阶段①」展开。

文档分篇

文档	关注点
整体架构	模块组成、依赖关系、装配链路（含 Mermaid 模块图）
注解模型设计	为什么用嵌套注解、注解树长什么样（含 class 图）
扫描机制	启动后如何从 classpath 走到 ModelRegistry（含时序图）
模型注册中心	注册中心的并发选型、重复注册策略、可见性约束

阅读建议

1. 第一次看：依次按上表顺序读，每篇 5–10 分钟
2. 只想抓重点：直接看《整体架构》里的 Mermaid 图
3. 想动手改代码：先看完《扫描机制》和《模型注册中心》，再去翻 使用指南 · 实战与速查 找具体方法签名