Midway 控制器与路由实战指南:从装饰器路由到请求参数与响应控制

原创2026-10-08 23:42:521,924 阅读
文章标签:后端微服务云原生

Midway 控制器与路由实战指南:从装饰器路由到请求参数与响应控制

Midway 的 Controller(控制器)是 MVC 架构中连接客户端与业务逻辑的核心枢纽:它解析用户的 HTTP 输入,调用业务逻辑,再把结果以合适的响应返回给客户端。本文基于 Midway 官方文档,结合 packages/core 与 packages/web 中的真实源码实现,系统讲解控制器的路由声明、HTTP 方法绑定、请求参数获取、参数类型转换以及响应输出控制,帮助你快速写出可运行、可维护的 Web 接口。

控制器:MVC 中的 C,也是路由的载体

在常见的 MVC 架构中,C 代表 Controller(控制器),它负责解析用户的输入,并在处理后返回相应的结果。一次最基本的「请求-响应」过程是:客户端通过 HTTP 协议把请求发送到服务端的 Controller,Controller 处理完毕后将结果响应给客户端。

常见的控制器应用场景包括:

  • 在 RESTful 接口中,控制器接收用户参数,从数据库取出内容返回给用户,或把用户的请求更新到数据库;
  • 在 HTML 页面请求中,控制器根据用户访问的不同 URL 渲染不同的模板,生成 HTML 返回给用户;
  • 在代理服务器中,控制器把用户的请求转发到其他服务器,再将其他服务器的处理结果返回给用户。

一般来说,控制器经常承担三类工作:对用户的请求参数进行校验与转换、调用复杂业务逻辑、在拿到业务结果后组装数据并返回。

在 Midway 中,控制器同时承载了路由能力。每个控制器可以提供多个路由,不同路由可以执行不同的操作。所有控制器文件一般放在 src/controller 目录下,框架通过 @Controller() 装饰器识别 Web 控制器类型的类——这一点可以从源码 packages/core/src/decorator/web/controller.ts 中得到印证:Controller 装饰器内部会调用 DecoratorManager.saveModule(CONTROLLER_KEY, target) 注册模块,并声明 Scope(ScopeEnum.Request)(请求作用域)与 Provide()(依赖注入),随后把 prefix 前缀与 routerOptions 作为元数据写入类定义。

路由声明:从零创建一个首页控制器

控制器文件通常位于 src/controller 目录,结构如下:

➜  my_midway_app tree
.
├── src
│   └── controller
│       └── home.ts
├── test
├── package.json
└── tsconfig.json

在 src/controller/home.ts 中创建首页控制器,并暴露一个默认的 / 路由:

// src/controller/home.ts

import { Controller, Get } from '@midwayjs/core';

@Controller('/')
export class HomeController {

  @Get('/')
  async home() {
    return "Hello Midwayjs!";
  }
}
  • @Controller 装饰器告诉框架这是一个 Web Controller 类型的类,其可选参数为路由前缀(分组),控制器下的所有路由都会携带此前缀;
  • @Get 装饰器告诉框架,被装饰的 home 方法将被暴露为 / 路由,可以通过 GET 请求访问。

整个方法返回一个字符串,浏览器端收到的是 text/plain 响应类型和 200 状态码。

[!TIP] 路由方法都是 async 异步方法。

从源码看,@Get 这类方法装饰器由 packages/core/src/decorator/web/requestMapping.ts 中的 createMappingDecorator 工厂函数生成:它把 HTTP 方法与路径合并为 RouterOption,再通过 RequestMapping 调用 MetadataManager.attachMetadata(WEB_ROUTER_KEY, routerMeta, target) 把路由元数据挂到类上,供框架启动时统一收集注册。

路由方法装饰器:绑定不同的 HTTP Method

除了 GET,Midway 还提供了更多路由方法装饰器:

// src/controller/home.ts

import { Controller, Get, Post } from '@midwayjs/core';

@Controller('/')
export class HomeController {

  @Get('/')
  async home() {
    return 'Hello Midwayjs!';
  }

  @Post('/update')
  async updateData() {
    return 'This is a post method'
  }
}

Midway 提供的路由方法装饰器包括 @Get、@Post、@Put()、@Del()、@Patch()、@Options()、@Head() 和 @All()。其中 @All 比较特殊,表示它可以接受所有类型的 HTTP 方法。

