字段说明表怎么写才规范？SQL 加上这一步，生成 ER 图 + 字段解释就一站搞定

很多学生在做课设或毕设时，除了生成 ER 图，还会被要求提交一张完整的“字段说明表”或“字段结构文档”。这类表格往往包含字段名、类型、主外键标识、字段说明等信息，是系统文档中非常重要的一部分。 [schooltools.cn](https://schooltools.cn) 平台提供了两个关键工具： - [SQL 转 ER 图工具](https://schooltools.cn/tool/sql_er) → 画图 - [SQL 转字段说明表工具](https://schooltools.cn/tool/sql_csv) → 生成表格 但很多人用完后会发现： > **“为什么我导出的字段说明是空的？”** 本文就来讲清楚： - 字段说明怎么写 - COMMENT 在 SQL 中如何加 - 如何配合工具自动生成字段结构文档 --- ## ✅ 字段说明表长什么样？ 这是你最终要交给老师或写入论文的一张表格： | 字段名 | 类型 | 主键 | 外键 | 字段说明 | |--------|------|------|------|-----------| | id | INT | 是 | 否 | 用户主键，系统自动生成 | | username | VARCHAR(50) | 否 | 否 | 登录账号，唯一 | | status | TINYINT | 否 | 否 | 用户状态，0禁用，1正常 | | role_id | INT | 否 | 是 | 外键，关联角色表 | --- ## ✅ 平台工具能做什么，不能做什么？ - **`SQL转ER图工具`**：[https://schooltools.cn/tool/sql_er](https://schooltools.cn/tool/sql_er) → 主要用于生成数据库结构图，展示主外键关系。 - **`SQL转字段说明表工具`**：[https://schooltools.cn/tool/sql_csv](https://schooltools.cn/tool/sql_csv) → 自动解析 SQL 脚本，生成字段结构表格（含字段名、类型、主外键、说明等列）。 > ❗**重点提醒：字段说明这一列，是从你 SQL 中的 `COMMENT` 中读取的。** 换句话说：**你自己不写，工具没法帮你生成。** --- ## ✅ 如何在 SQL 中添加 COMMENT？ ```sql 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 图工具](https://schooltools.cn/tool/sql_er) — 用于生成结构图 - ➤ [SQL 转字段说明表工具](https://schooltools.cn/tool/sql_csv) — 用于生成字段结构文档 两者配合使用，图和表一次生成，补完字段说明，一份完整的系统文档就完成一大半了。