
# 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:

```text
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:

```dart
@Aspect()
@Component()
class Audit {
  @Before('execution(* *(..)) &&')
  void log() {}
}
```

```text
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`:

```text
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:

```dart
class Form {
  @NotBlank()
  int age = 0;
}
```

```text
@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](../spring-core-dart/validation/constraints.md).

## JSON

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

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

  @JsonValue()
  String get b => '';
}
```

```text
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](../spring-core-dart/json/index.md).

## 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.

```dart
@Component()
class Sounds {
  Sounds(@Value('asset:assets/sounds/tap.mp3') this.tap);
  final Resource tap;
}
```

```text
@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:

```text
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](auto-configurations.md#the-requires-check).

## 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:

```dart
@Service()
class _Greeter {}
```

```text
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](data.md).

## 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

- [Errors and the generated files](errors.md)
- [Data: entities, repositories, queries](data.md)
- [Auto-configurations](auto-configurations.md)
- [Pointcuts](../spring-core-dart/aop/pointcut.md)
- [Validation constraints](../spring-core-dart/validation/constraints.md)
