Temps, localisation et journalisation

Comprendre le mécanisme

Instant représente un point sur la ligne du temps ; LocalDateTime représente une date et une heure sans fuseau. Un ZoneId fournit les règles nécessaires à une conversion locale. Une période calendaire et une durée en secondes ne sont pas interchangeables autour des changements d’heure. Les objets java.time sont immuables : une méthode d’ajout retourne une nouvelle valeur.

Raisonner et vérifier

Séparez représentation machine stable et affichage destiné à une locale. Une virgule décimale ou un mois traduit ne doit pas être réinterprété comme un protocole universel. Un ResourceBundle résout des ressources localisées avec une stratégie de repli. Les logs doivent utiliser une corrélation et des champs minimisés ; une API de journalisation ne dispense pas d’éviter les secrets.

Représenter un instant ou une date locale

Instant représente un point sur la ligne du temps, alors qu’une LocalDateTime décrit des composantes locales sans identifier seule un instant mondial unique. Le choix dépend du besoin : un anniversaire n’a pas le même modèle qu’une expiration de token. Définissez le sens de la donnée avant sa sérialisation. Ajouter un format d’affichage ne fournit pas le contexte de zone qui manque à une valeur locale.

Le fuseau est un ensemble de règles

ZoneId désigne des règles de zone qui peuvent dépendre de la date. Ne le réduisez pas à un décalage constant simplement parce qu’un exemple d’hiver utilise une valeur donnée. Pour convertir une date locale en instant, choisissez la zone de référence prévue par le contrat. Les échanges machine doivent porter suffisamment d’information pour éviter qu’un serveur et un client appliquent silencieusement deux contextes différents.

Heures absentes et heures répétées

Un changement d’heure peut créer une période locale absente ou répétée. Un rendez-vous représenté uniquement par des composantes locales peut donc demander une politique explicite pour être interprété. Testez une date ordinaire et une date proche d’une transition avec les règles de la zone ciblée. L’affichage plausible ne constitue pas une preuve : plusieurs interprétations peuvent exister selon la représentation et les choix du consommateur.

Rendre le temps testable

Une horloge injectée permet de vérifier une limite d’expiration sans attendre réellement son échéance. Le test peut se placer juste avant, exactement à la borne et juste après. Ces cas doivent correspondre à la règle du produit. Évitez de changer l’heure globale d’un environnement partagé pour un exercice : une dépendance temporelle contrôlée donne une preuve plus reproductible et un périmètre plus clair.

Calendrier, durée et immuabilité

Period et Duration expriment des modèles différents, notamment unités calendaires et durée temporelle. Un mois n’est pas toujours trente jours. Les objets de date comme LocalDate sont immuables : plusDays retourne une nouvelle valeur et ne modifie pas l’objet initial. Conservez donc le résultat lorsque vous voulez le changement. Testez les fins de mois et les années bissextiles pour vérifier les hypothèses de votre calcul.

La locale organise une présentation

La locale porte des conventions de langue et de formatage ; elle ne remplace pas un fuseau ni l’instant lui-même. Deux utilisateurs peuvent afficher différemment une même donnée machine. Gardez le protocole d’échange séparé de cette présentation pour éviter qu’une virgule, un nom de mois ou un ordre de composantes local change la valeur interprétée par un autre service.

Une grammaire d’échange explicite

Le format machine doit annoncer sa grammaire et les informations de zone ou décalage nécessaires. Une chaîne lisible par un humain n’est pas forcément non ambiguë pour tous les parseurs. Définissez la politique de refus d’une entrée invalide au lieu de tenter plusieurs interprétations au hasard. Les fixtures doivent couvrir des valeurs limites et des variantes qui semblent proches mais n’appartiennent pas au format accepté.

Représenter exactement les montants

Un float binaire ne garantit pas les calculs décimaux exacts d’un paiement. Pour un échange PHP et Java, choisissez unité, type, bornes et arrondi. Un PSP qui demande un entier dans l’unité mineure ne doit pas recevoir une conversion implicite depuis un affichage localisé. La devise et son contrat d’unité doivent accompagner le montant ; toutes les devises ne suivent pas nécessairement la même règle d’exposant.

Les règles peuvent évoluer

Les données de fuseau reflètent des règles civiles susceptibles d’être mises à jour. Une application doit donc suivre les versions et le sens de ses données historiques ou futures. Ne supposez pas qu’un décalage observé aujourd’hui restera la bonne règle pour un événement futur. Lors d’une mise à jour, testez les zones et dates importantes pour le produit plutôt que seulement une date locale proche de l’exécution.

Comparer dans un modèle cohérent

Pour une expiration, comparez des valeurs dans un modèle temporel commun, avec une horloge et une tolérance documentées lorsque le protocole l’exige. Trier des chaînes locales de zones différentes ne prouve pas l’ordre des instants. La décision doit aussi préciser si la borne est inclusive ou exclusive. Les tests aux frontières rendent cette règle visible et empêchent qu’un format d’affichage décide implicitement d’un droit d’accès.

Atelier guidé : lire, expliquer et vérifier le code

import java.time.LocalDate;
class Main {
    public static void main(String[] args) {
        var date = LocalDate.of(2024, 2, 28).plusDays(1);
        System.out.print(date);
    }
}

Le programme part du 28 février 2024 et produit une nouvelle LocalDate en ajoutant un jour. Cette année étant bissextile, le résultat affiché est le 29 février. L’objet initial n’est pas modifié par plusDays ; c’est la valeur retournée qui est affectée à date dans l’exemple. Aucune zone n’est nécessaire pour ce calcul de date calendaire.

Conservez séparément la date initiale et le résultat pour vérifier leur indépendance. Essayez ensuite une fin de mois ordinaire. Pour une expiration réelle, changez de modèle et utilisez un instant avec une horloge contrôlée : une réussite sur une date locale ne démontre pas la bonne interprétation d’une heure ambiguë dans un fuseau. Chaque représentation doit correspondre à la question temporelle effectivement posée.

Montants PHP/Java : exactitude et unité contractuelle

Un montant doit porter une devise et une unité explicites. Dans le contrat posé, le PSP attend un entier d’unité mineure ; multiplier toujours par cent est incorrect pour les devises ou opérations dont l’exposant contractuel diffère.

Utilisez une représentation exacte : entier borné dans l’unité définie, ou décimal exact à la frontière de conversion avec règle d’arrondi explicite. En Java, construisez BigDecimal depuis une chaîne décimale lorsque nécessaire et vérifiez la conversion exacte vers l’entier du contrat. En PHP, évitez de passer par float pour reconstruire les centimes d’une chaîne utilisateur.

Testez devise à deux décimales, devise sans décimales et dépassement de capacité. Les limites d’API et les règles particulières du fournisseur doivent être vérifiées pour le type d’opération concerné. Une valeur exacte dans la mauvaise devise reste erronée ; un montant positif ne prouve pas non plus que l’acteur a le droit de débiter ou rembourser cette somme.

Points de vigilance : Les flottants binaires et la règle universelle de deux décimales introduisent des erreurs. Sans devise, l’unité et les opérations autorisées deviennent ambiguës. Une représentation de présentation locale n’est pas un contrat machine universel. Des unités explicites et une arithmétique exacte rendent les conversions vérifiables ; gérer également arrondis et dépassements.