Flutter JSON哈希计算插件gg_json_hash的使用

gg_json_hash 是一个轻量级的Dart包，旨在遍历JSON数据结构，并在其中的所有对象上添加唯一的哈希标识符。

动机

对嵌套的JSON对象进行哈希处理有几个关键原因：

• 变更检测：通过为每个对象生成唯一哈希值，可以轻松检测复杂数据结构中的变化，而无需手动比较所有字段。
• 高效同步：哈希允许系统仅同步修改或新增的数据，从而减少带宽并提高性能。
• 缓存管理：哈希作为缓存的唯一键，实现快速检索并确保数据一致性。
• 数据完整性：哈希验证嵌套对象是否未被更改，增加额外的安全性和可靠性。
• 简化跟踪：在复杂的系统中，哈希提供了一种一致的方式来识别和跟踪对象，即使是在分布式环境中也是如此。

特性

• 递归处理：向嵌套的JSON对象添加哈希值。
• SHA256：使用SHA256算法进行哈希处理。
• 哈希截断：指定添加哈希值的长度。
• 非侵入式：如果需要，可以在不改变现有数据的情况下添加哈希值。
• 浮点数：为相似的浮点数分配相同的哈希值。

示例

import 'package:gg_json_hash/gg_json_hash.dart';
import 'dart:convert';

void main() {
  var jh = JsonHash.defaultInstance;

  // 创建一个JSON结构
  print('创建一个JSON结构');

  Map<String, dynamic> json = {
    'a': '0',
    'b': '1',
    'child': {
      'd': 3,
      'e': 4,
    },
  };

  // 向JSON结构中添加哈希值
  print('向JSON结构中添加哈希值。');
  json = jh.apply(json);
  print(const JsonEncoder.withIndent('  ').convert(json));

  // 设置最大浮点精度
  print('设置最大浮点精度。');

  final config = HashConfig(
    numberConfig: NumberHashingConfig.defaultConfig.copyWith(precision: 0.001),
  );

  jh = JsonHash(config: config);

  try {
    jh.apply({
      'a': 1.000001,
    });
  } catch (e) {
    print(e.toString()); // 数字 1.000001 的精度高于 0.001
  }

  // 使用"inPlace"选项直接修改输入对象
  print('使用"inPlace"选项直接修改输入对象。');

  json = {'a': 1, 'b': 2};
  var ac = ApplyJsonHashConfig.defaultConfig.copyWith(inPlace: true);

  jh.apply(json, applyConfig: ac);
  assert(json['_hash'] == 'QyWM_3g_5wNtikMDP4MK38');

  // 设置"updateExistingHashes: false"以创建缺失的哈希值但不触发现有哈希值
  print('设置"updateExistingHashes: false"以创建缺失的哈希值但不触发现有哈希值。');

  json = {
    'a': 1,
    'b': 2,
    'child': {'c': 3},
    'child2': {'_hash': 'ABC123', 'd': 4},
  };
  ac = ac.copyWith(updateExistingHashes: false);

  json = jh.apply(json, applyConfig: ac);
  assert(json['_hash'] == 'pos6bn6mON0sirhEaXq41-');
  assert(json['child']['_hash'] == 'yrqcsGrHfad4G4u9fgcAxY');
  assert(json['child2']['_hash'] == 'ABC123');

  // 如果现有的哈希值与新计算的哈希值不匹配，则会抛出错误
  print('如果现有的哈希值与新计算的哈希值不匹配，则会抛出错误。');
  ac = ac.copyWith(throwIfOnWrongHashes: true);
  try {
    jh.apply({'a': 1, '_hash': 'invalid'});
  } catch (e) {
    print(e.toString());
    // '哈希"invalid"与新计算的哈希"AVq9f1zFei3ZS3WQ8ErYCE"不匹配。请确保所有系统都生成相同的哈希值。'
  }

  // 将"throwIfOnWrongHashes"设置为false以替换无效的哈希值
  print('将"throwIfOnWrongHashes"设置为false以替换无效的哈希值。');
  ac = ac.copyWith(
    throwIfOnWrongHashes: false,
    updateExistingHashes: true,
  );
  json = jh.apply({'a': 1, '_hash': 'invalid'}, applyConfig: ac);
  print(json['_hash']); // AVq9f1zFei3ZS3WQ8ErYCE

  // 使用validate检查哈希值是否正确
  print('使用validate检查哈希值是否正确。');

  json = {'a': 1, 'b': 2};
  json = jh.apply(json);
  jh.validate(json); // true

  try {
    json['a'] = 3;
    jh.validate({'a': 3, '_hash': 'invalid'});
  } catch (e) {
    print(e.toString());
  }
}