从入门到精通Cambria API全方位使用指南与示例代码【免费下载链接】cambria-projectSchema evolution with bi-directional lenses.项目地址: https://gitcode.com/gh_mirrors/ca/cambria-projectCambria 是一个用 TypeScript 编写的 JavaScript 库核心能力是双向透镜bi-directional lensJSON 数据转换你只需在 YAML 或 JSON 中描述一份透镜即可在两个相关的数据结构Schema之间自由转换文档、JSON Patch 编辑和 JSON Schema 描述且支持反向回传编辑。本文是一份从零上手的完整教程覆盖 Cambria API 的核心函数、示例代码与 CLI 用法适合新手和普通开发者快速掌握 JSON Schema 演化schema evolution的正确打开方式。一、Cambria 能做什么Cambria 解决的问题是同一份数据在不同版本或不同系统里长得不一样。比如你的 JSON API 升级了字段或数据库结构迁移了你不想写两份转换脚本正向一份、反向一份还要担心两边逻辑不一致。Cambria 让你只写一份透镜定义它就自动拥有双向能力转换对象格式对应 API完整文档JSONapplyLensToDoc文档编辑JSON PatchapplyLensToPatch/compile结构描述JSON SchemaupdateSchema三大典型使用场景 管理 JSON API 的正反向兼容性️ JSON 数据的数据库结构迁移️ 命令行下把 JSON 文档转换成另一种形状⚠️ 提示Cambria 目前是早期软件官方说明它尚未完全准备好用于生产环境学习入门和原型验证非常合适。二、快速安装与上手步骤1. 获取项目用 npm 或 yarn 直接安装库npm install cambria # 或者 yarn add cambria也可以克隆源码自己玩建议克隆仓库里带有完整可运行的演示git clone https://gitcode.com/gh_mirrors/ca/cambria-project cd cambria-project yarn yarn build2. 认识核心 API 的四大件Cambria 的所有能力都从入口文件src/index.ts导出初学者只要先记住这 4 个函数函数作用定义位置loadYamlLens把 YAML 格式的透镜文本加载为LensSourcelens-loader.tsapplyLensToDoc把整份文档通过透镜转换doc.tsreverseLens把透镜反转实现反向转换reverse.tscompile预编译透镜得到正向/反向两个转换函数patch.ts透镜本身是什么在src/lens-ops.ts中可以看到LensSource就是一组透镜操作LensOp的数组每个操作形如{ op: rename, source: a, destination: b }。常见的操作包括add/remove新增或删除字段rename重命名字段hoist/plunge把字段从子对象提升到顶层或下沉进子对象wrap/head字段与单元素数组之间互转in/map进入某个字段内部、或对数组每个元素应用子透镜convert按映射表转换字段值三、五分钟实战完整示例代码仓库的demo/目录给出了一个最直观的例子把一份 GitHub Issue JSON 转换成精简的节肢动物风格 IssueArthropod Issue。下面按顺序走一遍。第 1 步准备一份透镜YAML打开 github-arthropod.lens.yml它声明了一组操作删除milestone、pull_request等十几个冗余字段把title重命名为name再把labels数组压平成单个category字段lens: - remove: { name: milestone } - remove: { name: pull_request } - rename: source: title destination: name - head: name: labels - in: name: labels lens: - rename: source: name destination: category - hoist: host: labels name: category - remove: name: labels短短十几行 YAML就完成了两个 Schema 之间的完整映射——而且反向转换自动存在不需要再写一份。第 2 步用 API 把整份文档转换过去import { readFileSync } from fs import { loadYamlLens, reverseLens, applyLensToDoc } from cambria // 1. 读取并加载 YAML 透镜 const lensData readFileSync(./demo/github-arthropod.lens.yml, utf-8) let lens loadYamlLens(lensData) // 2. 读取输入文档 const doc JSON.parse(readFileSync(./demo/github-issue.json, utf-8)) // 3. 应用透镜得到新 Schema 下的文档 const newDoc applyLensToDoc(lens, doc) console.log(JSON.stringify(newDoc, null, 2))运行后那份包含 30 多个 URL 字段的 GitHub Issue就变成只有 8 个字段的结构对照 simple-issue.json{ id: 1, state: open, name: Found a bug!!!, body: Im having a problem with this., category: feature, created_at: 2011-04-22T13:33:48Z, updated_at: 2011-04-22T13:33:48Z }第 3 步反向转换——编辑回传这正是双向透镜的精髓在新结构Schema B里编辑完文档后用同一份透镜反向把它合回原结构Schema A。applyLensToDoc的第 4 个参数是底稿文档反向转换时把原 GitHub Issue 作为底稿传入const reversed reverseLens(lens) const baseDoc JSON.parse(readFileSync(./demo/github-issue.json, utf-8)) const restored applyLensToDoc(reversed, newDoc, undefined, baseDoc)restored就是一份更新过的完整 GitHub Issue——被删除的字段会恢复默认值编辑过的字段比如name改回title会写回正确位置。这套机制的底层在src/doc.ts的importDoc它先把输入文档转成一个覆盖全部字段的 JSON Patch再让补丁穿过透镜最后应用到底稿上所以缺失字段不会丢。进阶compile预编译透镜如果你要高频转换可以先compile(lens)它会返回一对柯里化函数{ right, left }分别代表正向和反向应用适合封装成一个转换器函数对外暴露避免每次调用都重复处理透镜。四、CLI 命令行用法不想写代码Cambria 自带命令行工具cli.ts一条管道命令即可转换# 正向GitHub Issue → 精简 Issue cat ./demo/github-issue.json | node ./dist/cli.js -l ./demo/github-arthropod.lens.yml # 反向精简 Issue → 写回 GitHub Issue-r 反转-b 指定底稿 cat ./demo/simple-issue.json | node ./dist/cli.js -l ./demo/github-arthropod.lens.yml -r -b ./demo/github-issue.json常用参数一览参数说明-l, --lens透镜文件YAML必填-i, --input输入文档缺省从标准输入读取-s, --schema输入文档的 JSON Schema缺省自动推断-b, --base反向转换时使用的底稿文档-r, --reverse反转透镜方向想要改文件就自动重新转换的实时流水线可以搭配entr工具具体写法见仓库自带的 demo/README.md。五、进阶能力透镜图Lens Graph当你的项目有 3 个以上 Schema 版本V1 → V2 → V3时可以不用两两手写透镜。src/lens-graph.ts提供了透镜图 APIinitLensGraph()初始化一个空的透镜图registerLens(graph, V1, V2, lens)注册一条边的透镜反向透镜自动注册lensFromTo(graph, V1, V3)自动沿图寻路把多段透镜串联起来从 V1 直接迁到 V3底层用的是 Dijkstra 寻路见src/lens-graph.ts这意味着你只需维护相邻版本之间的透镜任意两个版本之间的转换都能自动推导出来。测试代码test/lens-graph.ts给出了完整用法参考。六、常见疑问 FAQ问输入文档没有 JSON Schema能用吗能。applyLensToDoc的第 3 个参数是可选项不传时会通过importDoc定义于src/doc.ts自动从文档推断出 Schema。问透镜是单向的还是双向的双向的。reverse.ts中对每个操作都有反向规则如add反转成remove、hoist反转成plunge、head反转成wrap所以你永远只需要维护一份透镜定义。问和直接写两个转换脚本比优势在哪只写一份定义就保证正反向一致不会出现正向能转过去、反向转不回来的 bug而且透镜可以同时作用于文档、Patch 编辑和 Schema 三种对象这是普通转换脚本做不到的。问能用于生产环境吗官方 README 明确标注 Cambria 仍是早期软件still immature software建议在关键业务中先做原型验证或配合其自动化合并生态cambria-automerge做本地优先文档协作的预研。七、结语下一步学什么按这个路线走你可以快速吃透 Cambria API✅ 读透demo/目录下的完整示例Issue 双向转换✅ 打开 lens-ops.ts把 11 种透镜操作的类型定义过一遍✅ 用loadYamlLensapplyLensToDoc转换你自己项目的两份 JSON✅ 尝试reverseLens与compile体验编辑回传✅ 阅读test/目录下的单元测试test/patch.ts、test/lens-graph.ts作为进阶示例代码掌握双向透镜你就不用再为两个版本的数据怎么来回同步发愁了——写一份透镜转换与回传全部自动完成。【免费下载链接】cambria-projectSchema evolution with bi-directional lenses.项目地址: https://gitcode.com/gh_mirrors/ca/cambria-project创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 从入门到精通：Cambria API全方位使用指南与示例代码
从入门到精通Cambria API全方位使用指南与示例代码【免费下载链接】cambria-projectSchema evolution with bi-directional lenses.项目地址: https://gitcode.com/gh_mirrors/ca/cambria-projectCambria 是一个用 TypeScript 编写的 JavaScript 库核心能力是双向透镜bi-directional lensJSON 数据转换你只需在 YAML 或 JSON 中描述一份透镜即可在两个相关的数据结构Schema之间自由转换文档、JSON Patch 编辑和 JSON Schema 描述且支持反向回传编辑。本文是一份从零上手的完整教程覆盖 Cambria API 的核心函数、示例代码与 CLI 用法适合新手和普通开发者快速掌握 JSON Schema 演化schema evolution的正确打开方式。一、Cambria 能做什么Cambria 解决的问题是同一份数据在不同版本或不同系统里长得不一样。比如你的 JSON API 升级了字段或数据库结构迁移了你不想写两份转换脚本正向一份、反向一份还要担心两边逻辑不一致。Cambria 让你只写一份透镜定义它就自动拥有双向能力转换对象格式对应 API完整文档JSONapplyLensToDoc文档编辑JSON PatchapplyLensToPatch/compile结构描述JSON SchemaupdateSchema三大典型使用场景 管理 JSON API 的正反向兼容性️ JSON 数据的数据库结构迁移️ 命令行下把 JSON 文档转换成另一种形状⚠️ 提示Cambria 目前是早期软件官方说明它尚未完全准备好用于生产环境学习入门和原型验证非常合适。二、快速安装与上手步骤1. 获取项目用 npm 或 yarn 直接安装库npm install cambria # 或者 yarn add cambria也可以克隆源码自己玩建议克隆仓库里带有完整可运行的演示git clone https://gitcode.com/gh_mirrors/ca/cambria-project cd cambria-project yarn yarn build2. 认识核心 API 的四大件Cambria 的所有能力都从入口文件src/index.ts导出初学者只要先记住这 4 个函数函数作用定义位置loadYamlLens把 YAML 格式的透镜文本加载为LensSourcelens-loader.tsapplyLensToDoc把整份文档通过透镜转换doc.tsreverseLens把透镜反转实现反向转换reverse.tscompile预编译透镜得到正向/反向两个转换函数patch.ts透镜本身是什么在src/lens-ops.ts中可以看到LensSource就是一组透镜操作LensOp的数组每个操作形如{ op: rename, source: a, destination: b }。常见的操作包括add/remove新增或删除字段rename重命名字段hoist/plunge把字段从子对象提升到顶层或下沉进子对象wrap/head字段与单元素数组之间互转in/map进入某个字段内部、或对数组每个元素应用子透镜convert按映射表转换字段值三、五分钟实战完整示例代码仓库的demo/目录给出了一个最直观的例子把一份 GitHub Issue JSON 转换成精简的节肢动物风格 IssueArthropod Issue。下面按顺序走一遍。第 1 步准备一份透镜YAML打开 github-arthropod.lens.yml它声明了一组操作删除milestone、pull_request等十几个冗余字段把title重命名为name再把labels数组压平成单个category字段lens: - remove: { name: milestone } - remove: { name: pull_request } - rename: source: title destination: name - head: name: labels - in: name: labels lens: - rename: source: name destination: category - hoist: host: labels name: category - remove: name: labels短短十几行 YAML就完成了两个 Schema 之间的完整映射——而且反向转换自动存在不需要再写一份。第 2 步用 API 把整份文档转换过去import { readFileSync } from fs import { loadYamlLens, reverseLens, applyLensToDoc } from cambria // 1. 读取并加载 YAML 透镜 const lensData readFileSync(./demo/github-arthropod.lens.yml, utf-8) let lens loadYamlLens(lensData) // 2. 读取输入文档 const doc JSON.parse(readFileSync(./demo/github-issue.json, utf-8)) // 3. 应用透镜得到新 Schema 下的文档 const newDoc applyLensToDoc(lens, doc) console.log(JSON.stringify(newDoc, null, 2))运行后那份包含 30 多个 URL 字段的 GitHub Issue就变成只有 8 个字段的结构对照 simple-issue.json{ id: 1, state: open, name: Found a bug!!!, body: Im having a problem with this., category: feature, created_at: 2011-04-22T13:33:48Z, updated_at: 2011-04-22T13:33:48Z }第 3 步反向转换——编辑回传这正是双向透镜的精髓在新结构Schema B里编辑完文档后用同一份透镜反向把它合回原结构Schema A。applyLensToDoc的第 4 个参数是底稿文档反向转换时把原 GitHub Issue 作为底稿传入const reversed reverseLens(lens) const baseDoc JSON.parse(readFileSync(./demo/github-issue.json, utf-8)) const restored applyLensToDoc(reversed, newDoc, undefined, baseDoc)restored就是一份更新过的完整 GitHub Issue——被删除的字段会恢复默认值编辑过的字段比如name改回title会写回正确位置。这套机制的底层在src/doc.ts的importDoc它先把输入文档转成一个覆盖全部字段的 JSON Patch再让补丁穿过透镜最后应用到底稿上所以缺失字段不会丢。进阶compile预编译透镜如果你要高频转换可以先compile(lens)它会返回一对柯里化函数{ right, left }分别代表正向和反向应用适合封装成一个转换器函数对外暴露避免每次调用都重复处理透镜。四、CLI 命令行用法不想写代码Cambria 自带命令行工具cli.ts一条管道命令即可转换# 正向GitHub Issue → 精简 Issue cat ./demo/github-issue.json | node ./dist/cli.js -l ./demo/github-arthropod.lens.yml # 反向精简 Issue → 写回 GitHub Issue-r 反转-b 指定底稿 cat ./demo/simple-issue.json | node ./dist/cli.js -l ./demo/github-arthropod.lens.yml -r -b ./demo/github-issue.json常用参数一览参数说明-l, --lens透镜文件YAML必填-i, --input输入文档缺省从标准输入读取-s, --schema输入文档的 JSON Schema缺省自动推断-b, --base反向转换时使用的底稿文档-r, --reverse反转透镜方向想要改文件就自动重新转换的实时流水线可以搭配entr工具具体写法见仓库自带的 demo/README.md。五、进阶能力透镜图Lens Graph当你的项目有 3 个以上 Schema 版本V1 → V2 → V3时可以不用两两手写透镜。src/lens-graph.ts提供了透镜图 APIinitLensGraph()初始化一个空的透镜图registerLens(graph, V1, V2, lens)注册一条边的透镜反向透镜自动注册lensFromTo(graph, V1, V3)自动沿图寻路把多段透镜串联起来从 V1 直接迁到 V3底层用的是 Dijkstra 寻路见src/lens-graph.ts这意味着你只需维护相邻版本之间的透镜任意两个版本之间的转换都能自动推导出来。测试代码test/lens-graph.ts给出了完整用法参考。六、常见疑问 FAQ问输入文档没有 JSON Schema能用吗能。applyLensToDoc的第 3 个参数是可选项不传时会通过importDoc定义于src/doc.ts自动从文档推断出 Schema。问透镜是单向的还是双向的双向的。reverse.ts中对每个操作都有反向规则如add反转成remove、hoist反转成plunge、head反转成wrap所以你永远只需要维护一份透镜定义。问和直接写两个转换脚本比优势在哪只写一份定义就保证正反向一致不会出现正向能转过去、反向转不回来的 bug而且透镜可以同时作用于文档、Patch 编辑和 Schema 三种对象这是普通转换脚本做不到的。问能用于生产环境吗官方 README 明确标注 Cambria 仍是早期软件still immature software建议在关键业务中先做原型验证或配合其自动化合并生态cambria-automerge做本地优先文档协作的预研。七、结语下一步学什么按这个路线走你可以快速吃透 Cambria API✅ 读透demo/目录下的完整示例Issue 双向转换✅ 打开 lens-ops.ts把 11 种透镜操作的类型定义过一遍✅ 用loadYamlLensapplyLensToDoc转换你自己项目的两份 JSON✅ 尝试reverseLens与compile体验编辑回传✅ 阅读test/目录下的单元测试test/patch.ts、test/lens-graph.ts作为进阶示例代码掌握双向透镜你就不用再为两个版本的数据怎么来回同步发愁了——写一份透镜转换与回传全部自动完成。【免费下载链接】cambria-projectSchema evolution with bi-directional lenses.项目地址: https://gitcode.com/gh_mirrors/ca/cambria-project创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考