Normalizr-translate-chinese

官方英文文档

翻译的不太好，可以对比着看看

normalizr build status npm version npm downloads

在Flux和Redux 应用中根据一种模式来扁平化深层嵌套的api返回的json数据

安装

  1. npm install --save normalizr

应用例子

Flux

See flux-react-router-example.

Redux

See redux/examples/real-world.

问题

  • 你有一个返回了深层嵌套的对象的API请求
  • 你想要你的应用针对Flux 或者 Redux;
  • 你发现Store(或者Reducers)从深层嵌套的数据中获取和操作数据会非常麻烦

Normalizr采用JSON格式和一种schema，并且用嵌套实体的id来替换嵌套实体，整合所有的实体到字典对象中

For example,

  1. [{
  2.   id: 1,
  3.   title: 'Some Article',
  4.   author: {
  5.     id: 1,
  6.     name: 'Dan'
  7.   }
  8. }, {
  9.   id: 2,
  10.   title: 'Other Article',
  11.   author: {
  12.     id: 1,
  13.     name: 'Dan'
  14.   }
  15. }]

可以被范式化成(normalized to)

  1. {
  2.   result: [1, 2],
  3.   entities: {
  4.     articles: {
  5.       1: {
  6.         id: 1,
  7.         title: 'Some Article',
  8.         author: 1
  9.       },
  10.       2: {
  11.         id: 2,
  12.         title: 'Other Article',
  13.         author: 1
  14.       }
  15.     },
  16.     users: {
  17.       1: {
  18.         id: 1,
  19.         name: 'Dan'
  20.       }
  21.     }
  22.   }
  23. }

注意它的扁平化结构(所有的嵌套都没了)

特性

  • 实体可以嵌套在其他实体、对象、数组中
  • 可以通过结合实体的schema来表示任何类型API返回的数据
  • 相同id的实体会自动合并 (with a warning if they differ);
  • 允许使用自定义的id属性作为合并的依据 (e.g. slug).

用法

  1. import { normalize, Schema, arrayOf } from 'normalizr';

首先，为实体定义一个模式(schema)

  1. const article = new Schema('articles');
  2. const user = new Schema('users');

然后我们定义一个嵌套规则

  1. article.define({
  2.   author: user,
  3.   contributors: arrayOf(user)
  4. });