这些装饰器对应的底层方法类型定义在 packages/core/src/decorator/web/requestMapping.ts 的 RequestMethod 枚举中(get、post、put、delete、patch、all、options、head),并且每个方法装饰器还支持传入第二个参数 routerOptions,用于配置 routerName(路由别名)、middleware(路由级中间件)、summary/description(Swagger 摘要与描述)以及 ignoreGlobalPrefix(忽略全局前缀)。

同一个方法还可以绑定多个路由:

@Get('/')
@Get('/main')
async home() {
  return 'Hello Midwayjs!';
}

获取请求参数

接下来创建一个关于用户的 HTTP API。同样先创建 src/controller/user.ts 文件,这次我们加入路由前缀和更多请求类型。先定义一个用户类型,一般放在 src/interface.ts 文件中:

➜  my_midway_app tree
.
├── src
│   ├── controller
│   │   ├── user.ts
│   │   └── home.ts
│   └── interface.ts
├── test
├── package.json
└── tsconfig.json
// src/interface.ts
export interface User {
  id: number;
  name: string;
  age: number;
}

添加路由前缀与对应的控制器:

// src/controller/user.ts

import { Controller } from '@midwayjs/core';

@Controller('/api/user')
export class UserController {
  // xxxx
}

接下来,针对不同的请求类型调用不同的处理逻辑。除了请求类型,请求数据一般是动态的,会通过 HTTP 的不同位置传递,例如常见的 Query、Body 等。

参数装饰器约定

Midway 为动态值提供了通用装饰器。以 @Query 为例,它获取 URL 中的查询参数并赋值给函数入参。下面的例子中,id 从路由的 query 参数中获取:如果 URL 是 /?id=1,那么 id 的值就是 1,同时路由返回一个 User 类型的对象:

// src/controller/user.ts

import { Controller, Get, Query } from '@midwayjs/core';

@Controller('/api/user')
export class UserController {
  @Get('/')
  async getUser(@Query('id') id: string): Promise<User> {
    // xxxx
  }
}

@Query 装饰器有一个参数:可以传入指定的字符串 key 获取对应值并赋值给入参;如果不传参数,则默认返回整个 query 对象:

// URL = /?id=1
async getUser(@Query('id') id: string) // id = 1
async getUser(@Query() queryData) // {"id": "1"}

Midway 提供了更多从 Query、Body、Header 等位置取值的内置装饰器,它们开箱即用,并适配了不同的上层 Web 框架。下表是这些装饰器及对应的 Express / Koa(EggJS)框架原生取值方式:

装饰器 Express 对应方法 Koa/EggJS 对应方法
@Session(key?: string) req.session / req.session[key] ctx.session / ctx.session[key]
@Param(key?: string) req.params / req.params[key] ctx.params / ctx.params[key]
@Body(key?: string) req.body / req.body[key] ctx.request.body / ctx.request.body[key]
@Query(key?: string) req.query / req.query[key] ctx.query / ctx.query[key]
@Queries(key?: string) - - / ctx.queries[key]
@Headers(name?: string) req.headers / req.headers[name] ctx.headers / ctx.headers[name]

[!CAUTION] 注意: @Queries 装饰器与 @Query 不同。Queries 会把相同的 key 聚合在一起变成一个数组。当用户访问 /?name=a&name=B 时,@Queries 返回 {name: [a, B]},而 @Query 只返回 {name: B}。

从源码 packages/core/src/decorator/web/paramMapping.ts 可以看到,这些装饰器都由 createParamMapping(type) 工厂生成,其类型来自 RouteParamTypes 枚举(query、body、param、headers、session、file_stream、files_stream、request_path、request_ip、queries、fields、custom 等),通过 DecoratorManager.createCustomParamDecorator(WEB_ROUTER_PARAM_KEY, ...) 注册为参数装饰器;同时每个装饰器都支持第二个参数 pipes 管道,用于在赋值前后做数据变换。

Query:URL 查询参数

URL 中 ? 之后的部分是 Query String,常用于 GET 类型请求传参,例如:

GET /user?uid=1&sex=male

示例:通过装饰器获取

// src/controller/user.ts
import { Controller, Get, Query } from '@midwayjs/core';

@Controller('/user')
export class UserController {
  @Get('/')
  async getUser(@Query('uid') uid: string): Promise<User> {
    // xxxx
  }
}

示例:通过 API 操作获取

