JerryFramework简介及入门教程

简介

JerryFramework 是我独立开发的一个玩具级Java Web微服务框架,用于JavaWeb期末课程设计(其实是因为这门课的老师不允许使用现有框架),包含内嵌Web服务器JerryMouse(才不是Tomcat)与WebApi开发框架,风格与.Net WebApi相似,用于前后端分离开发。

示例项目地址,使用Vue.js + JerryFramework + OpenJudger开发的OJ系统。OpenJudger是我的另一个项目,实现了现代化OJ的核心评测模块(支持程序与SQL评测),旨在简化OJ系统开发。示例项目没什么功能,未来会继续开发。

设计思想

与.Net core的WebApi类似。Web服务器只负责接收请求和响应,构造出HTTP上下文并送入由多个中间件组成的请求处理管道,每个中间件实现具体功能(如错误拦截、静态资源、授权认证、WebApi),依次处理,中间件可以打破请求处理管道(如静态资源中间件已经找到了请求的资源,就无需将上下文传递给WebApi中间件)。用户也可以编写自己的中间件以扩展框架功能。当然,这种设计决定了处理管道里的中间件必须按序执行。因此,框架使用构造者模式实现了JerryBuilder,用来快速构建Web服务。

注意:此框架仅供娱乐测试,各种特性的实现求简单不求可靠,不适合用于生产环境。

已实现的特性

  • 静态Web服务:用于托管图片、JS、CSS、HTML页面等静态资源,支持数百种类型的mime
  • 自动URL、Content编解码
  • 全局错误拦截:统一方便的自定义错误处理
  • Session、Cookie
  • 路由/约定路由/路由继承:根据控制器和方法名自动映射请求
  • 请求方法限定:支持使用Get与Post注解限定请求方法
  • 请求/表单参数映射:将请求/表单参数自动映射到控制器的方法中
  • Json以及Quick Json糖:完整的Json支持,同时支持快速构建Json的Qucik Json糖
  • 返回值自动包装:可直接返回Java对象,由框架自动序列化为Json响应
  • 请求/响应过滤:在响应处理前后对内容执行过滤/修改
  • 中间件功能扩展:支持用户自定义中间件以扩展框架功能

入门教程

一、引入JerryFramework

使用Maven引入。为了快速实现参数映射功能,框架使用了JDK8中通过反射获取方法实际参数名的特性,因此,您必须使用JDK8(或更高版本)并在编译时添加-parameters参数。

<dependency>
  <groupId>com.rainng</groupId>
  <artifactId>jerryframework</artifactId>
  <version>1.0-SNAPSHOT</version>
</dependency>

二、Hello World

引入框架后,我们来创建第一个WebApi服务, 新建一个App类,包含标准的main入口 ,再新建一个ApiController控制器类。方便演示,两个类放在同一个文件。

JerryBuilder构造了一个Web服务。它使用了默认的9615端口,并启用了错误处理、静态Web(wwwroot目录)、WebApi中间件,使用start方法启动Web服务。

ApiController控制器继承自Controller(框架中,所有控制器都必须继承自它),包含了hello方法,返回一个String值。

public class App {
    public static void main(String[] args) {
        JerryBuilder.createWebApi(ApiController.class).start();
    }
}

class ApiController extends Controller {
    public String hello() {
        return "Hello JerryFramework";
    }
}

现在,启动程序,在浏览器中输入地址 http://localhost:9615/api/hello ,可以看到浏览器显示

 "Hello JerryFramework" 

这就是我们在Api控制器的hello方法中返回的值,无需配置,框架会自动扫描控制器中的方法,并映射请求,这叫做约定路由。当然您也可以指定路由,这会在下面讲到。

三、自动参数映射

向Api控制器中添加一个add方法,随后访问 http://localhost:9615/api/add?a=1&b=2.1 ,浏览器会返回3.1

public Double add(Integer a, Double b) {
    return a + b;
}

可以看出,框架将请求中的a、b参数自动映射到了add方法的a、b参数,并且正确地识别了对应类型。此外,所有方法支持重载,框架会自动根据请求参数映射对应的方法。

四、返回Json对象

默认情况下,你的方法可以返回任何对象实例或基本数据类型,如果你返回的是对象实例,框架就会自动地序列化实例并返回Json响应。

我们添加一个Student类,getter和setter方法已省略,它拥有id和name两个字段。

class Student {
    private Integer id;
    private String name;
}

我们向Api控制器中添加一个getStudent方法

public Student getStudent() {
    return new Student(12345, "小明");
}

访问 http://localhost:9615/api/getstudent ,浏览器就会序列化为Json的Student实例。

 {"id":12345,"name":"小明"} 

五、使用Quick Json

Quick Json是框架提供的用于快速构建Json实例的API。如下,不再需要编写Student类,只需要提供字段名和字段值即可生成Json响应。

public IResult getStudent2() {
    return json("id|name", 12345, "小明");
}
格式:json(使用|隔开的所有字段名, 字段1的值, 字段2的值, 字段3的值)

嵌套json对象也是可以的,使用jsono,如下

public IResult getStudent3() {
    return json("id|name|info", 12345, "小明", jsono("grade|age", "二年级", "八岁"));
}

访问 http://localhost:9615/api/getstudent3 会显示如下Json响应

 {"name":"小明","id":12345,"info":{"grade":"二年级","age":"八岁"}} 

六、路由

框架提供了简单的路由机制,支持约定路由或使用Route注解指定路由,使用Get/Post注解限制请求方法

1) 约定路由

可以不指定任何Route注解,框架将按照如下规则映射请求,注意:路由是可以由类继承关系继承的,也就是说,子控制器类会继承父控制器类的路由。

默认映射规则:基控制器的路由路径/控制器名(去除末尾的Controller)/方法名
2) 指定路由

使用@Route注解指定路由,Route注解可以修饰类和方法,支持相对路由与绝对路径

相对路径:Route("api/v1")
绝对路径:Route("/api/v1")
它们的区别,相对路径会继承父类的路由,而绝对路径会从/截断继承关系。
例如BaseController的路由为Route("/base")
AController的路由为Route("api/v1")
BController的路由为Route("/api/v1")
那么A的路由为/base/api/v1B的路由为/api/v1

七、请求方法限定

如果你想限制一个方法只响应Get或Post请求,那么可以使用@Get/@Post注解,非限定方法将返回404

@Get
public String getHello() {
    return "getHello";
}

@Post
public String postHello() {
    return "postHello";
}

八、Session/Cookie

在Web开发中,session用于服务器端保存信息,cookie用于客户端保存信息。框架提供了多种方法操作session和cookie,这里介绍两个最简单的例子:使用一组get/set/contains方法。它们记录客户访问服务器的时间

public Object session() {
    if(!containsSession("time")) {
        setSession("time", new Date().toString());
    }
    return getSession("time");
}

public Object cookie() {
    if(!containsCookie("time")) {
        setCookie("time", new Cookie("time", new Date().toString()));
    }
    return getCookie("time").getValue();
}

小结

本文简单介绍了JerryFramework的功能与设计思想,并给出了最基本功能的样例。但这只是冰山一角,框架的更多细节以及实例将在未来分享,例如:

  • 静态Web服务
  • 全局错误处理
  • 中间件扩展(实现授权认证等功能)
  • 请求/响应过滤
  • 控制器继承
  • 整合Spring

咕咕咕~

Azure99

大二蒟蒻,喜欢折腾vps、玩机,偶尔写写代码

You may also like...

发表评论

电子邮件地址不会被公开。 必填项已用*标注