go-openapi/strfmt 全解：用 Go 类型支撑 JSON Schema / OpenAPI 字符串格式的校验与序列化

strfmt 是 go-openapi 工具链（swagger 代码生成与校验体系）中负责"字符串格式"的类型注册表与实现库，它为 OpenAPI（swagger 2.0）与 JSON Schema 定义的 hostname、email、date-time、uuid、ipv4 等格式分别提供强类型、可校验、可序列化的 Go 数据类型。阅读本文后，你将掌握 strfmt 的格式体系与两个注册表的设计差异、各类型在 JSON/SQL/BSON 三条通道上的工作方式，以及如何在 MySQL、MongoDB 等真实场景中规避已知坑点。

strfmt 是什么：go-openapi 生态里的"字符串格式运行时"

在 OpenAPI / JSON Schema 规范中，字符串（string）除了普通文本外还承载着大量语义格式，例如 "2024-06-15T12:30:45Z" 是 date-time、"192.0.2.1/24" 是 cidr、"01:02:03:04:05:06" 是 mac。go-openapi/strfmt 的职责正是把这些"格式"翻译成 Go 语言中一个个具名类型，并把它们注册到统一的注册表中。

用项目 README 的原话来说：

• 该包向 go-openapi 工具链暴露了一个 数据类型注册表（registry of data types），用于支持各种字符串格式；
• strfmt 本身代表一个"广为人知的字符串格式"，例如 hostname 或 email；
• 该包还额外提供了若干实用格式，如美国信用卡号（credit card）、颜色（color）等；
• 每个格式类型既能完成 JSON 的序列化与反序列化，也能与 SQL 数据库交互；
• BSON（MongoDB）同样受支持。

它严格遵循 swagger 2.0 规范对 format 的定义，并且声明 API 已经稳定（Status: API is stable）。需要特别说明的是：该包只处理字符串格式，不会为 JSON Schema 中 number/integer 类型（如 float、double、int32 等）提供数值校验。

在 Moby（moby）仓库中，该库被 vendored 在 vendor/github.com/go-openapi/strfmt 下，顶层 go.mod 以 v0.27.0 的版本将其列为间接依赖（indirect），属于 go-openapi API 代码生成/校验工具链的一部分。

安装与最小使用

在你的 Go 项目中引入该库：

go get github.com/go-openapi/strfmt

之后可以直接使用包内暴露的两个注册表与全套类型：

package main

import (
	"fmt"

	"github.com/go-openapi/strfmt"
)

func main() {
	// 每个格式类型都实现了 Validate 方法（通过注册表校验）
	var email strfmt.Email = "[e-mail]"
	fmt.Println(strfmt.Default.Validates(&email)) // true

	var hostname strfmt.Hostname = "registry-1.docker.io"
	fmt.Println(strfmt.IsHostname(hostname.String())) // true
}

说明：go-openapi 生成的模型代码（swagger-gen 产物）一般并不直接调用注册表，而是由模型携带的 Validate(formats strfmt.Registry) 方法在解码/业务校验阶段统一调用注册表完成格式确认，详见下文"在 API 生成代码中的角色"。

支持的字符串格式全览

strfmt 兼容 swagger 2.0 规范，并在此基础上为 go-openapi 用户扩展了大量便利格式。下表按 README 的分类完整列出。

JSON Schema draft 4 定义的标准格式

格式	说明	典型取值
date-time	带时区的日期时间	1970-01-01T00:00:00Z
email	电子邮件地址	[e-mail]
hostname	主机名	www.example.com
ipv4	IPv4 地址	192.168.1.1
ipv6	IPv6 地址	2001:db8::1
uri	URI 统一资源标识符	https://example.com/a

swagger 2.0 的 format 扩展

格式	说明	典型取值
binary	二进制载荷	任意二进制
byte	Base64 编码的字节串（标准 RFC 4648 字母表，非 base64url）	aGVsbG8=
date	仅日期	1970-01-01
password	密码（见 register.go，校验函数恒返回 true，只作标记）	任意字符串

go-openapi 自定义扩展格式

格式	说明	典型取值
bsonobjectid	MongoDB ObjectID	24 位十六进制串
creditcard	美国主要卡种信用卡号	4111111111111111
duration（别名 duration-human）	人类可读时长	3 weeks、1ms
hexcolor	十六进制颜色	#FFFFFF
isbn / isbn10 / isbn13	图书国际标准书号	0-306-40615-2
mac	48 位 MAC 地址	01:02:03:04:05:06
rgbcolor	RGB 颜色函数写法	rgb(100,100,100)
ssn	美国社会安全号	123-45-6789
uuid / uuid3 / uuid4 / uuid5 / uuid7	各版本 UUID	550e8400-e29b-41d4-a716-446655440000
cidr	无类别域间路由记法	192.0.2.1/24、2001:db8:a0b:12f0::1/32
ulid	字典序可排序的全局唯一标识	00000PP9HGSBSSDZ1JTEXBJ0PW

