Flutter插件eskema的介绍与使用

Flutter插件eskema的介绍与使用

Flutter插件eskema简介

eskema 是一个用于验证动态数据的强大工具，它提供了简单而强大的API。最初的设计目的是验证从API返回的动态JSON、用户输入的数据或其他需要动态数据验证的场景。不过，它不仅限于JSON数据，还可以验证任何类型的动态数据。

Flutter插件eskema功能

Flutter插件eskema特性

• 简单的API：易于使用和理解。
• 可组合/可扩展：可以轻松地组合和扩展。
• 安全：确保数据的正确性和完整性。
• 完全测试：经过全面测试以保证稳定性。

开始使用Flutter插件eskema

要使用该插件，只需将其添加到 pubspec.yaml 文件中：

dependencies:
  eskema: ^最新版本号

然后运行 flutter pub get 即可。

核心概念

验证器 (Validator)

eskema 中的大多数功能都是基于 验证器 的，它们是接受一个值并返回一个结果的函数。

示例验证器：

isType<String>();
listOfLength(2);
listEach(isType<String>());
all([isType<List>(), isListOfLength(2)]);

验证结果 (IResult)

这是一个表示验证结果的类。

使用方法

简单示例

注意：如果只需要验证单一值，可能并不需要使用 eskema。

单独使用验证器：

final isString = isType<String>();
const result1 = isString('valid string');
const result2 = isString(123);

result1.isValid;  // true
result2.isValid;  // false
result2.expected; // String

组合验证器：

all([isType<String>(), isDate()]);     // 所有验证器必须有效
or(isType<String>(), isType<int>());   // 至少一个验证器必须有效
and(isType<String>(), isType<int>());  // 所有验证器必须有效

// 验证一个列表，长度为2，且每个元素是字符串或null
all([
  isOfLength(2),                    // 检查列表长度是否为2
  listEach(isTypeOrNull<String>()), // 检查每个元素是否是字符串或null
  listContains('test'),             // 列表必须包含值'test'
]);

// 验证一个映射是否符合某个eskema
final matchesEskema = eskema({
  'books': listEach(
    eskema({
      'name': isType<String>(),
    }),
  ),
});
matchesEskema({'books': [{'name': 'book name'}]});

验证器详解

类型验证 (isType<T>)

检查值是否为某种类型：

isType<String>();
isType<int>();
isType<double>();
isType<List>();
isType<Map>();

类型或空值验证 (isTypeOrNull<T>)

检查值是否为某种类型或null：

isTypeOrNull<String>();
isTypeOrNull<int>();

允许空值 (nullable)

允许验证器接受null值：

nullable(eskema({...}));

例如：

nullable(eskema({...})); // 允许map或null

验证映射 (eskema)

最常见的用例是验证JSON或动态映射。使用 eskema 验证器：

final validateMap = eskema({
  'name': isType<String>(),
  'address': nullable(
    eskema({
      'city': isType<String>(),
      'street': isType<String>(),
      'number': all([
        isType<int>(),
        isMin(0),
      ]),
      'additional': nullable(
        eskema({
          'doorbel_number': Field([isType<int>()])
        })
      ),
    })
  )
});

final invalidResult = validateMap.call({});
invalidResult.isValid;    // false
invalidResult.isNotValid; // true
invalidResult.expected;   // name -> String
invalidResult.message;    // Expected name -> String

final validResult = validateMap.call({'name': 'bobby'});
validResult.isValid;    // true
validResult.isNotValid; // false
validResult.expected;   // Valid

验证列表 (listEach)

验证动态列表的常见用例。使用 listEach：

final isValidList = all([
    listOfLength(2),
    listEach(isType<int>()),
]);

isValidList.validate(null).isValid;      // true
isValidList.validate([]).isValid;        // true
isValidList.validate([1, 2]).isValid;    // true
isValidList.validate([1, "2"]).isValid;  // false
isValidList.validate([1, "2"]).expected; // [1] -> int

自定义验证器

eskema 提供了一些常见的验证器，但你可以轻松创建自定义验证器。例如，验证字符串是否匹配正则表达式：

Validator validateRegexp(RegExp regexp) {
  return (value) {
    return Result(
      isValid: regexp.hasMatch(value),  
      expected: 'match pattern $regexp', // 解释此验证器期望什么
    );
  };
}