今天我们来写第一个 Java(Web) 项目，文章会包括如下内容：

• Spring MVC 常用注解
• Lombok 常用注解
• 创建 Spring Web 项目，并实现 echo 接口
• Spring MVC HTTP 请求的执行流程

Java Web 常用注解

• @RestController：是 @Controller 和 @ResponseBody 的组合注释
• @RequestMapping：类级别路由设置

 @RequestMapping("api/product")

• @GetMapping：方法级别路由设置，对应 GET 请求

 @GetMapping("listProduct")

• @PostMapping：方法级别路由设置，对应 POST 请求

 @PostMapping("createProduct")

• @DeleteMapping：方法级别路由设置，对应 DELETE 请求

 @DeleteMapping("delete/{id}")

• @PathVariable：路径变量，通常用于方法，但也可以于类

@GetMapping("/owners/{ownerId}/products/{productId}")
public Product getProduct(@PathVariable Long ownerId,
                                      @PathVariable Long productId) {
    // ...
}

• @RequestParam：路径参数，用于方法

@GetMapping("getProduct")
public String getProduct(@RequestParam("id") Long id) {
   // ...
}

• @RequestBody ：绑定到 HTTP Request Body，Body 的内容会通过 HttpMessageConverter 转换成你定义的参数

@PostMapping("addProduct")
public Result<String> addProduct(@RequestBody ProductDto param) {
    // ...
}

• @ResponseBody 同样的，该标注表明把返回值通过 HttpMessageConverter 序列化到 HTTP Response 中。

Lombok 常用注解

• @Getter, @Setter：生成 getter, setter 方法
• @ToString：生成 toString 方法
• @EqualsAndHashCode：生成 hashCode 和 equals 方法
• @NoArgsConstructor, @AllArgsConstructor：生成构造函数
• @Data： 是 @Getter, @Setter, @ToString, @EqualsAndHashCode, @RequiredArgsConstructor 的简写
• @Accessors(chain=true)：支持链式调用

Java Web 项目的两个分支

Java Web 有两个分支，一个是 Web Servlet，另一个是 Web Reactive.

• Web Servlet：Spring MVC, WebSocket, SockJS, STOMP Messaging
• Web Reactive：Spring WebFlux, WebClient, WebSocket, RSocket

接下来我们要创建的是 基于Servlet 的 Web 项目 Spring MVC。下面这个图清晰的表达了 Spring MVC 和 Spring WebFlux 的差异。

可以看到 Spring WebFlux 是不包含数据库（无 JDBC）访问的，而我们后面会用到数据库，所以这里我们选 Spring MVC 项目。

创建项目详细步骤

Spring Boot 3 最低要求 Java 17，而目前公司几乎所有项目用的都是 Java 8，所有这里我们选 Spring Boot 2 的最新版本 2.7.8。

经过以上步骤，一个空的 Java Web (Spring MVC) 项目已经创建起来了。如果你有安装 Spring Boot CLI，那么上述这么多步骤可以简化为一条命令：

spring init --dependencies=web,lombok --build=maven --java-version=1.8 --boot-version=2.7.8 springdemo

运行项目

通过 IDEA 右上方的工具栏运行如下，启动的服务默认端口是 8080

修改服务端口

可以通过修改项目配置文件来修改端口，IDEA 默认创建的配置文件是 application.properties，但最佳实践推荐使用 .yml 格式， 这里把 文件后缀名直接改成 .yml 即可。我们把端口改成 8990，修改完之后，再次运行，端口就变了。

创建 RESTFul API

• 封装项目的统一返回值类型

model/Result.java 文件

@Getter
@Setter
@Accessors(chain = true)
public class Result<T> {
    private int code;
    private String message;
    private T data;

    public Result() {
        code = 0;
        message = "success";
    }

    public Result<T> setCode(ResultCode error) {
        code = error.code();
        message = error.description();
        return this;
    }
}

• 定义返回值枚举

consts/ResultCode.java 文件

public enum ResultCode {
    /** success */
    ENoErr(0, "访问成功"),
    /** failed */
    EFailed(1, "系统异常"),
    /** parameter error */
    EInvalidParam(2, "非法参数")
    ;
    private final int code;
    private final String description;
    ResultCode(int code, String desc) {
        this.code = code;
        this.description = desc;
    }
    public int code() {
        return code;
    }
    public String description() {
        return description;
    }
}

• 创建 controller 定义request 请求处理的方法

controller/UtilController.java 文件

@RestController
@RequestMapping("api/util")
public class UtilController {
    /** 接收什么，就返回什么 */
    @PostMapping("echo")
    public Result<JsonNode> echo(@RequestBody JsonNode param) {
        Result<JsonNode> result = new Result<>();
        return result.setData(param);
    }
}

• 编译运行，调用接口

打开 Windows Terminal，使用 httpie 调用接口:

http -v http://192.168.1.10:8991/api/util/echo name=张三 birthday=2020-01-01

执行结果如下：

可以看到，通过接口传递的参数，被原样的返回给调用方。

Spring MVC 中 HTTP 请求的执行流程

今天篇幅有点长了，这部分另起一篇。

小结一下，今天咱们学习了 Spring MVC 和 Lombok 的常用注解；IDEA 中创建 Java 项目的基本步骤，也了解如何使用 Spring Boot CLI 命令来创建项目；并成功创建了第一个 Java Web 项目，实现了 第一个API：POST /api/util/echo。掌握如何运行，如何调用 API。

下一节，我们会继续分享 Spring MVC 中 HTTP 请求的执行过程，了解 HTTP Request 是怎么传递到 Controller 方法中的。