@jayfong/x-server 2.30.3 → 2.31.0

package/lib/cli/api_generator.js

@@ -1,131 +1,222 @@
-import * as parseComment from 'comment-parser';
+import path from 'path';
 import createDebug from 'debug';
 import fs from 'fs-extra';
-import path from 'node:path';
-import * as ts from 'ts-morph';
-import { ii, pascalCase, snakeCase } from 'vtils';
+import mo, { ts } from 'ts-morph';
+import { ii, pascalCase } from 'vtils';
 import { HandlerMethodToHttpMethod } from "../core/http_method";
+
+/** 注释 */
+
+/** 接口传输数据 */
+
+/** 接口数据 */
+
 export class ApiGenerator {
-  constructor() {
+  constructor(cwd = process.cwd()) {
+    this.cwd = cwd;
     this.debug = createDebug('api');
-    this.cwd = process.cwd();
-    // cwd = '/Users/admin/Documents/jfWorks/x-server-test'
-    this.project = void 0;
+    // 几种情况:
+    // /index.ts
+    // /user/index.ts
+    // /post.ts
+    // /user/list.ts
+    this.categoryUrlRe = /^.+\/src\/handlers\/(?:index\.ts|(.*)\/index\.ts|(.*)\.ts)$/;
+    this.checker = void 0;
   }
-  getTypeBySymbol(symbol) {
-    return symbol.getTypeAtLocation(symbol.getDeclarations()[0] || symbol.getValueDeclarationOrThrow());
+  async start() {
+    this.debug('启动项目...');
+    const tsConfigPath = path.join(this.cwd, 'tsconfig.json');
+    const handlersPath = path.join(this.cwd, 'node_modules/.x/handlers.ts');
+    const entryFile = path.join(this.cwd, 'src/generated/handlers.ts');
+
+    // 仅使用 ts-morph 初始化项目
+    const moProject = new mo.Project({
+      tsConfigFilePath: tsConfigPath
+    });
+    moProject.createSourceFile(entryFile, await fs.readFile(handlersPath, 'utf-8'));
+    const program = moProject.getProgram().compilerObject;
+    const checker = program.getTypeChecker();
+    this.checker = checker;
+    const moduleSymbol = checker.getSymbolAtLocation(program.getSourceFile(entryFile));
+    const categorySymbols = checker.getExportsOfModule(moduleSymbol);
+    const apiData = [];
+    for (const categorySymbol of categorySymbols) {
+      var _ref, _categoryUrlMatch$;
+      // 分类的类型
+      const categoryType = checker.getTypeOfSymbolAtLocation(categorySymbol, categorySymbol.getDeclarations()[0]);
+
+      // 处理器列表
+      const handlerSymbols = categoryType.getProperties();
+
+      // 分类源文件
+      const categorySourceFile = handlerSymbols[0].getDeclarations()[0].getSourceFile();
+
+      // 分类源文件路径
+      const categorySourceFilePath = categorySourceFile.fileName;
+
+      // 分类 URL
+      const categoryUrlMatch = categorySourceFilePath.match(this.categoryUrlRe);
+      let categoryUrl = (_ref = (_categoryUrlMatch$ = categoryUrlMatch[1]) != null ? _categoryUrlMatch$ : categoryUrlMatch[2]) != null ? _ref : '';
+      categoryUrl = categoryUrl === '' ? '/' : `/${categoryUrl}/`;
+      for (const handlerSymbol of handlerSymbols) {
+        // 处理器名称
+        const handlerName = handlerSymbol.getName();
+
+        // 处理器 URL
+        const handlerUrl = `${categoryUrl}${handlerName}`;
+
+        // 处理器注释
+        const handlerComment = this.getComment(handlerSymbol);
+        if (handlerComment.tags.has('private')) {
+          this.debug('跳过生成接口: %s', `${handlerUrl}`);
+          continue;
+        }
+        this.debug('生成接口: %s ...', handlerUrl);
+        const handlerNode = handlerSymbol.getDeclarations()[0];
+        const handlerType = checker.getTypeAtLocation(handlerNode);
+        const [requestType, responseType, methodType] = checker.getTypeArguments(handlerType);
+        const handlerCategory = pascalCase(categoryUrl) || 'Index';
+        const handlerDescription = handlerComment.description || handlerUrl;
+        const handlerMethod = methodType.value;
+        const httpMethod = HandlerMethodToHttpMethod[handlerMethod];
+        const requestData = this.getApiDto({
+          type: requestType
+        });
+        const responseData = this.getApiDto({
+          type: responseType
+        });
+        const requestDataJsonSchema = this.apiDataToJsonSchema(requestData);
+        const responseDataJsonSchema = this.apiDataToJsonSchema(responseData);
+        apiData.push({
+          category: handlerCategory,
+          name: handlerDescription,
+          path: handlerUrl,
+          handlerMethod: handlerMethod,
+          method: httpMethod,
+          requestData: requestData,
+          responseData: responseData,
+          requestDataJsonSchema: requestDataJsonSchema,
+          responseDataJsonSchema: responseDataJsonSchema
+        });
+      }
+    }
+    this.debug('写入文件...');
+    await Promise.all([fs.outputJSON(path.join(this.cwd, 'temp/api.json'), apiData, {
+      spaces: 2
+    }), fs.outputJSON(path.join(this.cwd, 'temp/yapi.json'), this.genYApiData(apiData), {
+      spaces: 2
+    })]);
   }
-  getComment(declaration) {
-    var _declaration$getLeadi;
-    const text = ((declaration == null || (_declaration$getLeadi = declaration.getLeadingCommentRanges()[0]) == null ? void 0 : _declaration$getLeadi.getText()) || '').trim();
-    const comment = parseComment.parse(text)[0];
-    const description = (comment == null ? void 0 : comment.description) || '';
-    const tags = new Map();
-    comment == null ? void 0 : comment.tags.forEach(tag => {
-      tags.set(tag.tag, tag.description);
+
+  // 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 = ts.displayPartsToString(symbol.getDocumentationComment(this.checker)).trim();
+    const tags = symbol.getJsDocTags().map(item => {
+      return {
+        label: item.name,
+        value: ts.displayPartsToString(item.text).trim()
+      };
     });
     return {
-      existing: !!comment,
+      existing: !!description,
       description: description,
-      tags: tags
+      tags: tags.reduce((res, item) => {
+        res.set(item.label, item.value);
+        return res;
+      }, new Map())
     };
   }
-  getCommentBySymbol(symbol) {
-    var _this$getComment;
-    return ((_this$getComment = this.getComment(symbol.getDeclarations()[0])) == null ? void 0 : _this$getComment.description) || '';
-  }
-  typeToApiData(type, _symbol) {
-    var _type$getSymbol, _type$getSymbol2, _type$getSymbol3;
-    // ws
-    if (((_type$getSymbol = type.getSymbol()) == null ? void 0 : _type$getSymbol.getName()) === 'SocketStream') {
+  getApiDto({
+    type,
+    keySymbol = type.symbol || type.aliasSymbol
+  }) {
+    var _valueSymbol;
+    const hasTypeFlag = (flag, _type = type) => (_type.flags & flag) === flag;
+    let valueSymbol = type.symbol || type.aliasSymbol;
+    const keySymbolName = (keySymbol == null ? void 0 : keySymbol.getName()) || '';
+    let valueSymbolName = ((_valueSymbol = valueSymbol) == null ? void 0 : _valueSymbol.getName()) || '';
+    const comment = this.getComment(keySymbol);
+    let isRequired = keySymbol ? !(keySymbol.getFlags() & ts.SymbolFlags.Optional) : false;
+
+    // WS
+    if (valueSymbolName === 'SocketStream') {
       return {
         name: 'ws',
-        desc: 'ws',
-        required: false,
+        desc: comment.description,
+        required: isRequired,
         type: 'object',
-        children: [],
-        enum: []
+        enum: [],
+        children: []
       };
     }
 
-    // XFile
-    if (((_type$getSymbol2 = type.getSymbol()) == null ? void 0 : _type$getSymbol2.getName()) === 'MultipartFile') {
-      const symbol = _symbol || type.getSymbol();
+    // 文件
+    if (valueSymbolName === 'MultipartFile') {
       return {
         name: 'file',
-        desc: symbol && this.getCommentBySymbol(symbol) || '',
-        required: !!symbol && !(symbol.getFlags() & ts.SymbolFlags.Optional),
+        desc: comment.description,
+        required: isRequired,
         type: 'file',
-        children: [],
-        enum: []
+        enum: [],
+        children: []
       };
     }
-    let isRequired = true;
-    let isUnion = type.isUnion();
-    const unionTypes = isUnion ? type.getUnionTypes().filter(item => !item.isBooleanLiteral() && !item.isNull() && !item.isUndefined()) : [];
-    isUnion = !!unionTypes.length;
+
+    // 联合类型
+    // 布尔、枚举也会用这表示
+    const rawUnionTypes = type.isUnion() && type.types || [];
+    const unionTypes = rawUnionTypes.filter(item => !hasTypeFlag(ts.TypeFlags.Null, item) && !hasTypeFlag(ts.TypeFlags.Undefined, item));
+    const isUnion = !!unionTypes.length;
     if (isUnion) {
-      if (unionTypes.length === 1 && !unionTypes[0].isLiteral()) {
-        isUnion = false;
+      var _this$checker$getBase;
+      if (unionTypes.length !== rawUnionTypes.length) {
+        isRequired = false;
       }
-      // 兼容 prisma 生成的类型用 null 表示可选
-      isRequired = unionTypes.length === type.getUnionTypes().length;
-      // 必须用 getBaseTypeOfLiteralType 获取枚举字面量的原始类型
-      type = unionTypes[0].getBaseTypeOfLiteralType();
+      type = unionTypes[0];
+      valueSymbol = type.symbol || type.aliasSymbol;
+      valueSymbolName = ((_this$checker$getBase = this.checker.getBaseTypeOfLiteralType(type).getSymbol()) == null ? void 0 : _this$checker$getBase.getName()) || '';
     }
-    const isEnum = type.isEnum();
-    const enumData = isEnum ?
-    // @ts-ignore
-    type.compilerType.types.reduce((res, item) => {
-      res[item.getSymbol().getName()] = item.value;
-      return res;
-    }, {}) : {};
-    const enumKeys = Object.keys(enumData);
-    const enumValues = Object.values(enumData);
     const isIntersection = type.isIntersection();
-    const intersectionTypes = isIntersection && type.getIntersectionTypes();
-    const isArray = type.isArray();
-    const isString = isEnum ? typeof enumValues[0] === 'string' : type.isString() || ['Date'].includes(((_type$getSymbol3 = type.getSymbol()) == null ? void 0 : _type$getSymbol3.getName()) || '');
-    const isNumber = isEnum ? typeof enumValues[0] === 'number' : type.isNumber();
-    const isBoolean = type.isBoolean() || type.isUnion() && type.getUnionTypes().some(item => item.isBooleanLiteral()) && type.getUnionTypes().every(item => item.isBooleanLiteral() || item.isNull() || item.isUndefined());
-    const isObject = !isArray && !isString && !isNumber && !isBoolean && type.isObject() ||
-    // 将交集类型视为对象
+    const intersectionTypes = isIntersection && type.types || [];
+    const isDate = valueSymbolName === 'Date';
+    const isBigIntLiteral = hasTypeFlag(ts.TypeFlags.BigIntLiteral);
+    const isBigInt = hasTypeFlag(ts.TypeFlags.BigInt) || isBigIntLiteral;
+    const isArray = valueSymbolName === 'Array' || valueSymbolName === 'ReadonlyArray';
+    const isStringLiteral = hasTypeFlag(ts.TypeFlags.StringLiteral);
+    const isString = hasTypeFlag(ts.TypeFlags.String) || isStringLiteral ||
+    // BigInt 类型视为字符串
+    isBigInt ||
+    // Date 类型视为字符串
+    isDate;
+    const isNumberLiteral = hasTypeFlag(ts.TypeFlags.NumberLiteral);
+    const isNumber = hasTypeFlag(ts.TypeFlags.Number) || isNumberLiteral;
+    const isBoolean = hasTypeFlag(ts.TypeFlags.Boolean) || hasTypeFlag(ts.TypeFlags.BooleanLiteral);
+    const isLiteral = isStringLiteral || isNumberLiteral || isBigIntLiteral;
+    const isObject = !isArray && !isString && !isNumber && !isBoolean && hasTypeFlag(ts.TypeFlags.Object) ||
+    // 交集类型视为对象
     isIntersection;
-    const symbol = _symbol || type.getSymbol();
-    const parentSymbol = symbol;
-    const apiName = (symbol == null ? void 0 : symbol.getName()) || '__type';
-    const apiDesc = [symbol && this.getCommentBySymbol(symbol), isEnum && `枚举：${enumKeys.map((key, index) => `${key}->${enumValues[index]}`).join('; ')}`].filter(Boolean).join('\n');
-    const apiEnum = isUnion ? unionTypes.map(t => t.getLiteralValue()) : isEnum ? enumValues : [];
+    const apiName = keySymbolName || '__type';
+    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 === false ? false : !!symbol && !(symbol.getFlags() & ts.SymbolFlags.Optional);
-    const apiChildren = isArray ? [this.typeToApiData(type.getArrayElementTypeOrThrow())] : isObject ? ii(() => {
-      const context = type._context;
-      const compilerFactory = context.compilerFactory;
-      const rawChecker = type.compilerType.checker;
-      let symbols = [];
-      if (intersectionTypes) {
-        // https://github.com/microsoft/TypeScript/issues/38184
-        symbols = rawChecker.getAllPossiblePropertiesOfTypes(intersectionTypes.map(item => item.compilerType))
-        // https://github.com/dsherret/ts-morph/blob/a7072fcf6f9babb784b40f0326c80dea4563a4aa/packages/ts-morph/src/compiler/types/Type.ts#L296
-        .map(symbol => compilerFactory.getSymbol(symbol));
-      } else {
-        // symbols = type.getApparentProperties()
-        // https://github.com/microsoft/TypeScript/issues/38184
-        symbols = rawChecker.getAllPossiblePropertiesOfTypes([type.compilerType])
-        // https://github.com/dsherret/ts-morph/blob/a7072fcf6f9babb784b40f0326c80dea4563a4aa/packages/ts-morph/src/compiler/types/Type.ts#L296
-        .map(symbol => compilerFactory.getSymbol(symbol));
-      }
-      return symbols.map(symbol => {
-        return this.typeToApiData(!symbol.compilerSymbol.declarations ?
-        // 对于复杂对象，没有定义的，通过 type 直接获取（在前面通过 getText 预处理得到）
-        symbol.compilerSymbol.type ? compilerFactory.getType(symbol.compilerSymbol.type) :
-        // fix: symbol.compilerSymbol.type 为 undefined
-        // https://github.com/styleguidist/react-docgen-typescript/blob/master/src/parser.ts#L696
-        compilerFactory.getType(rawChecker.getTypeOfSymbolAtLocation(
-        // @ts-ignore
-        symbol.compilerSymbol,
-        // @ts-ignore
-        parentSymbol.compilerSymbol.declarations[0])) : this.getTypeBySymbol(symbol), symbol);
+    const apiRequired = isRequired;
+    const apiChildren = isArray ? [this.getApiDto({
+      type: this.checker.getTypeArguments(type)[0]
+    })] : isObject ? ii(() => {
+      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 {
@@ -142,7 +233,6 @@ export class ApiGenerator {
     if (apiData.type === 'object') {
       jsonSchema.type = 'object';
       jsonSchema.properties = apiData.children.reduce((res, item) => {
-        ;
         res[item.name] = this.apiDataToJsonSchema(item);
         return res;
       }, {});
@@ -219,62 +309,4 @@ export class ApiGenerator {
       list: data[cat]
     }));
   }
-  async generate() {
-    this.debug('启动项目...');
-    this.project = new ts.Project({
-      tsConfigFilePath: path.join(this.cwd, 'tsconfig.json')
-    });
-    this.debug('加载文件...');
-    const sourceFile = this.project.createSourceFile(path.join(this.cwd, 'src/generated/handlers.ts'), await fs.readFile(path.join(this.cwd, 'node_modules/.x/handlers.ts'), 'utf-8'));
-    this.debug('导出处理器...');
-    const handlerGroup = sourceFile.getExportSymbols();
-    const handles = [];
-    this.debug('生成API文档...');
-    for (const handlerList of handlerGroup) {
-      const handlerListSourceFile = this.getTypeBySymbol(handlerList).getProperties()[0].getDeclarations()[0].getSourceFile();
-      const basePath = `/${handlerListSourceFile.getFilePath().replace('.ts', '').split('/src/handlers/')[1].replace(/(^|\/)index$/, '/').split('/').map(v => snakeCase(v)).join('/')}/`.replace(/\/{2,}/g, '/');
-      for (const handler of handlerListSourceFile.getVariableStatements().filter(item => item.isExported())) {
-        // 重要：这一步必须，先调一遍 getText 获取看到的对象，后续对于复杂定义才不会报错
-        handler.getDeclarations().forEach(exp => {
-          exp.getType().getText();
-        });
-        const handlerExp = handler.getDeclarations()[0];
-        const handlerPath = `${basePath}${handlerExp.getName()}`;
-        this.debug('生成接口: %s ...', handlerPath);
-        const [requestType, responseType, methodType] = handlerExp.getType().getTypeArguments();
-        const handlerComment = this.getComment(handlerExp.getParent().getParent());
-        if (handlerComment.tags.has('private')) {
-          this.debug('跳过生成接口: %s', `${handlerPath}`);
-          continue;
-        }
-        const handlerCategory = pascalCase(basePath) || 'Index';
-        const handlerName = handlerComment.description || handlerPath;
-        const handlerMethod = methodType.getLiteralValueOrThrow();
-        const serverMethod = HandlerMethodToHttpMethod[handlerMethod];
-        const requestData = this.typeToApiData(requestType);
-        const responseData = this.typeToApiData(responseType);
-        const requestDataJsonSchema = this.apiDataToJsonSchema(requestData);
-        const responseDataJsonSchema = this.apiDataToJsonSchema(responseData);
-        handles.push({
-          category: handlerCategory,
-          name: handlerName,
-          path: handlerPath,
-          handlerMethod: handlerMethod,
-          method: serverMethod,
-          requestData: requestData,
-          responseData: responseData,
-          requestDataJsonSchema: requestDataJsonSchema,
-          responseDataJsonSchema: responseDataJsonSchema
-        });
-      }
-    }
-    this.debug('写入文件...');
-    await Promise.all([fs.outputJSON(path.join(this.cwd, 'temp/api.json'), handles, {
-      spaces: 2
-    }), fs.outputJSON(path.join(this.cwd, 'temp/yapi.json'), this.genYApiData(handles), {
-      spaces: 2
-    })]);
-  }
-}
-
-// new ApiGenerator().generate()
+}

package/lib/cli/api_generator1.d.ts

@@ -0,0 +1,44 @@
+import createDebug from 'debug';
+import type { JSONSchema4 } from 'json-schema';
+import * as ts from 'ts-morph';
+import type { XHandler } from '../core/types';
+interface ApiData {
+    name: string;
+    desc: string;
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'file';
+    enum: any[];
+    required: boolean;
+    children: ApiData[];
+}
+type ApiHandles = Array<{
+    category: string;
+    name: string;
+    path: string;
+    handlerMethod: XHandler.Method;
+    method: string;
+    requestData: ApiData;
+    responseData: ApiData;
+    requestDataJsonSchema: JSONSchema4;
+    responseDataJsonSchema: JSONSchema4;
+}>;
+export declare class ApiGenerator1 {
+    debug: createDebug.Debugger;
+    cwd: string;
+    project: ts.Project;
+    getTypeBySymbol(symbol: ts.Symbol): ts.Type;
+    getComment(declaration?: ts.Node): {
+        existing: boolean;
+        description: string;
+        tags: Map<string, string>;
+    };
+    getCommentBySymbol(symbol: ts.Symbol): string;
+    typeToApiData(type: ts.Type, _symbol?: ts.Symbol): ApiData;
+    apiDataToJsonSchema(apiData: ApiData, jsonSchema?: JSONSchema4): JSONSchema4;
+    genYApiData(handles: ApiHandles): {
+        name: string;
+        desc: string;
+        list: any;
+    }[];
+    generate(): Promise<void>;
+}
+export {};