Build-time checks

The generator reads every annotated declaration of the application anyway, so it checks what it can while it is there. A mistake that Spring would report when the application starts, or never, fails the build here, with a message that points at the source element and says how to fix it.

Why

A configuration mistake found at build time costs a few seconds. Found at startup it costs a run of the app; found in production, much more. And some mistakes would not fail at all: a pointcut with a typo that matches nothing, a constraint on a type it cannot check, an asset that is missing from the bundle. The build turns these into errors.

What depends on the whole running application is left to the startup: missing or ambiguous beans and dependency cycles are reported when the context starts, before any of your objects is created.

All problems at once

The scanner does not stop at the first bad declaration. It collects the independent problems of a build and reports them together:

2 problems in this build:

1. Bean class Broken must not be abstract (an abstract class is a bean only
   when it has @Lookup methods for the container to implement).
   package:app/src/broken.dart:3:16
   ...

2. Injected field clock must be settable: declare it `late final` or
   non-final.
   package:app/src/report.dart:5:15
   ...

Each entry has its message, the library URI and the location. A build with a single problem reports that problem alone.

AOP

Every advice expression, every @Pointcut and every @Aspect('perthis(...)') clause is parsed with the runtime's own parser (ExpressionPointcut of spring_core_dart). A pointcut the build accepts is accepted at startup. A syntax error names the aspect, the advice and the character position:

@Aspect()
@Component()
class Audit {
  @Before('execution(* *(..)) &&')
  void log() {}
}
The pointcut of before advice Audit.log is invalid: Invalid pointcut
(unexpected end of expression) at character 21 of 'execution(* *(..)) &&'

An unknown designator is reported the same way (unknown designator 'frobnicate'), and so is a bad @Pointcut:

The @Pointcut Audit.bad is invalid: ...

execution type patterns are checked too (String||int without parentheses, Animal+). A reference to a named pointcut of a class the build cannot see (another package's holder class) is left to the runtime.

Validation constraints

A constraint on a type it cannot check fails the build, as Hibernate Validator would fail at validation time:

class Form {
  @NotBlank()
  int age = 0;
}
@NotBlank on Form.age: it validates String values, not int (like Hibernate
Validator's UnexpectedTypeException). Remove it or change the type.

So do invalid attributes:

Declaration Message
@Size(min: -1) Invalid @Size on Form.name: the min parameter cannot be negative (Hibernate Validator rejects it when validating).
@Size(min: 5, max: 2) ... min (5) is greater than max (2) ...
@Digits(integer: -1, fraction: 2) ... the length of the integer part cannot be negative ...
@DecimalMin('abc') ... "abc" is not a decimal number ...
@Matches('[a-') ... invalid regular expression "[a-" ...
@Each(...) on a type with no elements @Each on Form.tags: it constrains the elements of an Iterable or the values of a Map, not String. Remove it or change the type.

See Validation constraints.

JSON

@JsonValue makes a class be written as one value, so a class can have only one, on a member it can work on:

class Isbn {
  @JsonValue()
  String get a => '';

  @JsonValue()
  String get b => '';
}
Isbn has more than one @JsonValue (a, b); like Jackson, a class can be
written as one value only.

Other cases, each as @JsonValue on <Class>.<member> ...: on a setter (is a setter; mark the field or getter), on a method of an enum, on a method with required parameters, on a private member (is private, so generated code cannot read it), on a static member. An enum with both a @JsonValue and @JsonProperty names on its constants fails too. See JSON.

Flutter assets

A literal @Value('asset:<key>') (of spring_boot_starter_flutter) is checked against the package: the file must exist, and pubspec.yaml must declare it under flutter: assets:, or the app would not contain it.

@Component()
class Sounds {
  Sounds(@Value('asset:assets/sounds/tap.mp3') this.tap);
  final Resource tap;
}
@Value('asset:assets/sounds/tap.mp3') in package:app/src/sounds.dart#Sounds:
assets/sounds/tap.mp3 is not declared in pubspec.yaml, so the app would not
contain it. Add it under `flutter: assets:`:

flutter:
  assets:
    - assets/sounds/

A missing file gives ... there is no file assets/sounds/tap.mp3 in the package app. Keys with placeholders and other packages' assets (packages/...) are not checked: only the running app knows them.

Starters

A starter's requires range is checked against the spring_boot_dart version in use:

Incompatible starter: neon_cache requires spring_boot_dart ^0.8.0, but 0.7.1
is used.
Upgrade spring_boot_dart to a version in ^0.8.0, or use a version of
neon_cache made for spring_boot_dart 0.7.1 (see its CHANGELOG / pub.dev
versions).

An invalid range, and a starter with requires in an application that does not depend on spring_boot_dart, fail too. See Auto-configurations.

Declarations

Mistake Message (start)
@Component (or @Service, ...) on a mixin, enum, extension or extension type @Service on mixin Audit of package:app/src/audit.dart: only classes can be beans; ...
@Bean on a top-level function @Bean on top-level function clock of package:app/src/clock.dart: @Bean methods belong to a class with @Configuration or @Component; move it there (as an instance or static method).
@ComponentScan on anything but a top-level variable @ComponentScan on class AppBeans of package:app/src/beans.dart: put it on a top-level variable holding the generated module, e.g. followed by @ComponentScan() final BeanModule appBeans = $appBeans;
Two @ComponentScan in one file Only one @ComponentScan is allowed per file.
Two @ComponentScan roots in one directory Two @ComponentScan roots in lib/src/: lib/src/a.dart and lib/src/b.dart. A directory has one scan root; remove one, or move it into a subdirectory (which the other then imports).
A private scan variable, or one starting with $ @ComponentScan variable must be public and must not start with $.
An empty, blank or space-padded bean name or alias ... is empty: give a name, or remove it to use the default name 'clock'., or ... ' clock' starts or ends with whitespace: use 'clock'.
Two unconditional beans with one name Bean name 'clock' is used by both SystemClock and FixedClock.
An injected field that cannot be set Injected field clock must be settable: declare it `late final` or non-final.
A nullable @Lazy dependency @Lazy on repo: a lazy dependency cannot be nullable; use ObjectProvider<Repository> for an optional lazy bean.
Injecting or returning an extension type Cannot inject extension type Id into ...: extension types are erased at runtime, so the container cannot ...
An abstract bean class without @Lookup methods Bean class Broken must not be abstract ...

Beans with conditions (@Profile('dev') and @Profile('prod') both declaring dataSource) may share a name: the container registers those whose conditions match.

Private declarations

Generated code lives in another library, so it cannot name a private declaration (_Foo, _default). Instead of writing a file that does not compile, the build fails with a message that names the declaration, its library and the fix:

@Service()
class _Greeter {}
Bean class _Greeter must be public: the generated module cannot reference a
private class of package:app/src/greeter.dart. Make it public, or move it out
of the scanned directory.

The same holds for a private @Bean return type, an injected type (also as a type argument), an event type, an advice parameter type, and a default value that is a private function, class or constructor. The fixes offered are: make it public, move it out of the scan, declare a public supertype, or drop the default.

Data repositories

The data starter's repositories, derived queries and @Query texts are checked as well, with "did you mean" suggestions. See Data: entities, repositories, queries.

Clean generated code

The generated code is free of analyzer warnings and of the package:lints recommended lints. It still ignores type=lint, because your own lint set may differ.

See also