数据模型 · 使用说明（小白向）

本文说明：服务器管理 → 数据模型 怎么用——建表元数据、配关系、发布动态 API、试调。
适合：业务配置、实施、对接开发。
关联：连接配置-使用说明 · 服务配置-使用说明 · 动态API-用户项目接入与鉴权说明

阅读建议

你是谁	建议先看
从零建表	第 4 章上手 → 第 5 章发布
库里已有表	第 5.1 从数据源同步
主子表 / 关联	第 6 章关系
对外调接口	第 7 章路径 + 动态 API 接入文档
JSON 列 / create 传 null 报错	第 10 章 FAQ 10.7～10.12

1. 一句话

数据模型 = 在平台里描述「业务库有哪些表、哪些字段、表之间什么关系」；
点发布后，系统自动生成一组 动态 API（list / get / create / update / delete），不用手写 Java Controller。

text

连接配置 → 数据模型（元数据）→ 发布 → 动态 API 运行面

2. 名词解释

名词	说明
物理表名	数据库里真实表名，如 `products`
modelKey	运行面 URL 里的模型标识，默认=表名，可配 `api_path` 别名
主键	至少一个字段勾选主键；建议自增 ID
发布	把配置推到运行面，外部才可调用
重新发布	字段/关系/发布配置变更后刷新运行时快照
下线	注销路由，外部不可再调
发布配置	每条接口的路径、方法、返回字段、鉴权等
出站关联	本表作为「源」指向其它表的关系，影响 include / 关联接口
试调	控制台内发真实 HTTP，看 JSON 返回

3. 入口与视图

路径：项目 → 服务器管理 → 数据模型

常见视图：

视图	用途
表格	模型列表、字段维护、发布/试调入口
关系图	拖拽连线配置 1:1 / 1:N / N:1 / N:N

相关菜单：API 管理（汇总已发布接口）、连接配置（绑定数据源）。

4. 五分钟上手

步骤 1：准备连接

按连接配置-使用说明建好并激活一条连接。

步骤 2：新建或同步模型

方式 A — 从库同步（库里已有表）

从数据源同步 → 选连接 → 勾选表 → 确认。
平台拉取字段类型、主键等到元数据。

方式 B — 手工新建（新表）

新建模型 → 填模型名、物理表名。
绑定数据源（必选已激活连接）。
在字段 Tab 添加列：字段名、类型、是否主键、是否自增等。

步骤 3：检查主键

至少一个主键字段；整型自增最省事。无主键无法可靠 get/update/delete。

步骤 4：发布 API

点击 发布 API（或 重新发布）。
在 发布配置 弹窗中确认接口列表（见第 7 章默认路径）。
确认发布。
记下提示的基础路径，如 /yc/dynamic-api/v1/{projectId}/products。

步骤 5：试调

列表行调试，或 API 路由 查看路径 → 填写参数 → 发送。
若项目开了鉴权，试调可 跳过鉴权 或填 Token（见服务配置 / 动态 API 文档）。

5. 字段与表结构

5.1 字段常用属性

属性	说明
字段名	与库列名一致（同步时自动带出）
类型	varchar、int、datetime 等
主键	勾选主键；多主键按产品规则
自增	整型主键可勾自增
可空 / 默认值	与 DDL 一致
注释	便于 API 管理展示

5.2 同步表结构到物理库

若元数据比库新（加了列、改了类型），可用 同步表结构：

会补列、MODIFY 已有列，不删库中多余列。
主键类型变更（如 varchar → 自增 int）前请确认无脏数据。
操作前阅读确认弹窗说明。

5.3 全局命名策略

发布配置里 全局命名策略：

策略	API 字段风格
snake_case	`user_id`
camelCase	`userId`

影响 list 的 params、返回 JSON 字段名；切换后「分页列表」请求体模板会重生成。

5.4 JSON 类型字段（图集、扩展属性等）

从数据源同步或手工建字段时，若数据库列类型为 JSON（如 MySQL JSON），平台会在元数据里标记 fieldType = JSON。

创建 / 更新时的入参约定（运行面自动处理，无需额外配置）：

请求体写法	平台行为
JSON 数组，如 `["https://a.jpg","https://b.jpg"]`	自动序列化为合法 JSON 字符串再写入库
JSON 对象，如 `{"tags":["a","b"]}`	同上
已是 JSON 字符串，如 `"[\"https://a.jpg\"]"`	校验格式后原样写入
普通字符串（非 JSON 文本）	按 JSON 字符串字面量写入（加引号转义）

说明：

