Communitygithub.com

Strapi Patterns

Open-Source Headless CMS – Content-Type-Schemas, REST-API, Document Service API, benutzerdefinierte Controller, Lifecycle Hooks, Authentifizierung, TypeScript

Was ist Strapi Patterns?

Diese Skill-Anleitung beschreibt, wie Strapi als Open-Source-Headless-CMS mit automatisch generierten REST/GraphQL-APIs aus Content-Type-Schemas verwendet wird. In der Strapi v5 muss für den serverseitigen Datenzugriff die Document Service API (`strapi.documents()`) anstelle der veralteten Entity Service API genutzt werden. Die REST-API-Antworten verwenden ein flaches Format (`data.fieldName` statt `data.attributes.fieldName`). Beziehungen und Medien werden standardmäßig NICHT befüllt – immer `populate` übergeben. Die Bibliothek `qs` dient zum Erstellen komplexer Abfragezeichenfolgen. Content-Types sind standardmäßig privat; Berechtigungen werden über das Users & Permissions Plugin oder API-Tokens konfiguriert. Die Anleitung behandelt die Definition von Content-Type-Schemas, REST-API-Abfragen, die Document Service API für CRUD-Operationen, benutzerdefinierte Controller, Services, Routes, Policies, Middlewares, Lifecycle Hooks und die JWT-Authentifizierung – alles mit klaren Entscheidungsrahmen und Anti-Patterns für den produktiven Einsatz.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/agents-inc/skills/tree/HEAD/src/skills/api-cms-strapi

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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, nicht data.attributes.fieldName). Beziehungen und Medien werden standardmäßig NICHT befüllt – immer populate übergeben. qs verwenden, 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, sort und 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:

  1. 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.
  2. 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.
  3. 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.
  4. Entwurf & Veröffentlichen – Content-Types können Entwurf/Veröffentlichungs-Workflows haben. Der Document Service verwendet standardmäßig den Status 'draft'; veröffentlichter Inhalt erfordert status: 'published' oder explizite publish()-Aufrufe.
  5. 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.
  6. 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

…

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

Verwandte Skills