JSON 转 UTS 模型生成器

更新记录

1.0.1（2026-07-15）下载此版本

多层数组会递归生成类型和每层转换函数。数组中的 null 元素会原样保留。字段缺失改为可选字段，默认对象和转换结果不会自动补 null。名称冲突会自动生成唯一字段名、类型名和函数名。特殊字段使用安全字段名及 @JSON_FIELD，符合 UTS 官方规则。

1.0.0（2026-06-15）下载此版本

支持在 HBuilderX 项目文件夹右键，从 JSON 生成 UTS 模型文件。
支持标准 JSON 和 HBuilderX 控制台 UTSJSONObject 日志结构。
支持 JSON 实时校验、错误提示和格式化。
生成默认值函数与 UTSJSONObject 转换函数。

平台兼容性

HbuilderX/cli最低兼容版本
3.9.0

HBuilderX插件通用注意事项

HBuilderX-2.7.12以下版本安装插件市场内的插件后，卸载时需手动卸载，详细教程参考：如何手动卸载插件

# JSON 转 UTS 模型生成器

这是一个 HBuilderX 插件，用来把 JSON 数据生成 uni-app x 可用的 UTS 数据模型文件。

插件支持两种 JSON 输入：

标准 JSON，例如接口文档里的返回示例。
HBuilderX 控制台打印出来的 JSON 结构，例如带有 // [UTSJSONObject]、// [number] 这类类型注释的日志。

插件信息

插件 id：wuts-model-generator
插件名称：JSON 转 UTS 模型生成器
最低 HBuilderX 版本：3.9.0
入口菜单：JSON 转 UTS 模型：生成模型文件
推荐搜索标签：utsJson JSON转UTS模型 JSON生成模型 UTS数据模型接口数据模型

使用步骤

在 HBuilderX 中打开需要生成模型文件的项目。
在项目管理器里，右键点击要保存模型文件的文件夹。
点击菜单里的 JSON 转 UTS 模型：生成模型文件。

在弹窗中填写 模型 name，例如 Ceshi、LoginResult、UserInfo。
把接口返回 JSON 或 HBuilderX 控制台 JSON 日志粘贴到 详细 JSON 输入框。
如果 JSON 是压缩在一行里的，可以点击 格式化 JSON。
当 JSON 合规时，输入框下方会显示绿色提示，并且 生成 按钮可以点击。
当 JSON 不合规时，输入框会显示红框和错误提示，生成 按钮会保持不可用。

创建模型弹窗

生成结果

插件会在右键选中的文件夹下生成一个 .uts 文件。

例如填写：

生成目录：/api
模型 name：Ceshi

最终会生成：

/api/Ceshi.uts

生成的文件中包含：

export type Ceshi = { ... }
createCeshi()：创建默认数据。
createCeshiFromJson(json : UTSJSONObject | null)：把 uni.request 返回的 UTSJSONObject 转成 Ceshi。
createCeshiArrayFromJson(list : Array<UTSJSONObject> | null)：把 UTSJSONObject 数组转成 Array<Ceshi>。

类型推断规则

插件会检查数组中的全部样例，不会只根据第一条数据生成类型。

字段缺失

字段缺失和字段值为 null 是两种不同状态。例如：

[
    { "id": 1, "name": "张三" },
    { "id": 2 }
]

name 会生成可选属性：

export type RootItem = {
    id: number
    name?: string | null
}

第二条数据转换后仍然只有 id，插件不会自动添加 name: null。只有原始 JSON 明确包含 "name": null 时，才会保留这个 null 值。

多层数组和可空数组元素

插件会递归生成多层数组中的对象类型。数组元素明确为 null 时，会生成类似 Array<UserItem | null> 的类型，并在转换时保留 null 元素。

特殊字段名

当 JSON 字段包含连字符、运算符、UTS 保留字或其他非法字符时，插件会生成合法字段名和 @JSON_FIELD 注释。例如 a+b 会转换为 a_b，class 会转换为 _class。

如果多个字段转换后名称相同，插件会自动生成不重复的字段名和类型名，避免 UTS 编译时出现重复定义。

空数组

空数组没有元素样例，插件无法判断真实元素类型，因此会生成 Array<any>。建议输入至少一条完整的数组元素样例。

页面中使用

在 .uvue 页面中，不要直接把 UTSJSONObject 写成 res as Ceshi，因为运行时对象还是 UTSJSONObject，不能直接强转成自定义 type。

应该使用插件生成的转换函数：

import { createCeshi, createCeshiFromJson, type Ceshi } from '@/api/Ceshi.uts'

const loginData = ref<Ceshi>(createCeshi())

uni.request({
    url: '接口地址',
    method: 'POST',
    data: {}
}).then((res : any) => {
    const full = createCeshiFromJson(res as UTSJSONObject)
    loginData.value = full
})