Skip to content

Diana Documentation

Diana is a Spring-inspired, annotation-driven backend framework for Dart. Everything — dependency injection, routing, middleware wiring, validation — is resolved at compile time by a code generator. There is no reflection and no runtime container: configuration mistakes are build errors, and startup is instant.

Where to start

If you want to… Read
Install Diana and serve your first request in 5 minutes Getting started
Build a complete API step by step Tutorial: build a bookstore API
Understand one feature in depth The guides
Look up an annotation, class or error message The reference
Understand how the generator works inside Architecture
Fix a build or runtime problem Troubleshooting & FAQ

Guides

Task-oriented explanations of each feature:

  • Dependency injection — providers, scopes, interface binding, qualifiers, the generated context
  • Controllers and routing — routes, parameter binding, request bodies, return types, status codes
  • Middleware — the Middleware interface, global and per-route chains, ordering, short-circuiting
  • Configuration — application.yaml, environment overrides, @Value, @ConfigurationProperties
  • Validation — constraint annotations, cascading, the error response format
  • Error handling — the HttpException hierarchy, @ControllerAdvice, the exception pipeline
  • WebSockets — @WebSocketController, the handler lifecycle, sessions, broadcast patterns, handshake interceptors
  • STOMP messaging — STOMP 1.2 over WebSockets: @MessageMapping/@SendTo, an in-memory topic broker, StompPublisher
  • Application lifecycle — @PostConstruct/ @PreDestroy, graceful shutdown, DianaApp, test overrides
  • Application events — @EventListener, the injectable DianaEventPublisher, cross-isolate broadcast
  • CORS and static files — @CrossOrigin, preflight, static serving and SPA fallback
  • Content negotiation — BodyCodec, @Consumes/@Produces, the built-in XML codec
  • Server-Sent Events — Stream returns, heartbeats, disconnect handling
  • gRPC — @GrpcService, package:diana_grpc, serving gRPC next to HTTP
  • Authentication & authorization — diana_auth, pluggable strategies (JWT/Basic/API key), @Secured/@RolesAllowed, @Principal
  • Persistence — diana_data, injectable Database over knex_dart, @Transactional, migrations
  • Aspects — @Timed, @Cacheable, @Retryable, @CircuitBreaker on service methods, composed at compile time
  • Observability — diana_observability (Prometheus metrics, OpenTelemetry tracing, liveness/readiness), /actuator/health//info, @Scheduled tasks
  • OpenAPI — the build-time generated spec and /openapi.json
  • Operations — HTTPS, multi-isolate serving, configuration profiles
  • JSON serialization — the fromJson/toJson convention, json_serializable interop
  • Testing — unit tests, wiring tests, end-to-end HTTP tests

Reference

Complete API documentation — every public symbol and every diagnostic:

  • Annotations — all annotations with fields, defaults, targets and examples
  • Runtime API — every public class and function in package:diana (and package:diana_grpc)
  • Generated code — what the generator emits, naming conventions, part directives
  • Build diagnostics — every build error Diana can report and how to fix it
  • Configuration keys — every server.*, management.*, grpc.* and profile key Diana reads

Requirements

  • Dart SDK 3.6 or later
  • build_runner (code generation)

Versioning and stability

Diana is currently 0.15.1. APIs may change before 1.0.0. The roadmap lists what's planned.