动态 API · 用户项目接入与鉴权说明（小白向）

本文用尽量好懂的方式，说明：天幕动态 API 是什么、四种「校验方式」分别怎么用、常见名词含义、试调要不要填 Token、用户业务项目如何对接。
适合：第一次接动态 API 的开发者、配置服务配置的管理员。
关联：服务配置-使用说明、自定义API-使用说明、运行面 SDK 使用文档

阅读建议

你是谁	建议先看
完全新手	第 2 章名词解释 → 第 4 章四种校验方式 → 第 11 章 FAQ
要配天幕控制台	第 4 章 + 第 8 章试调 + 服务配置页面
要写自己的后端	第 4 章选一种方式 + 第 5～7 章链路图 + 运行面 SDK 使用文档
已经 401 报错	直接看第 11 章 FAQ
JSON 列 / create 传 null / 天幕调用失败	第 11 章 FAQ 11.18～11.23

1. 一句话（先建立印象）

动态 API = 天幕根据你在「数据模型」里配置的表，自动生成的增删改查接口（不用自己写 Java 接口代码）。
你的 网站 / App 不要直接访问天幕地址，应通过 自己的后端服务（很多人叫 BFF）去访问。
打开 「启用运行时鉴权」 后，每次调用动态 API 都要带凭证（Token 或 API Key 等，取决于你选的校验方式）。
用户登录验一次（你的后端）+ 调天幕再验一次（平台）是正常的，验的不是同一件事。

2. 名词解释（遇到不懂的先翻这里）

2.1 架构相关

名词	通俗解释	常见对应
BFF	Backend For Frontend，专门给前端用的后端。前端只认 BFF 的地址，BFF 再去调数据库或其它系统。	您自建的 Node/Java 等业务 API 服务，例如本机 `http://localhost:4000`，提供 `/api/login`、`/api/products` 等。
前端	浏览器里的页面、小程序、App 界面。	用户直接访问的页面服务，例如本机 `http://localhost:5173` 或 `5174`（以您实际端口为准）。
运行面	对外真正干活的 HTTP 接口（给业务系统调），区别于管理员登录天幕控制台。	地址以 `/yc/dynamic-api/`、`/yc/custom-api/` 开头。
管理面 / 控制台	天幕网页后台：配数据模型、服务配置、试调 API。	您登录天幕低代码管理网站用的那一套。
项目 ID（`projectId`）	天幕里一个「应用 / 项目」的唯一编号，动态 API 地址里会带上它。	写在业务后端 `.env` 中，如 `YC_PROJECT_ID=...`。

2.2 鉴权相关

名词	通俗解释
鉴权	验证「你是谁 / 你有没有权限」，不是业务里的「查数据」本身。
认证	证明身份（登录成功）。
授权	证明你能做某件事（例如只能看自己的订单）。
401	HTTP 状态码：未授权。常见原因：没带 Token、Token 过期、密钥配错。
403	禁止访问。常见原因：IP 不在白名单、Token 范围不对。
启用运行时鉴权	服务配置里的总开关。打开后，运行面接口默认要凭证；关掉则谁都能调（非常不安全，仅适合本地临时调试）。

2.3 Token / JWT / 密钥

名词	通俗解释	类比
Token	一串字符，像临时通行证，证明你这次请求是合法的。	游乐园手环，有过期时间。
JWT	一种常见的 Token 格式（很长，中间有点号 `.` 分三段）。可以里面带上用户 id、过期时间等。	通行证上印着姓名和有效期。
Bearer	HTTP 里携带 Token 的写法：`Authorization: Bearer 后面贴Token`。	进门时说「这是我的通行证」。
JWT 签名密钥（`secret`）	签发和校验 JWT 用的密码本（配置在服务器上，不是每次请求手填的）。	游乐园制作手环的模具。
API Key	一段固定的秘密字符串，每次请求放在请求头里，一般不会过期（除非你在平台轮换）。	长期有效的门禁卡号。
接入密钥	平台生成的 `ycdk_...` 字符串，用来换短期 Token，只显示一次，要抄到你自己服务器的环境变量里。	去银行取号的凭条。
公钥 / 私钥（RSA）	一对钥匙：你用私钥签名，平台用公钥验证；私钥不能泄露。	你盖章，平台只认章的样式。

2.4 天幕相关

名词	通俗解释
动态 API	按数据模型自动发布的 REST 接口，如 `products` 列表、详情。
自定义 API	你在天幕里编排好的「自定义业务接口」，地址和动态 API 不同。
服务配置	菜单：服务器管理 → 服务配置，管鉴权、密钥、IP 白名单等。
数据模型	配表结构、发布 API、试调动态 API 的地方。
发布	把配置好的 API 推到「运行面」，外部才能按发布结果访问。
试调	在控制台里点按钮测接口是否正常；规则和真实对外可能略有不同（见第 8 章）。
跳过鉴权试调	仅控制台试调用的选项，带特殊请求头，不能当成对外正式方案。

