DEV Community: Rodolphe D.

Pourquoi ton code n'a pas besoin d'aller sur la Lune (KISS)

Rodolphe D. — Wed, 30 Sep 2026 11:58:22 +0000

TL;DR

Mes factures ont 3 statuts (draft, pending, paid) et 2 transitions possibles. J'ai quand même écrit une machine à états avec classes abstraites, factory, registre de guards et bus d'événements : 5 fichiers, ~150 lignes. KISS, c'est : "la solution la plus simple qui résout le problème d'aujourd'hui gagne." On remplace tout ça par un type, deux méthodes et une ligne de Vue.

Dans l'Invoice App, une facture a une vie très simple. Elle naît en brouillon (draft), on l'envoie (pending), le client paie (paid). Fin. Trois statuts, deux flèches :

stateDiagram-v2
  direction LR
  draft --> pending : Save & Send
  pending --> paid : Mark as Paid

Sauf que la semaine dernière, j'étais encore tout fier de mon refactor DRY. J'avais goûté à l'abstraction, et comme tout débutant qui vient de découvrir un marteau, je voyais des clous partout.

Alors je me suis dit : "Un changement de statut, c'est une machine à états. Les vrais devs font des machines à états." Trois heures plus tard, j'avais une classe abstraite, trois classes concrètes, une factory, un registre de guards, des hooks onEnter / onExit et un système d'événements.

Pour faire passer un booléen déguisé de pending à paid.

Bienvenue dans le syndrome de l'architecte en herbe : ce moment où ton code est prêt pour la NASA, alors que ton problème tient sur un Post-it.

Imagine que tu veux allumer la lumière de ta cuisine. Tu as deux options.

Option A : un interrupteur. Clic, lumière.

Option B : une machine de Rube Goldberg. Une bille dévale une rampe, fait tomber un domino, qui tire une ficelle, qui lève un levier, qui appuie sur l'interrupteur. C'est impressionnant. Tes amis filment. Et le jour où la lumière ne s'allume pas, tu passes vingt minutes à chercher quel domino est tombé de travers.

KISS (Keep It Simple, Stupid), c'est choisir l'interrupteur. Pas parce que la machine est "mal", mais parce que ton problème, c'est d'allumer une lumière, pas de gagner un concours d'ingéniosité.

Le "stupid" ne vise pas toi. Il vise le code : un code bête est un code que n'importe qui comprend en 30 secondes, y compris toi à 2h du matin quand la prod est en feu.

Le code "avant" (le péché)

Je t'épargne la totalité. Voici juste les morceaux les plus gênants, répartis dans un dossier app/state_machine/ créé spécialement pour l'occasion.

La classe abstraite, parce qu'on ne sait jamais :

// app/state_machine/invoice_state.ts
export type InvoiceStatusName = 'draft' | 'pending' | 'paid'

export abstract class InvoiceState {
  constructor(protected machine: InvoiceStateMachine) {}

  abstract get name(): InvoiceStatusName
  abstract allowedTransitions(): InvoiceStatusName[]

  async onEnter(): Promise<void> {}
  async onExit(): Promise<void> {}

  canTransitionTo(target: InvoiceStatusName) {
    return this.allowedTransitions().includes(target)
  }
}

export class DraftState extends InvoiceState {
  get name() { return 'draft' as const }
  allowedTransitions() { return ['pending' as const] }
}

export class PendingState extends InvoiceState {
  get name() { return 'pending' as const }
  allowedTransitions() { return ['paid' as const] }
  async onEnter() { this.machine.emit('invoice:sent', this.machine.invoice) }
}

export class PaidState extends InvoiceState {
  get name() { return 'paid' as const }
  allowedTransitions() { return [] }
  async onEnter() { this.machine.emit('invoice:paid', this.machine.invoice) }
}

La factory, pour fabriquer les états (tous les trois) :

// app/state_machine/invoice_state_factory.ts
export class InvoiceStateFactory {
  private registry = new Map<InvoiceStatusName, new (m: InvoiceStateMachine) => InvoiceState>([
    ['draft', DraftState],
    ['pending', PendingState],
    ['paid', PaidState],
  ])

  create(name: InvoiceStatusName, machine: InvoiceStateMachine) {
    const StateClass = this.registry.get(name)
    if (!StateClass) throw new Error(`Unknown state: ${name}`)
    return new StateClass(machine)
  }
}

La machine, avec son petit bus d'événements maison que personne n'écoute :

// app/state_machine/invoice_state_machine.ts
export class InvoiceStateMachine {
  private current: InvoiceState
  private listeners = new Map<string, Array<(invoice: Invoice) => void>>()

  constructor(
    public invoice: Invoice,
    private factory: InvoiceStateFactory,
    private guards: TransitionGuardRegistry
  ) {
    this.current = this.factory.create(invoice.status, this)
  }

  async transitionTo(target: InvoiceStatusName) {
    if (!this.current.canTransitionTo(target)) {
      throw new Error(`Transition ${this.current.name} -> ${target} interdite`)
    }
    await this.guards.check(this.current.name, target, this.invoice)
    await this.current.onExit()
    this.current = this.factory.create(target, this)
    this.invoice.status = target
    await this.current.onEnter()
  }

  on(event: string, cb: (invoice: Invoice) => void) { /* ... */ }
  emit(event: string, invoice: Invoice) { /* ... */ }
}

Et enfin, le controller, qui doit maintenant assembler tout ce petit monde :

// app/controllers/invoices_controller.ts
async markAsPaid({ params, response }: HttpContext) {
  const invoice = await Invoice.findOrFail(params.id)
  const machine = new InvoiceStateMachine(
    invoice,
    new InvoiceStateFactory(),
    new TransitionGuardRegistry()
  )
  await machine.transitionTo('paid')
  await invoice.save()
  return response.redirect().back()
}

Faisons les comptes : 5 fichiers, une centaine et demie de lignes, trois design patterns. Le registre de guards ne contient aucun guard. Les événements invoice:sent et invoice:paid ne sont écoutés par personne. Et pour comprendre "est-ce qu'une facture payée peut redevenir brouillon ?", il faut ouvrir trois fichiers.

La réponse tient pourtant en un mot : non.

Le refactor "après" (la rédemption)

Étape 1 — on rm -rf app/state_machine/. Honnêtement, c'était l'étape la plus satisfaisante.

Étape 2 — le statut devient un simple type sur le modèle, et les règles deviennent deux méthodes qui disent exactement ce qu'elles font :

// app/models/invoice.ts
import { Exception } from '@adonisjs/core/exceptions'

export type InvoiceStatus = 'draft' | 'pending' | 'paid'

export default class Invoice extends BaseModel {
  @column()
  declare status: InvoiceStatus

  @computed()
  get isEditable() {
    return this.status !== 'paid'
  }

  send() {
    if (this.status !== 'draft') {
      throw new Exception('Seul un brouillon peut être envoyé', { status: 422 })
    }
    this.status = 'pending'
  }

  markAsPaid() {
    if (this.status !== 'pending') {
      throw new Exception('Seule une facture en attente peut être payée', { status: 422 })
    }
    this.status = 'paid'
  }
}

Toute la "machine à états" est là, lisible en un coup d'œil. Une facture payée peut-elle redevenir brouillon ? Aucune méthode ne le permet. Réponse en 5 secondes, un seul fichier ouvert.

Étape 3 — le controller redevient un controller :

// app/controllers/invoices_controller.ts
async markAsPaid({ params, response }: HttpContext) {
  const invoice = await Invoice.findOrFail(params.id)
  invoice.markAsPaid()
  await invoice.save()
  return response.redirect().back()
}

// start/routes.ts
router.patch('/invoices/:id/pay', [InvoicesController, 'markAsPaid'])

Étape 4 — côté Vue, le bouton "Mark as Paid" du design Frontend Mentor n'apparaît que quand il a un sens :

<script setup lang="ts">
import { router } from '@inertiajs/vue3'

const props = defineProps<{ invoice: Invoice }>()

const markAsPaid = () => router.patch(`/invoices/${props.invoice.id}/pay`)
</script>

<template>
  <button v-if="invoice.isEditable">Edit</button>
  <button v-if="invoice.status === 'pending'" @click="markAsPaid">
    Mark as Paid
  </button>
</template>

💡 Petit détail Adonis au passage : sans le décorateur @computed(), un getter n'est pas sérialisé, donc isEditable n'arriverait jamais dans tes props Inertia.

Bilan : de 5 fichiers et ~150 lignes à une vingtaine de lignes dans le modèle. Même comportement, mêmes garde-fous, zéro domino.

Le piège à éviter (petite mise en garde)

KISS ne veut pas dire "simpliste", ni "les machines à états c'est mal." Le jour où mes factures auront 8 statuts (overdue, partially_paid, refunded, cancelled...), des transitions qui déclenchent des emails, des webhooks Stripe et des règles métier croisées, une vraie machine à états (ou une lib comme XState) deviendra la solution simple. À ce moment-là, ce sont mes if imbriqués qui seront la machine de Rube Goldberg.

La question à se poser n'est pas "quelle est la solution la plus élégante ?" mais "quelle est la solution la plus simple qui résout le problème que j'ai vraiment, là, maintenant ?" Et ce "maintenant" est justement le sujet de la semaine prochaine.

La semaine prochaine, Partie 3 : YAGNI. Ou comment j'ai passé un week-end entier à rendre l'appli multi-devises, multi-langues et compatible export comptable... pour une appli de factures dont le seul utilisateur, c'est moi. Spoiler : je facture toujours en euros.

Build One Ugly System. It'll Teach You More Than 10 Tutorials.

Rodolphe D. — Wed, 30 Sep 2026 08:43:57 +0000

TL;DR: Tutorials can't teach judgment because they never let you be wrong about something that matters. The fix isn't more courses — it's building one small, ugly system where your mistakes have consequences.

I want to tell you about the night I wasted four hours on a bug.

It was a race condition in a queue I'd written. The code looked fine. Tests passed. Then in production, every few hours, a job would run twice. I pasted a fix from Stack Overflow. It stopped. I still don't fully know why it worked.

That night taught me more than any tutorial I'd done — not because I learned about race conditions, but because I learned I didn't understand the thing I'd built.

What "System" Actually Means

People say "build systems" like it's a magic spell. For a long time, I said it too without knowing what I meant. Let's fix that.

A system is a set of things that depend on each other. That's it. That's the whole definition.

A pile of bricks isn't a system. A wall is. Pull one brick and something else moves — or the whole thing falls. That's the difference. Not size. Not complexity. Consequences.

I didn't get this for two years. I thought "system" meant "big project" or "architecture." It doesn't. It means: things you can be wrong about.

Here's a task:

function sendEmail(user) {
  return mailer.send(user.email, "Welcome");
}

Here's a system:

async function sendEmail(user, attempt = 1) {
  try {
    return await mailer.send(user.email, "Welcome");
  } catch (err) {
    if (attempt >= 3) {
      await queue.deadLetter({ user, err });
      return;
    }
    await wait(2 ** attempt * 1000);
    return sendEmail(user, attempt + 1);
  }
}

The first one assumes email always works. The second one assumes email fails — and that you don't know when, or why, or how many times.

That's the difference. The first is a task. The second is a claim about the world you'll have to defend.

And here's the thing: even the second version is wrong. It assumes that if mailer.send throws, the email wasn't sent. But a timeout can fire after the mail server already accepted the message. Retry, and your user gets two welcome emails.

Sound familiar? A job running twice. Same bug as my queue, different costume.

The usual fix is to make the operation idempotent — for example, an idempotency key your provider can use to deduplicate. But the fix isn't the point. The point is that I wrote that "robust" version, felt good about it, and it was still making a claim reality could break.

Every line of code you write is that kind of claim. "This user will always have an email." "This queue will never grow past X." "This function never gets called twice." Reality either agrees with you or it doesn't.

