paas-build-package 0.0.1

package/packages/cli/hbs-temp/index.d.ts.hbs

@@ -0,0 +1,9 @@
+{{#each entities as |entity|}}
+import type { {{pascalCase (camelCase entity.entityName) }}Service } from './apis/{{entity.entityName}}.service';
+{{/each}}
+
+export interface ApiManage {
+{{#each entities as |entity|}}
+  readonly {{camelCase entity.entityName}}: {{pascalCase (camelCase entity.entityName)}}Service;
+{{/each}}
+}

package/packages/cli/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@gct-paas/cli",
+  "version": "0.1.6",
+  "type": "module",
+  "description": "paas 平台核心包",
+  "bin": {
+    "gct-paas": "es/bin.mjs"
+  },
+  "main": "dist/index.cjs",
+  "module": "es/index.mjs",
+  "types": "es/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./es/index.d.ts",
+      "import": "./es/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "es",
+    "hbs-temp",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "keywords": [
+    "paas",
+    "gct"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://git.gct-china.com/paas/frontend/paas-package.git"
+  },
+  "license": "MIT",
+  "author": "gct",
+  "scripts": {
+    "run": "tsx src/bin.ts gen-cdn-lib --tag=dev --dir=/Users/zhr/workspace/gct/gct-paas-cdn/extras",
+    "build": "unbuild",
+    "publish:next": "npm run build && npm publish --access public --tag=next --registry=https://registry.npmjs.org/",
+    "publish:dev": "npm run build && npm publish --access public --tag=dev --registry=https://registry.npmjs.org/",
+    "publish:alpha": "npm run build && npm publish --access public --tag=alpha --registry=https://registry.npmjs.org/",
+    "publish:beta": "npm run build && npm publish --access public --tag=beta --registry=https://registry.npmjs.org/",
+    "publish:npm": "npm run build && npm publish --access public --registry=https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.2.0",
+    "commander": "^14.0.2",
+    "consola": "^3.4.2",
+    "core-js": "^3.48.0",
+    "fast-glob": "^3.3.3",
+    "fs-extra": "^11.3.3",
+    "got": "^14.6.6",
+    "handlebars": "^4.7.8",
+    "handlebars-helpers": "^0.10.0",
+    "listr2": "^10.2.1",
+    "lodash-es": "^4.17.23",
+    "ora": "^9.1.0",
+    "pacote": "^21.5.0",
+    "picocolors": "^1.1.1",
+    "rimraf": "^6.1.2",
+    "simple-git": "^3.33.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/lodash-es": "^4.17.12",
+    "@types/node": "^25.0.10",
+    "@types/pacote": "^11.1.8",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "unbuild": "^3.6.1"
+  }
+}

package/packages/cli/src/actions/gen-api/api-manage.ts

@@ -0,0 +1,96 @@
+import { IObject } from '../../core';
+import { SPECIAL_ENTITIES } from './special-entities.config';
+
+/**
+ * api 管理
+ *
+ * @export
+ * @class EntityApiManage
+ */
+export class EntityApiManage {
+  readonly cache = new Map<string, IObject>();
+
+  constructor(public readonly name: string) {}
+
+  /**
+   * 新增方法
+   *
+   * @param {string} method 方法名称
+   * @param {string} mode 请求方式
+   * @param {IObject} cfg 从 swagger 获取的配置
+   */
+  add(method: string, mode: string, cfg: IObject): void {
+    const tag = `${method}:${mode}`;
+    this.cache.set(tag, cfg);
+  }
+}
+
+/**
+ * api 清单管理
+ *
+ * @export
+ * @class ApiManage
+ */
+export class ApiManage {
+  readonly cache = new Map<string, EntityApiManage>();
+
+  constructor() {
+    this.specialTreatment();
+  }
+
+  /**
+   * 根据配置文件中的特殊实体映射来处理
+   *
+   * @protected
+   */
+  protected specialTreatment() {
+    SPECIAL_ENTITIES.forEach(({ canonical, aliases }) => {
+      const manage = new EntityApiManage(canonical);
+      aliases.forEach(alias => {
+        this.cache.set(alias, manage);
+      });
+    });
+  }
+
+  /**
+   * 新增 api
+   *
+   * @param {string} pathStr 请求路径
+   * @param {IObject} cfg swagger 配置
+   */
+  add(pathStr: string, cfg: IObject) {
+    // 根据路径截取归属标识，例：/gct-apaas/api/app-branch/info 提取出 app-branch
+    const splits = pathStr.split('/');
+    const entityName = splits[3];
+    const method = splits.slice(4).join('_');
+    const requestPath = splits.slice(4).join('/');
+    if (!this.cache.has(entityName)) {
+      this.cache.set(entityName, new EntityApiManage(entityName));
+    }
+    const entity = this.cache.get(entityName)!;
+    const modes = Object.keys(cfg);
+    modes.forEach(mode => {
+      const _cfg = cfg[mode];
+      _cfg.requestPath = requestPath;
+      entity.add(method, mode, _cfg);
+    });
+  }
+
+  /**
+   * 结束新增 api 后调用
+   *
+   */
+  done(): void {
+    // 清理特殊实体中的别名，保留标准名称
+    SPECIAL_ENTITIES.forEach(({ canonical, aliases }) => {
+      if (this.cache.has(canonical)) {
+        // 删除所有别名，只保留标准名称
+        aliases.forEach(alias => {
+          if (alias !== canonical) {
+            this.cache.delete(alias);
+          }
+        });
+      }
+    });
+  }
+}

package/packages/cli/src/actions/gen-api/gen-api.ts

@@ -0,0 +1,211 @@
+import path from 'path';
+import fse from 'fs-extra';
+import * as rm from 'rimraf';
+import glob from 'fast-glob';
+import log from 'consola';
+import got from 'got';
+import { HandlebarsEngine, IObject, MACRO_FOLDER } from '../../core';
+import { ModelManage } from './model-manage';
+
+/**
+ * 基于 handlebars 模板编写生成 api
+ *
+ * @export
+ * @class GenApiAction
+ */
+export class GenApiAction {
+  // private baseUrl = 'http://paas.paasdev.gct-paas.com';
+
+  private engine = new HandlebarsEngine();
+
+  private modelManage = new ModelManage();
+
+  private configs: Record<string, string> = {
+    platform:
+      '/gct-platform/v2/api-docs?group=%E7%AE%A1%E7%90%86%E5%B9%B3%E5%8F%B0API',
+    apaas: '/gct-apaas/v2/api-docs?group=apaas%E5%B9%B3%E5%8F%B0API',
+    ipaas: '/gct-ipaas/v2/api-docs?group=ipaas%E5%B9%B3%E5%8F%B0API',
+    rag: '/gct-rag/v2/api-docs?group=%E7%AE%A1%E7%90%86%E5%B9%B3%E5%8F%B0API',
+  };
+
+  /**
+   * 生成 api
+   *
+   * @param {string} baseUrl swagger 服务地址
+   * @param {string} tag 要发布的 api 标识
+   * @param {string} template 模板目录
+   * @param {string} output 输出目录
+   * @param {boolean} clean 是否清理输出目录后再生成
+   */
+  async run(
+    baseUrl: string,
+    tag: string,
+    template: string,
+    output: string,
+    clean: boolean,
+  ) {
+    try {
+      const cwd = process.cwd();
+      // 模板绝对路径
+      const tempPath = path.resolve(cwd, template);
+      // 输出绝对路径
+      const outPath = path.resolve(cwd, output);
+      // 输出目录目录存在时，根据配置清理
+      if (clean === true && fse.existsSync(outPath)) {
+        rm.sync(outPath);
+      }
+      await this.registerMacros(tempPath, this.engine);
+      await this.registerTempFiles(tempPath, this.engine);
+      await this.write(
+        tag,
+        path.join(baseUrl, this.configs[tag]),
+        outPath,
+        this.engine,
+      );
+    } catch (error) {
+      console.error(error);
+    }
+  }
+
+  /**
+   * 基于模型编译输出文件
+   *
+   * @protected
+   * @param {string} url
+   * @param {string} outPath
+   * @param {HandlebarsEngine} engine
+   * @returns {*}  {Promise<void>}
+   */
+  protected async write(
+    tag: string,
+    url: string,
+    outPath: string,
+    engine: HandlebarsEngine,
+  ): Promise<void> {
+    // 从 swagger 获取配置
+    const cfg = await got(url).json<IObject>();
+
+    const model = this.transformModel(cfg);
+
+    this.modelManage.init(tag, model);
+
+    const all: Promise<void>[] = [];
+    engine.temps.forEach((template, key) => {
+      if (key === '') {
+        return;
+      }
+      const outFilePath = path.join(outPath, key);
+      // 解析出模板路径中的所有标识，没有标识表示全局
+      const tags = engine.parseContextTags(key);
+      if (tags.length === 0) {
+        log.info(`生成文件：${outFilePath}`);
+        all.push(
+          fse.outputFile(
+            outFilePath,
+            engine.render(template, {
+              entities: Array.from(this.modelManage.entities.values()),
+              definitions: model.definitions,
+            }),
+            'utf-8',
+          ),
+        );
+      } else {
+        if (tags.includes('api')) {
+          this.modelManage.entities.forEach(model => {
+            const filePath = engine.render(outFilePath, model);
+            log.info(`生成文件：${filePath}`);
+            all.push(
+              fse.outputFile(filePath, engine.render(template, model), 'utf-8'),
+            );
+          });
+        }
+      }
+    });
+    await Promise.all(all);
+  }
+
+  /**
+   * 注册所有的宏
+   *
+   * @protected
+   * @param {string} tempPath
+   * @param {HandlebarsEngine} engine
+   * @returns {*}  {Promise<void>}
+   */
+  protected async registerMacros(
+    tempPath: string,
+    engine: HandlebarsEngine,
+  ): Promise<void> {
+    const macroFiles = glob.sync(path.join(MACRO_FOLDER, '**/*.hbs'), {
+      cwd: tempPath,
+      dot: true,
+      absolute: true,
+    });
+    if (macroFiles.length > 0) {
+      await Promise.all(
+        macroFiles.map(macroFilePath => {
+          return new Promise<void>(resolve => {
+            fse.readFile(macroFilePath, 'utf-8').then(file => {
+              const key = path.relative(tempPath, macroFilePath);
+              log.info(`注册宏：${key}`);
+              engine.registerMacro(key, file);
+              resolve();
+            });
+          });
+        }),
+      );
+    }
+  }
+
+  /**
+   * 注册所有模板文件
+   *
+   * @protected
+   * @param {string} tempPath
+   * @param {HandlebarsEngine} engine
+   * @returns {*}  {Promise<void>}
+   */
+  protected async registerTempFiles(
+    tempPath: string,
+    engine: HandlebarsEngine,
+  ): Promise<void> {
+    const tempFiles = glob.sync('**/*.hbs', {
+      cwd: tempPath,
+      dot: true,
+      absolute: true,
+      ignore: [path.join(MACRO_FOLDER, '**/*.hbs')],
+    });
+    if (tempFiles.length > 0) {
+      await Promise.all(
+        tempFiles.map(tempFilePath => {
+          return new Promise<void>(resolve => {
+            fse.readFile(tempFilePath, 'utf-8').then(file => {
+              const key = path.relative(tempPath, tempFilePath);
+              log.info(`注册模板：${key}`);
+              engine.registerTemp(key, file);
+              resolve();
+            });
+          });
+        }),
+      );
+    }
+  }
+
+  /**
+   * 针对加载的配置进行处理
+   *
+   * @protected
+   * @param {IObject} model
+   * @returns {*}  {IObject}
+   */
+  protected transformModel(model: IObject): IObject {
+    const keys = Object.keys(model.definitions);
+    keys.forEach(key => {
+      const item = model.definitions[key];
+      if (item.properties) {
+        item.propertySize = Object.keys(item.properties).length;
+      }
+    });
+    return model;
+  }
+}

package/packages/cli/src/actions/gen-api/model-manage.ts

@@ -0,0 +1,269 @@
+import { IObject } from '../../core';
+import { ApiManage } from './api-manage';
+
+/**
+ * 实体方法模型
+ *
+ * @export
+ * @interface IMethodModel
+ */
+export interface IMethodModel {
+  /**
+   * 方法名称
+   *
+   * @type {string}
+   */
+  name: string;
+  /**
+   * 请求方式
+   *
+   * @type {string}
+   */
+  mode: string;
+  /**
+   * 方法模型
+   *
+   * @type {IObject}
+   */
+  model: IObject;
+  /**
+   * 请求实体
+   *
+   * @type {IObject}
+   */
+  requestEntity?: IObject;
+  /**
+   * 响应实体
+   *
+   * @type {IObject}
+   */
+  responseEntity?: IObject;
+  /**
+   * 查询参数
+   *
+   * @type {IObject[]}
+   */
+  queries: IObject[];
+  /**
+   * 路径参数, 路径示例：/gct-apaas/api/model-comprehensive/model/{key}/{mode}/{modelCategory}
+   *
+   * @type {string[]}
+   */
+  pathParams?: string[];
+}
+
+/**
+ * 实体模型
+ *
+ * @export
+ * @interface IEntityModel
+ */
+export interface IEntityModel {
+  /**
+   * 实体名称
+   *
+   * @type {string}
+   */
+  entityName: string;
+  /**
+   * 平台标识 apaas, platform
+   *
+   * @type {string}
+   */
+  tag: string;
+  /**
+   * 实体名称(同name)
+   *
+   * @type {string}
+   */
+  api: string;
+  /**
+   * 实体模型
+   *
+   * @type {IObject}
+   */
+  model: IObject;
+  /**
+   * 实体方法模型
+   *
+   * @type {IMethodModel[]}
+   */
+  methods: IMethodModel[];
+  /**
+   * 实体引用实体名称集合
+   *
+   * @type {string[]}
+   */
+  entityRefs: string[];
+}
+
+/**
+ * 模型管理
+ *
+ * @export
+ * @class ModelManage
+ */
+export class ModelManage {
+  /**
+   * 所有实体模型
+   *
+   * @type {Map<string, IEntityModel>}
+   */
+  readonly entities = new Map<string, IEntityModel>();
+
+  /**
+   * 所有用到的实体定义
+   *
+   * @type {Map<string, IObject>}
+   */
+  readonly definitions = new Map<string, IObject>();
+
+  /**
+   * 目前接口中的基础数据类型
+   *
+   * @protected
+   */
+  protected basicDataType = [
+    'any',
+    'number',
+    'string',
+    'null',
+    'boolean',
+    'Void',
+    'object',
+  ];
+
+  init(tag: string, cfg: IObject): void {
+    const apiManage = new ApiManage();
+    // 从 swagger 配置生成 api 管理类
+    const paths = Object.keys(cfg.paths).filter(pathStr => {
+      // 过滤 external 开头，但是 /external/api/tenant/info/byPortOrDomain 需要保留
+      return (
+        !pathStr.startsWith('/external') ||
+        pathStr === '/external/api/tenant/info/byPortOrDomain'
+      );
+    });
+    paths.forEach((pathStr: string) => {
+      const pathCfg = cfg.paths[pathStr];
+      apiManage.add(pathStr, pathCfg);
+    });
+    apiManage.done();
+    // 遍历所有实体
+    const entityNames = apiManage.cache.keys();
+    for (const entityName of entityNames) {
+      const entitySet = new Set<string>();
+      const entityManage = apiManage.cache.get(entityName)!;
+      const methods: IMethodModel[] = [];
+      if (entityManage.cache.size > 0) {
+        // 遍历所有方法，tags 拼接规则：方法名-请求方式
+        const tags = entityManage.cache.keys();
+        for (const tag of tags) {
+          // 方法名称、请求方式
+          const [methodName, mode] = tag.split(':');
+          const config = entityManage.cache.get(tag)!;
+          // 请求实体对象
+          let requestEntity: IObject | undefined = undefined;
+          // 获取 body 参数
+          const param = config.parameters.find((param: IObject) => {
+            if (param.in === 'body') {
+              return param;
+            }
+          });
+          if (param && param.schema) {
+            // 后端通用接口特殊处理，名称为 requestBody 的参数，直接定义为 IObject
+            if (param.name === 'requestBody') {
+              requestEntity = { title: 'IObject' };
+            } else if (param.name === 'file') {
+              requestEntity = { title: 'UploadFileData' };
+            } else {
+              const refKey = this.getOriginRef(param.schema);
+              // 根据 body 参数获取引用的实体
+              requestEntity = cfg.definitions[refKey];
+              if (requestEntity && Object.keys(requestEntity).length > 0) {
+                this.definitions.set(refKey, requestEntity);
+                entitySet.add(refKey);
+              }
+            }
+          }
+          // 响应实体对象
+          let responseEntity: IObject | undefined = undefined;
+          if (config.responses['200'].schema) {
+            const refKey = this.getOriginRef(config.responses['200'].schema);
+            // 根据 body 参数获取引用的实体
+            responseEntity = cfg.definitions[refKey];
+            if (responseEntity && Object.keys(responseEntity).length > 0) {
+              this.definitions.set(refKey, responseEntity);
+              entitySet.add(refKey);
+            }
+          }
+          const queries: IObject[] = config.parameters.filter(
+            (param: IObject) => {
+              if (param.in === 'query') {
+                return param;
+              }
+            },
+          );
+          // 2026 年 2 月 3 日 去掉此逻辑，已经支持了 pathParams 的处理，不再需要特殊处理
+          // {
+          //   // 当put方法需要在url中拼接主键时，默认补充query查询参数
+          //   if (methodName === '{id}') {
+          //     queries.push({
+          //       name: 'id',
+          //       in: 'query',
+          //       description: '数据主键',
+          //       required: true,
+          //       type: 'string',
+          //     });
+          //   }
+          // }
+          // 请求路径 config.requestPath
+          const matches = [...config.requestPath.matchAll(/\{([^}]*)\}/g)].map(
+            m => m[1],
+          );
+          methods.push({
+            name: methodName !== 'undefined' ? methodName : '',
+            mode,
+            model: config,
+            requestEntity,
+            responseEntity,
+            queries,
+            pathParams: matches,
+          });
+        }
+        this.entities.set(entityName, {
+          tag,
+          entityName: entityName,
+          api: entityName,
+          model: cfg.definitions[entityName],
+          methods,
+          entityRefs: Array.from(entitySet.values()).filter(item => {
+            // 过滤掉基础类型的导入
+            return (
+              this.basicDataType.findIndex(type => {
+                return item.indexOf(`«${type}»`) !== -1;
+              }) === -1 && !this.basicDataType.includes(item)
+            );
+          }),
+        });
+      }
+    }
+  }
+
+  /**
+   * 获取接口的引用对象
+   *
+   * @protected
+   * @param {IObject} data
+   * @returns {*}  {string}
+   */
+  protected getOriginRef(data: IObject): string {
+    const { $ref, originalRef, type } = data;
+    if (type) return type;
+    if (originalRef) return originalRef;
+    if ($ref) {
+      const _refs_ = $ref.split('/');
+      return _refs_[_refs_.length - 1];
+    }
+    return 'any';
+  }
+}

package/packages/cli/src/actions/gen-api/special-entities.config.ts

@@ -0,0 +1,26 @@
+/**
+ * 特殊实体映射配置
+ * 用于处理 swagger 中存在的特殊命名或映射规则
+ */
+export interface SpecialEntityMapping {
+  /** 标准实体名称 */
+  canonical: string;
+  /** 别名映射列表 */
+  aliases: string[];
+}
+
+/**
+ * 特殊实体配置列表
+ * 当后续有类似的特殊处理需求时，直接在此列表中添加新条目即可
+ */
+export const SPECIAL_ENTITIES: SpecialEntityMapping[] = [
+  {
+    canonical: 'med-pro',
+    aliases: ['medpro', 'medPro', 'med-pro'],
+  },
+  // 示例：如果后续有其他特殊映射，按照下面的格式添加
+  // {
+  //   canonical: 'some-entity',
+  //   aliases: ['someEntity', 'someentity', 'some-entity'],
+  // },
+];