这是运行面引擎能力，不是发布弹窗里的单独开关；只要字段类型为 JSON 即生效。
读取（list / get）时，驱动一般会把 JSON 列解析为对象或字符串返回，与 JDBC 实现有关。
若业务服务（BFF）在调动态 API 之前已把数组转成 JSON 字符串，同样兼容。
旧版本若出现 Cannot create a JSON value from a string with CHARACTER SET 'binary'，请 重新发布模型 并 升级/重启 yc_user_service 后再试。

示例（create 请求体片段）：

json

{
  "title": "游记",
  "content": "正文",
  "images": [
    "https://cdn.example.com/1.jpg",
    "https://cdn.example.com/2.jpg"
  ]
}

images 对应表字段 images（JSON 类型）时，可直接传数组，不必手动 JSON.stringify。

5.5 create 时「显式传 null」与可空字段

现象：业务 BFF 调用 create 时若写入 "published_at": null，可能报错 字段不能为空: published_at。

原因（运行面规则）：

请求体里 带了字段名且值为 null，平台原先按「显式传空」校验；若该字段在模型中不可空或未配默认值，则拒绝写入。
与数据库列 DEFAULT NULL 无矛盾，是 动态 API 写入语义 问题。

平台能力（运行面已实现，无需业务改代码）：

create：请求体中值为 null 的键在写入前会被丢弃，等同「未传该字段」；不可空列可再走模型默认值或库表默认。
patch / update：仍保留 null 语义，便于将列更新为 NULL。

纯配置建议（与引擎能力叠加，推荐）：

场景	天幕控制台操作
发布时间仅审核通过时写入	`user_post` → 发布配置 → create → 可写字段不勾选 `published_at`；或加入全局排除字段
审核流字段	`status` 可写；`published_at` 由 update 或管理端改状态时再写
字段元数据	`published_at` 勾选可空，默认值留空或 `NULL`

配置路径：服务器管理 → 数据模型 → 选中模型 → 发布 / 重新发布 → 各接口「配置」。

6. 模型关系（多表）

6.1 何时需要配关系？

需求	建议
详情页嵌套子对象	配 1:1 / N:1 / 1:N，详情 `?include=`
查某用户下所有订单	推荐：直接调子表 POST 分页，`params` 写外键
列表每行带关联	❌ 单接口不支持；用 API 编排或前端两次请求
一次写多表	❌ 单接口不支持；用 API 编排顺序 create

6.2 关系类型

类型	含义	详情 include 返回
1:1	一对一	嵌套对象
N:1	多对一	嵌套对象
1:N	一对多	嵌套数组
N:N	多对多	需配中间表三字段

N:N 中间表字段：中间表名、指向源主键列、指向目标主键列。

6.3 配置步骤

关系图视图：从源表拖线到目标表。
选类型、外键字段（源字段 → 目标字段）。
主表、子表分别 发布 API。
发布弹窗 出站关联 区核对目标表是否 已发布。

6.4 关联接口（可选）

发布时可为出站关系生成 关联类接口（如关联列表、绑定、解绑），路径含 /relations/{关联名}/；试调时注意 JSON 里填 本表主键 id。

7. 发布配置详解

7.1 默认接口与路径（当前版本）

基础段：/yc/dynamic-api/v1/{projectId}/{modelKey}

接口	默认路径后缀	默认方法
分页列表	`/list`	POST
按主键详情	`/get`	GET
创建	`/create`	POST
全量更新	`/update`	PUT
删除	`/delete`	DELETE

示例（products 表）：

text

POST .../products/list          ← 分页，body: currentPage, pageSize, params
GET  .../products/get?id=1      ← 详情
POST .../products/create        ← 创建
PUT  .../products/update?id=1   ← 全量更新
DELETE .../products/delete?id=1 ← 删除

路径、方法均可改：点接口行配置 → 改「请求路径」「请求方式」。

主键传递：/get、/update、/delete 用 ?id= 或 body { "id": "..." }（不再推荐 .../products/{id} 路径段；旧版仍兼容）。

7.2 发布弹窗配置项

配置	说明
全局命名策略	snake_case / camelCase
全局排除字段	所有接口不可见/不可写，如 `password`
接口启用	至少勾选一个
返回字段	list / get：限制返回列
可写字段	create / update：限制写入列
查询参数字段	list：允许出现在 body.params 的键
请求体模板	list 分页 JSON 示例
单接口鉴权	inherit / none 等（项目级鉴权在服务配置）

7.3 接口行操作

按钮	作用
配置	改名称、方法、路径、字段、请求头
调试	已发布模型内试调（须先发布）

7.4 重新发布 / 下线 / 批量

操作	何时用
重新发布	改字段、关系、发布配置后
下线 API	临时停服该模型所有接口
批量发布	多模型一起发布（若入口提供）

8. POST 分页列表示例

http

