sumor 1.3.0 → 2.0.0

package/modules/middlewares/apiMiddleware/load/index.js

@@ -0,0 +1,35 @@
+import path from 'path'
+import { glob } from 'glob'
+import { getRelativePath } from '../../../utils/pathUtils.js'
+import loadConfig from '../../../utils/loadConfig.js'
+import { pathToFileURL } from 'url'
+
+export default async apiRoot => {
+  // 解析 apiRoot 的绝对路径
+  const absoluteApiRoot = path.resolve(apiRoot)
+
+  // 使用 glob 扫描 apiRoot 目录中的 .js 文件
+  const jsFiles = glob.sync(`${absoluteApiRoot}/**/*.js`)
+
+  const apis = {}
+  for (const file of jsFiles) {
+    const relativePath = getRelativePath(apiRoot, file)
+    const route = '/' + relativePath
+
+    const config = await loadConfig(file.split('.')[0])
+    let callback
+    try {
+      const program = await import(pathToFileURL(file))
+      callback = program.default
+    } catch (e) {
+      callback = null
+    }
+
+    apis[route] = {
+      ...config,
+      callback
+    }
+  }
+
+  return apis
+}

package/modules/middlewares/apiMiddleware/load/index.test.js

@@ -0,0 +1,30 @@
+import { describe, it, expect } from '@jest/globals'
+import load from './index.js'
+import fse from 'fs-extra'
+import path from 'path'
+import tmp from '../../../../test-utils/tmp.js'
+
+describe('load', () => {
+  it('应该加载指定目录下的所有.js文件', async () => {
+    const tmpDir = await tmp('apiLoader')
+    await fse.writeFile(path.join(tmpDir, 'test1.js'), 'syntax error')
+    await fse.writeFile(path.join(tmpDir, 'test2.js'), 'export default ()=>{return "test2";}')
+    await fse.writeFile(path.join(tmpDir, 'test2.json'), '{"name":"Test 2"}')
+    await fse.writeFile(path.join(tmpDir, 'test4.ts'), 'export default ()=>{return "test4";}')
+
+    await fse.ensureDir(tmpDir + '/deep')
+    await fse.writeFile(
+      path.join(tmpDir, 'deep', 'test3.js'),
+      'export default ()=>{return "test3";}'
+    )
+
+    const apis = await load(tmpDir)
+    expect(Object.keys(apis).length).toBe(3)
+    expect(Object.keys(apis).sort()).toStrictEqual(['/deep/test3', '/test1', '/test2'])
+    expect(apis['/test2'].name).toBe('Test 2')
+
+    // 检查加载失败的文件
+    expect(apis['/test1'].callback).toBeNull()
+    expect(apis['/test2'].callback()).toBe('test2')
+  })
+})

package/modules/middlewares/apiMiddleware/metadataToSwagger.js

