spring-cloud 构建一个restful的web服务

Posted 2020-08-24 xxzblog

构建一个restful的web服务

这篇文章告诉你如何通过spring创建一个”hello world”的restful的web服务

你会建立什么

你会建立一个接受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+
• 你也可以从本指南中导入代码，以及查看该网页直接进入Spring Tool Suite(STS)，并通过它来进行工作。

如何完成本指南

像大多数的 Spring Getting Started guides，你可以从头开始并完成每一个步骤，或者可以避开这个已经熟悉的基本设置步骤。无论以那种方式完成你的代码。

从头开始，请点击这里通过Gradle

跳过基础，进行如下操作：
- 下载并解压源代码，或者使用git克隆它：

git clone https://github.com/spring-guides/gs-rest-service.git

- 进入 gs-rest-service/initial
- 直接跳到 创建资源类

当你完成，你可以检查你的结果和代码在

gs-rest-service/complete


通过Gradle构建

首先你先建立一个基本的构建脚本，您可以使用spring在任何你喜欢的构建系统上构建app，但你的code需要用Gradle和Maven来运行。如果你不熟悉，要么，请参阅通过Gradle构建Java项目 或者 通过Maven构建Java项目

创建目录结构

在你选择的项目目录，创建如下的子目录结构，例子，在*nix系统通过 mkdir -p src/main/java/hello创建：

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

创建Gradle构建文件

下面是最初的构建文件

build.gradle

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath("org.springframework.boot:spring-boot-gradle-plugin:1.4.1.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(‘org.springframework.boot:spring-boot-starter-test‘)
}

这是Spring Boot gradle plugin 提供了许多快捷特性：

• 它收集的类路径上所有jar文件，并建立一个单一的可运行的jar，这使得它更方便地执行和传输你的服务
• 它搜索 public static void main()方法来标示可运行的类
• 它提供了一个内置的依赖解析器，用于设置版本号以匹配Spring Boot dependencies。您可以覆盖任何你想要的版本，但它会默认引导的选择版本。

通过Maven构建

首先，你建立一个基本的构建脚本。你可以使用spring在任何你喜欢的构建系统上构建app，但是你的code必须通过Maven来运行，如果你还不熟悉Maven，请参阅Building Java Projects with Maven

创建目录结构

在你选择的项目目录，创建如下子目录结构；例子，在 *nix 系统通过mkdir -p src/main/java/hello 创建：

└── 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.4.1.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>

    <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/提供许多快捷特性：

• 它收集的类路径上所有jar文件，并建立一个单一的可运行的jar，这使得它更方便地执行和传输你的服务
• 它搜索 public static void main()方法来标示可运行的类
• 它提供了一个内置的依赖解析器，用于设置版本号以匹配Spring Boot dependencies。您可以覆盖任何你想要的版本，但它会默认引导的选择版本。

通过IDE构建

• 如何阅读本指南直接导入到Spring Tool Suite
• 了解如何使用本指南运行在IntelliJ IDEA中

创建资源类

现在你已经设置了该项目，并构建系统，你可以创建Web服务。

通过考虑服务交互开始流程。

这个服务将处理GET请求/greeting，通过可选name参数查询字符串，GET请求应返回一个200 OK的响应JSON字符串，字符串应该是这样的：

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

id字段是用于问候的唯一标识
content是问候的文字描述

问候转换成model表示，你可以创建一个资源类，通过一些id,content字段，构造方法和getter方法提供一个简单的java对象：
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

接下来创建资源控制器

创建资源控制器

在Spring的方式来构建RESTful Web服务，HTTP请求由控制器处理。通过@RestController注解标识的GreetingController下处理GET请求/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注解确保http请求/greeting映射到greeting()方法上。

上面的例子并不指定GET与PUT，POST，等等，因为@RequestMapping在默认情况下映射的所有HTTP操作。使用@RequestMapping(method=GET)来缩小这种映射范围

@RequestParam绑定查询字符串name的值到greeting()方法的name参数上，这个查询字符串明确声明为可选(默认required=true)，如果在请求参数中缺少，则使用默认值”World”。

这个方法体实现是通过id和content属性创建一个Greeting对象返回，id是通过计数器，name是通过格式话模板字符串。

传统的MVC控制器和上面的RESTful Web服务控制器之间的主要区别在于HTTP响应体的创建方式。而不是依靠一个视图技术来执行服务器端渲染的html问候数据，这RESTful Web服务控制器简单地填充，并返回一个Greeting对象，对象数据将直接通过JSON格式写入到HTTP响应中。

该代码使用Spring4的新@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

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 基于类路径添加beans，其他beans和各个属性设置。

• 通常你会添加@EnableWebMvc到Spring MVC的应用程序，但是当它看到的类路径上有spring-webmvc时会自动添加这个注解。它标志着程序是一个Web应用程序，并激活关键行为，如设置DispatcherServlet。

• @ComponentScan告诉spring去查找在hello包下的其它组件，配置和服务，允许它找到HelloController。

main()方法使用spring boot的SpringApplication.run()方法来启动应用程序。你有没有注意到没有一行XML？没有web.xml文件，这个Web应用程序是100％纯Java并且你没有要处理任何配置。

编译一个可执行jar

您可以从Gradle或Maven命令行运行应用或者你可以建立一个包含所有必要的依赖，类和资源的一个可执行的JAR文件并运行。这样便于在不同的环境传输，版本和部署服务在整个开发生命周期的应用程序，等等

如果你使用Gradle，你可以使用./gradlew bootRun运行程序，或者你可以使用./gradlew build编译一个jar，然后运行jar文件：


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


如果你使用Maven，你使用./mvnw spring-boot:run运行程序，或者你可以使用./mvnw clean package编译一个jar，然后运行jar文件：


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, World!”变成”Hello, User!”：

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

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

还要注意为何id属性已经从1改为2，这证明了你的工作对跨多个请求相同GreetingController实例，它的计数器字段被每次调用增加一次。

表明spring controller默认是单例的

总结

恭喜！你刚刚使用Spring开发RESTful Web服务

原文链接：http://spring.io/guides/gs/rest-service/
?
?
?
?
?