Midway Hooks 文件路由实战：用纯函数与文件目录快速生成 API 接口-平芜编程栈

后端
微服务
云原生

【免费下载链接】midway

🍔 A Node.js Serverless Framework for front-end/full-stack developers. Build the application for next decade. Works on AWS, Alibaba Cloud, Tencent Cloud and traditional VM/Container. Super easy integrate with React and Vue. 🌈

项目地址：https://gitcode.com/gh_mirrors/mi/midway

点击查看免费下载

本文围绕 Midway Hooks（@midwayjs/hooks）的Easy Mode（简易模式）与文件系统路由（Filesystem Routing）展开，讲解如何通过midway.config.ts中的routes配置开启文件路由系统，让目录结构、文件命名直接决定 HTTP 接口路径，从而在前端/全栈项目中用纯函数快速产出GET/POST接口。读完本文，你将掌握简易模式下的接口编写、Api()与路径参数（Params<T>）的配合使用，以及 index 路由、嵌套路由、通配路由、动态路径参数的完整规则，并能结合仓库内的 React 全栈示例进行验证。

什么是简易模式（Simple mode）

在 Midway Hooks 中，简易模式允许**只用普通异步函数（pure functions）**来快速创建 HTTP 接口，无需编写@Controller、@Get等装饰器。函数即接口，导出即路由。

使用简易模式需要满足两个前提：

必须开启文件路由系统：需要在midway.config.js（或midway.config.ts）中配置routes字段；
接口方法受限：由纯函数自动生成的路由只支持GET与POST两种 HTTP 方法；在全栈应用中，这种自动生成的方式不支持传递Query / Params / Header参数。

需要注意：即便处于简易模式，你仍然可以使用Api()来定义路由，并且支持手动指定路径；此时basePath会自动拼接到生成的路径前缀中（详见下文"使用 Api() 创建路由"）。

简易模式接口编写：GET 与 POST

GET 请求

一个最简单的 GET 接口，只需要导出一个异步函数，并通过useContext()获取 HTTP 请求上下文：