@@ -0,0 +1,139 @@
+/**
+ * 将API元数据转换为Swagger UI格式
+ * @param {Object} metadata - API元数据对象
+ * @returns {Object} Swagger UI格式的API文档
+ */
+export default function convertToSwagger(metadata) {
+  const swaggerDoc = {
+    openapi: '3.0.0',
+    info: {
+      title: metadata.name,
+      version: '1.0.0',
+      description: metadata.desc || '接口文档'
+    },
+    tags: [
+      {
+        name: '接口列表',
+        description: `共${Object.keys(metadata.apis).length}个接口`
+      }
+    ],
+    paths: {},
+    components: {
+      schemas: {}
+    }
+  }
+
+  // 遍历所有API端点
+  Object.entries(metadata.apis)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .forEach(([path, apiInfo]) => {
+      const swaggerPath = {}
+
+      let methods = apiInfo.methods
+      if (methods.includes('POST')) {
+        methods = ['POST']
+      } else if (methods.includes('GET')) {
+        methods = ['GET']
+      }
+
+      // 处理每个HTTP方法
+      methods.forEach(method => {
+        const methodLower = method.toLowerCase()
+        swaggerPath[methodLower] = {
+          tags: ['接口列表'],
+          summary: apiInfo.name || path,
+          description: apiInfo.desc || '',
+          parameters: [],
+          responses: {
+            200: {
+              description: '成功响应',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object'
+                  }
+                }
+              }
+            }
+          }
+        }
+
+        // 处理路径参数
+        if (path.includes(':')) {
+          const pathParams = path.match(/:[^/]+/g) || []
+          pathParams.forEach(param => {
+            const paramName = param.slice(1)
+            const paramInfo = apiInfo.parameters[paramName]
+            if (paramInfo) {
+              swaggerPath[methodLower].parameters.push({
+                name: paramName,
+                in: 'path',
+                required: paramInfo.required,
+                schema: {
+                  type: paramInfo.type,
+                  description: paramInfo.desc
+                },
+                description: paramInfo.name
+              })
+            }
+          })
+        }
+
+        // 处理查询参数
+        Object.entries(apiInfo.parameters).forEach(([paramName, paramInfo]) => {
+          if (!path.includes(`:${paramName}`) && paramInfo.type !== 'file') {
+            swaggerPath[methodLower].parameters.push({
+              name: paramName,
+              in: 'query',
+              required: paramInfo.required,
+              schema: {
+                type: paramInfo.type,
+                description: paramInfo.desc
+              },
+              description: paramInfo.name
+            })
+          }
+        })
+
+        // 处理文件上传
+        if (method === 'POST' && Object.values(apiInfo.parameters).some(p => p.type === 'file')) {
+          swaggerPath[methodLower].requestBody = {
+            content: {
+              'multipart/form-data': {
+                schema: {
+                  type: 'object',
+                  properties: {}
+                }
+              }
+            }
+          }
+
+          // 添加文件参数到schema
+          Object.entries(apiInfo.parameters).forEach(([paramName, paramInfo]) => {
+            if (paramInfo.type === 'file') {
+              swaggerPath[methodLower].requestBody.content['multipart/form-data'].schema.properties[
+                paramName
+              ] = {
+                type: 'array',
+                items: {
+                  type: 'string',
+                  format: 'binary'
+                },
+                description: paramInfo.desc || paramInfo.name
+              }
+            }
+          })
+        }
+      })
+
+      // 将处理后的路径添加到swagger文档中
+      swaggerDoc.paths[path] = swaggerPath
+    })
+
+  return swaggerDoc
+}
+
+// 使用示例
+// import metadata from './sample-metadata.json' assert { type: 'json' };
+// const swaggerDoc = convertToSwagger(metadata);
+// console.log(JSON.stringify(swaggerDoc, null, 2));

package/modules/middlewares/apiMiddleware/prepareData/format/caseSensitive.js

@@ -0,0 +1,26 @@
+export default (parameter, value) => {
+  const needLowerCase = parameter.toLowerCase === true
+  const needUpperCase = parameter.toUpperCase === true
+
+  if (value !== null && needLowerCase) {
+    switch (parameter.type) {
+      case 'string':
+        value = value.toLowerCase()
+        break
+      default:
+        break
+    }
+  }
+
+  if (value !== null && needUpperCase) {
+    switch (parameter.type) {
+      case 'string':
+        value = value.toUpperCase()
+        break
+      default:
+        break
+    }
+  }
+
+  return value
+}

package/modules/middlewares/apiMiddleware/prepareData/format/caseSensitive.test.js

@@ -0,0 +1,36 @@
+import { describe, it, expect } from '@jest/globals'
+import caseSensitive from './caseSensitive'
+
+describe('区分大小写', () => {
+  it('当参数.toLowerCase 为 true 时，应将字符串转换为小写', () => {
+    const result = caseSensitive({ toLowerCase: true, type: 'string' }, 'Hello World')
+    expect(result).toBe('hello world')
+  })
+
+  it('当参数.toUpperCase 为 true 时，应将字符串转换为大写', () => {
+    const result = caseSensitive({ toUpperCase: true, type: 'string' }, 'Hello World')
+    expect(result).toBe('HELLO WORLD')
+  })
+
+  it('当参数.type 不是字符串时，应返回原始值', () => {
+    const result = caseSensitive({ toLowerCase: true, type: 'number' }, 12345)
+    expect(result).toBe(12345)
+  })
+
+  it('当值为 null 时，应返回 null', () => {
+    const result = caseSensitive({ toLowerCase: true, type: 'string' }, null)
+    expect(result).toBeNull()
+  })
+
+  it('当 toLowerCase 和 toUpperCase 同时为 true 时，应优先处理为大写', () => {
+    const result = caseSensitive(
+      {
+        toLowerCase: true,
+        toUpperCase: true,
+        type: 'string'
+      },
+      'Hello World'
+    )
+    expect(result).toBe('HELLO WORLD') // 大写优先
+  })
+})

