@Log

@Log() (from spring_core_dart) gives a class a log getter that returns a SpringLog, like Lombok's @Slf4j in Java. The generator writes the getter as an extension on the class, in the .spring.dart file of the @ComponentScan or @SpringBootApplication that scans the class.

Why

A class that logs needs a logger, usually a constant such as const log = SpringLog('my_app.Checkout');. Writing it by hand in every class repeats the class name, and the name goes stale when the class is renamed or moved. Dart cannot add a field to a class from outside, but an extension can add a getter. So the generator writes one extension per @Log class, with the logger name computed at build time.

Example

// lib/src/checkout.dart in the package my_app
import 'package:spring_core_dart/spring_core_dart.dart';

import '../spring_gen/main.spring.dart'; // where the extension is

@Service()
@Log()
class Checkout {
  void pay(double amount) => log.info('paid $amount');
}

// Not a bean: @Log works on any class of the scan.
@Log(topic: 'neon.payments', fieldName: 'logger')
class Payments {
  void refund() => logger.warning('refund');
}

The generator writes, into the .spring.dart file of the scan (simplified: the real file uses import prefixes such as _i1.):

/// `@Log` of [Checkout]: the logger 'my_app.Checkout'.
extension $CheckoutLog on Checkout {
  SpringLog get log => const SpringLog(r'my_app.Checkout');
}

/// `@Log` of [Payments]: the logger 'neon.payments'.
extension $PaymentsLog on Payments {
  SpringLog get logger => const SpringLog(r'neon.payments');
}

Inside the class, log.info(...) calls the extension's getter. The getter returns a constant, so there is no object per instance and no lookup at run time.

A real excerpt, from the spring_core_dart example (example/spring_gen/main.spring.dart), for two classes with @Log(topic: 'tour'):

/// `@Log` of [WelcomeMail]: the logger 'tour'.
extension $WelcomeMailLog on _i2.WelcomeMail {
  _i1.SpringLog get log => const _i1.SpringLog(r'tour');
}

/// `@Log` of [Tour]: the logger 'tour'.
extension $TourLog on _i2.Tour {
  _i1.SpringLog get log => const _i1.SpringLog(r'tour');
}

The arguments

Argument Default Effect
topic: <package>.<Class> the logger name passed to SpringLog
fieldName: log the name of the generated getter

The default logger name is the package name and the class name: my_app.Checkout for a class in any library of the package my_app (the folder below lib/ does not count). For a library outside lib/, which has no package: URI (a file in bin/, example/ or test/), the file name without .dart is used instead of the package: a class Tour in bin/main.dart logs as main.Tour.

Use topic: to group several classes under one logger, so one setting controls them:

# lib/resources/application.properties
logging.level.neon.payments=debug

Levels follow the dots in the name (neon.payments also covers neon.payments.refunds). See SpringLog.

Use fieldName: when log is taken. dart:math and dart:developer both declare a top-level function log, and a log declared in the library's scope wins over an extension getter. With one of them imported, pick another name: @Log(fieldName: 'logger').

How it works

  1. Which classes. Every class of the libraries a module scans is checked for @Log, bean or not: a @Service, a plain class, a class that the scan's filters do not make a bean. A class outside every scan (for example in a test file) gets no getter.
  2. The checks. The class must be public, fieldName must be a valid getter name, and the class must not already have a member with that name (see Build errors).
  3. The name. The logger name is computed from the library's URI and the class name, unless topic: is given.
  4. The extension. It is named $<Class>Log and written after the module and the application functions. Two @Log classes with the same name in different libraries of one module get $CheckoutLog and $CheckoutLog2, in scan order, so the extensions do not clash.
  5. Generic classes. The extension is on the raw type: @Log() class Repo<T> gives extension $RepoLog on Repo, which matches every Repo<...>.

Importing the getter

An extension is visible only where its library is imported. The class's own library must import the .spring.dart file that scans it:

The class is scanned by Import
@SpringBootApplication in bin/main.dart bin/spring_gen/main.spring.dart
@SpringBootApplication in lib/main.dart package:my_app/spring_gen/main.spring.dart
@ComponentScan in lib/src/beans.dart package:my_app/spring_gen/src/beans.spring.dart

Without the import, log is an unknown name and the class does not compile. A library imported by its generated file and importing it back is a normal import cycle in Dart.

Build errors

A getter that could not work fails the build, with the class as the location. The errors are collected with the other problems of the build and reported together.

Problem Message
a private class @Log on _Hidden: the class is private, so the generated getter (an extension in the .spring.dart file) cannot name it; make the class public or declare the logger yourself: const _log = SpringLog('...');
an invalid getter name @Log on A: fieldName "class" is not a valid getter name (a public Dart identifier that is no reserved word).
a member with the getter's name @Log on C: C already has a member "log", which would win over the generated getter; choose another name with @Log(fieldName: '...').

A valid fieldName starts with a letter or $, then has letters, digits, _ or $. A name starting with _ is refused (the getter would be private to the generated file), and so are Dart's reserved words and built-in identifiers (class, get, set, type, late, required and the others).

The member check looks at the methods, getters, setters and fields of the class and of all its supertypes. A member of a superclass counts too, since a class member always wins over an extension member:

class Base {
  void log() {}
}

@Log() // ✗ @Log on D: D already has a member "log", ...
class D extends Base {}

In Spring (Java)

@Slf4j(topic = "neon.payments")
class Payments {
  void refund() { log.warn("refund"); }
}

Differences that matter:

See also