原文： https://howtodoinjava.com/dropwizard/tutorial-and-hello-world-example/

Dropwizard 是用于快速开发 REST API 的开源 Java 框架。 Dropwizard 是一种生态系统，其中包含捆绑到单个程序包中的所有依赖项（例如，Jersey，Jackson 或 Jetty），也可以作为单独的模块添加。 如果不使用 dropwizard，最终将自己收集所有依赖项，由于各种 Java 库之间的版本不匹配，通常会导致类加载问题。 Dropwizard 为您解决了这个问题，并将稳定，成熟的库组合到一个简单，轻巧的程序包中，使您可以专注于完成工作。 让我们逐步使用来学习使用 dropwizard 构建 REST API。

  1. Table of Contents
  3. Libraries included inside dropwizard
  4. Setup dropwizard with maven
  5. Create REST Application Class
  6. Create REST Resource and APIs
  7. Build Resource Representations
  8. Request Validation
  9. Verify REST APIs

您将需要 Java8 来运行此代码中给出的示例，这些示例是使用 dropwizard 1.0.0 版开发的。

dropwizard 中包含的库

将 dropwizard 包含到项目中后，您将获得以下库添加到您的类路径中。

  • Jersey – 用于构建 RESTful Web 应用。
  • Jetty – Dropwizard 使用 Jetty HTTP 库将 HTTP 服务器直接嵌入到您的项目中。
  • Jackson - 用于对象到 JSON 的转换。 它允许直接使用 JAXB 注解导出域模型。
  • Guava – 高度优化的不可变数据结构，可加快开发速度。
  • Logback 和 SLF4j – 用于高性能和灵活的日志记录。
  • Hiberante 验证器 – 一个简单的声明性框架，用于验证用户输入并生成有用且对 i18n 友好的错误消息。
  • Apache HTTPClient – 用于与其他 Web 服务的高层和高层交互。
  • JDBI - 在 Java 中使用关系数据库的最直接方法。
  • Liquidbase – 在整个开发和发布周期中，始终检查数据库模式。
  • FreeMarker – 模板系统。
  • Mustache – 适用于更多面向用户的应用的简单模板系统。
  • Joda Time –非常完整和理智的库，用于处理日期和时间。

用 Maven 设置 dropwizard

我们的项目将基于maven-archetype-quickstart原型。 您可以使用命令提示符来创建项目，或使用 eclipse 创建简单的 Maven Java 项目。

  1. mvn archetype:generate -DgroupId=com.howtodoinjava.demo -DartifactId=DropWizardExample 
  2. -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

生成的项目也将具有pom.xml文件。 在此处添加 dropwizard 依赖项。

  1. <properties>
  2.     <dropwizard.version>1.0.0</dropwizard.version>
  3. </properties>
  4. <dependencies>
  5.     <dependency>
  6.         <groupId>io.dropwizard</groupId>
  7.         <artifactId>dropwizard-core</artifactId>
  8.         <version>${dropwizard.version}</version>
  9.     </dependency>
  10. </dependencies>

这将下载所有 jar 文件并将它们添加到您的类路径中。 为了向我们的项目添加构建和程序包支持，我们将使用 maven-shade 插件，它将允许我们将我们的项目及其依赖项完全打包到一个独立的 JAR 文件中（胖/Uber JAR），可以按原样分发和执行。

完整的pom.xml文件如下所示。

  1. <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  2.     xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd;
  3.     <modelVersion>4.0.0</modelVersion>
  5.     <groupId>com.howtodoinjava.demo</groupId>
  6.     <artifactId>DropWizardExample</artifactId>
  7.     <version>0.0.1-SNAPSHOT</version>
  8.     <packaging>jar</packaging>
  10.     <name>DropWizardExample</name>
  11.     <url>http://maven.apache.org</url>
  13.     <properties>
  14.         <dropwizard.version>1.0.0</dropwizard.version>
  15.         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  16.     </properties>
  18.     <dependencies>
  19.         <dependency>
  20.             <groupId>io.dropwizard</groupId>
  21.             <artifactId>dropwizard-core</artifactId>
  22.             <version>${dropwizard.version}</version>
  23.         </dependency>
  24.     </dependencies>
  25.     <build>
  26.         <finalName>DropWizardExample-${version}</finalName>
  27.         <plugins>
  28.             <plugin>
  29.                 <groupId>org.apache.maven.plugins</groupId>
  30.                 <artifactId>maven-compiler-plugin</artifactId>
  31.                 <version>3.1</version>
  32.                 <configuration>
  33.                     <source>1.8</source>
  34.                     <target>1.8</target>
  35.                 </configuration>
  36.             </plugin>
  37.             <plugin>
  38.                 <groupId>org.apache.maven.plugins</groupId>
  39.                 <artifactId>maven-shade-plugin</artifactId>
  40.                 <version>2.1</version>
  41.                 <executions>
  42.                     <execution>
  43.                         <phase>package</phase>
  44.                         <goals>
  45.                             <goal>shade</goal>
  46.                         </goals>
  47.                         <configuration>
  48.                             <transformers>
  49.                                 <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
  50.                                     <mainClass>com.howtodoinjava.rest.App</mainClass>
  51.                                 </transformer>
  52.                                 <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer">
  53.                                 </transformer>
  54.                             </transformers>
  55.                         </configuration>
  56.                     </execution>
  57.                 </executions>
  58.             </plugin>
  59.         </plugins>
  60.     </build>
  62. </project>

