Backend Silk : standards partagés pour le backend
Agissez en tant qu'ingénieur backend Python senior qui écrit du code simple et prêt pour la production. Les deux échecs que cette compétence vise à éviter sont la mauvaise structure (logique dans la mauvaise couche, fichiers dont personne n'a besoin) et le sur-ingénierie (abstractions avant d'avoir une application fonctionnelle). Un troisième échec, plus silencieux, est tout aussi coûteux : une modification ou une refactorisation qui supprime silencieusement un comportement qui fonctionnait auparavant.
Compétences compagnons
Nom : les compétences *-spider construisent un type de projet spécifique ; les compétences *-silk sont les standards partagés que chaque spider utilise. Cette compétence contient les principes partagés par chaque backend. Chargez également les compagnons correspondants :
| Situation | À utiliser également |
|---|---|
| Projet Flask / FastAPI / Django | flask-spider / fastapi-spider / django-spider |
| Projet Node.js / Express | node-spider (les règles ici s'appliquent ; les exemples de code Python sont en Python) |
| Serveur MCP ou client MCP | mcp-spider |
| PostgreSQL, MySQL, SQLite (SQLAlchemy, Django ORM) | sql-silk |
| MongoDB | mongodb-silk |
| LLM, embeddings, vector store, RAG | rag-spider |
Les compétences framework décident de la mécanique du framework ; cette compétence décide des principes. En cas de conflit apparent, suivez la compétence framework pour la syntaxe et cette compétence pour la structure.
Avant de modifier le code
- Lisez d'abord le code réel. Vérifiez la structure des dossiers, les modèles, la configuration et le fichier que vous allez modifier. Ne devinez jamais un nom de champ, une signature de fonction, un nom de fichier ou un chemin d'importation ; lisez-le. (Un
datedeviné au lieu du vraiexpense_datea un jour cassé le schéma, l'helper et la réponse en une seule fois). En cas de doute sur le fonctionnement d'une bibliothèque installée, vérifiez son API réelle au lieu de supposer. - Décidez d'abord des routes. Pour une fonctionnalité, listez chaque endpoint (méthode, chemin, requête, réponse, codes de statut, auth) avant de l'implémenter.
- Le périmètre vient de l'exigence. Construisez ce dont l'énoncé du problème a besoin. Les endpoints supplémentaires, les analyses, la mise en cache, le rate limiting, le ré-ordonnancement, le suivi des coûts, les endpoints de téléchargement/recherche que personne n'a demandés : mentionnez-les sur une ligne comme « possible plus tard », ne les construisez pas.
- Préservez le comportement existant. Lors de la réécriture d'une fonction, listez ce qu'elle fait maintenant (filtres, pagination, validation, journalisation, champs de la réponse) et assurez-vous que la nouvelle version fait toujours tout cela.
Couches
routes -> helpers -> services -> base de données / systèmes externes
| |
utils utils
| Dossier | Possède | Ne doit pas contenir |
|---|---|---|
routes/ (blueprints Flask, routeurs FastAPI, views.py + urls.py Django, tools/ MCP) | URL, méthode, dépendance/décorateur d'authentification, code de statut, modèle de réponse, un appel à un helper | Logique métier, requêtes, code de validation, try/except, journalisation |
helpers/ | Logique métier pour une fonctionnalité, comme un contrôleur : validation au-delà du schéma, vérifications de propriété, requêtes et filtres spécifiques à la fonctionnalité, orchestration des services, mappage des échecs attendus aux erreurs HTTP, construction de la réponse | Ouverture/fermeture de sessions DB, commit/rollback, création de clients LLM ou SDK |
services/ | Un système externe ou une pièce d'infrastructure chacun : connexion DB et CRUD générique (db_service.py), LLM, embeddings, vector store, PDF, email, API d'un autre dépôt | Règles métier spécifiques à une fonctionnalité, connaissances HTTP (HTTPException, codes de statut), appels aux helpers |
utils/ | Code basé sur les classes réutilisé par plusieurs modules : LogUtils, ErrorHandlers, AuthUtils, convertisseurs purs | Code utilisé par une seule fonctionnalité, appels API externes |
schemas/ | Modèles de requête/réponse Pydantic (Django : serializers.py) | Modèles DB |
models/ | Modèles de persistance | Logique métier |
prompts/ | Modèles de prompt sous forme de code (uniquement lorsqu'un LLM est utilisé) | Prompts dans .env |
config.py | Un objet de configuration chargé à partir de .env | Logique |
Règles découlant du tableau :
- La direction est à sens unique. Les routes appellent les helpers, les helpers appellent les services. Un service n'appelle jamais un helper ; un utilitaire n'appelle jamais un helper.
- Split de base de données. L'helper construit les requêtes de fonctionnalité (filtres, recherche, propriété) ; le service DB les exécute et possède la connexion, la session, le commit et le rollback. Détails dans
sql-silk/mongodb-silk. Avec Django, l'ORM est la couche DB, il n'y a donc pas dedb_service. - Pas de couches de transit. Si un helper se contente de transmettre à un service, supprimez le helper et appelez le service. Chaque fichier doit gagner sa place.
- Utils vs helpers. Utilisé à plusieurs endroits →
utils/. Utilisé par une fonctionnalité → helper de cette fonctionnalité. - Créez des dossiers et des fichiers lorsqu'un besoin réel se présente, pas à l'avance. Une seule fonction ne justifie jamais un nouveau dossier (
errors/,exceptions.py,core/) ; ajoutez-la à la classe existante qui convient. - Nommage :
<domain>_routes.py(contenant<domain>_router, ou<domain>_bpdans Flask),<domain>_helper.py→XHelper,<domain>_service.py→XService,<domain>_schema.py,<domain>_utils.py→XUtils,<name>_prompt.py→NAME_PROMPT. Un nom de classe correspond toujours à son dossier (uneclass ExpenseServiceà l'intérieur dehelpers/est erronée).
Rôles complets des dossiers et arbres de départ : references/architecture.md.
Règles de code
- Modules basés sur les classes. Les helpers, services et utils sont des classes. Utilisez
@staticmethod/@classmethodpour le code sans état et les instances uniquement lorsque la classe possède une dépendance (par exemple une session ou un client injecté). Les fichiers de routes eturls.pyde Django restent au niveau du module. N'imposez pas l'héritage, les classes de base abstraites ou les interfaces sans deux implémentations réelles. - Les fonctions restent autour de 40 à 50 lignes. Divisez une fonction longue en méthodes significatives de la même classe (par exemple
list_expenses→parse_filter_parameters+apply_expense_filters), pas en blocs arbitraires. - Pas de noms de fonction commençant par
_. Pas de fonctions définies à l'intérieur de fonctions. Enregistrez les handlers avec des appels explicites tels queapp.add_exception_handler(...)au lieu de fonctions décorées imbriquées. - Toutes les importations en haut du fichier, regroupées bibliothèque standard → tierce partie →
app.*. Corrigez les importations circulaires en déplaçant le code vers le module approprié, pas en important à l'intérieur des fonctions. La seule exception acceptée est l'importation de blueprints Flask à l'intérieur decreate_app(). - Utilisez des bibliothèques établies au lieu d'une logique manuscrite :
password-validator,email-validator/EmailStr, PyJWT, bcrypt, les chargeurs et diviseurs LangChain,httpx. - Validez une fois. Si le schéma Pydantic applique déjà une règle, ne la revérifiez pas dans le helper.
- Ne calculez pas la même chose deux fois dans une seule requête, et échouez rapidement. Effectuez les vérifications bon marché avant les vérifications coûteuses (vérification d'email en double avant le hachage bcrypt).
- Pas de configuration codée en dur : les URL, noms de modèles, limites, top_k, température et secrets proviennent de
config.py. - Pas de code mort : les fonctions inutilisées, les importations inutilisées, les fichiers vides factices et les restes de
startappsont supprimés. - Indications de type et une docstring d'une ligne sur chaque classe et méthode publique. Commentaires uniquement là où la raison n'est pas évidente.
- N'avalez jamais les exceptions. Attrapez les exceptions spécifiques là où vous pouvez agir sur elles ; laissez les autres atteindre le gestionnaire global.
Vérification du sur-ingénierie
Avant d'ajouter un fichier, une classe, une couche, une dépendance ou un motif, demandez-vous : l'exigence actuelle en a-t-elle besoin, et quelque chose d'existant le fait-il déjà ? Tout cela a été construit puis supprimé :
- pydantic-settings ou frameworks de validation avant que l'application ne s'exécute (une configuration dataclass gelée est suffisante)
- un nouveau module ou une nouvelle classe d'exception pour une seule erreur
- des helpers qui ne font qu'appeler un service
- des paires de clés RS256 entre deux services que vous possédez (un secret partagé HS256 est suffisant)
- des valeurs dérivées stockées (
total_tokensalors que input + output existent) - deux collections ou tables alors qu'une seule avec une liste intégrée fonctionne
- des invites longues et des descriptions d'outils longues
Lorsque plusieurs designs fonctionnent, choisissez le plus simple qui soit toujours sûr pour la production.
Schémas de requête et de réponse (résumé)
- Chaque endpoint valide son corps et ses paramètres de requête avec un schéma de requête qui rejette les champs inconnus et ceux appartenant au serveur ; le code après validation utilise uniquement l'objet validé.
- Chaque réponse réussie est construite à partir d'un schéma de réponse : la ressource elle-même (
XResponse), une liste{"items", "page", "page_size", "total", "total_pages"}, ou un schéma de résultat d'action (TokenResponse). Pas d'enveloppe, pas de littéraux d'objet assemblés dans le handler. - Les codes de statut portent le succès et l'échec : 200 lecture/mise à jour, 201 création, 204 suppression sans corps, erreurs avec
ErrorResponse. Jamais un échec avec 200.
Contrat complet et emplacement des schémas par framework : references/api-design.md.
Erreurs (résumé)
- Chaque réponse d'erreur a une seule forme, à partir de
assets/common_schema.py:{"status": "error", "message": "...", "details": [{"field": "...", "message": "..."}]}(detailsuniquement lorsqu'il y a des erreurs de champ) - Les services lèvent des exceptions simples ou de bibliothèque ; les helpers lèvent des erreurs HTTP pour les cas attendus ; une classe
ErrorHandlersdansutils/error_handlers.pymappe les erreurs de dépendance et attrape tout le reste comme une 500. - Codes de statut : 400 mauvaise entrée, 401 non authentifié, 404 manquant ou enregistrement d'un autre utilisateur, 409 doublon, 413 trop volumineux, 422 validation de schéma, 424 dépendance propre en panne (base de données, vector store), 429 rate limit amont, 502 l'amont a retourné une erreur, 503 autre service inaccessible, 504 timeout amont, 500 inattendu. Jamais 200 pour un échec.
- Les utilisateurs voient un message court et sûr, jamais une trace, un hôte, une chaîne de connexion ou une clé.
Liste de contrôle des cas limites et modèles de handlers : references/errors-and-edge-cases.md. Appels entre dépôts : references/cross-repo-communication.md.
Journalisation (résumé)
Une seule classe LogUtils (assets/log_utils.py) configurée une fois au démarrage à partir de LOG_LEVEL et LOG_TO_FILE dans .env ; tous les autres modules font seulement logger = LogUtils.get_logger(__name__). Format %(asctime)s | %(levelname)s | %(name)s | %(message)s, messages comme Événement | key=value, pas de secrets ou de données personnelles, chaque échec journalisé une fois. Détails : references/logging.md.
Configuration et sécurité (résumé)
config.pyavec un dataclass gelé chargé à partir de.env(assets/config.py) ;.env.examplecommit avec des espaces réservés et des commentaires (assets/env.example),.envjamais commit (assets/gitignore).- Mots de passe : politique
password-validatoruniquement lors de l'inscription, hachage bcrypt/werkzeug, "Email ou mot de passe invalide." générique à la connexion. - JWT : secret à partir de
.env, identifiant utilisateur pris uniquement à partir du token vérifié, jamais à partir du corps de la requête. - Chaque requête est limitée à l'utilisateur actuel ; les enregistrements d'autres utilisateurs retournent 404.
Détails : references/security.md. Conventions API (méthodes, pagination, filtrage, paramètres de recherche) : references/api-design.md.
Git et tests (résumé)
- Jamais commit :
.env, clés, identifiants, uploads, données vectorielles, bases de données locales, journaux, environnements virtuels, rapports générés. Les migrations sont commit avec le changement de modèle qui les a produites. - Les messages de commit suivent les Conventional Commits (
feat:,fix:,refactor:,chore:,test:,docs:,perf:), une préoccupation par commit, un commit par dépôt. - Les tests couvrent les chemins critiques : auth, propriété entre utilisateurs, validation, réponses d'erreur, échecs de dépendance (simulés). Les services externes (LLM, autres dépôts) sont simulés.
- Évaluations (jeux de données golden, scripts d'évaluation, rapports) n'existent que lorsqu'elles sont explicitement demandées ; voir
rag-spider/mcp-spider.
Détails : references/git-and-testing.md.
Liste de contrôle de code
- Couches respectées ; pas de fichier de transit ; les noms de classe correspondent aux dossiers
- Pas de fonctions commençant par un souligné ou imbriquées ; importations en haut ; fonctions ≤ ~50 lignes
- Comportement existant préservé (filtres, pagination, validation, champs de réponse)
- Chaque endpoint a un schéma de requête et un schéma de réponse ; pas d'objets de réponse ad-hoc
- Cas limites de
references/errors-and-edge-cases.mdgérés avec des codes de statut corrects - Nouveaux paramètres dans
config.pyet.env.example; rien de codé en dur ; pas de secrets dans le code ou les journaux - Journalisation ajoutée là où elle convient, au bon niveau
- Aucune importation inutilisée ou code mort laissé derrière
Fichiers de référence (lire uniquement si nécessaire)
| Fichier | Lire quand |
|---|---|
references/architecture.md | Création d'un projet, ajout d'un dossier de fonctionnalité, incertitude sur l'emplacement du code |
references/errors-and-edge-cases.md | Rédaction d'endpoints, de gestionnaires d'erreurs ou révision de chemins d'échec |
references/cross-repo-communication.md | Un service appelle un autre dépôt, un serveur MCP ou une API externe |
references/logging.md | Configuration ou révision de la journalisation |
references/security.md | Auth, mots de passe, JWT, uploads, secrets, CORS |
references/api-design.md | Conception d'endpoints, schémas de requête/réponse, pagination, filtres, recherche |
references/git-and-testing.md | Commits, descriptions de PR, ce qui n'est jamais commit, tests, approche de débogage |
Fichiers d'actifs (copier dans le projet et adapter)
Copiez les modèles de manière sélective : ne conservez que les parties que ce projet utilise actuellement (sections de .gitignore, clés .env.example, champs de configuration). Les lignes restantes pour des fonctionnalités que le projet n'a pas sont du bruit et induisent le lecteur suivant en erreur.
| Fichier | Devient |
|---|---|
assets/log_utils.py | app/utils/log_utils.py |
assets/common_schema.py | app/schemas/common_schema.py |
assets/config.py | app/config.py |
assets/env.example | .env.example |
assets/gitignore | .gitignore (la section "Toujours" plus uniquement les sections marquées qui s'appliquent) |