2.5 请求相关（不用背，查表即可）

名词	放在哪	示例
请求头 Header	HTTP 请求的「附加信息」	`Authorization: Bearer eyJhbG...`
X-Access-Key	一种请求头名，用来传接入密钥	`X-Access-Key: ycdk_abc123`
X-Api-Key	一种请求头名，用来传 API Key	`X-Api-Key: 你的固定密钥`
环境变量（.env）	写在服务器配置文件里的密钥，不要提交到 Git 公开仓库	`JWT_SECRET=xxx`

2.6 接口路径（URL 如何区分 list / get / create）

标准 CRUD 默认用路径后缀区分不同操作，不再依赖「同一个 URL + 换 HTTP 方法」。

基础段：

text

/yc/dynamic-api/v1/{projectId}/{modelKey}

以 products 为例（{projectId} 换成你的项目 ID）：

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

你需要知道的：

请求方式可改：在「数据模型 → 发布 → 接口配置」里，每条接口可单独改「请求方式」（例如把详情改成 POST）。
路径可改：同一配置抽屉里可改「请求路径」；默认后缀 /list、/get 等便于识别，可按团队规范调整。
主键怎么传：/get、/update、/delete 请用查询参数 ?id=123 或请求体 { "id": "123" }；不再推荐 .../products/123 这种路径段（旧写法仍兼容）。
列表请求体：POST .../list 仍为 { "currentPage": 1, "pageSize": 20, "params": {} }。
在哪里看真实路径：数据模型 → 发布 → 接口配置表格的「路径」列，或 API 管理 列表；对外调用以发布结果为准。
历史配置：若你之前用的是 .../products（列表/创建）和 .../products/{id}（详情/更新/删除），重新打开发布配置时会自动迁移为后缀路径；已自定义过的路径不会被覆盖。

3. 签名密钥 vs Token（最容易混的两件事）

	JWT 签名密钥	Token（Bearer）
是什么	服务器保存的「密码本」	每次请求携带的「通行证字符串」
会不会每次变	一般不变（除非你主动轮换）	每次登录 / 换发都会变，且会过期
填在哪	天幕「服务配置」+ 你自己后端 `.env`	请求头 `Authorization: Bearer ...`
谁能看到	只有运维 / 后端配置人员	每次请求都会发（所以要 HTTPS）

记住：

服务配置里 「JWT 签名密钥留空 = 不修改已保存的密钥」，不是「这次不用带 Token」。
开启运行时鉴权后，真实调用必须带当前有效的 Token 或 Key（除非控制台试调勾选跳过）。

4. 四种「校验方式」详细说明

在 服务配置 → 动态 API 管控 → 校验方式 下拉框里，共有四项（见下图）。同一时间请只选一种作为主方式。

text

┌─────────────────────────────────────────┐
│ 平台凭证换 Token（推荐 BFF）              │
│ RSA 私钥签 JWT（推荐高安全）              │
│ 项目 JWT（与用户登录同密钥）              │
│ API Key（固定密钥）                       │  ← 你截图里当前选中
└─────────────────────────────────────────┘

4.0 先对比：一张表选方式

校验方式	难度	安全性	和用户登录关系	推荐场景
平台凭证换 Token	中	高	分开，互不影响	正式项目首选（有独立后端时）
RSA 私钥签 JWT	较高	很高	分开	安全要求高、有运维能力
项目 JWT	低	中	共用同一把签名密钥	演示、PoC、快速打通链路
API Key	最低	中低（泄露风险大）	分开	内网简单联调；密钥要能轮换

怎么选（小白版）：

已有 Node/Java 等业务后端（BFF） → 优先 平台凭证换 Token。
只是演示、已经和登录共用 JWT_SECRET → 用 项目 JWT。
公司要求非对称加密 → RSA。
临时测试、内网且能接受固定密码 → API Key（生产慎用）。

4.1 平台凭证换 Token（推荐 BFF）

一句话： 平台给你一把「接入密钥」；你的后端用它先换一张短期通行证（Token），再调商品等接口。

适合谁

有独立 BFF / 后端服务（推荐所有正式环境）。
希望：用户登录用的 JWT 和 调天幕用的凭证 不是同一个东西。

在天幕服务配置里要做的事

启用运行时鉴权 = 开。
校验方式 = 选 「平台凭证换 Token（推荐 BFF）」。
点击 「生成接入密钥」（或 RSA 旁的那个按钮，选接入密钥类型）。
页面上 只显示一次 的 ycdk_xxxxxxxx → 立刻复制到你自己服务器的配置文件（例如 .env 的 YC_PLATFORM_ACCESS_KEY）。
保存动态 API 鉴权配置。

