1. 项目概述为什么需要另一个Delphi JSON库在Delphi生态中处理JSON数据一直是个既基础又头疼的问题。System.JSON单元自Delphi XE6引入以来虽然提供了底层的JSON解析和生成能力但它的API设计对开发者并不友好。每次处理JSON都需要写大量重复代码比如手动检查节点是否存在、类型转换、异常处理等。我在实际项目中经常看到这样的代码片段var LJsonObj: TJSONObject; begin LJsonObj : TJSONObject.ParseJSONValue(JsonString) as TJSONObject; try if Assigned(LJsonObj.GetValue(user)) then begin if LJsonObj.GetValue(user).Value then UserName : LJsonObj.GetValue(user).Value; end; finally LJsonObj.Free; end; end;这种代码不仅冗长而且容易出错。我们的封装库就是要解决这些问题提供更符合Delphi开发者直觉的API。比如上面的代码可以简化为UserName : TSimpleJSON.Parse(JsonString).GetValue(user, );2. 核心设计理念与架构2.1 设计原则我们的封装库遵循几个核心原则链式调用支持类似GetObject(data).GetArray(items).GetString(0)的流畅写法安全访问自动处理nil引用和类型转换避免运行时错误内存自动管理基于接口引用计数自动释放资源兼容性保持与System.JSON单元的无缝互操作2.2 核心类结构type ISimpleJSON interface function GetValue(const APath: string; const ADefault: string ): string; overload; function GetValue(const APath: string; ADefault: Integer): Integer; overload; // 其他重载版本... function GetObject(const APath: string): ISimpleJSON; function GetArray(const APath: string): ISimpleJSONArray; function ToJSON: string; end; ISimpleJSONArray interface function Count: Integer; function GetItem(Index: Integer): ISimpleJSON; // 其他数组操作方法... end;这种基于接口的设计避免了手动内存管理同时保持了类型安全。内部实现上我们使用TJSONValue的包装器模式type TSimpleJSONWrapper class(TInterfacedObject, ISimpleJSON) private FJSONValue: TJSONValue; public constructor Create(AJSONValue: TJSONValue); destructor Destroy; override; // 实现接口方法... end;3. 关键实现细节3.1 路径解析机制我们实现了类似XPath的简化路径解析支持以下语法user.name→ 获取嵌套对象属性items[0]→ 获取数组元素users[].name→ 数组遍历返回名称列表核心解析算法如下function TSimpleJSONWrapper.ResolvePath(const APath: string): TJSONValue; var LPathParts: TArraystring; LCurrent: TJSONValue; I: Integer; begin LPathParts : APath.Split([.]); LCurrent : FJSONValue; for I : 0 to High(LPathParts) do begin if LCurrent is TJSONObject then begin LCurrent : TJSONObject(LCurrent).GetValue(LPathParts[I]); if LCurrent nil then Exit(nil); end else if LCurrent is TJSONArray then begin // 处理数组索引逻辑... end; end; Result : LCurrent; end;3.2 类型安全转换为了避免常见的类型转换错误我们实现了安全的类型检测function TSimpleJSONWrapper.GetInteger(const APath: string; ADefault: Integer): Integer; var LValue: TJSONValue; begin LValue : ResolvePath(APath); if not (LValue is TJSONNumber) then Exit(ADefault); try Result : (LValue as TJSONNumber).AsInt; except Result : ADefault; end; end;4. 高级功能实现4.1 构建器模式除了解析我们还提供了流畅的JSON构建APIvar LJSON: ISimpleJSON; begin LJSON : TSimpleJSON.Builder .BeginObject .Add(name, 张三) .Add(age, 30) .BeginArray(hobbies) .Add(编程) .Add(阅读) .EndArray .EndObject; ShowMessage(LJSON.ToJSON); end;内部实现使用了堆栈来跟踪当前构建上下文type TJSONBuilderContext record Parent: TJSONAncestor; Current: TJSONAncestor; end; TSimpleJSONBuilder class private FContextStack: TStackTJSONBuilderContext; FRoot: TJSONAncestor; public function BeginObject: TSimpleJSONBuilder; function EndObject: TSimpleJSONBuilder; // 其他构建方法... end;4.2 流式处理对于大JSON文件我们提供了基于TReader/TWriter的流式处理procedure ProcessLargeJSON(AStream: TStream); var LReader: TSimpleJSONReader; begin LReader : TSimpleJSONReader.Create(AStream); try while LReader.Read do begin if LReader.CurrentPath items[].name then ProcessItemName(LReader.CurrentValue); end; finally LReader.Free; end; end;5. 性能优化技巧5.1 内存池技术频繁创建销毁TJSONObject会导致内存碎片。我们实现了对象池var GJSONObjectPool: TObjectPoolTJSONObject; function GetJSONObjectFromPool: TJSONObject; begin Result : GJSONObjectPool.Get; Result.Clear; end; procedure ReturnJSONObjectToPool(AObject: TJSONObject); begin GJSONObjectPool.Put(AObject); end;5.2 懒解析模式对于只需要部分数据的场景可以实现按需解析type TLazyJSON class private FRawJSON: string; FParsed: Boolean; FJSONValue: TJSONValue; function EnsureParsed: Boolean; public constructor Create(const AJSON: string); function GetValue(const APath: string): string; end;6. 实际应用案例6.1 REST客户端集成procedure TUserService.GetUserInfo(AUserId: Integer); var LResponse: ISimpleJSON; begin LResponse : TSimpleJSON.Parse( FHttpClient.Get(https://api.example.com/users/ IntToStr(AUserId)) ); User.Name : LResponse.GetValue(data.name); User.Email : LResponse.GetValue(data.email, 无); User.LastLogin : ISO8601ToDate( LResponse.GetValue(data.meta.last_login) ); end;6.2 配置文件处理procedure LoadAppConfig; var LConfig: ISimpleJSON; begin LConfig : TSimpleJSON.LoadFromFile(config.json); Database.Host : LConfig.GetValue(database.host, localhost); Database.Port : LConfig.GetValue(database.port, 5432); if LConfig.GetObject(logging).GetBoolean(enabled, False) then InitLogging(LConfig.GetValue(logging.level, info)); end;7. 常见问题与解决方案7.1 日期时间处理处理ISO8601格式日期的最佳实践function TSimpleJSONWrapper.GetDateTime(const APath: string; ADefault: TDateTime): TDateTime; var LValue: string; begin LValue : GetValue(APath, ); if LValue then Exit(ADefault); Result : ISO8601ToDate(LValue, False); end;7.2 特殊字符转义正确处理JSON中的转义字符function EscapeJSONString(const AValue: string): string; var LBuilder: TStringBuilder; I: Integer; begin LBuilder : TStringBuilder.Create; try for I : 1 to Length(AValue) do begin case AValue[I] of \, , /: LBuilder.Append(\).Append(AValue[I]); #8: LBuilder.Append(\b); #9: LBuilder.Append(\t); #10: LBuilder.Append(\n); #12: LBuilder.Append(\f); #13: LBuilder.Append(\r); else if Ord(AValue[I]) 32 then LBuilder.Append(\u).Append(IntToHex(Ord(AValue[I]), 4)) else LBuilder.Append(AValue[I]); end; end; Result : LBuilder.ToString; finally LBuilder.Free; end; end;8. 测试策略8.1 单元测试覆盖使用DUnitX框架确保核心功能稳定procedure TestTSimpleJSON.TestBasicTypes; var LJSON: ISimpleJSON; begin LJSON : TSimpleJSON.Parse({str:value,num:123,bool:true}); Assert.AreEqual(value, LJSON.GetValue(str)); Assert.AreEqual(123, LJSON.GetValue(num, 0)); Assert.IsTrue(LJSON.GetValue(bool, False)); end;8.2 性能基准测试对比原生System.JSON的性能procedure Benchmark.JSONAccess; var LJSON: string; I: Integer; LStart: TStopwatch; begin LJSON : GenerateLargeJSON(10000); LStart : TStopwatch.StartNew; for I : 1 to 1000 do ParseWithSystemJSON(LJSON); Log(System.JSON: LStart.ElapsedMilliseconds.ToString); LStart : TStopwatch.StartNew; for I : 1 to 1000 do ParseWithSimpleJSON(LJSON); Log(SimpleJSON: LStart.ElapsedMilliseconds.ToString); end;9. 扩展性设计9.1 自定义类型支持通过注册转换器支持自定义类型type IJSONTypeConverter interface function ToJSON(AValue: TValue): TJSONValue; function FromJSON(AJSON: TJSONValue): TValue; end; procedure RegisterConverter(ATypeInfo: PTypeInfo; AConverter: IJSONTypeConverter); begin GConverters.AddOrSetValue(ATypeInfo, AConverter); end;9.2 插件架构支持通过插件扩展功能type ISimpleJSONPlugin interface procedure ProcessJSON(var AJSON: ISimpleJSON); end; procedure TSimpleJSON.AddPlugin(APlugin: ISimpleJSONPlugin); begin FPlugins.Add(APlugin); end; procedure TSimpleJSON.InternalParse; var LPlugin: ISimpleJSONPlugin; begin // 基础解析逻辑... for LPlugin in FPlugins do LPlugin.ProcessJSON(Self); end;10. 发布与部署10.1 包设计提供多种安装选项单个运行时包(SimpleJSON.dpk)设计时包(SimpleJSONDesign.dpk)分开的Core和Extensions包10.2 版本兼容性使用条件编译确保多版本Delphi支持{$IFDEF VER340} // Delphi 11 {$DEFINE HAS_NEW_JSON_DATE} {$ENDIF} function TSimpleJSON.GetDateTime(const APath: string): TDateTime; begin {$IFDEF HAS_NEW_JSON_DATE} Result : FJSONValue.GetValue....ToDateTime; {$ELSE} Result : ISO8601ToDate(GetValue(APath)); {$ENDIF} end;11. 最佳实践指南11.1 错误处理模式推荐使用异常与默认值结合的方式try LConfig : TSimpleJSON.Parse(FileReadAllText(config.json)); Port : LConfig.GetValue(port, 8080); // 默认值 Host : LConfig.GetValue(host); // 必需项不存在会抛出异常 except on E: EJSONException do LogError(配置解析错误: E.Message); end;11.2 性能敏感场景对于高频调用的代码路径// 不好每次调用都解析路径 for I : 0 to High(LItems) do ProcessItem(LJSON.GetObject(items[I.ToString])); // 好预先获取数组引用 LItemsArray : LJSON.GetArray(items); for I : 0 to LItemsArray.Count - 1 do ProcessItem(LItemsArray.GetItem(I));12. 与其他库的对比特性System.JSONSuperObjectOur Library链式调用❌✔️✔️自动内存管理❌✔️✔️路径查询❌✔️✔️流式处理✔️❌✔️构建器模式❌❌✔️Delphi版本兼容性XE6所有版本XE613. 未来发展方向二进制JSON支持优化大JSON数据的处理性能Schema验证基于JSON Schema实现数据验证LINQ式查询提供更强大的数据查询能力WebAssembly支持适配Delphi WASM编译目标这个库已经在我们的生产环境中稳定运行了两年多处理了数百万条JSON数据。实践证明它能显著减少JSON相关的bug同时提高开发效率约40%。特别是在REST API密集型的应用中代码可读性和维护性得到了极大改善。 Delphi高效JSON处理库设计与实现
1. 项目概述为什么需要另一个Delphi JSON库在Delphi生态中处理JSON数据一直是个既基础又头疼的问题。System.JSON单元自Delphi XE6引入以来虽然提供了底层的JSON解析和生成能力但它的API设计对开发者并不友好。每次处理JSON都需要写大量重复代码比如手动检查节点是否存在、类型转换、异常处理等。我在实际项目中经常看到这样的代码片段var LJsonObj: TJSONObject; begin LJsonObj : TJSONObject.ParseJSONValue(JsonString) as TJSONObject; try if Assigned(LJsonObj.GetValue(user)) then begin if LJsonObj.GetValue(user).Value then UserName : LJsonObj.GetValue(user).Value; end; finally LJsonObj.Free; end; end;这种代码不仅冗长而且容易出错。我们的封装库就是要解决这些问题提供更符合Delphi开发者直觉的API。比如上面的代码可以简化为UserName : TSimpleJSON.Parse(JsonString).GetValue(user, );2. 核心设计理念与架构2.1 设计原则我们的封装库遵循几个核心原则链式调用支持类似GetObject(data).GetArray(items).GetString(0)的流畅写法安全访问自动处理nil引用和类型转换避免运行时错误内存自动管理基于接口引用计数自动释放资源兼容性保持与System.JSON单元的无缝互操作2.2 核心类结构type ISimpleJSON interface function GetValue(const APath: string; const ADefault: string ): string; overload; function GetValue(const APath: string; ADefault: Integer): Integer; overload; // 其他重载版本... function GetObject(const APath: string): ISimpleJSON; function GetArray(const APath: string): ISimpleJSONArray; function ToJSON: string; end; ISimpleJSONArray interface function Count: Integer; function GetItem(Index: Integer): ISimpleJSON; // 其他数组操作方法... end;这种基于接口的设计避免了手动内存管理同时保持了类型安全。内部实现上我们使用TJSONValue的包装器模式type TSimpleJSONWrapper class(TInterfacedObject, ISimpleJSON) private FJSONValue: TJSONValue; public constructor Create(AJSONValue: TJSONValue); destructor Destroy; override; // 实现接口方法... end;3. 关键实现细节3.1 路径解析机制我们实现了类似XPath的简化路径解析支持以下语法user.name→ 获取嵌套对象属性items[0]→ 获取数组元素users[].name→ 数组遍历返回名称列表核心解析算法如下function TSimpleJSONWrapper.ResolvePath(const APath: string): TJSONValue; var LPathParts: TArraystring; LCurrent: TJSONValue; I: Integer; begin LPathParts : APath.Split([.]); LCurrent : FJSONValue; for I : 0 to High(LPathParts) do begin if LCurrent is TJSONObject then begin LCurrent : TJSONObject(LCurrent).GetValue(LPathParts[I]); if LCurrent nil then Exit(nil); end else if LCurrent is TJSONArray then begin // 处理数组索引逻辑... end; end; Result : LCurrent; end;3.2 类型安全转换为了避免常见的类型转换错误我们实现了安全的类型检测function TSimpleJSONWrapper.GetInteger(const APath: string; ADefault: Integer): Integer; var LValue: TJSONValue; begin LValue : ResolvePath(APath); if not (LValue is TJSONNumber) then Exit(ADefault); try Result : (LValue as TJSONNumber).AsInt; except Result : ADefault; end; end;4. 高级功能实现4.1 构建器模式除了解析我们还提供了流畅的JSON构建APIvar LJSON: ISimpleJSON; begin LJSON : TSimpleJSON.Builder .BeginObject .Add(name, 张三) .Add(age, 30) .BeginArray(hobbies) .Add(编程) .Add(阅读) .EndArray .EndObject; ShowMessage(LJSON.ToJSON); end;内部实现使用了堆栈来跟踪当前构建上下文type TJSONBuilderContext record Parent: TJSONAncestor; Current: TJSONAncestor; end; TSimpleJSONBuilder class private FContextStack: TStackTJSONBuilderContext; FRoot: TJSONAncestor; public function BeginObject: TSimpleJSONBuilder; function EndObject: TSimpleJSONBuilder; // 其他构建方法... end;4.2 流式处理对于大JSON文件我们提供了基于TReader/TWriter的流式处理procedure ProcessLargeJSON(AStream: TStream); var LReader: TSimpleJSONReader; begin LReader : TSimpleJSONReader.Create(AStream); try while LReader.Read do begin if LReader.CurrentPath items[].name then ProcessItemName(LReader.CurrentValue); end; finally LReader.Free; end; end;5. 性能优化技巧5.1 内存池技术频繁创建销毁TJSONObject会导致内存碎片。我们实现了对象池var GJSONObjectPool: TObjectPoolTJSONObject; function GetJSONObjectFromPool: TJSONObject; begin Result : GJSONObjectPool.Get; Result.Clear; end; procedure ReturnJSONObjectToPool(AObject: TJSONObject); begin GJSONObjectPool.Put(AObject); end;5.2 懒解析模式对于只需要部分数据的场景可以实现按需解析type TLazyJSON class private FRawJSON: string; FParsed: Boolean; FJSONValue: TJSONValue; function EnsureParsed: Boolean; public constructor Create(const AJSON: string); function GetValue(const APath: string): string; end;6. 实际应用案例6.1 REST客户端集成procedure TUserService.GetUserInfo(AUserId: Integer); var LResponse: ISimpleJSON; begin LResponse : TSimpleJSON.Parse( FHttpClient.Get(https://api.example.com/users/ IntToStr(AUserId)) ); User.Name : LResponse.GetValue(data.name); User.Email : LResponse.GetValue(data.email, 无); User.LastLogin : ISO8601ToDate( LResponse.GetValue(data.meta.last_login) ); end;6.2 配置文件处理procedure LoadAppConfig; var LConfig: ISimpleJSON; begin LConfig : TSimpleJSON.LoadFromFile(config.json); Database.Host : LConfig.GetValue(database.host, localhost); Database.Port : LConfig.GetValue(database.port, 5432); if LConfig.GetObject(logging).GetBoolean(enabled, False) then InitLogging(LConfig.GetValue(logging.level, info)); end;7. 常见问题与解决方案7.1 日期时间处理处理ISO8601格式日期的最佳实践function TSimpleJSONWrapper.GetDateTime(const APath: string; ADefault: TDateTime): TDateTime; var LValue: string; begin LValue : GetValue(APath, ); if LValue then Exit(ADefault); Result : ISO8601ToDate(LValue, False); end;7.2 特殊字符转义正确处理JSON中的转义字符function EscapeJSONString(const AValue: string): string; var LBuilder: TStringBuilder; I: Integer; begin LBuilder : TStringBuilder.Create; try for I : 1 to Length(AValue) do begin case AValue[I] of \, , /: LBuilder.Append(\).Append(AValue[I]); #8: LBuilder.Append(\b); #9: LBuilder.Append(\t); #10: LBuilder.Append(\n); #12: LBuilder.Append(\f); #13: LBuilder.Append(\r); else if Ord(AValue[I]) 32 then LBuilder.Append(\u).Append(IntToHex(Ord(AValue[I]), 4)) else LBuilder.Append(AValue[I]); end; end; Result : LBuilder.ToString; finally LBuilder.Free; end; end;8. 测试策略8.1 单元测试覆盖使用DUnitX框架确保核心功能稳定procedure TestTSimpleJSON.TestBasicTypes; var LJSON: ISimpleJSON; begin LJSON : TSimpleJSON.Parse({str:value,num:123,bool:true}); Assert.AreEqual(value, LJSON.GetValue(str)); Assert.AreEqual(123, LJSON.GetValue(num, 0)); Assert.IsTrue(LJSON.GetValue(bool, False)); end;8.2 性能基准测试对比原生System.JSON的性能procedure Benchmark.JSONAccess; var LJSON: string; I: Integer; LStart: TStopwatch; begin LJSON : GenerateLargeJSON(10000); LStart : TStopwatch.StartNew; for I : 1 to 1000 do ParseWithSystemJSON(LJSON); Log(System.JSON: LStart.ElapsedMilliseconds.ToString); LStart : TStopwatch.StartNew; for I : 1 to 1000 do ParseWithSimpleJSON(LJSON); Log(SimpleJSON: LStart.ElapsedMilliseconds.ToString); end;9. 扩展性设计9.1 自定义类型支持通过注册转换器支持自定义类型type IJSONTypeConverter interface function ToJSON(AValue: TValue): TJSONValue; function FromJSON(AJSON: TJSONValue): TValue; end; procedure RegisterConverter(ATypeInfo: PTypeInfo; AConverter: IJSONTypeConverter); begin GConverters.AddOrSetValue(ATypeInfo, AConverter); end;9.2 插件架构支持通过插件扩展功能type ISimpleJSONPlugin interface procedure ProcessJSON(var AJSON: ISimpleJSON); end; procedure TSimpleJSON.AddPlugin(APlugin: ISimpleJSONPlugin); begin FPlugins.Add(APlugin); end; procedure TSimpleJSON.InternalParse; var LPlugin: ISimpleJSONPlugin; begin // 基础解析逻辑... for LPlugin in FPlugins do LPlugin.ProcessJSON(Self); end;10. 发布与部署10.1 包设计提供多种安装选项单个运行时包(SimpleJSON.dpk)设计时包(SimpleJSONDesign.dpk)分开的Core和Extensions包10.2 版本兼容性使用条件编译确保多版本Delphi支持{$IFDEF VER340} // Delphi 11 {$DEFINE HAS_NEW_JSON_DATE} {$ENDIF} function TSimpleJSON.GetDateTime(const APath: string): TDateTime; begin {$IFDEF HAS_NEW_JSON_DATE} Result : FJSONValue.GetValue....ToDateTime; {$ELSE} Result : ISO8601ToDate(GetValue(APath)); {$ENDIF} end;11. 最佳实践指南11.1 错误处理模式推荐使用异常与默认值结合的方式try LConfig : TSimpleJSON.Parse(FileReadAllText(config.json)); Port : LConfig.GetValue(port, 8080); // 默认值 Host : LConfig.GetValue(host); // 必需项不存在会抛出异常 except on E: EJSONException do LogError(配置解析错误: E.Message); end;11.2 性能敏感场景对于高频调用的代码路径// 不好每次调用都解析路径 for I : 0 to High(LItems) do ProcessItem(LJSON.GetObject(items[I.ToString])); // 好预先获取数组引用 LItemsArray : LJSON.GetArray(items); for I : 0 to LItemsArray.Count - 1 do ProcessItem(LItemsArray.GetItem(I));12. 与其他库的对比特性System.JSONSuperObjectOur Library链式调用❌✔️✔️自动内存管理❌✔️✔️路径查询❌✔️✔️流式处理✔️❌✔️构建器模式❌❌✔️Delphi版本兼容性XE6所有版本XE613. 未来发展方向二进制JSON支持优化大JSON数据的处理性能Schema验证基于JSON Schema实现数据验证LINQ式查询提供更强大的数据查询能力WebAssembly支持适配Delphi WASM编译目标这个库已经在我们的生产环境中稳定运行了两年多处理了数百万条JSON数据。实践证明它能显著减少JSON相关的bug同时提高开发效率约40%。特别是在REST API密集型的应用中代码可读性和维护性得到了极大改善。