@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
- 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. - The checks. The class must be public,
fieldNamemust be a valid getter name, and the class must not already have a member with that name (see Build errors). - The name. The logger name is computed from the library's URI and the class name, unless
topic:is given. - The extension. It is named
$<Class>Logand written after the module and the application functions. Two@Logclasses with the same name in different libraries of one module get$CheckoutLogand$CheckoutLog2, in scan order, so the extensions do not clash. - Generic classes. The extension is on the raw type:
@Log() class Repo<T>givesextension $RepoLog on Repo, which matches everyRepo<...>.
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:
- Lombok adds a static field to the class while it compiles. Here the generator writes an extension getter in the
.spring.dartfile, which the class's library must import. - The default logger name is
<package>.<Class>, not the fully qualified class name. - Lombok's
@Slf4juses SLF4J. Here the getter returns aSpringLog, the one logging API of Spring for Dart.
See also
- SpringLog: levels, handlers and the logging API.
- Logging
- @ComponentScan modules: which libraries a module scans.