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 接口更清晰 、易维护，也方便前后端分离项目的协作开发。

相关推荐
一米阳光86612 小时前
软考（中级）软件设计师核心笔记（3）数据库系统——概念、数据库设计
数据库·笔记·职场发展·软考·软件设计师
蓝斯4972 小时前
[原创]《C#高级GDI+实战：从零开发一个流程图》第章：增加贝塞尔曲线，上、下、左、右连接点
java·c#·流程图
前端工作日常2 小时前
我学习到的Java 的 Service 分层：itf 和 impl 到底是什么？
java·后端
奈斯先生Vector2 小时前
告别工具碎片化：基于 Nano Banana 全模态 AI 聚合架构搭建“文本-图像-视频”自动化协同生产线
运维·数据库·人工智能·架构·自动化·aigc·音视频
都叫我大帅哥3 小时前
Spring @Transactional 注解完全指南
java·spring
Java成神之路-3 小时前
G1 垃圾回收器 ：SATB + TAMS核心机制深度解析
java·jvm
前端工作日常3 小时前
我学习到的JIT即时编译与机器码缓存失效
java·后端
带刺的坐椅3 小时前
Solon 的 10 种 HTTP 服务器：改一行依赖，换一个引擎
java·solon·jetty·undertow·mcp-server·htttp
犀利豆4 小时前
Claude Code Tools 研究系列（三）ExitPlanMode
人工智能·后端
星栈4 小时前
oh-my-pi工程级AI编码工使用体验
人工智能·后端·agent
热门推荐
01GitHub 镜像站点02如何新建文件夹？ 电脑新建文件夹的4种方法03国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）042026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片05微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新062026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？07AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路08Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费09历年考研数学一、数学二、数学三真题试卷及答案PDF102026开年大模型最新对比解析及场景落地指南