目录

• 背景
• 创建 SpringBoot 项目/模块
  • SpringBoot pom.xml
  • api pom.xml
• 创建 RESTful API 应用
  • @SpringBootApplication
    • @Configuration
    • @EnableAutoConfiguration
    • @ComponentScan
  • SpringApplication.run
• Rest Controller
  • @RestController
  • @RequestMapping
• Get/Post/Put/Patch/Delete
  • Get
    • @GetMapping
    • @PathVariable
    • @RequestParam
    • 调用示例
  • Post
    • @PostMapping
    • @RequestBody
    • 调用示例
  • Put
    • @PutMapping
  • Patch
    • @PatchMapping
  • Delete
    • @DeleteMapping
• 结语
• 附

背景 这么简单的事情也值得写一篇文章？
去年搞一个项目时候，因为参与的人员越来越多，很快就暴露出一个问题：大家每个人都有自己的一套（代码）风格。考虑团队协同作战，就提议制订一下相关的规范，把大家的步调搞得一致一些，也有利于项目的推进效率。执行过程中出现了特别大的分歧（意料之中），其中争议最大的就是 Http API 这部分，主要发现两个问题：

• 很多同学认为 RESTful 风格的 API 就是好的（先进的），可是为什么好，说不上来？
• 很多同学认为自己知道 RESTful 风格的 API 是什么样子的，可是坐下来一聊，发现每个人的都不一样，谁都说服不了对方？

最后因为项目周期关系，没有在这个事情上面多纠结，以业务优先为幌子，大家先按自己的风格推进项目，在实践的过程中逐步建立规范。
后来 Review 代码的时候，也发现一个很有意思的现象：即使对于同一位同学，他所写出来的 RESTful 风格的 API 实际也是不一致的，主要表现两个现象：

• 类似的业务场景，API Url和参数的设计明显不同，这位同学也说不上原因，可能和写具体 API 时的心情有关系；
• 有一些业务场景，API 的设计已经明显偏离 RESTful，这位同学用“不这么写，业务逻辑没法儿实现”来搪塞；

和多位同学沟通之后，我得出一个结论：让这些自己以为自己很懂 RESTful 的同学按照自己的理解制订一套规范，用于约束什么样的场景应该如何设计 API，实际上是做不到的。
这么流行的东西，应该是标准化（大家的共识）程度很高的，为什么还会有这种现象？直到最近几天看到一篇 文章：

REST stands for “representational state transfer,” described by Roy Fielding in his dissertation. Sadly, that dissertation is not widely read, and so many people have their own idea of what REST is, leading to a lot of confusion and disagreement.

大意就是，REST 是一篇老外的论文（2000年的时候）里提出来的；但是呢，这篇论文应该很多人没有实际看过，大家都是根据网络上的“只言片语”来理解的，所以导致了很多的曲解和不一致（表示无法更认同）。
论文 确实有点儿长，估计很少有人真的会去看（包括我自己），这里推荐大家看一篇源自微软的文章，讨论的内容很全面，基本可以作为 RESTful API 入门和实践的指南。
本文的后续章节以该篇文章为基础，主要讲述如何使用 SpringBoot 构建 RESTful API 的若干关键技术点，已具备相关经验的同学可以忽略这部分内容。
创建 SpringBoot 项目/模块 使用 Idea 创建 Maven 项目（Project），名称：SpringBoot；再创建一个模块，名称：api，用于构建 RESTful API，这里仅列出 pom.xml。
SpringBoot pom.xml

4.0.0tech.exchange springbootpom 0.1 api 2.6.13.8.1 3.3.0 17 UTF-8 org.springframework.boot spring-boot-starter-parent ${spring-boot.version} pom org.springframework.boot spring-boot-starter-web ${spring-boot.version} org.apache.maven.plugins maven-compiler-plugin ${maven-compiler-plugin.version} ${java.version} ${java.version} ${encoding} maven-assembly-plugin ${maven-assembly-plugin.version} ${maven.multiModuleProjectDirectory}/src/assembly/package.xml make-assemblypackage single

简要介绍一下 pom.xml 各个部分的含义：

1. groupId/artifactId/packaging/version
   

   tech.exchange springbootpom 0.1

   
   用于声明项目的组织、名称、打包方式和版本。
   
2. modules
   

   api

   
   用于声明项目（多模块项目）内的多个模块，这里仅包含一个模块：api。
   
