将 SQLAlchemy 模型 转换为 JSON!

输入 SQLAlchemy 模型,即可生成示例 JSON!支持 SQLAlchemy ORM。适用于 API 文档和测试请求体(sample JSON)。
SQLAlchemy
结果
 

将 SQLAlchemy 模型 转换为 JSON!

粘贴 SQLAlchemy 模型类,就能得到以列属性名为 key 的示例 JSON。它能读取 2.0 风格的 Mapped[...] 配合 mapped_column()、1.x 风格的 Column() 以及 Flask-SQLAlchemy 的 db.Column(),并合并来自 mixin 和父类的列。

SQLAlchemy 模型无法直接传给 json.dumps,所以 FastAPI 和 Flask 应用会另外编写 Pydantic 或 Marshmallow schema。在写 schema 之前,可以用它梳理模型会暴露哪些字段,或者为测试构造请求体。

使用方法

  1. 把模型文件粘贴到 SQLAlchemy 框中。Base、mixin 和 enum.Enum 类请放在同一个输入里,这样继承的列和 enum 值才能解析。
  2. 只有带 __tablename__ 的类才算模型。多个模型会按类名输出,如 { "User": {...}, "Team": {...} }。
  3. 复制结果。

示例

输入 (Python · Flask-SQLAlchemy)
class TimestampMixin:
    created_at = db.Column(db.DateTime, default=datetime.utcnow)


class Plan(enum.Enum):
    FREE = "free"
    PRO = "pro"


class Subscription(TimestampMixin, db.Model):
    __tablename__ = "subscriptions"

    id = db.Column(db.Integer, primary_key=True)
    plan = db.Column(db.Enum(Plan), nullable=False)
    seats = db.Column(db.SmallInteger, default=1)
    trial_ends = db.Column(db.Date)
    user_id = db.Column(db.Integer, db.ForeignKey("users.id"))
    user = db.relationship("User", backref="subscriptions")
输出 (JSON)
{
  "created_at": "1970-01-01T00:00:00",
  "id": 0,
  "plan": "free",
  "seats": 1,
  "trial_ends": "1970-01-01",
  "user_id": 0
}

来自 TimestampMixin 的 created_at 按继承顺序排在最前面,user 因为 relationship() 不是列而被去掉。db.Enum(Plan) 取 enum 的第一个值 "free",db.Date 变成 1970-01-01。seats 根据 default=1 显示 1,而 datetime.utcnow 是函数,所以 created_at 保留占位值。

支持的功能

  • Mapped[int]、Mapped[Optional[str]]、Mapped[str | None] 等 Python 类型提示决定值。
  • 没有类型提示时,由 SQL 类型参数决定,如 Column(String(50)) 或 db.Column(db.Numeric)。
  • DateTime → 1970-01-01T00:00:00,Date → 1970-01-01,Time → 00:00:00,JSON/JSONB → {},Uuid → 全零的 UUID。
  • ARRAY(String) 和 Mapped[list[str]] 变成单元素数组。
  • 继承 enum.Enum 的类,通过 Enum(Plan) 或 Mapped[Plan] 使用时,取第一个成员的值。
  • relationship()、column_property()、普通类变量以及 __table_args__ 这类双下划线属性都会被排除。
  • 来自 mixin 和父模型的列排在子类自己的列之前。

使用场景

起草 Pydantic 响应模型

在为 FastAPI 的 response_model 编写 Pydantic 类之前,先确认模型以 JSON 暴露的字段和类型。把这份 JSON 交给 JSON 转 Python 页面,还能得到 Pydantic 的草稿。

Flask API 的测试 payload

用与模型属性一致的 key 构造 client.post("/subscriptions", json=...) 的请求体。先去掉自增的 id 和创建时间。

注意事项与限制

  • 字面量形式的 default=("new"、1、True、None)会用作示例值;datetime.utcnow 或 dict 这样的可调用对象不会被执行。server_default= 和 nullable= 不会被读取。
  • 如果列另外指定了数据库名,比如 Column("user_name", String),JSON key 仍然是 Python 属性名。
  • 不包含通过 relationship 加载的关联对象。如果响应中嵌入了它们,请自行添加嵌套对象。
  • hybrid_property 或 @property 这类计算属性不会出现在输出中。

常见问题

为什么 Mapped[Optional[str]] 是空字符串而不是 null?

Optional 表示允许 None;示例展示的是有值的情况,所以使用内部的 str。如果需要那种情况,请在输出中改成 null。

为什么日期时间没有 Z 或时区偏移?

DateTime 列默认是 naive 的,isoformat() 输出时不带偏移。如果使用 DateTime(timezone=True),带 +00:00 的示例更接近实际情况。

能转换 Django 模型吗?

不能。本页只理解 SQLAlchemy 的 Column、mapped_column 和 Mapped 语法,models.CharField 这样的 Django 字段无法识别。