Building a RESTful Web Service
2017-06-14 10:54
483 查看
原文链接:https://spring.io/guides/gs/rest-service/
and respond with a JSON representation of a greeting:
You can customize the greeting with an optional
in the query string:
The
value overrides the default value of "World" and is reflected in the response:
About 15 minutes
A favorite text editor or IDE
JDK 1.8 or later
Gradle 2.3+ or Maven
3.0+
You can also import the code straight into your IDE:
Spring Tool Suite (STS)
IntelliJ IDEA
Like most Spring Getting Started guides, you can start from scratch and complete
each step, or you can bypass basic setup steps that are already familiar to you. Either way, you end up with working code.
To start from scratch, move on to Build
with Gradle.
To skip the basics, do the following:
Download and unzip the source repository
for this guide, or clone it using Git:
cd into
Jump ahead to Create a resource representation class.
When you’re finished, you can check your results against the code in
Now that you’ve set up the project and build system, you can create your web service.
Begin the process by thinking about service interactions.
The service will handle
for
in the query string. The
should return a
with JSON in the body that represents a greeting. It should look something like this:
The
is a unique identifier for the greeting, and
the textual representation of the greeting.
To model the greeting representation, you create a resource representation class. Provide a plain old java object with fields, constructors, and accessors for the
Next you create the resource controller that will serve these greetings.
In Spring’s approach to building RESTful web services, HTTP requests are handled by a controller. These components are easily identified by the
and the
handles
returning a new instance of the
This controller is concise and simple, but there’s plenty going on under the hood. Let’s break it down step by step.
The
ensures that HTTP requests to
mapped to the
the value of the query string parameter
the
This query string parameter is explicitly marked as optional (
default): if it is absent in the request, the
"World" is used.
The implementation of the method body creates and returns a new
with
based on the next value from the
and formats the given
the greeting
A key difference between a traditional MVC controller and the RESTful web service controller above is the way that the HTTP response body is created. Rather than relying on a view
technology to perform server-side rendering of the greeting data to HTML, this RESTful web service controller simply populates and returns a
The object data will be written directly to the HTTP response as JSON.
This code uses Spring 4’s new
which marks the class as a controller where every method returns a domain object instead of a view. It’s shorthand for
together.
The
must be converted to JSON. Thanks to Spring’s HTTP message converter support, you don’t need to do this conversion manually. Because Jackson 2 is
on the classpath, Spring’s
automatically chosen to convert the
to JSON.
Although it is possible to package this service as a traditional WAR file
for deployment to an external application server, the simpler approach demonstrated below creates a standalone application. You package everything in a single, executable JAR file, driven by a good old Java
Along the way, you use Spring’s support for embedding the Tomcat servlet container as the HTTP runtime, instead of deploying to an external instance.
a convenience annotation that adds all of the following:
the class as a source of bean definitions for the application context.
Spring Boot to start adding beans based on classpath settings, other beans, and various property settings.
Normally you would add
a Spring MVC app, but Spring Boot adds it automatically when it sees spring-webmvc on the classpath. This flags the application as a web application and activates key behaviors such as
setting up a
Spring to look for other components, configurations, and services in the
allowing it to find the controllers.
The
uses Spring Boot’s
to launch an application. Did you notice that there wasn’t a single line of XML? No web.xml file either. This web application is 100% pure Java and you didn’t have to deal with configuring
any plumbing or infrastructure.
You can run the application from the command line with Gradle or Maven. Or you can build a single executable JAR file that contains all the necessary dependencies, classes, and
resources, and run that. This makes it easy to ship, version, and deploy the service as an application throughout the development lifecycle, across different environments, and so forth.
If you are using Gradle, you can run the application using
If you are using Maven, you can run the application using
Logging output is displayed. The service should be up and running within a few seconds.
Now that the service is up, visit http://localhost:8080/greeting,
where you see:
Provide a
string parameter with http://localhost:8080/greeting?name=User. Notice how the value of the
changes from "Hello, World!" to "Hello User!":
This change demonstrates that the
in
as expected. The
has been given a default value of "World", but can always be explicitly overridden through the query string.
Notice also how the
has changed from
This proves that you are working against the same
across multiple requests, and that its
is being incremented on each call as expected.
Congratulations! You’ve just developed a RESTful web service with Spring.
Want to write a new guide or contribute to an existing one? Check out our contribution
guidelines.
Building a RESTful Web Service
What you’ll build
You’ll build a service that will accept HTTP GET requests at:http://localhost:8080/greeting
and respond with a JSON representation of a greeting:
{"id":1,"content":"Hello, World!"}
You can customize the greeting with an optional
nameparameter
in the query string:
http://localhost:8080/greeting?name=User
The
nameparameter
value overrides the default value of "World" and is reflected in the response:
{"id":1,"content":"Hello, User!"}
What you’ll need
About 15 minutesA favorite text editor or IDE
JDK 1.8 or later
Gradle 2.3+ or Maven
3.0+
You can also import the code straight into your IDE:
Spring Tool Suite (STS)
IntelliJ IDEA
How to complete this guide
Like most Spring Getting Started guides, you can start from scratch and completeeach step, or you can bypass basic setup steps that are already familiar to you. Either way, you end up with working code.
To start from scratch, move on to Build
with Gradle.
To skip the basics, do the following:
Download and unzip the source repository
for this guide, or clone it using Git:
git clone https://github.com/spring-guides/gs-rest-service.git
cd into
gs-rest-service/initial
Jump ahead to Create a resource representation class.
When you’re finished, you can check your results against the code in
gs-rest-service/complete.
Build with Gradle
Build with Maven
Build with your IDE
Create a resource representation class
Now that you’ve set up the project and build system, you can create your web service.Begin the process by thinking about service interactions.
The service will handle
GETrequests
for
/greeting, optionally with a
nameparameter
in the query string. The
GETrequest
should return a
200 OKresponse
with JSON in the body that represents a greeting. It should look something like this:
{ "id": 1, "content": "Hello, World!" }
The
idfield
is a unique identifier for the greeting, and
contentis
the textual representation of the greeting.
To model the greeting representation, you create a resource representation class. Provide a plain old java object with fields, constructors, and accessors for the
idand
contentdata:
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 get 14efd Id() { return id; } public String getContent() { return content; } }
As you see in steps below, Spring uses the Jackson JSON library to automatically marshal instances of type Greetinginto JSON. |
Create a resource controller
In Spring’s approach to building RESTful web services, HTTP requests are handled by a controller. These components are easily identified by the @RestControllerannotation,
and the
GreetingControllerbelow
handles
GETrequests for
/greetingby
returning a new instance of the
Greetingclass:
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)); } }
This controller is concise and simple, but there’s plenty going on under the hood. Let’s break it down step by step.
The
@RequestMappingannotation
ensures that HTTP requests to
/greetingare
mapped to the
greeting()method.
The above example does not specify GETvs. PUT, POST, and so forth, because @RequestMappingmaps all HTTP operations by default. Use @RequestMapping(method=GET)to narrow this mapping. |
@RequestParambinds
the value of the query string parameter
nameinto
the
nameparameter of the
greeting()method.
This query string parameter is explicitly marked as optional (
required=trueby
default): if it is absent in the request, the
defaultValueof
"World" is used.
The implementation of the method body creates and returns a new
Greetingobject
with
idand
contentattributes
based on the next value from the
counter,
and formats the given
nameby using
the greeting
template.
A key difference between a traditional MVC controller and the RESTful web service controller above is the way that the HTTP response body is created. Rather than relying on a view
technology to perform server-side rendering of the greeting data to HTML, this RESTful web service controller simply populates and returns a
Greetingobject.
The object data will be written directly to the HTTP response as JSON.
This code uses Spring 4’s new
@RestControllerannotation,
which marks the class as a controller where every method returns a domain object instead of a view. It’s shorthand for
@Controllerand
@ResponseBodyrolled
together.
The
Greetingobject
must be converted to JSON. Thanks to Spring’s HTTP message converter support, you don’t need to do this conversion manually. Because Jackson 2 is
on the classpath, Spring’s
MappingJackson2HttpMessageConverteris
automatically chosen to convert the
Greetinginstance
to JSON.
Make the application executable
Although it is possible to package this service as a traditional WAR filefor deployment to an external application server, the simpler approach demonstrated below creates a standalone application. You package everything in a single, executable JAR file, driven by a good old Java
main()method.
Along the way, you use Spring’s support for embedding the Tomcat servlet container as the HTTP runtime, instead of deploying to an external instance.
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); } }
@SpringBootApplicationis
a convenience annotation that adds all of the following:
@Configurationtags
the class as a source of bean definitions for the application context.
@EnableAutoConfigurationtells
Spring Boot to start adding beans based on classpath settings, other beans, and various property settings.
Normally you would add
@EnableWebMvcfor
a Spring MVC app, but Spring Boot adds it automatically when it sees spring-webmvc on the classpath. This flags the application as a web application and activates key behaviors such as
setting up a
DispatcherServlet.
@ComponentScantells
Spring to look for other components, configurations, and services in the
hellopackage,
allowing it to find the controllers.
The
main()method
uses Spring Boot’s
SpringApplication.run()method
to launch an application. Did you notice that there wasn’t a single line of XML? No web.xml file either. This web application is 100% pure Java and you didn’t have to deal with configuring
any plumbing or infrastructure.
Build an executable JAR
You can run the application from the command line with Gradle or Maven. Or you can build a single executable JAR file that contains all the necessary dependencies, classes, andresources, and run that. This makes it easy to ship, version, and deploy the service as an application throughout the development lifecycle, across different environments, and so forth.
If you are using Gradle, you can run the application using
./gradlew bootRun. Or you can build the JAR file using
./gradlew build. Then you can run the JAR file:
java -jar build/libs/gs-rest-service-0.1.0.jar
If you are using Maven, you can run the application using
./mvnw spring-boot:run. Or you can build the JAR file with
./mvnw clean package. Then you can run the JAR file:
java -jar target/gs-rest-service-0.1.0.jar
The procedure above will create a runnable JAR. You can also opt to build a classic WAR file instead. |
Test the service
Now that the service is up, visit http://localhost:8080/greeting,where you see:
{"id":1,"content":"Hello, World!"}
Provide a
namequery
string parameter with http://localhost:8080/greeting?name=User. Notice how the value of the
contentattribute
changes from "Hello, World!" to "Hello User!":
{"id":2,"content":"Hello, User!"}
This change demonstrates that the
@RequestParamarrangement
in
GreetingControlleris working
as expected. The
nameparameter
has been given a default value of "World", but can always be explicitly overridden through the query string.
Notice also how the
idattribute
has changed from
1to
2.
This proves that you are working against the same
GreetingControllerinstance
across multiple requests, and that its
counterfield
is being incremented on each call as expected.
Summary
Congratulations! You’ve just developed a RESTful web service with Spring.Want to write a new guide or contribute to an existing one? Check out our contribution
guidelines.
All guides are released with an ASLv2 license for the code, and an Attribution, NoDerivatives creative commons license for the writing. |
相关文章推荐
- 教程学习 01-Building a RESTful Web Service 学习笔记
- Building a RESTful Web Service
- gradle第二天(Building a RESTful Web Service)
- 构建一个RESTful Web Service(Building a RESTful Web Service)
- Spring起步(一)Building a RESTful Web Service
- 构建一个REST风格的Web服务(Building a RESTful Web Service)
- Spring Building a RESTful Web Service
- Getting Started · Building a RESTful Web Service
- 构建一个RESTful Web Service(Building a RESTful Web Service)
- Building a RESTful Web Service
- Building a RESTful Web Service
- Building a RESTful Web Service Using Spring Boot In Eclipse
- Spring Boot: Building a RESTful Web Service
- SpringBoot 之 Building a RESTful Web Service
- Building a RESTful Web Service(转)
- Building a RESTful Web Service
- Eclipse + Spring + maven Building a RESTful Web Service ---需要添加注释
- SOAP Webservice和RESTful Webservice
- Restful webservice 注意事项
- RESTful Webservice 和 SOAP Webserivce 对比及区别