POST /yc/dynamic-api/v1/{projectId}/products/list
Content-Type: application/json
Authorization: Bearer <凭证>

{
  "currentPage": 1,
  "pageSize": 20,
  "params": {
    "status": "1",
    "name": ""
  }
}

params 空字符串字段一般不作为过滤条件。
键名须与 命名策略、查询参数字段 白名单一致。

9. API 管理与路由

API 管理：查看项目下所有已发布动态 API、自定义 API 汇总。
API 路由（模型行内）：查看 Method + 完整路径。
对外调用以 发布配置里保存的 path 为准。

10. 常见问题（FAQ）

10.1 发布按钮灰了？

检查：是否绑定数据源、是否有主键、连接是否已激活。

10.2 试调 401？

项目开了鉴权 → 试调填 Token 或勾选跳过；或查服务配置-使用说明。

10.3 试调 404 / 未匹配路径？

是否已发布 / 重新发布。
URL 是否含正确后缀（如 /list）。
modelKey 是否与表名 / api_path 一致。

10.4 返回字段比库表少？

发布配置 返回字段 做了白名单；空=全部可读字段（受全局排除影响）。

10.5 改了发布配置，外部仍旧行为？

须 重新发布 才会更新运行时快照。

10.6 include 不生效？

仅详情类接口支持 ?include=。
目标模型须 已发布。
关系名与发布说明一致。

10.7 创建时报 JSON / binary 相关错误？

典型报错：

text

Cannot create a JSON value from a string with CHARACTER SET 'binary'

原因：MySQL 列为 JSON 类型，但运行面把 Java List/Map 等对象按错误字符集绑定进 JDBC，或 BFF 传了未规范化的二进制串。

处理（优先平台，不必改业务库表）：

数据模型中该字段 fieldType 含 JSON（从库同步一般会自动识别）。
create/update 请求体对 JSON 列直接传 数组或对象，例如 images: ["https://..."]（见 §5.4）。
升级并重启 yc_user_service（运行面 DynamicApiJdbcValueHelper 会自动 JSONUtil 序列化）。
对该模型 重新发布。
控制台 试调 create 用数组写法复现；通过后再测 BFF。