// src/controller/user.ts
import { Controller, Get, Inject } from '@midwayjs/core';
import { Context } from '@midwayjs/koa';

@Controller('/user')
export class UserController {

  @Inject()
  ctx: Context;

  @Get('/')
  async getUser(): Promise<User> {
    const query = this.ctx.query;
    // {
    //   uid: '1',
    // sex: 'male',
    //}
  }
}

[!CAUTION] 注意: EggJS 与其他框架不同,当 Query String 中的 key 重复时,ctx.query 只取该 key 第一次出现的值,后续出现的会被忽略。例如 GET /user?uid=1&uid=2 通过 ctx.query 得到的值是 { uid: '1' }。

Body:请求体参数

虽然可以通过 URL 传参,但仍有很多限制:

  • 浏览器中 URL 的长度有限制,参数过多时 URL 无法承载;
  • 服务器常把完整 URL 记录到日志文件,通过 URL 传递敏感数据不安全。

HTTP 请求报文中,header 之后有 body 部分,我们通常在 POST、PUT、DELETE 等方法中通过 body 传参。当请求带有 body 时,客户端(浏览器)会同时发送 Content-Type 告诉服务端 body 的格式。Web 开发中最常用的两种数据格式是 JSON 和 Form。

框架内置了 bodyParser 中间件,把这两种格式的请求解析成对象并挂载到 ctx.request.body 上。HTTP 协议不建议在 GET、HEAD 方法中通过 body 传参,因此这两种方法中无法按此方式获取内容。

示例:获取单个 body 字段

// src/controller/user.ts
// POST /user/ HTTP/1.1
// Host: localhost:3000
// Content-Type: application/json; charset=UTF-8
//
// {"uid": "1", "name": "harry"}
import { Controller, Post, Body } from '@midwayjs/core';

@Controller('/user')
export class UserController {
  @Post('/')
  async updateUser(@Body('uid') uid: string): Promise<User> {
    // id is equivalent to ctx.request.body.uid
  }
}

示例:获取整个 body

// src/controller/user.ts
// POST /user/ HTTP/1.1
// Host: localhost:3000
// Content-Type: application/json; charset=UTF-8
//
// {"uid": "1", "name": "harry"}
import { Controller, Post, Body } from '@midwayjs/core';

@Controller('/user')
export class UserController {
  @Post('/')
  async updateUser(@Body() user: User): Promise<User> {
    // user is equivalent to the entire body object of ctx.request.body
    // => output user
    // {
    //   uid: '1',
    //   name: 'harry',
    // }
  }
}

示例:通过 API 操作获取

// src/controller/user.ts
// POST /user/ HTTP/1.1
// Host: localhost:3000
// Content-Type: application/json; charset=UTF-8
//
// {"uid": "1", "name": "harry"}
import { Controller, Post, Inject } from '@midwayjs/core';
import { Context } from '@midwayjs/koa';

@Controller('/user')
export class UserController {

  @Inject()
  ctx: Context;

  @Post('/')
  async getUser(): Promise<User> {
    const body = this.ctx.request.body;
    // {
    // uid: '1',
    // name: 'harry',
    //}
  }
}

示例:同时获取 query 和 body 参数

装饰器可以组合使用:

@Post('/')
async updateUser(@Body() user: User, @Query('pageIdx') pageIdx: number): Promise<User> {
  // user gets it from body
  // pageIdx obtained from query
}

框架为 bodyParser 设置了一些默认参数,配置后具备以下特性:

  • 当请求 Content-Type 为 application/json、application/json-patch+json、application/vnd.api+json 和 csp-report 时,请求体按 json 格式解析,且 body 最大长度限制为 1mb;
  • 当请求 Content-Type 为 application/x-www-form-urlencoded 时,请求体按 form 格式解析,且 body 最大长度限制为 1mb;
  • 若解析成功,body 必须是 Object(可能是数组)。

[!CAUTION] 常见错误:把 ctx.request.body 与 ctx.body 混淆。ctx.body 其实是 ctx.response.body 的缩写。

Router Params:路径参数

如果路由以 :xxx 格式声明,就可以用 ctx.params 获取参数。

示例:通过装饰器获取

// src/controller/user.ts
// GET /user/1
import { Controller, Get, Param } from '@midwayjs/core';

@Controller('/user')
export class UserController {
  @Get('/:uid')
  async getUser(@Param('uid') uid: string): Promise<User> {
    // xxxx
  }
}