其中 uuid3/4/5 与 uuid7 分别遵循 RFC 9562 对应版本定义，ulid 遵循 ulid 规范。

JSON Schema draft 2020 新增格式

格式	说明	典型取值
duration-iso8601	ISO 8601 时长表示	P2W

另外，从 register.go 的初始化代码可以看出，注册表中实际还挂载了 README 未单列的几个类型键位：date、datetime、ulid、bsonobjectid、currency（货币，ISO 4217）、country（国家，ISO 3166）。后两者的数据源位于 internal/countries，以 iso3166.json 为内置字典。

已实现的具名类型清单

README 明确列出的导出类型共 20 余种，按源码文件分布在 default.go、date.go、duration.go、ulid.go 等文件中：

Base64、CreditCard、Date、DateTime、Duration、DurationISO8601 与泛型策略类型 ISODuration[P ISODurationPolicy]、Email、HexColor、Hostname、IPv4、IPv6、CIDR、ISBN、ISBN10、ISBN13、MAC、ObjectId、Password、RGBColor、SSN、URI、UUID、UUID3、UUID4、UUID5、UUID7、ULID，以及注册表中出现的 Currency、Country。

注册表机制：Default 与 JSONSchema2020Registry

strfmt 把"格式名 → (类型实例, 校验函数)"的映射关系集中管理在注册表中，代码中的核心数据结构与两个全局实例都定义在 register.go：

// Default 是默认格式注册表。
// 注意：默认情况下格式 "duration" 被映射到 "duration-human"。
var Default Registry

// JSONSchema2020Registry 是带 JSON Schema draft 2020 格式的注册表
// （其中 duration 指 ISO 8601 时长）。
var JSONSchema2020Registry Registry

两者的差异全部集中在 duration 这个格式名指向谁 上：

• Default 注册表：把 duration 映射为人类可读的 duration-human（例如 "1 ms"），这是 strfmt 长期以来的既有行为。由于 Swagger 2.0 本来就没有定义 duration 格式，因此这样的默认映射不构成破坏性变更，与历史实现保持对齐；
• JSONSchema2020Registry 注册表：把 duration 映射为 ISO 8601 时长 duration-iso8601。

从 register.go 可以看到第二个注册表并非从零注册，而是通过 NewSeededFormats(def.data, JSONSchema2020Normalizer) 以 Default 的数据为基础做"规范化重映射"而来。

此外，README 强调了一个容易踩坑的设计原则：

关于 duration 格式存在两种截然不同的定义：曾经只叫 "duration" 的"人类可读"时长，以及新增的 "duration-iso8601"。不存在同时接受两种格式的"双模解析器"——类型是专门化的。因此引入了新别名 duration-human（如 "1 ms"），与 duration-iso8601 明确区分。

每个格式的注册还附带了校验器，例如 register.go 中展示的模式：

eml := Email("")
Default.Add("email", &eml, IsEmail)

hn := Hostname("")
Default.Add("hostname", &hn, IsHostname)

uid4 := UUID4("")
Default.Add("uuid4", &uid4, IsUUID4)

也就是说注册表 Add(name, base, validator) 接受三个参数：格式名、作为空值模板的类型实例、以及对应的 func(string) bool 校验函数。运行时校验动作实际上委托给这些顶层函数，例如 IsEmail、IsHostname、IsUUID4、IsDate、IsDuration 等，它们大多定义在 default.go、date.go、duration.go 中，也可以脱离注册表直接当作普通布尔函数使用。

格式类型的"三位一体"能力：JSON / 文本 / SQL

README 指出，strfmt 中定义的所有类型都实现了 database/sql 的 sql.Scanner 与 driver.Valuer 接口，因此可以直接配合 Go 标准库 database/sql 及任何 SQL 驱动开箱即用。每个类型身上通常同时挂着三组方法（以 URI 类型 为例，同目录下 Base64、Email、Hostname、IPv4、IPv6、MAC 等实现方式几乎完全一致）：

