Was macht Strapi Patterns?
Kurzanleitung: Strapi als Open-Source-Headless-CMS mit automatisch generierten REST/GraphQL-APIs aus Content-Type-Schemas verwenden. In v5 die Document Service API (
strapi.documents()) für den serverseitigen Datenzugriff anstelle der veralteten Entity Service API nutzen. REST-API-Antworten verwenden ein flaches Format (data.fieldName, nichtdata.attributes.fieldName). Beziehungen und Medien werden standardmäßig NICHT befüllt – immerpopulateübergeben.qsverwenden, um komplexe Abfragezeichenfolgen zu erstellen. Content-Types sind standardmäßig privat; Berechtigungen über das Users & Permissions Plugin oder API-Tokens konfigurieren.
<critical_requirements>
KRITISCH: Vor der Verwendung dieser Skill
Der gesamte Code muss die Projektkonventionen in CLAUDE.md befolgen (kebab-case, benannte Exporte, Import-Reihenfolge,
import type, benannte Konstanten)
(Sie MÜSSEN strapi.documents('api::content-type.content-type') (Document Service API) für den gesamten serverseitigen Datenzugriff in Strapi v5 verwenden – die Entity Service API ist entfernt)
(Sie MÜSSEN immer populate übergeben, wenn Sie Beziehungen, Medien, Komponenten oder dynamische Zonen benötigen – Strapi gibt standardmäßig KEINE Beziehungen zurück)
(Sie MÜSSEN die Bibliothek qs verwenden, um komplexe REST-API-Abfragezeichenfolgen mit Filtern, populate und sort zu erstellen – manuelle Zeichenfolgenerstellung bricht bei verschachtelten Parametern)
(Sie MÜSSEN sowohl Eingabe als auch Ausgabe in benutzerdefinierten Controllern mit this.sanitizeQuery(ctx), this.sanitizeOutput() und this.validateQuery(ctx) bereinigen und validieren)
(Sie MÜSSEN Berechtigungen für jeden Content-Type-Endpunkt über das Admin-Panel oder die Konfiguration festlegen – alle Routen sind standardmäßig privat)
</critical_requirements>
Auto-Erkennung: Strapi, strapi, @strapi/strapi, createCoreController, createCoreService, createCoreRouter, Document Service, strapi.documents, content-type, schema.json, api::, plugin::, lifecycle hooks, Users & Permissions, /api/auth/local, populate, qs.stringify
Wann verwenden:
- Erstellen von inhaltsverwalteten Anwendungen mit Strapi als Headless-CMS
- Definieren von Content-Type-Schemas (
schema.json) mit Feldern, Beziehungen, Komponenten und dynamischen Zonen - Abfragen der REST-API mit Filtern,
populate,sortund Paginierung - Erstellen von benutzerdefinierten Controllern, Services, Routen, Policies oder Middlewares
- Verwenden der Document Service API für serverseitiges CRUD mit Entwurf/Veröffentlichungs-Workflows
- Implementieren der JWT-Authentifizierung mit dem Users & Permissions Plugin
- Hinzufügen von Lifecycle Hooks zu Content-Types für Nebeneffekte
- Generieren von TypeScript-Typen für Content-Schemas
Wichtige abgedeckte Muster:
- Content-Type-Schema-Definition (
schema.json) - REST-API-Abfragen mit
qs(Filter,populate,sort, Paginierung) - Document Service API (
findMany,findOne,create,update,delete,publish,unpublish) - Benutzerdefinierte Controller, Services, Routen, Policies und Middlewares
- Lifecycle Hooks (
beforeCreate,afterUpdate, etc.) - JWT-Authentifizierung (Registrierung, Login, authentifizierte Anfragen)
- TypeScript-Typgenerierung
Wann NICHT verwenden:
- Nicht-Strapi-CMS-Plattformen (die dafür vorgesehene Skill für Ihr CMS verwenden)
- Direkte Datenbankabfragen, die die Strapi-API-Schicht umgehen (Die Document Service API von Strapi verwenden)
- Komplexe transaktionale Logik, die rohes SQL erfordert (Strapi abstrahiert die Datenbank)
Detaillierte Ressourcen:
- Für Entscheidungsrahmen und Kurzreferenztabellen siehe reference.md
Core & REST API:
- examples/core.md – Content-Type-Schemas, REST-API-Abfragen, Document Service API, Fehlerbehandlung
Backend-Anpassung:
- examples/backend.md – Benutzerdefinierte Controller, Services, Routen, Policies, Middlewares, Lifecycle Hooks, Document Service Middleware
Authentifizierung:
- examples/auth.md – JWT-Authentifizierung, Registrierung, Login, Rollen und Berechtigungen
Philosophie
Strapi ist ein Open-Source-Headless-CMS, das auf Node.js (Koa) aufbaut und RESTful- und GraphQL-APIs automatisch aus Content-Type-Schemas generiert. Inhalte werden über JSON-Schemas definiert, über ein Admin-Panel verwaltet und über generierte API-Endpunkte konsumiert.
Kernprinzipien:
- Schema-gesteuerte Inhalte – Content-Types werden in
schema.json-Dateien definiert, die Felder, Beziehungen, Komponenten und dynamische Zonen beschreiben. Der Admin-Panel Content-Type Builder bietet einen visuellen Editor, aber Schemas sind Code, der sich in Ihrem Repository befindet. - Automatisch generierte APIs – Jeder Content-Type erhält automatisch CRUD-REST-Endpunkte (
/api/:pluralApiId) und optional GraphQL-Unterstützung. Keine manuelle Erstellung von Routen/Controllern für Standardoperationen erforderlich. - Document Service API (v5) – Die serverseitige API für den Zugriff auf Inhalte aus benutzerdefiniertem Code, Plugins und Lifecycle Hooks. Ersetzt die Entity Service API von v4. Verwendet
documentId(nicht die Datenbank-id) als primären Identifikator. - Entwurf & Veröffentlichen – Content-Types können Entwurf/Veröffentlichungs-Workflows haben. Der Document Service verwendet standardmäßig den Status
'draft'; veröffentlichter Inhalt erfordertstatus: 'published'oder explizitepublish()-Aufrufe. - Berechtigungen zuerst – Alle Content-Type-Endpunkte sind standardmäßig privat. Der Zugriff muss explizit über das Admin-Panel (Users & Permissions Plugin) oder API-Tokens gewährt werden.
- Backend-Anpassung – Controller, Services, Routen, Policies und Middlewares können alle angepasst werden. Strapi folgt einem MVC-ähnlichen Muster, das auf Koa aufbaut.
Kernmuster
Muster 1: Content-Type-Schema
Content-Types werden in schema.json-Dateien unter ./src/api/[api-name]/content-types/[content-type-name]/schema.json definiert. Verwenden Sie collectionType für Multi-Dokument-Inhalte (Artikel, Produkte) und singleType für Ein-Dokument-Inhalte (Site-Einstellungen, Startseite).
{
"kind": "collectionType",
"info": {
"singularName": "article",
"pluralName": "articles",
"displayName": "Article"
},
"options": { "draftAndPublish": true },
"attributes": {
"title": { "type": "string", "required": true },
"slug": { "type": "uid", "targetField": "title" },
"author": {
"type": "relation",
"relation": "manyToOne",
"target": "api::author.author",
"inversedBy": "articles"
},
"blocks": {
"type": "dynamiczone",
"components": ["blocks.hero", "blocks.rich-text"]
}
}
}
Wichtige Felder: uid generiert automatisch Slugs aus targetField, relation-Typen definieren die Kardinalität mit inversedBy/mappedBy, component bettet wiederverwendbare Blöcke ein, dynamiczone erlaubt gemischte Komponententypen. Siehe examples/core.md für vollständige Beispiele für Collection- und Single-Types.
Muster 2: REST-API-Abfragen mit qs
Die REST-API akzeptiert komplexe Abfrageparameter zum Filtern, Befüllen, Sortieren und Paginieren. Verwenden Sie immer die Bibliothek qs, um Abfragezeichenfolgen zu erstellen.
import qs from "qs";
const query = qs.stringify(
{
filters: { publishedAt: { $notNull: true } },
populate: {
author: { fields: ["name"] },
categories: { fields: ["name", "slug"] },
},
sort: ["publishedAt:desc"],
pagination: { page: 1, pageSize: 25 },
},
{ encodeValuesOnly: true },
);
const response = await fetch(`${STRAPI_URL}/api/articles?${query}`);
const { data, meta } = await response.json();
Wichtige Punkte: encodeValuesOnly verhindert Probleme mit der Klammercodierung, Filter verwenden Operatoren ($eq, $notNull, $containsi, $or, $and), gezieltes populate mit fields vermeidet Überabruf (niemals populate=* in der Produktion verwenden), dynamische Zonenkomponenten verwenden die on-Syntax. Siehe examples/core.md für vollständige Beispiele zu Filtern, Befüllen und Paginierung.
Muster 3: Document Service API (Back-End)
Die Document Service API wird in benutzerdefinierten Controllern, Services, Lifecycle Hooks und Plugins verwendet, um serverseitig auf Inhalte zuzugreifen. Sie ersetzt die Entity Service API von v4 (in v5 entfernt).
const CONTENT_TYPE_UID = "api::article.article";
// Veröffentlichte Inhalte finden (Standard ist 'draft')
const articles = await strapi.documents(CONTENT_TYPE_UID).findMany({
status: "published",
filters: { categories: { slug: { $eq: "news" } } },
populate: { author: true },
});
// CRUD verwendet documentId (nicht die Datenbank-id)
const article = await strapi
.documents(CONTENT_TYPE_UID)
.findOne({ documentId });
const created = await strapi
.documents(CONTENT_TYPE_UID)
.create({ data: { title: "New" } });
await strapi.documents(CONTENT_TYPE_UID).publish({ documentId });
Wichtige Punkte: strapi.documents(uid) ersetzt strapi.entityService (in v5 entfernt), documentId ist der persistente Identifikator über Locales und Entwurf/Veröffentlichungs-Versionen hinweg, der Standardstatus ist 'draft' (explizit status: 'published' übergeben), dedizierte publish()/unpublish()/discardDraft()-Methoden. Siehe examples/core.md für vollständige CRUD- und Veröffentlichungs-/Zurückziehungsbeispiele.
Muster 4: Benutzerdefinierte Controller
Erweitern oder ersetzen Sie automatisch generierte Controller-Aktionen. Controller behandeln Anfrage-/Antwortlogik und delegieren an Services. Verwenden Sie createCoreController aus factories, um Bereinigungshilfsfunktionen zu erben.
// src/api/article/controllers/article.ts
export default factories.createCoreController(
"api::article.article",
({ strapi }) => ({
async find(ctx) {
await this.validateQuery(ctx);
const sanitizedQuery = await this.sanitizeQuery(ctx);
const { results, pagination } = await strapi
.service("api::article.article")
.find(sanitizedQuery);
const sanitizedResults = await this.sanitizeOutput(results, ctx);
return this.transformResponse(sanitizedResults, { pagination });
},
}),
);
Warum gut: validateQuery + sanitizeQuery + sanitizeOutput erzwingen rollenbasierten Feldzugriff, transformResponse() verpackt die Ausgabe in ein { data, meta }-Envelope
Siehe examples/backend.md für vollständige Controller-Beispiele mit benutzerdefinierten Aktionen (findBySlug, incrementViews, search).
Muster 5: Benutzerdefinierte Routen
Definieren Sie benutzerdefinierte Routen, um benutzerdefinierte Controller-Aktionen bereitzustellen. Benutzerdefinierte Routendateien befinden sich neben dem Core-Router.
// src/api/article/routes/custom-article.ts
export default {
routes: [
{
method: "GET",
path: "/articles/slug/:slug",
handler: "api::article.article.findBySlug",
config: { auth: false },
},
],
};
Warum gut: Separate Datei vom Core-Router, handler verwendet die vollständige UID, auth: false für öffentlichen Zugriff, Policies/Middlewares pro Route anheftbar
Siehe examples/backend.md für Routeneinschränkung mit only, Middleware-Anheftung und Policy-Konfiguration.
Muster 6: Lifecycle Hooks
Registrieren Sie Nebeneffekte bei Content-Type-Operationen. Hooks werden in lifecycles.ts-Dateien neben dem Content-Type-Schema definiert.
// src/api/article/content-types/article/lifecycles.ts
export default {
async beforeCreate(event) {
/* event.params.data – mutieren, um Eingabe zu transformieren */
},
async afterCreate(event) {
/* event.result – das erstellte Dokument */
},
async beforeUpdate(event) {
/* event.params.data – vor dem Speichern mutieren */
},
async afterDelete(event) {
/* event.result – zugehörige Ressourcen bereinigen */
},
};
Warum gut: Hooks feuern automatisch bei Document Service-Operationen, beforeXxx kann event.params.data mutieren, afterXxx hat event.result
Hinweis: Für übergreifende Belange in v5 (Audit-Logging, Cache-Invalidierung) bevorzugen Sie Document Service Middleware (strapi.documents.use((ctx, next) => { ... })), die in src/index.ts registriert wird. Lifecycle Hooks sind weiterhin für Content-Type-spezifische Nebeneffekte verfügbar.
Siehe examples/backend.md für vollständige Lifecycle-Beispiele inklusive Slug-Generierung, programmatischem Abonnement und Audit-Logging.
Muster 7: Services
Services enthalten wiederverwendbare Geschäftslogik, die von Controllern aufgerufen wird. Verwenden Sie createCoreService, um das standardmäßige CRUD zu erben und benutzerdefinierte Methoden hinzuzufügen.
export default factories.createCoreService(
"api::article.article",
({ strapi }) => ({
async findPublished(filters = {}) {
return strapi
.documents("api::article.article")
.findMany({ status: "published", filters });
},
}),
);
// Aufgerufen über: strapi.service("api::article.article").findPublished()
Warum gut: Erbt das standardmäßige CRUD, benutzerdefinierte Methoden kapseln wiederverwendbare Abfragelogik, werden von Controllern über strapi.service(uid) aufgerufen
Siehe examples/backend.md für komplexe Service-Beispiele inklusive verwandter Artikelabfragen und Veröffentlichen-mit-Benachrichtigungsmustern.
Muster 8: Policies
Policies sind schreibgeschützte Funktionen, die den Zugriff auf eine Route erlauben oder verweigern. Sie geben true (erlauben) oder false (verweigern) zurück und können die Anfrage nicht ändern.
// src/api/article/policies/is-owner.ts
export default async (policyContext, config, { strapi }) => {
const article = await strapi.documents("api::article.article").findOne({
documentId: policyContext.params.documentId,
populate: { author: true },
});
return article?.author?.documentId === policyContext.state.user?.documentId;
};
Warum gut: Schreibgeschützte Prüfung (keine Anfragemutation), pro Aktion auf der Core-Router-Konfiguration angewendet
Siehe examples/backend.md für die Anwendung von Policies auf Routen, Ratenbegrenzungs-Policies und die Verkettung mehrerer Policies.
<decision_framework>
Entscheidungsrahmen
REST-API vs. Document Service API
Wo läuft Ihr Code?
+-- Client-seitig (Browser, Frontend-App)
| +-- REST-API verwenden (fetch /api/:pluralApiId)
+-- Server-seitig (benutzerdefinierter Controller, Service, Plugin, Lifecycle Hook)
+-- Document Service API verwenden (strapi.documents(uid))
Befüllungsstrategie
Benötigen Sie zugehörige Daten?
+-- NEIN --> `populate` nicht übergeben (schlankere Antwort)
+-- JA --> Welche Kontrollstufe?
+-- Alle Beziehungen, 1 Ebene --> populate: '*' (bequem, aber Überabruf)
+-- Bestimmte Beziehungen --> populate: { relation: { fields: [...] } }
+-- Verschachtelte Beziehungen
…