A tutorial hides that. A tutorial made all the claims for you, and quietly cleaned up the ones that were wrong.

A system hides nothing. That's the whole point.

Why Tutorials Can't Fix This

There are three classic ways developers stay stuck. You've probably heard them framed as discipline problems: stop copy-pasting, stop course-hopping, stop being scared of real code. Just try harder.

Seen through the lens above, they look different. They're not discipline problems. They're design problems — each one is a way of never having to be wrong.

🚫 Trap 1: Blind Copy-Paste

You paste code you don't understand. AI makes this easier. You accept the suggestion, it works, you move on.

That's exactly what I did with my queue. The bug went away, and I walked off without knowing which of my claims had been false. The fix worked; I didn't learn.

The fix: treat every AI output — and every Stack Overflow answer — like a code review. "Why is this here? What breaks if I remove it?" If you can't answer, don't use it yet. Notice why this works: you're forcing yourself to see the claims hidden in the code. That's system thinking. You're doing it in your head instead of in a repo.

🚫 Trap 2: Disguised Tutorial Hell

You jump from course to course and feel like you're learning. But someone else made all the hard calls.

The fix: build something nobody asked you to build. Not a Twitter clone. Something that solves a real problem for you — a script that cleans your logs, a CLI for a boring workflow. The point isn't complexity. It's that you have to make calls with no safety net.

🚫 Trap 3: Fear of the Real Codebase

Blank project? Fine. Existing 50,000-line codebase? Panic.

The fix: read code you didn't write. Follow one request end-to-end. Learn the debugger — console.log is fine, but it shouldn't be your only tool. A real codebase is just a pile of claims other people made. Reading it is how you learn which ones held up, which ones didn't, and why.

Notice what all three fixes have in common: you're the one who has to be wrong. That's the only thing that grows judgment. Not knowing more. Being wrong more, in places where it counts, and paying attention.

Why Bother

Because your head can't hold everything. A system is a thought you wrote down so you could check it later.

The first time something you built breaks for a reason you didn't predict — that's not failure. That's data. The only kind that makes you better.

Judgment Beats Speed

With AI writing more of the code, typing speed matters less every month. What still matters is being the person who can say: "We shouldn't build it this way. Here's why."

That judgment doesn't come from a tutorial. It comes from owning your mistakes and deciding under uncertainty. It's uncomfortable. It's also the only path.

My queue was my first ugly system. It broke, I patched it without understanding it, and that gap is exactly what I'm asking you not to leave behind.

So next time you're staring at a blank screen: that's where the learning starts. Don't run to another tutorial. Stay. Break it down. Search. Fail. Try again.

And when it works — build the next ugly thing.

💬 If you read this, do one thing: reply with the last thing you built that broke in a way you didn't expect. Not the fix. Just what broke. I'll answer every comment for the next 48 hours.

Building a Choose-Your-Own-Adventure API with NestJS — Part 4: Auth

Rodolphe D. — Wed, 30 Sep 2026 05:43:09 +0000

Part 4 of the Grimoire API series. So far: a validated endpoint (Part 1), persistence (Part 2), and the actual XP/badge rules (Part 3) — all running against one hardcoded "default player." This post finally gets rid of that placeholder.

Retiring `DEFAULT_PLAYER_ID`

Since Part 2, every POST /progress/choice call has quietly advanced the same fake user. It was a deliberate shortcut to build persistence and game logic without also building login at the same time — but it can't last. This milestone adds real accounts, and every progress endpoint gets scoped to whoever is actually authenticated.

Two new pieces: Passport and Guards

NestJS doesn't reinvent authentication — it wraps Passport, the well-established Node auth library, behind its own decorators. Two Passport strategies cover what this project needs:

Local strategy — email + password, used once, at login, to issue a token
JWT strategy — validates a bearer token on every subsequent request

A Guard is what actually blocks a request before it reaches a controller method, if authentication fails:

// src/auth/jwt-auth.guard.ts
import { Injectable } from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';

@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {}

Barely any code — AuthGuard('jwt') from @nestjs/passport does the real work; this class just names which strategy to use.

Hashing passwords

Never store a plain password. bcrypt handles hashing on sign-up and comparison on login:

// src/auth/auth.service.ts
import { Injectable, UnauthorizedException } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { JwtService } from '@nestjs/jwt';
import * as bcrypt from 'bcrypt';
import { User } from '../users/entities/user.entity';

@Injectable()
export class AuthService {
  constructor(
    @InjectRepository(User) private readonly userRepo: Repository<User>,
    private readonly jwtService: JwtService,
  ) {}

  async register(email: string, password: string): Promise<User> {
    const passwordHash = await bcrypt.hash(password, 10);
    return this.userRepo.save(this.userRepo.create({ email, passwordHash }));
  }

  async login(email: string, password: string): Promise<{ accessToken: string }> {
    const user = await this.userRepo.findOneBy({ email });
    const valid = user && (await bcrypt.compare(password, user.passwordHash));

    if (!valid) {
      throw new UnauthorizedException('Invalid credentials');
    }

    return { accessToken: this.jwtService.sign({ sub: user.id }) };
  }
}

The 10 in bcrypt.hash(password, 10) is the cost factor — how many rounds of hashing, trading speed for resistance to brute-force attempts. 10 is a reasonable default for a learning project; production tuning is its own topic.

Note the deliberately vague error: 'Invalid credentials' regardless of whether the email doesn't exist or the password is wrong. Being specific ("no such email") tells an attacker which emails are registered — a small leak, but a real one.

The JWT strategy

// src/auth/jwt.strategy.ts
import { Injectable } from '@nestjs/common';
import { PassportStrategy } from '@nestjs/passport';
import { ExtractJwt, Strategy } from 'passport-jwt';

@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy) {
  constructor() {
    super({
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      secretOrKey: process.env.JWT_SECRET,
    });
  }

  async validate(payload: { sub: string }) {
    return { id: payload.sub };
  }
}

Whatever validate() returns becomes request.user on every guarded request. Here it's deliberately minimal — just the user ID from the token's sub claim — because that's all the rest of the app actually needs.

A custom decorator: `@CurrentUser()`

Reaching into request.user by hand in every controller gets repetitive fast. NestJS lets you wrap that pattern in your own decorator:

// src/auth/current-user.decorator.ts
import { createParamDecorator, ExecutionContext } from '@nestjs/common';

export const CurrentUser = createParamDecorator(
  (_data: unknown, ctx: ExecutionContext) => {
    return ctx.switchToHttp().getRequest().user;
  },
);

And now the progress controller from Part 2 loses its placeholder for good:

@UseGuards(JwtAuthGuard)
@Post('choice')
async advance(@CurrentUser() user: { id: string }, @Body() dto: AdvanceProgressDto) {
  return this.progressService.advance(user.id, dto.nextPageId);
}

@UseGuards(JwtAuthGuard) rejects the request with a 401 before the method body ever runs if the token is missing or invalid — the same "reject before your code even sees it" pattern as the ValidationPipe from Part 1, just guarding who instead of what shape of data.

Where I expect to get stuck

I haven't built this milestone yet, but I can already name the likely trap from experience reading about it: forgetting that @Injectable() services created per request (none of mine are, so far) behave differently from the request-scoped nature of request.user. As long as CurrentUser stays a decorator that reads straight from the request object — rather than something cached on a singleton service — this should be a non-issue. Worth double-checking once real tests are in place, in Part 5.

What's next

Every meaningful endpoint is now behind a real login. Part 5 closes the loop on quality: a proper test suite for the XP/badge logic, a global exception filter so error responses are consistent everywhere, and a look at Pipes and Interceptors beyond the validation pipe from Part 1.

Building a Choose-Your-Own-Adventure API with NestJS — Part 3: Game Logic

Rodolphe D. — Wed, 23 Sep 2026 09:32:54 +0000

Part 3 of the Grimoire API series. Part 1 built a validated read-only endpoint, Part 2 added persistence with TypeORM. Now: the actual gamification — XP, levels, and badges.

Where the rules were hiding

Up to this point, choices in the story JSON already carried an xpReward and an optional badgeUnlocked — the data was there since Part 1. What wasn't there was anything that did something with it. ProgressService.advance() just moved the player to the next page; it never looked at the reward attached to the choice they made.

This milestone is about extracting that behavior into its own services, instead of bolting more if statements onto ProgressService.

Why not just add it to ProgressService?

I could have. It would have worked, for a while. The reason I split it out: ProgressService already has one job — reading and writing PlayerProgress rows. XP math and badge-unlock rules are a different job, with different reasons to change (a new leveling curve vs. a new column). Keeping them apart means a bug in the leveling formula can't accidentally corrupt how progress gets saved, and either one can be tested completely on its own, with no database involved at all.

XpService: the level formula

// src/xp/xp.service.ts
import { Injectable } from '@nestjs/common';

@Injectable()
export class XpService {
  /**
   * Level N requires N² × 100 total XP.
   * Level 1: 0xp, Level 2: 400xp, Level 3: 900xp, ...
   */
  levelForXp(xp: number): number {
    let level = 1;
    while (xp >= (level + 1) ** 2 * 100) {
      level += 1;
    }
    return level;
  }

  xpForNextLevel(xp: number): number {
    const currentLevel = this.levelForXp(xp);
    return (currentLevel + 1) ** 2 * 100;
  }
}

This is the payoff from Part 2's decision to never store level: it's just a pure function of XP. No injection of a repository, no database call, nothing but a number in and a number out — which makes it almost embarrassingly easy to test:

describe('XpService', () => {
  it('stays at level 1 below the level-2 threshold', () => {
    expect(service.levelForXp(399)).toBe(1);
  });

  it('reaches level 2 exactly at the threshold', () => {
    expect(service.levelForXp(400)).toBe(2);
  });
});

No TestingModule, no mocked repository — just new XpService() and assertions. Pure logic is the cheapest kind of code to test, so it's worth carving as much of the game's rules into this shape as possible.

BadgeService: unlocking without duplicating

Badges are a bit trickier than XP because unlocking one is not idempotent by default — advancing through the same page twice shouldn't award the same badge twice. That means BadgeService does need the database, to check what's already unlocked:

// src/badges/badges.service.ts
import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { PlayerBadge } from './entities/player-badge.entity';
import { Badge } from './entities/badge.entity';

@Injectable()
export class BadgesService {
  constructor(
    @InjectRepository(Badge) private readonly badgeRepo: Repository<Badge>,
    @InjectRepository(PlayerBadge)
    private readonly playerBadgeRepo: Repository<PlayerBadge>,
  ) {}

  async unlock(userId: string, badgeCode: string): Promise<void> {
    const alreadyUnlocked = await this.playerBadgeRepo.findOne({
      where: { user: { id: userId }, badge: { code: badgeCode } },
    });
    if (alreadyUnlocked) return;

    const badge = await this.badgeRepo.findOneByOrFail({ code: badgeCode });
    await this.playerBadgeRepo.save(
      this.playerBadgeRepo.create({ user: { id: userId }, badge }),
    );
  }
}

The early if (alreadyUnlocked) return; is the whole idempotency guard — deliberately boring, which is exactly what you want from code responsible for not double-awarding a reward.

Wiring it into `advance()`

Back in ProgressService, the pieces come together:

async advance(userId: string, choice: PageChoice): Promise<PlayerProgress> {
  const progress = await this.findForUser(userId);

  progress.xp += choice.xpReward;
  progress.currentPageId = choice.goto;
  await this.progressRepo.save(progress);

  const targetPage = this.pagesService.findById(choice.goto);
  if (targetPage.badgeUnlocked) {
    await this.badgesService.unlock(userId, targetPage.badgeUnlocked);
  }

  return progress;
}

ProgressService now depends on XpService (indirectly, via the stored xp — the level itself is computed on read, not here) and BadgesService, both injected through the constructor exactly like PagesService was in Part 1. Same pattern, just one more layer.