业务 BFF 不必再手写 JSON.stringify；若已序列化为合法 JSON 字符串（以 [ 或 { 开头），平台也会识别。

更多说明：动态 API FAQ 11.18。

10.8 create 时传 `published_at: null` 报「字段不能为空」？

典型报错：

text

字段不能为空: published_at

或 BFF 日志：天幕动态 API 调用失败: 字段不能为空: published_at

原因：请求体里 带了字段名且值为 null。旧版运行面按「显式传空」校验；若模型里该字段不可空或未配默认值，则拒绝。与数据库 DEFAULT NULL 不矛盾。

处理（推荐组合，无需改业务 Server 代码）：

步骤	操作
1	重启 `yc_user_service`（新版本 create 会把值为 `null` 的键视为未传，见 §5.5）
2	对该模型重新发布
3	发布配置 → create → 可写字段：不要勾选 `published_at`（发布时间应在审核通过时用 update 写入）
4	或把 `published_at` 加入全局排除字段
5	字段元数据：`published_at` 勾选可空，默认值留空

注意：patch / update 仍可用 null 将列更新为 NULL；与 create 行为不同。

详见动态 API FAQ 11.19。

10.9 可写字段、全局排除、返回字段分别管什么？

配置项	作用接口	效果
全局排除字段	读 + 写	所有接口不可见/不可写该列（如 `password`）
可写字段	create / update	白名单；未勾选的列即使 body 里有也会被跳过
返回字段	list / get	白名单；空表示全部可读列（仍受全局排除影响）
查询参数字段	list	允许出现在 `body.params` 的筛选键

典型场景：发帖 create 可写 title、images、status，不可写 published_at；审核通过 时在 update 可写 status、published_at。

10.10 内容审核流（待审 / 已发布）怎么配字段？

以「用户发帖 → 管理端审核 → 发现流展示」为例（表如 user_post）：

阶段	建议字段值	配置要点
用户发帖 create	`status = 2`（审核中），不写 `published_at`	create 可写字段含 `status`，不含 `published_at`
管理端通过	`status = 1`，写入 `published_at`	update 可写字段含 `status`、`published_at`
发现流 list	只查 `status = 1`	list 查询参数字段允许 `status`

列表筛选键名须与 命名策略（snake_case / camelCase）及白名单一致。

10.11 升级运行面或改了引擎后，试调仍像旧行为？

重启 yc_user_service（本地默认端口常为 8081）。
在数据模型对涉及表 重新发布（刷新运行时快照）。
再用控制台调试或 Postman 调 create，确认 JSON / null 行为已更新。
最后测业务 BFF；BFF 未重启不会自动获得平台侧修复。

见服务配置 FAQ 10.6。

10.12 业务 BFF 是否还要为 JSON、可空日期写特殊逻辑？

一般不需要（在运行面已升级并重新发布的前提下）：

JSON 列：直接传数组/对象给动态 API create / update。
可空日期（如 published_at）：create 时不要传，或传 null（新版本视为未传）；审核后再 update。

若暂时无法升级运行面，可临时在 BFF 做 JSON.stringify 或 omit published_at，但长期应 以平台配置 + 运行面能力为准。
SDK 侧错误对照见运行面 SDK · §8.1 · §12 联调 FAQ。

11. 推荐阅读顺序

修订记录

版本	日期	说明
v1.0	2026-05-22	初版；含路径后缀 /list、/get 等约定
v1.1	2026-05-26	新增 JSON 字段 create/update 自动序列化说明（§5.4、FAQ 10.7）
v1.2	2026-05-26	新增 create 时 null 视为未传、可写字段配置说明（§5.5）
v1.3	2026-05-26	FAQ 扩充：JSON/binary、published_at、可写字段、审核流、运行面升级（§10.7～10.12）

数据模型 · 使用说明（小白向） ​

阅读建议 ​

1. 一句话 ​

2. 名词解释 ​

3. 入口与视图 ​

4. 五分钟上手 ​

步骤 1：准备连接 ​

步骤 2：新建或同步模型 ​

步骤 3：检查主键 ​

步骤 4：发布 API ​

步骤 5：试调 ​

5. 字段与表结构 ​

5.1 字段常用属性 ​

5.2 同步表结构到物理库 ​

5.3 全局命名策略 ​

5.4 JSON 类型字段（图集、扩展属性等） ​

5.5 create 时「显式传 null」与可空字段 ​

6. 模型关系（多表） ​

6.1 何时需要配关系？ ​

6.2 关系类型 ​

6.3 配置步骤 ​

6.4 关联接口（可选） ​

7. 发布配置详解 ​

7.1 默认接口与路径（当前版本） ​

7.2 发布弹窗配置项 ​

7.3 接口行操作 ​

7.4 重新发布 / 下线 / 批量 ​

8. POST 分页列表示例 ​

9. API 管理与路由 ​

10. 常见问题（FAQ） ​

10.1 发布按钮灰了？ ​

10.2 试调 401？ ​

10.3 试调 404 / 未匹配路径？ ​

10.4 返回字段比库表少？ ​

10.5 改了发布配置，外部仍旧行为？ ​

10.6 include 不生效？ ​

10.7 创建时报 JSON / binary 相关错误？ ​

10.8 create 时传 published_at: null 报「字段不能为空」？ ​

10.9 可写字段、全局排除、返回字段分别管什么？ ​

10.10 内容审核流（待审 / 已发布）怎么配字段？ ​

10.11 升级运行面或改了引擎后，试调仍像旧行为？ ​

10.12 业务 BFF 是否还要为 JSON、可空日期写特殊逻辑？ ​

11. 推荐阅读顺序 ​

修订记录 ​

数据模型 · 使用说明（小白向）

阅读建议

1. 一句话

2. 名词解释

3. 入口与视图

4. 五分钟上手

步骤 1：准备连接

步骤 2：新建或同步模型

步骤 3：检查主键

步骤 4：发布 API

步骤 5：试调

5. 字段与表结构

5.1 字段常用属性

5.2 同步表结构到物理库

5.3 全局命名策略

5.4 JSON 类型字段（图集、扩展属性等）

5.5 create 时「显式传 null」与可空字段

6. 模型关系（多表）

6.1 何时需要配关系？

6.2 关系类型

6.3 配置步骤

6.4 关联接口（可选）

7. 发布配置详解

7.1 默认接口与路径（当前版本）

7.2 发布弹窗配置项

7.3 接口行操作

7.4 重新发布 / 下线 / 批量

8. POST 分页列表示例

9. API 管理与路由

10. 常见问题（FAQ）

10.1 发布按钮灰了？

10.2 试调 401？

10.3 试调 404 / 未匹配路径？

10.4 返回字段比库表少？

10.5 改了发布配置，外部仍旧行为？

10.6 include 不生效？

10.7 创建时报 JSON / binary 相关错误？

10.8 create 时传 `published_at: null` 报「字段不能为空」？

10.9 可写字段、全局排除、返回字段分别管什么？

10.10 内容审核流（待审 / 已发布）怎么配字段？

10.11 升级运行面或改了引擎后，试调仍像旧行为？

10.12 业务 BFF 是否还要为 JSON、可空日期写特殊逻辑？

11. 推荐阅读顺序

修订记录