企业官网建设流程全解析

• 人工智能
• AI Agent
• 多模态
• 语音
• AI 应用

is_structured()是 nlohmann/json 库中用于判定 JSON 值是否为结构化类型（数组或对象）的核心查询接口。本文以 TEN-framework 仓库内集成的 nlohmann_json 源码（位于 third_party/nlohmann_json）为依据，完整讲解该接口的签名、返回值、异常安全与复杂度保证，并结合库内真实实现（json.hpp）与 SAX 解析器内部调用（json_sax.hpp）剖析其底层原理。读完本文，你将掌握如何在 C++ 项目中正确区分 JSON 的原始类型与结构化类型，并理解它与is_primitive()、is_array()、is_object()之间的关系与取舍。

接口声明与基本语义

is_structured()的完整函数签名如下（见 接口文档）：

constexpr bool is_structured() const noexcept;

该函数当且仅当JSON 值的类型为结构化类型（即数组array或对象object）时返回true，其余所有类型一律返回false。它是nlohmann::basic_json的成员函数，通过const限定保证不修改对象自身状态，并且被声明为noexcept，因此可以在常量表达式（constexpr）上下文中使用。

在 TEN-framework 仓库中，nlohmann_json 以第三方依赖形式集成，并被 C++ 集成测试客户端广泛引用，例如 graph_env_var_1 客户端、hello_world 客户端 等测试用例均通过#include <nlohmann/json.hpp>使用该库构造与解析 JSON 消息。理解is_structured()正是正确遍历、校验这类 JSON 载荷的基础。

返回值与 RFC 8259 术语来源

返回值的判定规则可以概括为一句话：

• 类型为array（数组）或object（对象）→ 返回true；
• 其余所有类型（null、boolean、number、string、binary、discarded）→ 返回false。

“结构化（structured）”这一术语源于RFC 8259（The JavaScript Object Notation (JSON) Data Interchange Format）的权威表述：

JSON can represent four primitive types (strings, numbers, booleans, and null) and two structured types (objects and arrays).

也就是说，JSON 规范将类型天然划分为两大类：四种原始类型（字符串、数字、布尔、null）和两种结构化类型（对象、数组）。is_structured()正是对这一规范分类的 C++ 映射。

需要特别强调的是：C++ 中的std::string本质上是容器，但在 JSON 语义中字符串被明确视为原始值。因此一个字符串类型的 JSON 值调用is_structured()会得到false，这与直觉中“字符串是容器”的印象相反，是实际开发中最容易踩中的认知误区。

底层实现：从枚举类型到布尔判定

is_structured()的实现非常直观，源码位于 json.hpp：

/// @brief return whether type is structured constexpr bool is_structured() const noexcept { return is_array() || is_object(); }

其内部只是简单地对is_array()与is_object()两个查询做逻辑或运算。这两个查询最终都归结于对内部类型标记m_data.m_type与value_t枚举值的比较。该枚举定义于 value_t.hpp：

