
# Differences from Spring

`spring_boot_dart` follows Spring Boot: the same annotations, the same property names, the same order of the start. This page lists every place where it does not, and why, grouped by topic.

## Why

Most differences come from three facts:

- **Dart has no reflection at run time and no class path.** The package is scanned at build time, starters are discovered at build time, and `lib/resources/` plays the role of the classpath.
- **A Dart program that listens for signals never ends by itself**, which changes the shutdown hook.
- **An old name ignored in silence does harm**, so renamed keys stop the start instead of warning.

## Example

The same application in both:

```dart
@SpringBootApplication()
void main(List<String> args) => runApplication(args);
```

```java
@SpringBootApplication
public class NeonBooks {
  public static void main(String[] args) {
    SpringApplication.run(NeonBooks.class, args);
  }
}
```

## The start

| Spring Boot | Here | Why |
|---|---|---|
| `@SpringBootApplication` on a class; the classpath is scanned at start-up | On the `main` function; the package is scanned by `build_runner`, and the generated `springApplication` lists the beans and starters | No reflection |
| `SpringApplication.run` returns after the runners | `runApplication` returns after the synchronous part; `runApplicationAsync` waits for the runners | Runners may be asynchronous |
| `EnvironmentPostProcessor`s, `FailureAnalyzer`s and listeners in `META-INF/spring.factories` | Passed to the `SpringApplication` constructor (analyzers can also be beans) | No class path to scan |
| A starter's other entries of `META-INF/spring.factories`, read with `SpringFactoriesLoader.loadFactories(type, classLoader)` | Constants in `factories` of its `@AutoConfigurationModule`, copied into the generated `springApplication` by the generator; read with `SpringApplication.factories.load<T>()` or the `springFactories` bean. See [Factories](auto-configuration.md#factories) | No class path to scan |
| `Started app in 0.07 seconds (process running for 0.3)` | Without the process uptime | Dart has no process start time |
| The banner printed to `System.out`; `${application.version}`, `${AnsiColor.*}` in `banner.txt` | `print` (or the log); `${spring-boot.version}`, `${spring-boot.formatted-version}` and environment placeholders | No manifest version, no ANSI property source |
| `spring.main.allow-circular-references=true` | Not supported: a cycle is always an error; use `@Lazy()` or an `ObjectProvider` | No early singleton references |
| No start-up progress hook | `SpringApplication.progressListener` with `StartupProgress` | Splash screens of mobile apps |

## Configuration files and locations

| Spring Boot | Here | Why |
|---|---|---|
| `classpath:` | `resources:` (`lib/resources/`, embedded by the generator) | No class path |
| `.properties` read as ISO-8859-1 | UTF-8; `[encoding=iso-8859-1]` on a location, or `PropertiesPropertySourceLoader(encoding: latin1)` | Dart files are UTF-8 |
| Any Java charset in an encoding hint | UTF-8, ISO-8859-1 and US-ASCII only; another fails the start | Dart's codecs |
| YAML 1.1 (SnakeYAML) | YAML 1.2: `on`, `off`, `yes`, `no` stay strings (still convert to `bool`), `0777` is 777 | The Dart team's YAML parser |
| `application.xml` and `.xml` imports | Not read; `x.xml` fails the start | No `Properties.loadFromXML` |
| `env:` imports, `classpath*:` locations | Not supported | |
| A comment right after `#---` joins the documents | The documents stay apart | Read as written |
| In a `;` group, spaces are kept and an empty entry is the importing directory | Spaces trimmed, empty entries skipped | |
| The resolver of a `;` group comes from its first entry | Each entry is read by its own prefix | |
| A relative import in a wildcard-found file resolves against the pattern | Against that file | |
| A `configtree:` location that is a file fails, even `optional:` | Counts as missing | |
| No `--dart-define` | `--dart-define` values are a source right below the command line | Flutter and web apps have no command line |
| HTTP imports through Spring Cloud Config | `spring.config.import=https://...` with an asynchronous start; no config server client | |

## Profiles

| Spring Boot | Here |
|---|---|
| Spring Boot 4.1 reads `spring.profiles.active`, `.default` and `.group.*` from documents limited to a profile | They fail the start when the document applies, and are ignored when it does not, as Spring Boot's documentation describes |
| Placeholders in `on-profile` and `spring.config.import` resolved once, at the first pass | `on-profile` resolved once the profiles are decided; imports when they are read |
| A profile group list with a gap fails the start | Read up to the gap |
| `Profiles.of` accepts some malformed expressions (`(dev`, `a &`) | They fail with `Malformed profile expression` |
| No platform profiles | Flutter apps get `android`, `ios`, `web`, `macos`, `windows`, `linux`, `mobile`, `desktop` and `debug`, `profile`, `release` |

