Xây dựng một dịch vụ web RESTful

Hướng dẫn này sẽ hướng dẫn bạn quy trình tạo dịch vụ web RESTful “Hello, World” với Spring.

Những gì bạn sẽ xây dựng

Bạn sẽ xây dựng một dịch vụ chấp nhận các yêu cầu HTTP GET tại http://localhost:8080/greeting.

Nó sẽ phản hồi bằng cách đại diện JSON của một lời chào, như danh sách sau đây cho thấy:

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

Bạn có thể tùy chỉnh lời chào bằng một nametham số tùy chọn trong chuỗi truy vấn, như danh sách sau đây hiển thị:

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

Các namegiá trị tham số ghi đè giá trị mặc định Worldvà được phản ánh trong phản ứng, như các chương trình liệt kê sau đây:

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

Những gì bạn cần

Khoảng 15 phút
Một trình soạn thảo văn bản hoặc IDE yêu thích
JDK 1.8 trở lên
Gradle 4+ hoặc Maven 3.2+
Bạn cũng có thể nhập mã trực tiếp vào IDE của mình:
- Bộ công cụ mùa xuân (STS)
- IntelliJ IDEA

Cách hoàn thành hướng dẫn này

Giống như hầu hết các hướng dẫn Bắt đầu Spring , bạn có thể bắt đầu từ đầu và hoàn thành từng bước hoặc bạn có thể bỏ qua các bước thiết lập cơ bản đã quen thuộc với bạn. Dù bằng cách nào, bạn sẽ phải làm việc với mã.

Để bắt đầu lại từ đầu , hãy chuyển sang Bắt đầu với Khởi tạo Spring .

Để bỏ qua những điều cơ bản , hãy làm như sau:

Tải xuống và giải nén kho lưu trữ nguồn cho hướng dẫn này hoặc sao chép nó bằng Git :git clone https://github.com/spring-guides/gs-rest-service.git
cd vào gs-rest-service/initial
Tiếp tục để Tạo Lớp Đại diện Tài nguyên .

Khi hoàn thành , bạn có thể kiểm tra kết quả của mình với mã trong gs-rest-service/complete.

Bắt đầu với Spring Initialize

Đối với tất cả các ứng dụng Spring, bạn nên bắt đầu với Spring Initializr . Initializr cung cấp một cách nhanh chóng để lấy tất cả các phụ thuộc bạn cần cho một ứng dụng và thực hiện rất nhiều thiết lập cho bạn. Ví dụ này chỉ cần phụ thuộc Spring Web.

Danh sách sau đây hiển thị pom.xmltệp được tạo khi bạn chọn Maven:

<?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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.3.2.RELEASE</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.example</groupId>
	<artifactId>rest-service</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>rest-service</name>
	<description>Demo project for Spring Boot</description>

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

	<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>
			<exclusions>
				<exclusion>
					<groupId>org.junit.vintage</groupId>
					<artifactId>junit-vintage-engine</artifactId>
				</exclusion>
			</exclusions>
		</dependency>
	</dependencies>

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

</project>

Danh sách sau đây hiển thị build.gradletệp được tạo khi bạn chọn Gradle:

plugins {
	id 'org.springframework.boot' version '2.3.2.RELEASE'
	id 'io.spring.dependency-management' version '1.0.8.RELEASE'
	id 'java'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '1.8'

repositories {
	mavenCentral()
}

dependencies {
	implementation 'org.springframework.boot:spring-boot-starter-web'
	testImplementation('org.springframework.boot:spring-boot-starter-test') {
		exclude group: 'org.junit.vintage', module: 'junit-vintage-engine'
	}
}

test {
	useJUnitPlatform()
}

Tạo lớp đại diện tài nguyên

Bây giờ bạn đã thiết lập dự án và xây dựng hệ thống, bạn có thể tạo dịch vụ web của mình.

Bắt đầu quá trình bằng cách suy nghĩ về các tương tác dịch vụ.

Dịch vụ sẽ xử lý GETcác yêu cầu /greeting, tùy chọn với một nametham số trong chuỗi truy vấn. Các GETyêu cầu phải trả lại một 200 OKphản ứng với JSON trong cơ thể đại diện cho một lời chào. Nó sẽ giống như đầu ra sau:

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

Trường idnày là một số nhận dạng duy nhất cho lời chào và contentlà phần trình bày bằng văn bản của lời chào.

Để mô hình hóa biểu diễn lời chào, hãy tạo một lớp biểu diễn tài nguyên. Để làm như vậy, hãy cung cấp một đối tượng Java cũ thuần túy với các trường, hàm tạo và trình truy cập cho idvà contentdữ liệu, như danh sách sau (from src/main/java/com/example/restservice/Greeting.java) cho thấy:

package com.example.restservice;

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

Ứng dụng này sử dụng thư viện Jackson JSON để tự động điều chỉnh các phiên bản của loại Greetingthành JSON. Jackson được bao gồm theo mặc định bởi trình khởi động web.

Tạo bộ điều khiển tài nguyên

Trong cách tiếp cận của Spring để xây dựng các dịch vụ web RESTful, các yêu cầu HTTP được xử lý bởi một bộ điều khiển. Các thành phần này được nhận dạng bởi @RestControllerchú thích và GreetingControllerđược hiển thị trong danh sách sau (từ src/main/java/com/example/restservice/GreetingController.java) xử lý GETcác yêu cầu /greetingbằng cách trả về một phiên bản mới của Greetinglớp:

package com.example.restservice;

import java.util.concurrent.atomic.AtomicLong;

import org.springframework.web.bind.annotation.GetMapping;
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();

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

Bộ điều khiển này ngắn gọn và đơn giản, nhưng có rất nhiều điều đang diễn ra. Chúng tôi chia nhỏ nó ra từng bước.

Các @GetMappingĐảm bảo chú thích rằng HTTP GET yêu cầu để /greetingđược ánh xạ tới các greeting()phương pháp.

Có các chú thích đồng hành cho các động từ HTTP khác (ví dụ: @PostMappingcho ĐĂNG). Ngoài ra còn có một @RequestMappingchú thích mà tất cả chúng đều bắt nguồn và có thể dùng như một từ đồng nghĩa (ví dụ @RequestMapping(method=GET)).

@RequestParamliên kết giá trị của tham số chuỗi truy vấn namevào nametham số của greeting()phương thức. Nếu nametham số không có trong yêu cầu, tham defaultValuesố của Worldđược sử dụng.

Việc triển khai thân phương thức tạo và trả về một Greetingđối tượng mới với idvà contentcác thuộc tính dựa trên giá trị tiếp theo từ countervà định dạng được đưa ra namebằng cách sử dụng lời chào template.

Sự khác biệt chính giữa bộ điều khiển MVC truyền thống và bộ điều khiển dịch vụ web RESTful được trình bày trước đó là cách tạo phần thân phản hồi HTTP. Thay vì dựa vào công nghệ dạng xem để thực hiện kết xuất dữ liệu lời chào từ phía máy chủ sang HTML, bộ điều khiển dịch vụ web RESTful này điền và trả về một Greetingđối tượng. Dữ liệu đối tượng sẽ được ghi trực tiếp vào phản hồi HTTP dưới dạng JSON.

Mã này sử dụng @RestControllerchú thích Spring , đánh dấu lớp là bộ điều khiển nơi mọi phương thức trả về một đối tượng miền thay vì một dạng xem. Nó được viết tắt để bao gồm cả hai @Controllervà @ResponseBody.

Đối Greetingtượng phải được chuyển đổi thành JSON. Nhờ hỗ trợ trình chuyển đổi tin nhắn HTTP của Spring, bạn không cần thực hiện việc chuyển đổi này theo cách thủ công. Vì Jackson 2 nằm trên classpath, Spring MappingJackson2HttpMessageConvertersẽ tự động được chọn để chuyển đổi Greetingphiên bản thành JSON.

@SpringBootApplication là một chú thích tiện lợi bổ sung tất cả những điều sau:

@Configuration: Gắn thẻ lớp như một nguồn định nghĩa bean cho ngữ cảnh ứng dụng.
@EnableAutoConfiguration: Yêu cầu Spring Boot bắt đầu thêm các bean dựa trên cài đặt classpath, các bean khác và các cài đặt thuộc tính khác nhau. Ví dụ: nếu spring-webmvcnằm trên classpath, chú thích này sẽ gắn cờ ứng dụng là ứng dụng web và kích hoạt các hành vi chính, chẳng hạn như thiết lập a DispatcherServlet.
@ComponentScan: Yêu cầu Spring tìm kiếm các thành phần, cấu hình và dịch vụ khác trong com/examplegói, cho phép nó tìm thấy bộ điều khiển.

Các main()phương pháp sử dụng mùa xuân Boot của SpringApplication.run()phương pháp để khởi động một ứng dụng. Bạn có nhận thấy rằng không có một dòng XML nào không? Không có web.xmltệp nào cả. Ứng dụng web này là Java thuần túy 100% và bạn không phải xử lý cấu hình bất kỳ hệ thống ống nước hoặc cơ sở hạ tầng nào.

Xây dựng một JAR có thể thực thi

Bạn có thể chạy ứng dụng từ dòng lệnh với Gradle hoặc Maven. Bạn cũng có thể xây dựng một tệp JAR thực thi duy nhất chứa tất cả các phụ thuộc, lớp và tài nguyên cần thiết và chạy tệp đó. Việc xây dựng một jar thực thi giúp dễ dàng vận chuyển, phiên bản và triển khai dịch vụ như một ứng dụng trong suốt vòng đời phát triển, trên các môi trường khác nhau, v.v.

Nếu bạn sử dụng Gradle, bạn có thể chạy ứng dụng bằng cách sử dụng ./gradlew bootRun. Ngoài ra, bạn có thể tạo tệp JAR bằng cách sử dụng ./gradlew buildvà sau đó chạy tệp JAR, như sau:

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

Nếu bạn sử dụng Maven, bạn có thể chạy ứng dụng bằng cách sử dụng ./mvnw spring-boot:run. Ngoài ra, bạn có thể tạo tệp JAR với ./mvnw clean packagevà sau đó chạy tệp JAR, như sau:

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

Các bước được mô tả ở đây tạo ra một JAR có thể chạy được. Bạn cũng có thể tạo một tệp WAR cổ điển .

Đầu ra ghi nhật ký được hiển thị. Dịch vụ sẽ hoạt động trong vòng vài giây.

Kiểm tra dịch vụ

Bây giờ dịch vụ đã hoạt động, hãy truy cập http://localhost:8080/greeting, nơi bạn sẽ thấy:

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

Cung cấp nametham số chuỗi truy vấn bằng cách truy cập http://localhost:8080/greeting?name=User. Lưu ý cách giá trị của contentthuộc tính thay đổi từ Hello, World!thành Hello, User!, như danh sách sau đây cho thấy:

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

Thay đổi này chứng tỏ rằng sự @RequestParamsắp xếp trong GreetingControllerđang hoạt động như mong đợi. Các namethông số đã được đưa ra một giá trị mặc định Worldnhưng có thể được ghi đè một cách rõ ràng thông qua chuỗi truy vấn.

Cũng lưu ý cách idthuộc tính đã thay đổi từ 1thành 2. Điều này chứng tỏ rằng bạn đang làm việc với cùng một GreetingControllertrường hợp trên nhiều yêu cầu và countertrường của nó đang được tăng lên trên mỗi cuộc gọi như mong đợi.

Tóm lược

Xin chúc mừng! Bạn vừa phát triển một dịch vụ web RESTful với Spring.

Nguon: spring.io

Spring – Xây dựng một dịch vụ web RESTful