strapi-v5-expert

Указания для Агента

Когда пользователь ставит задачу, найди наиболее подходящую категорию в разделе "Quick Reference" ниже. Скопируй нужный URL и ИСПОЛЬЗУЙ ИНСТРУМЕНТ WEB BROWSING, чтобы прочитать актуальную документацию Strapi v5 по этой ссылке. Только после прочтения приступай к генерации кода.

---

Quick Reference (Индекс Документации)

1. Document Service API (Главный инструмент работы с БД)

Используй эти ссылки для любых задач, связанных с CRUD операциями бэкенда. Устаревший entityService заменен на strapi.documents().

• Core API & CRUD: https://docs.strapi.io/dev-docs/api/document-service Описание: Базовые методы (findOne, findMany, create, update, delete, count). Работа с documentId.
• Documents Concept: https://docs.strapi.io/dev-docs/api/document-service#documents Описание: Что такое Document в Strapi 5 (объединение локалей и статусов публикации в один объект).
• Populate (Связи и Медиа): https://docs.strapi.io/dev-docs/api/document-service/populate Описание: Как запрашивать вложенные связи и медиафайлы.
• Fields Selection: https://docs.strapi.io/dev-docs/api/document-service/fields Описание: Выборка конкретных колонок из БД (параметр fields).
• Filters (Фильтрация): https://docs.strapi.io/dev-docs/api/document-service/filters Описание: Операторы фильтрации ($eq, $in, $not, $and и др.).
• Sort & Pagination: https://docs.strapi.io/dev-docs/api/document-service/sort-pagination Описание: Сортировка по полям и пагинация (limit, start).
• Locale (i18n): https://docs.strapi.io/dev-docs/api/document-service/locale Описание: Манипуляции с документами для конкретной локали (языка).
• Draft & Publish: https://docs.strapi.io/dev-docs/api/document-service/draft-and-publish Описание: Работа со статусами (published, draft), методы publish() и unpublish().
• Document Service Middlewares: https://docs.strapi.io/dev-docs/api/document-service/middlewares Описание: Перехват и модификация запросов strapi.documents.use() до обращения к БД.

2. Архитектура и Кастомизация Бэкенда

• Overview & Structure: https://docs.strapi.io/dev-docs/backend-customization Описание: Интерактивная диаграмма запросов бэкенда.
• Project Structure: https://docs.strapi.io/dev-docs/project-structure Описание: Структура папок Strapi-проекта (src/api, config и т.д.).
• Routes: https://docs.strapi.io/dev-docs/backend-customization/routes Описание: Настройка кастомных HTTP-маршрутов и core-роутов.
• Controllers: https://docs.strapi.io/dev-docs/backend-customization/controllers Описание: Создание кастомных контроллеров и расширение (createCoreController).
• Services: https://docs.strapi.io/dev-docs/backend-customization/services Описание: Инкапсуляция бизнес-логики (createCoreService).
• Middlewares (HTTP): https://docs.strapi.io/dev-docs/backend-customization/middlewares Описание: Глобальные и route-мидлвары Koa (ctx, next).
• Policies: https://docs.strapi.io/dev-docs/backend-customization/policies Описание: Защита эндпоинтов и проверка прав доступа до контроллера.
• Requests & Responses: https://docs.strapi.io/dev-docs/backend-customization/requests-responses Описание: Структура объекта ctx (ctx.request, ctx.state.user, ctx.response).
• Error Handling: https://docs.strapi.io/dev-docs/error-handling Описание: Выброс стандартизированных ошибок (ApplicationError, ValidationError).
• Lifecycle Functions (Global): https://docs.strapi.io/dev-docs/configurations/functions Описание: Использование register, bootstrap и destroy в файле src/index.ts.

3. 模型和数据库

• 模型与内容类型： https://docs.strapi.io/dev-docs/backend-customization/models 说明： 创建数据架构（schema.json）、属性类型。
• 生命周期钩子： https://docs.strapi.io/dev-docs/backend-customization/models#lifecycle-hooks 说明： 数据库触发器（beforeCreate、afterUpdate）。
• 关联关系： https://docs.strapi.io/dev-docs/api/rest/relations 说明： 通过 API 管理关联关系（connect、disconnect、set）。
• 数据库事务： https://docs.strapi.io/dev-docs/database/transactions 说明： 使用 strapi.db.transaction() 执行原子操作。
• 数据库迁移： https://docs.strapi.io/dev-docs/database/migrations 说明： 用于迁移结构或数据的脚本（database/migrations 文件夹）。
• 数据库配置： https://docs.strapi.io/dev-docs/configurations/database 说明： 配置 config/database.ts（SQLite、PostgreSQL、MySQL）。

