Flutter JSON类型定义插件json_typedef_dart的使用

Flutter JSON类型定义插件json_typedef_dart的使用

JSON Type Definition（简称JTD），即RFC 8927，是一种易于学习且标准化的方法来为JSON数据定义一个模式。您可以使用JSON Typedef在不同的编程语言之间便携地验证数据，生成虚拟数据，生成代码等。

本包是一个Dart/Flutter实现的JSON Type Definition。它允许您根据JSON Type Definition模式验证输入数据。

安装

您可以使用pub安装此包：

flutter pub add json_typedef_dart

基本用法

以下是如何使用此包验证JSON数据的例子：

import 'package:json_typedef_dart/json_typedef_dart.dart';

Json schema = <String, dynamic>{
   "properties": {
      "name": {"type": "string"},
      "age": {"type": "uint32"},
      "phones": {
         "elements": {"type": "string"}
      }
   }
};

void main() {
// validate返回一个包含验证错误的数组。如果输入数据没有问题，则返回空数组。

// 输出: []
   print(validate(schema: schema, data: {
      "name": "John Doe",
      "age": 43,
      "phones": ["+44 1234567", "+44 2345678"],
   }));

// 下一个输入有三个问题：
//
// 1. 缺少必需的属性"name"。
// 2. "age" 是字符串，但应该是整数。
// 3. "phones[1]" 是数字，但应该是字符串。
//
// 每个错误都对应于validate返回的错误之一。

// 输出:
//
// [
//   { instancePath: [], schemaPath: [ 'properties', 'name' ] },
//   {
//     instancePath: [ 'age' ],
//     schemaPath: [ 'properties', 'age', 'type' ]
//   },
//   {
//     instancePath: [ 'phones', '1' ],
//     schemaPath: [ 'properties', 'phones', 'elements', 'type' ]
//   }
// ]
   print(validate(schema: schema, data: {
      "age": "43",
      "phones": ["+44 1234567", 442345678],
   }));
}

高级用法：限制返回的错误数量

默认情况下，validate会返回所有找到的错误。如果您只关心是否有任何错误，或者您不能显示超过一定数量的错误，则可以使用maxErrors选项提高validate的性能。

例如，以前面相同的例子为例，但将其限制为最多1个错误，我们得到：

import 'package:json_typedef_dart/json_typedef_dart.dart';

Json schema = <String, dynamic>{
   "properties": {
      "name": {"type": "string"},
      "age": {"type": "uint32"},
      "phones": {
         "elements": {"type": "string"}
      }
   }
};

void main() {
// 输出:
//
// [ { instancePath: [], schemaPath: [ 'properties', 'name' ] } ]
   print(validate(schema: schema, data: {
      "age": "43",
      "phones": ["+44 1234567", "+44 2345678"],
   }, maxErrors: 1));
}

高级用法：处理不受信任的模式

如果您想针对不受信任的模式运行validate，则应：

1. 使用isValidSchema确保模式格式正确，这会验证诸如确保所有ref都有相应定义之类的事情。
2. 使用maxDepth选项调用validate。JSON Typedef允许编写递归模式——如果您正在评估不受信任的模式，可能会在评估恶意输入时进入无限循环，例如：

   {
     "ref": "loop",
     "definitions": {
       "loop": {
         "ref": "loop"
       }
     }
   }

maxDepth选项告诉jtd.validate在放弃并抛出MaxDepthExceededError之前递归跟踪多少个ref。

以下是如何使用jtd评估不受信任的模式下的数据的例子：

import 'package:json_typedef_dart/json_typedef_dart.dart';

// validateUntrusted 返回true，如果`data`满足`schema`，否则返回false。如果`schema`无效或验证陷入无限循环，则抛出错误。
bool validateUntrusted(Json schema, dynamic data) {
   if (!isValidSchema(schema)) {
      throw Exception("invalid schema");
   }

// 您应该将maxDepth调整到足够高，以使大多数合法模式无需错误即可评估，但也要足够低，防止攻击者导致拒绝服务攻击。
   return validate(schema: schema, data: data, maxDepth: 32).isEmpty;
}

void main() {
// 输出: true
   print(validateUntrusted(<String, dynamic>{"type": "string"}, "foo"));

// 输出: false
   validateUntrusted(<String, dynamic>{"type": "string"}, null);

// 抛出 "invalid schema"
   try {
      validateUntrusted(<String, dynamic>{"type": "nonsense"}, null);
   } catch (e) {
      print(e);
   }
// 抛出 MaxDepthExceededError 的实例
   try {
      validateUntrusted(<String, dynamic>{
         "ref": "loop",
         "definitions": {
            "loop": {"ref": "loop"}
         }
      }, null);
   }
   catch(e){
      print(e);
   }
}