SuperObject:Delphi/Pascal 中最好用的 JSON 处理库
前言
在 Delphi/Object Pascal 的世界里,JSON 早已成为与后端 API 交互、处理配置、序列化数据的标准格式。虽然官方从 Delphi XE 起提供了 System.JSON,但很多老手依然对 SuperObject 情有独钟。它轻量、无依赖、语法优雅,即使今天看来,仍然是一个非常优秀的 JSON 库。
项目地址:https://github.com/frostney/superobject
(注:原始版本由 Henri Gourvest 开发,GitHub 上存在多个维护分支,frostney 的仓库是其中之一。)
什么是 SuperObject
SuperObject 是一个纯 Pascal 实现的 JSON 解析与生成库,兼容 Delphi 与 Free Pascal(FPC)。它的核心设计理念非常明确:
- 零第三方依赖:单文件即可编译,不需要额外的 DLL 或包。
- 统一的对象模型:JSON 的任何值(对象、数组、字符串、数字、布尔、null)都由同一个
ISuperObject接口表示。 - 链式调用:支持
obj.S['key']、obj.A['list']等便捷语法,写起来像脚本语言。 - 双向转换:支持 JSON 与 Pascal 的 RTTI 结构互相序列化,也支持 XML 与 JSON 互转。
它支持 JSON 的 JSON-RPC、JSONPath 子集,甚至自带了一个基于 JSON 的模板语法(TSuperObject 的格式化功能)。
快速上手
解析 JSON
uses
superobject;
var
obj: ISuperObject;
begin
obj := SO('{"name":"Pascal","version":3.2,"tags":["json","delphi"]}');
WriteLn(obj.S['name']); // Pascal
WriteLn(obj.D['version']); // 3.2
WriteLn(obj.A['tags'].S[0]); // json
end;
SO() 函数是 SuperObject 最常用的”入口”函数,它接受字符串并返回一个 ISuperObject。
构建 JSON
var obj: ISuperObject; begin obj := TSuperObject.Create; obj.S['name'] := 'Delphi'; obj.I['year'] := 2024; obj.B['active'] := True; WriteLn(obj.AsJSon(True)); // 带缩进输出 end;
数组操作
var
arr: ISuperObject;
begin
arr := SA([]); // 创建空数组
arr.AsArray.Add(SO('"a"'));
arr.AsArray.Add(SO('1'));
// 遍历
for var item in arr do
WriteLn(item.AsString);
end;
核心 API 一览
SuperObject 提供的访问器命名非常直观,记住几个缩写就够用了:
| 访问器 | 含义 | 示例 |
|---|---|---|
S['key'] |
String | obj.S['name'] |
I['key'] |
Integer | obj.I['age'] |
D['key'] |
Double | obj.D['price'] |
B['key'] |
Boolean | obj.B['flag'] |
A['key'] |
Array | obj.A['items'] |
O['key'] |
Object | obj.O['user'] |
N['key'] |
Null 检测 | obj.N['field'] |
对应 .AsString、.AsInteger、.AsDouble、.AsBoolean、.AsArray、.AsObject,以及 Nil 判断。
读取与写入共用同一个符号——给属性赋值时它就是 setter,取值时它就是 getter。这种设计极大简化了代码:
obj.S['title'] := 'Hello'; // 写入
s := obj.S['title']; // 读取
obj.A['list'].Add(SO('42')); // 数组追加
与 Pascal 对象/记录的互转
SuperObject 支持通过 RTTI 自动把类或者记录映射成 JSON:
type
TPerson = class
private
FName: string;
FAge: Integer;
published
property Name: string read FName write FName;
property Age: Integer read FAge write FAge;
end;
var
p: TPerson;
obj: ISuperObject;
begin
p := TPerson.Create;
p.Name := 'Alice';
p.Age := 30;
obj := TSuperObject.Create(TSuperTypeInfo(p.ClassInfo));
obj.FromObject(p); // 对象 -> JSON
WriteLn(obj.AsJSon);
obj.ToObject(p); // JSON -> 对象
end;
注意:published 属性是必须的,因为 RTTI 依赖它。这一机制在配置读写、Web 服务响应封装等场景非常好用。
JSONPath 与查询
SuperObject 内置了一个简化的 JSONPath 支持,可以方便地从深层结构里取数据:
obj := SO('{"data":{"users":[{"name":"A"},{"name":"B"}]}}');
WriteLn(obj.S['data.users[1].name']); // B
路径用点号分隔,数组用 [index] 下标。虽然不如完整 JSONPath 强大,但覆盖了日常绝大多数场景。
XML 与 YAML
这也是 SuperObject 的隐藏彩蛋:它内置了 XML 与 YAML 的读取/输出能力(obj.AsXML、TSuperObject.ParseXML 等)。跨格式转换时可以直接用:
obj := TSuperObject.ParseXML('<root><a>1</a></root>');
WriteLn(obj.AsJSon);
对于需要对接旧系统 XML 接口的项目,这能省去不少手写解析器的麻烦。
优点与局限
优点:
- 单文件(
superobject.pas+ 少量依赖),拖入项目即刻可用。 - 接口式设计(
ISuperObject引用计数),无需手动释放。 - 链式语法写起来非常顺手,代码量小。
- 支持 Delphi、FPC、Lazarus,跨平台无障碍。
- 同时处理 JSON、XML、YAML,格式互换方便。
局限:
- 原始项目多年未大改,对 Unicode 的支持在老版本 Delphi 上略有坑(新版问题不大)。
- 对超大 JSON(数百 MB)性能不如专门的流式解析器(如 Simon Choi 的
JsonDataObjects)。 - JSONPath 实现有限,复杂查询需要自己遍历。
- 接口并非线程安全,多线程解析需要隔离实例。
什么时候选它?
- 项目还在用 Delphi 7 ~ XE 之前 的版本:
System.JSON不可用,SuperObject 是首选。 - 想要 单文件引入、零配置 的库:直接拖
superobject.pas进项目。 - 需要对 JSON/XML 双向转换:内置支持很香。
- 需要 轻量、代码短 的快速 JSON 处理:链式语法省心。
- 但如果项目是 海量数据流式处理 或需要 严格的现代 JSON 规范,可考虑
System.JSON(官方)或JsonDataObjects(性能派)。
结语
SuperObject 是 Pascal 生态里少见的”用起来像动态语言”的库。它把 JSON 的各种细节包装成简洁的接口,让开发者专注业务逻辑而非格式处理。即使官方 System.JSON 已很成熟,SuperObject 依然凭其 单文件、易用、跨格式 的特点活跃在大量遗留项目和 FPC 项目中。
如果你维护的是老 Delphi 代码或需要快速集成 JSON 能力,不妨给这个老而弥坚的库一次机会——克隆 frostney/superobject,把 superobject.pas 加入工程,SO() 一下,你会爱上那种简洁。



还没有评论,来说两句吧...