enum class value_t : std::uint8_t { null, ///< null value object, ///< object (unordered set of name/value pairs) array, ///< array (ordered collection of values) string, ///< string value boolean, ///< boolean value number_integer, ///< number value (signed integer) number_unsigned, ///< number value (unsigned integer) number_float, ///< number value (floating-point) binary, ///< binary array (ordered collection of bytes) discarded ///< discarded by the parser callback function };

从源码结构可以推断：由于value_t中共有 10 个枚举成员，而结构化类型仅占其中两个（object与array），is_structured()本质上是在做一次 O(1) 的枚举比较，不涉及任何遍历或分配，这也是文档宣称其**复杂度为常量（Constant）**的根本原因。

值得一提的是，接口文档中“Possible implementation”一节给出的示例代码将函数名误写为is_primitive()（函数体return is_array() || is_object();是正确的），而库内真实实现 json.hpp 的函数名与函数体均正确。实际开发中应以仓库源码为准。

与is_primitive()的互补关系

is_structured()与is_primitive()是一对互补的类型判定接口。is_primitive()的实现同样位于 json.hpp：

/// @brief return whether type is primitive constexpr bool is_primitive() const noexcept { return is_null() || is_string() || is_boolean() || is_number() || is_binary(); }

可见原始类型的判定范围是：null、string、boolean、number（含三种数字子类型）以及 binary。与is_structured()的 array/object 判定范围恰好互补（注意 binary 类型既不算结构化，也不属于 RFC 8259 的四种原始类型，是库的扩展类型，但被归入“非结构化”一侧）。

两者配合使用时，可以高效地对任意 JSON 值进行穷举分类。仓库自带的示例 is_structured.cpp 与 is_primitive.cpp 覆盖了库支持的全部 JSON 类型，是验证两者行为的最佳参考。

异常安全与性能保证

接口文档明确给出了两项关键保证：

• No-throw guarantee（无异常保证）：该成员函数永远不会抛出异常。因为它的实现只包含枚举比较与布尔运算，不涉及内存分配、I/O 或用户回调，任何情况下都不存在抛出路径。
• Constant（常量复杂度）：无论 JSON 值嵌套多深、体量多大，is_structured()的执行时间都是固定的，与数据结构规模无关。

这两项保证意味着is_structured()可以安全地用于性能敏感路径（如热循环中的类型分派）以及异常安全要求严格的代码（如析构函数或noexcept函数内部）。

完整示例：覆盖全部 JSON 类型

仓库提供了可直接编译运行的示例程序 is_structured.cpp：

#include <iostream> #include <nlohmann/json.hpp> using json = nlohmann::json; int main() { // create JSON values json j_null; json j_boolean = true; json j_number_integer = 17; json j_number_float = 23.42; json j_number_unsigned_integer = 12345678987654321u; json j_object = {{"one", 1}, {"two", 2}}; json j_array = {1, 2, 4, 8, 16}; json j_string = "Hello, world"; json j_binary = json::binary({1, 2, 3}); // call is_structured() std::cout << std::boolalpha; std::cout << j_null.is_structured() << '\n'; std::cout << j_boolean.is_structured() << '\n'; std::cout << j_number_integer.is_structured() << '\n'; std::cout << j_number_unsigned_integer.is_structured() << '\n'; std::cout << j_number_float.is_structured() << '\n'; std::cout << j_object.is_structured() << '\n'; std::cout << j_array.is_structured() << '\n'; std::cout << j_string.is_structured() << '\n'; std::cout << j_binary.is_structured() << '\n'; }

程序输出（与 is_structured.output 一致）：

false false false false false true true false false

从输出可以清晰验证：示例中构造的 9 种 JSON 值里，仅有对象（j_object）和数组（j_array）返回true；而 null、两种整数、浮点数、字符串与 binary 全部返回false。std::boolalpha使布尔值以true/false而非1/0的形式打印，便于阅读。

内部应用：SAX 解析器中的结构化判定

is_structured()不仅在用户代码中用于类型查询，也参与库内部解析流程。在 SAX 解析器的end_object()处理中（json_sax.hpp），当解析回调选择丢弃某个值后，需要从父容器中移除被丢弃的元素，其前置条件正是父节点必须是结构化类型：

if (!ref_stack.empty() && ref_stack.back() && ref_stack.back()->is_structured()) { // remove discarded value for (auto it = ref_stack.back()->begin(); it != ref_stack.back()->end(); ++it) { if (it->is_discarded()) { ref_stack.back()->erase(it); break; } } }

从这段实现可以看出：只有数组与对象（即is_structured()为true的容器）才支持迭代与删除操作，而字符串等“C++ 容器”在库的内部处理中同样被视为叶子值。这从侧面印证了“字符串是原始值”的 JSON 语义——结构化类型与“可包含子值的容器”在库内是严格对齐的。

相关 API 与版本演进

is_structured()与以下查询接口共同构成类型自检 API 家族：

实际编码中，若只需区分“是否数组”或“是否对象”，应直接使用更精确的is_array()/is_object()；而is_structured()适合“关心容器与否、不关心容器具体形态”的场景，例如统一处理对象与数组的递归遍历、序列化前的容器校验等。

版本演进方面，is_structured()自nlohmann/json 1.0.0起加入，属于库最早一批公开的类型查询接口，接口形态与语义在后续版本中保持稳定。TEN-framework 仓库集成的 nlohmann_json 位于 third_party/nlohmann_json，包含完整的 include 头文件、文档与可编译示例，读者可直接在仓库内查看源码与测试用例进一步验证本文所述行为。

• 人工智能
• AI Agent
• 多模态
• 语音
• AI 应用