Custom exceptions for domain errors

One thing I hadn't needed until now: what happens if a client sends a choiceLabel that doesn't exist on the current page? NestJS ships generic exceptions (NotFoundException, BadRequestException), but a custom one documents intent better:

// src/progress/exceptions/invalid-choice.exception.ts
import { BadRequestException } from '@nestjs/common';

export class InvalidChoiceException extends BadRequestException {
  constructor(choiceLabel: string, pageId: string) {
    super(`"${choiceLabel}" is not a valid choice on page ${pageId}`);
  }
}

It still resolves to a 400 (NestJS understands the inheritance chain), but reading throw new InvalidChoiceException(...) at the call site is more honest about what actually went wrong than a generic BadRequestException('Invalid input') would be.

What's next

Right now, advance() still takes a bare userId string, sourced from that temporary DEFAULT_PLAYER_ID from Part 2. Part 4 replaces it with real accounts, login, and a JWT — so userId finally means "whoever is actually making this request," not a placeholder.

Pourquoi ton code sent le copier-coller (DRY)

Rodolphe D. — Fri, 18 Sep 2026 08:30:58 +0000

TL;DR

Tu valides la même facture à 3 endroits différents et tu recalcules le même total à 4 endroits différents. Le jour où tu changes une règle, tu dois te souvenir des 7. DRY, c'est juste : "dis-le une fois, utilise-le partout." On refactore un InvoicesController Adonis qui pue le copier-coller pour le rendre propre.

Il y a deux semaines, j'ai décidé de changer une règle bête sur mon appli de factures : la TVA passe de 20% à 5.5% pour certains clients. Simple, non ? J'ai modifié le calcul, j'ai testé sur la page de création... et ça marchait parfaitement.

Sauf que sur la page d'édition, le total affichait toujours l'ancienne TVA.

Pourquoi ? Parce que j'avais oublié qu'elle avait sa propre copie du calcul. Écrite trois semaines plus tôt, par un moi plus jeune et plus insouciant, qui avait fait un copier-coller "juste pour aller vite."

Bienvenue dans le syndrome du copier-coller de la honte : ce moment où tu réalises que ton bug n'est pas dans ton code, il est dans tes trois codes identiques qui ont divergé sans te prévenir.

Imagine que ton adresse est écrite à la main sur 15 formulaires papier différents — ta banque, ton assurance, ton abonnement internet, ta mutuelle, etc.

Tu déménages. Tu dois retrouver les 15 formulaires et corriger chacun. Tu en oublies un — ta banque, disons — et six mois plus tard elle envoie encore ton relevé chez l'ancien locataire, qui commence à te détester.

DRY (Don't Repeat Yourself), c'est exactement ça appliqué au code : au lieu d'avoir ton adresse écrite 15 fois, tu as un seul endroit où elle est écrite, et les 15 formulaires vont la chercher là. Tu déménages une fois, tu corriges une fois, tout le monde est à jour.

Ce n'est pas une religion du "zéro duplication." C'est juste : arrête d'avoir plusieurs sources de vérité pour la même vérité.

Le code "avant" (le péché)

Voici à peu près ce que contenait mon InvoicesController.ts :

// app/controllers/invoices_controller.ts
export default class InvoicesController {
  async store({ request, response }: HttpContext) {
    const data = request.body()

    // Validation copiée-collée
    if (!data.clientName || !data.clientEmail || !data.items?.length) {
      return response.badRequest('Champs manquants')
    }

    const total = data.items.reduce(
      (sum: number, item: any) => sum + item.quantity * item.price,
      0
    )

    const invoice = await Invoice.create({ ...data, total })
    return response.created(invoice)
  }

  async update({ request, response, params }: HttpContext) {
    const data = request.body()

    // Exactement la même validation, copiée depuis store()
    if (!data.clientName || !data.clientEmail || !data.items?.length) {
      return response.badRequest('Champs manquants')
    }

    // Exactement le même calcul, copié depuis store()
    const total = data.items.reduce(
      (sum: number, item: any) => sum + item.quantity * item.price,
      0
    )

    const invoice = await Invoice.findOrFail(params.id)
    invoice.merge({ ...data, total })
    await invoice.save()
    return response.ok(invoice)
  }
}

Et pour faire bonne mesure, InvoiceForm.vue refaisait encore ce calcul pour afficher un aperçu en temps réel :

<script setup>
const previewTotal = computed(() =>
  form.items.reduce((sum, item) => sum + item.quantity * item.price, 0)
)
</script>

Trois copies. Une seule vérité qui aurait dû exister.

Le refactor "après" (la rédemption)

Étape 1 — le calcul du total devient une propriété du modèle, calculée une seule fois, à la source :

// app/models/invoice.ts
export default class Invoice extends BaseModel {
  @hasMany(() => InvoiceItem)
  declare items: HasMany<typeof InvoiceItem>

  get total() {
    return this.items.reduce((sum, item) => sum + item.quantity * item.price, 0)
  }
}

Étape 2 — la validation devient un schéma VineJS partagé, écrit une fois, importé partout :

// app/validators/invoice_validator.ts
import vine from '@vinejs/vine'

const itemSchema = vine.object({
  name: vine.string(),
  quantity: vine.number().positive(),
  price: vine.number().positive(),
})

export const invoiceValidator = vine.compile(
  vine.object({
    clientName: vine.string().minLength(1),
    clientEmail: vine.string().email(),
    items: vine.array(itemSchema).minLength(1),
  })
)

Étape 3 — le controller n'a plus qu'à appeler ces deux briques, sans jamais réécrire la logique :

// app/controllers/invoices_controller.ts
export default class InvoicesController {
  async store({ request, response }: HttpContext) {
    const data = await request.validateUsing(invoiceValidator)
    const invoice = await Invoice.create(data)
    return response.created(invoice)
  }

  async update({ request, response, params }: HttpContext) {
    const data = await request.validateUsing(invoiceValidator)
    const invoice = await Invoice.findOrFail(params.id)
    invoice.merge(data)
    await invoice.save()
    return response.ok(invoice)
  }
}

Étape 4 — côté Vue, on arrête de recalculer, on affiche simplement ce que le backend renvoie via les props Inertia :

<script setup>
const props = defineProps<{ invoice: Invoice }>()
</script>

<template>
  <p>Total : {{ invoice.total }}</p>
</template>

Résultat : si un jour la règle de TVA change, je la change à un seul endroit, et store, update et l'affichage Vue sont automatiquement synchronisés. Plus de courrier envoyé chez l'ancien locataire.

Le piège à éviter (petite mise en garde)

DRY ne veut pas dire "zéro duplication à tout prix." Si deux bouts de code se ressemblent aujourd'hui mais évoluent pour des raisons différentes — par exemple la validation d'une facture et la validation d'un profil client n'ont aucune raison de partager un schéma générique juste parce qu'elles valident toutes les deux des emails — les fusionner créerait plus de problèmes que ça n'en résout. On y reviendra dans la Partie 4, quand DRY se bat avec KISS.

La semaine prochaine, Partie 2 : comment j'ai transformé un simple changement de statut (draft → pending → paid) en machine à états digne de la NASA. Spoiler : c'était une mauvaise idée.

Building a Choose-Your-Own-Adventure API with NestJS — Part 2: Persistence

Rodolphe D. — Tue, 15 Sep 2026 16:05:45 +0000

Part 2 of a series building "Grimoire API" — a choose-your-own-adventure backend in NestJS, learned one milestone at a time. Part 1 covered controllers, providers, DI and validation with a single read-only endpoint. This time: making a player's progress survive a server restart.

The problem with Part 1

By the end of Part 1, GET /pages/:id worked — but every request started from scratch. There was no concept of "a player," let alone where they currently were in the story. To move a player from one page to the next, something has to remember that between requests. That's what a database is for.

Picking the pieces

For this project I'm using PostgreSQL with TypeORM — NestJS's most common ORM pairing, well documented, and closely integrated with NestJS's dependency injection (you @InjectRepository() a repository the same way you inject a service).

I'm running Postgres locally through Docker Compose rather than installing it directly — one docker compose up and it's there, one docker compose down and it's gone, no leftover system service to remember about.

The entity

An entity is a TypeORM class that maps to a database table. Here's PlayerProgress:

// src/progress/entities/player-progress.entity.ts
import { Entity, PrimaryGeneratedColumn, Column, OneToOne, JoinColumn } from 'typeorm';
import { User } from '../../users/entities/user.entity';

@Entity()
export class PlayerProgress {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @OneToOne(() => User)
  @JoinColumn()
  user: User;

  @Column({ default: 'page-001' })
  currentPageId: string;

  @Column({ default: 0 })
  xp: number;
}

Two decorators do the heavy lifting: @Entity() says "this is a table," @Column() says "this is a column." @OneToOne + @JoinColumn describe the relationship to User — one player, one progress record.

Notice what's not here: no level column. The spec I wrote before touching any code was explicit about this — level is always calculated from XP, never stored as an independent value. If I stored both, sooner or later they'd drift out of sync (say, a bug that updates XP but forgets to bump level), and now the API is lying to the player about their own progress. Deriving it removes the possibility entirely — there's nothing to get out of sync with itself.

Wiring TypeORM into the module

// src/progress/progress.module.ts
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { PlayerProgress } from './entities/player-progress.entity';
import { ProgressService } from './progress.service';
import { ProgressController } from './progress.controller';

@Module({
  imports: [TypeOrmModule.forFeature([PlayerProgress])],
  controllers: [ProgressController],
  providers: [ProgressService],
})
export class ProgressModule {}

TypeOrmModule.forFeature([PlayerProgress]) is what makes @InjectRepository(PlayerProgress) available for injection inside this module — it's the same DI pattern from Part 1, just applied to a repository instead of a plain service.

The repository pattern

Inside the service, I don't write raw SQL — I use the repository, an object TypeORM generates for each entity with methods like findOne, save, update:

// src/progress/progress.service.ts
import { Injectable, NotFoundException } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { PlayerProgress } from './entities/player-progress.entity';

@Injectable()
export class ProgressService {
  constructor(
    @InjectRepository(PlayerProgress)
    private readonly progressRepo: Repository<PlayerProgress>,
  ) {}

  async findForUser(userId: string): Promise<PlayerProgress> {
    const progress = await this.progressRepo.findOne({
      where: { user: { id: userId } },
    });

    if (!progress) {
      throw new NotFoundException('No progress found for this player');
    }

    return progress;
  }

  async advance(userId: string, nextPageId: string): Promise<PlayerProgress> {
    const progress = await this.findForUser(userId);
    progress.currentPageId = nextPageId;
    return this.progressRepo.save(progress);
  }
}

Everything is async now — talking to a database is I/O, and NestJS (like the rest of Node) expects that to be handled with promises, not callbacks.

A temporary shortcut: no auth yet

This project's milestones are deliberately ordered so authentication (Part 4) comes after persistence. That leaves an awkward gap right now: advance() needs a userId, but there's no login system yet to produce one.

For this milestone, I'm sidestepping it with a single hardcoded "default player" seeded at startup, and the endpoint doesn't take a userId at all:

@Post('choice')
async advance(@Body() dto: AdvanceProgressDto) {
  return this.progressService.advance(DEFAULT_PLAYER_ID, dto.nextPageId);
}

It's not a design I'd keep — it's a conscious, temporary simplification so I can build and test persistence in isolation, without also having to build auth at the same time. Part 4 removes DEFAULT_PLAYER_ID entirely and replaces it with whichever user the JWT identifies. Calling out a shortcut like this in the code (and in this post) matters — future-me needs to know it's not the final shape.

Migrations vs. `synchronize: true`

NestJS's TypeORM starter examples often show synchronize: true, which auto-updates your database schema to match your entities. Convenient for a demo, dangerous for anything else — it can drop columns based on nothing but code changes, no history, no way to review what's about to happen.

Instead I generated a real migration:

npx typeorm migration:generate src/migrations/CreatePlayerProgress -d src/data-source.ts
npx typeorm migration:run -d src/data-source.ts

This produces a plain TypeScript file with up()/down() methods — reviewable in a PR, reversible, and it's the same workflow I'd use against a real production database later.

What's next

Progress now survives a restart, but the actual game rules — how much XP a choice grants, when a level-up happens, when a badge unlocks — are still just sitting inert on the choices in the JSON content. Part 3 pulls that logic out into dedicated services.

Building a Choose-Your-Own-Adventure API with NestJS — Part 1: The Foundation

Rodolphe D. — Wed, 09 Sep 2026 12:55:27 +0000

This is the first post in a series where I learn backend development by building "Grimoire API" — a REST API for a choose-your-own-adventure book, complete with XP and badges (because why not gamify learning to code?). If you know a bit of JavaScript and have played with Express, but NestJS still looks like a wall of decorators, this post is for you.

Why a text adventure API?

I wanted a project I'd actually stay motivated to finish. "Build a generic CRUD API" is the kind of tutorial I abandon after day two. So instead, I'm building the backend for a livre dont vous êtes le héros — a choose-your-own-adventure book — where players read a page, pick a choice, and move forward through the story while earning XP and unlocking badges.

The learning goal comes first, the game is the excuse. Every milestone in this project maps to a specific NestJS concept I want to actually understand, not just copy-paste.

This post covers Milestone 1: The Foundation — the very first working endpoint: GET /pages/:id, which returns one page of the story as JSON.

Where I was starting from

I'd written basic Express routes before — app.get('/something', (req, res) => {...}), that kind of thing. Simple, direct, no magic. NestJS, on the other hand, throws a lot of new vocabulary at you on day one: modules, controllers, providers, dependency injection, decorators, DTOs. It's easy to feel like you need to understand the whole framework before writing a single line.

Turns out you don't. Here's the minimum you need to build one real endpoint.

The four building blocks

NestJS organizes code around four ideas. Once they click, everything else is a variation on them.

1. Controllers — the front door

A controller's only job is to receive an HTTP request and return a response. It should not contain business logic. Mine looks like this:

@Controller('pages')
export class PagesController {
  constructor(private readonly pagesService: PagesService) {}

  @Get(':id')
  getPage(@Param() params: GetPageParamsDto) {
    return this.pagesService.findById(params.id);
  }
}

@Controller('pages') says "everything in here handles requests under /pages". @Get(':id') says "and this method handles GET /pages/:id". That's it — the controller doesn't know how to find a page, it just asks something else to do it.

2. Providers (services) — where the logic lives

That "something else" is a service — in NestJS terms, a provider. It holds the actual behavior:

@Injectable()
export class PagesService {
  findById(id: string): Page {
    // read the JSON file, parse it, return it
    // (or throw a 404 if it doesn't exist)
  }
}

The split matters: the controller deals with HTTP, the service deals with the story. If I ever swap how pages are stored — JSON files today, a database later — the controller doesn't change at all.

3. Dependency Injection — the part that felt like magic

Here's the line that confused me the most at first:

constructor(private readonly pagesService: PagesService) {}

I never write new PagesService() anywhere. NestJS creates the instance for me and hands it to the controller automatically. This is dependency injection (DI): instead of a class creating the things it depends on, those things are given to it from outside.

Why bother? Because it makes testing trivial. In my controller test, I don't need a real PagesService reading real files — I can hand it a fake one:

providers: [
  { provide: PagesService, useValue: { findById: jest.fn() } },
],

The controller has no idea it's talking to a fake. That's the whole point.

4. Modules — the glue

A module just declares "these controllers and these providers belong together":

@Module({
  controllers: [PagesController],
  providers: [PagesService],
})
export class PagesModule {}

Then it gets imported into the app's root module. Think of a module as a folder with a table of contents NestJS can read.

The part that actually tripped me up: validation

The route is GET /pages/:id, and :id is just a string typed by whoever calls the API. Nothing stops someone from requesting /pages/../../etc/passwd or /pages/💀. I wanted every page ID to match the format page-XXX (three digits) before it ever reaches my service.

NestJS's answer is a DTO (Data Transfer Object) combined with class-validator:

export class GetPageParamsDto {
  @Matches(/^page-\d{3}$/, {
    message: 'id must match the format page-XXX (3 digits)',
  })
  id: string;
}

And one line in main.ts to turn validation on globally:

app.useGlobalPipes(new ValidationPipe({ transform: true, whitelist: true }));

That's it. Now GET /pages/page-001 works, and GET /pages/not-a-valid-id gets rejected with a 400 before my controller code even runs. I didn't write a single if statement — the framework did the guarding for me, declaratively, right next to the field it protects.

Where I got stuck

Fair warning if you're following a similar path: the confusing part isn't the syntax, it's the order of trust. I kept wanting to validate manually inside the controller (if (!id.match(...)) throw ...), out of old Express habits. Letting the DTO + pipe handle it before my code runs required trusting a layer I couldn't see executing. Once I added a console.log inside the controller and watched it never fire for a bad ID, that trust clicked.

What's next

Milestone 1 ends with one working, validated endpoint and a passing test suite (unit tests for the service and controller, plus one end-to-end test hitting the real HTTP layer). No database yet — the story pages are just JSON files for now.

Milestone 2 is where it gets real: persisting player progress in PostgreSQL with TypeORM, so a player's position in the story actually survives a server restart. That's next.

Ton premier vrai backend Go : fil rouge part 1 — le squelette

Rodolphe D. — Tue, 25 Aug 2026 09:07:00 +0000

Jusqu'ici, le Go tenait dans un package main : un fichier pour la logique, un pour le handler, un main qui câble. Parfait pour comparer Express et Go. Insuffisant pour un backend que tu vas faire grandir.

Rodolphe D.

Aug 11

Ce que Go t'oblige à faire que Node te laissait éviter : les erreurs explicites

#go #node #webdev #beginners

8 min read

La semaine dernière — Handler / service / repository expliqué à un dev Express — on a nommé les trois rôles côté Express. Aujourd'hui, partie 1 du fil rouge : on pose le squelette Go de ce découpage. Pas toute l'API. Pas la validation exhaustive. Un projet qui démarre, avec POST /register et une place claire pour la suite (login, /me, de meilleures erreurs).

Promesse : à la fin, tu as une arborescence que tu comprends, un go run qui écoute, et une carte mentale pour savoir où coller le prochain fichier.

Les parties 2 et 3 arriveront plus tard : erreurs & validation (S8), puis structurer quand ça grossit (S10). Aujourd'hui = fondations seulement.

1. Ce qu'on construit (et ce qu'on laisse pour plus tard)

