使用spring创建一个RESTful Web Service

本教程通过创建一个简单的“Hello World”RESTful Web服务来介绍如何使用Spring Boot快速构建RESTful API。该服务能接收HTTP GET请求并返回JSON格式的数据。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

原文地址:https://spring.io/guides/gs/rest-service/

这篇文章引导你使用spring创建一个 "hello world" 的RESTful web service .

你将创建什么

你将创建一个可以接受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分钟
你喜欢的文本编辑器或者ide
JDK 1.8 或更高
Gradle 2.3+或者 Maven 3.0+
You你也可以按照指南直接导入代码到Spring Tool Suite (STS) ,直接开始工作.

如何完成这个指南

像大多数的spring指导文档一样 , 你可以从头开始并完成每一个步骤,或者可以跳过你熟悉的操作

按部就班的话,请参见使用gradle 构建.

或者从git hub导入代码:

git代码下载:git clone https://github.com/spring-guides/gs-rest-service.git
进入目录 gs-rest-service/initial
直接跳过接下来的构建部分继续看.

这些做完后,你的代码就跟gs-rest-service/complete下面的一样.

使用Gradle构建

首先要有一个构建脚本,可以用任何你熟悉的构建系统,但要能在gradle或者maven 下工作. 如果不知道怎么用,参见Building Java Projects with Gradle or Building Java Projects with Maven.

创建目录结构

在你的项目下创建如下结构;例如, 可以使用 mkdir -p src/main/java/hello 在 *nix 系统上创建:

└── src
    └── main
        └── java
            └── hello

创建Gradle构建文件

build.gradle

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath("org.springframework.boot:spring-boot-gradle-plugin:1.3.3.RELEASE")
    }
}

apply plugin: 'java'
apply plugin: 'eclipse'
apply plugin: 'idea'
apply plugin: 'spring-boot'

jar {
    baseName = 'gs-rest-service'
    version =  '0.1.0'
}

repositories {
    mavenCentral()
}

sourceCompatibility = 1.8
targetCompatibility = 1.8

dependencies {
    compile("org.springframework.boot:spring-boot-starter-web")
    testCompile("junit:junit")
}

task wrapper(type: Wrapper) {
    gradleVersion = '2.3'
}

Spring Boot gradle plugin 提供了很多便利:

可以收集classpath中所有的jar文件,并构建一个可直接运行的jar.让你可以很方便的运行和传输你的service.
会自动搜索的 public static void main() 方法作为可以运行的主类
提供一个根据版本号来解析对应的Spring Boot dependencies. 你可以使用你想用的版本,默认使用预设版本

使用Maven构建

创建目录结构

在你的项目下创建如下结构;例如, 可以使用 mkdir -p src/main/java/hello 在 *nix 系统上创建:

└── 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>1.3.3.RELEASE</version>
    </parent>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </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>

    <repositories>
        <repository>
            <id>spring-releases</id>
            <url>https://repo.spring.io/libs-release</url>
        </repository>
    </repositories>
    <pluginRepositories>
        <pluginRepository>
            <id>spring-releases</id>
            <url>https://repo.spring.io/libs-release</url>
        </pluginRepository>
    </pluginRepositories>
</project>

Spring Boot Maven plugin 有很多优势:

可以收集classpath中所有的jar文件,并构建一个可直接运行的jar.让你可以很方便的运行和传输你的service.
会自动搜索的 public static void main() 方法作为可以运行的主类
提供一个根据版本号来解析对应的Spring Boot dependencies. 你可以使用你想用的版本,默认使用预设版本

使用IDE

参见如何将代码导入Spring Tool Suite (STS) .
参见如何使用 IntelliJ IDEA.

创建资源表现类

构建好之后就可以创建web服务了

现在要开始考虑服务交互.

本服务使用get请求/greeting, name 字段可选. 响应一个JSON. 像这样的:

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

id 字段是一个唯一的问候表示,content 是文字问候语.

创建如下model:

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自动将Greeting 转换成JSON.

接下来创建资源控制器,提供访问.

创建资源控制器

In 使用Spring很容易创建RESTful服务的,只需使用 @RestController 注解, 下面的GreetingController 通过get请求返回一个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 到 greeting() 方法.

上面的例子没有指定 GET PUT, POST, 等等,因为@RequestMapping 默认使用@RequestMapping(method=GET)来映射.

@RequestParam 绑定了一个默认值(required=false by default)当没有指定name字段值时,使用""world"

这个方法实现了一个自增的id,和一个可以格式化的问候语

传统的mvc 控制器和RESTful 的最大不同在于HTTP response body的创建方式. 相较于依赖视图技术实现创建html,RESTful web service只是简单的填充,对象直接以json的形式返回

代码中使用 Spring 4 @RestController 注解,被它标记的类用对象代替一个view返回,是@Controller和 @ResponseBody 混合后的简写

Greeting 对象必须转换成JSON,因为Spring的http报文转换,你不需要手动转换. 因为有Jackson 2, Spring的 MappingJackson2HttpMessageConverter自动将 Greeting 转换成 JSON.

编译可执行程序

Although 虽然可以打包成传统的WAR 文件,然后部署. 下面就是用一种简单的方式,创建一个单独的程序,可以打包所有文件到一个独立执行的jar 文件,通过执行main() 方法,可以使用spring 内嵌的Tomcat之间启动服务,无需部署

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

@SpringBootApplication 很方便,包含以下操作:

@Configuration 标记一个类来作为bean定义的应用程序上下文的来源.
@EnableAutoConfiguration 告诉Spring引导添加基于类路径设置的bean，其他bean，以及各种属性设置bean。
通常来说,在Spring mvc中你需要添加 @EnableWebMvc 注解, 在 Spring Boot 中将自动添加,只要classpath中有spring-webmvc 这个标记应用程序作为web应用和活动的关键,相当于设置了一个T DispatcherServlet.
@ComponentScan 告诉 Spring 在 hello包下搜寻其他组件,配置和服务 ,使其找到 GreetingController.

main() 方法使用 Spring Boot的 SpringApplication.run()方法启动程序. 没有XML,没有web.xml,就是一个纯java程序,不需要任何配置

构建可执行 JAR

如果使用gradle,使用 ./gradlew bootRun.

You can b可以构建一个单个的JAR,它包含所有的依赖,类和资源. 这个可以使你很方便的传送,发行,随时随地部署到服务器.

./gradlew build

然后这样运行 JAR 文件:

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

使用maven mvn spring-boot:run. 或者 mvn clean package 去构建,使用下面的方式运行:

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

以上都是创建JAR,你也可以创建传统的WAR

看到日志输出后,几秒钟之后就启动了服务.

测试服务

现在访问 http://localhost:8080/greeting, 可以看到:

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

用name 字串 http://localhost:8080/greeting?name=User. content 被改成 "Hello User!":

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

这个变化表明 @RequestParam 和预期的一样 GreetingController正常运行. name有一个默认值 "World", 可以随时通过query改变

注意到 id 从1 变成 2. 表明 GreetingController实例跨多请求,counter值改变.