现在我们可以在处理API请求返回数据的方法中使用这个schema:

  1. const ServerActionCreators = {
  3.   // 有两个带有不同响应对象的schemas的XHR endpoints----------------------------
  4.   // 我们可以用前面定义的schema对象来表示他们:
  6.   receiveOneArticle(response) {
  8.     // 在这里，这个返回的数据是一个包含了一篇文章的对象
  9.     // 把文章的schema作为normalize方法的第二个参数，让他能正确的遍历响应对象并且把所有的实体都整合到一起
  11.     // BEFORE:
  12.     // {
  13.     //   id: 1,
  14.     //   title: 'Some Article',
  15.     //   author: {
  16.     //     id: 7,
  17.     //     name: 'Dan'
  18.     //   },
  19.     //   contributors: [{
  20.     //     id: 10,
  21.     //     name: 'Abe'
  22.     //   }, {
  23.     //     id: 15,
  24.     //     name: 'Fred'
  25.     //   }]
  26.     // }
  27.     //
  28.     // AFTER:
  29.     // {
  30.     //   result: 1,                    // <--- 注意对象是由ID来引用的
  31.     //   entities: {
  32.     //     articles: {
  33.     //       1: {
  34.     //         author: 7,              // <--- 同样适用于在其它实体中的引用
  35.     //         contributors: [10, 15]  
  36.     //         ...}
  37.     //     },
  38.     //     users: {
  39.     //       7: { ... },
  40.     //       10: { ... },
  41.     //       15: { ... }
  42.     //     }
  43.     //   }
  44.     // }
  46.     response = normalize(response, article);
  48.     AppDispatcher.handleServerAction({
  49.       type: ActionTypes.RECEIVE_ONE_ARTICLE,
  50.       response
  51.     });
  52.   },
  54.   receiveAllArticles(response) {
  56.     // 这里，返回的数据是一个对象，他的key为'articles'并且该key指向了一个包含文章对象的数组
  57.     // 把 { articles: arrayOf(article) }作为normalize方法的第二个参数，让他能正确的遍历响应对象并且把所有的实体都整合到一起
  59.     // BEFORE:
  60.     // {
  61.     //   articles: [{
  62.     //     id: 1,
  63.     //     title: 'Some Article',
  64.     //     author: {
  65.     //       id: 7,
  66.     //       name: 'Dan'
  67.     //     },
  68.     //     ...
  69.     //   },
  70.     //   ...
  71.     //   ]
  72.     // }
  73.     //
  74.     // AFTER:
  75.     // {
  76.     //   result: {
  77.     //    articles: [1, 2, ...]     // <--- 注意对象数组转换成ID数组的方式
  78.     //   },
  79.     //   entities: {
  80.     //     articles: {
  81.     //       1: { author: 7, ... }, // <--- 同样适用于在其它实体中的引用
  82.     //       2: { ... },
  83.     //       ...
  84.     //     },
  85.     //     users: {
  86.     //       7: { ... },
  87.     //       ..
  88.     //     }
  89.     //   }
  90.     // }
  92.     response = normalize(response, {
  93.       articles: arrayOf(article)
  94.     });
  96.     AppDispatcher.handleServerAction({
  97.       type: ActionTypes.RECEIVE_ALL_ARTICLES,
  98.       response
  99.     });
  100.   }
  101. }

Finally, different Stores can tune in to listen to all API responses and grab entity lists from action.response.entities:

  1. AppDispatcher.register((payload) => {
  2.   const { action } = payload;
  4.   if (action.response && action.response.entities && action.response.entities.users) {
  5.     mergeUsers(action.response.entities.users);
  6.     UserStore.emitChange();
  7.     break;
  8.   }
  9. });

API Reference

new Schema(key, [options])

Schema 允许你定义一个通过API返回的实体的类型 这应该与你服务器上代码的模型相对应

key参数允许你为这类实体指定一个名字(译者的理解其实就是数据库表名)

  1. const article = new Schema('articles');
  3. // 你可以使用自定义的id属性
  4. const article = new Schema('articles', { idAttribute: 'slug' });
  6. // 或者指定一个函数来生成
  7. function generateSlug(entity) { /* ... */ }
  8. const article = new Schema('articles', { idAttribute: generateSlug });
  10. // You can also specify meta properties to be used for customizing the output in assignEntity (见下)
  11. const article = new Schema('articles', { idAttribute: 'slug', meta: { removeProps: ['publisher'] }});
  13. // You can specify custom `assignEntity` function to be run after the `assignEntity` function passed to `normalize`
  14. const article = new Schema('articles', { assignEntity: function (output, key, value, input) {
  15.   if (key === 'id_str') {
  16.     output.id = value;
  17.     if ('id_str' in output) {
  18.       delete output.id_str;
  19.     }
  20.   } else {
  21.     output[key] = value;
  22.   }
  23. }})
  25. // 你可以为实体指定默认的值
  26. const article = new Schema('articles', { defaults: { likes: 0 } });

Schema.prototype.define(nestedSchema)

允许你指定不同实体之间的关系

  1. const article = new Schema('articles');
  2. const user = new Schema('users');
  4. article.define({
  5.   author: user
  6. });

Schema.prototype.getKey()

返回这个schema的key

  1. const article = new Schema('articles');
  3. article.getKey();
  4. // articles

Schema.prototype.getIdAttribute()

返回这个schema的id属性

  1. const article = new Schema('articles');
  2. const slugArticle = new Schema('articles', { idAttribute: 'slug' });
  4. article.getIdAttribute();
  5. // id
  6. slugArticle.getIdAttribute();
  7. // slug