Dans cette partie :

layout cmd/ + internal/
couches handler → service → repository
POST /register (validation minimale, comme avant)
GET /health (sanity check)
câblage dans main, stdlib net/http, SQL via database/sql

Pas encore :

auth / JWT / sessions
POST /login, GET /me
wrapping d'erreurs sophistiqué, validation dédiée
migrations, Docker, CI

Un squelette, pas un produit fini. Si tu sens l'envie d'ajouter Gin, GORM et un dossier utils/, respire : on reste volontairement simple.

2. L'arborescence

filrouge/
├── go.mod
├── cmd/
│   └── api/
│       └── main.go          # câblage + ListenAndServe
└── internal/
    ├── httpapi/
    │   ├── handler.go       # HTTP ↔ service
    │   └── respond.go       # petits helpers JSON / erreurs HTTP
    ├── user/
    │   ├── service.go       # règles métier
    │   └── repository.go    # SQL
    └── mailer/
        └── mailer.go        # stub email (comme depuis la S1)

Pourquoi comme ça :

cmd/api — le binaire. Un seul main. Plus tard tu pourras avoir cmd/migrate sans mélanger.
internal/ — code privé à ce module. Go refuse qu'un autre module l'importe. C'est le « ne touchez pas depuis l'extérieur » du langage.
user/ — le domaine « utilisateur » (service + repo). Pas un fourre-tout services/ global dès le jour 1.
httpapi/ — tout ce qui parle HTTP. Le domaine ne connaît pas ResponseWriter.

Si tu viens d'Express, l'équivalent mental :

Express (après S5)	Go (fil rouge)
`handler.js` / routes	`internal/httpapi`
`registerService.js`	`internal/user/service.go`
`userRepository.js`	`internal/user/repository.go`
`server.js` / `app.listen`	`cmd/api/main.go`

3. Le repository — SQL, point

// internal/user/repository.go
package user

import (
    "context"
    "database/sql"
)

type User struct {
    ID           string
    Email        string
    PasswordHash string
}

type Repository struct {
    db *sql.DB
}

func NewRepository(db *sql.DB) *Repository {
    return &Repository{db: db}
}

func (r *Repository) FindByEmail(ctx context.Context, email string) (*User, error) {
    var u User
    err := r.db.QueryRowContext(ctx,
        `SELECT id, email, password_hash FROM users WHERE email = $1`, email,
    ).Scan(&u.ID, &u.Email, &u.PasswordHash)
    if err == sql.ErrNoRows {
        return nil, nil
    }
    if err != nil {
        return nil, err
    }
    return &u, nil
}

func (r *Repository) Create(ctx context.Context, email, passwordHash string) (User, error) {
    var u User
    err := r.db.QueryRowContext(ctx,
        `INSERT INTO users (email, password_hash) VALUES ($1, $2)
         RETURNING id, email, password_hash`,
        email, passwordHash,
    ).Scan(&u.ID, &u.Email, &u.PasswordHash)
    return u, err
}

Remarque : FindByEmail renvoie (nil, nil) si l'utilisateur n'existe pas. « Pas trouvé » n'est pas une erreur infra — c'est une information pour le service. Les vraies erreurs SQL remontent telles quelles.

Le context.Context en premier argument : idiome Go. Ça permettra d'annuler une requête si le client HTTP raccroche. On ne creuse pas plus aujourd'hui ; on le met parce que c'est la signature attendue.

4. Le service — les décisions

// internal/user/service.go
package user

import (
    "context"
    "errors"
    "fmt"
    "log"
    "strings"

    "golang.org/x/crypto/bcrypt"
)

var (
    ErrValidation = errors.New("données invalides")
    ErrConflict   = errors.New("cet email est déjà utilisé")
)

type RegisterInput struct {
    Email    string
    Password string
}

type RegisteredUser struct {
    ID    string `json:"id"`
    Email string `json:"email"`
}

// Mailer : assez petit pour rester une interface ici.
type Mailer interface {
    SendWelcome(email string) error
}

type Service struct {
    repo   *Repository
    mailer Mailer
}

func NewService(repo *Repository, mailer Mailer) *Service {
    return &Service{repo: repo, mailer: mailer}
}

func (s *Service) Register(ctx context.Context, in RegisterInput) (RegisteredUser, error) {
    if !strings.Contains(in.Email, "@") {
        return RegisteredUser{}, fmt.Errorf("%w: email invalide", ErrValidation)
    }
    if len(in.Password) < 8 {
        return RegisteredUser{}, fmt.Errorf("%w: mot de passe trop court (8 caractères min)", ErrValidation)
    }

    existing, err := s.repo.FindByEmail(ctx, in.Email)
    if err != nil {
        return RegisteredUser{}, err
    }
    if existing != nil {
        return RegisteredUser{}, ErrConflict
    }

    hash, err := bcrypt.GenerateFromPassword([]byte(in.Password), 12)
    if err != nil {
        return RegisteredUser{}, err
    }

    u, err := s.repo.Create(ctx, in.Email, string(hash))
    if err != nil {
        return RegisteredUser{}, err
    }

    if err := s.mailer.SendWelcome(u.Email); err != nil {
        log.Printf("envoi email échoué: %v", err)
    }

    return RegisteredUser{ID: u.ID, Email: u.Email}, nil
}