3. properties
   

   ......

   
   用于声明项目 pom.xml 中可能多次使用或需要统一设置的属性（值），比如 SpringBoot 版本号。
   
4. dependencyManagement/dependencies
   

   ......

   
   用于声明项目需要使用的依赖（Jar）名称和版本，项目的模块只需要声明具体使用的依赖名称即可，版本由项目统一指定。
   
5. build/plugins
   

   ......

   
   用于声明项目或模块构建（编译、打包或其它）需要使用的插件。
   

api pom.xml

tech.exchange springboot 0.1 4.0.0api org.springframework.boot spring-boot-starter-web

1. artifactId
   

   api

   
   用于声明模块名称。
   
2. dependencies/dependency
   

   ......

   
   用于声明模块具体需要使用的依赖（Jar）。
   

创建 RESTful API 应用 创建一个名称为 Main 的类：

package tech.exchange.springboot.api; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; /** * @author yurun */ @SpringBootApplication public class Main { public static void main(String[] args) { SpringApplication.run(Main.class, args); } }

@SpringBootApplication @SpringBootApplication 是三个注解（Annotation）的合集：

@SpringBootApplication = @Configuration + @EnableAutoConfiguration + @ComponentScan

它的作用就是告诉 Spring 以 Main 为入口，自动装载各种各样的 Bean（组件或配置）到 容器 中，最终形成一个 SpringBoot 应用，用以接收和响应外部请求。
这些 Bean 来源于三个方面：
@Configuration

Tags the class as a source of bean definitions for the application context.

装载 Main 中我们自定义的 Beans（本文示例中没有包含自定义 Bean）。
@EnableAutoConfiguration

Tells Spring Boot to start adding beans based on classpath settings, other beans, and various property settings.

根据类路径、其它 Beans或属性配置装载需要的 Beans，比如：示例中包含依赖 spring-boot-starter-web，会自动装载 web 相关的 Beans。
@ComponentScan

Tells Spring to look for other components, configurations, and services in the tech/exchange/springboot/api package。

扫描包（Package）路径：tech/exchange/springboot/api，装载包下面的 Beans。
SpringApplication.run

SpringApplication.run(Main.class, args);

启动 SpringBoot 应用，默认情况下会看到如下输出：

2021-12-02 14:44:15.537INFO 58552 --- [main] tech.exchange.springboot.api.Main: Starting Main using Java 17.0.1 on bogon with PID 58552 (/Users/yurun/workspace/tech-exchange/springboot/api/target/classes started by yurun in /Users/yurun/workspace/tech-exchange/springboot) 2021-12-02 14:44:15.538INFO 58552 --- [main] tech.exchange.springboot.api.Main: No active profile set, falling back to default profiles: default 2021-12-02 14:44:16.160INFO 58552 --- [main] o.s.b.w.embedded.tomcat.TomcatWebServer: Tomcat initialized with port(s): 8080 (http) 2021-12-02 14:44:16.170INFO 58552 --- [main] o.apache.catalina.core.StandardService: Starting service [Tomcat] 2021-12-02 14:44:16.170INFO 58552 --- [main] org.apache.catalina.core.StandardEngine: Starting Servlet engine: [Apache Tomcat/9.0.55] 2021-12-02 14:44:16.213INFO 58552 --- [main] o.a.c.c.C.[Tomcat].[localhost].[/]: Initializing Spring embedded WebApplicationContext 2021-12-02 14:44:16.214INFO 58552 --- [main] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 633 ms 2021-12-02 14:44:16.436INFO 58552 --- [main] o.s.b.w.embedded.tomcat.TomcatWebServer: Tomcat started on port(s): 8080 (http) with context path '' 2021-12-02 14:44:16.443INFO 58552 --- [main] tech.exchange.springboot.api.Main: Started Main in 1.209 seconds (JVM running for 1.584)

其中，8080 (http) 表示应用实例端口号为8080，支持 HTTP 请求。
Rest Controller 目前，应用还是一个 空 的应用，无法实际接收任何请求或响应。SpringBoot 中 HTTP 请求或响应需要通过 Controller 实现，一个 Controller 内可以支持（包含）一个或多个 HTTP 请求或响应的实现，也就是一个或多个 API 的实现。

package tech.exchange.springboot.api.controller; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; /** * @author yurun */ @RestController @RequestMapping("/hello") public class HelloController { }