Schema.prototype.getDefaults()

返回这个schema的默认值

  1. const article = new Schema('articles', { defaults: { likes: 0 } });
  3. article.getDefaults();
  4. // { likes: 0 }

arrayOf(schema, [options])

描述了一个schema的数组作为参数被传递

  1. const article = new Schema('articles');
  2. const user = new Schema('users');
  4. article.define({
  5.   author: user,
  6.   contributors: arrayOf(user)
  7. });

If the array contains entities with different schemas, you can use the schemaAttribute option to specify which schema to use for each entity: 如果一个数组包含了具有不同schema的实体，你可以使用schemaAttribute选项来为每一个实体指定schema

  1. const article = new Schema('articles');
  2. const image = new Schema('images');
  3. const video = new Schema('videos');
  4. const asset = {
  5.   images: image,
  6.   videos: video
  7. };
  9. // You can specify the name of the attribute that determines the schema
  10. article.define({
  11.   assets: arrayOf(asset, { schemaAttribute: 'type' })
  12. });
  14. // Or you can specify a function to infer it
  15. function inferSchema(entity) { /* ... */ }
  16. article.define({
  17.   assets: arrayOf(asset, { schemaAttribute: inferSchema })
  18. });

valuesOf(schema, [options])

Describes a map whose values follow the schema passed as argument.

  1. const article = new Schema('articles');
  2. const user = new Schema('users');
  4. article.define({
  5.   collaboratorsByRole: valuesOf(user)
  6. });

If the map contains entities with different schemas, you can use the schemaAttribute option to specify which schema to use for each entity:

  1. const article = new Schema('articles');
  2. const user = new Schema('users');
  3. const group = new Schema('groups');
  4. const collaborator = {
  5.   users: user,
  6.   groups: group
  7. };
  9. // You can specify the name of the attribute that determines the schema
  10. article.define({
  11.   collaboratorsByRole: valuesOf(collaborator, { schemaAttribute: 'type' })
  12. });
  14. // Or you can specify a function to infer it
  15. function inferSchema(entity) { /* ... */ }
  16. article.define({
  17.   collaboratorsByRole: valuesOf(collaborator, { schemaAttribute: inferSchema })
  18. });

unionOf(schemaMap, [options])

Describe a schema which is a union of multiple schemas. This is useful if you need the polymorphic behavior provided by arrayOf or valuesOf but for non-collection fields.

Use the required schemaAttribute option to specify which schema to use for each entity.

  1. const group = new Schema('groups');
  2. const user = new Schema('users');
  4. // a member can be either a user or a group
  5. const member = {
  6.   users: user,
  7.   groups: group
  8. };
  10. // You can specify the name of the attribute that determines the schema
  11. group.define({
  12.   owner: unionOf(member, { schemaAttribute: 'type' })
  13. });
  15. // Or you can specify a function to infer it
  16. function inferSchema(entity) { /* ... */ }
  17. group.define({
  18.   creator: unionOf(member, { schemaAttribute: inferSchema })
  19. });

A unionOf schema can also be combined with arrayOf and valuesOf with the same behavior as each supplied with the schemaAttribute option.

  1. const group = new Schema('groups');
  2. const user = new Schema('users');
  4. const member = unionOf({
  5.   users: user,
  6.   groups: group
  7. }, { schemaAttribute: 'type' });
  9. group.define({
  10.   owner: member,
  11.   members: arrayOf(member),
  12.   relationships: valuesOf(member)
  13. });

normalize(obj, schema, [options])

Normalizes object according to schema.
Passed schema should be a nested object reflecting the structure of API response.