Même règles qu'avant. Même choix « l'email ne fait pas échouer l'inscription ». Mais plus de *sql.DB dans la signature publique du métier : le service parle au repository. Et le mailer est une interface — en test, tu branches un faux en deux lignes.

5. Le handler — HTTP only

// internal/httpapi/handler.go
package httpapi

import (
    "encoding/json"
    "errors"
    "net/http"

    "filrouge/internal/user"
)

type Handler struct {
    users *user.Service
}

func NewHandler(users *user.Service) *Handler {
    return &Handler{users: users}
}

func (h *Handler) Register(w http.ResponseWriter, r *http.Request) {
    var in user.RegisterInput
    if err := json.NewDecoder(r.Body).Decode(&in); err != nil {
        writeError(w, http.StatusBadRequest, "corps de requête invalide")
        return
    }

    out, err := h.users.Register(r.Context(), in)
    switch {
    case err == nil:
        writeJSON(w, http.StatusCreated, out)
    case errors.Is(err, user.ErrValidation):
        writeError(w, http.StatusBadRequest, err.Error())
    case errors.Is(err, user.ErrConflict):
        writeError(w, http.StatusConflict, err.Error())
    default:
        writeError(w, http.StatusInternalServerError, "erreur serveur")
    }
}

func (h *Handler) Health(w http.ResponseWriter, r *http.Request) {
    writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
}

// internal/httpapi/respond.go
package httpapi

import (
    "encoding/json"
    "net/http"
)

func writeJSON(w http.ResponseWriter, status int, v any) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)
    _ = json.NewEncoder(w).Encode(v)
}

func writeError(w http.ResponseWriter, status int, msg string) {
    writeJSON(w, status, map[string]string{"error": msg})
}

Le handler ne sait pas hasher. Il ne sait pas parler SQL. Il traduit — exactement le rôle de la Semaine 5, en Go, avec les errors.Is de la Semaine 4.

6. Le câblage — `main` lit comme une recette

// cmd/api/main.go
package main

import (
    "database/sql"
    "log"
    "net/http"
    "os"

    "filrouge/internal/httpapi"
    "filrouge/internal/mailer"
    "filrouge/internal/user"

    _ "github.com/jackc/pgx/v5/stdlib"
)

func main() {
    dsn := envOr("DATABASE_URL", "postgres://user:pass@localhost:5432/filrouge")

    db, err := sql.Open("pgx", dsn)
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()

    repo := user.NewRepository(db)
    svc := user.NewService(repo, mailer.Stub{})
    h := httpapi.NewHandler(svc)

    mux := http.NewServeMux()
    mux.HandleFunc("GET /health", h.Health)
    mux.HandleFunc("POST /register", h.Register)
    // Plus tard : POST /login, GET /me — même mux, nouveaux handlers.

    addr := envOr("ADDR", ":8080")
    log.Printf("écoute sur %s", addr)
    log.Fatal(http.ListenAndServe(addr, mux))
}

func envOr(key, fallback string) string {
    if v := os.Getenv(key); v != "" {
        return v
    }
    return fallback
}

// internal/mailer/mailer.go
package mailer

type Stub struct{}

func (Stub) SendWelcome(email string) error {
    return nil // volontairement muet pour le squelette
}

Lis main de haut en bas : ouvrir la DB → repo → service → handler → routes → listen. Aucune magie de framework. Si tu te perds dans six mois, tu rouvres ce fichier et tu retrouves le graphe de dépendances.

Initialiser le module :

mkdir -p filrouge && cd filrouge
go mod init filrouge
# coller les fichiers ci-dessus, puis :
go get github.com/jackc/pgx/v5/stdlib
go get golang.org/x/crypto/bcrypt
go run ./cmd/api

GET /health doit répondre {"status":"ok"}. POST /register attend une table users (id, email, password_hash) — même schéma minimal qu'en Semaine 2.

7. Où tu branches la suite (sans la coder aujourd'hui)

Garde cette carte sous la main :

Besoin	Où ça vit	Quelle partie du fil rouge
Meilleure validation, erreurs riches	`user/service.go` + helpers d'erreur	Partie 2 (S8)
`POST /login`, hash verify, token	`user/service.go` + `httpapi`	Partie 2 / suite
`GET /me` protégé	middleware dans `httpapi`	plus tard
Trop de fichiers dans `user/`	découper / packages — sans paniquer	Partie 3 (S10)

Le squelette est fait pour recevoir ces ajouts. Tu n'auras pas à tout jeter pour « enfin structurer ».

8. Ce qu'il faut retenir

Un backend Go « réel » ne commence pas par un framework. Il commence par : un main qui câble, un handler qui traduit HTTP, un service qui décide, un repository qui parle SQL. Le reste — auth, validation poussée, découpage fin — s'accroche sur cette ossature.

Si tu ne retiens qu'une phrase : le squelette, c'est le graphe de dépendances rendu évident dans main et dans les dossiers — pas le nombre de bibliothèques installées.

Prochaine station du fil rouge (S8) : on durcit erreurs et validation, Node vs Go, sur ce projet. Entre-temps, si tu veux juste relire les couches côté Express : l'article handler / service / repository est le mode d'emploi.

La série continue.

Handler / service / repository expliqué à un dev Express

Rodolphe D. — Tue, 18 Aug 2026 10:00:00 +0000

En Semaine 1, on a sorti la logique du handler. Un geste, une fonction : registerUser. Ça a tout changé — jusqu'au jour où cette fonction devient le nouveau monolithe.

Rodolphe D.

Jul 17

Pourquoi tes routes Express deviennent illisibles (et le seul geste qui les sauve)

#node #javascript #webdev #architecture

7 min read

Aujourd'hui, on coupe ce monolithe en trois rôles que tu as déjà croisés sous d'autres noms : handler, service, repository. Pas pour coller un diagramme sur le frigo. Pour savoir où mettre la prochaine règle métier quand le fichier grossit — sans retomber dans le routes.js de 400 lignes.

Promesse : à la fin, tu sauras qui fait quoi, tu auras le découpage sur le register que tu connais, et tu sauras aussi quand ne pas le faire.

1. Le problème après le premier geste

Voici où on en était. La logique est hors du handler — bien. Mais elle fait encore tout :

async function registerUser({ email, password }) {
  if (!email || !email.includes('@')) {
    throw new ValidationError('Email invalide')
  }
  if (!password || password.length < 8) {
    throw new ValidationError('Mot de passe trop court (8 caractères min)')
  }

  const existing = await prisma.user.findUnique({ where: { email } })
  if (existing) {
    throw new ConflictError('Cet email est déjà utilisé')
  }

  const passwordHash = await bcrypt.hash(password, 12)
  const user = await prisma.user.create({ data: { email, passwordHash } })

  try {
    await sendWelcomeEmail(user.email)
  } catch (err) {
    console.error('Envoi email échoué', err)
  }

  return { id: user.id, email: user.email }
}

Trois natures de travail dans la même fonction :

Règles métier — « email valide », « mot de passe ≥ 8 », « email unique ».
Persistance — findUnique, create.
Effet de bord — l'email de bienvenue.

Tant que c'est court, ça va. Le jour où tu ajoutes « vérifier un code d'invitation », « écrire dans une table d'audit », « choisir le provider d'email selon l'env », cette fonction devient le fichier que tu n'oses plus ouvrir — juste un cran plus bas dans la pile.

Le premier geste (sortir du handler) reste nécessaire. Il n'est plus suffisant.

2. Les trois rôles, en français de café

Oublie un instant les buzzwords. Pose-toi trois questions sur chaque bout de code :

Question	Rôle	En Express, ça ressemble à…
« Comment je parle HTTP ? »	Handler	la route, le controller
« Qu'est-ce que mon produit autorise / décide ? »	Service	la logique métier, parfois appelée use case
« Comment je lis / écris les données ? »	Repository	l'accès Prisma / SQL / ORM

Le handler décode req, appelle le service, traduit résultat/erreur en status HTTP. Il ne connaît pas Prisma. Il ne hash pas de mot de passe.
Le service applique les règles. Il dit « cet email est déjà pris ». Il ne sait pas si ça vient de Postgres ou d'un mock en mémoire. Il ne connaît pas res.status.
Le repository parle à la base. findByEmail, create. Pas de règle « mot de passe trop court » ici — ce n'est pas son job.

Le test mental, le même qu'en Semaine 1, se décline :

Peux-tu tester une règle métier sans lancer Express ? → service isolé.
Peux-tu changer de base (ou mocker) sans réécrire les règles ? → repository derrière une interface claire.
Peux-tu lire la route en 10 secondes ? → handler mince.

3. Le même register, découpé

Repository — la base, rien d'autre

// userRepository.js
class UserRepository {
  constructor(prisma) {
    this.prisma = prisma
  }

  findByEmail(email) {
    return this.prisma.user.findUnique({ where: { email } })
  }

  create({ email, passwordHash }) {
    return this.prisma.user.create({
      data: { email, passwordHash },
    })
  }
}

module.exports = { UserRepository }

Pas de validation. Pas de bcrypt. Des questions à la base, des réponses.

Service — les règles du produit

// registerService.js
const bcrypt = require('bcrypt')
const { sendWelcomeEmail } = require('./mailer')

class ValidationError extends Error {}
class ConflictError extends Error {}

class RegisterService {
  constructor(users) {
    this.users = users // UserRepository
  }

  async register({ email, password }) {
    if (!email || !email.includes('@')) {
      throw new ValidationError('Email invalide')
    }
    if (!password || password.length < 8) {
      throw new ValidationError('Mot de passe trop court (8 caractères min)')
    }

    const existing = await this.users.findByEmail(email)
    if (existing) {
      throw new ConflictError('Cet email est déjà utilisé')
    }

    const passwordHash = await bcrypt.hash(password, 12)
    const user = await this.users.create({ email, passwordHash })

    try {
      await sendWelcomeEmail(user.email)
    } catch (err) {
      console.error('Envoi email échoué', err)
    }

    return { id: user.id, email: user.email }
  }
}

module.exports = { RegisterService, ValidationError, ConflictError }

Le service orchestre. Il décide. Il délègue le stockage au repository. Toujours zéro req / res.

Handler — le traducteur HTTP

// handler.js
const express = require('express')
const { PrismaClient } = require('@prisma/client')
const { UserRepository } = require('./userRepository')
const {
  RegisterService,
  ValidationError,
  ConflictError,
} = require('./registerService')

const prisma = new PrismaClient()
const users = new UserRepository(prisma)
const registerService = new RegisterService(users)

const app = express()
app.use(express.json())

app.post('/register', async (req, res, next) => {
  try {
    const user = await registerService.register(req.body)
    return res.status(201).json(user)
  } catch (err) {
    if (err instanceof ValidationError) {
      return res.status(400).json({ error: err.message })
    }
    if (err instanceof ConflictError) {
      return res.status(409).json({ error: err.message })
    }
    return next(err)
  }
})

module.exports = app

Même job qu'en Semaine 1 — mais il appelle un service, pas une fonction fourre-tout. Le câblage (prisma → repo → service) se fait une fois, au démarrage. Les routes ne créent plus leurs dépendances dans le handler.

4. Ce que ça change concrètement

Tester sans HTTP ni vraie DB. Tu injectes un faux repository :

const { test } = require('node:test')
const assert = require('node:assert')
const { RegisterService, ValidationError } = require('./registerService')

test('refuse un mot de passe trop court', async () => {
  const fakeUsers = {
    findByEmail: async () => null,
    create: async () => {
      throw new Error('ne doit pas être appelé')
    },
  }
  const service = new RegisterService(fakeUsers)

  await assert.rejects(
    () => service.register({ email: 'ada@example.com', password: '123' }),
    ValidationError,
  )
})

La règle métier est vérifiée. Aucun Express. Aucun Postgres. Le fake ne fait que ce que le service a le droit d'attendre du repository.

Changer d'outil sans réécrire le métier. Demain tu remplaces Prisma par pg brut, ou tu ajoutes un cache devant findByEmail : tu touches le repository. Le service et le handler restent.

Lire le projet par responsabilité. « Où est la règle du mot de passe ? » → service. « Où est la requête SQL / Prisma ? » → repository. « Où est le 409 ? » → handler. Tu ne fouilles plus un seul fichier de 300 lignes pour les trois réponses.

5. Et en Go, c'est la même carte

Si tu as suivi la Semaine 2 et la Semaine 4, tu as déjà vu le handler mince et les erreurs-valeurs. Le découpage se lit pareil :

Express	Go (idée)
`RegisterService.register`	`RegisterService.Register` (méthode sur un struct)
`UserRepository.findByEmail`	`UserRepository.FindByEmail`
injection via `constructor`	injection via champs du struct + câblage dans `main`
`instanceof ValidationError`	`errors.Is(err, ErrValidation)`

Même carte mentale. Autre syntaxe. La semaine prochaine, on pose exactement ce squelette en Go — pas en théorie, en arborescence de projet.

6. Quand ne pas faire ça

Trois couches pour un script de 40 lignes, c'est du théâtre.

Règle simple que j'utilise :

Une route, logique courte → fonction + handler mince (Semaine 1). Stop.
La fonction métier mélange règles et SQL, et ça commence à faire mal → introduis service / repository.
Tu ajoutes une deuxième façon d'entrer (job cron, CLI, autre transport) → le service devient obligatoire ; le handler HTTP n'est plus le seul client.

Ce n'est pas « clean architecture ou rien ». C'est « un cran de découpe quand la douleur apparaît », pas avant. Les projets juniors que je vois partent trop souvent du diagramme à six couches et n'écrivent jamais la première règle métier.

7. Ce qu'il faut retenir

Handler = HTTP. Service = décisions du produit. Repository = données. Le premier geste (sortir du handler) reste la fondation ; ces trois rôles sont ce que tu ajoutes quand registerUser devient le nouveau fichier qu'on évite.

Si tu ne retiens qu'une phrase : chaque couche a une seule question à laquelle répondre — et elle ne répond pas aux deux autres.

La semaine prochaine : on pose le squelette du fil rouge Go — ton premier vrai backend, structuré handler / service / repository, prêt à grandir (parties 2 et 3 plus tard).

La série continue.

Ce que Go t'oblige à faire que Node te laissait éviter : les erreurs explicites

Rodolphe D. — Tue, 11 Aug 2026 12:15:46 +0000

En Semaine 2, on a posé le même POST /register en Express et en Go, côte à côte. Un fil est resté volontairement tendu : if err != nil partout, une erreur qui se renvoie au lieu de se lancer. Plaisir ou corvée ?

Rodolphe D.

Jul 21

De Node à Go : le même POST /register, côte à côte

#go #javascript #node #webdev

7 min read

Aujourd'hui, on coupe ce fil. Pas pour te convaincre que Go a inventé la gestion d'erreurs — Node sait aussi gérer des erreurs. Pour montrer ce que Go refuse de te laisser faire, et ce que Node te laisse éviter jusqu'au jour où ça te revient en pleine face.

Promesse simple : à la fin, tu sauras pourquoi if err != nil n'est pas du bruit, et tu auras un schéma mental pour traduire tes try/catch en retours d'erreur Go — sans perdre le fil métier.

1. Ce que Node te laisse faire (et que tu fais)

En Node, une erreur est optionnelle jusqu'à ce qu'elle explose.

Tu peux écrire ceci, et ça tourne :

async function registerUser({ email, password }) {
  const existing = await prisma.user.findUnique({ where: { email } })
  if (existing) {
    throw new ConflictError('Cet email est déjà utilisé')
  }

  const passwordHash = await bcrypt.hash(password, 12)
  const user = await prisma.user.create({ data: { email, passwordHash } })
  await sendWelcomeEmail(user.email) // et si ça plante ?
  return { id: user.id, email: user.email }
}

Trois façons de "gérer" l'échec de sendWelcomeEmail, toutes légales :

Ne rien faire. L'erreur remonte, le catch du handler (s'il existe) la transforme en 500. L'inscription a peut-être réussi en base, mais le client reçoit une erreur. Ou pire : pas de catch, et le process crache un UnhandledPromiseRejection.
Avaler silencieusement. Un try/catch vide, ou un .catch(() => {}). L'inscription réussit, l'email disparaît dans le vide, personne n'est prévenu.
Logger et continuer. Comme en Semaine 1 : on catch, on console.error, on renvoie quand même l'utilisateur créé. C'est le bon choix ici — mais rien dans le langage ne te l'impose.