@RestController @RestController 用于标识 HelloController 是一个 Controller，SpringBoot 应用启动后会被自动装载到容器中。
@RequestMapping HelloController 相当于是一个 API 的集合，内部可包含多个 API 的具体实现，如：

/hello/a1 /hello/a2 /hello/a3 ......

可以使用 @RequestMapping 统一标识这些 API 请求路径的父路径，如：/hello，内部的 API 请求路径无需再包含此父路径，使用 /a1、/a2、/a3 即可。
Get/Post/Put/Patch/Delete 目前，HelloController 还是一个 空 的 Controller，不包含任何 API 的实现。
RESTfull API 共涉及 5 种 请求类型：Get/Post/Put/Patch/Delete，3种参数类型：请求路径参数、请求参数和请求体参数。每一种请求类型模拟实现一个 API，用于演示 API 的实现过程，以及每一种参数类型的使用方式。
Get 在 HelloController 中添加方法（Method） get：

@GetMapping("/get/{name1}") public String get(@PathVariable String name1, @RequestParam(defaultValue = "https://www.it610.com/article/name2dv") String name2) { return "hello " + name1 + " " + name2; }

@GetMapping
@GetMapping 用于标识方法 get 仅响应 HTTP GET 请求，且请求路径为 /hello/get/{name1}，其中 {name1} 为请求路径参数名称，实际请求时需要替换为具体的参数值，如：value1。
@PathVariable

@PathVariable String name1

@PathVariable 用于标识请求方法参数，接收请求路径参数。假设请求路径为 /hello/value1，执行请求时参数值 value1 会被传递给请求方法 get 的参数 name1。
请求路径参数默认为必填项（不支持修改），发起请求时必须填写，否则请求会失败。
@RequestParam

@RequestParam(defaultValue = "https://www.it610.com/article/name2dv") String name2

@RequestParam 用于标识请求方法参数，接收请求参数。假设请求路径为 /hello?name2=value2，执行请求时参数值 value2 会被传递给请求方法 get 的参数 name2；假设请求路径为 /hello，执行请求时请求方法 get 的参数 name2 会被设置为默认值（defaultValue） name2dv。
请求参数默认为必填项（可以通过注解属性 required 修改），发起请求时必须填写；如果有设置 defaultValue，则发起请求时可以不填写，使用默认值代替，否则请求会失败。
调用示例

请求：curl http://localhost:8080/hello/get/value1 响应：hello value1 name2dv请求：curl http://localhost:8080/hello/get/value1?name2=value2 响应：hello value1 value2

请求路径参数和请求方法参数的参数名称需要保持一致，如不一致，需要通过注解属性额外指定（下同）；
发起请求时填写的参数类型需要和请求方法声明的参数类型兼容（下同）；
请求路径参数和请求方法参数可以使用零个或多个（下同）；
Get 场景中请求体参数应用场景不多，本文不予讨论。

Post Post 中请求路径参数和请求参数的使用方式与 Get 相同，不再赘述，仅实现请求体参数的使用方式。请求体参数的使用方式与 HTTP Request Header Content-Type 的具体值有关，本文仅讨论最常用的类型：application/json。
发起请求时需要使用 JSON 传递请求体参数，请求方法需要通过 类 接收请求体参数值。

@PostMapping("/post") public String post(@RequestBody PostParams params) { return "hello " + params.getName1() + " " + params.getName2(); }

@PostMapping
@PostMapping 用于标识方法 post 仅响应 HTTP POST 请求，且请求路径为 /hello/post。
@RequestBody

@RequestBody PostParams params

@RequestBody 用于标识请求方法参数，接收请求体参数（JSON）。
假设请求体参数：

{"name1": "value1", "name2": "value2"}

需要创建一个类用于接收体参数：

public class PostParams { private String name1; private String name2 = "name2dv"; public String getName1() { return name1; }public void setName1(String name1) { this.name1 = name1; }public String getName2() { return name2; }public void setName2(String name2) { this.name2 = name2; } }

执行请求时会将每个 JSON 字段按名称分别赋值给 类 实例（param）字段。如果 name1 不存在于 JSON 中，则 name1 为 null；如果 name2 不存在于 JSON 中，则 name2 为 name2dv；如果 JSON 中的某些字段不存在于 类 中，这些字段将会被忽略。
调用示例

