Schema 动态字段

受众：开发者摘要：Schema / Dynamic Field 字段定义、校验规则和渲染元数据底座。

spring-open-starter-schema 提供跨 Form、商户入驻、Install 配置、Plugin 配置等场景复用的动态字段底座。它只负责字段定义、校验和渲染元数据，不承载业务提交流程，也不创建数据库表。 Form 平台已在后端字段保存和公开提交校验中复用 Schema starter；Payment Platform 商户入驻已提供后台字段 Schema contract 并在 Admin 详情页复用动态字段渲染；Install 配置已提供安装配置字段 Schema contract 并由安装页消费；Plugin 配置已把插件描述符里的 configKeys 映射为后台只读配置字段 Schema。

Maven 依赖

xml

<dependency>
    <groupId>com.springopen</groupId>
    <artifactId>spring-open-starter-schema</artifactId>
</dependency>

自动配置类由 SchemaServiceProvider.configure(...) 声明，并交给 lifecycle starter 在 Spring Boot 自动配置导入阶段统一汇总。普通 starter 不再手写 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports。

配置前缀

yaml

spring:
  open:
    schema:
      enabled: true

代码中使用 PropertyPrefixes.SCHEMA 维护配置前缀，避免业务模块手写字符串。

字段结构

核心模型是 SchemaFieldDefinition：

key：字段唯一标识。
label：展示名称，未配置时使用 key。
type：字段类型。
required：是否必填。
description：字段说明。
defaultValue：默认值。
options：选项型字段的候选项。
validationRules：声明式校验规则。
render：前端渲染元数据。
metadata：业务扩展元数据。

字段类型覆盖文本、数字、布尔、单选、多选、日期时间、评分、文件、图片和 JSON 等常见动态表单场景。

已接入场景

Form 平台：字段定义保存前校验 Schema 定义，公开提交时校验 Schema 值；App / PC 公开填写页使用动态字段组件渲染。
Payment Platform 商户入驻：后台 GET /api/v1/admin/payment-platform/merchants/onboarding-schema 输出商户资料字段 Schema，Admin 商户详情抽屉使用 SchemaDynamicField 只读展示字段值。
Install 配置：GET /api/v1/install/config/schema 输出站点、管理员、数据库、Redis 和 Storage 字段 Schema，安装页消费 label / description / required / options，接口不返回配置值或敏感默认值。
Plugin 配置：GET /api/v1/admin/plugins/{id}/config/schema 输出插件描述符 configKeys 映射出的只读字段 Schema，Admin 插件详情抽屉使用 SchemaDynamicField 展示配置声明；当前不读取或回显配置值。

校验规则

内置规则包括：

REQUIRED
MIN_LENGTH / MAX_LENGTH
MIN / MAX
PATTERN
EMAIL / URL
ENUM
MIN_ITEMS / MAX_ITEMS

校验结果通过 SchemaValidationResult 返回，包含 SchemaValidationIssue 列表。业务模块可以在保存配置、预览表单、提交答案前调用 SchemaManager.validateDefinition(...) / SchemaManager.validateValues(...) 做统一校验。

渲染元数据

SchemaRenderMetadata 描述跨端渲染提示：

component：推荐控件类型。
placeholder：占位文案。
helpText：辅助说明。
group：分组或步骤标识。
order：组内排序。
width：布局宽度提示。
hidden / readonly / disabled：基础交互状态。
props：控件扩展属性。

这些元数据是提示而不是业务授权来源。服务端仍应在提交或保存时重新校验字段可见性、必填和类型约束。

渲染 contract

业务模块需要把 Schema 输出给 Admin / PC / App 渲染时，优先调用 SchemaManager.render(...)：

SchemaManager.render(SchemaDefinition) 返回 SchemaRenderDefinition。
SchemaRenderDefinition.groups() 按 render.group 分组，未配置时归入 default。
组和字段默认按 render.order 升序排列；未配置 order 时保留字段定义顺序。
默认过滤 render.hidden=true 字段，避免普通填写页渲染后台隐藏字段。
设计器、预览器等需要显示隐藏字段时，使用 SchemaRenderRequest.includeHidden(schema)。

render(...) 只做字段展示队列整理，不替代提交校验、权限判断、条件显示和业务状态判断。

前端组件

三端已经提供可复用动态字段组件：

端	入口
Admin	`views/admin/src/components/SchemaField/SchemaDynamicField.vue`
PC	`views/pc/app/components/schema/SchemaDynamicField.vue`
App	`views/app/src/components/SchemaField/SchemaDynamicField.vue`

PC 与 App 同时提供 schema-field helper，用于解析旧 Form 字段结构和新 Schema 字段结构：

PC：views/pc/app/types/schema-field.ts
App：views/app/src/services/schema-field.js

helper 兼容 questionType、optionsJson、validationJson，也兼容新的 type、options、validationRules、render。后续业务页面接入时应优先复用这些 helper，不再在页面内复制选项解析、分步、可见性和文件答案展示逻辑。

边界

Schema starter 不依赖业务模块。
Schema starter 不持久化字段定义。
动态字段组件不直接调用业务 API。
业务模块仍负责表单版本、提交记录、配置来源、权限和审计。

Schema 动态字段 ​

Maven 依赖 ​

配置前缀 ​

字段结构 ​

已接入场景 ​

校验规则 ​

渲染元数据 ​

渲染 contract ​

前端组件 ​

边界 ​