本文永久链接 – https://tonybai.com/2025/03/11/building-effective-agents

近来，人工智能领域再次风起云涌，各种能力超强的大模型、创新概念和工具层出不穷，让人目不暇接。从DeepSeek发布的开源MoE 模型DeepSeek-V3和令人惊艳的具备深度思考能力的推理模型DeepSeek R1，到声称是“世界上第一个通用AI智能体(Agent)”的Manus以及其开源复刻品OpenManus，再到Anthropic推出让业界大牛程序员Steve Yegge都感到惊叹的Claude Code代码辅助编写Agent工具以及其使用的模型上下文协议（MCP），以及Docker之父Solomon Hykes的Dagger项目转型构建AI Agent工具，无不预示着AI Agent时代的加速到来。

在这一波澜壮阔的技术浪潮中，如何构建高效、可靠且易于维护的AI Agent系统，成为了开发者们共同关注的焦点。Anthropic作为大模型领域的领军企业之一，其在构建AI Agent方面的经验和见解，无疑具有重要的参考价值。

本文翻译自Anthropic官方博客文章《Building Effective AI Agents》，旨在分享Anthropic在与客户合作以及自身实践中总结出的AI Agent构建经验。原文深入探讨了Agentic Systems的概念、架构、常见模式、最佳实践以及工具开发等关键问题，并提供了实用的建议和案例。

选择翻译这篇文章，不仅仅是因为它内容翔实、具有指导意义，更是出于“翻译中学习，学习中翻译”的初衷。通过对原文的翻译，同时也是一次深入学习和理解AI Agent构建技术的绝佳机会。希望本文的翻译能够为广大中文读者提供有益的参考，共同探索AI Agent的无限可能。

注：原文发表于2024年12月中旬，网络上有过很多中文译版，如果你曾阅读过那些文章，你大可忽略本篇文章。

以下是文章正文。

在过去的一年里，我们与数十个团队合作，在各个行业构建大型语言模型 (LLM) 智能体 (Agents)。最成功的那些实现并没有使用复杂的框架或专用库。相反，他们都是使用简单、可组合的模式进行构建的。

在这篇文章中，我们将分享与客户合作和自行构建智能体过程中所学到的知识，并为开发者提供构建高效智能体的实用建议。

什么是智能体？

“智能体(Agent)” 可以有多种定义方式。一些客户将智能体定义为完全自主的系统，它们可以在较长时间内独立运行，使用各种工具来完成复杂的任务。另一些客户则使用该术语来描述遵循预定义工作流的更规范性的实现。在Anthropic，我们将所有这些变体归类为智能体系统(agentic systems)，但在工作流(workflows)和智能体(agents)之间做了重要的架构区分：

• 工作流是通过预定义的代码路径编排LLM和工具的系统。
• 智能体则是LLM动态指导自身流程和工具使用的系统，控制它们完成任务的方式。

下面，我们将详细探讨这两种类型的智能体系统。在附录1（“智能体的实践应用”）中，我们描述了客户发现使用这些系统特别有价值的两个领域。

何时（以及何时不）使用智能体

在使用LLM构建应用程序时，我们建议找到尽可能简单的解决方案，并且仅在需要时才增加复杂性。这可能意味着根本不需要构建智能体系统。智能体系统通常会牺牲延迟和成本来换取更好的任务性能，你应该考虑这种权衡何时有意义。

当需要更多复杂性时，工作流为定义明确的任务提供可预测性和一致性，而当需要大规模的灵活性和模型驱动的决策时，智能体是更好的选择。然而，对于许多应用程序来说，使用检索和上下文示例优化单个LLM调用通常就足够了。

何时以及如何使用框架

有许多框架可以更容易地实现智能体系统，包括：

• LangChain的LangGraph；
• Amazon Bedrock的AI Agent framework；
• Rivet，一个拖放式GUI LLM工作流构建器；以及
• Vellum，另一个用于构建和测试复杂工作流的GUI工具。

这些框架通过简化标准低级任务（如调用LLM、定义和解析工具以及将调用链接在一起）使入门变得容易。然而，它们通常会创建额外的抽象层，这可能会掩盖底层的提示和响应，使它们更难调试。它们还可能诱使在更简单的设置就足够的情况下增加复杂性。

