astra_dart 0.1.0

A modern, type-safe web framework for Dart inspired by FastAPI. Features include dependency injection, auto-generated OpenAPI docs, and generic controllers.

Astra 🚀

⚠️ 实验性项目：Astra 目前处于早期开发阶段，API 可能会发生变化。欢迎尝试并反馈 Issues！

Astra 是一个受 FastAPI 启发的现代 Dart Web 框架。 它利用 Dart 的 AOT 编译性能和强类型系统，提供极佳的开发者体验 (DX)。

English Documentation

✨ 核心特性

• 直观的路由定义：使用 @Get, @Post 等注解定义路由，类似 FastAPI/NestJS。
• 依赖注入 (DI)：内置强大的 DI 容器，支持单例和请求级作用域，自动注入 Controller 构造函数依赖。
• 类型安全参数：自动解析并转换 @Path, @Query, @Body 参数。
• 智能返回值：直接返回 DTO 对象或 Future<T>，框架自动处理 JSON 序列化。
• 自动文档 (OpenAPI)：开箱即用的 Swagger/OpenAPI 支持，访问 /docs 即可查看漂亮的 API 文档 (基于 Redoc)。
• 零运行时反射：使用 build_runner 在编译时生成代码，完美支持 Dart AOT 和 Native 部署。
• 中间件支持：兼容标准 shelf 中间件 ecosystem。

📦 安装

在 pubspec.yaml 中添加依赖：

dependencies:
  astra: ^0.1.0
  shelf: ^1.4.0

dev_dependencies:
  build_runner: ^2.4.0
  # 其他生成器依赖...

🚀 快速开始

1. 定义 Controller (lib/src/user_controller.dart)

import 'package:astra_dart/astra.dart';
import 'package:shelf/shelf.dart';

part 'user_controller.g.dart'; // 引用生成的文件

// 定义 DTO
class UserDto {
  final String name;
  final String email;
  UserDto({required this.name, required this.email});
  
  Map<String, dynamic> toJson() => {'name': name, 'email': email};
  factory UserDto.fromJson(Map<String, dynamic> json) => UserDto(
    name: json['name'], 
    email: json['email']
  );
}

@Controller('/users')
class UserController {
  
  // 依赖注入 (假设 UserService 已注册)
  final UserService userService;
  UserController(this.userService);

  @Get('/:id')
  Future<UserDto> getUser(@Path() String id, @Query() bool details) async {
    return userService.findUser(id, details: details);
  }

  @Post('/')
  Future<UserDto> createUser(@Body() UserDto body) async {
    return userService.create(body);
  }
}

2. 运行代码生成

在终端运行：

dart run build_runner build

这将生成 user_controller.g.dart，其中包含路由注册和依赖注入的工厂代码。

3. 创建应用入口 (bin/main.dart)

import 'package:astra_dart/astra.dart';
import 'package:your_project/src/user_controller.dart'; 

void main() async {
  // 1. 初始化 App 和依赖
  final app = AstraApp(
    providers: [
      UserService(), // 注册服务
    ],
  );

  // 2. 注册 Controller (使用生成的辅助函数)
  registerUserController(app);

  // 3. 启动服务器
  await app.listen(8080);
}

�️ 开发工具

1. 准备数据库 (必须)

项目默认依赖 Postgres。请确保本地已有运行的实例，并创建 astra_todo 数据库。 快速启动命令：

docker run --name astra-postgres \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=astra_todo \
  -p 5432:5432 \
  -d postgres

2. 启动开发服务器 (热重载)

无需手动重启，使用 dev 命令监听文件变更：

dart bin/astra.dart dev -t example/server.dart

🔒 认证与安全 (Authentication)

Astra 提供了基于 AuthService 和中间件的认证机制。

1. 实现 AuthService: 定义如何签名和验证 Token。
2. 启用中间件: 在 AstraApp 中添加 authMiddleware。支持白名单配置。
3. 获取用户: 控制器中直接使用 req.user。

// 启用认证，并允许 /login 和 /docs 直接访问
authMiddleware(authService, whitelist: ['/login', '/docs'])

@Get('/me')
Future<UserDto> getMe(Request req) async {
  final user = req.user!; // 获取当前登录用户
  return UserDto(id: user.id);
}

📚 API 文档

启动服务后，访问：

• API 文档 UI: http://localhost:3000/docs
• OpenAPI JSON: http://localhost:3000/openapi.json

🛠️ 异常处理

直接抛出异常，框架会自动转换为对应的 HTTP 响应：

@Get('/error')
void testError() {
  throw BadRequestException('Invalid input'); // 返回 400
  // 或者 throw NotFoundException('User not found'); // 返回 404
}