Medusa 自定义 API 路由(Custom API Routes)实战指南:文件系统路由、路径参数与中间件体系

原创2026-09-09 22:43:321,920 阅读
文章标签:电商后端企业应用前端流程编排认证鉴权插件系统

Medusa 自定义 API 路由(Custom API Routes)实战指南:文件系统路由、路径参数与中间件体系

Medusa 的 API 路由(API Route)是一个 REST API 端点,它采用"文件即路由"的约定式设计:只要在应用的 src/api 目录下按约定命名与组织文件,就能自动注册出完整的 HTTP 接口,无需手动挂载 Express 路由。本文以 loyalty 插件 的真实实现为佐证,系统讲解路由文件的创建方式、支持的全部 HTTP 方法、路径参数、依赖注入容器(req.scope)以及 middlewares.ts 中间件体系的完整配置方法,并深入 framework 路由加载器 源码,揭示文件系统路由在启动时是如何被扫描、解析与注册的。读完本文,你可以独立在 Medusa 应用中编写出可用的自定义管理端、商城端乃至认证端 REST 接口。

文件系统路由:从 route.ts 文件到 REST 端点

Medusa 应用中的 API 路由创建在 /src/api 目录下的 TypeScript 或 JavaScript 文件中,文件名必须是 route.ts 或 route.js。文件在目录中的相对位置,决定了该端点对外暴露的 URL 路径;文件中导出的函数名,则决定了它响应的 HTTP 方法。

例如,要创建一个 GET /store/hello-world 端点,只需创建文件 src/api/store/hello-world/route.ts,内容如下:

import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http";

export async function GET(req: MedusaRequest, res: MedusaResponse) {
  res.json({
    message: "Hello world!",
  });
}

启动应用后,向 /store/hello-world 发起 GET 请求即可得到 { "message": "Hello world!" } 的 JSON 响应。

从源码角度确认这一机制:框架的 RoutesLoader.scanDir(routes-loader.ts)会递归扫描源目录,只挑选文件名恰好为 route、扩展名为 .js 或 .ts 的文件,并把它们的相对路径转换为 URL 匹配模式,随后注册进路由表。src/api 目录中以下划线 _ 开头的目录/文件段会被跳过(routeFilePathSegment.some((segment) => segment.startsWith("_"))),可用于放置不希望暴露为路由的辅助模块。

支持的 HTTP 方法与多方法处理

基于文件的约定式路由支持以下 HTTP 方法:

  • GET
  • POST
  • PUT
  • PATCH
  • DELETE
  • OPTIONS
  • HEAD

你可以在同一个 route.ts 文件中,通过导出与 HTTP 方法同名的函数,为同一路径定义多个方法的处理器:

import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http";

export async function GET(req: MedusaRequest, res: MedusaResponse) {
  // Handle GET requests
}

export async function POST(req: MedusaRequest, res: MedusaResponse) {
  // Handle POST requests
}

export async function PUT(req: MedusaRequest, res: MedusaResponse) {
  // Handle PUT requests
}

路由加载器在解析文件导出时,只把名字属于 HTTP_METHODS 列表且类型为函数的导出当作路由处理器,其余导出(如配置标志)会被忽略(routes-loader.ts)。方法集合定义在 types.ts 的 HTTP_METHODS 常量中,与上述 7 个方法一一对应。

路径参数:用 [param] 目录捕获动态片段

要创建接收路径参数(path parameter)的路由,在路由路径中创建一个名字形如 [param] 的目录即可。例如定义一个接收 productId 参数的路由,创建文件 /api/products/[productId]/route.ts:

import type {
  MedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"

export async function GET(req: MedusaRequest, res: MedusaResponse) {
  const { productId } = req.params;

  res.json({
    message: `You're looking for product ${productId}`
  })
}

路径参数会出现在 req.params 对象中,可直接解构使用。

若要接收多个路径参数,在文件路径中创建多个 [param] 目录即可。例如同时接收 productId 与 variantId,创建文件 /api/products/[productId]/variants/[variantId]/route.ts,请求 /products/prod_123/variants/var_456 时 req.params 即为 { productId: "prod_123", variantId: "var_456" }。

底层实现上,RoutesLoader.createRoutePath(routes-loader.ts)会通过正则 PARAM_SEGMENT_MATCHER = /\[(\w+)\]/ 把 [xxx] 目录名转换为 Express 的 :xxx 参数语法,并在同一路径中发现重复参数名时直接抛出错误("Duplicate parameters found in route ..."),避免歧义。

loyalty 插件中就有一个典型的双用途参数路由:store/gift-cards/[idOrCode]/route.ts 用 [idOrCode] 目录同时承接礼品卡 ID 或兑换码:

export const GET = async (
  req: AuthenticatedMedusaRequest<StoreGetGiftCardParams>,
  res: MedusaResponse
) => {
  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY);
  const { idOrCode: code } = req.params;
  // ...通过 query.graph 按 code 查询礼品卡,未命中时抛出 NOT_FOUND
  res.json({ gift_card });
};