示例:通过 API 操作获取

// src/controller/user.ts
// GET /user/1
import { Controller, Get, Inject } from '@midwayjs/core';
import { Context } from '@midwayjs/koa';

@Controller('/user')
export class UserController {

  @Inject()
  ctx: Context;

  @Get('/:uid')
  async getUser(): Promise<User> {
    const params = this.ctx.params;
    // {
    // uid: '1',
    //}
  }
}

Header:请求头参数

除了从 URL 和请求体获取参数,很多参数是通过请求头传递的。框架提供了一些辅助属性和方法:

  • ctx.headers、ctx.header、ctx.request.headers、ctx.request.header:等价于获取整个 header 对象;
  • ctx.get(name)、ctx.request.get(name):获取请求头中某个字段的值,字段不存在时返回空字符串;
  • 推荐使用 ctx.get(name) 而不是 ctx.headers['name'],因为前者会自动处理大小写。

示例:通过装饰器获取

// src/controller/user.ts
// GET /user/1
import { Controller, Get, Headers } from '@midwayjs/core';

@Controller('/user')
export class UserController {
  @Get('/:uid')
  async getUser(@Headers('cache-control') cacheSetting: string): Promise<User> {
    // no-cache
    // ...
  }
}

示例:通过 API 操作获取

// src/controller/user.ts
// GET /user/1
import { Controller, Get, Inject } from '@midwayjs/core';
import { Context } from '@midwayjs/koa';

@Controller('/user')
export class UserController {

  @Inject()
  ctx: Context;

  @Get('/:uid')
  async getUser(): Promise<User> {
    const cacheSetting = this.ctx.get('cache-control');
    // no-cache
  }
}

Cookie

HTTP 请求是无状态的,但 Web 应用通常需要知道是谁发起的请求。为解决这个问题,HTTP 协议设计了特殊的请求头:Cookie。服务端可以通过响应头(set-cookie)把少量数据响应给客户端,浏览器按协议保存这些数据,并在下次请求同一服务时携带(浏览器也会遵循协议,只对符合 cookie 规则的网站携带对应的 cookie,以确保安全)。

ctx.cookies 让我们在 Controller 中方便、安全地设置和读取 Cookie:

import { Inject, Controller, Get, Provide } from '@midwayjs/core';
import { Context } from '@midwayjs/koa';

@Controller('/')
export class HomeController {
  @Inject()
  ctx: Context;

  @Get('/')
  async home() {
    // set cookie
    this.ctx.cookies.set('foo', 'bar', { encrypt: true });
    // get cookie
    this.ctx.cookies.get('foo', { encrypt: true });
  }
}

虽然 Cookie 在 HTTP 中只是一个 header,但可以以 foo=bar;foo1=bar1; 的格式设置多个键值对。

Cookie 在 Web 应用中常承担传递客户端身份信息的作用,因此有许多安全相关配置不可忽略。Cookie 文档 详细描述了 Cookie 的用法与安全配置项。

Session

通过 Cookie 可以为每个用户设置一个 Session,存储与用户身份相关的信息。这些信息会被加密后存储在 Cookie 中,用于跨请求维持用户身份。

框架内置了 Session 组件,提供 ctx.session 来访问或修改当前用户的 Session:

import { Inject, Controller, Get, Provide } from '@midwayjs/core';
import { Context } from '@midwayjs/koa';

@Controller('/')
export class HomeController {
  @Inject()
  ctx: Context;

  @Get('/')
  async home() {
    // Get the content on the Session
    const userId = this.ctx.session.userId;
    const posts = await this.ctx.service.post.fetch(userId);
    // Modify the value of the Session
    this.ctx.session.visited = ctx.session.visited ? (ctx.session.visited + 1) : 1;
    // ...
  }
}

Session 的使用非常直观:直接读取或修改即可。如需删除,直接赋值为 null:

ctx.session = null;

与 Cookie 一样,Session 也有很多安全选项和功能,使用前建议阅读 Session 文档。

上传文件

获取上传文件一般通过 @Files 装饰器,使用 multipart/form-data 协议头。上传功能由 upload 组件 提供,更多细节见 upload 文档。

其他参数

还有一些更常用的参数装饰器及对应方法:

装饰器 Express 对应方法 Koa/EggJS 对应方法
@RequestPath req.baseurl ctx.path
@RequestIP req.ip ctx.ip

