Skip to content

序列化#

当处理函数返回 Go 对象时，它们将被序列化为字节以传输回客户端。

默认格式#

config.Formats 将内容类型名称或扩展名（后缀）映射到 huma.Format 实例。

Huma 的默认配置包括对 JSON (RFC 8259) 和可选的 CBOR (RFC 7049) 内容类型的支持，通过 Accept 头部实现。这是通过使用 huma.DefaultJSONFormat 注册以下内容类型来完成的：

  • application/json
  • 以 +json 结尾的任何内容

可以通过导入 cbor 包来启用 CBOR 支持，这会将 cbor.DefaultCBORFormat 添加到默认格式列表中：

main.go
import (
    "github.com/danielgtaylor/huma/v2"

    _ "github.com/danielgtaylor/huma/v2/formats/cbor"
)

这会添加以下内容类型：

  • application/cbor
  • 以 +cbor 结尾的任何内容

其他格式

您可以轻松添加对其他序列化格式的支持，包括像 Protobuf 这样的二进制格式，如果需要的话。

自定义格式#

Huma 通过实现 huma.Format 接口来支持自定义序列化格式。序列化格式在 API 创建时设置在 API 配置上，并通过客户端驱动的内容协商 进行选择。

编写新格式可以非常简单，只需提供 marshal 和 unmarshal 函数：

code.go
var DefaultJSONFormat = Format{
	Marshal: func(w io.Writer, v any) error {
		return json.NewEncoder(w).Encode(v)
	},
	Unmarshal: json.Unmarshal,
}

内容协商#

内容协商允许客户端在与 API 交互时选择他们最舒适的内容类型。对于请求体，这使用 Content-Type 头部。对于响应体，它使用 Accept 头部。如果没有指定，则通常选择 JSON 作为默认/首选内容类型。

Terminal
# 使用 Restish 发送 YAML 作为输入
$ echo 'foo: bar' | \
	restish put api.rest.sh -H 'Content-Type:application/yaml'

# 从 API 获取 CBOR 输出
$ restish api.rest.sh -H 'Accept:application/cbor'
HTTP/2.0 200 OK
Content-Length: 318
Content-Type: application/cbor
Etag: O7fTqWETqWI
...

有关更多信息，请参阅 negotiation 包。

深入了解#