You may optionally specify any of the following options:

  • assignEntity (function): This is useful if your backend emits additional fields, such as separate ID fields, you’d like to delete in the normalized entity. See the tests and the discussion for a usage example.

  • mergeIntoEntity (function): You can use this to resolve conflicts when merging entities with the same key. See the test and the discussion for a usage example.

  1. const article = new Schema('articles');
  2. const user = new Schema('users');
  4. article.define({
  5.   author: user,
  6.   contributors: arrayOf(user),
  7.   meta: {
  8.     likes: arrayOf({
  9.       user: user
  10.     })
  11.   }
  12. });
  14. // ...
  16. // Normalize one article object
  17. const json = { id: 1, author: ... };
  18. const normalized = normalize(json, article);
  20. // Normalize an array of article objects
  21. const arr = [{ id: 1, author: ... }, ...]
  22. const normalized = normalize(arr, arrayOf(article));
  24. // Normalize an array of article objects, referenced by an object key:
  25. const wrappedArr = { articles: [{ id: 1, author: ... }, ...] }
  26. const normalized = normalize(wrappedArr, {
  27.   articles: arrayOf(article)
  28. });

通过例子来解释

假如你有返回以下schema的API请求/articles:

  1. articles: article*
  3. article: {
  4.   author: user,
  5.   likers: user*
  6.   primary_collection: collection?
  7.   collections: collection*
  8. }
  10. collection: {
  11.   curator: user
  12. }

如果不做范式化，你的store需要清楚的知道返回数据的结构 比如， UserStore在获取到请求结果的时候会包含很多样板代码来获取新用户

  1. // 如果不做范式化, 你需要对每一个store都做这些
  2. AppDispatcher.register((payload) => {
  3.   const { action } = payload;
  5.   switch (action.type) {
  6.   case ActionTypes.RECEIVE_USERS:
  7.     mergeUsers(action.rawUsers);
  8.     break;
  10.   case ActionTypes.RECEIVE_ARTICLES:
  11.     action.rawArticles.forEach(rawArticle => {
  12.       mergeUsers([rawArticle.user]);
  13.       mergeUsers(rawArticle.likers);
  15.       mergeUsers([rawArticle.primaryCollection.curator]);
  16.       rawArticle.collections.forEach(rawCollection => {
  17.         mergeUsers(rawCollection.curator);
  18.       });
  19.     });
  21.     UserStore.emitChange();
  22.     break;
  23.   }
  24. });

Normalizr解决了这个问题，通过把嵌套的实体用id替代把请求返回的数据变成了一个扁平化的结构的对象

  1. {
  2.   result: [12, 10, 3, ...],
  3.   entities: {
  4.     articles: {
  5.       12: {
  6.         authorId: 3,
  7.         likers: [2, 1, 4],
  8.         primaryCollection: 12,
  9.         collections: [12, 11]
  10.       },
  11.       ...
  12.     },
  13.     users: {
  14.       3: {
  15.         name: 'Dan'
  16.       },
  17.       2: ...,
  18.       4: ....
  19.     },
  20.     collections: {
  21.       12: {
  22.         curator: 2,
  23.         name: 'Stuff'
  24.       },
  25.       ...
  26.     }
  27.   }
  28. }

UserStore的代码可以像这样被重写

  1. // 做了范式化后，所有的用户都在action.response.entities.users中
  3. AppDispatcher.register((payload) => {
  4.   const { action } = payload;
  6.   if (action.response && action.response.entities && action.response.entities.users) {
  7.     mergeUsers(action.response.entities.users);
  8.     UserStore.emitChange();
  9.     break;
  10.   }
  11. });

依赖

  • 一些方法依赖 lodash, 比如 isObject, isEqual 和 mapValues

Browser Support

Modern browsers with ES5 environments are supported.
The minimal supported IE version is IE 9.

Running Tests

  1. git clone https://github.com/gaearon/normalizr.git
  2. cd normalizr
  3. npm install
  4. npm test # run tests once
  5. npm run test:watch # run test watcher

Credits

Normalizr was originally created by Dan Abramov and inspired by a conversation with Jing Chen.
It has since received contributions from different community members.