Aller au contenu

ADR-026 : Nommer les accesseurs de Request par leur source : query et route

Statut

Accepté, Forge 1.0.0-beta.15 (ticket HTTP-REQUEST-PARAM-RENAME-001).

Date

2026-06-07

Contexte

core.http.request.Request expose une famille d'accesseurs de données, nommés par leur source :

Méthode Source
param(key) query string (?clé=)
route_param(key) chemin de l'URL (/article/{id})
form(key) corps de formulaire
json(key) corps JSON
header(name) en-tête HTTP
file(key) fichier téléversé

Deux noms dénotent par rapport au reste de la famille :

  1. param ne nomme pas sa source.
    C'est le seul membre dont le nom est générique : il ne dit pas que la valeur vient de la query string.
    Tous les autres nomment un lieu précis.
  2. route_param est asymétrique avec param (suffixe _param que les autres lecteurs n'ont pas) et un peu imprécis : une route est l'objet complet (méthode + motif + handler), alors que la valeur vient du chemin.

Contraintes établies

  • request.path existe déjà comme attribut (la chaîne du chemin, request.py), convention quasi universelle (Flask, Django, Express).
    Une méthode path() entrerait en collision : le nom nu path est donc exclu.
  • request.query et request.route sont libres (aucun attribut ni méthode existant).
    « route » est déjà le vocabulaire de Forge (route_param, router.group, starters *-route).
  • Phase bêta pré-1.0 : une rupture interne de l'API se fait sans alias ni dépréciation (convention de CLAUDE.md).
    C'est la fenêtre idéale ; après le tag 1.0 stable, ce renommage serait beaucoup plus coûteux.

Décision

  1. D1 : Request.param est renommé Request.query (lit la query string).
  2. D2 : Request.route_param est renommé Request.route (lit un paramètre du chemin de route dynamique).
  3. D3 : les autres accesseurs (form, json, header, file) sont déjà nommés par leur source et ne changent pas.
  4. D4 : pas d'alias de compatibilité (rupture franche, pré-1.0).
    Tous les appels sont migrés dans le même chantier : core, starters, tutoriel welcome-forge, tests, faux objets de test, contrat public 1.0, doc HTTP.

La paire obtenue est nue, brève, symétrique et nomme la source : query / route / form / json / header / file.

Conséquences

Positives

  • Chaque accesseur nomme d'où vient la donnée (charte §3 : refuser la magie cachée ; §11 : une seule façon claire).
    request.query("name") et request.route("id") se lisent sans connaître de convention implicite.
  • Symétrie de la famille restaurée, sans collision avec request.path.

Limites / Risques

  • Rupture de l'API publique du core : tout appel request.param(...) / request.route_param(...) doit être migré (aucun alias).
  • Les attributs internes self.params (dict query) et self.route_params (dict chemin), ainsi que les clés "params" / "route_params" de request.data (visibles via Response.debug), restent inchangés : hors périmètre de ce renommage de méthodes.

Alternatives écartées

A : query_param / path_param

Terminologie HTTP standard et symétrique, mais suffixée alors que le reste de la famille est nu (form, json, header, file).
Plus verbeuse sans gain de clarté décisif.
query / route est plus léger et cohérent avec le vocabulaire Forge.

B : query / path

Le plus court, mais path entre en collision avec l'attribut existant request.path (la chaîne du chemin).
Libérer path() exigerait de renommer cet attribut conventionnel, rupture plus large et sémantiquement trouble (« path » le chemin vs « path('id') » un paramètre).
Écarté.

C : query / dynamic

dynamic est libre et fait écho au starter « dynamic-route », mais il nomme une caractéristique (le segment est variable), pas une source (le chemin), contredisant le critère retenu.
Écarté.

Hors périmètre de cet ADR

  • Les attributs self.params / self.route_params et les clés de request.data ("params", "route_params").
  • Les autres accesseurs (form, json, header, file), déjà conformes.

Référence

  • Ticket d'implémentation : HTTP-REQUEST-PARAM-RENAME-001.
  • Code concerné : core/http/request.py (query, route), tous les appelants (starters, docs/starters/welcome-forge/, tests, tests/fake_request.py), docs/reference/http.md, docs/reference/public-contract-1.0.md.
  • ADR-003 Convention de langue (API en anglais) : docs/adr/003-language-convention.md.
  • Charte : CHARTE_DOC.md (principes 3, 10, 11).