[SpringBoot guides系列翻译]SpringBoot构建RESTful程序入门

原文地址

构建一个RESTful的WebService

这个指南将带你用Spring创建一个RESTful的helloworld程序。

你将完成

在下面地址上创建一个接收http get请求的服务

http://localhost:8080/greeting

返回json格式的数据

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

自定义可选参数name作为请求参数

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

name的值会替换World然后返回结果

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

你需要的

  • 大约15分钟
  • 你喜欢的文本编辑器(我这里用了vscode)或者IDE
  • jdk1.8+
  • Gradle 4+ 或 Maven 3.2+
  • 你也可以直接把你的代码导入到你的ide中
    • Spring Tool Suite
    • IntelliJ IDEA

如何完成这份指南

其他的不说了,一步一步来,直接看通过Maven

通过Gradle

忽略~~

通过Maven

这里演示如何用Maven来构建你的spring应用,如果你不熟悉怎么使用Maven,可以看这里

创建项目结构:

mkdir -p src/main/java/hello

然后定义pom.xml文件。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.springframework</groupId>
    <artifactId>gs-rest-service</artifactId>
    <version>0.1.0</version>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.0.5.RELEASE</version>
    </parent>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>com.jayway.jsonpath</groupId>
            <artifactId>json-path</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <properties>
        <java.version>1.8</java.version>
    </properties>


    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

有几点可以说一下:

  • 第一是固定的modelVersion=4.0
  • 第二是几个groupId都是org.springframework.boot,这个我们一般写自己的公司或者组织相关的倒序域名,这里因为是spring自己的教程,所以都是一样的org.springframework.boot。
  • spring-boot-starter-parent提供了依赖和插件管理的功能。spring-boot-starter-web用于构建restful的webapi以及springmvc应用。,spring-boot-starter-test用于测试,包含了JUnit,Hamcrest,Mockito。这3个包算是完整的项目基本上都要用到的。
  • 然后是spring-boot-maven-plugin插件。他提供了很多便捷的特性。
    • 把用到的所有依赖打包成一个整体,这样方便服务的执行以及分发。
    • public static void main()标记成可执行类。
    • 提供了内置的依赖解析器用于设置相符的Spring Boot依赖的版本号。

通过IDE

介绍了如何使用intellij IDEA,占个位,忽略先。

创建一个资源表示类

定义好了pom就可以开始写代码了。

先想一下服务的交互是怎么样的。

服务处理/greeting过的来的get请求,可能会有一个name参数。然后结果返回一个json以及200状态码。json如下。

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

id字段作为一个唯一表示符,content表示内容。

下面创建一个java类来表示这个类。包含字段,构造函数,两个get方法。src/main/java/hello/Greeting.java

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 使用Jackson Json库把对象转换成JSON。

接下来创建控制器。

创建一个资源控制器

Spring用控制器来处理HTTP请求。用@RestController注解来标识。@RequestMapping注解申明请求路径/greeting,然后返回一个Greeting的实例。下面示例代码。

src/main/java/hello/GreetingController.java

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注解使/greeting过来的HTTP请求映射到greeting()方法。

上面的@RequestMapping方法注解里面没有指定get或者put或者post,所以,默认是接收所有方法。如果需要,可以按如下指定为只接收get方法@RequestMapping(method=GET)

@RequestParam把请求过来的name参数绑定到方法的name参数上,如果没有传值,默认用defaultValue指定的world

返回的Greeting对象的idcounter构造,contenttemplate构造。

与传统的MVC 里面的控制器对比,RESTful服务的HTTP请求的Response由控制器直接返回一个Greeting对象,而传统的MVC里面的控制器还需要依赖视图渲染技术进行服务端的渲染技术返回html。

代码使用Spring 4的@RestController注解,把类标记成控制器并且返回领域对象而不是一个视图。可以算是@Controller@ResponseBody的合体。

Greeting对象需要转换成json对象。Spring使用MappingJackson2HttpMessageConverter选择Jackson2作为默认的库把Greeting对象转成json。

使你的程序可运行

虽然把程序打包成一个war文件,然后部署到外部的服务器是可行的。下面演示一种更简单的方式。把程序打包成一个可执行的jar文件,通过main()方法驱动。通过这种方式,使用Tomcat服务器来托管http运行时。

创建src/main/java/hello/Application.java

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);
    }
}

什么是bean。简单来说是由Spring的 IoC容器控制的,并且是程序的骨架。

@SpringBootApplication是一个简便的注解,它添加了下面这些东西:

  • @Configuration 定义这个类是bean的来源类。
  • @EnableAutoConfiguration 告诉SpringBoot去添加基于classpath设置的或者是其他的bean,以及各种属性。
  • 通常你可能会添加@EnableWebMvc注解在Spring MVC程序中。但是SpringBoot会自动为你添加,如果在classpath里面有spring-webmvc。这个标记把程序标记成web应用。激活并设置比如DispatcherServlet之类的核心行为。
  • @ComponentScan告诉Sping 去查找hello包里面的其他的组件,配置服务,包括控制器。

mian()方法使用SpingBoot的 SpringApplication.run()方法来启动应用。是的,没有写xml配置,这是一个纯粹的java程序。

编译生成可执行的jar

你可以通过命令行的Maven或者Gradle来运行程序。或者你可以把程序编译生成一个可执行的jar文件。这个jar文件包含了必须的依赖,类,资源文件。这方便于分发部署。

mvn spring-boot:run命令来运行程序。

mvn clean package 命令来打包程序生成jar。然后使用

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

来运行。第一次需要要从Maven下载dependency,所以package过程有点长。。。喝杯☕️。

试试这个服务

启动默认是8080端口。访问http://localhost:8080/greeting,将会看到

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

提供一个name参数http://localhost:8080/greeting?name=User,content就会变掉。

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

总结

恭喜,你已经学会~。

posted @ 2019-04-09 14:02  Sheldon_Lou  阅读(347)  评论(0编辑  收藏  举报