Go encoding/json/v2 format 为什么 format 标签不支持（参数形态）

如果你把代码迁移到 Go 1.27 的 encoding/json/v2 后，发现 json:"at,format:RFC3339" 不再按预期工作，原因不是冒号或逗号写错了，而是 format 标签选项已经从首发版本移除。它属于实验期设计，不是当前稳定 API 的可用参数。

处理这类代码时，先删掉 format:value，再按字段类型选择默认表示、调用时的 json.Options，或者自定义类型方法。不要把旧实验语法换成另一个看似相近的标签字符串。

先看标签解析：format 不是当前可用的参数

Go 结构体标签的基本形态仍然是“JSON 字段名，加上逗号分隔的选项”。例如，下面的写法只改变字段名和零值省略规则：

type Event struct {
	// 只改变 JSON 字段名，不改变时间值的编码规则。
	At time.Time `json:"at,omitzero"`
	// string 只适用于原本会编码成 JSON 数字的字段。
	ID int64 `json:"id,string"`
}

迁移时最容易保留下来的旧代码通常是：

type Event struct {
	// format 曾出现在 jsonv2 实验设计中，Go 1.27 首发版本不再接受它。
	At time.Time `json:"at,format:RFC3339"`
}

这里的关键不是 RFC3339 是否拼写正确，而是 format:value 这一参数形态已经不在支持列表里。当前文档列出的标签选项分别负责省略字段、数字字符串化和字段名匹配；它们不能被拼接成一个通用的格式化 DSL。

为什么 format 在首发版本被移除

format 曾经试图在普通字符串标签里塞入一套小型格式语言，例如让字段携带 RFC 3339、Unix 时间或自定义布局。这样写起来短，但格式值的语义必须由字段类型解释，标签本身既不提供类型检查，也不容易表达复杂的编码约束。

Go 1.27 的发布说明把它列为 encoding/json/v2 首发前移除的实验能力，并说明未来更有希望通过类型化结构体标签表达这类格式属性。对迁移者来说，这意味着不能把实验期文档当作稳定 API 继续使用；应该把格式责任放在类型或调用选项上。

因此，遇到这类报错或结果异常时，检查顺序应是：先确认编译使用的 Go 版本，再搜索结构体标签里的 format:，最后根据字段类型选择替代方案。不要先尝试调整冒号、单引号或布局字符串。

按字段类型选择迁移写法

删除标签以后，先问“这个字段的 JSON 形态由谁负责”。下面的划分足以覆盖大多数从实验语法迁移过来的代码：

package main

import (
	"encoding/json/v2"
	"fmt"
	"time"
)

type Task struct {
	// time.Time 在 json/v2 中默认使用 RFC 3339 纳秒精度。
	CreatedAt time.Time `json:"createdAt"`
	// duration 没有默认 JSON 表示，调用方显式选择纳秒数字。
	Timeout time.Duration `json:"timeout"`
}

func main() {
	task := Task{CreatedAt: time.Now(), Timeout: 1500 * time.Millisecond}
	// 选项放在调用边界，避免把 format:value 写进结构体标签。
	b, err := json.Marshal(task, json.FormatDurationAsNano(true))
	if err != nil {
		// 生产代码应保留 SemanticError 的上下文，便于定位字段类型。
		panic(err)
	}
	fmt.Println(string(b))
}

上面的分工很重要：time.Time 使用类型的默认约定，time.Duration 通过显式选项选择纳秒数字。若协议要求的是业务日期、带时区的特殊文本或旧系统规定的非标准形态，就定义一个包装类型，在它的 MarshalJSONTo 和 UnmarshalJSONFrom 中完成编码与错误处理。

迁移代码时的最小排查清单

1. 确认运行环境已经进入 Go 1.27 的 encoding/json/v2 语义，不要把实验期源码和稳定版文档混用。
2. 全局查找 json:"...,format:、json:",format: 和单独的 format: 标签片段。
3. 对 time.Time 先使用默认 RFC 3339；对 time.Duration 选择 FormatDurationAsNano 或类型级编码。
4. 如果格式属于业务协议，优先放进自定义类型方法，而不是继续扩展结构体标签。
5. 重新检查错误处理。v2 对无效结构体标签和无法表示的类型更倾向于报告运行时 SemanticError，不能沿用 v1 “忽略问题也能继续编码”的预期。

判断迁移是否完成，不是看标签能否被解析，而是确认输出协议是否仍然满足下游约定：时间字符串、持续时间单位、整数精度和空值策略都要分别对照接口契约。

常见问题

把 format:RFC3339 改成 format:'2006-01-02' 可以吗？

不可以。改变引号或布局字符串不能恢复已经移除的标签选项。应该删除 format，再使用默认表示或自定义类型。

string 能不能替代所有 format 用法？

不能。string 只针对原本会编码为 JSON 数字的字段，用于把数字放进 JSON 字符串；它不负责日期布局或任意文本格式。

为什么 time.Duration 要单独处理？

在 encoding/json/v2 中，time.Duration 没有默认 JSON 表示。需要纳秒数字时传入 json.FormatDurationAsNano(true)，需要其他协议形态时用自定义类型方法。

一句话记忆：format:value 是实验期标签，不是 Go 1.27 encoding/json/v2 的稳定参数；迁移时按字段类型把表示规则放回默认类型、json.Options 或自定义类型边界。