workers-best-practices

Examine et évalue du code Cloudflare Workers selon les bonnes pratiques de production. À utiliser lors de l'écriture de nouveaux Workers, de la revue de code Worker, de la configuration de wrangler.jsonc, ou de la vérification des anti-patterns courants (streaming, floating promises, état global, secrets, bindings, observabilité). Privilégie la récupération depuis la documentation Cloudflare plutôt que les connaissances pré-entraînées.

npx skills add https://github.com/cloudflare/skills --skill workers-best-practices

Votre connaissance des APIs Cloudflare Workers, des types et de la configuration peut être obsolète. Privilégiez la récupération plutôt que la pré-formation pour toute tâche de code Workers — écriture ou révision.

Sources de récupération

Récupérez les dernières versions avant d'écrire ou de réviser du code Workers. Ne vous fiez pas aux connaissances intégrées pour les signatures API, les champs de config ou les formes de binding.

Source Comment récupérer Utilisation
Bonnes pratiques Workers Récupérez https://developers.cloudflare.com/workers/best-practices/workers-best-practices/ Règles canoniques, patterns, anti-patterns
Types Workers Voir references/review.md pour les étapes de récupération Signatures API, types de handler, types de binding
Schéma de config Wrangler node_modules/wrangler/config-schema.json Champs de config, formes de binding, valeurs autorisées
Docs Cloudflare Outil de recherche ou https://developers.cloudflare.com/workers/ Référence API, dates/flags de compatibilité

D'ABORD : Récupérez les dernières références

Avant de réviser ou d'écrire du code Workers, récupérez la page des bonnes pratiques actuelles et les définitions de types pertinents. Si le node_modules du projet contient une version plus ancienne, privilégiez la dernière version publiée.

# Récupérez les derniers types workers
mkdir -p /tmp/workers-types-latest && \
  npm pack @cloudflare/workers-types --pack-destination /tmp/workers-types-latest && \
  tar -xzf /tmp/workers-types-latest/cloudflare-workers-types-*.tgz -C /tmp/workers-types-latest
# Types à /tmp/workers-types-latest/package/index.d.ts

Documentation de référence

  • references/rules.md — toutes les règles de bonnes pratiques avec exemples de code et anti-patterns
  • references/review.md — validation des types, validation de config, patterns d'accès aux bindings, processus de révision

Référence rapide des règles

Configuration

Règle Résumé
Compatibility date Définissez compatibility_date à aujourd'hui sur les nouveaux projets ; mettez à jour périodiquement sur les projets existants
nodejs_compat Activez le flag nodejs_compat — de nombreuses bibliothèques dépendent des built-ins Node.js
wrangler types Exécutez wrangler types pour générer Env — ne rédigez jamais manuellement les interfaces de binding
Secrets Utilisez wrangler secret put, ne codez jamais en dur les secrets dans la config ou le code source
wrangler.jsonc Utilisez la config JSONC pour les paramètres non-secrets — les fonctionnalités plus récentes sont JSON uniquement

Gestion des requêtes et réponses

Règle Résumé
Streaming Streamez les payloads volumineux/inconnus — n'attendez jamais response.text() sur des données sans limite
waitUntil Utilisez ctx.waitUntil() pour le travail post-réponse ; ne destructurez pas ctx

Architecture

Règle Résumé
Bindings plutôt que REST Utilisez les bindings en processus (KV, R2, D1, Queues) — pas l'API REST Cloudflare
Queues & Workflows Déplacez le travail asynchrone/en arrière-plan hors du chemin critique
Service bindings Utilisez les service bindings pour les appels Worker-à-Worker — pas HTTP public
Hyperdrive Utilisez toujours Hyperdrive pour les connexions PostgreSQL/MySQL externes

Observabilité

Règle Résumé
Logs & Traces Activez observability dans la config avec head_sampling_rate ; utilisez le logging JSON structuré

Patterns de code

