Midway 控制器与路由实战指南:从装饰器路由到请求参数与响应控制
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';
}
}
内部重定向有一些规则:
- 重定向会保留原路由的所有参数,即整个 ctx 透明传递;
- 重定向只能发生在同一个 HTTP 方法内;
- 重定向不会再次执行 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 已经统一对路由进行了排序,通配符路由会自动降低优先级并在最后加载。规则如下:
- 绝对路径规则优先级最高,例如
/AB/cb/e; - 星号只能出现在最后,且后面必须跟
/,例如/AB/cb/**; - 如果绝对路径和通配配置都能匹配某个路径,绝对规则优先级高。例如
/abc/*与/abc/d同时存在,请求/abc/d时匹配绝对路由/abc/d; - 如果多个通配都能匹配一个路径,按最长规则匹配。例如
/AB/**与/AB/cd/**同时存在,请求/AB/cd/f时命中/AB/cd/**; - 如果
/和/*都能匹配/,/的优先级高于/*; - 如果权重相同,例如
/: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 统一计算。