4. 外部 API（REST、GraphQL、客户端）

• 内容 API 概览： https://docs.strapi.io/dev-docs/api/content-api 说明： Strapi 外部 API 概览。
• REST API 参考： https://docs.strapi.io/dev-docs/api/rest 说明： 主要端点参考。v5 的响应采用扁平格式。
• REST API 参数： https://docs.strapi.io/dev-docs/api/rest/parameters 说明： REST API 参数完整列表。
• REST API 指南： https://docs.strapi.io/dev-docs/api/rest/guides 说明： REST API 的特定使用场景。
• REST API Populate 与 Select： https://docs.strapi.io/dev-docs/api/rest/populate-select 说明： REST 请求中的 populate 和 fields 参数。
• REST API 排序与分页： https://docs.strapi.io/dev-docs/api/rest/sort-pagination 说明： 按 offset 和 page 进行排序与分页。
• REST API 状态： https://docs.strapi.io/dev-docs/api/rest/status 说明： 按状态（published/draft）筛选 REST 响应。
• REST API 区域设置： https://docs.strapi.io/dev-docs/api/rest/locale 说明： 使用 locale 参数发送 REST API 请求。
• REST API 上传： https://docs.strapi.io/dev-docs/api/rest/upload 说明： 通过 POST /api/upload 上传文件。
• 交互式查询构建器： https://docs.strapi.io/dev-docs/api/rest/interactive-query-builder 说明： 使用 qs 库构建复杂 URL。
• GraphQL API： https://docs.strapi.io/dev-docs/api/graphql 说明： 使用 GraphQL 突变和查询，以及筛选功能。
• GraphQL 插件配置： https://docs.strapi.io/dev-docs/plugins/graphql 说明： 在 config/plugins.ts 中配置 Apollo Server、Shadow CRUD 和复杂度限制。
• Strapi 客户端： https://docs.strapi.io/dev-docs/strapi-client 说明： 面向前端的官方库 @strapi/client。
• OpenAPI 与 Swagger： https://docs.strapi.io/dev-docs/api/openapi 说明： 生成 OpenAPI 规范，使用 Documentation 插件。

5. TypeScript

• TypeScript 设置与概览： https://docs.strapi.io/dev-docs/typescript 说明： 在 Strapi 中使用 TypeScript。
• TypeScript 开发： https://docs.strapi.io/dev-docs/typescript/development 说明： 自动补全、strapi 实例的类型声明。
• 文档操作： https://docs.strapi.io/dev-docs/typescript/manipulating-documents 说明： 使用 UID.ContentType 和 Data.Document 实现严格类型声明。
• TypeScript 配置： https://docs.strapi.io/dev-docs/typescript/configuration 说明： config/typescript.ts 配置和类型自动生成。
• 添加 TypeScript： https://docs.strapi.io/dev-docs/typescript/migration 说明： 如何在现有 JS 项目中添加 TS。

6. 配置与自动化（Settings）

• 配置概览： https://docs.strapi.io/dev-docs/configurations 描述： /config 文件夹概览。
• 服务器配置： https://docs.strapi.io/dev-docs/configurations/server 描述： config/server.ts（host、port、url、proxy）。
• API 配置： https://docs.strapi.io/dev-docs/configurations/api 描述： config/api.ts（前缀、分页限制）。
• 中间件配置： https://docs.strapi.io/dev-docs/configurations/middlewares 描述： 在 config/middlewares.ts 中配置内置中间件（CORS、security、body）。
• 插件配置： https://docs.strapi.io/dev-docs/configurations/plugins 描述： 在本地连接和配置插件（config/plugins.ts）。
• 环境变量： https://docs.strapi.io/dev-docs/configurations/environment 描述： 使用 .env 和 env() 助手函数。
• CRON 作业： https://docs.strapi.io/dev-docs/configurations/cron 描述： 按计划执行后台任务（node-schedule）。
• Webhooks： https://docs.strapi.io/dev-docs/configurations/webhooks 描述： 配置向外部系统发送 HTTP 请求的触发器。
• 功能（Feature Flags）： https://docs.strapi.io/dev-docs/configurations/features 描述： 启用实验性功能。

7. 插件与扩展

