@jayfong/x-server 2.119.0 → 3.1.1

package/lib/_cjs/cli/api_generator.js

@@ -1,458 +0,0 @@
-"use strict";
-
-var _interopRequireWildcard = require("@babel/runtime/helpers/interopRequireWildcard").default;
-var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault").default;
-exports.__esModule = true;
-exports.ApiGenerator = void 0;
-var _nodePath = _interopRequireDefault(require("node:path"));
-var _debug = _interopRequireDefault(require("debug"));
-var _fsExtra = _interopRequireDefault(require("fs-extra"));
-var _tsMorph = _interopRequireWildcard(require("ts-morph"));
-var _vtils = require("vtils");
-var _http_method = require("../core/http_method");
-/** 注释 */
-
-/** 接口传输数据 */
-
-/** 接口数据 */
-
-class ApiGenerator {
-  constructor(options = {}) {
-    this.options = options;
-    this.cwd = void 0;
-    this.debug = (0, _debug.default)('api');
-    // 几种情况:
-    // /index.ts
-    // /user/index.ts
-    // /post.ts
-    // /user/list.ts
-    // category 必须从 handlers 目录结构中推导，后续会直接拼接到 URL 前缀
-    this.categoryUrlRe = /^.+\/src\/handlers\/(?:index\.ts|(.*)\/index\.ts|(.*)\.ts)$/;
-    this.checker = void 0;
-    this.cwd = this.options.cwd || process.cwd();
-  }
-  async start() {
-    this.debug('启动项目...');
-    const tsConfigPath = _nodePath.default.join(this.cwd, 'tsconfig.json');
-    const handlersPath = _nodePath.default.join(this.cwd, 'node_modules/.x/handlers.ts');
-    const entryFile = _nodePath.default.join(this.cwd, 'src/generated/handlers.ts');
-
-    // 仅使用 ts-morph 初始化项目，并把运行时生成的 handlers 聚合文件注入到 Program 中
-    const moProject = new _tsMorph.default.Project({
-      tsConfigFilePath: tsConfigPath
-    });
-    moProject.createSourceFile(entryFile, await _fsExtra.default.readFile(handlersPath, 'utf-8'));
-    const program = moProject.getProgram().compilerObject;
-    const checker = program.getTypeChecker();
-    this.checker = checker;
-    const entrySourceFile = program.getSourceFile(entryFile);
-    // handlers.ts 的每个 export 对应一个分类（如 user、post）
-    const moduleSymbol = checker.getSymbolAtLocation(entrySourceFile);
-    const categorySymbols = checker.getExportsOfModule(moduleSymbol);
-    const apiData = [];
-    for (const categorySymbol of categorySymbols) {
-      // 分类的类型：形如 { list: defineHandler<...>, detail: defineHandler<...> }
-      const categoryType = checker.getTypeOfSymbol(categorySymbol);
-
-      // 处理器列表
-      const handlerSymbols = categoryType.getProperties();
-
-      // 分类源文件
-      const categorySourceFile = handlerSymbols[0].getDeclarations()[0].getSourceFile();
-
-      // 分类源文件路径
-      const categorySourceFilePath = categorySourceFile.fileName;
-
-      // 忽略仅开发时生效的路由
-      if (/@dev[/.]/.test(categorySourceFilePath)) continue;
-
-      // 支持 include, exclude
-      if (this.options.include?.length) {
-        if (this.options.include.every(item => !categorySourceFilePath.includes(item))) continue;
-      }
-      if (this.options.exclude?.length) {
-        if (this.options.exclude.some(item => categorySourceFilePath.includes(item))) continue;
-      }
-
-      // 分类 URL
-      const categoryUrlMatch = categorySourceFilePath.match(this.categoryUrlRe);
-      let categoryUrl = categoryUrlMatch[1] ?? categoryUrlMatch[2] ?? '';
-      categoryUrl = categoryUrl === '' ? '/' : `/${categoryUrl}/`;
-      for (const handlerSymbol of handlerSymbols) {
-        // 处理器路径
-        let handlerPath = [handlerSymbol.getName()];
-        const handlerNode = handlerSymbol.getDeclarations()[0];
-
-        // 支持自定义 requestPath，仅识别字符串字面量或字符串数组字面量
-        // 这里不会执行表达式（例如变量、模板字符串、函数调用）
-        if (
-        // const xx = defineHandler
-        _tsMorph.ts.isVariableDeclaration(handlerNode) && handlerNode.initializer &&
-        // defineHandler()
-        _tsMorph.ts.isCallExpression(handlerNode.initializer) &&
-        // defineHandler({})
-        _tsMorph.ts.isObjectLiteralExpression(handlerNode.initializer.arguments[0])) {
-          const props = handlerNode.initializer.arguments[0].properties;
-          const requestPathNode = props.find(item => item.name?.getText() === 'requestPath');
-          if (requestPathNode &&
-          // requestPath: ''
-          _tsMorph.ts.isPropertyAssignment(requestPathNode)) {
-            const customHandlerPath =
-            // requestPath: 'xx'
-            _tsMorph.ts.isStringLiteral(requestPathNode.initializer) ? requestPathNode.initializer.text :
-            // requestPath: ['xx']
-            _tsMorph.ts.isArrayLiteralExpression(requestPathNode.initializer) ? requestPathNode.initializer.elements.filter(item => _tsMorph.ts.isStringLiteral(item)).map(item => item.text) : '';
-            if (customHandlerPath.length) {
-              handlerPath = (0, _vtils.castArray)(customHandlerPath);
-            }
-          }
-        }
-
-        // 处理器 URL
-        const handlerUrl = handlerPath.map(path => `${categoryUrl}${path}`);
-
-        // 处理器注释
-        const handlerComment = this.getComment(handlerSymbol);
-        if (handlerComment.tags.has('private')) {
-          this.debug('跳过生成接口: %s', `${handlerUrl}`);
-          continue;
-        }
-        this.debug('生成接口: %s ...', handlerUrl);
-        const handlerType = checker.getTypeAtLocation(handlerNode);
-
-        // 约定 defineHandler 的泛型顺序固定为 <Request, Response, Method>
-        // 若上游定义顺序变更，这里会静默解析错误
-        const [requestType, responseType, methodType] = checker.getTypeArguments(handlerType);
-        const handlerCategory = (0, _vtils.pascalCase)(categoryUrl) || 'Index';
-        const handlerDescription = handlerComment.description || handlerUrl.join(', ');
-        const handlerMethod = methodType.value;
-        const httpMethod = _http_method.HandlerMethodToHttpMethod[handlerMethod];
-        const requestData = this.getApiDto({
-          type: requestType
-        });
-        const responseData = this.getApiDto({
-          type: responseType
-        });
-        const requestDataJsonSchema = this.apiDataToJsonSchema(requestData);
-        const responseDataJsonSchema = this.apiDataToJsonSchema(responseData);
-
-        // 说明文档按“首段标题 + 空行 + 详情”拆分
-        const handlerDescriptionDividerIndex = handlerDescription.indexOf('\n\n');
-        const apiName = handlerDescriptionDividerIndex === -1 ? handlerDescription : handlerDescription.substring(0, handlerDescriptionDividerIndex);
-        const apiDesc = handlerDescriptionDividerIndex === -1 ? '' : handlerDescription.substring(handlerDescriptionDividerIndex + 2);
-        apiData.push({
-          category: handlerCategory,
-          name: apiName,
-          desc: apiDesc,
-          path: handlerUrl,
-          handlerMethod: handlerMethod,
-          method: httpMethod,
-          requestData: requestData,
-          responseData: responseData,
-          requestDataJsonSchema: requestDataJsonSchema,
-          responseDataJsonSchema: responseDataJsonSchema
-        });
-      }
-    }
-    this.debug('写入文件...');
-    const prefix = this.options.name ? `${this.options.name}_` : '';
-    await Promise.all([_fsExtra.default.outputJSON(_nodePath.default.join(this.cwd, `temp/${prefix}api.json`), apiData, {
-      spaces: 2
-    }), _fsExtra.default.outputJSON(_nodePath.default.join(this.cwd, `temp/${prefix}yapi.json`), this.apiDataToYApiData(apiData), {
-      spaces: 2
-    }), _fsExtra.default.outputJSON(_nodePath.default.join(this.cwd, `temp/${prefix}openapi31.json`), this.apiDataToOpenAPI31Data(apiData), {
-      spaces: 2
-    })]);
-  }
-
-  // ref: https://github.com/styleguidist/react-docgen-typescript/blob/master/src/parser.ts#L777
-  getComment(symbol) {
-    if (!symbol) {
-      return {
-        existing: false,
-        description: '',
-        tags: new Map()
-      };
-    }
-    const description = _tsMorph.ts.displayPartsToString(symbol.getDocumentationComment(this.checker)).trim();
-    // JSDoc tag 统一收敛到 Map，方便按 @private 这类标签做开关
-    const tags = symbol.getJsDocTags().map(item => {
-      return {
-        label: item.name,
-        value: _tsMorph.ts.displayPartsToString(item.text).trim()
-      };
-    });
-    return {
-      existing: !!description,
-      description: description,
-      tags: tags.reduce((res, item) => {
-        res.set(item.label, item.value);
-        return res;
-      }, new Map())
-    };
-  }
-  getApiDto({
-    type,
-    keySymbol = type.symbol || type.aliasSymbol
-  }) {
-    const hasTypeFlag = (flag, _type = type) => (_type.flags & flag) === flag;
-
-    // valueSymbol 用于识别“实际值类型”，keySymbol 用于保留字段名和字段注释
-    let valueSymbol = type.symbol || type.aliasSymbol;
-    const keySymbolName = keySymbol?.getName() || '';
-    let valueSymbolName = valueSymbol?.getName() || '';
-    const comment = this.getComment(keySymbol);
-    let isRequired = keySymbol ? !(keySymbol.getFlags() & _tsMorph.ts.SymbolFlags.Optional) : false;
-    const apiName = keySymbolName || '__type';
-
-    // Decimal, Prisma 生成的
-    if (valueSymbolName === 'Decimal') {
-      return {
-        name: apiName,
-        desc: comment.description,
-        required: isRequired,
-        type: 'number',
-        enum: [],
-        children: []
-      };
-    }
-
-    // WS
-    if (valueSymbolName === 'SocketStream') {
-      return {
-        name: 'ws',
-        desc: comment.description,
-        required: isRequired,
-        type: 'object',
-        enum: [],
-        children: []
-      };
-    }
-
-    // 文件
-    if (valueSymbolName === 'MultipartFile') {
-      return {
-        name: 'file',
-        desc: comment.description,
-        required: isRequired,
-        type: 'file',
-        enum: [],
-        children: []
-      };
-    }
-
-    // Buffer
-    if (valueSymbolName === 'Buffer') {
-      return {
-        name: 'buffer',
-        desc: comment.description,
-        required: isRequired,
-        type: 'object',
-        enum: [],
-        children: []
-      };
-    }
-
-    // 联合类型：布尔字面量、枚举字面量都会走到这里
-    // 处理策略：忽略 null/undefined，用第一个成员推断基础类型，同时把所有字面量收集到 enum
-    const rawUnionTypes = type.isUnion() && type.types || [];
-    const unionTypes = rawUnionTypes.filter(item => !hasTypeFlag(_tsMorph.ts.TypeFlags.Null, item) && !hasTypeFlag(_tsMorph.ts.TypeFlags.Undefined, item));
-    const isUnion = !!unionTypes.length;
-    if (isUnion) {
-      if (unionTypes.length !== rawUnionTypes.length) {
-        isRequired = false;
-      }
-      type = unionTypes[0];
-      valueSymbol = type.symbol || type.aliasSymbol;
-      valueSymbolName = this.checker.getBaseTypeOfLiteralType(type).getSymbol()?.getName() || '';
-    }
-    const isIntersection = type.isIntersection();
-    const intersectionTypes = isIntersection && type.types || [];
-    const isDate = valueSymbolName === 'Date';
-    const isRegExp = valueSymbolName === 'RegExp';
-    const isBigIntLiteral = hasTypeFlag(_tsMorph.ts.TypeFlags.BigIntLiteral);
-    const isBigInt = hasTypeFlag(_tsMorph.ts.TypeFlags.BigInt) || isBigIntLiteral;
-    const isArray = valueSymbolName === 'Array' || valueSymbolName === 'ReadonlyArray';
-    const isStringLiteral = hasTypeFlag(_tsMorph.ts.TypeFlags.StringLiteral);
-    const isString = hasTypeFlag(_tsMorph.ts.TypeFlags.String) || isStringLiteral ||
-    // BigInt 类型视为字符串
-    isBigInt ||
-    // Date 类型视为字符串
-    isDate ||
-    // RegExp 类型视为字符串
-    isRegExp;
-    const isNumberLiteral = hasTypeFlag(_tsMorph.ts.TypeFlags.NumberLiteral);
-    const isNumber = hasTypeFlag(_tsMorph.ts.TypeFlags.Number) || isNumberLiteral;
-    const isBoolean = hasTypeFlag(_tsMorph.ts.TypeFlags.Boolean) || hasTypeFlag(_tsMorph.ts.TypeFlags.BooleanLiteral);
-    const isLiteral = isStringLiteral || isNumberLiteral || isBigIntLiteral;
-
-    // object 兜底：只要不是数组/基础类型，且 TypeScript 视为 Object，就按对象递归
-    const isObject = !isArray && !isString && !isNumber && !isBoolean && hasTypeFlag(_tsMorph.ts.TypeFlags.Object) ||
-    // 交集类型视为对象
-    isIntersection;
-    const apiDesc = keySymbol && this.getComment(keySymbol).description || '';
-    const apiEnum = (isUnion ? unionTypes.map(item => item.value) : isLiteral ? [type.value] : []).filter(v => v != null);
-    const apiType = isArray ? 'array' : isString ? 'string' : isNumber ? 'number' : isBoolean ? 'boolean' : 'object';
-    const apiRequired = isRequired;
-    const apiChildren = isArray ? [this.getApiDto({
-      type: this.checker.getTypeArguments(type)[0]
-    })] : isObject ? (0, _vtils.ii)(() => {
-      // 这里使用了 TypeChecker 的内部能力来合并交集类型字段
-      // 若 TypeScript 内部 API 变化，这里是高风险点
-      const childSymbols = this.checker.getAllPossiblePropertiesOfTypes(intersectionTypes.length ? intersectionTypes : [type]);
-      return childSymbols.map(childSymbol => {
-        const childType = this.checker.getTypeOfSymbol(childSymbol);
-        return this.getApiDto({
-          type: childType,
-          keySymbol: childSymbol
-        });
-      });
-    }) : [];
-    return {
-      name: apiName,
-      desc: apiDesc,
-      enum: apiEnum,
-      type: apiType,
-      required: apiRequired,
-      children: apiChildren
-    };
-  }
-  apiDataToJsonSchema(apiData, jsonSchema = {}) {
-    // 递归把内部 DTO 结构映射到 JSON Schema（以 object/array/primitive 三类分支处理）
-    jsonSchema.description = apiData.desc;
-    if (apiData.type === 'object') {
-      jsonSchema.type = 'object';
-      jsonSchema.properties = apiData.children.reduce((res, item) => {
-        res[item.name] = this.apiDataToJsonSchema(item);
-        return res;
-      }, {});
-      jsonSchema.required = apiData.children.filter(item => item.required).map(item => item.name);
-    } else if (apiData.type === 'array') {
-      jsonSchema.type = 'array';
-      jsonSchema.items = apiData.children.map(item => this.apiDataToJsonSchema(item))[0];
-    } else {
-      jsonSchema.type = apiData.type;
-      if (apiData.enum.length) {
-        jsonSchema.enum = apiData.enum;
-      }
-    }
-    return jsonSchema;
-  }
-  apiDataToYApiData(handles) {
-    const data = {};
-    for (const handle of handles) {
-      for (const path of handle.path) {
-        data[handle.category] = data[handle.category] || [];
-        data[handle.category].push(
-        // GET -> query；FILE -> form-data；其余 -> json body
-        // 此处是与 YApi 结构的协议转换层
-        handle.handlerMethod === 'GET' ? {
-          method: handle.method.toUpperCase(),
-          title: handle.name,
-          markdown: handle.desc,
-          path: path,
-          res_body_type: 'json',
-          req_body_is_json_schema: false,
-          res_body_is_json_schema: true,
-          req_params: [],
-          req_query: handle.requestData.children.map(item => ({
-            required: item.required ? 1 : 0,
-            name: item.name,
-            desc: item.desc,
-            type: 'string'
-          })),
-          req_headers: [],
-          req_body_form: [],
-          res_body: JSON.stringify(handle.responseDataJsonSchema)
-        } : handle.handlerMethod === 'FILE' ? {
-          method: handle.method.toUpperCase(),
-          title: handle.name,
-          markdown: handle.desc,
-          path: path,
-          req_body_type: 'form',
-          res_body_type: 'json',
-          req_body_is_json_schema: false,
-          res_body_is_json_schema: true,
-          req_params: [],
-          req_query: [],
-          req_headers: [],
-          req_body_form: handle.requestData.children.map(item => ({
-            required: item.required ? 1 : 0,
-            name: item.name,
-            desc: item.desc,
-            type: item.type === 'file' ? 'file' : 'text'
-          })),
-          res_body: JSON.stringify(handle.responseDataJsonSchema)
-        } : {
-          method: handle.method.toUpperCase(),
-          title: handle.name,
-          markdown: handle.desc,
-          path: path,
-          req_body_type: 'json',
-          res_body_type: 'json',
-          req_body_is_json_schema: true,
-          res_body_is_json_schema: true,
-          req_params: [],
-          req_query: [],
-          req_headers: [],
-          req_body_form: [],
-          req_body_other: JSON.stringify(handle.requestDataJsonSchema),
-          res_body: JSON.stringify(handle.responseDataJsonSchema)
-        });
-      }
-    }
-    return Object.keys(data).map(cat => ({
-      name: cat,
-      desc: cat,
-      list: data[cat]
-    }));
-  }
-  apiDataToOpenAPI31Data(handles) {
-    const data = {
-      openapi: '3.1.0',
-      info: {
-        title: `${process.env.APP_NAME}`,
-        version: '1.0.0'
-      },
-      paths: {},
-      servers: [{
-        url: `${process.env.APP_URL}`.replace(/\/+$/, ''),
-        description: '生产'
-      }, {
-        url: `http://127.0.0.1:${process.env.APP_PORT}`,
-        description: '本地'
-      }]
-    };
-    for (const handle of handles) {
-      for (const path of handle.path) {
-        data.paths[path] = {
-          [handle.method.toLowerCase()]: {
-            tags: [handle.category],
-            summary: handle.name,
-            description: handle.desc,
-            // 目前统一按 application/json 输出；上传类接口未转为 multipart/form-data
-            requestBody: {
-              content: {
-                'application/json': {
-                  schema: handle.requestDataJsonSchema
-                }
-              }
-            },
-            responses: {
-              '200': {
-                description: 'success',
-                content: {
-                  'application/json': {
-                    schema: handle.responseDataJsonSchema
-                  }
-                }
-              }
-            }
-          }
-        };
-      }
-    }
-    return data;
-  }
-}
-exports.ApiGenerator = ApiGenerator;