workers-best-practices

Examine et évalue le code Cloudflare Workers par rapport aux meilleures pratiques de production. À charger lors de la rédaction de nouveaux Workers, de l'examen du code Worker, de la configuration de wrangler.jsonc, ou de la vérification des anti-patterns courants des Workers (streaming, floating promises, global state, secrets, bindings, observability). Privilégie la récupération à partir de la documentation Cloudflare par rapport aux 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 par rapport à la pré-formation pour toute tâche de code Workers — écriture ou révision.

Sources de récupération

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

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

PREMIER : Récupérez les références les plus récentes

Avant de réviser ou d'écrire du code Workers, récupérez la page des bonnes pratiques actuelle et les définitions de type pertinentes. Si le node_modules du projet contient une version plus ancienne, privilégiez la version publiée la plus récente.

# 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 des exemples de code et des anti-motifs
  • references/review.md — validation des types, validation de config, motifs d'accès aux bindings, processus de révision

Référence rapide des règles

Configuration

Règle Résumé
Date de compatibilité 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
Types wrangler Exécutez wrangler types pour générer Env — ne rédigez jamais manuellement les interfaces de bindings
Secrets Utilisez wrangler secret put, ne codez jamais les secrets en dur dans la config ou la 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 grandes données/charges inconnues — n'utilisez jamais await response.text() sur des données non bornées
waitUntil Utilisez ctx.waitUntil() pour le travail post-réponse ; ne déstructurez pas ctx

Architecture

Règle Résumé
Bindings plutôt que REST Utilisez les bindings in-process (KV, R2, D1, Queues) — pas l'API REST Cloudflare
Queues & Workflows Déplacez le travail asynchrone/en arrière-plan en dehors du chemin critique
Service bindings Utilisez les service bindings pour les appels Worker-to-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 la journalisation JSON structurée

Motifs de code

Règle Résumé
Pas d'état de requête global Ne stockez jamais les données scoped à la requête dans les variables au niveau du module
Promises flottantes 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-motifs à signaler

Anti-motif Pourquoi c'est important
await response.text() sur des données non bornées Épuisement de mémoire — limite de 128 MB
Secrets codés en dur dans la source ou la config Fuite d'identifiants via le contrôle de version
Math.random() pour les tokens/IDs Prévisible, pas cryptographiquement sécurisé
fetch() nu sans await ou waitUntil Promise flottante — résultat abandonné, erreur avalée
Variables mutables au niveau du module pour l'état de requête Fuites de données entre requêtes, état obsolète, erreurs d'E/S
API REST Cloudflare depuis l'intérieur d'un Worker Saut réseau inutile, surcharge d'auth, latence ajoutée
ctx.passThroughOnException() comme gestion d'erreur Cache les bugs, rend le débogage impossible
Interface Env rédigée à la main Dévie de la configuration wrangler réelle des bindings
Comparaison de chaînes directe pour les valeurs de secret Timing side-channel — utilisez crypto.subtle.timingSafeEqual
Déstructuration de ctx (const { waitUntil } = ctx) Perd la liaison this — lève "Illegal invocation" à l'exécution
any sur Env ou les paramètres du handler Annule la sécurité des types pour tous les accès aux bindings
Double-cast as unknown as T Cache les incompatibilités de type réelles — 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 Doit être this.env.X dans les classes étendant DurableObject, WorkerEntrypoint, etc.

Flux de révision

  1. Récupérez — récupérez la page des bonnes pratiques la plus récente, les types workers et le schéma wrangler
  2. Lisez les fichiers complets — pas seulement les diffs ; le contexte est important pour les motifs 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 motifs — streaming, promises flottantes, é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 motif correct de chaque règle

Portée

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

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

Principes

  • Soyez certain. Récupérez avant de signaler. Si vous ne êtes pas sûr d'une API, d'un champ de config ou d'un motif, 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.
  • Correction plutôt que complétude. Un exemple concis qui fonctionne vaut mieux qu'un complet avec des erreurs.