Le point n'est pas que Node est mauvais. C'est que le langage te laisse choisir de ne pas choisir. Tu peux oublier un await. Tu peux oublier un catch. Tu peux laisser une Promise rejeter sans jamais la regarder. Le runtime proteste parfois, parfois trop tard, parfois jamais en local.

Et le pire : ça a l'air de marcher. Jusqu'à ce qu'un email ne parte pas en prod, ou qu'un findUnique échoue pour une raison réseau et que tu te retrouves avec un undefined que tu traites comme un user.

2. Ce que Go refuse

En Go, une fonction qui peut échouer le dit dans sa signature. Pas dans un commentaire. Pas dans un @throws que personne ne lit. Dans le type de retour.

func RegisterUser(db *sql.DB, in RegisterInput) (RegisteredUser, error)

Deux valeurs. Le résultat et l'erreur. L'appelant voit qu'il y a une erreur possible. Et le compilateur ne te laisse pas faire semblant :

user, err := RegisterUser(db, in)
// Si tu ignores err et que tu utilises user, tu as un bug.
// Go ne te force pas à checker err — mais la convention, l'outil, et
// tout le code autour te le rappellent à chaque ligne.

Petite nuance honnête, parce que je n'aime pas les slogans : Go ne compile pas un oubli de if err != nil. Tu peux écrire _ = err ou ignorer err et continuer. Ce n'est pas un garde-fou magique du compilateur.

Ce qui change, c'est ailleurs :

L'erreur est une valeur, pas un événement qui traverse la pile en silence.
Elle est dans le flux : tu la vois à chaque appel, dans le même ordre que le code métier.
La convention est si forte (if err != nil { return ..., err }) que le code qui l'ignore se remarque. Un _ = err crie. Un throw oublié en JS, non.

Node te laisse éviter. Go te met l'échec sous le nez, à chaque étape.

3. Le même register, vu par les erreurs

Reprends RegisterUser de la Semaine 2, mais cette fois on ne regarde que le chemin des erreurs.

func RegisterUser(db *sql.DB, in RegisterInput) (RegisteredUser, error) {
    if !strings.Contains(in.Email, "@") {
        return RegisteredUser{}, fmt.Errorf("%w: email invalide", ErrValidation)
    }
    if len(in.Password) < 8 {
        return RegisteredUser{}, fmt.Errorf("%w: mot de passe trop court (8 caractères min)", ErrValidation)
    }

    var exists bool
    if err := db.QueryRow(
        "SELECT EXISTS(SELECT 1 FROM users WHERE email = $1)", in.Email,
    ).Scan(&exists); err != nil {
        return RegisteredUser{}, err // erreur infra : on la remonte telle quelle
    }
    if exists {
        return RegisteredUser{}, ErrConflict
    }

    hash, err := bcrypt.GenerateFromPassword([]byte(in.Password), 12)
    if err != nil {
        return RegisteredUser{}, err
    }

    var id string
    if err := db.QueryRow(
        "INSERT INTO users (email, password_hash) VALUES ($1, $2) RETURNING id",
        in.Email, string(hash),
    ).Scan(&id); err != nil {
        return RegisteredUser{}, err
    }

    if err := sendWelcomeEmail(in.Email); err != nil {
        // Choix métier explicite : l'email ne doit pas faire échouer l'inscription.
        log.Printf("envoi email échoué: %v", err)
    }

    return RegisteredUser{ID: id, Email: in.Email}, nil
}

Chaque if err != nil est une décision écrite :

Étape	Si ça échoue	Décision
Validation email / password	Données pourries	Erreur métier (`ErrValidation`), stop
`QueryRow` EXISTS	Base down / SQL cassé	Remonter l'erreur infra, stop
Email déjà pris	Conflit métier	`ErrConflict`, stop
`bcrypt`	Rare, mais possible	Remonter, stop
`INSERT`	Contrainte, réseau, etc.	Remonter, stop
Email de bienvenue	SMTP down	Logger et continuer

En Node, la dernière ligne du tableau est souvent un oubli ou un try/catch collé après coup. Ici, le "continuer malgré l'échec de l'email" est une ligne que tu lis dans le flux principal. Ce n'est plus un détail caché dans un catch trois niveaux plus haut.

C'est ça, le vrai contraste : l'échec n'est plus un événement latéral, c'est une branche du code métier.

4. `errors.Is`, wrapping, et pourquoi `fmt.Errorf("%w")`

En Semaine 1–2, côté Express, on avait des classes : ValidationError, ConflictError. Le handler faisait instanceof.

En Go, l'équivalent idiomatique :

var (
    ErrValidation = errors.New("données invalides")
    ErrConflict   = errors.New("cet email est déjà utilisé")
)

Et pour ajouter du contexte sans perdre l'identité de l'erreur :

return RegisteredUser{}, fmt.Errorf("%w: email invalide", ErrValidation)

Le %w (wrap) dit : "cette erreur est encore ErrValidation, avec un message plus précis". Le handler peut alors faire :

user, err := RegisterUser(db, in)
switch {
case err == nil:
    // 201 + JSON
case errors.Is(err, ErrValidation):
    http.Error(w, err.Error(), http.StatusBadRequest)
case errors.Is(err, ErrConflict):
    http.Error(w, err.Error(), http.StatusConflict)
default:
    http.Error(w, "erreur serveur", http.StatusInternalServerError)
}

Pourquoi pas comparer avec == ? Parce qu'après un wrap, err == ErrValidation est faux — tu as une nouvelle valeur qui contient ErrValidation. errors.Is déroule la chaîne. C'est l'instanceof des erreurs-valeurs.

Et le default ? C'est le filet pour tout ce que tu n'as pas nommé : timeout DB, disque plein, bug. Tu ne fuis pas ces erreurs — tu refuses de les exposer telles quelles au client. En Node, l'équivalent est souvent un next(err) vers un middleware d'erreur global. Même idée, mais en Go tu le vois dans le handler, pas trois fichiers plus loin.

5. La traduction mentale Node → Go

Si tu viens de JS, voilà le tableau que j'aurais voulu avoir le premier jour :

Node	Go
`throw new Error(...)`	`return zeroValue, err`
`try { ... } catch (e) { ... }`	`if err != nil { ... }` juste après l'appel
`instanceof ValidationError`	`errors.Is(err, ErrValidation)`
Classe d'erreur custom	`var ErrX = errors.New("...")` (+ wrap `%w` pour le détail)
Promise rejetée non catchée	Valeur `error` non inspectée (visible, mais pas bloquée par le compilateur)
`async/await` qui "saute" au catch	Retour anticipé `return ..., err` — le flux reste linéaire

Un piège classique quand on débarque : vouloir recréer try/catch avec un panic / recover. Ça existe. Ce n'est pas le chemin pour les erreurs attendues (validation, conflit, DB down). panic, c'est pour "le programme ne peut plus continuer de façon sensée" — bug, invariant cassé. Pas pour "l'email est déjà pris".