在你的后端要做的事（两步请求）

第 1 步：换 Token

http

POST http://localhost:8081/yc/dynamic-api/v1/{你的projectId}/_auth/token
X-Access-Key: ycdk_你复制的接入密钥
Content-Type: application/json

{"ttlSeconds": 600}

成功会返回类似：

json

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 600
}

第 2 步：调业务接口

http

POST http://localhost:8081/yc/dynamic-api/v1/{projectId}/products/list
Authorization: Bearer 上一步的accessToken
Content-Type: application/json

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

路径后缀 /list 为当前默认约定；若在发布配置里改过路径或方法，以 API 管理 / 接口配置 中显示的为准。旧版 POST .../products（根路径）仍可用，见 §2.6。

业务后端应实现「换 Token + 缓存」（可先换 Token 再调业务接口）；您只需在服务器环境变量中配置 YC_PLATFORM_ACCESS_KEY。仓库附带的演示工程中有可参考实现。

优点 / 缺点

优点	缺点
用户 Token 不用给天幕，更安全	比「项目 JWT」多一步换 Token
接入密钥可轮换，Token 短期有效	要在后端安全保存 `ycdk_...`
适合生产	换 Token 接口也要保护 Access-Key

常见错误

现象	原因
换 Token 401	接入密钥错、没点「生成」、复制少了字符
调接口 401	用了用户登录的 JWT，但平台配的是「平台凭证」模式
Token 过期	正常，重新换 Token；检查 `expiresIn`

4.2 RSA 私钥签 JWT（推荐高安全）

一句话： 平台只保存公钥；你的后端用私钥自己签一张 JWT，每次请求带上；平台用公钥验证签名。

适合谁

对安全要求高，不希望天幕和你的后端共用同一段对称密码。
团队熟悉 RSA / JWT 签名库。

在天幕服务配置里要做的事

启用运行时鉴权 = 开。
校验方式 = 选 「RSA 私钥签 JWT（推荐高安全）」。
点击 「生成 RSA 密钥对」。
私钥 PEM 只显示一次 → 保存到服务器（环境变量 YC_CLIENT_RSA_PRIVATE_KEY 或密钥文件）。
公钥已由平台保存，无需你再填。
保存配置。

在你的后端要做的事

用私钥签发 JWT，大致要求（平台会校验）：

算法：RS256
载荷建议包含：sub = 你的 projectId，scope = dynamic:invoke，exp = 过期时间

请求时：

http

Authorization: Bearer 你用私钥签出来的JWT

业务后端在 .env 中配置 YC_CLIENT_RSA_PRIVATE_KEY 后，由服务端模块完成 RS256 签名即可；具体可参考仓库演示工程中的平台鉴权客户端实现。

优点 / 缺点

优点	缺点
私钥不在平台存，泄露面小	配置比 PROJECT_JWT 复杂
安全性高	私钥丢失只能重新生成密钥对
与用户登录 JWT 完全分离	后端要实现 RS256 签名

常见错误

现象	原因
401	私钥和平台公钥不是一对、scope/sub 不对、JWT 过期
签不出来	私钥 PEM 格式错（换行要用 `\n` 或真实多行）

4.3 项目 JWT（与用户登录同密钥）

一句话： 用户在你系统登录时拿到的 JWT，和调天幕时用的 JWT，用**同一把「签名密钥」**签发；平台也配这同一串密钥来验。

适合谁

演示、PoC、快速验证链路。
已经有一套用户登录 JWT，想少改代码。

签名密钥从哪来（重要）

平台不会发给你密钥。你要：

在业务后端 .env 里设定，例如：
JWT_SECRET=your-project-jwt-secret（生产请换成足够长的随机串）
把完全相同的一串填到天幕：服务配置 → JWT 签名密钥 → 保存。
若需在本地跑通完整链路，可参考运行面 SDK 使用文档 §4.5 中的环境变量对照，将 JWT_SECRET 与服务配置对齐。

两边必须一字不差，否则必 401。

在天幕服务配置里要做的事

启用运行时鉴权 = 开。
校验方式 = 「项目 JWT（与用户登录同密钥）」。
JWT 签名密钥 = 填与你的 JWT_SECRET 相同的值（已保存过可留空不改）。
保存。

在你的后端要做的事

用户登录后得到 token，调你自己的接口时带：

http

Authorization: Bearer 用户token

您的 BFF 调天幕时，应把同一枚用户 Token 再传给天幕（由动态 API 客户端模块转发 Authorization 头）。

优点 / 缺点