请求：curl -H "Content-Type:application/json" -X POST --data '{"name1": "value1", "name2": "value2"}' http://localhost:8080/hello/post 响应：hello value1 value2请求：curl -H "Content-Type:application/json" -X POST --data '{}' http://localhost:8080/hello/post 响应：hello null name2dv请求：curl -H "Content-Type:application/json" -X POST --data '{"name1": "value1", "name3": "value2"}' http://localhost:8080/hello/post 响应：hello value1 name2dv

请求体参数仅能为零个或一个（下同）；
请求体参数字段类型需要和类字段类型兼容（下同）；
请求路径参数、请求参数和请求体参数可以混合使用（下同）。

Put

@PutMapping("/put") public String put(@RequestBody PostParams params) { return "hello " + params.getName1() + " " + params.getName2(); }

@PutMapping
@PutMapping 用于标识方法 put 仅响应 HTTP PUT 请求，且请求路径为 /hello/put。
其余内容同上，不再赘述。
Patch

@PatchMapping("/patch") public String patch(@RequestBody PostParams params) { return "hello " + params.getName1() + " " + params.getName2(); }

@PatchMapping
@PatchMapping 用于标识方法 patch 仅响应 HTTP PATCH 请求，且请求路径为 /hello/patch。
其余内容同上，不再赘述。
Delete

@DeleteMapping("/delete") public String delete(@RequestBody PostParams params) { return "hello " + params.getName1() + " " + params.getName2(); }

@DeleteMapping
@DeleteMapping 用于标识方法 delete 仅响应 HTTP DELETE 请求，且请求路径为 /hello/delete。
其余内容同上，不再赘述。
结语 本文介绍了一篇讲述 RESTfull API 的文章，并以此为基础，演示了一个使用 SpringBoot 构建 RESTfull API 应用的完整过程，核心的配置和注解也给出了说明，希望对大家有帮助。
附 【使用|使用 SpringBoot 构建一个RESTful API】https://github.com/tech-exchange/springboot/blob/master/api/src/main/java/tech/exchange/springboot/api/controller/HelloController.java
https://github.com/tech-exchange/springboot/blob/master/api/src/main/java/tech/exchange/springboot/api/controller/PostParams.java

推荐阅读

• 

  2018世界杯西班牙对摩洛哥哪个厉害 西班牙对摩洛哥预测结果
• 

  做了核酸检测健康码什么时候显示
• 

  说爱你蔡依林mp3下载 如何评价蔡依林唱的说爱你，说爱你 周杰伦
• 

  吉林有哪些特色水果 吉林的水果
• 

  行车记录仪小的好还是大的好 2021年口碑最好的行车记录仪
• 

  东床快婿原本指的是什么 成语东床快婿最初指的是谁
• 

  玩英雄联盟电脑最低配置要求 玩英雄联盟的电脑最低配置是多少
• 

  辛辰和他的 辛辰身世公开了没
• 

  孕妇是否可以吃石榴
• 

  常州轻工学院几个食堂 常州轻工职业技术学院怎么样
• 

  ip前所未有的超高性价比？苹果iPad SE平板曝光
• 

  酷狗音乐如何制作歌词,酷狗歌词制作有报酬么
• 

  实现抵押权申请书
• 

  年轻人头晕晕沉沉是怎么回事 为什么头有点晕
• 

  高德地图如何参加双11集能量_收集能量详细图文教程
• 

  2016office永久激活码教程 正版office2016激活码多少钱
• 

  画圣诞树的软件app，想问一下这个是那个手机指绘软件谢谢大家了
• 

  华为荣耀9怎么样好用吗
• 

  国产手办真的很烂吗 为什么叫手办
• 

  大学生消费调查报告范文精选6篇

• 由浅入深理解AOP
• 【译】20个更有效地使用谷歌搜索的技巧
• Activiti（一）SpringBoot2集成Activiti6
• mybatisplus如何在xml的连表查询中使用queryWrapper
• MybatisPlus|MybatisPlus LambdaQueryWrapper使用int默认值的坑及解决
• MybatisPlus使用queryWrapper如何实现复杂查询
• SpringBoot调用公共模块的自定义注解失效的解决
• 解决SpringBoot引用别的模块无法注入的问题
• iOS中的Block
• Linux下面如何查看tomcat已经使用多少线程