Règle Résumé
Pas d'état global de requête Ne stockez jamais les données scoped à la requête dans des variables au niveau du module
Floating promises Chaque Promise doit être awaitée, returnée, voidée, ou passée à ctx.waitUntil()

Sécurité

Règle Résumé
Web Crypto Utilisez crypto.randomUUID() / crypto.getRandomValues() — jamais Math.random() pour la sécurité
Pas de passThroughOnException Utilisez try/catch explicite avec des réponses d'erreur structurées

Anti-patterns à signaler

Anti-pattern Pourquoi c'est important
await response.text() sur des données sans limite Épuisement mémoire — limite de 128 Mo
Secrets codés en dur dans le code source ou la config Fuite de credentials via le contrôle de version
Math.random() pour des tokens/IDs Prévisible, pas cryptographiquement sûr
fetch() nu sans await ou waitUntil Floating promise — résultat ignoré, erreur avalée
Variables mutables au niveau du module pour l'état de requête Fuite de données entre requêtes, état obsolète, erreurs I/O
API REST Cloudflare depuis l'intérieur d'un Worker Saut réseau inutile, overhead d'auth, latence ajoutée
ctx.passThroughOnException() comme gestion d'erreur Cache les bugs, rend le débogage impossible
Interface Env rédigée manuellement Drifts par rapport aux bindings réels de wrangler config
Comparaison de chaînes directe pour les valeurs secrètes Side-channel timing — utilisez crypto.subtle.timingSafeEqual
Destructuration ctx (const { waitUntil } = ctx) Perd la liaison this — lance "Illegal invocation" à l'exécution
any sur Env ou les paramètres du handler Anéantit la sécurité des types pour tous les accès aux bindings
Double-cast as unknown as T Cache les véritables incompatibilités de type — corrigez la conception
implements sur les classes de base de la plateforme (au lieu de extends) Héritage — perd this.ctx, this.env. S'applique à DurableObject, WorkerEntrypoint, Workflow
env.X à l'intérieur de la classe de base de la plateforme Devrait être this.env.X dans les classes étendant DurableObject, WorkerEntrypoint, etc.

Flux de révision

  1. Récupérez — récupérez la dernière page de bonnes pratiques, les types workers et le schéma wrangler
  2. Lisez les fichiers complets — pas seulement les diffs ; le contexte importe pour les patterns d'accès aux bindings
  3. Vérifiez les types — accès aux bindings, signatures du handler, pas de any, pas de casts non sûrs (voir references/review.md)
  4. Vérifiez la config — compatibility_date, nodejs_compat, observability, secrets, cohérence binding-code
  5. Vérifiez les patterns — streaming, floating promises, état global, limites de sérialisation
  6. Vérifiez la sécurité — utilisation de crypto, gestion des secrets, comparaisons timing-safe, gestion d'erreur
  7. Validez avec les outils — npx tsc --noEmit, lint pour no-floating-promises
  8. Référencez les règles — voir references/rules.md pour le pattern correct de chaque règle

Scope

Cette skill couvre les bonnes pratiques spécifiques à Workers et la révision de code. Pour les sujets connexes :

  • Durable Objects : chargez la skill durable-objects
  • Workflows : voir Rules of Workflows
  • Commandes CLI Wrangler : chargez la skill wrangler

Principes

  • Soyez certain. Récupérez avant de signaler. Si vous êtes incertain à propos d'une API, d'un champ de config ou d'un pattern, récupérez d'abord la documentation.
  • Fournissez des preuves. Référencez les numéros de ligne, la sortie des outils ou les liens de documentation.
  • Concentrez-vous sur ce que les développeurs copieront. Le code Workers dans les exemples et la documentation est collé en production.
  • Exactitude plutôt que complétude. Un exemple concis qui fonctionne vaut mieux qu'un exhaustif avec des erreurs.

Skills similaires

wrangler
cloudflare / skills

Configurer et déployer des Cloudflare Workers via la CLI Wrangler.

1 381
web-perf
cloudflare / skills

1 381