企业官网建设流程全解析

Pdman 这个工具，说实话在国产开源建模工具里算是一股清流。我最早接触它是因为要给一个老项目补数据库文档，试了好几个工具都不顺手，要么是英文界面看着费劲，要么是生成文档还要收费，直到同事甩给我这个绿色小工具，才发现原来做数据库建模和逆向出文档，能省下这么多事。

如果你是刚听说 Pdman，我用一句话给你定位：这是一个免费、开源、跨平台的数据库建模工具，支持中文界面，并且内置了从建模到生成建表 SQL、再到一键输出数据库设计文档的完整闭环。它特别适合这几类人：需要频繁给甲方或领导交数据库设计文档的开发人员，负责老系统维护、手上只有线上库没有文档的运维或后端，以及还在用 Visio 之类通用绘图工具画 ER 图的学生和初学者。

1. 工具选型解析：为什么在众多建模工具里选 Pdman

先聊点实际的。数据库建模这件事，市面上能选的工具其实不少，各有各的优缺点。我挑几个大家常用的做个对比，你就明白 Pdman 的位置在哪里了。

ERWin 和 PowerDesigner是老牌商业软件，功能确实强大。PowerDesigner 当年我在外企工作时用过，它对企业级架构、数据仓库建模的支持非常成熟。但问题也很明显：授权费不便宜，界面还是上个世纪的风格，学习曲线陡峭，而且它是 Windows 平台的工具，Mac 上想用就得开虚拟机。说实话，如果你只是要建一个业务系统的库表结构，用这类工具属于杀鸡用牛刀，大部分功能你根本用不到，还得忍受它那繁琐的操作逻辑。

Navicat 和 DBeaver这类数据库客户端，更多是把重点放在数据管理、查询、导入导出上。它们虽然也提供简单的 ER 图展示和模型功能，但建模能力相对薄弱。你很难在 Navicat 里精细化地设计索引、约束、触发器这些对象，它的模型视图更多是一个可视化浏览的功能，而不是设计工具。

Sybase PowerDesigner 的替代品里，还有一个不能不提的是 MySQL Workbench。它自带建模功能，如果你用的是 MySQL，确实能直接上手画 ER 图和做正向逆向工程。但它是官方为 MySQL 量身定做的，对其他数据库的支持就很一般，而且界面同样偏老派，一些操作逻辑也比较反人类。

Pdman 的定位恰好填补了这些工具的空白。它最初是个人开源项目，目标就很纯粹：把数据库建模和文档生成这两件事做好，并且对国内开发者友好。我用下来的感受是这么几点：

• 中文界面和中文文档生成，这对国内团队太关键了。给甲方交付的《数据库设计说明书》能直接生成中文 Word 或 Markdown，不用自己二次翻译。
• 跨平台免费，团队里有人用 Windows，有人用 macOS，大家都能跑同一个工具，不需要额外付费，也不涉及版权风险。
• 操作思路清晰，它的设计理念非常准确地切中了一个痛点：数据库模型的核心就是“表、字段、关系、索引、字典”，把这些要素管理好，自然能产出高质量的建表脚本和设计文档。没有一堆用不上的企业级功能堆在界面上，上手成本极低。
• 导出 SQL 支持多种数据库方言，同一套模型可以导出 MySQL、Oracle、PostgreSQL 等不同版本的建表语句。这个功能在做数据库迁移或支持多数据库版本的产品时特别实用。

2. 核心功能拆解与实操步骤：从安装到完成一次完整的数据库建模

接下来进入正题，我把一次完整的建模流程拆开，按实际操作顺序讲透。为了演示方便，我用一个常见的“用户-角色-权限”模型作为案例，这套模型虽然简单，但足够覆盖 Pdman 核心功能的使用场景。

2.1 安装与初始化准备

Pdman 的安装非常简单，你现在去它的 GitHub 仓库或者搜索官方下载地址，就能拿到对应操作系统的安装包。它是基于 Java 技术栈开发的，所以理论上只要有 JRE 环境就能跑。