• 安装插件： https://docs.strapi.io/user-docs/plugins 描述： 使用 Marketplace 和 CLI 安装插件。
• 用户与权限： https://docs.strapi.io/dev-docs/plugins/users-permissions 描述： 管理用户、JWT、ACL、注册和角色。
• 上传文件 / 媒体库： https://docs.strapi.io/dev-docs/plugins/upload 描述： 配置文件上传提供程序（AWS S3、本地）。
• Email 插件： https://docs.strapi.io/dev-docs/plugins/email 描述： 发送事务性邮件，配置 SMTP 提供程序。
• 自定义字段： https://docs.strapi.io/dev-docs/custom-fields 描述： 创建和注册自定义字段类型。
• Sentry 插件： https://docs.strapi.io/dev-docs/plugins/sentry 描述： 集成 Sentry 以跟踪错误。

8. 从 v4 迁移到 v5

• 升级简介： https://docs.strapi.io/dev-docs/migration/v4-to-v5 描述： Strapi 5 升级流程概览。
• 分步指南： https://docs.strapi.io/dev-docs/migration/v4-to-v5/step-by-step 描述： 升级分步说明。
• 升级工具： https://docs.strapi.io/dev-docs/migration/v4-to-v5/upgrade-tool 描述： 使用 CLI 工具（codemods）自动迁移。
• 破坏性变更： https://docs.strapi.io/dev-docs/migration/v4-to-v5/breaking-changes 描述： 破坏性变更的完整列表。
• 从 Entity Service 到 Document Service： https://docs.strapi.io/dev-docs/migration/v4-to-v5/entity-service 描述： 将旧查询重构为新 API，并使用 documentId。
• 插件迁移： https://docs.strapi.io/dev-docs/migration/v4-to-v5/plugins 描述： 更新插件并使用 Plugin SDK。
• Helper-plugin 迁移： https://docs.strapi.io/dev-docs/migration/v4-to-v5/helper-plugin 描述： 替换已移除的 @strapi/helper-plugin。
• Design System 更新： https://docs.strapi.io/dev-docs/migration/v4-to-v5/design-system 描述： UI 组件的变更（Design System v2）。

9. Инфраструктура и CLI

• Installation & Quick Start: https://docs.strapi.io/dev-docs/installation Описание: Установка Strapi (CLI, Docker).
• Command Line Interface (CLI): https://docs.strapi.io/dev-docs/cli Описание: Команды strapi generate, build, ts:generate-types.
• Templates: https://docs.strapi.io/dev-docs/templates Описание: Создание проектов на основе готовых шаблонов GitHub.
• Deployment: https://docs.strapi.io/dev-docs/deployment Описание: Требования к серверу, переменные для продакшена.
• Data Management: https://docs.strapi.io/dev-docs/data-management Описание: Импорт/Экспорт/Трансфер данных между базами (CLI).
• Testing: https://docs.strapi.io/dev-docs/testing Описание: Настройка Jest и Supertest для unit и интеграционных тестов.

10. CMS Features и Админ-Панель

• Admin Panel Settings: https://docs.strapi.io/user-docs/intro Описание: Обзор графического интерфейса администратора.
• Admin Panel Configuration: https://docs.strapi.io/dev-docs/configurations/admin-panel Описание: Настройка config/admin.ts (секреты, переводы).
• Homepage Customization: https://docs.strapi.io/dev-docs/admin-panel-customization/homepage Описание: Добавление виджетов на главную страницу админки.
• Content-Type Builder: https://docs.strapi.io/user-docs/content-type-builder Описание: Использование GUI для создания моделей данных.
• Content Manager: https://docs.strapi.io/user-docs/content-manager Описание: Интерфейс редактирования записей.
• Draft & Publish (CMS): https://docs.strapi.io/user-docs/draft-and-publish Описание: Механика статусов контента.
• Internationalization (CMS): https://docs.strapi.io/dev-docs/plugins/i18n Описание: Перевод контента на разные языки в админке.
• Preview: https://docs.strapi.io/dev-docs/plugins/preview Описание: Настройка Live Preview (предпросмотр контента на фронтенде).
• API Tokens: https://docs.strapi.io/user-docs/api-tokens Описание: Токены для Server-to-Server интеграций.
• Role-Based Access Control (RBAC): https://docs.strapi.io/user-docs/users-roles-permissions Описание: Настройка прав администраторов панели.
• Single Sign-On (SSO): https://docs.strapi.io/dev-docs/configurations/sso Описание: Авторизация админов через Azure, Google (Enterprise).
• Audit Logs: https://docs.strapi.io/user-docs/audit-logs Описание: Журналирование действий администраторов (Enterprise).
• Review Workflows: https://docs.strapi.io/user-docs/review-workflows Описание: Настройка стадий ревью контента (Enterprise).
• Content History: https://docs.strapi.io/user-docs/content-history Описание: Версионирование и откат изменений контента (Enterprise).
• Releases: https://docs.strapi.io/user-docs/releases Описание: Пакетная публикация контента (Growth/Enterprise).