在路由中使用容器(req.scope)

Medusa 的依赖注入容器(container)在路由处理器中通过 req.scope 暴露。可以用它解析模块的主服务(module service)以及其他已注册的资源,完成业务逻辑:

import type {
  MedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"

export const GET = async (
  req: MedusaRequest,
  res: MedusaResponse
) => {
  const productModuleService = req.scope.resolve("product")

  const [, count] = await productModuleService.listAndCount()

  res.json({
    count,
  })
}

上面的示例解析了 product 模块的主服务并调用 listAndCount() 统计商品总数。在实践中,loyalty 插件更常解析框架注册的通用查询服务(注册键 ContainerRegistrationKeys.QUERY)来执行 GraphQL 风格的实体查询,例如 store/store-credit-accounts/claim/route.ts 中的 POST 处理器:它先解析 QUERY 服务与认证上下文 req.auth_context.actor_id,运行 claimStoreCreditAccountWorkflow.run(...) 工作流完成领券业务,再通过 graph.graph({ entity: "store_credit_account", ... }) 查询结果并返回。

除了服务,你还可以在处理器中访问:

  • req.auth_context:当前请求的认证信息(actor_id 等),适用于经过认证的路由;
  • req.queryConfig:由查询校验中间件解析出的字段选择配置;
  • req.body:请求体内容。

中间件体系:middlewares.ts 与 defineMiddlewares

可以为路由挂载中间件:在 /api/middlewares.ts 中导出一个配置对象,声明将哪些中间件应用到哪些路由上。

例如,要为 /store/custom 路由应用一个自定义中间件函数,在 /api/middlewares.ts 中写入:

import { defineMiddlewares } from "@medusajs/framework/http"
import type {
  MedusaRequest,
  MedusaResponse,
  MedusaNextFunction,
} from "@medusajs/framework/http";

async function logger(
  req: MedusaRequest,
  res: MedusaResponse,
  next: MedusaNextFunction
) {
  console.log("Request received");
  next();
}

export default defineMiddlewares({
  routes: [
    {
      matcher: "/store/custom",
      middlewares: [logger],
    },
  ],
})

其中:

  • matcher:可以是字符串或正则表达式,用于匹配要应用中间件的路由;
  • middlewares:接收一个中间件函数数组。

从源码看,defineMiddlewares 是 @medusajs/framework/http 提供的辅助函数(define-middlewares.ts),它规范化配置结构并返回 MiddlewaresConfig。真正的加载工作由 MiddlewareFileLoader(middleware-file-loader.ts)完成——它专门扫描名为 middlewares(MIDDLEWARE_FILE_NAME)的文件,读取其 default 导出配置。

中间件路由配置的完整字段

根据 types.ts 中 MiddlewareRoute 与 MiddlewaresConfig 的类型定义,每条中间件路由配置支持以下字段:

字段 类型 说明
matcher string | RegExp 匹配要应用中间件的路由路径
methods MiddlewareVerb[] 限定该配置仅对指定 HTTP 方法生效(USE / ALL 或 7 个标准方法);旧版字段 method 已标记为废弃
middlewares 中间件函数数组 依次应用到匹配路由的中间件
bodyParser false | { sizeLimit?, preserveRawBody? } 覆盖该路由的 body parser 配置,false 表示关闭解析,也可自定义大小限制
additionalDataValidator ZodRawShape 以 Zod shape 声明额外的请求数据校验规则,与既有路由校验器合并
policies { resource, operation }[] 声明该路由所需的 RBAC 资源与操作权限

methods 字段让同一 matcher 可以对 GET 与 POST 应用不同的中间件组合。loyalty 插件的 store/gift-cards/middlewares.ts 展示了这一实践:

export const storeGiftCardsMiddlewares: MiddlewareRoute[] = [
  {
    method: ["GET"],
    matcher: "/store/gift-cards/:code",
    middlewares: [
      validateAndTransformQuery(
        StoreGetGiftCardParams,
        retrieveGiftCardTransformQueryConfig
      ),
    ],
  },
];

这里通过 method: ["GET"] 限定方法,用 validateAndTransformQuery 对查询参数进行 Zod 校验与字段转换——注意 matcher 中直接使用了 Express 风格的 :code 参数写法,与文件系统路由中 [idOrCode] 目录生成的 :idOrCode 是同一套参数机制。

统一组织多个路由的中间件

插件或应用通常为每个子目录维护一份 middlewares.ts(如 admin/gift-cards/middlewares.ts、store/carts/middlewares.ts),再在顶层 api/middlewares.ts 统一汇总:

import { defineMiddlewares } from "@medusajs/framework";
import { adminGiftCardMiddlewares } from "./admin/gift-cards/middlewares";
import { storeGiftCardsMiddlewares } from "./store/gift-cards/middlewares";
// ...

export default defineMiddlewares({
  routes: [
    ...adminGiftCardMiddlewares,
    ...storeGiftCardsMiddlewares,
    // ...
  ],
});

这种"局部声明、顶层汇总"的组织方式,使每个业务子模块的中间件职责内聚、便于复用与测试。

自定义全局错误处理

defineMiddlewares 的配置对象还支持顶层 errorHandler 字段(值为 false 或自定义错误处理函数),用于覆盖全局错误处理行为。未提供时,框架使用内置的 error-handler 中间件 统一格式化异常响应。

深入原理:路由是如何被扫描与注册的

框架对 src/api 目录的处理分为两个阶段,均由 express-loader.ts 在应用启动时驱动:

  1. 路由加载(RoutesLoader):扫描 route.ts 文件,生成 RouteDescriptor 并注册。每个描述符包含 matcher(URL 模式)、method(HTTP 方法)、handler(处理函数)以及一组标志位(types.ts):

    • optedOutOfAuth:是否跳过认证;
    • shouldAppendAdminCors / shouldAppendStoreCors / shouldAppendAuthCors:是否为对应前缀的路由附加 CORS 策略。
  2. 中间件加载(MiddlewareFileLoader):扫描 middlewares.ts,解析出中间件描述符、body parser 配置路由、附加数据校验路由与全局错误处理函数,再统一装配到 Express 应用上。

其中路由类型(admin / store / auth)是根据路径前缀自动判定的:RoutesLoader 用 ADMIN_ROUTE_MATCH = /(\/admin$|\/admin\/)/、STORE_ROUTE_MATCH = /(\/store$|\/store\/)/、AUTH_ROUTE_MATCH = /(\/auth$|\/auth\/)/ 三个正则(routes-loader.ts)识别前缀,并据此附加对应的 CORS 策略与认证行为。

认证与 CORS 的控制标志

默认情况下,所有路由都会被框架的认证机制保护(shouldAuthenticate 默认为 true)并附加 CORS 策略。如果某个路由需要跳过认证(例如公开的 Webhook 回调端点),可以在 route.ts 中显式导出标志来覆盖默认行为:

export const AUTHENTICATE = false; // 跳过该路由的认证
export const CORS = false;         // 跳过该路由的 CORS 策略

路由加载器通过 AUTHTHENTICATION_FLAG = "AUTHENTICATE" 与 CORS_FLAG = "CORS" 检查文件导出(routes-loader.ts),并将结果写入描述符的 optedOutOfAuth 与 shouldAppend*Cors 标志。在 中间件夹具 与 routes-loader 相关测试 中,你可以看到这些标志与中间件装配行为的完整验证用例。

实践要点小结

  • 每个路由文件必须命名为 route.ts / route.js,位于应用 src/api 目录下;目录层级即 URL 路径,[name] 目录即路径参数。
  • 一个文件可同时导出多个 HTTP 方法处理器;非方法名的导出(AUTHENTICATE、CORS 标志)用于控制认证与 CORS 行为。
  • 业务逻辑通过 req.scope.resolve(...) 获取模块服务与容器资源,工作流可通过 workflow.run({ input, container: req.scope }) 编排复杂业务。
  • 中间件集中在 src/api/middlewares.ts 中声明,使用 defineMiddlewares 组织 matcher + methods + middlewares(以及 bodyParser、additionalDataValidator、policies)的配置项;loyalty 插件提供了多子模块中间件文件汇总合并的成熟范式。
  • 框架的路由与中间件加载实现在 routes-loader.ts、middleware-file-loader.ts 与 express-loader.ts 中,配合 tests 下的测试用例,可作为你理解与调试自定义路由行为的权威参考。
登录后查看全文
medusa