• 如果你用的是 Windows，下载 zip 包解压后，找到启动脚本（通常是startup.bat或者直接运行 exe 文件）就能打开。
• macOS 用户下载 dmg 安装包拖进应用程序目录即可。
• Linux 用户可能需要给启动脚本添加执行权限，这在国产工具里算是对开发者比较友好的了。

第一次启动后，你会看到 Pdman 的主界面，左边是模型导航树，中间是设计画布，右边是属性面板。初次使用建议先看一下导航栏，把界面布局混个眼熟。我不建议你一上来就百度各种“技巧”，先把这个界面上的几个核心区域认清楚，操作逻辑就通了一半。

提示：Pdman 的操作界面是纯中文的，所以在学习和使用上，它比 PowerDesigner 这种纯英文工具不知道友好到哪里去了。第一次打开界面，你大概率能靠着直觉就完成基础操作。

2.2 创建项目与数据源配置：建模的第一步是定义连接

Pdman 的模型文件是以.pdman格式保存到本地的 JSON 文件，这意味着它天然适合放进 Git 仓库做版本管理。我见过不少团队用 Pdman 建模，直接把模型文件当代码一样提交，同事拉下来就能继续编辑，这个体验是那些存在数据库里或私有格式里的商业建模工具给不了的。

创建项目时，Pdman 会引导你配置默认的数据源连接信息。这一步的核心是选择你最终要部署的目标数据库类型，比如 MySQL、Oracle、PostgreSQL、SQL Server、SQLite、MariaDB 等。

以我们的“用户-角色-权限”模型为例，假设目标数据库是 MySQL 5.7 以上版本，数据源配置里设置好数据库名、用户名、密码即可。这个配置的作用有两层：

1. 在正向工程中，Pdman 会根据你选的数据库类型生成对应方言的建表脚本。
2. 在反向工程中，Pdman 需要连接真实的数据库来读取表结构信息。

如果你不确定自己的数据库版本怎么办？我的建议是：保持默认配置先往下走，后面导出 SQL 时再根据实际情况微调。Pdman 的 MySQL 模板兼容性做得不错，5.7 和 8.0 的主要差异集中在字符集默认值上，后面在导出步骤里可以改。

2.3 设计逻辑模型：从零创建表、字段、索引和关系

数据源配置完成后，就进入了核心的模型设计环节。我先建立三张核心表：

• sys_user：用户表，存储系统用户的基础信息
• sys_role：角色表，存储角色定义
• sys_user_role：用户角色关联表，用于多对多关系

右键左侧导航树中的“表”节点，选择“新建表”，然后在右侧属性面板设置表名、表注释、字段列表。

第一步：设置表基本信息

表名使用小写加下划线的蛇形命名法，这是国内开发者的主流习惯。表注释建议写清楚表的业务含义，比如“用户信息表”而不是简单的“用户”，这样以后生成的文档可读性会好很多。

第二步：定义字段

sys_user表的字段设计如下：

在 Pdman 中新建字段时，重点注意几个细节：

• 主键设置：在字段上勾选“主键”选项，生成 SQL 时会自动处理 PRIMARY KEY。
• 自增：MySQL 的 AUTO_INCREMENT 在 Pdman 中通过字段属性里的“自增”勾选实现。如果你用的是 Oracle，这个选项会被自动忽略，Oracle 序列需要另外处理。
• 默认值：CURRENT_TIMESTAMP这种表达式可以直接填在默认值输入框里，Pdman 不会做额外转义，会原样写进 DDL。

第三步：创建索引

切换到“索引”页签，点击“新增索引”。索引类型支持普通索引、唯一索引、全文索引。对于sys_user表，我给username建立唯一索引，给email和phone建立普通索引，然后给组合查询场景建立一个(status, create_time)的联合索引。

这里有一个我踩过的坑：Pdman 的索引列表中，每个字段点击上移/下移就能调整顺序，这个顺序直接决定了索引的字段顺序。刚开始用的时候我没注意，把联合索引字段顺序排反了，导致 SQL 里索引一直没被命中，排查了半天才发现是建模阶段字段顺序错了。