示例:同时获取 body、路径和 ip 地址

@Post('/')
async updateUser (
  @Body('id') id: string,
  @RequestPath() p: string,
  @RequestIP() ip: string): Promise<User> {

}

自定义请求参数装饰器

可以使用 createRequestParamDecorator 快速创建自定义的请求参数装饰器。源码 packages/core/src/decorator/web/paramMapping.ts 显示,它内部会把用户传入的 transform 函数包装成 RouteParamTypes.CUSTOM 类型的参数装饰器,并且支持通过第二个参数传入 pipes 管道:

import { createRequestParamDecorator } from '@midwayjs/core';

// 实现装饰器
export const Token = () => {
  return createRequestParamDecorator(ctx => {
    return ctx.headers.token;
  });
};

// 使用装饰器
export class UserController {
  async invoke(@Token() token: string) {
    console.log(token);
  }
}

请求参数类型转换

对于简单类型,Midway 会自动把参数转换成用户声明的类型。

Number 类型:

@Get('/')
async getUser(@Query('id') id: number): Promise<User> {
  console.log(typeof id) // number
}

Boolean 类型:

  • 当值为 0、"0"、"false" 时转换为 false,其余返回 Boolean(value) 的值
@Get('/')
async getUser(@Query('id') id: boolean): Promise<User> {
  console.log(typeof id) // boolean
}

对于其他类型,框架不做处理。如果需要转换,请引入 validation 组件。

参数验证

参数验证功能由 validation 组件 提供,可以在参数装饰器上配合 pipes 管道或 DTO 类做声明式校验。

设置 HTTP 响应

设置返回值

大部分数据通过 body 发送给请求方。与请求中的 body 类似,响应中的 body 也需要匹配的 Content-Type 告诉客户端如何解析数据。

  • 作为 RESTful API 接口控制器,通常返回 Content-Type 为 application/json 的 body,内容是 JSON 字符串;
  • 作为 HTML 页面控制器,通常返回 Content-Type 为 text/html 的 body,内容是 HTML 代码片段。

在 Midway 中,可以直接使用 return 返回数据:

import { Controller, Get, HttpCode } from '@midwayjs/core';

@Controller('/')
export class HomeController {
  @Inject()
  ctx: Context;

  @Get('/')
  async home() {
    // 返回字符串
    return "Hello Midwayjs!";

    // 返回 json
    return {
      a: 1,
      b: 2
    };

    // 返回 html
    return '<html><h1>Hello</h1></html>';

    // 返回流
    return fs.createReadStream('./good.png');
  }
}

也可以使用 Koa 的原生 API:

import { Controller, Get, HttpCode } from '@midwayjs/core';

@Controller('/')
export class HomeController {

  @Get('/')
  async home() {
    // 返回字符串
    this.ctx.body = "Hello Midwayjs!";

    // 返回 JSON
    this.ctx.body = {
      a: 1,
      b: 2,
    };

    // 返回 html
    this.ctx.body = '<html><h1>Hello</h1></html>';

    // 返回流
    this.ctx.body = fs.createReadStream('./good.png');
  }
}

[!CAUTION] 注意:ctx.body 是 ctx.response.body 的缩写,不要与 ctx.request.body 混淆。

设置状态码

默认情况下,响应的状态码始终是 200。通过在 handler 层添加 @HttpCode 装饰器或通过 API,可以轻松改变这一行为。发送 4xx/5xx 错误时,可以使用异常处理抛出错误。

示例:使用装饰器

import { Controller, Get, HttpCode } from '@midwayjs/core';

@Controller('/')
export class HomeController {

  @Get('/')
  @HttpCode(201)
  async home() {
    return "Hello Midwayjs!";
  }
}

示例:API 操作

import { Controller, Get, Inject } from '@midwayjs/core';

@Controller('/')
export class HomeController {
  @Inject()
  ctx: Context;

  @Get('/')
  async home() {
    this.ctx.status = 201;
    // ...
  }
}

[!INFO] 响应流关闭(response.end 之后)后,状态码无法再修改。

设置响应头

Midway 提供了 @SetHeader 装饰器或 API 来简单地设置自定义响应头。

示例:使用装饰器

import { Controller, Get, SetHeader } from '@midwayjs/core';

@Controller('/')
export class HomeController {