我们建议开发者首先直接使用LLM API：许多模式可以在几行代码中实现。如果你确实使用了框架，请确保你了解底层代码。对底层内容的错误假设是客户错误的常见来源。

请参阅我们的cookbook 以获取一些示例实现。

构建块(Building Blocks)、工作流和智能体

在本节中，我们将探讨我们在生产中看到的智能体系统的常见模式。我们将从基础构建块——增强型LLM——开始，并逐步增加复杂性，从简单的组合工作流到自主智能体。

构建块：增强型LLM

智能体系统的基本构建块是经过增强的LLM，增强功能包括检索、工具和记忆。我们目前的模型可以主动使用这些功能——生成自己的搜索查询、选择合适的工具以及确定要保留的信息。

我们建议重点关注实现的两个关键方面：根据你的特定用例定制这些功能，并确保它们为你的LLM提供简单、文档齐全的接口。虽然有很多方法可以实现这些增强，但有一种方法是通过我们最近发布的Model Context Protocol，它允许开发者通过简单的客户端实现 与不断增长的第三方工具生态系统集成。

在本文的其余部分，我们将假设每次LLM调用都可以访问这些增强功能。

工作流：提示链(Prompt Chaining)

提示链将任务分解为一系列步骤，其中每个LLM调用处理前一个调用的输出。你可以在任何中间步骤上添加程序化检查（参见下图中的“Gate”），以确保流程仍在正轨上。

何时使用此工作流： 当任务可以轻松干净地分解为固定的子任务时，此工作流非常理想。主要目标是通过使每个LLM调用成为更简单的任务来权衡延迟以获得更高的准确性。

提示链有用的示例：

• 生成营销文案，然后将其翻译成不同的语言。
• 编写文档大纲，检查大纲是否符合特定条件，然后根据大纲编写文档。

工作流：路由(Routing)

路由对输入进行分类并将其定向到专门的后续任务。此工作流允许分离关注点，并构建更专业的提示。如果没有此工作流，针对一种类型的输入进行优化可能会损害其他输入的性能。

何时使用此工作流： 路由适用于存在不同类别的复杂任务，这些类别最好单独处理，并且可以使用LLM或更传统的分类模型/算法准确地进行分类。

路由有用的示例：

• 将不同类型的客户服务查询（一般问题、退款请求、技术支持）定向到不同的下游流程、提示和工具。
• 将简单/常见问题路由到较小的模型（如Claude 3.5 Haiku），将困难/不常见问题路由到功能更强大的模型（如Claude 3.5 Sonnet），以优化成本和速度。

工作流：并行化(Parallelization)

LLM有时可以并行处理多个任务，并以编程方式聚合它们的输出。这种工作流（并行化）体现在两个关键变体中：

• 分段(Sectioning)：将任务分解为并行运行的独立子任务。
• 投票(Voting)：多次运行同一任务以获得不同的输出。

何时使用此工作流： 当可以将划分的子任务并行化以提高速度，或者需要多个视角或尝试以获得更高置信度的结果时，并行化是有效的。对于具有多个考虑因素的复杂任务，LLM通常在每个考虑因素由单独的LLM调用处理时表现更好，从而可以集中关注每个特定方面。

并行化有用的示例：

• 分段：
  • 实现防护措施，其中一个模型实例处理用户查询，而另一个模型实例筛选不当内容或请求。这往往比让同一个LLM调用同时处理护栏和核心响应效果更好。
  • 自动评估LLM性能，其中每个LLM调用评估模型在给定提示上的性能的不同方面。
• 投票：
  • 审查一段代码是否存在漏洞，其中几个不同的提示会审查代码，如果发现问题则标记。
  • 评估给定内容是否不当，其中多个提示评估不同的方面或需要不同的投票阈值来平衡误报和漏报。

工作流：编排器-工作者(Orchestrator-Workers)

在编排器-工作者工作流中，中央LLM动态分解任务，将它们委托给工作者LLM，并综合它们的结果。

何时使用此工作流： 此工作流非常适合你无法预测所需子任务的复杂任务（例如，在编码中，需要更改的文件数量以及每个文件中更改的性质可能取决于任务）。虽然在拓扑上相似，但它与并行化工作流的关键区别在于其灵活性——子任务不是预先定义的，而是由编排器根据特定输入确定的。

