# Liora

**Repository Path**: xxkfk/liora

## Basic Information

- **Project Name**: Liora
- **Description**: Liora 是一款专为 Java Web 框架学习设计的轻量级教学框架，其核心目标是通过简化的实现展示 Web 框架的底层工作原理。与生产级框架（如 Spring MVC）相比，Liora 剥离了复杂的企业级特性，保留了 Web 开发的核心流程，使学习者能够清晰理解从请求接收、路由匹配到响应处理的完整链路。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-11-16
- **Last Updated**: 2026-01-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Liora

> ⚠️ **项目正在开发中** | *Currently under development*

Liora 是一个基于 Java 8 和 Undertow 的轻量级 Web 框架，采用响应式编程模型构建。它旨在为开发者提供一个高性能、可扩展且易于使用的 Web 开发平台。

## 目录

- [项目特性](#项目特性)
- [项目状态](#项目状态)
- [技术栈](#技术栈)
- [模块结构](#模块结构)
- [核心组件详解](#核心组件详解)
- [快速开始](#快速开始)
- [详细使用教程](#详细使用教程)
  - [创建控制器](#创建控制器)
  - [处理不同类型的请求](#处理不同类型的请求)
  - [路径参数和查询参数](#路径参数和查询参数)
  - [JSON处理](#json处理)
  - [异常处理](#异常处理)
  - [启动服务器](#启动服务器)
- [架构设计](#架构设计)
- [性能优势](#性能优势)
- [许可证](#许可证)

## 项目特性

### 高性能与轻量级
- **基于 Undertow**: 使用高性能的非阻塞 HTTP 服务器，提供卓越的并发处理能力
- **响应式编程**: 利用 Reactor 框架实现非阻塞异步处理，最大化系统资源利用率

### 现代化设计
- **注解驱动**: 通过简洁的注解系统简化路由配置和请求处理
- **函数式编程**: 支持 Mono 和 Flux 返回类型，充分利用响应式编程优势
- **类型安全**: 强类型设计，编译时捕获更多错误
- **模块化架构**: 清晰的模块划分，便于扩展和维护

### 易用性与可扩展性
- **易于上手**: 简洁的 API 设计，降低学习成本
- **灵活扩展**: 支持自定义处理器、适配器和拦截器
- **统一异常处理**: 完善的异常处理机制
- **详细文档**: 完整的代码注释和使用文档

## 项目状态

该框架目前仍在积极开发中，API 可能会发生变化。我们建议您在生产环境中使用前密切关注更新日志。

## 技术栈

- **Java 8**: 利用 Java 8 的现代特性，如 Lambda 表达式和 Stream API
- **Undertow**: 高性能非阻塞 HTTP 服务器
- **Reactor**: 响应式编程库，实现异步非阻塞处理
- **Fastjson**: 高性能 JSON 处理库，用于请求/响应序列化

## 模块结构

### liora-base
核心注解和基础组件定义模块：
- HTTP 方法注解 (`@GetRoute`, `@PostRoute`, `@PutRoute`, `@DeleteRoute`)
- 路径注解 (`@ClassRoute`)
- HTTP 方法枚举 (`HttpMethod`)
- 通用异常类 (`LioraException`)

### liora-server
服务器核心实现模块：
- 服务器接口及实现 (`LioraServer`, `StandardLioraServer`)
- 请求处理链 (`Handler`, `LioraHandlerContext`)
- HTTP 请求封装 (`HttpRequest`, `StandardHttpRequest`)
- 路由调度管理 (`HttpDispatcher`, `StandardHttpDispatcher`)
- 请求适配器 (`RequestAdaptor`, `StandardHttpAdaptor`)
- 结果写入解析器 (`ResultWriteResolver`, `StandardResultWriteResolver`)
- 控制器调用处理器 (`RouterInvoker`)
- 异常处理机制 (`ErrHandler`, `ErrHandlerDispatcher`, `StandardErrHandlerDispatcher`)

## 核心组件详解

### 注解系统

Liora 提供了一套完整的注解来定义 REST API，使路由配置变得简单直观：

- `@ClassRoute`: 定义控制器的根路径
- `@GetRoute`: 处理 GET 请求
- `@PostRoute`: 处理 POST 请求
- `@PutRoute`: 处理 PUT 请求
- `@DeleteRoute`: 处理 DELETE 请求

### 服务器核心

`StandardLioraServer` 是框架的核心服务器实现，提供以下功能：
- 支持添加自定义处理器和控制器
- 灵活的端口和主机配置
- 基于 Undertow 的高性能 HTTP 服务
- 统一异常处理机制

### 请求处理链

Liora 采用责任链模式处理请求，通过 `Handler` 和 `LioraHandlerContext` 实现处理器链：
- 支持前置和后置处理器
- 统一的异常处理机制
- 灵活的处理流程控制

### 路由调度

`StandardHttpDispatcher` 负责将控制器方法映射到相应的 HTTP 路径和方法：
- 支持路径参数解析
- 灵活的路由匹配机制
- 多种 HTTP 方法支持

### 响应式处理

框架全面支持 Reactor 的响应式编程模型：
- 控制器方法可返回 `Mono<T>` 或 `Flux<T>`
- 自动处理异步响应序列化
- 支持背压机制

## 快速开始

### 1. 创建控制器

```java
// 定义控制器
@ClassRoute("/api/users")
public class UserController {

    @GetRoute("/{id}")
    public Mono<User> getUser(HttpRequest request) {
        String userId = request.pathParams("id").get(0);
        // 处理获取用户逻辑
        return Mono.just(new User(userId, "John Doe"));
    }
    
    @PostRoute
    public Mono<User> createUser(HttpRequest request) {
        String json = request.jsonString();
        // 处理创建用户逻辑
        return Mono.just(new User("1", "John Doe"));
    }
}
```

### 2. 启动服务器

```java
public class Application {
    public static void main(String[] args) {
        // 创建服务器实例
        LioraServer server = new StandardLioraServer();
        
        // 注册控制器
        server.addController(new UserController());
        
        // 启动服务器
        server.start(8080);
        
        System.out.println("Liora server started on port 8080");
    }
}
```

## 详细使用教程

### 创建控制器

在 Liora 框架中，控制器是处理 HTTP 请求的核心组件。通过使用注解，您可以轻松地定义路由和处理逻辑。

```java
// 使用 @ClassRoute 注解定义控制器的根路径
@ClassRoute("/api/books")
public class BookController {
    
    // 使用 @GetRoute 处理 GET 请求
    @GetRoute
    public Mono<List<Book>> getAllBooks(HttpRequest request) {
        // 返回书籍列表
        return Mono.just(Arrays.asList(
            new Book("1", "Java编程思想"),
            new Book("2", "设计模式")
        ));
    }
    
    // 使用 @GetRoute("/{id}") 处理带路径参数的 GET 请求
    @GetRoute("/{id}")
    public Mono<Book> getBookById(HttpRequest request) {
        // 从路径参数中获取书籍ID
        String bookId = request.pathParams("id").get(0);
        // 根据ID查找书籍并返回
        return Mono.just(new Book(bookId, "书籍名称"));
    }
    
    // 使用 @PostRoute 处理 POST 请求
    @PostRoute
    public Mono<Book> createBook(HttpRequest request) {
        // 从请求体中获取JSON数据
        String jsonString = request.jsonString();
        // 解析JSON并创建书籍对象
        Book book = JSON.parseObject(jsonString, Book.class);
        // 保存书籍并返回
        return Mono.just(book);
    }
}
```

### 处理不同类型的请求

Liora 支持处理各种 HTTP 方法的请求：

```java
@ClassRoute("/api/resources")
public class ResourceController {
    
    // GET 请求 - 获取资源
    @GetRoute
    public Mono<List<Resource>> getResources(HttpRequest request) {
        return Mono.just(Collections.emptyList());
    }
    
    // POST 请求 - 创建资源
    @PostRoute
    public Mono<Resource> createResource(HttpRequest request) {
        String json = request.jsonString();
        Resource resource = JSON.parseObject(json, Resource.class);
        return Mono.just(resource);
    }
    
    // PUT 请求 - 更新资源
    @PutRoute("/{id}")
    public Mono<Resource> updateResource(HttpRequest request) {
        String id = request.pathParams("id").get(0);
        String json = request.jsonString();
        Resource resource = JSON.parseObject(json, Resource.class);
        resource.setId(id);
        return Mono.just(resource);
    }
    
    // DELETE 请求 - 删除资源
    @DeleteRoute("/{id}")
    public Mono<String> deleteResource(HttpRequest request) {
        String id = request.pathParams("id").get(0);
        // 执行删除操作
        return Mono.just("Resource " + id + " deleted");
    }
}
```

### 路径参数和查询参数

Liora 提供了简单的方法来获取路径参数和查询参数：

```java
@ClassRoute("/api/data")
public class DataController {
    
    // 处理带路径参数的请求: /api/data/users/123
    @GetRoute("/users/{id}")
    public Mono<User> getUserById(HttpRequest request) {
        // 获取路径参数
        String userId = request.pathParams("id").get(0);
        return Mono.just(new User(userId, "用户名"));
    }
    
    // 处理带多个路径参数的请求: /api/data/users/123/orders/456
    @GetRoute("/users/{userId}/orders/{orderId}")
    public Mono<Order> getOrderById(HttpRequest request) {
        // 获取多个路径参数
        String userId = request.pathParams("userId").get(0);
        String orderId = request.pathParams("orderId").get(0);
        return Mono.just(new Order(orderId, userId));
    }
    
    // 处理带查询参数的请求: /api/data/search?name=John&age=25
    @GetRoute("/search")
    public Mono<List<User>> searchUsers(HttpRequest request) {
        // 获取查询参数
        List<String> names = request.queryParams("name");
        List<String> ages = request.queryParams("age");
        
        String name = names.isEmpty() ? null : names.get(0);
        String ageStr = ages.isEmpty() ? null : ages.get(0);
        Integer age = ageStr == null ? null : Integer.parseInt(ageStr);
        
        // 根据参数搜索用户
        return Mono.just(Collections.emptyList());
    }
}
```

### JSON处理

Liora 框架内置了对 JSON 的支持，可以轻松处理请求体和响应：

```java
@ClassRoute("/api/json")
public class JsonController {
    
    // 接收和处理JSON请求体
    @PostRoute("/users")
    public Mono<User> createUser(HttpRequest request) {
        // 获取JSON字符串
        String jsonString = request.jsonString();
        
        // 使用Fastjson解析JSON
        User user = JSON.parseObject(jsonString, User.class);
        
        // 处理业务逻辑
        user.setId("generated-id");
        
        // 返回响应（框架会自动序列化为JSON）
        return Mono.just(user);
    }
    
    // 返回复杂对象（框架会自动序列化为JSON）
    @GetRoute("/users/{id}")
    public Mono<UserDetails> getUserDetails(HttpRequest request) {
        String userId = request.pathParams("id").get(0);
        
        // 创建复杂对象
        UserDetails details = new UserDetails();
        details.setId(userId);
        details.setName("用户名");
        details.setEmail("user@example.com");
        details.setRoles(Arrays.asList("USER", "ADMIN"));
        
        return Mono.just(details);
    }
    
    // 返回列表数据
    @GetRoute("/users")
    public Mono<List<User>> getAllUsers(HttpRequest request) {
        List<User> users = Arrays.asList(
            new User("1", "用户1"),
            new User("2", "用户2"),
            new User("3", "用户3")
        );
        return Mono.just(users);
    }
}
```

### 异常处理

Liora 提供了统一的异常处理机制，您可以注册自定义异常处理器：

```java
public class Application {
    public static void main(String[] args) {
        LioraServer server = new StandardLioraServer();
        server.addController(new UserController());
        
        // 配置异常处理器
        server.errHandler(dispatcher -> {
            // 处理特定异常
            dispatcher.register(ValidationException.class, (request, e) -> {
                ValidationError error = new ValidationError(e.getMessage());
                return Mono.just(error);
            });
            
            // 处理通用异常
            dispatcher.register(Exception.class, (request, e) -> {
                ErrorResponse error = new ErrorResponse(500, "Internal Server Error", e.getMessage());
                return Mono.just(error);
            });
        });
        
        server.start(8080);
    }
}

// 在控制器中抛出异常
@ClassRoute("/api/exception")
public class ExceptionController {
    
    @GetRoute("/error")
    public Mono<String> throwError(HttpRequest request) {
        // 抛出异常，将由异常处理器处理
        throw new ValidationException("参数验证失败");
    }
    
    @GetRoute("/mono-error")
    public Mono<String> monoError(HttpRequest request) {
        // 返回包含错误的Mono
        return Mono.error(new RuntimeException("异步错误"));
    }
}
```

### 启动服务器

Liora 提供了多种方式来启动服务器：

```java
public class Application {
    public static void main(String[] args) {
        // 创建服务器实例
        LioraServer server = new StandardLioraServer();
        
        // 注册控制器
        server.addController(
            new UserController(),
            new BookController(),
            new ResourceController()
        );
        
        // 注册自定义处理器（可选）
        server.addHandler(new CustomHandler());
        
        // 配置异常处理（可选）
        server.errHandler(dispatcher -> {
            dispatcher.register(Exception.class, (request, e) -> 
                Mono.just(new ErrorResponse(500, "服务器内部错误", e.getMessage()))
            );
        });
        
        // 方式1: 使用默认主机和端口 (0.0.0.0:8080)
        // server.start();
        
        // 方式2: 指定端口
        // server.start(9000);
        
        // 方式3: 指定主机和端口
        server.start("localhost", 8080);
        
        System.out.println("Liora server started on http://localhost:8080");
    }
}
```

## 架构设计

Liora 框架采用分层架构设计，各层职责清晰：

1. **接入层**: Undertow HTTP 服务器负责接收和解析 HTTP 请求
2. **适配层**: 请求适配器将原始请求转换为框架内部的 HttpRequest 对象
3. **路由层**: 调度管理器负责请求路由和控制器方法映射
4. **处理层**: 控制器调用处理器执行具体的业务逻辑
5. **响应层**: 响应处理器将结果序列化并发送给客户端
6. **异常处理层**: 统一处理系统中抛出的异常

## 性能优势

- **非阻塞 I/O**: 基于事件驱动的异步处理模型
- **连接复用**: 高效的连接管理和复用机制
- **零拷贝**: 最小化数据拷贝，提高处理效率
- **线程优化**: 合理的线程模型设计，减少上下文切换
- **响应式流**: 支持背压机制，防止系统过载

## 许可证

待定