spring_web_dart

spring_web_dart is the shared web vocabulary of the Spring for Dart packages: the annotations that describe an HTTP call, the types of HTTP itself (headers, status codes, media types, response bodies, errors), and clients that send HTTP and WebSocket requests on the VM, in Flutter and in the browser.

Why

You describe an HTTP endpoint once, with annotations on a Dart method:

@GetMapping('/books/{isbn}')
Future<Book> find(@PathVariable() String isbn);

Two other packages read the same annotations from opposite sides:

Keeping the vocabulary in its own package lets the server, the clients, the WebSocket starter and libraries share it without depending on each other, and lets a Flutter app use the clients without a server.

Setup

Most applications never add this package by hand: it comes with the web, Feign and WebSocket starters, which re-export it. Add it directly when you want only the HTTP and WebSocket clients, or when you write a library that reads the annotations or works with the server types.

# pubspec.yaml
dependencies:
  spring_web_dart: ^0.9.0

Its only dependency is spring_core_dart, and it needs no code generation by itself. Imports:

Import Holds
package:spring_web_dart/spring_web_dart.dart Everything, with platformHttpTransport() and platformWebSocketTransport().
package:spring_web_dart/io.dart IoHttpTransport, IoWebSocketTransport (dart:io).
package:spring_web_dart/browser.dart FetchHttpTransport, BrowserWebSocketTransport.
package:spring_web_dart/testing.dart MockHttpTransport, MockWebSocketTransport, MockServerHttpRequest, MockServerHttpResponse, MockMultipartFile, WebSocketSessionPair.

Example

With this package alone you can send HTTP requests from any platform:

import 'package:spring_web_dart/spring_web_dart.dart';

Future<void> main() async {
  final transport = platformHttpTransport();
  final response = await transport.send(
    HttpRequest(
      method: HttpMethod.get,
      url: Uri.parse('https://api.neon.books/books/978-0'),
      headers: HttpHeaders({HttpHeaders.acceptHeader: MediaType.applicationJson}),
      timeout: const Duration(seconds: 5), // give up on a slow server
    ),
  );
  // Every status is a response; only network failures throw.
  if (response.statusCode.is2xxSuccessful) print(response.bodyText);
  transport.close();
}

HttpHeaders, HttpStatus, HttpRequest and HttpResponse have the same names as classes of dart:io. In a file that needs both, import dart:io with a prefix (import 'dart:io' as io;) or hide them.

Configuration

spring_web_dart has no properties of its own: it is a library of types, configured in code (platformHttpTransport(connectTimeout:), IoWebSocketTransport(maxTextMessageSize:)). The starters that use it read properties for it: server.* and spring.mvc.* in the web starter, spring.feign.* in the Feign starter, spring.websocket.client.* in the WebSocket starter.

What is inside

In Spring (Java)

In Spring these types are spread over spring-web (annotations, ResponseEntity, HttpHeaders, ProblemDetail), spring-webmvc and spring-websocket. Here they are one small package that runs everywhere Dart runs, browser included. The annotations take Dart's shape: .of constructors for named attributes, and no required or defaultValue.

See also