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:
- spring_boot_starter_web is a web server. On a
@RestControllerclass, the method above answersGET /books/978-0. - spring_boot_starter_feign is an HTTP client. On a
@FeignClientinterface, the method above sendsGET /books/978-0and reads the answer into aBook.
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
- Mapping annotations:
@GetMapping,@PathVariable,@RequestParam,@RequestBodyand the rest, for servers and clients. - Controller annotations:
@RestController,@ResponseStatus,@ExceptionHandler,@ControllerAdvice,@CrossOrigin. - HTTP types:
ResponseEntity,HttpHeaders,HttpStatus,MediaType,ProblemDetail, multipart. - HTTP transport:
HttpTransport, timeouts, streaming responses. - Server-sent events:
EventStream<T>, reconnection, the decoder. - WebSocket transport:
WebSocketTransport,WebSocketSession, limits. - Server side:
ServerHttpRequest,HandlerMapping,PathPattern,RequestDeadline,AllowedOrigins. - Testing:
MockHttpTransport,MockWebSocketTransport, server mocks. - Differences from Spring: what works differently than in Spring Web.
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.