Si tu te surprends à écrire panic pour une 400, tu es en train de réimporter le modèle mental Node dans un langage qui a un autre contrat.

6. Et le bruit dans le code ?

Objection légitime : "ok, mais c'est verbeux. Quatre lignes pour un appel qui en ferait une en JS."

Oui. Au début, ça grince. Puis trois choses arrivent.

D'abord, tu arrêtes de te demander où l'erreur est gérée. Elle est gérée ici, ou elle est renvoyée ici. Pas de chasse au catch manquant trois fonctions plus haut.

Ensuite, tu te mets à lire les erreurs comme du métier. "Si l'INSERT échoue, on remonte. Si l'email échoue, on log." Ce n'est plus du plomberie — c'est la spec, écrite en Go.

Enfin, tu remarques que Node n'était pas plus court : tu avais déplacé le coût. Moins de lignes dans le happy path, plus d'incertitude sur le chemin d'échec. Go inverse le trade-off : plus de lignes, moins d'incertitude.

Je ne vais pas te dire que c'est toujours agréable. Certains jours, le dixième if err != nil de la fonction me fatigue. Mais je ne me suis jamais réveillé à 3 h du matin en me demandant pourquoi une Promise avait rejeté en silence dans un job cron. Ce genre de nuit, Go me les a largement évitées.

7. Mini-exercice : le piège du `_`

Avant de refermer, un anti-pattern à reconnaître au premier coup d'œil :

user, _ := RegisterUser(db, in) // ❌ l'erreur disparaît
w.WriteHeader(http.StatusCreated)
json.NewEncoder(w).Encode(user)   // user peut être vide / partiel

Le _ dit au compilateur "je sais, je jette". En review, c'est un drapeau rouge sauf cas très documenté (ex. une fermeture de fichier où tu as déjà décidé d'ignorer l'erreur de Close — et encore, on débat).

La version honnête :

user, err := RegisterUser(db, in)
if err != nil {
    // traduire en HTTP, ou remonter
    return
}

Si tu dois vraiment ignorer, écris pourquoi en une ligne de commentaire. Le silence du _ sans explication, c'est exactement le comportement que Node te laissait avoir par défaut — et qu'on essaye de ne plus reproduire.

8. Ce qu'il faut retenir

Go ne t'apprend pas "à mieux gérer les erreurs" par magie. Il t'empêche de faire comme si l'échec n'existait pas. Chaque appel qui peut rater te tend une valeur error. Tu la traites, tu la wrap, ou tu l'assumes à voix haute. Ce que Node te laissait éviter — l'oubli, le catch manquant, la Promise orpheline — devient une décision visible dans le fichier.

Si tu ne retiens qu'une phrase : en Go, l'erreur est une valeur dans le flux ; en Node, c'est souvent un événement que tu peux rater.

La semaine prochaine : Handler / service / repository, expliqué à un dev Express — comment découper quand le fichier grossit, sans retomber dans le monolithe de routes de la Semaine 1.

La série continue.

« J'ai fini le tuto Node, et là je suis bloqué » — le mur dont personne ne parle

Rodolphe D. — Fri, 07 Aug 2026 06:20:00 +0000

Tu as fini le tuto.

Le vrai, le gros, celui de douze heures. Tu as tout suivi, tout tapé, tout fait tourner. À la fin, l'application marchait. Tu t'es senti capable. Tu t'es dit : « ça y est, je sais faire une API ».

Et puis tu as ouvert un dossier vide pour faire la tienne.

Curseur qui clignote. index.js. Rien.

Pas parce que tu as oublié la syntaxe. Tu la connais. Mais là, tout seul, sans quelqu'un qui te dit quoi taper à la ligne suivante, tu ne sais pas par où commencer. Et cette sensation-là, ce vide entre « j'ai fini le tuto » et « je sais faire », personne ne t'avait prévenu qu'elle existait.

C'est de ce mur que je veux parler. Parce que ce n'est pas un défaut chez toi. C'est une étape.

1. Le piège n'est pas le tuto, c'est ce qu'il te cache

Un tuto, c'est une suite de bonnes décisions déjà prises pour toi.

Quel dossier créer. Quel package installer. Où mettre le fichier de config. Quand extraire une fonction. À chaque embranchement, le formateur a choisi le bon chemin, et toi tu l'as suivi. Tu as tapé du code, oui. Mais tu n'as pris aucune décision.

Or coder, le vrai coder, c'est presque que ça : décider. Choisir entre deux structures. Trancher un nom de variable. Décider si ce bout de logique mérite sa propre fonction. Un développeur qui bosse, ce n'est pas quelqu'un qui connaît toutes les réponses — c'est quelqu'un qui sait avancer quand il n'y en a pas.

Le tuto t'a entraîné à taper. Il ne t'a pas entraîné à décider. Et c'est exactement la compétence qui te manque devant ton dossier vide. Ce n'est pas un trou dans ton savoir. C'est un muscle que tu n'as jamais sollicité, parce qu'on ne te l'a jamais laissé faire.

2. Pourquoi « un tuto de plus » ne réglera rien

Ta réaction instinctive face au blocage, c'est de retourner là où tu te sens compétent. Un autre tuto. Un cours de plus. Une nouvelle techno à cocher.

Je comprends le réflexe. Le tuto, c'est confortable : il y a une barre de progression, une fin, une petite dose de « j'ai réussi » à chaque étape. Le dossier vide, lui, ne te donne rien. Aucune barre, aucune validation, juste toi et des décisions à prendre.

Mais chaque tuto supplémentaire renforce précisément le muscle que tu as déjà, et laisse s'atrophier celui qui te manque. Tu deviens très bon à suivre, et toujours aussi bloqué à décider. C'est le fameux tutorial hell : pas un manque de connaissances, un excès de connaissances jamais mises à l'épreuve du choix.

La sortie n'est pas d'apprendre plus. Elle est de décider plus, sur un terrain assez petit pour que ce soit supportable.

3. La sortie : le plus petit projet qui décide à ta place de rien

Le mur tombe le jour où tu construis quelque chose que le tuto n'a pas prémâché. Mais « construis ton projet ! » est un conseil inutile — c'est justement le dossier vide qui te paralyse.

Alors on rétrécit. Beaucoup.

Pas une app. Pas un clone de Twitter. Une seule route qui fait une chose. Un endpoint GET /health qui répond { status: 'ok' }. C'est tout. Ça a l'air ridicule, et c'est le but : c'est assez petit pour que tu ne puisses pas te cacher derrière « je ne sais pas par où commencer ». Tu sais faire ça. Tu l'as fait cent fois dans les tutos.

La différence, cette fois : tu le fais dans un dossier vide, sans copier. Tu décides du nom du fichier. Tu décides d'installer Express ou d'utiliser le serveur natif. Tu décides où répondre. Chaque micro-décision est un peu inconfortable — et c'est exactement le muscle qui travaille.

const express = require('express')
const app = express()

app.get('/health', (req, res) => {
  res.json({ status: 'ok' })
})

app.listen(3000, () => console.log('En écoute sur le port 3000'))

Quinze lignes. Rien d'impressionnant. Mais si tu les as écrites sans tuto ouvert dans un autre onglet, tu viens de faire une chose que douze heures de vidéo ne t'avaient jamais fait faire : avancer seul.

Ensuite, tu ajoutes une décision à la fois. Une route POST qui reçoit un JSON. Puis une validation du champ reçu. Puis stocker les données quelque part — d'abord dans un tableau en mémoire, et tant pis si ce n'est pas « propre ». Chaque ajout est une nouvelle décision, prise par toi. C'est comme ça que le muscle grossit : par petites charges, pas en soulevant l'app entière d'un coup.

4. La règle qui garde le muscle en vie : jamais copier sans décider

Tu vas retomber sur des tutos, c'est inévitable, et c'est même utile. La question n'est pas de les fuir, c'est de changer ce que tu en fais.

La règle tient en une phrase : tu as le droit de lire n'importe quel tuto, mais pas de copier une ligne sans pouvoir dire pourquoi elle est là.

Concrètement. Tu bloques sur la validation d'un body, tu vas voir comment quelqu'un fait. Bien. Mais avant de coller sa solution dans ton projet, tu te forces à répondre : pourquoi cette ligne ? qu'est-ce qu'elle fait ? qu'est-ce qui casse si je l'enlève ? Si tu ne sais pas répondre, tu ne colles pas — tu creuses jusqu'à savoir. Le tuto redevient une doc que tu consultes, au lieu d'un pilote automatique que tu suis.

C'est la nuance entre apprendre dans un tuto et apprendre d'un tuto. La première te laisse bloqué au premier dossier vide. La seconde construit, décision après décision, le seul truc qui te fera passer le mur.

5. Ce qu'il faut retenir

Si tu es bloqué après avoir « tout appris », ce n'est pas que tu n'en sais pas assez. C'est que tu n'as jamais eu à décider seul, parce que le format tuto décide toujours à ta place.

La sortie n'est pas un cours de plus. C'est le plus petit projet possible, dans un dossier vide, où chaque ligne est une décision que tu prends toi-même — quitte à ce que ce soit déplaisant au début.

Et, le jour où décider ne te fait plus peur sur du petit, tu es prêt pour du plus gros. C'est aussi le moment idéal pour attaquer un langage qui te force la main sur ces décisions dès le départ — mais ça, c'est le sujet d'un autre article de la série.

Commence par ton GET /health. Aujourd'hui. Dossier vide, aucun onglet ouvert. C'est quinze lignes et c'est le premier mur qui tombe.

From Node to Go - the same POST /register, side by side

Rodolphe D. — Fri, 24 Jul 2026 09:15:32 +0000

A registration endpoint is small enough to hold in your head and real enough to hurt: validate the input, hash the password, write to the database, send a welcome email. In Express, I pulled the business logic out of the route handler — the logic in its own registerUser function, and a tiny handler whose only job is to translate HTTP into that logic and back. The result: a handler you can read at a glance, and a business rule you can test without ever starting a server. (The full before/after lives in the starter repo linked at the bottom — grab it if you want to run everything yourself.)

Today I'm changing the language, not the subject. I take that same endpoint and set it next to its Go equivalent. Same gesture, same split: the logic on one side, the HTTP handler on the other.

No sleight of hand, no framework hiding behind the curtain. Just the code, side by side. The contrasts come after — today, we just look.

1. The Express version, for reference

Same shape as before: the logic lives in registerUser, and a thin handler only translates.

const bcrypt = require('bcrypt')
const { PrismaClient } = require('@prisma/client')
const { sendWelcomeEmail } = require('./mailer')

const prisma = new PrismaClient()

class ValidationError extends Error {}
class ConflictError extends Error {}

// Business logic, decoupled from the framework: it knows nothing about
// req/res. You can call it from a script, a test, a job — anywhere.
async function registerUser({ email, password }) {
  if (!email || !email.includes('@')) {
    throw new ValidationError('Invalid email')
  }
  if (!password || password.length < 8) {
    throw new ValidationError('Password too short (8 characters minimum)')
  }

  const existing = await prisma.user.findUnique({ where: { email } })
  if (existing) {
    throw new ConflictError('This email is already taken')
  }

  const passwordHash = await bcrypt.hash(password, 12)
  const user = await prisma.user.create({ data: { email, passwordHash } })

  try {
    await sendWelcomeEmail(user.email)
  } catch (err) {
    console.error('Failed to send email', err)
  }

  return { id: user.id, email: user.email }
}

module.exports = { registerUser, ValidationError, ConflictError }

const express = require('express')
const { registerUser, ValidationError, ConflictError } = require('./registerUser')

const app = express()
app.use(express.json())

// The handler is thin: read the request, call the business logic,
// translate the result (or a business error) into an HTTP response.
app.post('/register', async (req, res, next) => {
  try {
    const user = await registerUser(req.body)
    return res.status(201).json(user)
  } catch (err) {
    if (err instanceof ValidationError) return res.status(400).json({ error: err.message })
    if (err instanceof ConflictError) return res.status(409).json({ error: err.message })
    return next(err)
  }
})