第四步：建立表关系

切换到“关系”视图，在画布上把sys_user_role.user_id拖到sys_user.id上，Pdman 会自动识别且创建外键关系。同理，把sys_user_role.role_id拖到sys_role.id上。

Pdman 的关系建模支持一对一、一对多、多对多三种。我在设计时通常遵循一个原则：逻辑模型保留外键关系，但生成物理模型时会根据实际情况决定是否用物理外键。很多互联网团队为了分库分表方便，会刻意避免物理外键，只用逻辑外键。Pdman 在这个点上处理得比较灵活，你可以选择生成关系，或在生成 SQL 时去掉外键约束。

2.4 使用字典与枚举：规范字段取值的利器

Pdman 的“字典”功能是一个容易被忽略但其实非常实用的模块。它对应数据库设计中的“枚举值管理”，但比 SQL 里的 ENUM 类型要灵活得多。

以sys_user.status字段为例，它只有 1（启用）和 0（禁用）两种取值。我可以在字典管理中创建一个叫做“用户状态”的字典，定义两个枚举项，然后在字段属性里把status关联到这个字典。

这样做的好处是什么？

• 生成的数据库设计文档里，status字段会自动带上取值范围说明，领导看文档时一眼就知道这个字段是干什么的。
• 后续代码生成时，这个字典可以映射为 Java 枚举类或前端常量定义，减少团队内部的沟通成本。
• 如果以后状态取值需要扩展，比如加一个“已注销”状态，只需维护字典定义，不需要去改每一条 SQL 注释。

同样的方法，我可以再建“逻辑删除标志”“性别”“是否”等常用字典。这个习惯一旦养成，你会发现数据库模型的“自描述性”强了很多，不用去看代码就能理解字段含义。

2.5 正向工程：从模型导出建表 SQL

模型设计完成后，最激动人心的时刻就是生成 SQL。点击菜单栏的“正向工程”，Pdman 会弹出一个预览窗口，里面就是完整的目标库建表语句。

这里多提一句，Pdman 的正向工程生成 SQL 的规则是“智能”的：不是每个数据库都一样。MySQL 模板会默认给 InnoDB 引擎和 utf8mb4 字符集；PostgreSQL 模板则会生成SERIAL类型或IDENTITY；Oracle 模板则会按 Oracle 的语法生成。所以你前期选对了目标数据库，这一步的产出基本上是开箱即用的。

但是，我要特别提醒一个我经常见到的坑：Pdman 的默认 MySQL 模板中，BIGINT类型的主键不会默认带UNSIGNED，如果你的业务主键准备用雪花算法生成，还是建议在字段设置里勾选无符号，避免主键上限不够用。别觉得这是小事，我见过不止一个项目上线后主键溢出的场景，那个排查过程相当痛苦。

导出的 SQL 可以直接复制到 Navicat 里执行，也可以保存成.sql文件经过版本管理后统一执行。Pdman 支持导出增量 SQL，也就是只生成新增或变更部分的语句，这个功能对线上环境变更非常友好。

2.6 反向工程：从已有数据库逆向生成模型和文档

如果说正向工程是“从设计到实现”，那反向工程就是“从实现反推设计”。这个功能在维护老系统、接手离职同事的项目时，简直是救命稻草。

点击“反向工程”，填入数据库连接信息，Pdman 会读取数据库中的所有表、字段、索引、外键，自动在画布上生成对应的模型关系图。整个过程比手动建表快了不止一个量级。

我实际用下来的体验是：

• 表多的情况下（超过100张表），Pdman 会生成一个比较密集的关系图，这时不要指望画布能自动排布得美观，它只会按默认布局平铺。你可以手动调整每张表的位置。
• 逆向生成的模型，字段注释、索引、默认值都能比较准确地还原，但触发器和存储过程是不会被带进模型的。这需要你自己在文档里补充说明。
• 逆向之后，建议赶紧执行一次“导出文档”，把当前真实库表的现状沉淀成文档存档。万一以后库表被人改了，你还有一份基线可对比。