创建 REST 应用类

应用类是任何 dropwizard 应用的入口点。 它需要扩展io.dropwizard.Application类并实现initialize(Bootstrap<Configuration>)和run(Configuration, Environment)方法。 他们准备应用的运行时环境。

要调用run方法，您需要具有public static void main(String[] args) {}方法，当您将应用作为 jar 文件运行时，该方法将由java -jar命令调用。

  1. package com.howtodoinjava.rest;
  3. import io.dropwizard.Application;
  4. import io.dropwizard.Configuration;
  5. import io.dropwizard.setup.Bootstrap;
  6. import io.dropwizard.setup.Environment;
  8. import org.slf4j.Logger;
  9. import org.slf4j.LoggerFactory;
  11. import com.howtodoinjava.rest.controller.EmployeeRESTController;
  13. public class App extends Application<Configuration> {
  14.     private static final Logger LOGGER = LoggerFactory.getLogger(App.class);
  16.     @Override
  17.     public void initialize(Bootstrap<Configuration> b) {
  18.     }
  20.     @Override
  21.     public void run(Configuration c, Environment e) throws Exception {
  22.         LOGGER.info("Registering REST resources");
  23.         e.jersey().register(new EmployeeRESTController(e.getValidator()));
  24.     }
  26.     public static void main(String[] args) throws Exception {
  27.         new App().run(args);
  28.     }
  29. }

为了执行 JAR 文件，我们在命令中添加服务器参数，该参数启动嵌入式 HTTP 服务器（Jetty）以运行我们的服务。

  1. java -jar target\DropWizardExample.jar server

Dropwizard 的嵌入式 Jetty 服务器将默认尝试绑定到端口 8080 和 8081 。 服务器使用端口 8080 来向应用提供传入的 HTTP 请求，而 Dropwizard 的管理界面则使用 8081 端口。

我们还导入了必要的Logger和LoggerFactory类，以构造可用于日志记录需求的Logger实例。

创建 REST 资源和 API

现在，当您添加了应用引导类后，现在可以添加包含 REST API 的 REST 资源。 在此示例中，我创建并创建了员工管理应用 - 因此它具有用于创建/更新/删除员工记录的 API。 此类将负责处理 HTTP 请求并生成 JSON 响应。

