Skip to main content

路由

¥Routes

通过任何 URL 发送到 Strapi 的请求均由路由处理。默认情况下，Strapi 为所有内容类型生成路由（参见 REST API 文档）。路由可以是 added 并配置：

¥Requests sent to Strapi on any URL are handled by routes. By default, Strapi generates routes for all the content-types (see REST API documentation). Routes can be added and configured:

  • 使用 policies，这是一种阻止访问路由的方法，

    ¥with policies, which are a way to block access to a route,

  • 以及 middlewares，这是一种控制和更改请求流和请求本身的方法。

    ¥and with middlewares, which are a way to control and change the request flow and the request itself.

一旦存在一条路由，到达该路由就会执行一些由控制器处理的代码（参见 控制器文档）。要查看所有现有路线及其层次顺序，你可以运行 yarn strapi routes:list（参见 CLI 参考）。

¥Once a route exists, reaching it executes some code handled by a controller (see controllers documentation). To view all existing routes and their hierarchal order, you can run yarn strapi routes:list (see CLI reference).

Simplified Strapi backend diagram with routes highlighted
The diagram represents a simplified version of how a request travels through the Strapi back end, with routes highlighted. The backend customization introduction page includes a complete, interactive diagram.

执行​

¥Implementation

实现新路由包括在 ./src/api/[apiName]/routes 文件夹内的路由文件中定义它（请参阅 项目结构）。

¥Implementing a new route consists in defining it in a router file within the ./src/api/[apiName]/routes folder (see project structure).

根据用例，有 2 种不同的路由文件结构：

¥There are 2 different router file structures, depending on the use case:

配置核心路由​

¥Configuring core routers

核心路由（即 find、findOne、create、update 和 delete）对应于创建新 content-type 时由 Strapi 自动创建的 默认路由。

¥Core routers (i.e. find, findOne, create, update, and delete) correspond to default routes automatically created by Strapi when a new content-type is created.

Strapi 提供了 createCoreRouter 工厂功能，可自动生成核心路由并允许：

¥Strapi provides a createCoreRouter factory function that automatically generates the core routers and allows:

  • 将配置选项传递给每个路由

    ¥passing in configuration options to each router

  • 并禁用一些核心路由到 创建自定义的。

    ¥and disabling some core routers to create custom ones.

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

¥A core router file is a JavaScript file exporting the result of a call to createCoreRouter with the following parameters:

范围描述类型
prefix允许传入自定义前缀以添加到该型号的所有路由（例如 /test）String
only只会加载的核心路由

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

这在功能上与 only 参数相反。		Array
config配置处理路由的 policies、middlewares 和 公开可用性Object

./src/api/[apiName]/routes/[routerName].js (e.g './src/api/restaurant/routes/restaurant.js')

const { createCoreRouter } = require('@strapi/strapi').factories;

module.exports = createCoreRouter('api::restaurant.restaurant', {
  prefix: '',
  only: ['find', 'findOne'],
  except: [],
  config: {
    find: {
      auth: false,
      policies: [],
      middlewares: [],
    },
    findOne: {},
    create: {},
    update: {},
    delete: {},
  },
});

通用实现示例：

¥Generic implementation example:

./src/api/restaurant/routes/restaurant.js

const { createCoreRouter } = require('@strapi/strapi').factories;

module.exports = createCoreRouter('api::restaurant.restaurant', {
  only: ['find'],
  config: {
    find: {
      auth: false,
      policies: [],
      middlewares: [],
    }
  }
});

这仅允许来自核心 find controller 的 /restaurants 路径上的 GET 请求，无需身份验证。

¥This only allows a GET request on the /restaurants path from the core find controller without authentication.

创建自定义路由​

¥Creating custom routers

创建自定义路由包括创建一个导出对象数组的文件，每个对象都是具有以下参数的路由：

¥Creating custom routers 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 或 PATCH）String
path到达路径，以正斜线开头（例如 /articles）String
handler到达路由时执行的函数。
应遵循以下语法：<controllerName>.<actionName>		String
config

可选		配置处理路由的 policies、middlewares 和 公开可用性

Object

可以使用参数和正则表达式创建动态路由。这些参数将在 ctx.params 对象中公开。更多详细信息，请参阅 正则表达式路径 文档。

¥Dynamic routes can be created using parameters and regular expressions. These parameters will be exposed in the ctx.params object. For more details, please refer to the PathToRegex documentation.

✋ 提醒

路由文件按字母顺序加载。要在核心路由之前加载自定义路由，请确保适当地命名自定义路由（例如 01-custom-routes.js 和 02-core-routes.js）。

¥Routes files are loaded in alphabetical order. To load custom routes before core routes, make sure to name custom routes appropriately (e.g. 01-custom-routes.js and 02-core-routes.js).

Example of a custom router using URL parameters and regular expressions for routes

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

¥In the following example, the custom routes file name is prefixed with 01- to make sure the route is reached before the core routes.

./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',
    }
  ]
}

配置​

¥Configuration

核心路由 和 定制路由 具有相同的配置选项。路由配置在 config 对象中定义，可用于处理 policies 和 middlewares 或 公开路由。

¥Both core routers and custom routers have the same configuration options. The routes configuration is defined in a config object that can be used to handle policies and middlewares or to make the route public.

政策​

¥Policies

政策 可以添加到路由配置中：

¥Policies can be added to a route configuration:

  • 通过指向 ./src/policies 中注册的策略，无论是否传递自定义配置

    ¥by pointing to a policy registered in ./src/policies, with or without passing a custom configuration

  • 或者直接声明策略实现，作为一个以 policyContext 扩展 Koa 的背景 (ctx) 和 strapi 实例作为参数的函数（参见 政策文件）

    ¥or by declaring the policy implementation directly, as a function that takes policyContext to extend Koa's context (ctx) and the strapi instance as arguments (see policies documentation)

./src/api/restaurant/routes/restaurant.js

const { createCoreRouter } = require('@strapi/strapi').factories;

module.exports = createCoreRouter('api::restaurant.restaurant', {
  config: {
    find: {
      policies: [
        // point to a registered policy
        'policy-name',

        // point to a registered policy with some custom configuration
        { name: 'policy-name', config: {} }, 
        
        // pass a policy implementation directly
        (policyContext, config, { strapi }) => {
          return true;
        },
      ]
    }
  }
});

中间件​

¥Middlewares

中间件 可以添加到路由配置中：

¥Middlewares can be added to a route configuration:

  • 通过指向 ./src/middlewares 中注册的中间件，无论是否传递自定义配置

    ¥by pointing to a middleware registered in ./src/middlewares, with or without passing a custom configuration

  • 或者直接将中间件实现声明为以 Koa 的背景 (ctx) 和 strapi 实例作为参数的函数：

    ¥or by declaring the middleware implementation directly, as a function that takes Koa's context (ctx) and the strapi instance as arguments:

./src/api/restaurant/routes/restaurant.js

const { createCoreRouter } = require('@strapi/strapi').factories;

module.exports = createCoreRouter('api::restaurant.restaurant', {
  config: {
    find: {
      middlewares: [
        // point to a registered middleware
        'middleware-name', 

        // point to a registered middleware with some custom configuration
        { name: 'middleware-name', config: {} }, 

        // pass a middleware implementation directly
        (ctx, next) => {
          return next();
        },
      ]
    }
  }
});

公共路由​

¥Public routes

默认情况下，路由受到 Strapi 身份验证系统的保护，该系统基于 API 令牌 或使用 用户和权限插件。

¥By default, routes are protected by Strapi's authentication system, which is based on API tokens or on the use of the Users & Permissions plugin.

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

¥In some scenarios, it can be useful to have a route publicly available and control the access outside of the normal Strapi authentication system. This can be achieved by setting the auth configuration parameter of a route to false:

./src/api/restaurant/routes/restaurant.js

const { createCoreRouter } = require('@strapi/strapi').factories;

module.exports = createCoreRouter('api::restaurant.restaurant', {
  config: {
    find: {
      auth: false
    }
  }
});