Go encoding/json/v2提案:JSON处理新引擎

本文永久链接 – https://tonybai.com/2025/02/05/go-encoding-json-v2-proposal-json-processing-new-engine

Go标准库中的encoding/json包,作为Go社区广泛使用的JSON处理工具,至今已走过十余年。凭借其将JSON数据与原生Go类型相互转换的能力、通过struct tag自定义字段表示的灵活性,以及Go类型自定义JSON格式的特性,赢得了Go开发者的青睐。

然而,随着时间的推移,encoding/json的局限性也逐渐显现。孤立地解决这些问题可能会导致非正交特性之间产生意外的交互。因此,Go团队在2023年下旬发起了关于encoding/json/v2的讨论,旨在全面审视现有encoding/json包,并提出一个面向未来十年的Go JSON处理方案,打造一个 JSON处理新引擎

经过近一年多的讨论、设计调整以及参考实现的优化,Go团队于近期正式提出了关于encoding/json/v2的提案issue。在该issue中,Go团队梳理并总结了讨论结果以及初始设计与后续调整之间的差异,以供Go社区进一步审阅与反馈。

为了让大家更好地了解该提案issue的核心内容,本文将对提案的背景、主要内容、相对于v1版本的主要改进,以及与v1版本的联系等进行全面介绍,希望通过这篇文章,大家能够及时了解到Go标准库json包的演进与变化。

1. 提案背景:现有encoding/json包的局限与改进的需求

在过去十年中,开发者在使用encoding/json的过程中,逐渐意识到了它在功能、API设计、性能和行为上存在的不足。这些问题可以归纳为以下几个方面,也正是encoding/json/v2提案希望解决的核心痛点:

1.1 功能缺失 (Missing functionality)

