JavaWeb RESTful 开发规范入门

还是鼠鼠2025-06-21 9:59

目录

[一、什么是 RESTful 规范](#一、什么是 RESTful 规范)

二、工程技术选型

三、项目结构

四、代码示例

一、什么是 RESTful 规范

REST（Representational State Transfer）是一种基于 HTTP 协议的架构风格，核心思想是将服务看作资源（Resource），通过统一的 URI（统一资源标识符）进行访问，并使用 HTTP 的四个动词（GET、POST、PUT、DELETE）来对资源执行不同的操作。遵循 RESTful 规范，可以让 API 具有良好的可读性、可维护性和可扩展性。

二、工程技术选型

  • 框架：Spring Boot（简化配置，快速搭建）

  • 依赖管理：Maven

  • 语言：Java 11+，配置文件为 properties（或 YAML）

三、项目结构

java 复制代码 
demo-restful/
├── pom.xml
└── src
    └── main
        ├── java
        │   └── com.example.demo
        │       ├── DemoApplication.java
        │       ├── model
        │       │   └── User.java
        │       └── controller
        │           └── UserController.java
        └── resources
            └── application.properties

四、代码示例

提示：下面标注了文件名和代码语言，方便直接复制粘贴。

XML 复制代码 
<!-- 文件：pom.xml -->
<!-- 语言：XML -->
<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 
                             http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>demo-restful</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.7.12</version>
  </parent>
  <dependencies>
    <!-- Web Starter 包含了 Spring MVC 和内嵌 Tomcat -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- Lombok 用于简化模型类写法（可选） -->
    <dependency>
      <groupId>org.projectlombok</groupId>
      <artifactId>lombok</artifactId>
      <optional>true</optional>
    </dependency>
    <dependency>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-databind</artifactId>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <!-- 插件：打包为可执行 Jar -->
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>
</project>
java 复制代码 
// 文件：src/main/java/com/example/demo/DemoApplication.java
// 语言：Java
package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {
  public static void main(String[] args) {
    SpringApplication.run(DemoApplication.class, args);
  }
}
java 复制代码 
// 文件：src/main/java/com/example/demo/model/User.java
// 语言：Java
package com.example.demo.model;

public class User {
  private Long id;
  private String name;
  private String email;

  public User() {}
  public User(Long id, String name, String email) {
    this.id = id;
    this.name = name;
    this.email = email;
  }
  // getter & setter
  public Long getId() { return id; }
  public void setId(Long id) { this.id = id; }
  public String getName() { return name; }
  public void setName(String name) { this.name = name; }
  public String getEmail() { return email; }
  public void setEmail(String email) { this.email = email; }
}
java 复制代码 
// 文件：src/main/java/com/example/demo/controller/UserController.java
// 语言：Java
package com.example.demo.controller;

import com.example.demo.model.User;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.*;

// @RestController = @Controller + @ResponseBody
@RestController
@RequestMapping("/users")
public class UserController {

  // 模拟内存中的用户列表
  private static final Map<Long, User> USER_MAP = Collections.synchronizedMap(new LinkedHashMap<>());
  static {
    USER_MAP.put(1L, new User(1L, "Alice", "alice@example.com"));
    USER_MAP.put(2L, new User(2L, "Bob", "bob@example.com"));
  }

  // GET /users     ------ 查询所有用户
  @GetMapping
  public List<User> list() {
    return new ArrayList<>(USER_MAP.values());
  }

  // GET /users/{id} ------ 根据 ID 查询
  @GetMapping("/{id}")
  public ResponseEntity<User> getById(@PathVariable Long id) {
    User u = USER_MAP.get(id);
    if (u != null) {
      return ResponseEntity.ok(u);
    }
    return ResponseEntity.status(HttpStatus.NOT_FOUND).build();
  }

  // POST /users    ------ 新增用户（请求体 JSON）
  @PostMapping
  public ResponseEntity<User> create(@RequestBody User user) {
    long nextId = USER_MAP.keySet().stream().max(Long::compare).orElse(0L) + 1;
    user.setId(nextId);
    USER_MAP.put(nextId, user);
    return ResponseEntity.status(HttpStatus.CREATED).body(user);
  }

  // PUT /users/{id} ------ 更新用户
  @PutMapping("/{id}")
  public ResponseEntity<User> update(@PathVariable Long id, @RequestBody User user) {
    if (!USER_MAP.containsKey(id)) {
      return ResponseEntity.status(HttpStatus.NOT_FOUND).build();
    }
    user.setId(id);
    USER_MAP.put(id, user);
    return ResponseEntity.ok(user);
  }

  // DELETE /users/{id} ------ 删除用户
  @DeleteMapping("/{id}")
  public ResponseEntity<Void> delete(@PathVariable Long id) {
    USER_MAP.remove(id);
    return ResponseEntity.noContent().build();
  }
}
XML 复制代码 
# 文件：src/main/resources/application.properties
# 语言：Properties
server.port=8080
spring.jackson.serialization.indent_output=true   # JSON 输出格式化

五、运行并测试

  1. 打包启动

    java 复制代码 
    mvn clean package
java -jar target/demo-restful-0.0.1-SNAPSHOT.jar

  2. 测试示例（使用 curl）

    • 查询所有用户

      java 复制代码 
      curl -i http://localhost:8080/users

      响应结果（HTTP/1.1 200 OK + JSON 列表）

      java 复制代码 
      [
  {
    "id": 1,
    "name": "Alice",
    "email": "alice@example.com"
  },
  {
    "id": 2,
    "name": "Bob",
    "email": "bob@example.com"
  }
]

    • 根据 ID 查询

      java 复制代码 
      curl -i http://localhost:8080/users/1

      响应结果（HTTP/1.1 200 OK + 单个 JSON）

      java 复制代码 
      {
  "id": 1,
  "name": "Alice",
  "email": "alice@example.com"
}

    • 新增用户

      java 复制代码 
      curl -i -X POST -H "Content-Type: application/json" \
  -d '{"name":"Charlie","email":"charlie@example.com"}' \
  http://localhost:8080/users

      响应结果（HTTP/1.1 201 Created）

      java 复制代码 
      {
  "id": 3,
  "name": "Charlie",
  "email": "charlie@example.com"
}

    • 更新用户

      java 复制代码 
      curl -i -X PUT -H "Content-Type: application/json" \
  -d '{"name":"Alice Smith","email":"alice.smith@example.com"}' \
  http://localhost:8080/users/1

      响应结果（HTTP/1.1 200 OK）

      java 复制代码 
      {
  "id": 1,
  "name": "Alice Smith",
  "email": "alice.smith@example.com"
}

    • 删除用户

      java 复制代码 
      curl -i -X DELETE http://localhost:8080/users/2

      响应结果（HTTP/1.1 204 No Content）

六、小结

  • URI 设计：名词复数（/users），层级清晰

  • 动词与 HTTP 方法映射：GET/POST/PUT/DELETE 对应 查询/新增/更新/删除

  • 状态码：200、201、204、404 等要符合语义

  • 请求/响应格式 ：JSON，使用 @RequestBody / @ResponseBody 自动序列化

遵循以上规范，能让你的 Java Web RESTful 接口更清晰 、易维护，也方便前后端分离项目的协作开发。

相关推荐
知北游天4 分钟前
Linux：多线程---同步&&生产者消费者模型
java·linux·网络
SoniaChen336 分钟前
Rust基础-part2-变量和可变类型
开发语言·后端·rust
Victor35614 分钟前
MySQL(131)如何解决MySQL CPU使用率过高问题？
后端
钢铁男儿14 分钟前
C#接口实现详解：从理论到实践，掌握面向对象编程的核心技巧
java·前端·c#
深栈解码17 分钟前
第二章：Class文件解剖：字节码的二进制密码
java·后端
error_cn19 分钟前
finger命令输出格式解析
后端
Victor35620 分钟前
MySQL(132)如何调整MySQL内存使用？
后端
武子康21 分钟前
大数据-38 Redis 分布式缓存 详细介绍 缓存、读写、旁路、穿透模式
大数据·redis·后端
时序数据说25 分钟前
时序数据库的存储之道：从数据特性看技术要点
大数据·数据库·物联网·开源·时序数据库·iotdb
TeamDev26 分钟前
从 JavaFX WebView 迁移至 JxBrowser
java·后端·webview
热门推荐
01【无标题】02集群聊天服务器---MySQL数据库的建立03Coze扣子平台完整体验和实践（附国内和国际版对比）04Java类变量（静态变量）05KGG转MP3工具|非KGM文件|解密音频06扣子（coze）实战|我用扣子搭建了一个自动分析小红薯笔记内容的AI应用|详细步骤拆解07使用Ruby接入实时行情API教程08Java学习第十五部分——MyBatis09DeepSeek各版本说明与优缺点分析10绿色建筑新态势：楼宇自控助力能效提升，推动成本优化新路径