dragonfly: 轻量级Java Web应用开发框架

请访问DeepWiki获取更详细的文档和使用帮助。

1. 介绍

Dragonfly是一个轻量级的Java应用开发框架，可以作为SpringBoot的替代。Dragonfly基于DI框架Whale，包括三个部分：

• Web: 一个遵循REST规范，参考JSR371和JAX-RS标准的Web开发框架
• Data:一个用统一的API集成了MyBatis,Apache DBUTILS和JPA的数据访问框架
• APP: 一些简化应用开发的工具

1.1 准备工作

• 首先，您需要新建一个Java Web项目，普通的Dynamic Web Project，或者Maven Project都可以;
• 因为还没有发布到Maven仓库中，得麻烦您手工将dragonfly-xxx.jar拷贝到您项目的WEB-INF/lib目录下，并且添加到CLASSPATH中;
• 在WEB-INF下或者src/main/resources下，建一个application.properties配置文件，推荐把配置文件都放在src/main/resouces目录下;
• 最简单的方法是：下载实例项目mantis(https://gitee.com/techarts/dragonfly/releases/download/1.0/mantis.zip)，解压后导入到Eclipse。

2. Web Framework

我们先写一个简单的Web服务。

@Restful
public class BookWebService{
    @Get("/book/{id}")
    public Book getBook(WebContext arg){
        var id = arg.intAt(0);
        //Statements...
    }
}

这个例子虽然简单，但它几乎包含了Dragonfly的全部。

2.1 注解@Restful

表示此类是一个Restful风格的Web服务。如果您是Spring MVC的老用户，也可以用@Controller这个注解(JSR371)，更熟悉一些，Dragonfly都支持。取决于您如何规划URL，如果本类中所有方法的URL都具有相同的前缀，则可以在注解中给出，免得每个方法的注解上重复写：

@Restful("/book")
//或者
@Controller("/book")

2.2 Web方法的形式

返回值不限，取决于您的业务。为了简化，Dragonfly采用了一个强制约束：每个方法都只有一个参数，类型为WebContext，WebContext中有您需要的一切，比如获取请求参数或设置错误代码/信息等。这种设计是为了让代码更简洁，形式更统一。

2.3 Web方法注解

注解表示它是哪一类REST请求（HTTP METHOD），以及资源的URL路径和参数。URL设计是个难点，需要根据业务去仔细琢磨。Dragonfly支持以下HTTP METHODS:

#	HTTP Method	注解	用途
1	GET	@Get	查询资源
2	PUT	@Put	修改资源
3	POST	@Post	创建资源
4	DELETE	@Delete	删除资源
5	HEAD	@Head
6	PATCH	@Patch
7	不区分方法	@Any	兼容非REST风格的API

在一个业务稍复杂的应用中，REST的严格约束会让开发者感到很不方便。因此，Dragonfly提供了一个@Any注解，兼容传统设计风格的Web API。但是需要注意：它的URL中不能使用路径参数了，也就是说，所有参数要么通过POST form传过来，要么通过Query String传过来。

2.4 获取请求参数

在方法体内，获取Request参数有两种方式：

• A. 如果是URL路径中花括号里的参数，需要用它的位置索引，从0开始，依次增加。 这是一种设计权衡，为了避免Spring MVC和JAX-RS中的@PathVariable和@PathParam注解对参数形式的破坏，这两个东西看起来乱糟糟的。 WebContext内置了多个方法获取不同类型的参数，包括：

#	方法	参数	返回值
1	at	int	String
2	intAt	int	int
3	floatAt	int	float
4	longAt	int	long
5	boolAt	int	boolean

当然，您也可以只是用at(int)，将获得的字符串使用Dragonfly提供的Converter工具进行类型转换。

• B. 如果是通过POST表单(form)或者GET QueryString(?xx=xxx)传过来的参数，需要根据参数的名称获取。WebContext中提供了丰富的方法：

#	方法	参数	返回值类型
1	get	String	String
2	getInt	String	int
3	getFloat	String	float
4	getLong	String	long
5	getBool	String	boolean
6	getDate	String	Date
7	getJson	无	JSON String
8	bean	T	T
9	getDouble	String	double

2.5 错误处理

如果要在Response中向调用者传递错误信息，可以使用WebContext的error方法：

@Get("/book/{id}")
public Book getBook(WebContext arg){
    arg.error(-2, "The book does not exist");
}

您需要自己设计错误代码，建议用复数表示错误。 目前有几个数字已经被Dragonfly框架占用：0（OK，成功）；-10000（Invalid Token，Token无效）；-10086（No Such Method，服务不存在）。

2.6 响应数据格式

Dragonfly将以JSON格式返回数据给请求者，并且模式是固定的：

public class Result implements Serializable{
    private int code;      //错误代码，0表示正确
    private String text;   //错误描述，0对应为OK
    private Object data;   //业务数据
}

它的JSON格式看起来是这样的：

{
  "code": 0,
  "text": "OK",
  "data": {
    "id": 166,
    "isbn": "222-3F",
    "name": "枯枝败叶",
    "author": "马尔克斯"
  }
}

Writing...