SQL to ER Diagram 是一款免费开源的 ER Diagram 生成器：粘贴CREATE TABLE语句，即可获得一张干净、可交互的实体关系图（ERD），且 100% 在浏览器本地运行、不上传任何数据。本文将带你从读懂它的目录结构出发，掌握新增 SQL 方言的完整步骤，最后附上一份可直接执行的 PR 实践清单，帮助你以最低的门槛完成第一次开源贡献。

为什么这个项目适合新手贡献

对新人友好，是 SQL to ER Diagram 最突出的贡献环境：

• 依赖极少：运行时依赖只有 2 个（构建用 Vite、布局用@dagrejs/dagre），打包后仅约 32KB gzip，见 package.json；
• 无后端、无数据库：整个工具就是一个静态页面，不需要配置服务就能本地跑起来；
• 模块边界清晰：解析、布局、渲染、序列化各司其职，改一个方言基本只碰一两个文件；
• MIT 协议：作者在 README.md 中明确欢迎 "add your own SQL dialects — go for it"。

一键启动：五分钟搭建开发环境

在任意目录克隆仓库并启动开发服务器：

git clone https://gitcode.com/gh_mirrors/sq/sqltoerdiagram cd sqltoerdiagram npm install npm run dev # 打开 http://localhost:5173

三个脚本定义在 package.json 中：dev（Vite 开发服务器）、build（产出dist/静态文件）、preview（本地预览生产构建）。贡献前建议养成npm run dev自测、npm run build确认不报错的习惯。

目录结构：新代码应该放哪里

仓库顶层只有src/、public/、scripts/三块，职责如下：

src/下的核心文件，按数据流排列：

数据流：一行 SQL 如何变成一张图

理解数据流，是写好贡献代码的前提。整条链路非常短：

1. 解析：src/parse.js 中的parseSchema()先判断格式，再分发给对应解析器，产出统一模型{ tables, relations, errors }；
2. 布局：src/layout.js 用 dagre 计算每张表的位置（layout()函数）；
3. 渲染：src/renderer.js 把表栅格化为离屏位图，平移缩放时只做drawImage，所以几百张表依然流畅；
4. 交互与回写：画布上的编辑通过 src/edit.js 的applyEdit()利用解析器记录的 source span 做"外科手术式"文本替换，注释和格式不会被破坏。

非 SQL 格式（Prisma、SQLAlchemy 等）走 src/formats/util.js 里的finalize()，产出同一种模型——保持这个模型形状不变，是所有解析类贡献的黄金法则。

新增 SQL 方言：区分两种"方言"再动手

这里要先厘清一个概念，避免改错文件：

• SQL DDL 方言（PostgreSQL / MySQL / SQLite / SQL Server / Snowflake）：影响的是 DDL 语法宽容度与列类型建议，代码在 src/dialects.js 和 src/parser.js；
• 输入格式（Prisma / DBML / Mermaid / PlantUML 等）：整段文本到模型的解析器，代码在 src/formats/ 和 src/parse.js。

场景一：新增一个 SQL DDL 方言（如 Oracle）

第 1 步：在方言表中注册。打开 src/dialects.js，DIALECTS是一个扁平对象，每个方言只需三样信息：label（下拉菜单显示名）、default（新增列的默认类型）、types（编辑列类型时的建议列表）：

oracle: { label: 'Oracle', default: 'VARCHAR2(255)', types: ['NUMBER', 'VARCHAR2(255)', 'CLOB', 'DATE', 'TIMESTAMP'], },

下拉菜单与"添加列"功能会自动读取这张表，无需改 UI。若想让新方言成为默认值，修改 DEFAULT_DIALECT 即可。

第 2 步：适配 DDL 语法差异。src/parser.js 已经对反引号、双引号、[方括号]、schema.限定名做了宽容处理（见文件头部注释 L1-L13）。若目标方言有新特性（如 Oracle 的NUMBER(p,s)、MySQL 的ENGINE=InnoDB子句），按现有模式扩展对应分支即可；原则是解析失败时给出 error 而不是抛异常——parseSchema()会捕获异常并把消息放进errors（src/parse.js），界面上会友好提示。

第 3 步：用真实 dump 验证。建议从目标方言的mysqldump/pg_dump风格导出脚本中截取 5~10 张表做样例，粘贴进npm run dev页面核对：表是否齐全、外键连线是否正确、注释是否被忽略。

场景二：新增一种输入格式（如 TypeORM）

流程与官方文档描述的扩展点一一对应：

1. 新建解析器src/formats/xxx.js，导出parseXxx(text)，返回值必须符合统一模型；可复用 util.js 中的makeTable/addColumn/finalize/splitTopCommas等共享工具，参考 bigquery.js 或 sequelize.js 的写法；
2. 注册格式：在 src/parse.js 的FORMATS中加一行显示名，并在parseSchema()的 switch 中接入；
3. 补充自动检测：在 detectFormat() 中为该格式写一条特征正则（例如 Prisma 靠model X {/datasource识别），注意正则要有区分度，避免误伤 SQL；
4. （可选）落地页：在 scripts/landing-data.mjs 中新增一条页面数据，运行node scripts/gen-landing.mjs生成静态页。

注意 parse.js 中的res.editable = fmt === 'sql'：画布双向编辑只对 SQL 生效，新格式天然是只读视图，这是设计使然，不要试图绕过。

PR 实践清单：提交前逐项勾选

📋 提交前，按这份清单自查：

• npm run dev下用真实样例验证功能，正常输入与异常输入（残缺语句、空文件）都有预期行为；
• npm run build通过、npm run preview页面正常，确保没有引入未使用的导入或语法错误；
• 返回值遵守统一模型形状（{ tables, relations, errors }，列含pk/nn/unique/fk标志），参考 serialize.js 头部注释 中的模型约定；
• 不新增运行时依赖——项目以"deps 2"为卖点（见 README.md 徽章），依赖变更需在 PR 中单独说明理由；
• 解析类改动覆盖边界场景：注释中的符号、字符串内的引号、嵌套括号（可参考 stripCommentsBQ 的引号感知写法）;
• 文案与命名跟随现有风格：文件头部用 2~4 行注释说明模块职责，注释用英文；
• PR 描述中附上"改前 / 改后"的输入示例与预期图面效果，方便维护者复现。

常见问题

改方言会影响其他格式吗？不会。DIALECTS只服务 SQL 路径的"新增列默认类型与类型建议"；各输入格式解析器彼此独立，唯一的公共契约是统一模型。

没有 TypeScript、没有测试框架，质量靠什么保证？靠模块边界小 + 纯函数设计：解析器不碰 DOM，渲染器不碰解析结果之外的状态。你贡献前只需在浏览器里做可视化验证，这正是该项目"轻装上阵"的取舍。

从哪个文件开始读源码最合适？建议按数据流顺序：src/parse.js（35 行，看懂调度）→ src/parser.js（核心解析）→ src/layout.js（布局）→ src/main.js（组装）。四个文件读下来，整个应用就尽收眼底了。