尽管encoding/json功能完善,但仍存在一些重要的功能缺失,社区也为此提出了诸多Feature Request,其中最突出的包括:

  • time.Time的自定义格式化 (#21990): 缺乏灵活的方式来指定time.Time类型在JSON中的格式,例如自定义日期时间字符串格式。
  • Marshal时忽略特定Go值 (#11939, #22480, #50480, #29310, #52803, #45669): 现有的omitempty标签在某些场景下无法满足需求,开发者希望更精细地控制哪些Go值在Marshal时被忽略,例如忽略零值、空值或特定条件下的值。Go 1.24版本增加了omitzero tag,将在一定层度缓解这个问题。
  • 将nil切片和mapMarshal为空JSON数组和对象 (#37711, #27589): encoding/json默认将nil切片和mapMarshal为JSONnull,但在某些场景下,开发者更期望将其Marshal为空的JSON数组[]和对象{}。
  • 无Go嵌入的Inline类型 (#6213): 希望能够更灵活地将Go类型内联到JSON对象中,而无需依赖Go的struct嵌入机制。

虽然这些功能缺失大部分可以通过向现有encoding/json包添加新功能来解决,但可能会导致API变得臃肿和复杂。

1.2 API 设计缺陷 (API deficiencies)

encoding/json的API设计存在一些尖锐或限制性的问题,影响了开发者的使用体验:

  • 难以正确地从io.Reader进行Unmarshal: 常用的json.NewDecoder(r).Decode(v)方法并不能正确处理JSON payload末尾的垃圾数据 (#36225),容易导致数据解析错误。
  • Marshal和Unmarshal函数无法使用Options: 虽然Encoder和Decoder类型支持Options配置,但Marshal和Unmarshal函数却无法使用,同样,实现Marshaler和Unmarshaler接口的类型也无法利用Options,缺乏选项配置的传递机制(#41144)。
  • Compact, Indent, HTMLEscape函数输出目标受限: 这些格式化函数只能将结果写入bytes.Buffer,而不是更灵活的[]byte或io.Writer,限制了函数的使用场景。

这些API缺陷可以通过向现有encoding/json包引入新的API来修复,但这可能会导致同一个任务在同一个包中存在多种不同的实现方式,增加学习成本和使用困惑。

1.3 性能限制 (Performance limitations)

encoding/json的性能表现一直备受关注,存在诸多限制性能提升的因素:

  • MarshalJSON接口: 强制实现者分配[]byte返回值,且encoding/json需要再次解析返回值以验证JSON的有效性并重新格式化,造成不必要的性能开销。
  • UnmarshalJSON接口: 要求提供完整的JSON value,导致encoding/json需要预先完整解析JSON值以确定边界,之后UnmarshalJSON方法本身还需要再次解析,如果UnmarshalJSON递归调用Unmarshal,则会导致O(N²)的性能退化,例如Kubernetes kube-openapi项目在Unmarshalspec.Swagger时遇到的性能瓶颈 (kubernetes/kube-openapi#315)。
  • Encoder.WriteToken: 缺乏流式Encoder API,虽然提案已被接受(#40127),但尚未实现,且可能同样存在性能问题。
  • Decoder.Token: Token类型是一个接口,可以容纳多种类型 (Delim, bool, float64, Number, string, nil),当boxing数字或字符串到Token接口类型时,会频繁发生内存分配 (#40128)。
  • 缺乏真正的流式处理: 即使Encoder.Encode和Decoder.Decode方法操作io.Writer和io.Reader,它们仍然会将整个JSON value缓冲到内存中,需要二次扫描JSON,与流式处理的初衷背道而驰 (#33714, #7872, #11046)。

encoding/json应该默认以真正的流式方式操作io.Writer和io.Reader。缓冲整个JSON value违背了使用io.Reader和io.Writer的意义。希望避免在发生错误时输出JSON 的用例应该调用Marshal,并在错误为nil时才写入输出。不幸的是,encoding/json无法默认切换到流式处理,因为这将是一个破坏性的行为变更,暗示着需要一个v2版本的json包来实现这个目标。

1.4 行为缺陷 (Behavioral flaws)

encoding/json在行为上存在诸多缺陷,随着JSON规范的日益严格 (RFC 4627, RFC 7159, RFC 7493, RFC 8259),这些缺陷显得愈发突出:

  • JSON 语法处理不严谨: encoding/json允许无效UTF-8字符,而最新的互联网标准 (RFC 8259) 要求使用有效的UTF-8编码。默认行为至少应符合RFC 8259,将无效UTF-8视为错误。
  • 允许重复的对象成员名称: RFC8259规定,重复的对象成员名称会导致未指定的行为。从安全角度考虑,默认行为应更严格,拒绝重复名称,正如 RFC 7493 所建议的那样。
  • Unmarshal时大小写不敏感: Unmarshal时,JSON对象名称与Go struct字段名称使用大小写不敏感匹配 (#14750),这既令人意外,也可能存在安全漏洞和性能瓶颈。
  • 类型定义方法调用不一致: 由于encoding/json及其对Go反射的使用,MarshalJSON和UnmarshalJSON方法在底层值不可寻址时无法调用 (#22967, #27722, #33993, #55890)。
  • Merge语义不一致: Unmarshal到非空的Go值时,是否清除目标、重置并重用目标内存、或合并到目标的行为不一致 (#27172, #31924, #26946)。
  • Error 类型不一致: encoding/json返回的Error类型不一致,难以可靠地检测Syntactic error, Semantic error, I/O error等不同类型的错误。

这些行为缺陷在不破坏向后兼容性的前提下难以修复。虽然可以添加选项来指定不同的行为,但这并非理想方案,因为期望的行为不应作为非默认选项存在。改变默认行为同样意味着需要一个v2版本的json包。

为了解决上述encoding/json包的种种问题,并为Go语言构建更强大、更现代化的JSON处理能力,Go团队正式提出了encoding/json/v2提案。正如“JSON处理新引擎”这个本文标题所寓意的,encoding/json/v2并非简单的修补和改进,而是一次对Go语言JSON处理的彻底革新。下面我们就来介绍一下这个新json引擎的主要功能和特点。

2. encoding/json/v2:Go JSON处理的新引擎

encoding/json/v2提案并非简单地对现有encoding/json进行升级,而是引入了两个全新的包:

  • encoding/json/jsontext: 这是一个纯语法层面的JSON处理包,专注于JSON语法的解析和生成,不依赖Go反射。它提供了对JSON令牌(Token)和原始值(Value)的操作,允许开发者在语法层面精细地控制JSON的编解码过程。
  • encoding/json/v2: 这是一个语义层面的JSON处理包,基于jsontext包实现,并依赖Go反射。它继承了encoding/json的核心功能,负责将Go值与JSON数据进行语义上的转换(Marshal 和 Unmarshal),并提供了更丰富的功能和更优的性能。

提案中还给出了两者的关系图,通过该图大家可以更直观地看出两个包之间的关系:

此外,提案还考虑了与现有encoding/json的兼容性,并提供了选项来实现互操作。encoding/json包本身也将被重构,底层实现将基于encoding/json/v2来重新实现

下面是对jsontext包和json/v2包的核心API的介绍。

2.1 encoding/json/jsontext包的关键API

jsontext包提供了Encoder和Decoder类型,用于JSON的编码和解码,以及Token和Value类型来表示JSON的语法元素。

package jsontext // "encoding/json/jsontext"

type Encoder struct { /* no exported fields */ }
func NewEncoder(io.Writer, ...Options) *Encoder
func (*Encoder) WriteToken(Token) error
func (*Encoder) WriteValue(Value) error

type Decoder struct { /* no exported fields */ }
func NewDecoder(io.Reader, ...Options) *Decoder
func (*Decoder) PeekKind() Kind
func (*Decoder) ReadToken() (Token, error)
func (*Decoder) ReadValue() (Value, error)
func (*Decoder) SkipValue() error

type Kind byte // JSON 令牌类型
type Token struct { /* no exported fields */ } // JSON 令牌
type Value []byte // JSON 原始值

其中:

  • Encoder和Decoder: 提供流式的JSON编码和解码能力,操作io.Writer和io.Reader。
  • Token: 表示JSON的基本语法单元,例如null, true, false, 字符串, 数字, 对象开始{, 对象结束}, 数组开始[, 数组结束]等。
  • Value: 表示JSON的原始值,可以是完整的JSON对象或数组,类似于encoding/json中的RawMessage。
  • Kind: 枚举类型,表示Token和Value的类型,例如’n'(null),’t'(true),’”‘(string),’{‘(object start) 等。

jsontext包还提供了格式化JSON的函数,例如AppendFormat, AppendQuote, AppendUnquote等,以及用于配置行为的Options类型。

2.2 encoding/json/v2包的关键API

encoding/json/v2包提供了Marshal, Unmarshal等核心函数,以及MarshalWrite, MarshalEncode, UnmarshalRead, UnmarshalDecode等变体,用于不同场景下的JSON编解码。

package json // "encoding/json/v2"

func Marshal(in any, opts ...Options) (out []byte, err error)
func MarshalWrite(out io.Writer, in any, opts ...Options) error
func MarshalEncode(out *jsontext.Encoder, in any, opts ...Options) error

func Unmarshal(in []byte, out any, opts ...Options) error
func UnmarshalRead(in io.Reader, out any, opts ...Options) error
func UnmarshalDecode(in *jsontext.Decoder, out any, opts ...Options) error

其中:

  • Marshal和Unmarshal: 核心的Marshal和Unmarshal函数,与encoding/json中的函数签名类似,但行为有所改进。
  • MarshalWrite, UnmarshalRead: 直接操作io.Writer和io.Reader,避免中间[]byte的分配。
  • MarshalEncode, UnmarshalDecode: 操作jsontext.Encoder和jsontext.Decoder,提供更底层的流式编解码能力。
  • Options: 用于配置Marshal和Unmarshal的行为,例如大小写敏感性、omitempty语义、错误处理等。

encoding/json/v2包还引入了更丰富的struct tag选项,例如omitzero, omitempty, string, nocase, strictcase, inline,unknown,format等,提供更灵活的字段映射和格式化控制。

2.3 设计原则

下面是该proposal的一些设计原则梳理:

  • 分离语法与语义: 明确区分JSON的语法处理(jsontext)和语义处理(json/v2),使得开发者可以根据需求选择合适的API。
  • 流式处理: 提供流式的Encoder和Decoder,支持高效处理大规模JSON数据,避免一次性加载整个JSON文档到内存。
  • 选项化配置: 通过Options类型提供丰富的配置选项,允许开发者根据具体需求定制JSON编解码的行为,例如大小写敏感性、格式化风格、错误处理方式等。
  • 改进错误处理: 引入SyntacticError和SemanticError类型,提供更详细的错误信息,包括错误发生的位置 (JSON Pointer) 和具体的错误原因,方便问题定位和调试。
  • 兼容性与迁移: encoding/json/v2尽可能兼容现有的encoding/json的行为,并提供选项 (DefaultOptionsV1) 来模拟v1的行为,方便用户平滑迁移。

接下来,我们再来看看json/v2相对于之前版本的提升与改进!

3. 相对于encoding/json的提升与改进

encoding/json/v2相对于现有的encoding/json包,在多个方面进行了显著的提升和改进:

3.1 性能提升

jsontext包采用更高效的语法解析算法,json/v2在语义处理方面也进行了优化,整体性能相比encoding/json有显著提升,尤其在反序列化和流式处理方面。Benchmark 测试显示,encoding/json/v2的反序列化速度比encoding/json快2.7x到10.2x:

以具体类型为例,下面是github.com/go-json-experiment/jsonbench给出的benchmark结果:


3.2 更正的行为

encoding/json/v2修正了encoding/json中一些行为不一致性和历史遗留问题,例如:

  • 大小写敏感的字段匹配: 默认采用严格的大小写敏感匹配,更符合JSON规范,并通过MatchCaseInsensitiveNames和nocasetag选项提供大小写不敏感匹配的灵活性。
  • 重新定义omitempty语义: omitempty基于JSON类型系统重新定义,更加清晰和一致,并通过OmitEmptyWithLegacyDefinition选项提供兼容v1 行为的选择。
  • nil切片和map的处理: 默认将nil切片和mapMarshal为空JSON数组和对象,而非null,并通过FormatNilSliceAsNull和FormatNilMapAsNull选项提供Marshal为null的选择。
  • 字节数组的表示: 默认将[]\byteMarshal为Base64编码的JSON字符串,而非JSON数字数组,并通过FormatBytesWithLegacySemantics和format:arraytag 选项提供兼容v1行为的选择。
  • 方法调用的可寻址性: MarshalJSON方法无论Go值是否可寻址都可调用,更符合预期。
  • Map Key 的方法调用: MarshalJSON和UnmarshalJSON方法可以用于 Map Key,提供更强大的自定义能力。
  • 确定性输出: 通过Deterministic选项,可以保证相同输入Marshal出相同的JSON字节序列。
  • 最小化转义: 默认使用最小化的JSON字符串转义,仅在必要时进行转义,例如只在HTML或JavaScript环境下才进行特殊字符的转义。
  • UTF-8 验证: 默认严格验证UTF-8编码,拒绝包含无效UTF-8的JSON输入,并通过AllowInvalidUTF8选项允许处理无效UTF-8。
  • 重复Key错误: 默认拒绝JSON对象中存在重复的Key,更符合JSON 规范,并通过AllowDuplicateNames选项允许处理重复Key。
  • Null值的Unmarshal: Unmarshal JSONnull时,始终一致地将Go值置零。
  • Unmarshal合并行为: Unmarshal JSON对象时,默认合并到已有的Go值,而非完全替换,提供更灵活的更新语义。
  • time.Duration的表示: 默认将time.DurationMarshal为JSON 字符串,而非纳秒数字,并通过FormatTimeWithLegacySemantics和format:nanotag选项提供兼容v1行为的选择。
  • 运行时错误报告: 对Go结构体类型中的结构性错误(例如错误的tag选项)进行运行时错误报告,提前发现问题。

3.3 更灵活的 API

jsontext包提供了更底层的API,允许开发者直接操作JSON token和原始值,实现更精细的JSON处理逻辑。json/v2提供了更多的选项和 struct tag 选项,支持更丰富的自定义需求。

3.4 更清晰的错误信息

SyntacticError和SemanticError类型提供了更详细的错误信息,包括错误位置 (JSON Pointer) 和错误原因,方便问题排查。

4. encoding/json与encoding/json/v2的联系

encoding/json/v2提案的一个重要目标是实现与现有encoding/json的平滑过渡。为此,提案采取了以下策略:

  • encoding/json基于encoding/json/v2实现: 未来的encoding/json包将完全基于encoding/json/v2包进行重构,这意味着encoding/json/v2将成为Go语言官方JSON处理的核心引擎。
  • DefaultOptionsV1选项: encoding/json包将提供DefaultOptionsV1选项,该选项预设了一系列兼容v1行为的配置,使得encoding/json的默认行为尽可能与旧版本保持一致。
  • 互操作选项: encoding/json/v2和encoding/json都提供了大量的选项,允许开发者在v1和v2行为之间进行灵活切换,逐步迁移到v2的新特性。

5. 示例代码

以下示例展示了encoding/json/v2的基本用法(示例改自https://github.com/go-json-experiment/json/blob/master/example_test.go):

package main

import (
    "fmt"
    "log"

    "github.com/go-json-experiment/json"
    "github.com/go-json-experiment/json/jsontext"
)

func main() {
    var value struct {
        // This field is explicitly ignored with the special "-" name.
        Ignored any `json:"-"`
        // No JSON name is not provided, so the Go field name is used.
        GoName any
        // A JSON name is provided without any special characters.
        JSONName any `json:"jsonName"`
        // No JSON name is not provided, so the Go field name is used.
        Option any `json:",nocase"`
        // An empty JSON name specified using an single-quoted string literal.
        Empty any `json:"''"`
        // A dash JSON name specified using an single-quoted string literal.
        Dash any `json:"'-'"`
        // A comma JSON name specified using an single-quoted string literal.
        Comma any `json:"','"`
        // JSON name with quotes specified using a single-quoted string literal.
        Quote any `json:"'\"\\''"`
        // An unexported field is always ignored.
        unexported any
    }

    b, err := json.Marshal(value)
    if err != nil {
        log.Fatal(err)
    }
    (*jsontext.Value)(&b).Indent() // indent for readability
    fmt.Println(string(b))
}

这段示例代码旨在演示github.com/go-json-experiment/json (即提案中encoding/json/v2的参考实现) 在处理Go结构体字段的json tag时,对于不同命名约定和特殊字符的处理方式。结构体value定义了多个字段,每个字段都使用了不同的json tag,用于演示不同的命名和选项,具体选项含义可以参考proposal中的说明。

(*jsontext.Value)(&b).Indent() // indent for readability

前面说过,jsontext是操作json语法的包,json缩进的工作就交给了该包的Value的Indent方法。在encoding/json中,我们通常直接用MarshalIndent来进行格式化json的工作。

运行上述示例将输出如下结果:

$go run main.go
{
    "GoName": null,
    "jsonName": null,
    "Option": null,
    "": null,
    "-": null,
    ",": null,
    "\"'": null
}

更多示例,可以参见 https://github.com/go-json-experiment/json/blob/master/example_test.go源文件。

6. 小结

encoding/json/v2提案代表了Go语言在JSON处理方面的一次重大升级。通过引入jsontext和json/v2两个包,并提供更强大的API、更丰富的选项和更优的性能,encoding/json/v2将为Go开发者带来更高效、更灵活、更可靠的JSON处理体验。同时,该提案也充分考虑了与现有encoding/json的兼容性,为用户平滑迁移提供了保障。encoding/json/v2的引入,无疑将进一步提升Go语言在Web开发、数据处理等领域的竞争力,为Go开发者构建下一代应用提供更强大的JSON处理新引擎

7. 参考资料


Gopher部落知识星球在2025年将继续致力于打造一个高品质的Go语言学习和交流平台。我们将继续提供优质的Go技术文章首发和阅读体验。并且,2025年将在星球首发“Go陷阱与缺陷”和“Go原理课”专栏!此外,我们还会加强星友之间的交流和互动。欢迎大家踊跃提问,分享心得,讨论技术。我会在第一时间进行解答和交流。我衷心希望Gopher部落可以成为大家学习、进步、交流的港湾。让我相聚在Gopher部落,享受coding的快乐! 欢迎大家踊跃加入!

img{512x368}
img{512x368}

img{512x368}
img{512x368}

著名云主机服务厂商DigitalOcean发布最新的主机计划,入门级Droplet配置升级为:1 core CPU、1G内存、25G高速SSD,价格6$/月。有使用DigitalOcean需求的朋友,可以打开这个链接地址:https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

Gopher Daily(Gopher每日新闻) – https://gopherdaily.tonybai.com

我的联系方式:

  • 微博(暂不可用):https://weibo.com/bigwhite20xx
  • 微博2:https://weibo.com/u/6484441286
  • 博客:tonybai.com
  • github: https://github.com/bigwhite
  • Gopher Daily归档 – https://github.com/bigwhite/gopherdaily
  • Gopher Daily Feed订阅 – https://gopherdaily.tonybai.com/feed

商务合作方式:撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

Go导出标识符:那些鲜为人知的细节

本文永久链接 – https://tonybai.com/2025/01/23/the-hidden-details-of-go-exported-identifiers

前不久,在“Go+用户组”微信群里看到有开发者向七牛云老板许式伟反馈七牛云Go SDK中的某些类型没有导出,导致外部包无法使用的问题(如下图)

七牛开发人员迅速对该问题做出了“更正”,将问题反馈中涉及的类型saveasArgs和saveasReply改为了导出类型,即首字母大写:

不过,这看似寻常的问题反馈与修正却引发了我的一些思考。

我们大胆臆想一下:如果saveasReply类型的开发者是故意将saveasReply类型设置为非导出的呢?看一下“更正”之前的saveasReply代码:

type saveasReply struct {
    Fname       string `json:"fname"`
    PersistenId string `json:"persistentId,omitempty"`
    Bucket      string `json:"bucket"`
    Duration    int    `json:"duration"` // ms
}

有读者可能会问:那为什么还将saveasReply结构体的字段设置为导出字段呢?请注意每个字段后面的结构体标签(struct tag)。这显然是为了进行JSON 编解码,因为目前Go的encoding/json包仅会对导出字段进行编解码处理。

除了这个原因,原开发者可能还希望包的使用者能够访问这些导出字段,而又不想完全暴露该类型。我在此不对这种设计的合理性进行评价,而是想探讨这种做法是否可行。

我们对Go导出标识符的传统理解是:导出标识符(以大写字母开头的标识符)可以在包外被访问和使用,而非导出标识符(以小写字母开头的标识符)只能在定义它们的包内访问。这种机制帮助开发者控制类型和函数的可见性,确保内部实现细节不会被随意访问,从而增强封装性。

但实际上,Go的导出标识符机制是否允许在某些情况下,即使类型本身是非导出的,其导出字段依然可以被包外的代码访问呢?该类型的导出方法呢?这些关于Go导出标识符的细节可能是鲜少人探讨的,在这篇博文中,我们将系统地了解这些机制,希望能为各位小伙伴带来更深入的理解。

1. Go对导出标识符的定义

我们先回顾一下Go语言规范(go spec)对导出标识符的定义

我们通常使用英文字母来命名标识符,因此可以将上述定义中的第一句理解为:以大写英文字母开头的标识符即为导出标识符。

注:Unicode字符类别Lu(Uppercase Letter)包含所有的大写字母。这一类别不仅包括英文大写字母,还涵盖多种语言的大写字符,例如希腊字母、阿拉伯字母、希伯来字母和西里尔字母等。然而,我非常不建议大家使用非英文大写字母来表示导出标识符,因为这可能会挑战大家的认知习惯。

而第二句后半部分的描述往往被我们忽视或理解不够到位。一个类型的字段名和方法名可以是导出的,但并没有明确要求其关联的类型本身也必须是导出的

这为我们提供了进一步探索Go导出标识符细节的机会。接下来,我们就用具体示例看看是否可以在包外访问非导出类型的导出字段以及导出方法。

2. 在包外访问非导出类型的导出字段

我们首先定义一个带有导出字段的非导出类型myStruct,并将它放在mypackage里:

// go-exported-identifiers/field/mypackage/mypackage.go

package mypackage

type myStruct struct {
    Field string // 导出的字段
}

// NewMyStruct1是一个导出的函数,返回myStruct的指针
func NewMyStruct1(value string) *myStruct {
    return &myStruct{Field: value}
}

// NewMyStruct1是一个导出的函数,返回myStruct类型变量
func NewMyStruct2(value string) myStruct {
    return myStruct{Field: value}
}

然后我们在包外尝试访问myStruct类型的导出字段:

// go-exported-identifiers/field/main.go

package main

import (
    "demo/mypackage"
    "fmt"
)

func main() {
    // 通过导出的函数获取myStruct的指针
    ms1 := mypackage.NewMyStruct1("Hello1")

    // 尝试访问Field字段
    fmt.Println(ms1.Field) // Hello1

    // 通过导出的函数获取myStruct类型变量
    ms2 := mypackage.NewMyStruct1("Hello2")

    // 尝试访问Field字段
    fmt.Println(ms2.Field) // Hello2
}

在go-exported-identifiers/field目录下编译运行该示例:

$go run main.go
Hello1
Hello2

我们看到,无论是通过myStruct的指针还是实例副本,都可以成功访问其导出变量Field。这个示例的关键就是:我们使用了短变量声明直接通过调用myStruct的两个“构造函数(NewXXX)”得到了其指针(ms1)以及实例副本(ms2)。在这个过程中,我们没有在main包中显式使用mypackage.myStruct这个非导出类型。

采用类似的方案,我们接下来再看看是否可以在包外访问非导出类型的导出方法。

3. 在包外访问非导出类型的导出方法

我们为非导出类型添加两个导出方法M1和M2:

// go-exported-identifiers/method/mypackage/mypackage.go

package mypackage

import "fmt"

type myStruct struct {
    Field string // 导出的字段
}

// NewMyStruct1是一个导出的函数,返回myStruct的指针
func NewMyStruct1(value string) *myStruct {
    return &myStruct{Field: value}
}

// NewMyStruct1是一个导出的函数,返回myStruct类型变量
func NewMyStruct2(value string) myStruct {
    return myStruct{Field: value}
}

func (m *myStruct) M1() {
    fmt.Println("invoke *myStruct's M1")
}

func (m myStruct) M2() {
    fmt.Println("invoke myStruct's M2")
}

然后,试着在外部包中调用M1和M2方法:

// go-exported-identifiers/method/main.go

package main

import (
    "demo/mypackage"
)

func main() {
    // 通过导出的函数获取myStruct的指针
    ms1 := mypackage.NewMyStruct1("Hello1")
    ms1.M1()
    ms1.M2()

    // 通过导出的函数获取myStruct类型变量
    ms2 := mypackage.NewMyStruct2("Hello2")
    ms2.M1()
    ms2.M2()
}

在go-exported-identifiers/method目录下编译运行这个示例:

$go run main.go
invoke *myStruct's M1
invoke myStruct's M2
invoke *myStruct's M1
invoke myStruct's M2

我们看到,无论是通过非导出类型的指针,还是通过非导出类型的变量复本都可以成功调用非导出类型的导出方法。

提及方法,我们会顺带想到接口,非导出类型是否可以实现某个外部包定义的接口呢?我们继续往下看。

4. 非导出类型实现某个外部包的接口

在Go中,如果某个类型T实现了某个接口类型I的方法集合中的所有方法,我们就说T实现了I,T的实例可以赋值给I类型的接口变量。

在下面示例中,我们看看非导出类型是否可以实现某个外部包的接口。

在这个示例中mypackage包中的内容与上面示例一致,主要改动的是main.go,我们来看一下:

// go-exported-identifiers/interface/main.go

package main

import (
    "demo/mypackage"
)

// 定义一个导出的接口
type MyInterface interface {
    M1()
    M2()
}

func main() {
    var mi MyInterface

    // 通过导出的函数获取myStruct的指针
    ms1 := mypackage.NewMyStruct1("Hello1")
    mi = ms1
    mi.M1()
    mi.M2()

    // 通过导出的函数获取myStruct类型变量
    // ms2 := mypackage.NewMyStruct2("Hello2")
    // mi = ms2 // compile error: mypackage.myStruct does not implement MyInterface
    // ms2.M1()
    // ms2.M2()
}

在这个main.go中,我们定义了一个接口MyInterface,它的方法集合中有两个方法M1和M2。根据类型方法集合的判定规则,*myStruct类型实现了MyInterface的所有方法,而myStruct类型则不满足,没有实现M1方法,我们在go-exported-identifiers/interface目录下编译运行这个示例,看看是否与我们预期的一致:

$go run main.go
invoke *myStruct's M1
invoke myStruct's M2

如果我们去掉上面代码中对ms2的注释,那么将得到Compiler error: mypackage.myStruct does not implement MyInterface。

注:关于一个类型的方法集合的判定规则,可以参考我的极客时间《Go语言第一课》专栏的第25讲

接下来,我们再来考虑一个场景,即非导出类型用作嵌入字段的情况,我们要看看该非导出类型的导出方法和导出字段是否会promote到外部类型中。

5. 非导出类型用作嵌入字段

我们改造一下示例,新版的带有嵌入字段的结构见下面mypackage包的代码:

// go-exported-identifiers/embedded_field/mypackage/mypackage.go

package mypackage

import "fmt"

type nonExported struct {
    Field string // 导出的字段
}

// Exported 是导出的结构体,嵌入了nonExported
type Exported struct {
    nonExported // 嵌入非导出结构体
}

func NewExported(value string) *Exported {
    return &Exported{
        nonExported: nonExported{
            Field: value,
        },
    }
}

// M1是导出的函数
func (n *nonExported) M1() {
    fmt.Println("invoke nonExported's M1")
}

// M2是导出的函数
func (e *Exported) M2() {
    fmt.Println("invoke Exported's M2")
}

这里新增一个导出类型Exported,它嵌入了一个非导出类型nonExported,后者拥有导出字段Field,以及两个导出方法M1。我们也Exported类型定义了一个方法M2。

下面我们再来看看main.go中是如何使用Exported的:

// go-exported-identifiers/embedded_field/main.go

package main

import (
    "demo/mypackage"
    "fmt"
)

// 定义一个导出的接口
type MyInterface interface {
    M1()
    M2()
}

func main() {
    ms := mypackage.NewExported("Hello")
    fmt.Println(ms.Field) // 访问嵌入的非导出结构体的导出字段

    ms.M1() // 访问嵌入的非导出结构体的导出方法

    var mi MyInterface = ms
    mi.M1()
    mi.M2()
}

在go-exported-identifiers/embedded_field目录下编译运行这个示例:

$go run main.go
Hello
invoke nonExported's M1
invoke nonExported's M1
invoke Exported's M2

我们看到,作为嵌入字段的非导出类型的导出字段与方法会被自动promote到外部类型中,通过外部类型的变量可以直接访问这些字段以及调用这些导出方法。这些方法还可以作为外部类型方法集中的一员,来作为满足特定接口类型(如上面代码中的MyInterface)的条件。

Go 1.18增加了泛型支持,那么非导出类型是否可以用作泛型函数和泛型类型的类型实参呢?最后我们来看看这个细节。

6. 非导出类型用作泛型函数和泛型类型的类型实参

和前面一样,我们先定义用于该示例的带有导出字段和导出方法的非导出类型:

// go-exported-identifiers/generics/mypackage/mypackage.go

package mypackage

import "fmt"

// 定义一个非导出的结构体
type nonExported struct {
    Field string
}

// 导出的方法
func (n *nonExported) M1() {
    fmt.Println("invoke nonExported's M1")
}

func (n *nonExported) M2() {
    fmt.Println("invoke nonExported's M2")
}

// 导出的函数,用于创建非导出类型的实例
func NewNonExported(value string) *nonExported {
    return &nonExported{Field: value}
}

现在我们将其用于泛型函数,下面定义了泛型函数UseNonExportedAsTypeArgument,它的类型参数使用MyInterface作为约束,而上面的nonExported显然满足该约束,我们通过构造函数NewNonExported获得非导出类型的实例,然后将其传递给UseNonExportedAsTypeArgument,Go会通过泛型的类型参数自动推导机制推断出类型实参的类型:

// go-exported-identifiers/generics/main.go

package main

import (
    "demo/mypackage"
)

// 定义一个用作约束的接口
type MyInterface interface {
    M1()
    M2()
}

func UseNonExportedAsTypeArgument[T MyInterface](item T) {
    item.M1()
    item.M2()
}

// 定义一个带有泛型参数的新类型
type GenericType[T MyInterface] struct {
    Item T
}

func NewGenericType[T MyInterface](item T) GenericType[T] {
    return GenericType[T]{Item: item}
}

func main() {
    // 创建非导出类型的实例
    n := mypackage.NewNonExported("Hello")

    // 调用泛型函数,传入实现了MyInterface的非导出类型
    UseNonExportedAsTypeArgument(n) // ok

    // g := GenericType{Item: n} // compiler error: cannot use generic type GenericType[T MyInterface] without instantiation
    g := NewGenericType(n)
    g.Item.M1()
}

但由于目前Go泛型还不支持对泛型类型的类型参数的自动推导,所以直接通过g := GenericType{Item: n}来初始化一个泛型类型变量将导致编译错误!我们需要借助泛型函数的推导机制将非导出类型与泛型类型进行结合,参见上述示例中的NewGenericType函数,通过泛型函数支持的类型参数的自动推导间接获得GenericType的类型实参。在go-exported-identifiers/generics目录下编译运行这个示例,便可得到我们预期的结果:

$go run main.go
invoke nonExported's M1
invoke nonExported's M2
invoke nonExported's M1

7. 非导出类型使用导出字段以及导出方法的用途

前面的诸多示例证明了:即使类型本身是非导出的,但其内部的导出字段以及它的导出方法依然可以在外部包中使用,并且在实现接口、嵌入字段、泛型等使用场景下均有效。

到这里,你可能会提出这样一个问题:会有Go开发者使用非导出类型结合导出字段或方法的设计吗

其实这种还是很常见的,在Go标准库中就有不少,只不过它们更多是包内使用,类似于非导出类型xxxImpl和它的Wrapper类型XXX的关系,或是xxxImpl或嵌入到XXX中,就像这样:

// 包内实现
type xxxImpl struct {  // 非导出的实现类型
    // 内部字段
}

// 导出的包装类型
type XXX struct {
    impl *xxxImpl  // 包含实现类型
    // 其他字段
}

// 或者通过嵌入方式
type XXX struct {
    *xxxImpl  // 嵌入实现类型
    // 其他字段
}

但也有一些可以包外使用的,比如实现了某个接口,并通过接口值返回,提供给外部使用,例如下面的valueCtx,它实现了Context接口,并通过WithValue返回,供调用WithValue的外部包使用:

//$GOROOT/src/context/context.go

func WithValue(parent Context, key, val any) Context {  // 构造函数,实现接口
    if parent == nil {
        panic("cannot create context from nil parent")
    }
    if key == nil {
        panic("nil key")
    }
    if !reflectlite.TypeOf(key).Comparable() {
        panic("key is not comparable")
    }
    return &valueCtx{parent, key, val}
}

// A valueCtx carries a key-value pair. It implements Value for that key and
// delegates all other calls to the embedded Context.
type valueCtx struct {
    Context
    key, val any
}

func (c *valueCtx) Value(key any) any {
    if c.key == key {
        return c.val
    }
    return value(c.Context, key)
}

这么做的目的是什么呢?大约有如下几点:

  • 隐藏实现细节

非导出类型的主要作用是防止外部直接使用和依赖其内部实现细节。通过限制类型的直接使用,库作者可以保持实现的灵活性,随时调整或重构类型的内部逻辑,而无需担心破坏外部调用代码; 还可以避免暴露多余的API,使库的接口更加简洁。

  • 控制实例的创建和管理

通过非导出类型,开发者还可以确保外部代码无法直接实例化类型,而必须通过导出的构造函数或工厂函数,就像前面举的示例那样。这种模式可以保证对象始终以特定的方式初始化,避免错误使用。同时,它还可以用来实现更复杂的初始化逻辑,如依赖注入或资源管理。

  • 在接口实现中的作用

非导出类型可以用来实现导出的接口,从而将接口的实现细节完全隐藏。对于用户来说,只需要关心接口的定义,而无需关注其实现。

8. 小结

本文探讨了Go语言中的导出标识符及其相关细节,特别是非导出类型如何与其导出字段和导出方法结合使用。

尽管某些类型是非导出的,其内部的导出字段和方法依然可以在包外访问。此外,非导出类型在实现接口、嵌入字段和泛型中也展现出良好的应用。这种设计不仅促进了封装和接口实现的灵活性,还允许开发者通过构造函数返回非导出类型的实例,从而有效控制实例的创建与管理。这种方式帮助隐藏实现细节,简化外部接口,使得代码结构更加清晰。

本文涉及的源码可以在这里下载。


Gopher部落知识星球在2025年将继续致力于打造一个高品质的Go语言学习和交流平台。我们将继续提供优质的Go技术文章首发和阅读体验。并且,2025年将在星球首发“Go陷阱与缺陷”和“Go原理课”专栏!此外,我们还会加强星友之间的交流和互动。欢迎大家踊跃提问,分享心得,讨论技术。我会在第一时间进行解答和交流。我衷心希望Gopher部落可以成为大家学习、进步、交流的港湾
。让我相聚在Gopher部落,享受coding的快乐! 欢迎大家踊跃加入!

img{512x368}
img{512x368}

img{512x368}
img{512x368}

著名云主机服务厂商DigitalOcean发布最新的主机计划,入门级Droplet配置升级为:1 core CPU、1G内存、25G高速SSD,价格5$/月。有使用DigitalOcean需求的朋友,可以打开这个链接地址:https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

Gopher Daily(Gopher每日新闻) – https://gopherdaily.tonybai.com

我的联系方式:

  • 微博(暂不可用):https://weibo.com/bigwhite20xx
  • 微博2:https://weibo.com/u/6484441286
  • 博客:tonybai.com
  • github: https://github.com/bigwhite
  • Gopher Daily归档 – https://github.com/bigwhite/gopherdaily
  • Gopher Daily Feed订阅 – https://gopherdaily.tonybai.com/feed

商务合作方式:撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

如发现本站页面被黑,比如:挂载广告、挖矿等恶意代码,请朋友们及时联系我。十分感谢! Go语言第一课 Go语言精进之路1 Go语言精进之路2 Go语言编程指南
商务合作请联系bigwhite.cn AT aliyun.com

欢迎使用邮件订阅我的博客

输入邮箱订阅本站,只要有新文章发布,就会第一时间发送邮件通知你哦!

这里是 Tony Bai的个人Blog,欢迎访问、订阅和留言! 订阅Feed请点击上面图片

如果您觉得这里的文章对您有帮助,请扫描上方二维码进行捐赠 ,加油后的Tony Bai将会为您呈现更多精彩的文章,谢谢!

如果您希望通过微信捐赠,请用微信客户端扫描下方赞赏码:

如果您希望通过比特币或以太币捐赠,可以扫描下方二维码:

比特币:

以太币:

如果您喜欢通过微信浏览本站内容,可以扫描下方二维码,订阅本站官方微信订阅号“iamtonybai”;点击二维码,可直达本人官方微博主页^_^:
本站Powered by Digital Ocean VPS。
选择Digital Ocean VPS主机,即可获得10美元现金充值,可 免费使用两个月哟! 著名主机提供商Linode 10$优惠码:linode10,在 这里注册即可免费获 得。阿里云推荐码: 1WFZ0V立享9折!


View Tony Bai's profile on LinkedIn
DigitalOcean Referral Badge

文章

评论

  • 正在加载...

分类

标签

归档



View My Stats