  @Get('/')
  @SetHeader('x-bbb', '123')
  async home() {
    return "Hello Midwayjs!";
  }
}

当需要修改多个响应头时,可以直接传入对象:

import { Controller, Get, SetHeader } from '@midwayjs/core';

@Controller('/')
export class HomeController {

  @Get('/')
  @SetHeader({
    'x-bbb': '123',
    'x-ccc': '234'
  })
  async home() {
    return "Hello Midwayjs!";
  }
}

示例:API 操作

import { Controller, Get, Inject } from '@midwayjs/core';

@Controller('/')
export class HomeController {
  @Inject()
  ctx: Context;

  @Get('/')
  async home() {
    this.ctx.set('x-bbb', '123');
    // ...
  }
}

[!INFO] 响应流关闭(response.end 之后)后,响应头无法再修改。

重定向

如果只是简单地把一个路由重定向到另一个路由,可以使用 @Redirect 装饰器。它的参数是一个重定向 URL 和一个可选的状态码,默认重定向状态码是 302。此外,也可以通过 API 跳转。

示例:使用装饰器

import { Controller, Get, Redirect } from '@midwayjs/core';

@Controller('/')
export class LoginController {

  @Get('/login_check')
  async check() {
    // TODO
  }

  @Get('/login')
  @Redirect('/login_check')
  async login() {
    // TODO
  }

  @Get('/login_another')
  @Redirect('/login_check', 302)
  async loginAnother() {
    // TODO
  }
}

示例:API 操作

import { Controller, Get, Inject } from '@midwayjs/core';

@Controller('/')
export class HomeController {
  @Inject()
  ctx: Context;

  @Get('/')
  async home() {
    this.ctx.redirect('/login_check');
    // ...
  }
}

[!INFO] 响应流关闭(response.end 之后)后,重定向无法再修改。

响应类型

虽然浏览器会根据内容自动判断最佳响应内容,但我们经常会遇到需要手动设置的情况。Midway 提供了 @ContentType 装饰器设置响应类型,也可以通过 API 设置。

示例:使用装饰器

import { Controller, Get, ContentType } from '@midwayjs/core';

@Controller('/')
export class HomeController {

  @Get('/')
  @ContentType('html')
  async login() {
    return '<body>hello world</body>';
  }
}

示例:API 操作

import { Controller, Get, Inject } from '@midwayjs/core';

@Controller('/')
export class HomeController {
  @Inject()
  ctx: Context;

  @Get('/')
  async home() {
    this.ctx.type = 'html';
    // ...
  }
}

[!INFO] 响应流关闭(response.end 之后)后,响应类型无法再修改。

流式响应

如果想流式返回数据,可以在 Node.js 原生响应对象上使用 write 和 end 方法:

import { Controller, Get, Inject, sleep } from '@midwayjs/core';
import { Context } from '@midwayjs/koa';

@Controller('/')
export class HomeController {
   @Inject()
   ctx: Context;

   @Get('/')
   async home() {
     this.ctx.status = 200;
     this.ctx.set('Transfer-Encoding', 'chunked');
     for (let i = 0; i < 100; i++) {
       await sleep(100);
       this.ctx.res.write('abc'.repeat(100));
     }

     this.ctx.res.end();
   }
}

内部重定向 ctx.forward

从 v3.12.0 开始,框架提供了内部重定向 API ctx.forward(url),仅支持 koa/egg 类型。

与外部重定向的区别是:内部重定向不会修改浏览器的 URL,只在程序内部流转。

import { Controller, Get, Inject } from '@midwayjs/core';

@Controller('/')
export class HomeController {
   @Inject()
   ctx: Context;

   @Get('/')
   async home() {
     return this.ctx.forward('/api');
   }

   @Get('/api')
   async api() {
     return 'abc';
   }
}

内部重定向有一些规则:

  1. 重定向会保留原路由的所有参数,即整个 ctx 透明传递;
  2. 重定向只能发生在同一个 HTTP 方法内;
  3. 重定向不会再次执行 Web 中间件,guard 也不会执行,但 interceptor 和参数装饰器会执行。

全局路由前缀

全局路由前缀需要在 src/config/config.default 配置中设置。注意不同组件对应不同的配置关键字:

// src/config/config.default.ts
export default {
  koa: {
    globalPrefix: '/v1'
  }
};
// src/config/config.default.ts
export default {
  egg: {
    globalPrefix: '/v1'
  }
};
// src/config/config.default.ts
export default {
  express: {
    globalPrefix: '/v1'
  }
};