• 文本编解码：MarshalText / UnmarshalText（encoding.TextMarshaler）；
• JSON 编解码：MarshalJSON / UnmarshalJSON（encoding/json）；
• SQL 存取：Scan(raw any) error 与 Value() (driver.Value, error)，其中 Scan 同时接受 []byte 与 string 两种来源；
• 拷贝辅助：DeepCopyInto / DeepCopy，服务于 swagger-gen 生成的模型树。

JSON 序列化与反序列化的过程也会顺带做解码层级的检查。以 Base64（对应 OpenAPI 的 format: byte，即标准 RFC 4648 +/ 字母表而非 base64url）为例，其 JSON 反序列化先解码 base64、解码失败即返回错误，而字符串的语义校验则放在后续校验阶段（源码注释 validation is performed later on）。

底层校验器的演进值得关注

与常见的"正则匹配"实现不同，本版本 strfmt 在 default.go 中用注释明确标注了旧正则常量的弃用（如 HostnamePattern、UUIDPattern 均标为 Deprecated）：

• hostname 校验：不再使用正则。新实现 IsHostname 遵循 WHATWG URL 规范的主机解析规则，并结合 IDNA 支持国际化域名（Unicode TLD）：空串非法、域名允许结尾点（IPv6 不允许）、纯数字结尾的主机段按 IPv4（支持十进制/八进制/十六进制混写）校验、IPv6 zone 显式不支持、FQDN 的 TLD 至少 2 个码点；
• UUID 校验：不再使用正则，改为委托 github.com/google/uuid 的 uuid.Parse 解析后再核对版本位，例如 IsUUID3/4/5/7 分别比对 id.Version() 是否为 3/4/5/7；
• email 校验：委托 net/mail.ParseAddress 解析，要求存在非空地址部分；
• 仍保留正则实现的校验包括 ISBN-10/13、美国信用卡号、SSN、十六进制颜色、RGB 颜色等（见 default.go）。

深入 Duration：单位别名与两套解析语义

时长是 strfmt 中话题最多的一类。Duration（人类可读版）是一个以纳秒计数存储的 time.Duration 别名，duration.go 注释提示其最大可表示时长约为 290 年。

它的解析器 ParseDuration 与标准库 time.ParseDuration 类似，但支持天、周这类单位，接受更多缩写与复数形式，并容忍空白（例如 "300 ms" 合法、符号与数字间允许空格）。源码中维护了完整的单位别名表（duration.go）：

量纲	支持的别名
纳秒	ns、nano、nanosecond(s)、nanos
微秒	us、µs、μs、micro(s)、microsecond(s)
毫秒	ms、milli(s)、millisecond(s)
秒	s、sec(s)、second(s)
分	m、min(s)、minute(s)
时	h、hr(s)、hour(s)
天	d、day(s)
周	w、wk(s)、week(s)

同一文件还支持负时长与小数时长。而 DurationISO8601 及带策略参数的 ISODuration[P ISODurationPolicy]（定义于 duration_iso8601.go 与 duration_iso8601_options.go）则按 ISO 8601 语法解析，例如 "P2W"，两者互不通用。

类型转换与指针辅助

README 专门用一个小节交代了类型转换规则，便于你与标准库类型互操作：

• 所有类型都实现了 Stringer，可调用 .String() 转字符串；大多数类型也能直接强转，如 string(Email{})；
• Date、DateTime 可以直接转换为 time.Time，例如 time.Time(DateTime{})；
• Duration 可以直接转换为 time.Duration，例如 time.Duration(Duration{})。

代码层面这三条路径分别落在 date.go、time.go、duration.go 中——Date/DateTime 内部即包装了 time.Time，Duration 内部即包装了 time.Duration。

关于指针，README 说明：conv 子包 提供与 go-openapi/swag 处理基本类型类似、把类型转为指针/从指针取回类型的辅助函数。该子包在 go-openapi 上游仓库中是独立交付的模块，当前 Moby 仓库的 vendored 快照中并不包含它，若需要请单独以对应模块引入。

数据库接入：SQL 与 BSON 双通道

SQL：全类型实现 Scan/Value

所有格式类型都实现了 sql.Scanner 与 driver.Valuer，因此可安全地用作文档库列、或经由 ORM/database/sql 直接读写。仓库的 bson.go、mongo.go 与 internal/bsonlite 提供了 BSON 序列化所需的编解码器。

MySQL/MariaDB 下 DateTime 的已知坑点

README 明确记录了一个需要注意的兼容性问题：