编排器-工作器有用的示例：

• 每次对多个文件进行复杂更改的编码产品。
• 搜索任务涉及收集和分析来自多个来源的信息以获取可能的相关信息。

工作流：评估器-优化器(Evaluator-Optimizer)

在评估器-优化器工作流中，一个LLM调用生成响应，而另一个LLM调用提供循环评估和反馈。

何时使用此工作流： 当我们有明确的评估标准，并且迭代改进提供可衡量的价值时，此工作流特别有效。良好匹配的两个迹象是，首先，当人类阐明他们的反馈时，LLM响应可以得到明显改善；其次，LLM可以提供此类反馈。这类似于人类作家在撰写精美文档时可能经历的迭代写作过程。

评估器-优化器有用的示例：

• 文学翻译，其中存在翻译器LLM最初可能无法捕捉到的细微差别，但评估器LLM可以提供有用的批评。
• 复杂的搜索任务，需要多轮搜索和分析才能收集全面的信息，评估器决定是否需要进一步搜索。

智能体(Agents)

随着LLM在关键功能（理解复杂输入、参与推理和规划、可靠地使用工具以及从错误中恢复）方面的成熟，智能体正在生产中出现。智能体通过人类用户的命令或交互式讨论开始其工作。一旦任务明确，智能体就会独立计划和操作，可能会返回给人类以获取更多信息或判断。在执行期间，智能体在每个步骤中从环境中获得“真实情况”（例如工具调用结果或代码执行）以评估其进度。然后，智能体可以在检查点或遇到障碍时暂停以获取人类反馈。任务通常在完成后终止，但通常也包含停止条件（例如最大迭代次数）以保持控制。

智能体可以处理复杂的任务，但它们的实现通常很简单。它们通常只是LLM在循环中根据环境反馈使用工具。因此，清晰而周到地设计工具集及其文档至关重要。我们在附录2（“提示工程你的工具”）中扩展了工具开发的最佳实践。

何时使用智能体： 智能体可用于难以或无法预测所需步骤数量的开放式问题，以及你无法硬编码固定路径的问题。LLM可能会运行多个回合，你必须对其决策制定有一定程度的信任。智能体的自主性使其成为在受信任环境中扩展任务的理想选择。

智能体的自主性意味着更高的成本，以及潜在的复合错误。我们建议在沙盒环境中进行广泛测试，并采取适当的护栏。

智能体有用的示例：

以下示例来自我们自己的实现：

• 一个用于解决SWE-bench任务 的编码智能体，它涉及根据任务描述编辑许多文件；
• 我们的“计算机使用”参考实现，其中Claude使用计算机来完成任务。

组合和定制这些模式

这些构建块不是规定性的。它们是开发人员可以塑造和组合以适应不同用例的常见模式。与任何LLM功能一样，成功的关键在于衡量性能并迭代实现。再次强调：你应该考虑仅在可以证明改进结果时才增加复杂性。

总结

LLM领域的成功不在于构建最复杂的系统。它在于构建适合你需求的系统。从简单的提示开始，通过全面的评估优化它们，并且仅在更简单的解决方案不足时才添加多步骤智能体系统。

在实施智能体时，我们尝试遵循三个核心原则：

1. 在智能体的设计中保持简单性。
2. 通过明确显示智能体的规划步骤来优先考虑透明度。
3. 通过彻底的工具文档和测试来仔细设计你的智能体-计算机接口(ACI)。

框架可以帮助你快速入门，但在转向生产时，请毫不犹豫地减少抽象层并使用基本组件进行构建。通过遵循这些原则，你可以创建不仅强大而且可靠、可维护并受到用户信任的智能体。

致谢

本文由Erik Schluntz和Barry Zhang撰写。这项工作借鉴了我们在Anthropic构建智能体的经验以及客户分享的宝贵见解，我们对此深表感谢。

附录1：智能体的实际应用

我们与客户的合作揭示了AI智能体的两个特别有前景的应用，它们展示了上述模式的实用价值。这两个应用都说明了智能体如何为需要对话和行动、具有明确的成功标准、启用反馈循环以及集成有意义的人类监督的任务增加最大价值。

A. 客户支持

