Schema 摘录

Schema 提取器将代码文件中的所有类型(说明或推断)转换为 JSON- 计划 计划 Schema提取是创建您代码自动化文档的必要步骤.

它由两个部分组成: ts 变压器 财务报告和审定财务报表 链接。 。 。 .

Schema 服务

schema服务允许观看特定的schema's,处理请求之间的缓存. 它发送一个更新事件, 具体说明文件无效后哪些类型已更新

它允许观看模块/Ast节点的策略. 获取有限的 Schema 深度 并扩展一个特定的分支 计划以后.

这允许图形用户界面只请求其读取的图案部分.

永远记得释放你的监视路径

使用量

要使用 Schema 提取项目从文件中提取类型数据,请导入 createLinker 函数从 @dazl/typescript-schema-extract。此函数收到一系列文件路径的字符串,并返回已初始化的链接类.

创建链接器后, 引用 linker.flatten它收到两个参数,并将返回我们要求的实体的链接计划(在 exportName:

    import {createLinker} from '@dazl/typescript-schema-extract';
    const files = [
        'myProject/src/file-a.ts',
        'myProject/src/file-b.ts'
    ];
    const linker = createLinker(files);
    const linkedSchema = linker.flatten(files[0], 'IAnimal');

说明: 如果您想使用不同提取器的链接器,请查看 创建自定义链接区域。 。 。 .
此外,目前还无法自动链接一个文件的所有输出。 您可以查看文件的输出并引用 flatten 但是这可能不是一个有效的过程.

结果实例

为了更好地理解变换是如何运作的,请查看以下界面: 变换:

// file-a.ts
export interface IAnimal {
  name: string;
  hasTail: boolean;
  makeNoise: (sound: ISound) => void;
  isTamed?: 'YES' | 'NO';
}

如果我们使用TS变压器进行改造,我们可以得到以下计划:

{
  "$id": "/index.tsx",
  "$ref": "common/module",
  "properties": {},
  "definitions": {
    "IAnimal": {
      "properties": {
        "name": {
          "type": "string"
        },
        "hasTail": {
          "type": "boolean"
        },
        "makeNoise": {
          "$ref": "common/function",
          "arguments": [
            {
              "$ref": "#ISound",
              "name": "sound"
            }
          ],
          "returns": {
            "$ref": "common/undefined"
          },
          "requiredArguments": ["sound"]
        },
        "isTamed": {
          "type": "string",
          "enum": ["YES", "NO"]
        }
      },
      "required": ["name", "hasTail", "makeNoise"],
      "$ref": "common/interface"
    }
  }
}

链接

链接器接收文件名和该文件中的导出名称,并返回该导出链接的策略 .

怎么会有区别呢 ts transformer当我们用 ts transformer,我们得到的结果将只使用 $ref 属性来引用其他类型(导入或来自同一文件).

链接器通过将它们连在一起来平分其中一些类型.

示例

让我们看看以下代码中的界面B:

export interface InterfaceA<T> {
  something: T;
}
export interface InterfaceB extends InterfaceA<string> {
  somethingElse: number;
}

如果我们使用TS变压器来改变这个文件,我们将得到以下方案:

{
  "$id": "/index.tsx",
  "$ref": "common/module",
  "properties": {},
  "definitions": {
    "InterfaceA": {
      "$ref": "common/interface",
      "properties": {
        "something": { "$ref": "#InterfaceA!T" }
      },
      "required": ["something"],
      "genericParams": [{ "name": "T" }]
    },
    "InterfaceB": {
      "$ref": "common/interface",
      "properties": {
        "somethingElse": { "type": "number" }
      },
      "required": ["somethingElse"],
      "genericArguments": [{ "type": "string" }],
      "extends": {
        "$ref": "#InterfaceA"
      }
    }
  }
}

但我们缺少一些关于界面B的关键信息。 连接后, InterfaceB 的图案将变成:

    "InterfaceB": {
        $ref: "common/interface",
        properties: {
            something: {
                inheritedFrom: '#InterfaceA',
                type: 'string'
            },
            somethingElse: {
                type: 'number'
            }
        },
        required: ['somethingElse', 'something']
    };

连接规则

为了避免跑入无限回路,链接器并不将每个计划中的每个成员链接. 它确实链接:

• extends - 使用扩展关键字的类和接口。 (但链接器不会链接界面成员)
• 一般类型
• 交叉类型 - 我们可能需要连接的策略来交叉两种或两种以上不同的类型.

什么不会是联系?

• 进口 - 如果您从不同的文件中导入一个类型, 它将作为引用 : $ref: "myProject/src/util#myFunction"
• 提及其他类型 - 任何形式提及不同类型或界面,如 type A = B 或者说 interface InterfaceA { type: InterfaceB }。这还包括使用其他类型作为参数或返回值的函数.

TS 变形器

将打字源文件转换为无链接的JSON-Schema. 默认情况下,链接器正在使用这个变压器,除非您想要一个非链接的变压器,否则无需使用这个变压器.

使用量

导入 transform 函数从 @dazl/typescript-schema-extract。该函数收到以下五个论据:

例如,如果我们想要改变自己的代码:

    import path from 'path';
    import compilerOptions from './utils';

    const projectPath = '/Projects/MySecretProject/;
    const fileName = projectPath + 'secret-stuff.ts'
    // TS setup
    const program = typescript.createProgram([fileName], compilerOptions);
    const sourceFile = program.getSourceFile(fileName);

    const schema = transform(program.getTypeChecker(), sourceFile, fileName, 'MySecretProject', path.posix);

外观结构( T)

您可以找到计划的结构 和我们所支持的不同类型 json-schema 类型

创建自定义链接器

说明数字 : 目前我们不出口SchemaLinker级。我们将导出它或添加一个接收提取器并返回链接器的函数

使用 createLinker 创建以打字为主的链接器,但链接器不仅限于打字. 在创建新的链接类时,链接器会接收一个提取对象:

    export interface ILinkerOptions {
        getSchema: (path: string) => ModuleSchema;
    }

ILinkerOptions 接收文件的路径并返回从该文件创建的 JSON-Schema .

要使用与链接器不同的取出器,只需与取出器创建出一个新的取出器类并引用平分.

    flatten(filePath: string, typeName: string): Schema

平面函数接收文件路径以及我们想要链接的其中的类型 .

import { SchemaLinker } from '@dazl/typescript-schema-extract/?????';
import { myExtractor } from './secretStuff';

function linkSchema(filePath, typeName) {
  const customLinker = new SchemaLinker(myExtractor);
  return linker.flatten(filePath, typeName);
}