Skip to content

JSON Schema 与注册表

JSON 架构#

使用默认的 Huma 配置（或通过 huma.SchemaLinkTransformer 手动配置），每个资源操作都会返回一个 describedby HTTP 链接关系头，该头引用一个 JSON Schema 文件。这些架构使用 config.SchemasPath 来提供其内容。例如：

HTTP Response
Link: </schemas/Note.json>; rel="describedby"

对象资源（即非数组或简单标量）也可以选择性地返回一个带有此类链接的 $schema 属性，这使得 described-by 关系能够超出 HTTP 请求的生命周期（例如，将正文保存到文件以供后续编辑），并使一些编辑器如 VSCode 在您输入时提供代码补全和验证。

response.json
{
	"$schema": "http://localhost:8888/schemas/Note.json",
	"title": "I am a note title",
	"contents": "Example note contents",
	"labels": ["todo"]
}

接受对象作为输入的操作将忽略 $schema 属性，因此可以安全地将数据提交回 API，即“往返”数据。

编辑

$schema 字段与 Restish 的 edit 命令结合使用时非常强大，它为您提供了一种快速简便的方式，在您喜欢的编辑器中编辑强类型资源。

架构注册表#

Huma 使用一个可自定义的注册表来跟踪从 Go 结构体生成的所有架构。这用于避免多次生成相同的架构，并提供一种通过名称引用架构的方法，用于 OpenAPI 操作和托管的 JSON Schema。

默认的架构实现使用 map 来按名称存储架构，这些名称从 Go 类型名称中生成（不包含包名称）。这支持递归架构，并生成像 Thing 或 ThingList 这样的简单名称。

架构名称

请注意，默认注册表**不**支持不同包中具有相同名称的多个模型。例如，添加 foo.Thing 和 bar.Thing 将导致冲突。您可以通过定义一个新类型如 type BarThing bar.Thing 并使用它来解决此问题，或者使用自定义 注册表命名函数。

自定义注册表#

您可以通过实现 huma.Registry 接口并在创建 API 时将其设置到 config.OpenAPI.Components.Schemas 上，来创建具有自定义行为的注册表。

深入了解#