feat: support route version for http (#4407)

* fix: special in filename

* fix: middleware pos

* fix: middleware pos

* fix: middleware pos

* fix: middleware pos

Author: czy88840616

packages/core/src/decorator/web/controller.ts

@@ -11,6 +11,10 @@ export interface ControllerOption {
     description?: string;
     tagName?: string;
     ignoreGlobalPrefix?: boolean;
+    // 版本控制配置
+    version?: string | string[];
+    versionType?: 'URI' | 'HEADER' | 'MEDIA_TYPE' | 'CUSTOM';
+    versionPrefix?: string;
   };
 }
 
@@ -22,6 +26,10 @@ export function Controller(
     description?: string;
     tagName?: string;
     ignoreGlobalPrefix?: boolean;
+    // 版本控制配置
+    version?: string | string[];
+    versionType?: 'URI' | 'HEADER' | 'MEDIA_TYPE' | 'CUSTOM';
+    versionPrefix?: string;
   } = { middleware: [], sensitive: true }
 ): ClassDecorator {
   return (target: any) => {

packages/core/src/service/webRouterService.ts

@@ -119,6 +119,21 @@ export interface RouterInfo {
    * url after wildcard and can be path-to-regexp by path-to-regexp v6
    */
   fullUrlFlattenString?: string;
+
+  /**
+   * version information for API versioning
+   */
+  version?: string | string[];
+
+  /**
+   * version type for API versioning
+   */
+  versionType?: 'URI' | 'HEADER' | 'MEDIA_TYPE' | 'CUSTOM';
+
+  /**
+   * version prefix for URI versioning
+   */
+  versionPrefix?: string;
 }
 
 export type DynamicRouterInfo = Omit<
@@ -248,11 +263,37 @@ export class MidwayWebRouterService {
       controllerOption.prefix || '/'
     );
     const ignorePrefix = controllerOption.prefix || '/';
+
     // if controller set ignore global prefix, all router will be ignore too.
     if (controllerIgnoreGlobalPrefix) {
       prefix = ignorePrefix;
     }
 
+    // Apply version prefix for URI versioning
+    if (
+      controllerOption.routerOptions?.version &&
+      (!controllerOption.routerOptions?.versionType ||
+        controllerOption.routerOptions?.versionType === 'URI')
+    ) {
+      const versionPrefix =
+        controllerOption.routerOptions?.versionPrefix || 'v';
+      const version = Array.isArray(controllerOption.routerOptions.version)
+        ? controllerOption.routerOptions.version[0]
+        : controllerOption.routerOptions.version;
+
+      const versionedPrefix = `/${versionPrefix}${version}`;
+
+      if (controllerIgnoreGlobalPrefix) {
+        prefix = joinURLPath(versionedPrefix, ignorePrefix);
+      } else {
+        prefix = joinURLPath(
+          this.options.globalPrefix,
+          versionedPrefix,
+          controllerOption.prefix || '/'
+        );
+      }
+    }
+
     if (/\*/.test(prefix)) {
       throw new MidwayCommonError(
         `Router prefix ${prefix} can't set string with *`

packages/mcp/src/index.ts

@@ -1,5 +1,4 @@
-export * from './configuration';
+export { MCPConfiguration as Configuration } from './configuration';
 export * from './framework';
 export * from './interface';
 export * from './decorator';
-export { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';

packages/mcp/src/interface.ts

@@ -5,7 +5,7 @@ import {
   NextFunction as BaseNextFunction,
 } from '@midwayjs/core';
 import { Implementation, CallToolResult, GetPromptResult, ReadResourceResult } from '@modelcontextprotocol/sdk/types.js';
-import { ServerOptions} from '@modelcontextprotocol/sdk/server/index.js';
+import { ServerOptions } from '@modelcontextprotocol/sdk/server/index.js';
 
 export interface IMidwayMCPConfigurationOptions extends IConfigurationOptions {
   serverInfo: Implementation;

packages/web-express/src/framework.ts

@@ -56,6 +56,7 @@ export class MidwayExpressFramework extends BaseFramework<
     debug('[express]: create express app');
     this.app = express() as unknown as IMidwayExpressApplication;
     debug('[express]: use root middleware');
+
     // use root middleware
     this.app.use((req, res, next) => {
       const ctx = req as Context;
@@ -66,6 +67,14 @@ export class MidwayExpressFramework extends BaseFramework<
       next();
     });
 
+    // 版本控制配置
+    const versioningConfig = this.configurationOptions.versioning;
+
+    // 如果启用版本控制，添加版本处理中间件
+    if (versioningConfig?.enabled) {
+      this.app.use(this.createVersioningMiddleware(versioningConfig));
+    }
+
     this.defineApplicationProperties({
       useMiddleware: (
         routerPath:
@@ -414,4 +423,60 @@ export class MidwayExpressFramework extends BaseFramework<
   public getFrameworkName() {
     return 'express';
   }
+
+  private createVersioningMiddleware(config: any) {
+    return (req: Context, res: Response, next: NextFunction) => {
+      // 提取版本信息
+      const version = this.extractVersion(req, config);
+      req.apiVersion = version;
+
+      // 对于 URI 版本控制，重写路径
+      if (config.type === 'URI' && version) {
+        const versionPrefix = `/${config.prefix || 'v'}${version}`;
+        if (req.path.startsWith(versionPrefix)) {
+          req.originalPath = req.path;
+          // Express 中需要修改 url 而不是 path
+          req.url = req.url.replace(versionPrefix, '') || '/';
+        }
+      }
+
+      next();
+    };
+  }
+
+  private extractVersion(req: Context, config: any): string | undefined {
+    // 自定义提取函数优先
+    if (config.extractVersionFn) {
+      return config.extractVersionFn(req);
+    }
+
+    const type = config.type || 'URI';
+
+    switch (type) {
+      case 'HEADER': {
+        const headerName = config.header || 'x-api-version';
+        const headerValue = req.headers[headerName];
+        if (typeof headerValue === 'string') {
+          return headerValue.replace(/^v/, '');
+        }
+        return undefined;
+      }
+
+      case 'MEDIA_TYPE': {
+        const accept = req.headers.accept;
+        const paramName = config.mediaTypeParam || 'version';
+        const match = accept?.match(new RegExp(`${paramName}=(\\\\d+)`));
+        return match ? match[1] : undefined;
+      }
+
+      case 'URI': {
+        const prefix = config.prefix || 'v';
+        const uriMatch = req.path.match(new RegExp(`^/${prefix}(\\\\d+)`));
+        return uriMatch ? uriMatch[1] : undefined;
+      }
+
+      default:
+        return config.defaultVersion;
+    }
+  }
 }

packages/web-express/src/interface.ts

@@ -18,7 +18,16 @@ import { ListenOptions } from 'net';
 type Request = IMidwayContext<ExpressRequest>;
 export type Response = ExpressResponse;
 export type NextFunction = ExpressNextFunction;
-export interface Context extends Request {}
+export interface Context extends Request {
+  /**
+   * API version extracted from request
+   */
+  apiVersion?: string;
+  /**
+   * Original path before version processing
+   */
+  originalPath?: string;
+}
 
 /**
  * @deprecated use Context
@@ -90,6 +99,39 @@ export interface IMidwayExpressConfigurationOptions extends IConfigurationOption
    * listen options
    */
   listenOptions?: ListenOptions;
+  /**
+   * API versioning configuration
+   */
+  versioning?: {
+    /**
+     * Enable versioning
+     */
+    enabled: boolean;
+    /**
+     * Versioning type
+     */
+    type?: 'URI' | 'HEADER' | 'MEDIA_TYPE' | 'CUSTOM';
+    /**
+     * Default version if none is specified
+     */
+    defaultVersion?: string;
+    /**
+     * Version prefix for URI versioning (default: 'v')
+     */
+    prefix?: string;
+    /**
+     * Header name for HEADER versioning (default: 'x-api-version')
+     */
+    header?: string;
+    /**
+     * Media type parameter name for MEDIA_TYPE versioning (default: 'version')
+     */
+    mediaTypeParam?: string;
+    /**
+     * Custom version extraction function
+     */
+    extractVersionFn?: (ctx: Context) => string | undefined;
+  };
 }
 
 export type Application = IMidwayExpressApplication;

packages/web-express/test/fixtures/versioning/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "express-versioning-test",
+  "version": "1.0.0",
+  "private": true
+}

packages/web-express/test/fixtures/versioning/src/config/config.default.ts

@@ -0,0 +1,11 @@
+'use strict';
+
+export const keys = 'test key';
+
+export const express = {
+  versioning: {
+    enabled: true,
+    type: 'URI',
+    prefix: 'v'
+  }
+}

packages/web-express/test/fixtures/versioning/src/config/config.unittest.ts

@@ -0,0 +1,4 @@
+exports.hello = {
+  b: 4,
+  c: 3,
+};

packages/web-express/test/fixtures/versioning/src/configuration.ts

@@ -0,0 +1,16 @@
+import { Configuration, Inject } from '@midwayjs/core';
+import * as express from '../../../../src';
+import { join } from 'path';
+
+@Configuration({
+  imports: [
+    express
+  ],
+  importConfigs: [
+    join(__dirname, './config'),
+  ]
+})
+export class AutoConfiguration {
+  @Inject()
+  framework: express.Framework;
+}