优点	缺点
配置最简单	用户 Token 直接进天幕，泄露影响大
和登录逻辑一致	用户 Token 过期，调天幕也会挂
上手快、改代码少	不适合作为长期生产最佳实践

常见错误

现象	原因
401	`JWT_SECRET` 和平台「JWT 签名密钥」不一致
登录成功但列表失败	调天幕时没带 Authorization
混淆	平台管理员登录天幕的 Token ≠ 业务用户 Token

4.4 API Key（固定密钥）

一句话： 像一把长期有效的密码，每次请求在请求头里带上同一个字符串；平台比对是否一致。

适合谁

内网、临时联调、非常简单的服务间调用。
不建议把 API Key 写进前端网页或手机 App（谁都能看见）。

在天幕服务配置里要做的事

启用运行时鉴权 = 开。
校验方式 = 「API Key（固定密钥）」。
在 「服务 API Key」 输入框填写你自己定义的强密码（或平台后续若提供「生成」则使用生成的）。
保存。

说明：密钥在平台侧会哈希存储，不会明文回显；再次修改需输入新 Key。

在你的后端要做的事

每次调天幕带上请求头（名称以平台配置为准，一般为）：

http

X-Api-Key: 你配置的同一个密钥

或使用 Bearer 方式传同一串（取决于安全方案配置，动态 API 默认常见为 X-Api-Key 方案名 ApiKey）。

优点 / 缺点

优点	缺点
实现最简单	泄露后长期有效，必须轮换
不用理解 JWT	没有自动过期（除非你自己换 Key）
适合脚本测试	不适合暴露给浏览器

常见错误

现象	原因
401	Key 不一致、请求头名错了（应是 `X-Api-Key`）
以为填 Key 就不用 Token	API Key 模式本来就没有「用户 Token」概念，只有固定 Key

4.5 四种方式对照总表（可打印）

项目	平台凭证换 Token	RSA 私钥签 JWT	项目 JWT	API Key
平台生成什么	`ycdk_` 接入密钥	公钥（私钥给你）	无（自备 secret）	无（自备 Key）
你服务器存什么	`YC_PLATFORM_ACCESS_KEY`	私钥 PEM	`JWT_SECRET`	固定 API Key
调接口前	先换 Token	先签 JWT	用登录 Token	直接带 Key
请求头典型写法	`Authorization: Bearer`	`Authorization: Bearer`	`Authorization: Bearer`	`X-Api-Key`
试调动态 API	填 Bearer 或跳过	填 Bearer 或跳过	填业务 JWT 或跳过	填 Api Key 或跳过

5. 总览：用户项目如何使用动态 API

mermaid

flowchart TB
    subgraph UserSide["用户侧"]
        Browser["浏览器 / 小程序 / App"]
    end

    subgraph YourProject["你的项目（BFF，如本机 :4000）"]
        BFF["业务 API\n/api/login、/api/products"]
        Auth["登录：签发用户 Token"]
        DynClient["调天幕：带平台或用户凭证"]
    end

    subgraph SkyCurtain["天幕平台 :8081"]
        SC["服务配置\n校验方式 + 密钥"]
        Filter["校验凭证"]
        Engine["查库返回数据"]
    end

    Browser -->|"① 登录"| BFF
    Browser -->|"② 业务请求"| BFF
    BFF -->|"③ 调动态 API"| Filter
    SC -.-> Filter
    Filter --> Engine

6. 为什么要「验两遍」？

第几遍	谁	验什么	小白理解
第 1 遍	你的 BFF	用户登录了吗？能看自己的数据吗？	你家大门的门禁
第 2 遍	天幕平台	这次调运行面的人，凭证合法吗？	天幕机房门口的安检

不是重复劳动：前端只应知道 BFF；天幕地址和平台密钥不应写在网页里。即使有人绕过前端直连天幕，没有第 2 遍凭证也应被拒绝。

7. 链路图（按校验方式）

7.1 项目 JWT（典型链路）

mermaid

sequenceDiagram
    participant U as 用户
    participant BFF as 你的 BFF
    participant P as 天幕动态 API

    U->>BFF: 登录
    BFF-->>U: 用户 Token
    U->>BFF: 查商品 + Bearer 用户Token
    BFF->>P: 调 products + 同一 Bearer
    P-->>BFF: 数据
    BFF-->>U: 商品列表

7.2 平台凭证换 Token（推荐）

mermaid

sequenceDiagram
    participant U as 用户
    participant BFF as 你的 BFF
    participant P as 天幕动态 API

    U->>BFF: 登录（用户 Token 只留在 BFF）
    BFF->>P: X-Access-Key 换 Token
    P-->>BFF: 短期 accessToken
    BFF->>P: 调 products + Bearer 平台Token
    P-->>BFF: 数据
    BFF-->>U: 结果

