企业官网建设流程全解析

Django Builder JSON项目描述规范完整指南：一次搞懂项目、App、模型与关系的全部配置

【免费下载链接】django_builderDjango Builder Site项目地址: https://gitcode.com/gh_mirrors/dj/django_builder

Django Builder 是一款用 JSON 文件描述即可生成完整 Django 项目的开源工具。这篇文章作为 Django Builder JSON 项目描述规范的参考，带你一次搞懂项目（Project）、App、模型（Model）与关系（Relationship）的全部配置：从 4 个配置层级，到每个字段选项，再到一条命令打包出可运行的项目 🚀

Django Builder 编辑器：上方可视化配置 App 与模型，下方即时生成 models.py、views.py、forms.py

一、JSON 规范的 4 层结构

整个规范非常清晰，只有 4 层嵌套：

完整的数据结构定义可参考类型声明文件 types.ts 和核心实现 api.ts。

二、第一层：项目级配置

项目层位于 JSON 根节点，控制"生成什么样的项目"：

一个最简项目只有一项配置即可运行，仓库提供了两个现成样例：

• 基础版：example-project.json
• PostgreSQL 版：example-project-postgres.json

三、第二层：App 与模型

apps是一个数组，每个 App 对应生成项目里的一个应用目录：

{ "name": "DjangoProject", "description": "A Django Project with great potential", "htmx": false, "postgres": false, "apps": [ { "name": "DjangoApp1", "models": [ /* 模型定义放这里 */ ] } ] }

每个 App 下的models数组就是数据库模型的"图纸"。每个模型除了name，还包含两个核心数组：

• fields—— 普通数据字段
• relationships—— 外键等关系字段

四、第三层：字段（fields）怎么配

添加字段：Name + Field Type + args 三要素，与 models.py 中的写法一一对应

每个字段由 3 个属性组成：

常用字段类型（完整清单见 api.ts）：

CharField·TextField·BooleanField·IntegerField·DecimalField·DateField·DateTimeField·EmailField·URLField·SlugField·UUIDField·JSONField·ImageField…

当项目启用postgres: true时，还可以使用 PostgreSQL 专属类型：ArrayField、HStoreField、CICharField、DateTimeRangeField等区间字段（范围类字段会标记is_postgres_range）。

💡小技巧：args里写editable=False的字段会被识别为只读字段，不会出现在生成的表单里——样例文件中的created/last_updated时间戳字段就是这么实现的。

五、第三层：关系（relationships）怎么配

添加关系：支持 ForeignKey、OneToOneField、ManyToManyField 三种类型

关系配置在结构上与字段类似，多了一个to指明"指向谁"：

to目前支持指向 Django 内置模型，内置模型清单定义在 api.ts 的BuiltInModelTypes中：

• auth.User/auth.AbstractUser/auth.AbstractBaseUser/auth.Group

⚠️ 注意：to引用的必须是内置模型或已定义模型，否则渲染时会抛出Unsupported relationship to ...错误——这是新手最常踩的坑。

六、一条命令：JSON → 可运行项目

配置完成后，用 CLI 的render命令即可打包出完整项目。解析逻辑在 cli.ts 中实现：

./bin/django-builder example_projects/example-project.json DjangoProject.tar tar -xvf DjangoProject.tar cd DjangoProject pip install -r requirements.txt python manage.py migrate && python manage.py runserver

生成的项目包含完整的 views、forms、urls、admin、序列化器、REST API 和 pytest 测试：

同一份 JSON 描述，自动渲染出的 API 路由、序列化器、管理后台与测试文件

生成的 Python 代码由模板渲染，核心模板位于 models.ts，模板机制实现在 rendering.ts。

七、进阶：把现有 models.py 导入规范

如果你已有写好的 Django 模型，ModelImporter可以解析models.py源码并还原成规范的模型结构（识别字段类型、外键关系、Meta.abstract等），实现在 importer.ts —— 也就是说，这套 JSON 规范既能"由 JSON 生成代码"，也能作为"代码到结构"的中间表示。

八、常见问题速查

Q1：字段类型写错会怎样？渲染时直接报错Unsupported field type XXX，请对照FieldTypes清单检查拼写（短名即可，如CharField而非django.db.models.CharField）。

Q2：args里参数之间怎么分隔？用英文逗号分隔，如null=True,on_delete=models.CASCADE，它会原样嵌入生成的models.py，语法即 Django 标准写法。

Q3：为什么生成的是 tar 包而不是目录？Renderer.tarballContent()先打包再输出，解压后即可运行，天然适合 CI 与模板分发场景。

总结

Django Builder 的 JSON 规范本质是一张项目蓝图：

1. 项目层声明技术选型（Django 版本、HTMX、PostgreSQL、Channels）；
2. App 层划分应用边界；
3. 模型层用fields+relationships两张表描述数据结构；
4. 一条render命令，蓝图变成可运行的完整 Django 工程。

掌握这 4 层结构后，无论是手工编写还是程序化生成配置，你都能快速驾驭这个"声明式 Django 脚手架"。

【免费下载链接】django_builderDjango Builder Site项目地址: https://gitcode.com/gh_mirrors/dj/django_builder