MySQL / MariaDB 关于 DateTime 的警告： go-sql-driver/mysql 驱动对 time.Time 有硬编码处理，但不会拦截 strfmt.DateTime 这种类型重定义。因此 DateTime.Value() 会送出一个 RFC 3339 字符串（如 "2024-06-15T12:30:45.123Z"），而 MySQL/MariaDB 的 DATETIME 列会拒绝该写法。

解决办法是把包级配置 strfmt.MarshalFormat 切换为 MySQL 兼容的时间格式，并在序列化前统一归一化到 UTC：

strfmt.MarshalFormat = strfmt.ISO8601LocalTime
strfmt.NormalizeTimeForMarshal = func(t time.Time) time.Time { return t.UTC() }

BSON / MongoDB：v0.26.0 之后的依赖变更

README 的 Announcements 部分记录了一个重要变更（对应 v0.26.0，2026-03-07 宣布）：

• v0.26.0 移除了对 mongodb driver 的依赖；
• MongoDB 用户无需任何改动即可继续使用本包；
• 不过与 mongodb driver 的向后兼容支持被冻结在 v2.5.0；
• 想要跟进该驱动未来（可能不兼容的）演进、需要使用真实驱动行为的用户，可以在程序中加入空导入：

import _ "github.com/go-openapi/strfmt/enable/mongodb"

这会把行为切换到实际驱动，该驱动作为独立模块持续保持常规更新。

也就是说，默认情况下包内自带一个与 mongo-driver v2.5.0 兼容的精简内置编解码器（built-in minimal codec，对应仓库内 internal/bsonlite 的 codec.go/lite.go）；只有在显式空导入 enable/mongodb 后才使用完整驱动的编解码行为。README 还提到，针对 MongoDB、MariaDB、PostgreSQL 的往返（roundtrip）兼容性测试在 CI 中持续运行，以验证所有格式类型的数据落地能力——该集成测试目录位于上游的 internal/testintegration/，未包含在当前 vendored 快照内。

在 API 生成代码中的角色：Validate(formats strfmt.Registry)

strfmt 最常见的消费方是 go-openapi/swagger-gen 生成的模型。典型生成的模型会带有如下签名的方法（可对照 Moby 仓库 api/templates/schema.gotmpl 的生成模板）：

func (m *SomeModel) Validate(formats strfmt.Registry) error {
	// 内部会针对 date-time、uuid 等字段调用 formats.Validates(...)
	return nil
}

服务端代码模板 api/templates/server/operation.gotmpl 中也会直接 import "github.com/go-openapi/strfmt"。需要如实指出的是：Moby 在生成 API 代码时主动禁用了这部分校验逻辑（模板中标注了多处 TODO(moby): Disabled for moby/api），并且 api/types 等运行时源码中并未直接 import strfmt——它目前以间接依赖的身份（go.mod 中 v0.27.0 // indirect）存在于构建图中，为其上层的 go-openapi/validate、go-openapi/runtime 等组件提供格式支持。因此，如果你在自己的 Go API 项目中同时使用 go-openapi 生成代码，strfmt 就会像上面模板所示那样成为校验链上不可缺的一环。

变更、许可与其他文档

• 变更日志：该库以 GitHub Releases 形式发布版本记录，对应到仓库内即为 vendor/github.com/go-openapi/strfmt 快照的版本演进（顶层 go.mod 锁定 v0.27.0）；
• 许可：以 SPDX 标识 Apache-2.0 发布，许可全文见 vendor/github.com/go-openapi/strfmt/LICENSE；
• 周边文档：随包还附带了 CONTRIBUTORS.md（历届贡献者）、CODE_OF_CONDUCT.md 与 SECURITY.md；
• 规范参考：格式集合以 OpenAPI 2.0 规范的数据类型定义与 JSON Schema 规范为源头。

小结：何时使用 strfmt

如果你的项目满足以下任一条件，strfmt 就值得纳入工具箱：

1. 正在使用 go-openapi / go-swagger 做 OpenAPI 模型生成，需要模型字段在解码与业务校验阶段得到格式级检查（date-time、uuid、ipv4、email……）；
2. 需要一套自带校验、同时支持 JSON 与 database/sql 往返的强类型字符串格式，避免到处散落正则与手工解析；
3. 需要与 MongoDB/BSON 交互，同时希望格式类型能在文档与 SQL 两种存储之间无缝复用（注意 MySQL/MariaDB 的 DateTime 时间格式配置与 mongodb 驱动 enable 空导入这两个开关）。

此时，strfmt.Default 注册表就是你的默认选择；只有当你面向 JSON Schema draft 2020、期望 duration 遵循 ISO 8601 语义时，才需要切换到 strfmt.JSONSchema2020Registry。