Spring创建RESTful web service

创建RESTful Web Service

这篇文章主要讲诉通过Spring创建一个“hello world” RESTful web service。

什么是RESTful Web Service

REST(英文:Representational State Transfer,简称REST)描述了一个架构样式的网络系统,比如 web 应用程序。它首次出现在 2000 年 Roy Fielding 的博士论文中,他是 HTTP 规范的主要编写者之一。在目前主流的三种Web服务交互方案中,REST相比于SOAP(Simple Object Access protocol,简单对象访问协议)以及XML-RPC更加简单明了,无论是对URL的处理还是对Payload的编码,REST都倾向于用更加简单轻量的方法设计和实现。值得注意的是REST并没有一个明确的标准,而更像是一种设计的风格。

它使用http方法将CRUE(create,retrieve,update,delete)操作映射到http请求中:

  • 创建(create):一般通过GET请求:GET /addresses/1

  • 检索(retrieve):一般通过POST请求:POST /addresses

  • 更新(update):一般通过PATCH请求:PUT /addresses/1
  • 删除(delete):一般通过DELETE请求:PATCH /addresses/1
  • http返回到状态码有:

  • 1XX - 信息

  • 2XX - 成功

  • 3XX - 重定向

  • 4XX - 客户端错误

  • 5XX - 服务端错误
  • 你将创建什么

    你将创建一个接收HTTP GET请求的服务:

    http://localhost:8080/greeting
    

    用JSON表示greeting方法的回复

    {"id":1,"content":"Hello, World!"}
    

    你能订做greeting的一个选择参数name在查询字符串中:

    http://localhost:8080/greeting?name=User
    

    name参数值覆盖了“World”的默认值,反映在响应中:

    {"id":1,"content":"Hello, User!"}
    

    你需要什么

  • 大约15分钟

  • 最喜欢的编译器或者IDE

  • JDK1.8或更高版本

  • Gradle4+或Maven3.2

  • 你也可以直接导入代码到你的IDE(Spring Tool Suite、IntelliJ IDEA)
  • 创建一个资源表示类

    现在你有设置项目和创建系统,有可以创建你的web service。

    首先考虑服务交互。

    服务将 GET 处理 /greeting 的请求,可以选择在查询字符串中使用 name 参数。在 GET 请求后可能返回一个 200 OK 的响应和JSON在身体中代表一个问候语。它应该是这样的:

    1
    2
    3
    4
    {
    "id": 1,
    "content": "Hello, World!"
    }

    id 字段是问候语的唯一标识符,content 是问候语的文本表示。

    要建模问候表示,您需要创建一个资源表示类。提供一个普通的旧java对象,其中包含 idcontent 数据的字段、构造函数和访问器:

    src/main/java/hello/Greeting.java
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    package hello;

    public class Greeting {

    private final long id;
    private final String content;

    public Greeting(long id, String content) {
    this.id = id;
    this.content = content;
    }

    public long getId() {
    return id;
    }

    public String getContent() {
    return content;
    }
    }

    创建一个资源控制器

    在Spring构建RESTful web服务的方法中,HTTP请求由一个控制器处理。@RestController 注释很容易识别这些组件,下面的 GreetingController 通过返回一个新的 greeting 类实例来处理 GET/greeting 的请求:

    src/main/java/hello/GreetingController.java
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    package hello;

    import java.util.concurrent.atomic.AtomicLong;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RequestParam;
    import org.springframework.web.bind.annotation.RestController;

    @RestController
    public class GreetingController {

    private static final String template = "Hello, %s!";
    private final AtomicLong counter = new AtomicLong();

    @RequestMapping("/greeting")
    public Greeting greeting(@RequestParam(value="name", defaultValue="World") String name) {
    return new Greeting(counter.incrementAndGet(),
    String.format(template, name));
    }
    }

    这个控制器简洁而简单,但是在引擎盖下面还有很多事情要做。让我们一步一步地把它分解。

    @RequestMapping 注解确性这个HTTP请求在 /greeting 是映射在 greeting() 方法.

    @RequestParam 将查询字符串参数 name 的值绑定到greeting()方法的 name 参数中。如果请求中没有 name 参数,则使用“World”的 defaultValue

    方法主体的实现基于 counter 的下一个值创建并返回一个带有 idcontent 属性的新 Greeting 对象,并使用问候语 template 格式化给定的 name

    传统的MVC控制器和上面的RESTful Web服务控制器之间的一个主要区别在于HTTP响应主体的创建方式。这个RESTful Web服务控制器并不依赖视图技术来执行将问候数据的服务器端呈现给HTML,而是简单地填充并返回一个 Greeting 对象。对象数据将作为JSON直接写入HTTP响应。

    这段代码使用Spring 4的新 @RestController 注释,它将类标记为控制器,其中每个方法都返回一个域对象而不是视图。这是速记 @Controller@ResponseBody 汇总。

    Greeting 对象必须转换为JSON。由于Spring的HTTP消息转换器支持,您不需要手动执行此转换。因为Jackson 2在类路径上,Spring MappingJackson2HttpMessageConverter 会自动选择将 Greeting 实例转换为JSON。

    使应用程序可执行

    虽然可以将此服务作为传统WAR文件打包以部署到外部应用程序服务器,但下面演示的更简单的方法会创建独立应用程序。您将所有内容都打包在一个单独的,可执行的JAR文件中,并由一个优秀的Java main() 方法驱动。一路上,您使用Spring的支持将Tomcat servlet容器作为HTTP运行时嵌入,而不是部署到外部实例。

    src/main/java/hello/Application.java
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    package hello;

    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;

    @SpringBootApplication
    public class Application {

    public static void main(String[] args) {
    SpringApplication.run(Application.class, args);
    }
    }

    @SpringBootApplication 是一个方便的注释,它增加了以下所有内容:

  • @Configuration 将该类标记为应用程序上下文的bean定义的来源。
  • @EnableAutoConfiguration 告诉Spring Boot开始添加基于类路径设置,其他bean和各种属性设置的bean。
  • 通常你会添加 @EnableWebMvc 一个Spring MVC应用程序,但Spring Boot会在类路径中看到spring-webmvc时自动添加它。这将该应用程序标记为Web应用程序并激活关键行为,例如设置一个 DispatcherServlet
  • @ComponentScan 告诉Spring在包中查找其他组件,配置和服务 hello,以便找到控制器。
  • main() 方法使用Spring Boot的 SpringApplication.run() 方法启动应用程序。你有没有注意到没有一行XML?没有web.xml文件。这个Web应用程序是100%纯Java,您不必处理配置任何管道或基础设施。

    构建一个可执行的JAR

    您可以使用Gradle或Maven从命令行运行应用程序。或者您可以构建一个包含所有必需的依赖项,类和资源的可执行JAR文件,并运行该文件。这使得在整个开发生命周期内跨越不同环境等,将服务作为应用程序发布,版本化和部署变得非常容易。

    如果您正在使用Gradle,则可以使用运行该应用程序 ./gradlew bootRun。或者你可以使用构建JAR文件 ./gradlew build。然后你可以运行JAR文件:

    java -jar build / libs / gs-rest-service-0.1.0.jar
    

    如果你正在使用Maven,你可以使用运行该应用程序 ./mvnw spring-boot:run。或者您可以使用构建JAR文件 ./mvnw clean package。然后你可以运行JAR文件:

    java -jar target / gs-rest-service-0.1.0.jar
    

    记录输出显示。该服务应该在几秒钟内启动并运行。

    测试服务

    现在服务已启动,请访问 http//localhost8080/greeting,您会看到:

    {"id":1,"content":"Hello, World!"}
    

    name 使用 http// localhost8080/greetingname=User 提供查询字符串参数。注意 content 属性的值是如何从“Hello,World!”变化的 到“Hello User!”:

    {"id":2,"content":"Hello, User!"}
    

    这一变化表明该 @RequestParam 安排 GreetingController 正在按预期工作。该 name 参数已被赋予默认值“World”,但始终可以通过查询字符串显式覆盖该参数。

    还要注意 id 属性如何从 1 变为 2。这证明您正在针对 GreetingController 多个请求中的相同实例工作,并且 counter 按照预期每次调用时都会增加其字段。

    More info: Deployment

    Author: Zac
    Link: http://www.zacsite.com/2018/06/17/resutful-web-service-springboot/
    Copyright Notice: All articles in this blog are licensed under CC BY-NC-SA 4.0 unless stating additionally.