## Binding

| Spring Boot | Here | Why |
|---|---|---|
| `@EnableConfigurationProperties`, `@ConfigurationPropertiesScan`, getters and setters | None needed; fields are bound directly | The annotation makes the class a bean |
| Constructor binding passes `null` for a missing property | A missing non-nullable scalar stops the start; a missing collection is empty, a missing nested object gets its defaults | Non-nullable types |
| `@ConstructorBinding` picks a constructor | Only a class whose only public generative constructor has parameters | Not implemented |
| `@DurationUnit(ChronoUnit.SECONDS)` | `@DurationUnit(ChronoUnit.seconds)`; no months or years | Dart's `Duration` |
| `BindHandler.onFailure` returns a replacement value | Returns whether the failure counts | Errors are collected and reported together |

## Renamed keys

| Spring Boot | Here |
|---|---|
| `spring.jackson.*` | `spring.json.*` |
| `spring.cloud.openfeign.*` | `spring.feign.*` |
| `spring.servlet.multipart.*` | `spring.web.multipart.*` |
| `server.servlet.*` | `server.*` |
| `logging.logback.rollingpolicy.*` | `logging.file.rolling-policy.*` |
| `spring.flyway.*` | `spring.sql.migration.*` |

`spring-boot-properties-migrator` only warns; here an old name in any source stops the start and names the new key.

## Keys of this project

`spring.messages.default-locale` (apps often have no meaningful system locale), `spring.devtools.restart.enabled` for the Dart VM hot reload, `spring.remote.allow-insecure`, and the default `false` of `spring.main.register-shutdown-hook`.

## Auto-configuration and conditions

| Spring Boot | Here | Why |
|---|---|---|
| `AutoConfiguration.imports` read from the classpath at start-up | `lib/spring_auto_configuration.dart` read at build time; a new starter needs a rebuild | No class path |
| `@AutoConfiguration(before, after)`, `@AutoConfigureOrder` on the class | `order`, `before`, `after` on `@AutoConfigurationModule`; classes named by short name | The module is the unit |
| `exclude` compares classes | A `Type` is compared by its simple name | A `Type` gives only its name at run time |
| `@ConditionalOnBean(annotation = Service.class)` finds meta-annotated beans | The exact annotation class only | Annotations are plain objects |
| `@ConditionalOnClass`, `@ConditionalOnWebApplication` | Not available | A class cannot be looked up at run time |
| The report explains each outcome | It names each condition and whether it matched | Conditions are plain Dart objects |
| No build-time switch | `AutoConfigurationModule(build:)` leaves a module out of a release | Smaller apps |
| Spring Boot's BOM | The release train and `requires` checked at build time | pub resolves one version per package |

## JSON

| Spring Boot | Here |
|---|---|
| `spring.jackson.*` with every Jackson feature | `spring.json.*` with the keys of [Built-in beans](built-in-beans.md); others warned about and ignored |
| Named time zones | Only `UTC` and fixed offsets: Dart has no time zone database |
| `JsonMapperBuilderCustomizer` gets Jackson's builder | It gets the core `JsonMapperBuilder` |

## Logging and shutdown

| Spring Boot | Here | Why |
|---|---|---|
| The shutdown hook is on and runs when the JVM exits | Off by default; only on SIGINT and SIGTERM, then `exit(130)` or `exit(143)` | Dart has no exit hooks, and a signal listener keeps a program alive |
| Logger names are Java packages | Dart library names or the names given to `SpringLog` | |
| Log dates in the local zone | UTC (with the logging starter) | No time zone database |

## Not supported

- `spring.main.allow-circular-references`, `spring.main.web-application-type` other than `none`.
- `env:` imports, XML properties, `.env` files, Spring Cloud Config, Consul and Vault clients.
- `logging.config`, `logging.structured.*`.
- Test slices such as `@WebMvcTest`.

## See also

- [spring_boot_dart](index.md)
- [All properties](properties.md)
- [External configuration](configuration/index.md)
- [Differences of the generator](../spring-core-dart-generator/differences.md)