package/modules/middlewares/apiMiddleware/prepareData/format/convertType.js

@@ -0,0 +1,48 @@
+export default (type, value) => {
+  if (value === null) return value
+
+  switch (type) {
+    case 'string':
+      if (typeof value !== 'string') {
+        return JSON.stringify(value)
+      } else {
+        return String(value)
+      }
+    case 'number':
+      if (isNaN(Number(value))) {
+        throw new Error('INVALID')
+      }
+      return Number(value)
+    case 'boolean':
+      return Boolean(value)
+    case 'array':
+      if (typeof value === 'string') {
+        try {
+          return JSON.parse(value)
+        } catch {
+          throw new Error('INVALID')
+        }
+      } else if (!Array.isArray(value)) {
+        throw new Error('INVALID')
+      }
+      return value
+    case 'object':
+      if (typeof value === 'string') {
+        try {
+          return JSON.parse(value)
+        } catch {
+          throw new Error('INVALID')
+        }
+      } else if (typeof value !== 'object') {
+        throw new Error('INVALID')
+      }
+      return value
+    case 'file':
+      if (!Array.isArray(value)) {
+        throw new Error('INVALID')
+      }
+      return value
+    default:
+      return value
+  }
+}

package/modules/middlewares/apiMiddleware/prepareData/format/convertType.test.js

@@ -0,0 +1,53 @@
+import { describe, test, expect } from '@jest/globals'
+import convertType from './convertType.js'
+
+describe('参数类型转换', () => {
+  test('应转换为字符串', () => {
+    expect(convertType('string', 123)).toBe('123')
+    expect(convertType('string', true)).toBe('true')
+  })
+
+  test('应转换为数字', () => {
+    expect(convertType('number', '123')).toBe(123)
+    expect(() => convertType('number', 'abc')).toThrow('INVALID')
+  })
+
+  test('应转换为布尔值', () => {
+    expect(convertType('boolean', 1)).toBe(true)
+    expect(convertType('boolean', 0)).toBe(false)
+  })
+
+  test('应转换为数组', () => {
+    expect(convertType('array', '[1,2,3]')).toEqual([1, 2, 3])
+    expect(convertType('array', [1, 2, 3])).toEqual([1, 2, 3])
+    expect(() => convertType('array', 'not an array')).toThrow('INVALID')
+    expect(() => convertType('array', 123)).toThrow('INVALID')
+  })
+
+  test('对象类型传入数组应报错', () => {
+    expect(() => convertType('array', { key: 'value' })).toThrow('INVALID')
+  })
+
+  test('应转换为对象', () => {
+    expect(convertType('object', { key: 'value' })).toEqual({ key: 'value' })
+    expect(convertType('object', '{"key":"value"}')).toEqual({ key: 'value' })
+    expect(() => convertType('object', 'not an object')).toThrow('INVALID')
+    expect(() => convertType('object', 123)).toThrow('INVALID')
+  })
+
+  test('对于未知类型应返回原值', () => {
+    expect(convertType('unknown', 'value')).toBe('value')
+  })
+
+  test('对于 null 值应返回 null', () => {
+    expect(convertType('string', null)).toBeNull()
+  })
+
+  test('应转换为文件类型', () => {
+    expect(() => convertType('file', 'not an array')).toThrow('INVALID')
+    expect(() => convertType('file', 123)).toThrow('INVALID')
+    expect(() => convertType('file', {})).toThrow('INVALID')
+    expect(convertType('file', [])).toEqual([])
+    expect(convertType('file', [{ path: '' }, { path: '' }])).toEqual([{ path: '' }, { path: '' }])
+  })
+})

package/modules/middlewares/apiMiddleware/prepareData/format/defaultValue.js