配置之后,所有路由会自动加上这个前缀。如果有特殊路由不需要加前缀,可以通过装饰器参数忽略。

示例:Controller 级忽略

// 该 Controller 下所有路由都会忽略全局前缀
@Controller('/api', {ignoreGlobalPrefix: true})
export class HomeController {
  // ...
}

示例:路由级忽略

@Controller('/')
export class HomeController {
  // 该路由不会被忽略
  @Get('/', {})
  async homeSet() {
  }

  // 该路由忽略全局前缀
  @Get('/bbc', {ignoreGlobalPrefix: true})
  async homeSet2() {
  }
}

从源码看,ignoreGlobalPrefix 同时存在于 requestMapping.ts 的 RouterOption 接口和 controller.ts 的 ControllerOption.routerOptions 中。而真正决定路由是否带前缀的逻辑集中在 packages/core/src/service/webRouterService.ts:当全局前缀存在时,框架会为每条路由计算实际路径;若路由自身显式声明了 ignoreGlobalPrefix(源码通过 __ignoreGlobalPrefixConfigured 非枚举标记区分「显式配置」与「默认 false」),则前缀会被跳过。

路由优先级

Midway 已经统一对路由进行了排序,通配符路由会自动降低优先级并在最后加载。规则如下:

  1. 绝对路径规则优先级最高,例如 /AB/cb/e;
  2. 星号只能出现在最后,且后面必须跟 /,例如 /AB/cb/**;
  3. 如果绝对路径和通配配置都能匹配某个路径,绝对规则优先级高。例如 /abc/* 与 /abc/d 同时存在,请求 /abc/d 时匹配绝对路由 /abc/d;
  4. 如果多个通配都能匹配一个路径,按最长规则匹配。例如 /AB/** 与 /AB/cd/** 同时存在,请求 /AB/cd/f 时命中 /AB/cd/**;
  5. 如果 / 和 /* 都能匹配 /,/ 的优先级高于 /*;
  6. 如果权重相同,例如 /:page/page 与 /page/:page,则按注册顺序处理。

这一规则与 Serverless 下函数的路由规则保持一致。简单理解为:「明确的路由优先级最高,长的路由优先级最高,通配分发优先级最低」。

例如:

@Controller('/api')
export class APIController {
  @Get('/invoke/*')
  async invokeAll() {
  }

  @Get('/invoke/abc')
  async invokeABC() {
  }
}

这种情况下,/invoke/abc 会被先注册以保证更高的优先级。不同 Controller 之间按长度排序,/ 根 Controller 最后加载。

从源码 webRouterService.ts 的 sortRouter 与路由收集逻辑可以看到,框架在注册路由时会计算每条路由的 priority:根路径 / 的优先级被设置为 -999(保证最后匹配),普通路由优先级为 0;通配路由则按规则降权。这与文档描述的路由优先级规则完全一致。

小结

通过本文,你已经掌握了 Midway 控制器的完整使用链路:

  • 路由声明:@Controller(prefix) 声明控制器前缀,@Get/@Post 等方法装饰器绑定 HTTP 方法,支持多路由绑定与 routerOptions 扩展(中间件、路由别名、忽略全局前缀等);
  • 参数获取:@Query、@Body、@Param、@Headers、@Session、@Queries、@RequestPath、@RequestIP、@Files 等内置装饰器开箱即用,也可通过 createRequestParamDecorator 自定义,底层由 paramMapping.ts 统一实现,并兼容 Express、Koa、EggJS 三种上层框架的取值方式;
  • 响应控制:return 或 ctx.body 返回数据,@HttpCode 设置状态码,@SetHeader 设置响应头,@Redirect 重定向,@ContentType 设置响应类型,ctx.res.write/end 实现流式响应,ctx.forward 实现内部重定向;
  • 全局配置:通过 koa/egg/express.globalPrefix 配置全局路由前缀,配合 ignoreGlobalPrefix 按控制器或路由粒度豁免;路由优先级遵循「明确优先、最长优先、通配最后」的排序规则,由 webRouterService.ts 统一计算。

在此基础上,可以进一步阅读 Midway 的 异常处理、参数验证 与 上传组件 文档,构建更完整的 Web 应用能力。

登录后查看全文
midway