module.exports = app

2. The same endpoint, in Go

Here's the same endpoint, structured the same way, in Go: the logic on one side, the handler on the other.

One difference in layers I want to name right away, so you don't mistake it for magic: on the Express side, the database went through Prisma, an ORM. On the Go side, I'm showing plain SQL with database/sql — the idiomatic default in the language. It's a subject of its own, and I'll come back to it another day.

RegisterUser is the Go mirror of registerUser: the business logic, decoupled, with no knowledge of net/http.

package main

import (
    "database/sql"
    "errors"
    "fmt"
    "log"
    "strings"

    "golang.org/x/crypto/bcrypt"
)

// Business errors — the Go equivalent of ValidationError / ConflictError.
// They never mention an HTTP status: the logic doesn't know HTTP exists.
var (
    ErrValidation = errors.New("invalid input")
    ErrConflict   = errors.New("this email is already taken")
)

// RegisterInput describes, explicitly, the shape of the expected data.
type RegisterInput struct {
    Email    string
    Password string
}

// RegisteredUser describes what the function returns.
type RegisteredUser struct {
    ID    string
    Email string
}

// RegisterUser holds the business logic. It knows nothing about
// *http.Request or http.ResponseWriter: call it from a script, a test, a job.
func RegisterUser(db *sql.DB, in RegisterInput) (RegisteredUser, error) {
    if !strings.Contains(in.Email, "@") {
        return RegisteredUser{}, fmt.Errorf("%w: invalid email", ErrValidation)
    }
    if len(in.Password) < 8 {
        return RegisteredUser{}, fmt.Errorf("%w: password too short (8 characters minimum)", ErrValidation)
    }

    var exists bool
    if err := db.QueryRow(
        "SELECT EXISTS(SELECT 1 FROM users WHERE email = $1)", in.Email,
    ).Scan(&exists); err != nil {
        return RegisteredUser{}, err
    }
    if exists {
        return RegisteredUser{}, ErrConflict
    }

    hash, err := bcrypt.GenerateFromPassword([]byte(in.Password), 12)
    if err != nil {
        return RegisteredUser{}, err
    }

    var id string
    if err := db.QueryRow(
        "INSERT INTO users (email, password_hash) VALUES ($1, $2) RETURNING id",
        in.Email, string(hash),
    ).Scan(&id); err != nil {
        return RegisteredUser{}, err
    }

    if err := sendWelcomeEmail(in.Email); err != nil {
        // Sending the email must not fail the registration.
        log.Printf("failed to send email: %v", err)
    }

    return RegisteredUser{ID: id, Email: in.Email}, nil
}

If you've never read Go, four landmarks are enough to keep you from getting lost in this file:

A function can return several values. Look at the signature: func RegisterUser(db *sql.DB, in RegisterInput) (RegisteredUser, error). It hands back two things at once — the result and an error. That's the Go convention: you often return (result, error), and the caller checks the error right after. Nothing more to grasp here; I'll cover it in depth in the next piece.
nil is the absence of a value. The mental equivalent of the null you know. A db set to nil means "no connection."
:= declares and assigns at once (hash, err := ...), where var only declares (var id string). Two ways to introduce a variable, depending on whether you already have a value to put in it.
The initial capital decides visibility. RegisterUser starts with a capital: it's exported, visible from outside the package. sendWelcomeEmail, lowercase, stays private to the package. The language reads the case like a scope keyword.

With those four landmarks, the rest reads like pseudo-code.

The handler next — thin, only relaying HTTP to the business logic, exactly like the Express side.

package main

import (
    "database/sql"
    "encoding/json"
    "errors"
    "net/http"
)

// registerHandler is thin: decode, call RegisterUser, translate to HTTP.
// It is an HTTP<->domain translator, not a place where logic lives.
func registerHandler(db *sql.DB) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        var in RegisterInput
        if err := json.NewDecoder(r.Body).Decode(&in); err != nil {
            http.Error(w, "invalid request body", http.StatusBadRequest)
            return
        }

        user, err := RegisterUser(db, in)
        switch {
        case err == nil:
            w.Header().Set("Content-Type", "application/json")
            w.WriteHeader(http.StatusCreated)
            json.NewEncoder(w).Encode(user)
        case errors.Is(err, ErrValidation):
            http.Error(w, err.Error(), http.StatusBadRequest)
        case errors.Is(err, ErrConflict):
            http.Error(w, err.Error(), http.StatusConflict)
        default:
            http.Error(w, "server error", http.StatusInternalServerError)
        }
    }
}

And the wiring: a http.ServeMux from the standard library, mux.HandleFunc("POST /register", ...). No third-party router, no framework — just the stdlib.

package main

import (
    "database/sql"
    "log"
    "net/http"

    _ "github.com/jackc/pgx/v5/stdlib"
)

func main() {
    db, err := sql.Open("pgx", "postgres://user:pass@localhost:5432/register")
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()

    mux := http.NewServeMux()
    mux.HandleFunc("POST /register", registerHandler(db))

    log.Println("listening on :8080")
    log.Fatal(http.ListenAndServe(":8080", mux))
}

One detail in passing: sendWelcomeEmail is a stub here, the same way mailer.js was on the Express side — nothing to dwell on.

3. What jumps out

Now that we have both versions side by side, a few contrasts show up right away. No need to dig — they're right on the surface.

First, the types. In Go, RegisterInput and RegisteredUser are declared, in black and white, at the top of the file. The shape of the expected data isn't a tacit convention or a comment — it's written down, and the compiler enforces it. On the Express side, req.body is a dynamic object: its shape exists in your head, maybe in a comment, but nowhere does the language check it for you. That's what I like here: I don't have to guess what RegisterUser wants — the signature tells me.

Next, the errors: if err != nil everywhere, an error you return instead of throwing. I like seeing every possible failure written right there, in the flow — but it's a big topic, and it's the whole subject of the next deep dive in this series.

Something else that's missing: a framework. No Express, no equivalent. net/http comes from the standard library, and the POST /register routing you saw in main.go has been built in since recent versions of Go — zero HTTP dependencies to install. That changes the nature of the project: the router is nobody's business but the stdlib's. And there's a flip side I appreciate: no framework version to track, no breaking change to brace for at every upgrade.

Last point, the plain SQL with database/sql: the queries are spelled out in full inside RegisterUser, not tucked away behind an ORM. I'll admit I like seeing exactly what goes to the database, with no layer to guess at — but that too is a big subject of its own, for another day.

4. The proof it runs

Here's the test from the Express side, restated as a question: can you test this rule without starting an HTTP server? On the Express side the answer turned out to be yes, once the logic was out of the handler. Let's see what it looks like in Go.

package main

import (
    "errors"
    "testing"
)

// Validation happens before any DB access: no database and no server needed.
func TestRegisterUser_RejectsShortPassword(t *testing.T) {
    _, err := RegisterUser(nil, RegisterInput{Email: "ada@example.com", Password: "123"})
    if !errors.Is(err, ErrValidation) {
        t.Fatalf("expected ErrValidation, got: %v", err)
    }
}

Look at what doesn't happen. go test, and that's it: no server starting up, no database to spin up. The first argument passed to RegisterUser is literally nil — no connection, no mock, nothing. And it works, because the email and password validation fires before the code ever touches db. The business rule is checked in a few milliseconds, and it can fail for one reason only: itself.

It's the same demonstration as on the Express side, with node:test on registerUser. Change the language, keep the gesture: decouple the logic from the framework, and the test becomes trivial to write.

5. What's next

One thread was left deliberately taut in this piece: if err != nil, everywhere, at every call that can fail. A pleasure or a chore? That's the whole subject of the next deep dive.

If I had to sum up the feeling of this comparison in one sentence: on the Go side, everything is written down, nothing is hidden. The types, the errors, the SQL queries, the routing — it's all there, in front of you, in the file. At first it throws you a little; there are more lines to read. After a while, I find it restful: I never have to wonder what's happening behind a decorator or an ORM, because the answer is always in the file open in front of me.

The series continues.

Want to run the whole thing yourself? The full journey — Express before/after plus this Go version, both runnable from a clean clone — lives in the free node-to-go-starter repo, with a one-page Express→Go cheat sheet. Grab it here: https://github.com/bu7ch/node-to-go-starter.

DEV Community: Rodolphe D.

Pourquoi ton code n'a pas besoin d'aller sur la Lune (KISS)

TL;DR

Le code "avant" (le péché)

Le refactor "après" (la rédemption)

Le piège à éviter (petite mise en garde)

Build One Ugly System. It'll Teach You More Than 10 Tutorials.

What "System" Actually Means

Why Tutorials Can't Fix This

🚫 Trap 1: Blind Copy-Paste

🚫 Trap 2: Disguised Tutorial Hell

🚫 Trap 3: Fear of the Real Codebase

Why Bother

Judgment Beats Speed

Building a Choose-Your-Own-Adventure API with NestJS — Part 4: Auth

Retiring DEFAULT_PLAYER_ID

Two new pieces: Passport and Guards

Hashing passwords

The JWT strategy

A custom decorator: @CurrentUser()

Where I expect to get stuck

What's next

Building a Choose-Your-Own-Adventure API with NestJS — Part 3: Game Logic

Where the rules were hiding

Why not just add it to ProgressService?

XpService: the level formula

BadgeService: unlocking without duplicating

Wiring it into advance()

Custom exceptions for domain errors

What's next

Pourquoi ton code sent le copier-coller (DRY)

TL;DR

Le code "avant" (le péché)

Le refactor "après" (la rédemption)

Le piège à éviter (petite mise en garde)

Building a Choose-Your-Own-Adventure API with NestJS — Part 2: Persistence

The problem with Part 1

Picking the pieces

The entity

Wiring TypeORM into the module

The repository pattern

A temporary shortcut: no auth yet

Migrations vs. synchronize: true

What's next

Building a Choose-Your-Own-Adventure API with NestJS — Part 1: The Foundation

Why a text adventure API?

Where I was starting from

The four building blocks

1. Controllers — the front door

2. Providers (services) — where the logic lives

3. Dependency Injection — the part that felt like magic

4. Modules — the glue

The part that actually tripped me up: validation

Where I got stuck

What's next

Ton premier vrai backend Go : fil rouge part 1 — le squelette

Ce que Go t'oblige à faire que Node te laissait éviter : les erreurs explicites

1. Ce qu'on construit (et ce qu'on laisse pour plus tard)

2. L'arborescence

3. Le repository — SQL, point

4. Le service — les décisions

5. Le handler — HTTP only

6. Le câblage — main lit comme une recette

7. Où tu branches la suite (sans la coder aujourd'hui)

8. Ce qu'il faut retenir

Handler / service / repository expliqué à un dev Express

Pourquoi tes routes Express deviennent illisibles (et le seul geste qui les sauve)

1. Le problème après le premier geste

2. Les trois rôles, en français de café

3. Le même register, découpé

Repository — la base, rien d'autre

Service — les règles du produit

Handler — le traducteur HTTP

4. Ce que ça change concrètement

5. Et en Go, c'est la même carte

6. Quand ne pas faire ça

7. Ce qu'il faut retenir

Ce que Go t'oblige à faire que Node te laissait éviter : les erreurs explicites

De Node à Go : le même POST /register, côte à côte

1. Ce que Node te laisse faire (et que tu fais)

Retiring `DEFAULT_PLAYER_ID`

A custom decorator: `@CurrentUser()`

Wiring it into `advance()`

Migrations vs. `synchronize: true`

6. Le câblage — `main` lit comme une recette

4. `errors.Is`, wrapping, et pourquoi `fmt.Errorf("%w")`

7. Mini-exercice : le piège du `_`