Skip to content

A light-weighted micro framework for creating cli tools.

License

Notifications You must be signed in to change notification settings

joe06102/arsenal

Repository files navigation

一个用于创建命令行的框架。优点是轻量、灵活。

安装

npm install jsouee-arsenal

为什么叫 Arsenal

Arsenal 源于 switch 上首发的机甲游戏 《恶魔机甲》中的基础机甲,在其基础之上可以增强为多种类型的机甲。

概念

Arsenal 核心基于 AOP 实现了灵活的插件机制。每一个指令都是一条独立的管道(Pipeline),每条管道都有一个独立的上下文(Context)用于挂载需要共享的数据, 每条管道上可以任意插入多个切入点(CutPoint)。

                                                       ---| CutPoint 1 |          --- | CutPoint 2 |
                                                      /                          /
                                                     /                          /
                                  ---| CommandA | --------| Command Context |----------------------- | OUTPUT |
                                 /
                                /
| Input |---| Arsenal Core |-------------------------------------------------------------------------------------
                                          \                          \
                                           \                          \
                                            ---| CommandB |            --- | CommandC |

管道(Pipeline)

Arsenal 中的管道分为 3 种类型,分别是:基础管道(BasicPipeline)可熔断管道(BailPipeline)并行管道(ParallelPipeline)

管道主要提供 3 个能力:

  1. 注册切入点
  2. 按照规则去执行 & 调度切入点
  3. 提供独立的上下文

定义一个基础管道(injectable 主要负责依赖注入,下面模块会详细说明):

import { BasicPipeline, injectable } from "jsouee-arsenal";
import { LoginCutPoint } from "../CutPoint/LoginCutPoint";

@injectable()
export class InitPipeline extends BasicPipeline {
  constructor(private loginCP: LoginCutPoint) {
    super();
    this.Register(loginCP);
    this.Context.Set("bigjoe", "bj");
  }
}

基础管道(BasicPipeline)

基础管道只支持注册基础切入点,并且会按照注册顺序执行切入点,支持同步、异步的切入点处理函数。

可熔断管道(BailPipeline)

可熔断管道只支持注册可熔断切入点,并且会按照注册顺序执行切入点,支持同步、异步的切入点处理函数。不同于基础管道,如果切入点的上一个处理函数返回了 Error 实例,则立即熔断处理流程,不会再执行后续切入点。

并行管道(ParallelPipeline)

并行管道只支持注册并行切入点,并且会并行的执行切入点,支持同步、异步的切入点处理函数(对于同步处理函数,并行的效果等同于基础管道)。

切入点(CutPoint)

切入点对应了 3 种类型的管道,分别是:基础切入点(BasicCutPoint)可熔断切入点(BailCutPoint)并行切入点(ParallelCutPoint)

切入点主要功能就是依据当前管道传入的上下文,做出相对应的处理,并且在需要时将处理结果挂载到上下文。

定义一个基础切入点:

import {
  IContext,
  BasicCutPoint,
  inject,
  injectable,
  ILogger,
  Token,
} from "jsouee-arsenal";

@injectable()
export class LoginCutPoint extends BasicCutPoint {
  // 定义切入点的名称
  Name = LoginCutPoint.name;

  constructor(@inject(Token.LoggerToken.ILogger) private logger: ILogger) {
    super();
  }

  // 定义切入点的处理函数
  async Intercept(ctx: IContext): Promise<void> {
    this.logger.Info(`[${LoginCutPoint.name}] ctx: ${ctx.Get("options.name")}`);
  }
}

基础切入点(BasicCutPoint)

按照注册顺序被执行。Intercept 支持同步、异步。

可熔断切入点(BailCutPoint)

按照注册顺序被执行。Intercept 支持同步、异步。不同于基础切入点,可熔断切入点支持返回 Error 实例,用于立即熔断管道中后续切入点的执行。

并行切入点(ParallelCutPoint)

并行地被执行。Intercept 支持同步、异步(推荐只在使用异步,同步效果同基础切入点)。

命令(Command)

命令是命令行中常见的参数,例如 npm 支持 installuninstall 等命令;

Arsenal 中定义了命令的结构 ArsenalCommand,用户在自定义命令时只需要实现该结构即可。

命令包含了如下属性:

  • Name:命令的名称,例如 install
  • Description: 命令的描述信息,当用户不知道该命令的作用时,可以通过 myArsenal command --help 在终端查看描述信息
  • Options: 命令支持哪些参数,例如 npm install --dev=true, --dev 就是参数,具体格式见下文
  • Pipeline:命令对应的管道实例,可以通过构造函数注入、手动调用 container.resolve 来构造,不要通过 new 来构造

例如,创建一个初始化的命令:

import {
  ArsenalCommand,
  ArsenalCommandOption,
  injectable,
} from "jsouee-arsenal";
import { InitPipeline } from "../Pipeline/InitPipeline";

@injectable()
export class InitCommand extends ArsenalCommand {
  Name = "init";
  Description = "init your cli";
  Options: ArsenalCommandOption<string>[] = [
    {
      Name: "--name [string]",
      Required: true,
      Description: "your app name",
      Type: "static",
      Parse: (val: string) => val,
    },
  ];

  constructor(public Pipeline: InitPipeline) {}
}

命令参数 ArsenalCommandOption

整体结构类似 ArsenalCommand, 需要注意 Name 属性必须以 -- 开头,详细可以参见 commander.js

export class ArsenalCommandOption<T = string> {
  Type: string;
  Name: string;
  Description: string;
  Default?: T;
  Required?: boolean;
  Parse?: (raw: string) => T;
}

脚手架配置文件

Arsenal 内置了常见的配置文件读取功能,用于配置脚手架的行为,可以通过入口文件配置 configRC 方法配置 配置文件的名称。

例如:如果配置了名称为 demo,则 Arsenal 在启动时会去搜索并读取下列格式的文件:

  • .demorc,
  • .demorc.json
  • .demorc.yaml
  • .demorc.yml
  • .demorc.js
  • .demorc.cjs
  • demo.config.js
  • demo.config.cjs
const arsenal = new Arsenal()
  // 设置脚手架配置文件的名称为demo
  .ConfigRC((options) => (options.Module = "demo"));

读取配置文件

设置完脚手架配置文件的名称后,就可以在自定义的 Pipeline 或者 CutPoint 中通过 依赖注入 的方式使用。

import {
  BasicCutPoint,
  inject,
  injectable,
  ILogger,
  IConfig,
  IContext,
  Token,
} from "jsouee-arsenal";

@injectable()
export class LoginCutPoint extends BasicCutPoint {
  Name = LoginCutPoint.name;

  constructor(
    @inject(Token.LoggerToken.ILogger) private logger: ILogger,
    @inject(Token.ConfigToken.IConfig) private config: IConfig
  ) {
    super();
  }

  async Intercept(ctx: IContext): Promise<void> {
    this.logger.Info(
      `[${LoginCutPoint.name}] ctx: ${ctx.Get(
        "options.name"
      )}, config: ${this.config.Get<string>("entry.name")}`
    );
  }
}

应用入口

import { Arsenal } from "Arsenal";
import { InitCommand } from "./Command/Init";

const arsenal = new Arsenal()
  // 配置资源文件的名称
  .ConfigRC((options) => (options.Module = "demo"))
  // 配置版本号,建议直接从package.json中获取
  .ConfigVersion("1.0.0")
  // 配置自定义的依赖注入服务
  .ConfigService((container) => {})
  // 注册一个Command,可以连续注册
  .ConfigCommand(InitCommand)
  // 运行程序
  .Run();

控制反转

为了提高代码的可测试性、可维护性、整洁度等,Arsenal 推荐全部使用依赖注入容器来实例化依赖的服务,并在启动前手动在 ConfigService 中注册自己定义的依赖。

Arsenal 中的依赖注入基于 tsyringe实现。

Arsenal 内置了部分模块的依赖注入,用于可直接引用:

  • ILogger:用于日志打印,默认实现为控制台打印(单例):

    export interface ILogger {
      Info(...args: string[]): void;
      Success(...args: string[]): void;
      Error(...args: string[]): void;
      Warning(...args: string[]): void;
    }
  • IConfig: 用于获取自定义的配置文件,默认实现为只支持 commonjs 格式的配置文件(单例,key 支持多层级,例如 a.b.c):

    export interface IConfig {
      Get<T>(key: string): T;
    }

如果需要在 Pipeline 或者 CutPoint 中使用时,可以直接借助构造函数注入的方式。

为了减少错误,Arsenal 导出了一个 Token 模块,包含了内置服务的注册名称:

import { BasicCutPoint, inject, injectable, ILogger, Token } from "Arsenal";

@injectable()
export class LoginCutPoint extends BasicCutPoint {
  Name = LoginCutPoint.name;

  constructor(@inject(Token.LoggerToken.ILogger) private logger: ILogger) {
    super();
  }

  async Intercept(ctx): Promise<void> {
    this.logger.Info(`[${LoginCutPoint.name}] ctx: ${ctx.Get("options.name")}`);
  }
}

完整 Demo

查看源代码中 Example 目录

建议

Arsenal 目前还是初版,如果有意见,欢迎 issue 交流。

About

A light-weighted micro framework for creating cli tools.

Resources

License

Stars

Watchers

Forks

Packages

No packages published