# Routes

在任何 URL 上发送到 Strapi 的请求都由 Routes 处理。默认情况下,Strapi 为所有 content-types 生成 Routes (参见 REST API 文档). Routes 可以被 添加 或配置:

一旦路由存在,请求路由就会执行一些由控制器处理的代码 (参见 controllers 文档).

# 实现

实现新路由包括在 ./src/api/[apiName]/routes 文件夹内的路由器文件中定义它。 (参见 project structure).

有 2 种不同的路由器文件结构,具体取决于用例:

# 配置核心路由器

核心路由器 (即 find, findOne, create, update, delete) 对应于 Strapi 在创建新的 内容类型 时自动创建的 默认路由器

Strapi提供了一个 createCoreRouter 工厂功能,可以自动生成核心路由器,并允许:

核心路由器文件是一个 JavaScript 文件,它使用以下参数导出对 createCoreRouter 的调用结果:

参数 描述 类型
prefix 允许传入自定义前缀以添加到此型号的所有路由器 (例 /test) String
only 仅加载的核心路由

不在此数组中的任何内容都将被忽略。
Array
except 不应加载的核心路由

这个功能与 only 参数相反。
Array
config 对于路由要处理的配置 policies, middlewarespublic availability Object


通用实现示例:

这只允许从核心 find controller/restaurants 路径上发出 GET 请求,而无需身份验证。

# 创建自定义路由

创建自定义路由 consists in creating a file that exports an array of objects, each object being a route with the following parameters:

参数 描述 类型
method 与路由关联的方法 (即 GET, POST, PUT, DELETE or PATCH) String
path 到达路由,从根据前缀开始 (例 /articles) String
handler 到达路由时要执行的函数。
应遵循以下语法: <controllerName>.<actionName>
String
config

Optional
对于路由要处理的配置 policies, middlewarespublic availability

Object

可以使用参数和正则表达式创建动态路由。这些参数将在 ctx.params 对象中公开。有关更多详细信息,请参阅 PathToRegex (opens new window) 文档.

✋ CAUTION

路由文件按字母顺序加载。要在核心路由之前加载自定义路由,请确保适当地命名自定义路由(例 01-custom-routes.js02-core-routes.js)。

使用 URL 参数和路由正则表达式的自定义路由器示例

在以下示例中,自定义路由文件名以 01- 为前缀,以确保在核心路由之前到达路由。

// path: ./src/api/restaurant/routes/01-custom-restaurant.js

module.exports = {
  routes: [
    { // Path defined with an URL parameter
      method: 'POST',
      path: '/restaurants/:id/review', 
      handler: 'restaurant.review',
    },
    { // Path defined with a regular expression
      method: 'GET',
      path: '/restaurants/:category([a-z]+)', // Only match when the URL parameter is composed of lowercase letters
      handler: 'restaurant.findByCategory',
    }
  ]
}
// path: ./src/api/restaurant/routes/custom-restaurant.ts

export default {
  routes: [
    { // Path defined with a URL parameter
      method: 'GET',
      path: '/restaurants/:category/:id',
      handler: 'Restaurant.findOneByCategory',
    },
    { // Path defined with a regular expression
      method: 'GET',
      path: '/restaurants/:region(\\d{2}|\\d{3})/:id', // Only match when the first parameter contains 2 or 3 digits.
      handler: 'Restaurant.findOneByRegion',
    }
  ]
}

# 配置

core routerscustom routers 具有相同的配置选项。路由配置在一个 config 对象中定义,该对象可用于处理 policies and middlewares or to make the route public.

# 策略

Policies 可以添加到路由配置中:

  • 通过指向在 ./src/policies 中注册的策略,无论是否传递自定义配置
  • 或者直接声明策略实现,作为一个函数,它将 policyContext 用于扩展 Koa's context (opens new window) (ctx) 和 strapi 实例作为参数 (参见 policies 文档)

# 中间件

Middlewares 可以添加到路由配置中:

  • 通过指向在 ./src/middlewares 中注册的中间件,无论是否传递自定义配置
  • 或者通过直接声明中间件实现,作为将 Koa's context (opens new window) (ctx) 和 strapi 实例作为参数的函数:

# 公共路由

默认情况下,路由受 Strapi 的身份验证系统保护,该系统基于 API tokens 或使用 Users & Permissions plugin.

在某些情况下,公开提供路由并控制正常 Strapi 身份验证系统之外的访问可能很有用。这可以通过将路由的 auth 配置参数设置为 false 来实现: