Skip to main content

插件的服务器 API：概述

🌐 Server API for plugins: An overview

Page summary:

服务器 API 定义了插件在 Strapi 服务器上注册、暴露和执行的内容。它包括生命周期钩子、路由、控制器、服务、策略、中间件和配置。使用入口文件声明插件的贡献内容，然后导航到下面为每个功能提供的专用页面。

Strapi 插件可以与 Strapi 应用的前端和后端进行交互。服务器 API 涵盖后端部分：它定义了插件在 Strapi 服务器上注册、暴露和执行的内容。服务器部分在入口文件中定义，该文件导出一个对象（或返回对象的函数）。该对象描述了插件对服务器的贡献内容。

🌐 A Strapi plugin can interact with both the back end and the front end of a Strapi application. The Server API covers the back-end part: it defines what the plugin registers, exposes, and executes on the Strapi server. The server part is defined in the entry file, which exports an object (or a function returning an object). That object describes what the plugin contributes to the server.

有关插件如何自定义管理面板界面的更多信息，请参阅 Admin Panel API。

🌐 For more information on how plugins can customize the admin panel UI, see Admin Panel API.

Prerequisites

在深入了解本页的概念之前，请确保你已经创建了一个 Strapi 插件。

🌐 Before diving deeper into the concepts on this page, please ensure you created a Strapi plugin.

入口文件​

🌐 Entry file

服务器 API 的入口文件是 [plugin-name]/server/src/index.js|ts。该文件导出所需的接口，提供以下可用参数：

🌐 The entry file for the Server API is [plugin-name]/server/src/index.js|ts. This file exports the required interface, with the following parameters available: | 参数类型 | 可用参数 || --- | --- || 生命周期函数 | register(), bootstrap(), destroy() || 配置 | config 对象 || 后端自定义 | contentTypes, routes, controllers, services, policies, middlewares |

一个最小的入口文件看起来像这样：

🌐 A minimal entry file looks like this:

/src/plugins/my-plugin/server/src/index.js
'use strict';

const register = require('./register');
const bootstrap = require('./bootstrap');
const destroy = require('./destroy');
const config = require('./config');
const contentTypes = require('./content-types');
const routes = require('./routes');
const controllers = require('./controllers');
const services = require('./services');
const policies = require('./policies');
const middlewares = require('./middlewares');

module.exports = () => ({
  register,
  bootstrap,
  destroy,
  config,
  contentTypes,
  routes,
  controllers,
  services,
  policies,
  middlewares,
});

从技术上讲，所有服务器代码都可以放在单一的入口文件中，但强烈建议将每个关注点拆分到各自的文件夹中，就像插件 SDK 生成的那样。本教程中的示例遵循了这种结构。

🌐 All server code can technically live in the single entry file, but splitting each concern into its own folder, as generated by the Plugin SDK, is strongly recommended. The examples in this documentation follow that structure.

Notes
  • 入口文件接受对象字面量或返回相同对象形状的函数。当使用函数形式时，Strapi 在加载插件模块时会使用 { env }（而不是 { strapi }）调用它。
  • config 是一个配置对象，而不是可执行的生命周期钩子。与 register()、bootstrap() 或 destroy() 不同，它在插件生命周期中不会作为函数被调用。它在启动时加载，用于设置默认值和验证用户配置。有关更多信息，请参见 服务器生命周期。

可用操作​

🌐 Available actions

服务器 API 让插件能够利用多个构建模块来定义其服务器端行为。

🌐 The Server API lets a plugin take advantage of several building blocks to define its server-side behavior.

使用下表查找与你的目标相匹配的能力：

🌐 Use the following table to find which capability matches your goal:

目标使用的参数运行时间
在服务器启动前运行代码register()在数据库和路由初始化之前
在所有插件加载后运行代码bootstrap()在数据库、路由和权限初始化后
在关闭时清理资源destroy()在关闭时
使用默认值和验证定义插件选项config启动时加载
声明插件内容类型contentTypes启动时加载
公开 HTTP 端点routes启动时加载
处理 HTTP 请求controllers每个请求调用
实现业务逻辑services从控制器或生命周期钩子调用
在路由上强制执行访问规则policies在控制器之前按每个请求评估
拦截并修改请求/响应流程middlewares附加在 register() 中或在路由配置中引用
在运行时访问插件功能获取器任何生命周期或请求处理程序

以下卡片直接链接到各自的专页：

🌐 The following cards link directly to each dedicated page:

Backend customization

插件的路由、控制器、服务、策略和中间件遵循与标准 Strapi 应用中的后端自定义相同的约定。服务器 API 会自动将这些封装到插件命名空间中（有关 UID 和命名约定的详细信息，请参见服务器内容类型）。

🌐 Plugin routes, controllers, services, policies, and middlewares follow the same conventions as backend customization in a standard Strapi application. The Server API wraps these into the plugin namespace automatically (see server content types for details on UIDs and naming conventions).