3. 文档生成与团队协作流的完整实践

3.1 一键生成数据库设计文档（Word/Markdown/HTML）

Pdman 作为一个自带文档生成能力的工具，它让我最省心的地方就在这里。以前我给别人做数据库设计说明，都是先截图，再打开 Word 一点点排版，三个小时的重复劳动想死的心都有。现在只需要点一下“生成文档”，选择你想要的格式，一份结构完好的《数据库设计说明书》就出来了。

我比较推荐先出 Markdown 再转 Word的工作流，原因有两点：

1. Markdown 生成速度快，而且格式干净，适合在 Git 里做版本管理。
2. Word 版用于交付给非技术人员或者需要盖章的正式场合。Pdman 支持直接导出 Word，也可以先用 Markdown 产出，再通过 Pandoc 转成 Word 自己微调封面和页眉。

生成出来的文档内容通常包含这几块：数据表清单、每张表的字段明细（含类型、长度、是否可空、默认值、注释）、索引信息、表之间的关系描述。这些内容虽然看起来是“套话”，但在评审会上你会发现，有一个结构齐全的文档，对方根本问不出太多刁钻问题，因为该有的信息你都在文档里展示了。

3.2 模型文件版本管理与多人协作建议

前面提过，Pdman 的模型文件本质上是 JSON 格式。这个特性看起来不起眼，实际配合 Git 用起来，能带来极大的协作优势。

我建议团队做这样几件事：

• 在代码仓库里专门建一个docs/database目录，把.pdman模型文件提交进去。
• 约定一个规矩：任何人修改表结构，必须先在 Pdman 里改模型，再导出 SQL，不允许绕过模型直接进数据库改表。
• 每次发布新版本，在 Git 的提交说明里写好“更新了哪些表、哪些字段”。

这样做一段时间以后，你的版本库会自动形成一条清晰的数据库演进日志。新同事入职看这套历史记录，比看任何上古文档都直观。

多人同时编辑同一个.pdman文件时，可能会遇到合并冲突。Pdman 的 JSON 结构还算友好，冲突通常发生在同一个表的不同字段，Git 会提示冲突，你手动选择保留哪一份即可。如果团队模型文件比较大，我建议拆分成“订单域”、“用户域”、“支付域”等多个模型文件，不同模块由不同的负责人维护，从根上降低冲突概率。

3.3 用代码生成能力打通开发链路

Pdman 还有一个被很多人忽略的能力：基于模型生成代码。它会根据表结构和字段定义，自动生成对应的 Java 实体类、Mapper 接口、MyBatis XML 映射文件等。

虽然它的生成模板不像专门的低代码平台那么花哨，但对于单体应用或中小团队来说，生成的代码质量完全可用，能省掉不少重复的 CRUD 代码编写时间。更重要的是，因为代码是从模型生成的，代码和数据库设计天然保持一致，不可能出现实体类和表字段对不上的情况。

我用它的方式，一般先把模型维护到位，然后生成一次代码作为“脚手架”，具体的业务逻辑再在脚手架基础上去改。这样既享受了自动化带来的效率，又不会因为模板的局限性而束缚业务实现。

4. 常见问题与排查技巧实录

4.1 连接数据库失败，提示无法创建连接

这恐怕是用到反向工程时最多发的故障，我总结了一下，90% 的情况出在下面几个原因：

• 未开放远程访问权限：MySQL 或 PostgreSQL 默认只监听 localhost，你需要检查目标库的 bind-address 配置。
• 时区问题：给 MySQL 连接地址加上?serverTimezone=Asia/Shanghai参数能解决大部分连接后查询时报时区错的问题。
• 端口被防火墙挡住：这个问题在云服务器上特别常见。你本地 Navicat 能连上，但 Pdman 连不上，多半就是网络策略问题，检查目标主机的安全组规则。
• 驱动缺失：旧版本 Pdman 可能不内置所有数据库驱动，如果你用的是比较新的数据库版本比如 PostgreSQL 15+，建议升级 Pdman 到最新版本，或者手动把对应的 JDBC 驱动 jar 包放到安装目录的 lib 下。