@@ -0,0 +1,31 @@
+export default (parameter, value) => {
+  if (value === undefined) {
+    value = null
+  }
+  if (parameter.type !== 'string' && value === '') {
+    value = null
+  }
+
+  const defaultValue = parameter.default
+  const hasDefault = defaultValue !== undefined && defaultValue !== null
+
+  if (hasDefault) {
+    if (value === '' && parameter.type === 'string') {
+      value = null
+    }
+    if (value === null) {
+      switch (parameter.type) {
+        case 'string':
+          value = defaultValue
+          break
+        case 'number':
+          value = defaultValue
+          break
+        default:
+          break
+      }
+    }
+  }
+
+  return value
+}

package/modules/middlewares/apiMiddleware/prepareData/format/defaultValue.test.js

@@ -0,0 +1,31 @@
+import { describe, test, expect } from '@jest/globals'
+import defaultValue from './defaultValue.js'
+
+describe('defaultValue 函数', () => {
+  test('当值为 undefined 时应返回 null', () => {
+    expect(defaultValue({ type: 'string' }, undefined)).toBeNull()
+  })
+
+  test('当值为空字符串且类型为非字符串时应返回 null', () => {
+    expect(defaultValue({ type: 'number' }, '')).toBeNull()
+  })
+
+  test('当有默认值且值为 null 时应返回默认值', () => {
+    expect(defaultValue({ type: 'string', default: 'default' }, null)).toBe('default')
+    expect(defaultValue({ type: 'number', default: 42 }, null)).toBe(42)
+  })
+
+  test('当值为空字符串且类型为字符串时应返回默认值', () => {
+    expect(defaultValue({ type: 'string', default: 'default' }, '')).toBe('default')
+  })
+
+  test('当无默认值时应保持原值', () => {
+    expect(defaultValue({ type: 'string' }, 'value')).toBe('value')
+    expect(defaultValue({ type: 'number' }, 123)).toBe(123)
+  })
+
+  test('当默认值为 null 或 undefined 时应保持原值', () => {
+    expect(defaultValue({ type: 'string', default: null }, null)).toBeNull()
+    expect(defaultValue({ type: 'string', default: undefined }, null)).toBeNull()
+  })
+})

package/modules/middlewares/apiMiddleware/prepareData/format/index.js

@@ -0,0 +1,18 @@
+import convertType from './convertType.js'
+import defaultValue from './defaultValue.js'
+import trim from './trim.js'
+import caseSensitive from './caseSensitive.js'
+import precision from './precision.js'
+
+export default (parameter, value) => {
+  value = defaultValue(parameter, value)
+
+  // 类型强制转换
+  value = convertType(parameter.type, value)
+
+  value = trim(parameter, value)
+  value = caseSensitive(parameter, value)
+  value = precision(parameter, value)
+
+  return value
+}

package/modules/middlewares/apiMiddleware/prepareData/format/index.test.js

@@ -0,0 +1,40 @@
+import { describe, it, expect } from '@jest/globals'
+import format from './index.js'
+
+describe('格式化', () => {
+  it('当值为 undefined 时，应应用默认值', () => {
+    const parameter = { type: 'string', default: 'defaultValue' }
+    const result = format(parameter, undefined)
+    expect(result).toBe('defaultValue')
+  })
+
+  it('当 trim 不为 false 时，应去除字符串两端的空格', () => {
+    const parameter = { type: 'string', trim: true }
+    const result = format(parameter, '  test  ')
+    expect(result).toBe('test')
+  })
+
+  it('当 toLowerCase 为 true 时，应将字符串转换为小写', () => {
+    const parameter = { type: 'string', toLowerCase: true }
+    const result = format(parameter, 'TEST')
+    expect(result).toBe('test')
+  })
+
+  it('当 toUpperCase 为 true 时，应将字符串转换为大写', () => {
+    const parameter = { type: 'string', toUpperCase: true }
+    const result = format(parameter, 'test')
+    expect(result).toBe('TEST')
+  })
+
+  it('当指定小数位数时，应处理数字精度', () => {
+    const parameter = { type: 'number', decimal: 2 }
+    const result = format(parameter, 123.456)
+    expect(result).toBe(123.46)
+  })
+
+  it('当没有匹配规则时，应保持原值不变', () => {
+    const parameter = { type: 'string' }
+    const result = format(parameter, 'unchanged')
+    expect(result).toBe('unchanged')
+  })
+})

