很多学生在做课设或毕设时，除了生成 ER 图，还会被要求提交一张完整的“字段说明表”或“字段结构文档”。这类表格往往包含字段名、类型、主外键标识、字段说明等信息，是系统文档中非常重要的一部分。
schooltools.cn 平台提供了两个关键工具：
- SQL 转 ER 图工具 → 画图
- SQL 转字段说明表工具 → 生成表格
但很多人用完后会发现：
“为什么我导出的字段说明是空的？”
本文就来讲清楚：
- 字段说明怎么写
- COMMENT 在 SQL 中如何加
- 如何配合工具自动生成字段结构文档
✅ 字段说明表长什么样？
这是你最终要交给老师或写入论文的一张表格：
| 字段名 | 类型 | 主键 | 外键 | 字段说明 |
|---|---|---|---|---|
| id | INT | 是 | 否 | 用户主键，系统自动生成 |
| username | VARCHAR(50) | 否 | 否 | 登录账号，唯一 |
| status | TINYINT | 否 | 否 | 用户状态，0禁用，1正常 |
| role_id | INT | 否 | 是 | 外键，关联角色表 |
✅ 平台工具能做什么，不能做什么？
-
SQL转ER图工具：https://schooltools.cn/tool/sql_er
→ 主要用于生成数据库结构图，展示主外键关系。 -
SQL转字段说明表工具：https://schooltools.cn/tool/sql_csv
→ 自动解析 SQL 脚本，生成字段结构表格（含字段名、类型、主外键、说明等列）。
❗重点提醒：字段说明这一列，是从你 SQL 中的
COMMENT中读取的。
换句话说：你自己不写，工具没法帮你生成。
✅ 如何在 SQL 中添加 COMMENT？
CREATE TABLE user (
id INT PRIMARY KEY AUTO_INCREMENT COMMENT '用户唯一标识，自增主键',
username VARCHAR(50) NOT NULL COMMENT '用户登录账号，必须唯一',
password VARCHAR(100) NOT NULL COMMENT '密码字段，需加密存储',
status TINYINT DEFAULT 1 COMMENT '账号状态，0禁用，1启用',
role_id INT COMMENT '外键，关联角色表的ID',
create_time DATETIME COMMENT '记录创建时间，系统自动生成'
);每个字段后面加上 COMMENT '说明文字'，再用工具导出 CSV，就会带上说明内容。
✅ 字段说明应该写多详细？
思路是：告诉别人这个字段的“用处 + 限制 + 来源”。
推荐写法如下：
| 字段名 | 字段说明 |
|---|---|
| id | 系统自动生成的主键，用于唯一标识用户 |
| username | 用户填写的登录账号，必须唯一，不可重复 |
| status | 状态字段，0 表示禁用，1 表示启用，默认启用 |
| create_time | 创建记录的时间，由系统自动生成 |
✅ 常见错误写法（避免被扣分）
| 写法 | 问题 |
|---|---|
| username → 用户名 | 没有任何说明意义，只是翻译 |
| status → 状态字段 | 没写清楚状态值代表什么 |
| password → 密码 | 是否明文？是否加密？完全没交代 |
| role_id → 外键 | 外键关系未说明清楚（关联哪个表？） |
✅ 如果 SQL 没有写 COMMENT 怎么办？
平台工具无法猜出字段含义，你只能导出空白字段说明列，然后手动补全。
可以使用 Excel、Markdown 等格式补写说明，但仍建议在 SQL 脚本中写好注释，以后无论导图还是导表都方便。
✅ 一份完整字段说明文档应该包含哪些列？
推荐结构如下（工具导出格式一致，方便复制进论文或说明书）：
| 表名 | 字段名 | 类型 | 主键 | 外键 | 字段说明 |
|---|---|---|---|---|---|
| user | id | INT | 是 | 否 | 用户主键，自增 |
| user | username | VARCHAR(50) | 否 | 否 | 登录账号，需唯一 |
| user | role_id | INT | 否 | 是 | 外键，关联 role 表 |
✅ 总结
- 字段说明是文档中最容易忽略，却非常关键的部分；
- 平台工具可以帮你生成字段说明表结构，但内容靠你写；
- 在 SQL 中添加 COMMENT 是生成字段说明的关键一步；
- COMMENT 写得好，既能导图、导表，也方便日后维护；
- 不要再交一堆“用户名”、“密码”这种水说明了！
📎 实用工具回顾：
- ➤ SQL 转 ER 图工具 — 用于生成结构图
- ➤ SQL 转字段说明表工具 — 用于生成字段结构文档
两者配合使用，图和表一次生成，补完字段说明，一份完整的系统文档就完成一大半了。