我的排查顺序是：先在本机用命令行工具测一遍账号密码，确认能连，再看 Pdman 的连接参数是否和命令行一致，最后才考虑网络和驱动的问题。

4.2 生成的 SQL 执行失败：数据类型和特殊字符的坑

有一次我帮朋友生成一套 Oracle 的脚本，执行时报“无效的关系运算符”，最后定位到是字段名和 Oracle 关键字冲突了。Pdman 本身不会智能到自动帮你加引号，所以这种坑非常隐蔽。

建议每次生成 SQL 后，至少在目标数据库上跑一遍验证脚本。尤其是：

• 字段名是否为desc、level、comment这类数据库保留字
• 默认值是否和目标库语法兼容，比如CURRENT_TIMESTAMP在 SQL Server 中可能不适用
• 字段长度是否超出目标库的限制，比如 MySQL 5.6 之前索引最长 767 字节，utf8mb4 字段的 varchar 长度不能超过 191

这类问题，只有真实执行一次 SQL 你才能发现。Pdman 只是生成工具，不替你把关所有数据库方言细节。

4.3 生成文档时中文乱码或字体异常

这个问题多见于 Windows 环境。解决思路很朴实：在导出文档前，检查你的系统有没有安装中文字体，以及 Pdman 的配置文件里默认编码是否为 UTF-8。一般改成 UTF-8 之后重启工具，问题就消失了。如果你用的是文档模板进行导出，还需要检查模板自身的字体配置，把标题和正文的字体调整为系统中文字体，否则 Word 里可能会显示成“方框”。

4.4 BigDecimal 与 decimal 映射不准确

这是做 Java 项目的同事容易遇到的问题。Pdman 的 MySQL 逆向工程中，decimal(10,2)类型会被映射成BigDecimal还是Double，取决于你选的代码生成模板。市面上有些模板默认把所有小数都映射成 Double，这会导致精度丢失。如果项目里对金额、折扣等字段有精度敏感要求，记得在生成代码前检查模板中 decimal 的映射规则，必要时改成BigDecimal。

4.5 模型文件损坏或打不开怎么办

.pdman文件本质是 JSON，如果真的遇到文件损坏，可以拿一个文本编辑器（比如 VS Code）直接打开，看 JSON 结构哪里断了，人工修一下再重新导入。当然这个操作比较硬核，前提是你对 JSON 结构有点了解。更保险的方案是，养成习惯，每隔一段时间导出一次文档或 SQL 备份，万一模型文件真坏了，还能靠 SQL 反向工程把结构追回来。

从我跟数据打交道这十年的经验来说，Pdman 的定位非常清晰：它不追求做成一个无所不能的企业级建模平台，而是在“数据库建模”这个具体问题上，把建模、SQL 生成、文档输出、代码生成这四件事做到了“小而美”。很多团队其实不需要 PowerDesigner 那种庞然大物，他们需要的只是一个能让数据库设计和交付文档这件事省心的工具，而 Pdman 恰好就是这个工具。

如果让我给刚接触它的人一个建议，我会说：找一个小项目，按照我上面的流程完整走一遍，从建模到生成 SQL，再到生成文档，整个过程不需要半天时间。等你亲手把一条链路跑通了，自然就明白在哪个环节能加自己的规范、在哪个环节可以自定义模板、在哪个环节需要特别小心。工具始终是工具，能把它用出多大价值，最终还是取决于你把设计规范沉淀到什么程度。

最后分享一个我自己的使用习惯：每次数据库版本的发布，我不仅会保存当时的.pdman模型文件，还会导出一份当时的数据库设计文档和一份完整建表 SQL，三个文件一起打成一个版本标签。这样做的好处是，任何时候想复盘当时的表结构设计，都不需要重新连接数据库或者回忆，直接解压那个标签，所有东西都在里面了。这就是工具之外、习惯带来的长期复利。