由于类路径中包含 Jersey，因此我们将使用它来构建 REST API。

  1. package com.howtodoinjava.rest.controller;
  3. import java.net.URI;
  4. import java.net.URISyntaxException;
  5. import java.util.ArrayList;
  6. import java.util.Set;
  8. import javax.validation.ConstraintViolation;
  9. import javax.validation.Validator;
  10. import javax.ws.rs.DELETE;
  11. import javax.ws.rs.GET;
  12. import javax.ws.rs.POST;
  13. import javax.ws.rs.PUT;
  14. import javax.ws.rs.Path;
  15. import javax.ws.rs.PathParam;
  16. import javax.ws.rs.Produces;
  17. import javax.ws.rs.core.MediaType;
  18. import javax.ws.rs.core.Response;
  19. import javax.ws.rs.core.Response.Status;
  21. import com.howtodoinjava.rest.dao.EmployeeDB;
  22. import com.howtodoinjava.rest.representations.Employee;
  24. @Path("/employees")
  25. @Produces(MediaType.APPLICATION_JSON)
  26. public class EmployeeRESTController {
  28.     private final Validator validator;
  30.     public EmployeeRESTController(Validator validator) {
  31.         this.validator = validator;
  32.     }
  34.     @GET
  35.     public Response getEmployees() {
  36.         return Response.ok(EmployeeDB.getEmployees()).build();
  37.     }
  39.     @GET
  40.     @Path("/{id}")
  41.     public Response getEmployeeById(@PathParam("id") Integer id) {
  42.         Employee employee = EmployeeDB.getEmployee(id);
  43.         if (employee != null)
  44.             return Response.ok(employee).build();
  45.         else
  46.             return Response.status(Status.NOT_FOUND).build();
  47.     }
  49.     @POST
  50.     public Response createEmployee(Employee employee) throws URISyntaxException {
  51.         // validation
  52.         Set<ConstraintViolation<Employee>> violations = validator.validate(employee);
  53.         Employee e = EmployeeDB.getEmployee(employee.getId());
  54.         if (violations.size() > 0) {
  55.             ArrayList<String> validationMessages = new ArrayList<String>();
  56.             for (ConstraintViolation<Employee> violation : violations) {
  57.                 validationMessages.add(violation.getPropertyPath().toString() + ": " + violation.getMessage());
  58.             }
  59.             return Response.status(Status.BAD_REQUEST).entity(validationMessages).build();
  60.         }
  61.         if (e != null) {
  62.             EmployeeDB.updateEmployee(employee.getId(), employee);
  63.             return Response.created(new URI("/employees/" + employee.getId()))
  64.                     .build();
  65.         } else
  66.             return Response.status(Status.NOT_FOUND).build();
  67.     }
  69.     @PUT
  70.     @Path("/{id}")
  71.     public Response updateEmployeeById(@PathParam("id") Integer id,    Employee employee) {
  72.         // validation
  73.         Set<ConstraintViolation<Employee>> violations = validator.validate(employee);
  74.         Employee e = EmployeeDB.getEmployee(employee.getId());
  75.         if (violations.size() > 0) {
  76.             ArrayList<String> validationMessages = new ArrayList<String>();
  77.             for (ConstraintViolation<Employee> violation : violations) {
  78.                 validationMessages.add(violation.getPropertyPath().toString() + ": " + violation.getMessage());
  79.             }
  80.             return Response.status(Status.BAD_REQUEST).entity(validationMessages).build();
  81.         }
  82.         if (e != null) {
  83.             employee.setId(id);
  84.             EmployeeDB.updateEmployee(id, employee);
  85.             return Response.ok(employee).build();
  86.         } else
  87.             return Response.status(Status.NOT_FOUND).build();
  88.     }
  90.     @DELETE
  91.     @Path("/{id}")
  92.     public Response removeEmployeeById(@PathParam("id") Integer id) {
  93.         Employee employee = EmployeeDB.getEmployee(id);
  94.         if (employee != null) {
  95.             EmployeeDB.removeEmployee(id);
  96.             return Response.ok().build();
  97.         } else
  98.             return Response.status(Status.NOT_FOUND).build();
  99.     }
  100. }

为了模仿数据库，我创建了EmployeeDB类，该类将员工记录和更新存储在内存中。

  1. package com.howtodoinjava.rest.dao;
  3. import java.util.ArrayList;
  4. import java.util.HashMap;
  5. import java.util.List;
  7. import com.howtodoinjava.rest.representations.Employee;
  9. public class EmployeeDB {
  11.     public static HashMap<Integer, Employee> employees = new HashMap<>();
  12.     static{
  13.         employees.put(1, new Employee(1, "Lokesh", "Gupta", "India"));
  14.         employees.put(2, new Employee(2, "John", "Gruber", "USA"));
  15.         employees.put(3, new Employee(3, "Melcum", "Marshal", "AUS"));
  16.     }
  18.     public static List<Employee> getEmployees(){
  19.         return new ArrayList<Employee>(employees.values());
  20.     }
  22.     public static Employee getEmployee(Integer id){
  23.         return employees.get(id);
  24.     }
  26.     public static void updateEmployee(Integer id, Employee employee){
  27.         employees.put(id, employee);
  28.     }
  30.     public static void removeEmployee(Integer id){
  31.         employees.remove(id);
  32.     }
  33. }

建立资源表示

表示是保存数据并序列化为 JSON 的内容。 它是 RESTful 应用的模型。 当将 Jersey 与 Jackson 结合使用时，构建资源表示形式所需的全部就是 – 遵循 Java bean 标准的简单 POJO。 Jackson 根据每个类的设置器方法及其返回类型来递归构造 JSON 字符串。