8. 管理台「试调」要不要填 Token？

8.1 动态 API（数据模型 → 试调动态 API）

你的操作	要不要填 Token
勾选「跳过鉴权试调」	不用填（仅控制台生效，对外不能用这招）
不勾选，且配了项目 JWT	要在 Bearer Token 框填：用户登录拿到的 JWT（不要加 `Bearer` 前缀）
不勾选，且配了 API Key	试调鉴权选「服务调用」，填 API Key
不勾选，且配了平台凭证 / RSA	填对应的 Bearer（或先按文档换 Token / 签名）

默认 没勾选跳过 且 开了鉴权 时，不填会 401——说明鉴权已生效，不是坏了。

8.2 自定义 API 试调

控制台试调会自动加 X-Custom-Api-Debug-Skip-Auth: 1，一般不用你填 Token。
要测「真实对外要不要 Token」，请用 Postman 或你自己的后端，按自定义API-使用说明测。

9. 服务配置 vs 数据模型（各管什么）

你想改什么	去哪里
开不开鉴权、四种校验方式、生成接入密钥	服务配置
这个接口匿名还是必须登录、返回哪些字段	数据模型 → 发布配置
表有哪些列、发布 API	数据模型

10. 业务后端环境变量对照

典型三层链路（端口以您本地为准）：

text

业务前端 → 业务后端（BFF）→ 天幕运行面(8081) → 业务数据库

配置项	示例值	含义
`JWT_SECRET`	与平台 JWT 签名密钥一致	用户登录 + 项目 JWT 校验方式时用
`YC_PLATFORM_ACCESS_KEY`	`ycdk_...`	平台凭证换 Token 时用
`YC_USE_DYNAMIC_API`	`1`	业务数据走天幕动态 API，而非 BFF 直连库
`YC_PROJECT_ID`	天幕项目 ID	拼在动态 API URL 中

手把手配置与验收：见运行面 SDK 使用文档与本文第 4、10 章。

11. 常见问题（FAQ · 小白加强版）

11.1 我是小白，从哪里开始？

读本文第 2 章名词、第 4 章选一种校验方式。
按本文第 4 章选一种校验方式，并对照运行面 SDK 使用文档配置业务后端（建议先用 项目 JWT 试通）。
跑通后若要上线，再改成 平台凭证换 Token。

11.2 BFF 是什么？我能不能不要 BFF？

BFF = 给前端用的后端，前端只调 http://你的后端/api/...。
动态 API 不要直接写在前端代码里（密钥、projectId 会暴露）。
没有 BFF 也要有一个只在服务器上跑的程序去调天幕，角色等同于 BFF。

11.3 四种校验方式可以混用吗？

同一时间只选一种作为主校验方式。
业务后端可同时支持多种实现：若配置了 YC_PLATFORM_ACCESS_KEY 则优先用平台凭证换 Token，否则可走用户 JWT（以您代码逻辑为准，生产建议只保留一种主方式）。

11.4 JWT 签名密钥是固定的吗？Token 呢？

签名密钥：配置在服务器上，通常几个月不变，轮换时要两边一起改。
Token：每次登录变，几分钟到几天过期，过期要重新登录或重新换 Token。

11.5 我选了 API Key，还要填 JWT 签名密钥吗？

不用。 选 API Key 时，填 服务 API Key 即可；JWT 签名密钥那一项是给 项目 JWT 用的。

11.6 我选了项目 JWT，还要点「生成接入密钥」吗？

不用。 那是「平台凭证换 Token」用的。项目 JWT 只需保证 JWT_SECRET 与平台「JWT 签名密钥」一致。

11.7 开启鉴权后，试调一定要 Token 吗？

见第 8 章：可勾选「跳过鉴权试调」；要模拟真实用户则填 Token。

11.8 浏览器里能看到 Token，安全吗？

用户登录 Token 在浏览器里是常见做法，但要 HTTPS，且不要把平台接入密钥 / API Key / 私钥放前端。
ycdk_、JWT_SECRET、RSA 私钥 只能放在服务器。

11.9 为什么 Postman 能调通，网页却 401？

Postman 可能带了 Token 或 Key，网页请求没带。
或网页调的是 BFF，BFF 调天幕时没转发凭证。
或校验方式和凭证类型不一致（见 4.5 对照表）。

11.10 报错 401，我该怎么排查？（按顺序）

服务配置是否 启用运行时鉴权？
校验方式和下端用的是否一致（项目 JWT vs 平台凭证 vs API Key）？
PROJECT_JWT：JWT_SECRET 与平台 JWT 签名密钥是否完全一致（无空格、无换行）？
Token 是否过期？重新登录或重新换 Token。
请求头是否写了 Authorization: Bearer xxx（Bearer 后有空格）？
API Key 是否用的 X-Api-Key 头？
改完服务配置是否 重启了天幕后端（yc_user_service）？
是否误把 天幕管理员登录 的 Token 当成业务 Token？