package/modules/middlewares/apiMiddleware/prepareData/format/precision.js

@@ -0,0 +1,12 @@
+export default (parameter, value) => {
+  if (
+    parameter.type === 'number' &&
+    parameter.decimal !== undefined &&
+    parameter.decimal !== null &&
+    typeof value === 'number'
+  ) {
+    value = Number(value.toFixed(parameter.decimal))
+  }
+
+  return value
+}

package/modules/middlewares/apiMiddleware/prepareData/format/precision.test.js

@@ -0,0 +1,33 @@
+import { describe, it, expect } from '@jest/globals'
+
+import precision from './precision'
+
+describe('precision', () => {
+  it('should round a number to the specified decimal places', () => {
+    const parameter = { type: 'number', decimal: 2 }
+    const result = precision(parameter, 3.14159)
+    expect(result).toBe(3.14)
+  })
+
+  it('should return the original number if decimal is not specified', () => {
+    const parameter = { type: 'number' }
+    const result = precision(parameter, 3.14159)
+    expect(result).toBe(3.14159)
+  })
+
+  it('should handle null or undefined decimal gracefully', () => {
+    const parameter = { type: 'number', decimal: null }
+    const result = precision(parameter, 3.14159)
+    expect(result).toBe(3.14159)
+
+    parameter.decimal = undefined
+    const result2 = precision(parameter, 3.14159)
+    expect(result2).toBe(3.14159)
+  })
+
+  it('should return the original value if it is not a number', () => {
+    const parameter = { type: 'number', decimal: 2 }
+    const result = precision(parameter, 'not-a-number')
+    expect(result).toBe('not-a-number')
+  })
+})

package/modules/middlewares/apiMiddleware/prepareData/format/trim.js

@@ -0,0 +1,15 @@
+export default (parameter, value) => {
+  const needTrim = parameter.trim !== false
+
+  if (value !== null && needTrim) {
+    switch (parameter.type) {
+      case 'string':
+        value = value.trim()
+        break
+      default:
+        break
+    }
+  }
+
+  return value
+}

package/modules/middlewares/apiMiddleware/prepareData/format/trim.test.js

@@ -0,0 +1,24 @@
+import { describe, it, expect } from '@jest/globals'
+import trim from './trim'
+
+describe('去除空格', () => {
+  it('应去除字符串两端的空格', () => {
+    const parameter = { type: 'string', trim: true }
+    expect(trim(parameter, '  hello  ')).toBe('hello')
+  })
+
+  it('当 trim 设置为 false 时，不应去除空格', () => {
+    const parameter = { type: 'string', trim: false }
+    expect(trim(parameter, '  hello  ')).toBe('  hello  ')
+  })
+
+  it('对于非字符串类型的值，应返回原始值', () => {
+    const parameter = { type: 'number', trim: true }
+    expect(trim(parameter, 123)).toBe(123)
+  })
+
+  it('应优雅地处理 null 值', () => {
+    const parameter = { type: 'string', trim: true }
+    expect(trim(parameter, null)).toBe(null)
+  })
+})

package/modules/middlewares/apiMiddleware/prepareData/index.js

@@ -0,0 +1,29 @@
+import format from './format/index.js'
+import validate from './validate/index.js'
+
+export default (req, apiKey, parameters) => {
+  parameters = parameters || {}
+  const data = req.data || {}
+
+  const { Error } = req.namespace('SUMOR_API')
+  const { Error: APIError } = req.namespace('API')
+
+  const errors = []
+
+  for (const key in parameters) {
+    const parameter = parameters[key] || {}
+    data[key] = format(parameter, data[key])
+
+    const parameterErrors = validate(Error, APIError, apiKey, parameter, data[key])
+
+    if (parameterErrors.length) {
+      errors.push(new Error('API_PARAMETER_NOT_VALID', { key }, parameterErrors))
+    }
+  }
+
+  if (errors.length) {
+    throw new Error('API_PARAMETERS_NOT_VALID', {}, errors)
+  }
+
+  return data
+}