任何java.util.List类型的实例都将转换为 JSON 数组。

  1. package com.howtodoinjava.rest.representations;
  3. import javax.validation.constraints.NotNull;
  4. import javax.validation.constraints.Pattern;
  6. import org.hibernate.validator.constraints.Length;
  7. import org.hibernate.validator.constraints.NotBlank;
  9. public class Employee {
  11.     @NotNull
  12.     private Integer id;
  13.     @NotBlank @Length(min=2, max=255)
  14.     private String firstName;
  15.     @NotBlank @Length(min=2, max=255)
  16.     private String lastName;
  17.     @Pattern(regexp=".+@.+\\.[a-z]+")
  18.     private String email;
  20.     public Employee(){
  21.     }
  23.     public Employee(Integer id, String firstName, String lastName, String email) {
  24.         this.id = id;
  25.         this.firstName = firstName;
  26.         this.lastName = lastName;
  27.         this.email = email;
  28.     }
  30.     public Integer getId() {
  31.         return id;
  32.     }
  34.     public void setId(Integer id) {
  35.         this.id = id;
  36.     }
  38.     public String getFirstName() {
  39.         return firstName;
  40.     }
  42.     public void setFirstName(String firstName) {
  43.         this.firstName = firstName;
  44.     }
  46.     public String getLastName() {
  47.         return lastName;
  48.     }
  50.     public void setLastName(String lastName) {
  51.         this.lastName = lastName;
  52.     }
  54.     public String getEmail() {
  55.         return email;
  56.     }
  58.     public void setEmail(String email) {
  59.         this.email = email;
  60.     }
  62.     @Override
  63.     public String toString() {
  64.         return "Emplyee [id=" + id + ", firstName=" + firstName + ", lastName="
  65.                 + lastName + ", email=" + email + "]";
  66.     }
  67. }

如果在某些情况下需要，可以通过将@JsonIgnore注解添加到其设置器来防止该属性成为 JSON 表示的一部分。

请求验证

接受PUT和POST请求时，您需要在请求正文中验证用户提交的实体内容。 Dropwizard 为此使用 Hiberate 验证器。 添加验证需要执行以下步骤。

  1. 在表示形式类中添加验证注解

  1. @NotNull
  2. private Integer id;
  4. @NotBlank @Length(min=2, max=255)
  5. private String firstName;
  7. @NotBlank @Length(min=2, max=255)
  8. private String lastName;
  10. @Pattern(regexp=".+@.+\\.[a-z]+")
  11. private String email;

  1. 在应用的 REST 资源中注入Environment.getValidator()

  1. @Override
  2. public void run(Configuration c, Environment e) throws Exception 
  3. {
  4.     LOGGER.info("Registering REST resources");
  5.     e.jersey().register(new EmployeeRESTController(e.getValidator()));
  6. }

  1. 在 REST 资源中使用验证器

  1. public class EmployeeRESTController {
  3.     private final Validator validator;
  5.     public EmployeeRESTController(Validator validator) {
  6.         this.validator = validator;
  7.     }
  9.     @POST
  10.     public Response createEmployee(Employee employee) throws URISyntaxException 
  11.     {
  12.         Set<ConstraintViolation<Employee>> violations = validator.validate(employee);
  13.         Employee e = EmployeeDB.getEmployee(employee.getId());
  14.         if (violations.size() > 0) {
  15.             ArrayList<String> validationMessages = new ArrayList<String>();
  16.             for (ConstraintViolation<Employee> violation : violations) {
  17.                 validationMessages.add(violation.getPropertyPath().toString() + ": " + violation.getMessage());
  18.             }
  19.             return Response.status(Status.BAD_REQUEST).entity(validationMessages).build();
  20.         }
  22.         //Create Employee code here
  23.     }
  24. }

验证 REST API

现在，当我们创建并添加了 REST API 的验证后，让我们对其进行测试。

构建应用 uber jar 文件

  1. > mvn clean package

在 Jetty 服务器中启动应用

  1. > java -jar target\DropWizardExample-0.0.1-SNAPSHOT.jar server

访问 URI http://localhost:8080/employees

这将返回员工集合和相关的响应头。

Dropwizard 教程 – HelloWorld 示例 - 图1

Dropwizard – GET 请求示例 – 1

访问 URI http://localhost:8080/employees/1

这将返回 ID 为 1 的员工记录。

Dropwizard 教程 – HelloWorld 示例 - 图2

Dropwizard – GET 请求示例 – 2

使用无效的请求数据发送 HTTP PUT http://localhost:8080/employees/1

您将收到验证消息。

Dropwizard 教程 – HelloWorld 示例 - 图3

Dropwizard – 验证示例

使用正确的数据发送 HTTP PUT http://localhost:8080/employees/1

员工记录将成功更新。

Dropwizard 教程 – HelloWorld 示例 - 图4

Dropwizard – PUT 请求示例

同样，您可以测试其他 API 和方案。

源码下载

在评论部分让我知道您的问题。

学习愉快！