客户支持将熟悉的聊天机器人界面与通过工具集成增强的功能相结合。这非常适合更开放式的智能体，因为：

• 支持交互自然地遵循对话流程，同时需要访问外部信息和操作；
• 可以集成工具来提取客户数据、订单历史记录和知识库文章；
• 可以以编程方式处理诸如发放退款或更新工单之类的操作；以及
• 可以通过用户定义的解决方案明确衡量成功。

一些公司已经通过基于使用量的定价模型证明了这种方法的可行性，该模型仅对成功的解决方案收费，表明对他们智能体的有效性充满信心。

B. 编码智能体

软件开发领域已经显示出LLM功能的巨大潜力，其功能从代码完成发展到自主解决问题。智能体特别有效，因为：

• 代码解决方案可以通过自动化测试进行验证；
• 智能体可以使用测试结果作为反馈来迭代解决方案；
• 问题空间定义明确且结构化；以及
• 可以客观地衡量输出质量。

在我们自己的实现中，智能体现在可以根据拉取请求描述本身解决SWE-bench Verified 基准测试中的真实GitHub问题。然而，虽然自动化测试有助于验证功能，但人工审查对于确保解决方案与更广泛的系统要求保持一致仍然至关重要。

附录2：提示工程你的工具

无论你构建哪种智能体系统，工具都可能是智能体的重要组成部分。工具 使Claude能够通过在我们的API中指定其确切结构和定义来与外部服务和API交互。当Claude响应时，如果它计划调用工具，它将在API响应中包含一个工具使用块。工具定义和规范应该像你的整体提示一样受到提示工程的重视。在这个简短的附录中，我们将描述如何提示工程化你的工具。

通常有几种方法可以指定相同的操作。例如，你可以通过编写diff或重写整个文件来指定文件编辑。对于结构化输出，你可以在markdown或JSON中返回代码。在软件工程中，像这样的差异是表面上的，并且可以从一种格式无损地转换为另一种格式。然而，某些格式比其他格式更难让LLM编写。编写diff需要在编写新代码之前知道块头(chunk header)中更改的行数。在JSON中编写代码（与markdown相比）需要对换行符和引号进行额外的转义。

我们对决定工具格式的建议如下：

• 给模型足够的token来“思考”，然后再将自己逼入绝境。
• 保持格式接近模型在互联网文本中自然看到的内容。
• 确保没有格式“开销”，例如必须准确计算数千行代码，或对它编写的任何代码进行字符串转义。

一个经验法则是考虑在人机界面(HCI)上投入了多少精力，并计划在创建良好的智能体-计算机界面 (ACI) 上投入同样多的精力。以下是关于如何做到这一点的一些想法：

• 设身处地为模型着想。根据描述和参数，是否明显知道如何使用此工具，或者你是否需要仔细考虑？如果是这样，那么对于模型来说可能也是如此。一个好的工具定义通常包括示例用法、边缘情况、输入格式要求以及与其他工具的明确边界。
• 你如何更改参数名称或描述以使事情更明显？将其视为为你团队中的初级开发人员编写出色的文档字符串。在使用许多类似的工具时，这一点尤其重要。
• 测试模型如何使用你的工具：在我们的workbench中运行许多示例输入，以查看模型犯了哪些错误，并进行迭代。
• 防呆(Poka-yoke) 你的工具。更改参数以使其更难出错。

在为SWE-bench 构建我们的智能体时，我们实际上花了更多时间优化我们的工具而不是整体提示。例如，我们发现，在智能体移出根目录后，使用相对文件路径的工具会出现错误。为了解决这个问题，我们将工具更改为始终需要绝对文件路径——并且我们发现模型完美地使用了这种方法。

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

著名云主机服务厂商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

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

本文永久链接 – 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. 参考资料

• proposal: encoding/json/v2: new API for encoding/json – https://github.com/golang/go/issues/71497
• discussions: encoding/json/v2 – https://github.com/golang/go/discussions/63397
• GopherCon 2023: The Future of JSON in Go – Joe Tsai – https://www.youtube.com/watch?v=avilmOcHKHE
• json/v2参考实现 – https://github.com/go-json-experiment/json
• json/v2 benchmark – https://github.com/go-json-experiment/jsonbench

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

著名云主机服务厂商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

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