import { useContext } from '@midwayjs/hooks'; export async function getPath() { // 通过 Hooks 获取 HTTP 请求上下文 const ctx = useContext(); return ctx.path; }

集成调用（全栈项目，零 API）：直接像调用普通函数一样导入并调用：

import { getPath } from './api/lambda'; const path = await getPath(); console.log(path); // /api/getPath

手动调用：使用fetcher按生成的路径发起请求：

fetcher .get('/api/getPath') .then((res) => { console.log(res.data); // /api/getPath });

POST 请求

POST 接口同样是一个普通异步函数，函数参数即接口入参：

import { useContext } from '@midwayjs/hooks'; export async function post ( name: string ) { const ctx = useContext(); return { message: 'Hello ${name}!', method: ctx.method }; }

集成调用：

import { post } from './api/lambda'; const response = await post('Midway'); console.log(response.data); // { message: 'Hello Midway!', method: 'POST'}

手动调用：手动调用时，函数入参需要放在 HTTP Body 的args数组中传递：

fetch('/api/post', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ args: ['Midway'] }), }).then((res) => { console.log(res.data); // { message: 'Hello Midway!', method: 'POST'} });

使用 Api() 创建路由

在简易模式下，你依然可以使用Api()来创建路由，但需要注意路径指定方式的约束：

无效写法：Api(Get('/specify_path'))—— 简易模式下不支持手动指定路径；
有效写法：不传路径，由文件系统自动生成。

下面是一个同时导出两条路由的合法示例（getPath为具名导出，default为默认导出，二者路由均由文件系统自动生成）：

import { Api, Get } from '@midwayjs/hooks'; import { useContext } from '@midwayjs/hooks'; export async function getPath() { // 通过 Hooks 获取 HTTP 请求上下文 const ctx = useContext(); return ctx.path; } export default Api(Get(), async () => { return 'Hello Midway!'; });

开启文件系统路由：midway.config.ts 配置

在midway.config.js（或midway.config.ts）中开启routes配置，即可同时启用文件路由系统与简易模式：

import { defineConfig } from '@midwayjs/hooks'; export default defineConfig({ source: './src/apis', routes: [ { baseDir: 'lambda', basePath: '/api', }, ], });

字段说明：

字段	说明	默认值 / 取值范围
`source`	后端代码目录	默认`./src/apis`，也可自定义为`./src/functions`等目录
`routes`	路由配置，默认是一个数组	数组可包含多个路由组
`routes[].baseDir`	函数目录，该目录下任意`.ts`文件中导出的异步函数都会自动生成为 Api 接口	相对`source`的目录名，如`lambda`
`routes[].basePath`	生成的 Api 地址前缀	如`/api`

仓库内的真实示例 site/example/function/midway.config.ts 与上述配置完全一致；对应的后端接口目录为src/apis/lambda，其下index.ts中默认导出（GET）与具名导出post（POST）分别被生成为接口，见 site/example/function/src/apis/lambda/index.ts。

路由生成规则

开启文件路由后，目录结构与文件命名将直接决定最终的路由路径。以下是全部规则。

Index 路由：index.ts 作为根路由

目录下的index.ts文件会作为该目录的根路由：

/lambda/index.ts→/
/lambda/about/index.ts→/about

嵌套路由：文件与目录逐级映射

嵌套文件会生成嵌套路由：

/lambda/about.ts→/about
/lambda/blog/index.ts→/blog
/lambda/about/contact.ts→/about/contact

导出方式与路由的对应关系

文件内默认导出的函数生成到根路径，具名导出的函数则将函数名拼接到路径上。

以/lambda/about.ts为例：

export default () => {}→/about
export function contact ()→/about/contact

提示：结合前文的示例，/lambda/index.ts中默认导出对应根路径，具名导出post则对应/api/post，与示例测试 site/example/function/src/apis/lambda/index.test.ts 中断言的GET/POST行为一致。

通配路由（Wildcard routing）

如果需要生成通配路由（例如/api/*，用于匹配/api、/api/about、/api/about/a/B/c等），文件名使用[...file]格式。

📢 建议通配路由中只使用export default导出函数，以避免不必要的路由冲突。

示例：

/lambda/[...index].ts→/api/*
/lambda/[...user].ts→/api/user/*
/lambda/about/[...contact].ts→/api/about/contact/*

路径参数（Path parameters）

如果需要生成动态路径参数，文件名使用[file]格式：

/lambda/[name]/project.ts→/api/about/:name/project
- 请求/about/midwayjs/project→{ name: 'midwayjs' }
/lambda/[type]/[page].ts→/api/about/:type/:page
- 请求/blog/1→{ type: 'blog', page: '1' }
- 请求/articles/3→{ type: 'articles', page: '3' }

使用路径参数时只能使用Api()开发后端接口，并使用Params<T>标记类型。

以/lambda/[name]/project.ts为例：

// lambda/[name]/project.ts import { Api, Get, Params, useContext } from '@midwayjs/hooks'; export default Api ( Get(), Params<{ name: string }>(), async () => { const ctx = useContext(); return { name: ctx.params.name }; } );

集成调用：全栈项目中通过params传参：

import getProject from './api/[name]/project'; const response = await getProject({ params: { name: 'midwayjs'} }); console.log(response); // { name: 'midwayjs'}

手动调用：

fetch('/api/about/midwayjs/project') .then((res) => res.json()) .then((res) => console.log(res)); // { name: 'midwayjs'}

结合仓库示例验证：一个完整的 React 全栈应用

仓库中的 site/example/function 是一个名为midway-hooks-react的完整示例，其依赖包括@midwayjs/hooks、@midwayjs/koa、react与vite（见 site/example/function/package.json）。它的目录结构与本文档描述的规则一一对应：

. ├── midway.config.ts // 配置目录与路由 ├── src │ ├── apis // 后端目录（source） │ │ ├── configuration.ts // Hooks 配置 │ │ └── lambda // Api 目录（对应 routes[].baseDir） │ │ ├── index.test.ts // Api 单元测试 │ │ └── index.ts // Api 接口文件 │ ├── App.tsx // React 前端 │ └── main.tsx └── vite.config.ts

后端接口文件 site/example/function/src/apis/lambda/index.ts 中，默认导出（GET/api）与具名导出post（POST/api/post）同时存在；
前端 site/example/function/src/App.tsx 直接import hello, { post } from './apis/lambda'并像调用普通函数一样调用hello()、post(message)，正是"零 API 集成调用"的典型用法；
单元测试 site/example/function/src/apis/lambda/index.test.ts 通过@midwayjs/hooks-testing-library的createApp()创建应用，用app.runFunction与app.request两种方式验证了默认导出返回{ message: 'Hello World', method: 'GET' }、post返回{ method: 'POST', name: 'Jake' }的行为；
Hooks 配置 site/example/function/src/apis/configuration.ts 通过createConfiguration导入hooks并挂载koa-bodyparser中间件，保证 POST body 可以解析；
Vite 侧通过 site/example/function/vite.config.ts 接入@midwayjs/vite-plugin-hooks插件，实现开发期前后端一体化。

运行该示例：开发模式执行npm run dev，构建执行npm run build（先后执行build:client与build:server），生产模式执行node bootstrap.js。

与 Api() 完整 API 的衔接

本主题聚焦于文件路由与简易模式；当需要处理Query<T>、Headers<T>、HttpCode、SetHeader、Redirect、ContentType等更完整的能力时，可继续阅读同目录下的 API 开发文档，其中详细列出了All / Get / Post / Put / Delete / Patch / Head / Options全部 HTTP 触发器及其用法，与本主题中的Api(Get(), Params<...>())写法一脉相承。

小结与注意事项

简易模式的本质是"函数即接口"：source指定后端目录，routes[].baseDir指定接口目录，basePath指定统一前缀；
自动生成的路由只支持GET/POST，且不自动支持Query / Params / Header传参；需要动态路径参数时，必须使用Api()+Params<T>；
index.ts映射根路径，嵌套目录/文件逐级映射路径，具名导出拼接函数名，[name]声明路径参数，[...name]声明通配路由；
通配路由中建议只使用默认导出，避免路由冲突；
文件路由的最终路径由basePath + 文件系统映射路径拼接而成，手动调用时需按完整路径（含basePath前缀）发起请求。