11.11 报错 500，提示不允许的查询字段？

发布配置里 「查询参数字段」 没勾选的列，不能作为筛选条件传；或参数名要用驼峰（与全局命名一致）。
试调模板里多填的空字段会被平台自动忽略（需较新版本）。

11.12 为什么业务系统返回的字段比平台试调多？

平台试调：只返回你在发布配置里勾选的 返回字段。
业务后端：常在接口层做字段映射、补默认值（例如空字符串），返回给前端的 JSON 会比试调结果更「满」，属正常业务封装，不是平台多给了字段。

11.13 没开鉴权，别人也能访问我的动态 API？

能。所以生产环境务必：启用运行时鉴权 + 选一种凭证方式 + 可选 IP 白名单。

11.14 动态 API 和自定义 API 是一套密码吗？

不是。 自定义 API 有单独的「接入密钥」和换 Token 地址（/custom-api/v1/...）。
动态 API 用服务配置里 动态 API 管控 的校验方式。两套要分别配置。

11.15 用户没登录，BFF 能调天幕吗？

项目 JWT：一般不能，没有合法用户 Token。
平台凭证 / API Key / RSA：可以，这是服务器到服务器的凭证，和用户是否登录无关；但仍要在 BFF 里做好「未登录用户不允许查数据」的业务判断。

11.16 `projectId` 在哪里看？

天幕项目 → 服务配置 安全概览里有 项目 ID，或浏览器地址栏 /project/一串字符/... 里那串字符。

11.17 修改校验方式后，旧 Token 还能用吗？

从 项目 JWT 改成 平台凭证 后，旧的用户 JWT 天幕可能不再认。
轮换接入密钥或 API Key 后，旧的 Key/Token 会失效。
改完配置建议 重启平台后端 再测。

11.18 create / update 时 JSON 列怎么传？

动态 API 对模型里 fieldType 为 JSON 的字段，在写入数据库前会自动规范化：

请求体传 JSON 数组或对象（推荐），例如图集字段 images: ["url1","url2"]。
也可传 已是合法 JSON 的字符串（以 [ 或 { 开头）。
无需在发布配置里单独勾选；也不必在业务 BFF 里先 JSON.stringify（若 BFF 已序列化，平台会识别并原样写入）。

典型报错：

text

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

排查顺序：

数据模型：该列 JSON 类型、fieldType 含 JSON → 数据模型 FAQ 10.7。
重启 yc_user_service 并对模型 重新发布。
控制台 试调 create，body 用数组写法；通过后再调 BFF。
仍失败：核对 BFF 是否把 images 传成 Buffer/错误编码字符串。

详见数据模型 §5.4。

11.19 create 时传 `null` 报「字段不能为空」？

典型场景："published_at": null、"deleted_at": null 等可空时间字段。

典型报错：

text

字段不能为空: published_at

处理（优先平台 + 配置，不必改业务 Server）：

运行面：新版本 create 将 值为 null 的键视为未传 → 重启 yc_user_service + 重新发布 模型。
配置：create 可写字段 不要勾 published_at；或 全局排除字段 加入 published_at；字段元数据可空。
审核流：发帖 create 只写 status（如待审）；审核通过时用 update 写 published_at。
patch/update 仍可用 null 将列置为 NULL（与 create 不同）。

详见数据模型 §5.5 · 数据模型 FAQ 10.8。

11.20 BFF 日志里「天幕动态 API 调用失败」怎么查？

业务后端常把运行面错误包一层，例如：

text

天幕动态 API 调用失败: 字段不能为空: published_at
天幕动态 API 调用失败: Cannot create a JSON value from a string with CHARACTER SET 'binary'

建议排查：

看冒号后的原文（平台 ValidationException / JDBC 信息）。
用 同一 projectId、同一 modelKey 在控制台 试调 create，区分是平台问题还是 BFF 组包问题。
对照本 FAQ：11.18（JSON）、11.19（null 字段）、11.10（401）、11.11（查询字段）。
确认 YC_BASE_URL 指向 yc_user_service（如 http://localhost:8081/yc），不是 sky-curtain 前端地址。
SDK 捕获异常时查看 platform / YcRuntimeException 原始 JSON（见 SDK §8）。

11.21 联调动态 API 时推荐检查哪些？

序号	检查项
1	`yc_user_service` 已启动（常见 8081），改引擎后已重启
2	数据模型目标表已发布 / 重新发布
3	`YC_PROJECT_ID`、modelKey 与 API 管理一致
4	鉴权：服务配置校验方式与 BFF 的 `YC_ACCESS_KEY` / JWT 一致；本地可临时 `YC_INVOKE_SKIP_AUTH=1`
5	create 试调：JSON 列用数组；可空日期字段不传或依赖新版 null→未传
6	list 试调：`params` 键在查询参数字段白名单内
7	通过试调后再测 BFF；BFF 改代码后需重启业务后端

11.22 能否只靠改业务 BFF，不改天幕？

不推荐长期如此。 下列问题应优先在 运行面 + 数据模型发布配置 解决：

问题	平台侧
JSON 列 binary 报错	升级并重启 `yc_user_service`；字段类型 JSON；试调用数组
create 传 null 报不能为空	create 省略 null 键；可写字段排除该列
敏感列被写入	全局排除 / 可写字段白名单

BFF 临时 JSON.stringify 或 omit 字段仅作过渡；文档与引擎以平台为准。
业务自有接口（非动态 API）的 404，见 SDK FAQ §12。

11.23 动态 API 试调成功，业务前端仍失败？

现象	常见原因
前端 401	未登录或 BFF 未转发用户 JWT；对比 Postman 是否带 Token
前端 404	调错地址（应调业务 BFF，不是 `8081` 动态 API 直连）
数据不一致	BFF 缓存、或 list 的 `params` 与试调不一致（如 `status` 筛选）
发帖成功但发现流没有	业务规则：待审 `status=2` 未展示；须管理端审核为已发布

12. 推荐阅读顺序

本文（名词 + 四种校验方式 + FAQ）
服务配置-使用说明.md（控制台能力说明）
运行面 SDK 使用文档（业务后端 env 与调用示例）
自定义API-使用说明.md（自定义 API 控制台与 BFF 对接）

修订记录

版本	日期	说明
v1.0	2026-05-22	初版
v1.1	2026-05-22	小白向：名词表、四种校验方式详解、FAQ 扩充
v1.2	2026-05-22	全文改用通用表述，不再使用内部演示工程代号作名词
v1.3	2026-05-22	路径后缀约定：/list、/get、/create、/update、/delete；主键 ?id=；兼容旧 URL
v1.4	2026-05-26	FAQ 11.18：JSON 列 create/update 入参约定与 binary 报错排查
v1.5	2026-05-26	FAQ 11.19：create 显式 null 与 published_at 配置说明
v1.6	2026-05-26	FAQ 扩充 11.18～11.23：JSON、null、天幕调用失败、联调清单、BFF 与平台分工

动态 API · 用户项目接入与鉴权说明（小白向） ​

阅读建议 ​

1. 一句话（先建立印象） ​

2. 名词解释（遇到不懂的先翻这里） ​

2.1 架构相关 ​

2.2 鉴权相关 ​

2.3 Token / JWT / 密钥 ​

2.4 天幕相关 ​

2.5 请求相关（不用背，查表即可） ​

2.6 接口路径（URL 如何区分 list / get / create） ​

3. 签名密钥 vs Token（最容易混的两件事） ​

4. 四种「校验方式」详细说明 ​

4.0 先对比：一张表选方式 ​

4.1 平台凭证换 Token（推荐 BFF） ​

适合谁 ​

在天幕服务配置里要做的事 ​

在你的后端要做的事（两步请求） ​

优点 / 缺点 ​

常见错误 ​

4.2 RSA 私钥签 JWT（推荐高安全） ​

适合谁 ​

在天幕服务配置里要做的事 ​

在你的后端要做的事 ​

优点 / 缺点 ​

常见错误 ​

4.3 项目 JWT（与用户登录同密钥） ​

适合谁 ​

签名密钥从哪来（重要） ​

在天幕服务配置里要做的事 ​

在你的后端要做的事 ​

优点 / 缺点 ​

常见错误 ​

4.4 API Key（固定密钥） ​

适合谁 ​

在天幕服务配置里要做的事 ​

在你的后端要做的事 ​

优点 / 缺点 ​

常见错误 ​

4.5 四种方式对照总表（可打印） ​

5. 总览：用户项目如何使用动态 API ​

6. 为什么要「验两遍」？ ​

7. 链路图（按校验方式） ​

7.1 项目 JWT（典型链路） ​

7.2 平台凭证换 Token（推荐） ​

8. 管理台「试调」要不要填 Token？ ​

8.1 动态 API（数据模型 → 试调动态 API） ​

8.2 自定义 API 试调 ​

9. 服务配置 vs 数据模型（各管什么） ​

10. 业务后端环境变量对照 ​

11. 常见问题（FAQ · 小白加强版） ​

11.1 我是小白，从哪里开始？ ​

11.2 BFF 是什么？我能不能不要 BFF？ ​

11.3 四种校验方式可以混用吗？ ​

11.4 JWT 签名密钥是固定的吗？Token 呢？ ​

11.5 我选了 API Key，还要填 JWT 签名密钥吗？ ​

11.6 我选了项目 JWT，还要点「生成接入密钥」吗？ ​

11.7 开启鉴权后，试调一定要 Token 吗？ ​

11.8 浏览器里能看到 Token，安全吗？ ​

11.9 为什么 Postman 能调通，网页却 401？ ​

11.10 报错 401，我该怎么排查？（按顺序） ​

11.11 报错 500，提示不允许的查询字段？ ​

11.12 为什么业务系统返回的字段比平台试调多？ ​

11.13 没开鉴权，别人也能访问我的动态 API？ ​

11.14 动态 API 和自定义 API 是一套密码吗？ ​

11.15 用户没登录，BFF 能调天幕吗？ ​

11.16 projectId 在哪里看？ ​

11.17 修改校验方式后，旧 Token 还能用吗？ ​

11.18 create / update 时 JSON 列怎么传？ ​

11.19 create 时传 null 报「字段不能为空」？ ​

11.20 BFF 日志里「天幕动态 API 调用失败」怎么查？ ​

11.21 联调动态 API 时推荐检查哪些？ ​

11.22 能否只靠改业务 BFF，不改天幕？ ​

11.23 动态 API 试调成功，业务前端仍失败？ ​

12. 推荐阅读顺序 ​

修订记录 ​

动态 API · 用户项目接入与鉴权说明（小白向）

阅读建议

1. 一句话（先建立印象）

2. 名词解释（遇到不懂的先翻这里）

2.1 架构相关

2.2 鉴权相关

2.3 Token / JWT / 密钥

2.4 天幕相关

2.5 请求相关（不用背，查表即可）

2.6 接口路径（URL 如何区分 list / get / create）

3. 签名密钥 vs Token（最容易混的两件事）

4. 四种「校验方式」详细说明

4.0 先对比：一张表选方式

4.1 平台凭证换 Token（推荐 BFF）

适合谁

在天幕服务配置里要做的事

在你的后端要做的事（两步请求）

优点 / 缺点

常见错误

4.2 RSA 私钥签 JWT（推荐高安全）

适合谁

在天幕服务配置里要做的事

在你的后端要做的事

优点 / 缺点

常见错误

4.3 项目 JWT（与用户登录同密钥）

适合谁

签名密钥从哪来（重要）

在天幕服务配置里要做的事

在你的后端要做的事

优点 / 缺点

常见错误

4.4 API Key（固定密钥）

适合谁

在天幕服务配置里要做的事

在你的后端要做的事

优点 / 缺点

常见错误

4.5 四种方式对照总表（可打印）

5. 总览：用户项目如何使用动态 API

6. 为什么要「验两遍」？

7. 链路图（按校验方式）

7.1 项目 JWT（典型链路）

7.2 平台凭证换 Token（推荐）

8. 管理台「试调」要不要填 Token？

8.1 动态 API（数据模型 → 试调动态 API）

8.2 自定义 API 试调

9. 服务配置 vs 数据模型（各管什么）

10. 业务后端环境变量对照

11. 常见问题（FAQ · 小白加强版）

11.1 我是小白，从哪里开始？

11.2 BFF 是什么？我能不能不要 BFF？

11.3 四种校验方式可以混用吗？

11.4 JWT 签名密钥是固定的吗？Token 呢？

11.5 我选了 API Key，还要填 JWT 签名密钥吗？

11.6 我选了项目 JWT，还要点「生成接入密钥」吗？

11.7 开启鉴权后，试调一定要 Token 吗？

11.8 浏览器里能看到 Token，安全吗？

11.9 为什么 Postman 能调通，网页却 401？

11.10 报错 401，我该怎么排查？（按顺序）

11.11 报错 500，提示不允许的查询字段？

11.12 为什么业务系统返回的字段比平台试调多？

11.13 没开鉴权，别人也能访问我的动态 API？

11.14 动态 API 和自定义 API 是一套密码吗？

11.15 用户没登录，BFF 能调天幕吗？

11.16 `projectId` 在哪里看？

11.17 修改校验方式后，旧 Token 还能用吗？

11.18 create / update 时 JSON 列怎么传？

11.19 create 时传 `null` 报「字段不能为空」？

11.20 BFF 日志里「天幕动态 API 调用失败」怎么查？

11.21 联调动态 API 时推荐检查哪些？

11.22 能否只靠改业务 BFF，不改天幕？

11.23 动态 API 试调成功，业务前端仍失败？

12. 推荐阅读顺序

修订记录